softClip(x, threshold = DEFAULTSOFTCLIPTHRESHOLD)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SafetyLimiter.js — Phase 2 ParticleVoice audio bridge. "SafetyLimiter.js — soft clip, DC removal, fade." No existing DC blocker/soft clip/limiter precedent exists in this codebase to reuse (checked — 's node is a bare waveshaper, not a limiter/DC blocker), so this is a fresh CPU side implementation. Sits at the very end of the audio bridge, downstream of , as the last line of defense before PCM reaches /the AudioContext — a physics/neural solver misbehaving upstream (an unstable reflection coefficient, a runaway Newton Raphson solve, etc.) should never be able to produce a harsh digital clip transient, a DC offset, or a click at an utterance boundary — that is this module's entire job. Three independent, composable stages, applied per sample in this order: 1. DC removal — the standard DC blocking filter (Julius O. Smith's well known form): . At DC this converges to exactly 0 (the zero cancels any constant component); close to 1 keeps the notch narrow so audible low frequencies are essentially untouched. is derived via this codebase's own established exponential pole convention ( 's pattern) rather than inventing a new formula style: here . 2. Fade — an explicit, persistent linear gain ramp ( / ), so an utterance start/stop or a cancellation ( 's discontinuity) can be given a clean few millisecond ramp instead of an audible click. 3. Soft clip — a saturating soft knee above (default 0.8): transparent (identity) below the threshold, then a C1 continuous (matching slope at the knee, so no audible kink) saturating curve that asymptotically approaches +/ 1 but never reaches or exceeds it — i.e. this NEVER hard clips, by construction. All three stages carry PERSISTENT state across


asymptotically approaches +/ 1 but never reaches or exceeds it — i.e. this NEVER hard clips, by construction. All three stages carry PERSISTENT state across calls (DC filter memory, fade envelope position) — clears all of it in one call, mirroring / 's reset on discontinuity convention, so a caller can reset the whole audio bridge chain in lockstep on cancellation/interruption. Classes Method Signature Summary Clears DC filter memory and any in progress fade (jumps straight to unity gain, no fade active) — matches / 's reset on discontinuity convention. Begins a linear fade in from the CURRENT gain (not necessarily 0 — a fade in interrupting an in progress fade out continues smoothly from wherever the gain currently is) up to unity, over . Begins a linear fade out from the current gain down to 0, over . Functions Pure, stateless: saturating soft knee. Identity below in magnitude; above it, asymptotically approaches but never reaches or exceeds it. C1 continuous at the knee ( matches the identity segment's slope exactly). Constants — SafetyLimiter.js — Phase 2 ParticleVoice audio bridge. "SafetyLimiter.js — soft clip, DC removal, fade." No existing DC blocker/soft clip/limiter precedent exists in this codebase to reuse (checked — 's node is a bare waveshaper, not a limiter/DC blocker), so this is a fresh CPU side implementation. Sits at the very end of the audio bridge, downstream of , as the last line of defense before PCM reaches /the AudioContext — a physics/neural solver misbehaving upstream (an unstable reflection coefficient, a runaway Newton Raphson solve, etc.) should never be able to produce a harsh digital clip transient, a DC offset, or a click at an utterance boundary — that is this module's entire job. Three independent, composable stages, applied per sample


clip transient, a DC offset, or a click at an utterance boundary — that is this module's entire job. Three independent, composable stages, applied per sample in this order: 1. DC removal — the standard DC blocking filter (Julius O. Smith's well known form): . At DC this converges to exactly 0 (the zero cancels any constant component); close to 1 keeps the notch narrow so audible low frequencies are essentially untouched. is derived via this codebase's own established exponential pole convention ( 's pattern) rather than inventing a new formula style: here . 2. Fade — an explicit, persistent linear gain ramp ( / ), so an utterance start/stop or a cancellation ( 's discontinuity) can be given a clean few millis


createSharedPCMRing({ sampleRate, capacitySeconds = DEFAULTRINGCAPACITYSECONDS })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SharedPCMRing.js — Phase 2 ParticleVoice audio bridge. Production generalization of (R4)'s proven / / SharedArrayBuffer PCM ring (single producer/single consumer, control layout consumed by 's allocation free ). Adds the plan's explicit "generation/sequence IDs" requirement, which R4's risk spike did not need (a disposable probe never gets reset mid run): (control[4]): bumped by whenever the producer discards the ring's contents outright (cancellation/ interruption per the plan's Phase 5 "cancellation resets state cleanly", or a device loss GPU recovery restart). The CONSUMER side ( /the resync check in ) compares its own cached generation against this value every call; on mismatch it resyncs to the CURRENT (dropping whatever stale audio was in the ring before the reset) rather than trusting a that may now point at samples from a discarded utterance. (control[5]): incremented once per producer call (a monotonic chunk counter, not a sample counter) — correlates a ring write with the that produced it for diagnostics/telemetry; the consumer does not need to read it for correctness (unlike ). The reader side helper function here ( ) is pure arithmetic over caller supplied typed arrays — no allocation, no closures over per call state — usable from a non worklet consumer (e.g. a test harness) without violating an allocation free constraint. (the AudioWorkletProcessor that actually drains this ring in real time) does NOT import this module — both existing worklet files in this project ( , ) are self contained with no ES imports, so duplicates and the read position arithmetic inline rather than relying on an unverified assumption that module imports behave identically to this project's


so duplicates and the read position arithmetic inline rather than relying on an unverified assumption that module imports behave identically to this project's other worklet loading paths. Both files' docstrings flag this duplication explicitly so the two definitions cannot silently drift apart unnoticed. Functions Returns: A fresh SharedArrayBuffer backed PCM ring, empty, generation 0. Producer side write: copies into the ring starting at the current , advancing it and incrementing . Clamps to available free space ( , the usual ring buffer one slot gap to distinguish full from empty) rather than overflowing past the reader's current position and corrupting not yet read samples — R4's own avoided this by pacing writes to wall clock time so it could never get ahead of the ring's capacity, but a production writer driven by GPU chunk completion (irregular timing) cannot assume that pacing, so this function must be defensive. Returns: The number of samples actually written (may be less Producer side reset: zeroes both indices and bumps so the consumer discards its cached read position on its next call rather than replaying stale audio. Does not zero the PCM data itself (unnecessary — the consumer will resync past it). Pure, allocation free: samples currently available to read (does not mutate anything). Safe to call from . Constants — SharedPCMRing.js — Phase 2 ParticleVoice audio bridge. Production generalization of (R4)'s proven / / SharedArrayBuffer PCM ring (single producer/single consumer, control layout consumed by 's allocation free ). Adds the plan's explicit "generation/sequence IDs" requirement, which R4's risk spike did not need (a disposable probe never gets reset mid run): (control[4]): bumped by whenever the producer discards the ring's contents outright


R4's risk spike did not need (a disposable probe never gets reset mid run): (control[4]): bumped by whenever the producer discards the ring's contents outright (cancellation/ interruption per the plan's Phase 5 "cancellation resets state cleanly", or a device loss GPU recovery restart). The CONSUMER side ( /the resync check in ) compares its own cached generation against this value every call; on mismatch it resyncs to the CURRENT (dropping whatever stale audio was in the ring before the reset) rather than trusting a that may now point at samples from a discarded utterance. (control[5]): incremented once per producer call (a monotonic chunk counter, not a sample counter) — correlates a ring write with the that produc


particlevoice/streaming/VoiceChunker.js
Classes
class VoiceChunker
Constants
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: VoiceChunker.js — Phase 2 ParticleVoice audio bridge. "VoiceChunker.js — legal buckets: first 12/16/24 frames, steady 32/48/64 frames, 16 frame left context, 8 12 frame overlap." A "frame" here is the Activity frame size ( 's measured lead values table: 256 samples @ 32 kHz, 8 ms/frame) — NOT the 100 Hz plan level analysis frame rate, which (Phase 3) reconciles separately. §4 ("Shape buckets") directly reuses these exact bucket definitions so a compiled model's execution plan only needs to support this small fixed set of shapes rather than arbitrary sequence lengths — this module is the single source of truth those buckets come from, not a second independent copy of them: firstChunkFrames: [12, 16, 24] steadyChunkFrames: [32, 48, 64] leftContextFrames: 16 overlapFrames: [8, 12] (R5) already exercised exactly these bucket sizes ( ) as one of its chunk boundary patterns and proved that an ABSOLUTE (not chunk relative) sample/phase counter design makes chunking bit identical to processing a whole signal at once — this module's bookkeeping exists for exactly that reason (a caller can derive an absolute frame index from it), not merely as a diagnostic counter. SCOPE (Phase 2, before any real streaming model exists): this module only decides CHUNK SIZE SCHEDULING (which legal bucket to use next, given how many frames are currently available) — it does not itself run a model, apply left context frames to a real tensor, or overlap add output audio (that's / , already built and verified in Phase 2's DSP kernels; a future model execution layer composes THOSE with the chunk size decisions THIS module makes). Latency/deadline tradeoffs (when to prefer a smaller, faster available bucket over


layer composes THOSE with the chunk size decisions THIS module makes). Latency/deadline tradeoffs (when to prefer a smaller, faster available bucket over waiting for a larger one) are explicitly 's job, not this module's — here always greedily picks the LARGEST legal bucket that currently fits, which is the natural default in the absence of an explicit deadline override. Classes Method Signature Summary Reverts to the initial state (next chunk will again be treated as the FIRST chunk of a fresh utterance) — matches this audio bridge's reset on discontinuity convention ( / / ) for cancellation/interruption. Records that additional frames (from whatever upstream produces them — e.g. a future ) are now available to be chunked. Decides the next legal chunk to dispatch, if enough frames are currently pending — always the LARGEST legal bucket for the current phase (first vs. steady) that fits, consuming that many frames from the pending count. Constants — VoiceChunker.js — Phase 2 ParticleVoice audio bridge. "VoiceChunker.js — legal buckets: first 12/16/24 frames, steady 32/48/64 frames, 16 frame left context, 8 12 frame overlap." A "frame" here is the Activity frame size ( 's measured lead values table: 256 samples @ 32 kHz, 8 ms/frame) — NOT the 100 Hz plan level analysis frame rate, which (Phase 3) reconciles separately. §4 ("Shape buckets") directly reuses these exact bucket definitions so a compiled model's execution plan only needs to support this small fixed set of shapes rather than arbitrary sequence lengths — this module is the single source of truth those buckets come from, not a second independent copy of them: firstChunkFrames: [12, 16, 24] steadyChunkFrames: [32, 48, 64] leftContextFrames: 16 overlapFrames: [8, 12] (R5) already exercised exactly these bucket


them: firstChunkFrames: [12, 16, 24] steadyChunkFrames: [32, 48, 64] leftContextFrames: 16 overlapFrames: [8, 12] (R5) already exercised exactly these bucket sizes ( ) as one of its chunk boundary patterns and proved that an ABSOLUTE (not chunk relative) sample/phase counter design makes chunking bit identical to processing a whole signal at once — this module's bookkeeping exists for exactly that reason (a caller can derive an absolute frame index from it), not merely as a diagnostic counter. SCOPE (Phase 2, before any real streaming model exists): this module only decides CHUNK SIZE SCHEDULING (which legal bucket to use next, given how many frames are currently available) — it does not itself run a model


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: VoiceDeadlineScheduler.js — Phase 2 ParticleVoice audio bridge. "VoiceDeadlineScheduler.js — target =300 ms, warning 200 ms, emergency 100 ms; GPU budget admission." These three thresholds classify how much PLAYBACK RUNWAY remains — how far ahead of the AudioContext's current playback position the produced but not yet played PCM currently extends ( , typically derived from 's via below) — into an urgency tier, and maps that tier onto EXISTING scheduling primitives rather than inventing new ones: 's priority buckets (queue ordering among pending runs). 's bypass ( 's own docstring: "Render critical work bypasses the budget") — this IS the "GPU budget admission" the plan names: in the tier, this module recommends so the broker admits the work immediately regardless of the current frame's compute budget, rather than letting a nearly starved voice ring wait behind unrelated background GPU work. Tier boundaries (this module's own interpretation of the plan's three named thresholds — documented explicitly since the plan states three thresholds but only two transitions are unambiguous from the wording alone): bufferedAheadMs = 300 'target' (healthy, target met) 200 <= bufferedAheadMs < 300 'belowTarget' (below target, not yet urgent) 100 <= bufferedAheadMs < 200 'warning' bufferedAheadMs < 100 'emergency' Classes Method Signature Summary Returns the most recently computed admission decision without recomputing it (e.g. for a caller that only wants to inspect current state between calls). Functions Returns: } Composes with 's — the natural real world source of for a live audio bridge — rather than re deriving ring position arithmetic here. Constants <! HUMAN NOTES Notes & Examples Where


natural real world source of for a live audio bridge — rather than re deriving ring position arithmetic here. Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: VoicePlayback.js — Phase 3 ParticleVoice audio bridge. The last hop of the Phase 3 path: model PCM → resample → → → audible speech. Every piece it composes was built and verified in Phase 2; this module only wires them, which is why it is small. ParticleVoiceModel (32 kHz) → PolyphaseResampler (32 kHz → AudioContext.sampleRate) → SafetyLimiter is already applied upstream by the model → SharedPCMRing (SAB, single producer/single consumer) → ParticleVoiceProcessor (AudioWorkletProcessor) The resample is mandatory, not optional The model's internal DSP rate is 32 kHz (R6's proven ), but an picks its own rate — commonly 48 kHz, sometimes 44.1 kHz. Writing 32 kHz samples into a 48 kHz ring without resampling does not error: it plays back 1.5× too fast and a fifth too high , which sounds like a chipmunk rather than like a bug. handles the exact integer L/M case (32k→48k reduces to L=3, M=2) and is streaming correct across chunk boundaries, so feeding it per utterance or per chunk gives identical output. Backpressure is the producer's problem CLAMPS to available space and returns how much it actually accepted — it never overwrites unread audio. A producer that ignores the return value silently drops the tail of every utterance that does not fit. therefore loops, awaiting drain, until everything has been accepted, and reports the total written so a caller can assert it. What this module deliberately does NOT do It does not own the . Creating and resuming one requires a user gesture in a real page, its lifetime belongs to the application, and a test harness needs to build its own — so the context and worklet node are passed in via . That also keeps this module testable without assuming


and a test harness needs to build its own — so the context and worklet node are passed in via . That also keeps this module testable without assuming any particular page structure. Classes Method Signature Summary The SAB views an 's needs. Record the worklet node driving this ring, so can report whether a consumer is actually running. Samples currently queued for playback. Milliseconds of audio queued ahead of the consumer, plus the tier and the scheduling admission it implies. The returned object is spreadable straight into / options, which is the shape was built to produce. Resample model rate PCM to the output rate. Exposed separately so a caller can inspect the conversion (and so tests can verify the rate change independently of the ring). Resample and enqueue an utterance, awaiting ring space as needed. Discard queued audio and resync the consumer — cancellation/barge in. Resets the resampler in lockstep so stale pre reset filter history cannot bleed into the next utterance, which is exactly why exists. Wait until queued audio has been consumed (or the timeout elapses). Functions Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleVoiceProcessor.js — Phase 2 ParticleVoice audio bridge. Production AudioWorkletProcessor consuming 's ring, generalizing (R4)'s proven allocation free (no , no object/array literals, no , no , no — only typed array indexing and Atomics on pre existing SharedArrayBuffer backed views) with the plan's generation aware resync requirement 's docstring describes. This file is deliberately SELF CONTAINED (no ES module imports), matching this project's two existing worklet files ( , ) — 's constants are duplicated here as rather than imported; the two must be kept in sync by hand (flagged in both files' docstrings) rather than relying on an unverified assumption that module imports behave identically to this project's other worklet loading paths. Control layout (Int32Array, SharedArrayBuffer, 6 x int32) — MUST match 's exactly: [0] writeIndex — next PCM slot the producer will write [1] readIndex — next PCM slot this processor will read [2] underrunCount — incremented whenever fewer than one quantum of samples are available [3] processCallCount — incremented every process() call [4] generation — bumped by the producer's resetSharedPCMRing(); on change, this processor jumps readIndex to the CURRENT writeIndex (dropping stale pre reset audio) instead of continuing from a readIndex that may now point at discarded samples. [5] writeSequence — producer chunk counter; read only from here, not required for correctness, exposed for parity with SharedPCMRing.js's layout only. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from


NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


persistence/CheckpointContracts.js

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Accept legacy {config,parameters} documents and return canonical v1 data. Validate both canonical v1 and the pre envelope checkpoint shape. Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


rig/BrainVisualizer.js

rig/BrainVisualizer.js
Classes
class BrainVisualizer
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Brain Visualizer Visualizes neural network activity on the brain sphere Method Signature Summary Update with neural network activity Compute average neural activity Get current activity level (0 1) Get activity history Render brain activity visualization Render pulsing rings Render activity particles Reset visualizer <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


rig/InjectionSystem.js

rig/InjectionSystem.js
Classes
class InjectionSystem
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Injection System Manages tentacle attachment from brain to ragdoll bones Method Signature Summary Initialize tentacles for each bone Update tentacles Get tentacle data for rendering Get tentacle start position (brain) Get tentacle end position for specific bone Check if tentacle is fully attached Get all attached tentacles <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


rig/ParasiteRig.js

rig/ParasiteRig.js
Classes
class ParasiteRig
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Parasite Rig The "brain sphere" entity that hovers above and controls the ragdoll Method Signature Summary Update parasite rig Inject into ragdoll Eject from ragdoll Set neural activity level (0 1) Get brain sphere position Get current radius (with pulse) Get glow color (varies with neural activity) Get injection progress (0 1) Render brain sphere <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


rig/TentacleRenderer.js

rig/TentacleRenderer.js
Classes
class TentacleRenderer
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Tentacle Renderer Renders tentacles using lightning/electricity effect Method Signature Summary Initialize renderer Render all tentacles Render single tentacle Generate curved path between two points Quadratic bezier curve Add electrical noise to path Get tentacle color based on neural activity Render neural pulse traveling down tentacle <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


scene/DebugVisualizer.js

scene/DebugVisualizer.js
Classes
class DebugVisualizer
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Debug Visualizer Renders debug overlays for training visualization Method Signature Summary Initialize debug visualizer Render debug visualizations Render bone positions as spheres Render velocity vectors Render center of mass Enable/disable debug visualization <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


scene/GroundPlane.js

scene/GroundPlane.js
Classes
class GroundPlane
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Ground Plane Infinite grid ground for training environment Method Signature Summary Initialize ground plane Render ground plane Set grid properties Set grid color <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


scene/SceneRenderer.js

scene/SceneRenderer.js
Classes
class SceneRenderer
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Initialize renderer Begin render pass End render pass Render grid Get render pass Get device <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


scene/TrackingCamera.js

scene/TrackingCamera.js
Classes
class TrackingCamera
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Tracking Camera Smooth camera that follows the ragdoll Method Signature Summary Set camera position Set look at target Set target to track Update camera position Reset camera Get camera position Get look at target Get view matrix Compute look at matrix Vector operations Set camera offset Set smoothing factor <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


scene/TrainingScene.js

scene/TrainingScene.js
Classes
class TrainingScene
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Initialize scene Spawn ragdoll in scene Reset scene for new episode Update scene physics Render scene Get ragdoll Get camera Enable/disable debug visualization <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


studio/core/StudioApp.js
Classes
class StudioApp
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Studio Application Main AGI Studio workspace application Classes Method Signature Summary Initialize studio application Initialize WebGPU Resize canvas to fill viewport Setup button handlers Start training Pause training Reset training Auto load last folder Verify permission for directory handle Show last folder hint in file browser Browse folder Load files from folder Update file list display Scroll files Load model from browser Auto load last model Save last folder handle to IndexedDB (for model loading) Get last folder handle from IndexedDB (for model loading) Clear last folder handle from IndexedDB Save last save folder handle to IndexedDB (for training data) Get last save folder handle from IndexedDB (for training data) Save last loaded model name to IndexedDB Get last loaded model name from IndexedDB Open IndexedDB Toggle metrics overlay visibility Update metrics display Start render loop Load ragdoll model (VRM/GLB) from folder Show model picker overlay Select and load model Save training data to folder Write file to directory Helper to download a file Toggle mesh visibility on/off Toggle particle emission on/off Get controller Get scene <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next


→ action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


class AGIStudioHandleStoreError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Versioned IndexedDB owner for AGI Studio directory handles. Classes Method Signature Summary Method Signature Summary Functions Validate a raw v1 handle or exact v2 envelope without serializing the handle. Constants — Versioned IndexedDB owner for AGI Studio directory handles. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


studio/main.js

studio/main.js
Exports
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


studio/ui/LoadingProgress.js
Classes
class LoadingProgress
Constants
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Loading Progress UI Shows what's loading and progress Method Signature Summary Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/ComputeGraph.js

tensor/ComputeGraph.js
Classes
class ComputeGraph
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Compute Graph Manages operation chaining and execution order for tensor operations Method Signature Summary Add operation node to graph Topological sort to determine execution order Execute the compute graph Clear graph state Reset entire graph Get node by ID Get all nodes Visualize graph structure <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/GradientTape.js

tensor/GradientTape.js
Classes
class GradientTape
class GradientContext
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Gradient Tape Automatic Differentiation Records operations for backward pass computation Method Signature Summary Start recording operations Stop recording operations Record an operation Compute gradients via backpropagation Get gradient for a tensor Clear all recorded operations and gradients Helper: Create tensor of ones with same shape Helper: Add two tensors (for gradient accumulation) Context manager for gradient tape Method Signature Summary <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/Tensor.js

tensor/Tensor.js
Classes
class Tensor
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPU resident float32 tensor with explicit readback and ownership. Classes GPU resident float32 tensor with explicit readback and ownership. Method Signature Summary <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/TensorCache.js

tensor/TensorCache.js
Classes
class TensorCache
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Tensor Cache Memory Management for GPU Tensors Manages tensor buffer lifecycle and memory reuse Method Signature Summary Get or create a buffer for tensor Release a buffer (mark as inactive but keep in cache) Evict oldest unused buffer Clear all cached buffers Get cache statistics Compact cache by removing inactive buffers Generate cache key from tensor properties <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/TensorOps.js

tensor/TensorOps.js
Classes
class TensorOps
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes GPU resident float32 elementwise and reduction operations. Method Signature Summary <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/TensorOpsAdvanced.js

tensor/TensorOpsAdvanced.js
Classes
class TensorOpsAdvanced
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Softmax activation softmax(x) = exp(x max(x)) / sum(exp(x max(x))) Layer Normalization LayerNorm(x) = gamma (x mean) / sqrt(var + eps) + beta Dropout randomly zero out elements during training Exponential function Square root Mean reduction along axis Sum reduction along axis Max reduction along axis Add scalar to tensor Divide tensor by scalar GELU activation GELU(x) = 0.5 x (1 + tanh(sqrt(2/π) (x + 0.044715 x^3))) Clip values to range [min, max] <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


createActivationShader(activationType = 'relu', workgroupSize = 256)

createActivationDerivativeShader(activationType = 'relu', workgroupSize = 256)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Activation Function Compute Shaders ReLU, Tanh, Sigmoid, and their derivatives <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


tensor/shaders/matmul.js
Functions
createMatmulShader(workgroupSize = 8)
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Matrix Multiplication Compute Shader C = A B where A is [M x K] and B is [K x N] <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Reduction Operations Compute Shaders Sum, Max, Min reductions along axes <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


ui/MetricsDisplay.js

ui/MetricsDisplay.js
Classes
class MetricsDisplay
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Metrics Display Real time training statistics display Method Signature Summary Initialize display Create metrics elements Create metric row Update metrics Destroy display <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


ui/TrainingUI.js

ui/TrainingUI.js
Classes
class TrainingUI
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Training UI Main control panel for training interface Method Signature Summary Initialize UI Create control buttons Create button element Toggle training Start training loop Reset training Save model Load model Update metrics display Destroy UI <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


AGI Training Guide

AGI Training Guide
Curriculum stages
The training loop
Tuning tips
Troubleshooting
See also

How to train the parasite rig from standing to full locomotion across seven curriculum stages, plus fixes for common problems. AGI Training Guide How to train the parasite rig from standing to full locomotion, and how to fix common problems. Condensed from and . Curriculum stages Training uses curriculum learning with 7 progressive stages. The advances automatically as criteria are met. Stage Approx. time Goal 1 Standing 1–2 h Stand upright for 10 s 2 Balance Recovery 2–3 h Recover from random perturbations 3 Walking Forward 4–6 h Walk at 1 m/s sustained 4 Directional Control 6–8 h Walk toward target positions 5 Obstacle Navigation 8–12 h Navigate around obstacles 6 Dynamic Terrain 12–16 h Walk on slopes up to 30° 7 Full Locomotion 16–24 h Run, jump, turn, crouch Total: 24–72 h for complete mastery. The training loop Each step: 1. reads the ragdoll into a 12D observation. 2. The policy network outputs a 17D action. 3. applies the action as bone impulses. 4. PBD physics advances; scores the result. 5. Experience is buffered (with GAE); updates the policy. Tuning tips Reward shaping — adjust weights in (or the Studio Reward editor). Increasing the uprightness weight helps early stages. Buffer/batch size — larger buffers stabilize updates but use more memory. Curriculum pacing — if a stage stalls, verify its advancement criteria before moving on. Troubleshooting Ragdoll not learning? Confirm WebGPU is available in the browser. Verify physics is running at 60 FPS. Increase the uprightness reward weight. Performance issues? Close other browser tabs. Reduce buffer size (default 2048). Disable debug visualizations. Check GPU utilization. Browser crashes? Reduce buffer size. Clear the tensor cache. Save the model frequently. See also AGI Getting Started. AGI Architecture. AGI


AGI Training Guide

GPU utilization. Browser crashes? Reduce buffer size. Clear the tensor cache. Save the model frequently. See also AGI Getting Started. AGI Architecture. AGI API Reference — , , .


API Reference

API Reference
Public entry points
Per-subsystem reference
Machine-readable catalog

Entry point to the stack's API — public entry points, the auto-generated per-symbol reference for each subsystem, and the curated public API maps. API Reference The stack's API is documented in two complementary forms: Curated public API maps — hand authored tables of the common exports for each subsystem, on the Capabilities page. Auto generated per symbol reference — generated from source by and browsable per subsystem (use the sidebar API Reference groups, or the links below). Public entry points Surface Import Notes Engine (source) All engine exports — math, ECS, render, sim, GPU, gameplay, saves. Engine (compiled) / After loading a built bundle. Plauna UI framework — app, widgets, services. AGI Core Training, observations, rewards, brains, motion. Editor Editor app orchestration + . See Engine Stack Usage for source mode vs bundle mode loading patterns. Per subsystem reference Each subsystem ships a generated, per file symbol reference (browse via the sidebar API Reference group under each section): Engine — overview, reference under . Editor — overview, reference under . Plauna — overview, reference under . AGI — overview, reference under . WebGPU OS — overview, reference under . The reference is hybrid : signatures are regenerated from source on every run, while hand authored notes below the marker are preserved. See the API Reference Standard. Machine readable catalog Agents and tools should start with . It combines all subsystem indexes and records the exact source path, source server import specifier, source SHA 256, detected exports, signatures, and summaries when the source JSDoc provides them. Its object quantifies missing module and export prose instead of filling gaps with invented descriptions. The per subsystem files use the same record shape and remain


API Reference

quantifies missing module and export prose instead of filling gaps with invented descriptions. The per subsystem files use the same record shape and remain compatible with the documentation viewer. The catalog's contract distinguishes source mode from compiled mode: absolute module imports assume is serving the repository root, while the compact production site may expose only generated bundles. For incremental indexing, use . Each line contains one module or detected export and repeats the source path, import specifier, and source hash required to verify its context. Use when the task needs bounded prose from guides and generated references without loading the full search index. Both feeds have byte identical copies at the site root and in . The catalog describes ES modules, not an HTTP API. Do not infer REST endpoints, request schemas, or behavior that is absent from the linked source. Regenerate the catalog with followed by .


APPFORGE IMPLEMENTATION PLAN

14. Phase 11: Visual Builder And Starter Packs

<! SPDX FileCopyrightText: 2026 Jake Wehmeier (BTSpaniel) <https://github.com/BTSpaniel SPDX License Identifier: LicenseRef ParticleRealms Alpha APPFORGE IMPLEMENTATION PLAN This document operationalizes . It is the execution checklist for building AppForge into the current WebGPU OS without replacing the existing kernel, app registry, package manager, permissions, shell, or Plauna panel stack. 1. Execution Rules Preserve current WebGPU OS boot behavior at every phase. Keep as the app manifest registry. Add AppForge as a part registry and assembly layer. Keep the existing permission engine canonical. Keep current package trust and sandbox checks. Do not add Node.js, npm, or package lock files. Use browser ES modules and Python tooling only. Do not edit vendored, generated, binary, or third party paths. Add SPDX headers to new source files. Every phase must be independently testable before moving forward. 2. Phase Dependency Order Order Phase Depends On Output 0 Baseline Guard none Known good boot and command baseline 1 Registry Foundation baseline AppForge part registry 2 Tags And Scoring registry Deterministic semantic query engine 3 Service Container registry facade 4 Context Graph services Provides/consumes state graph 5 Command Objects registry, services, context Registered command contract 6 Layout Zones registry, context AppForge workspace zones 7 Blueprints And AppFactory registry, tags, layout Deterministic workspace assembly 8 Terminal Service services, context, commands Persistent terminal sessions 9 Package Exports registry, permissions AppForge package part exports 10 Timeline And Lenses context, layout, commands Replayable workspace history and alternate views 11 Visual Builder And Packs all prior User facing composition tools Do not skip phases. Later


APPFORGE IMPLEMENTATION PLAN

layout, commands Replayable workspace history and alternate views 11 Visual Builder And Packs all prior User facing composition tools Do not skip phases. Later phases may stub data fixtures only in tests, never in runtime code. 2.1 Current Implementation Status Phase Status Evidence 1 Registry Foundation Implemented , , , 2 Tags And Scoring Implemented , 3 Service Container Implemented , , 4 Context Graph Implemented , , 5 Command Objects Implemented Command helpers, , pipelines, Notepad and Files batches, command tooling visibility 6 Layout Zones Implemented , , , , persisted snapshots 7 Blueprints And AppFactory Implemented , , , app manifest panel import 8 Terminal Service Implemented , , , terminal syscall bridge 9 Package Exports Implemented , package manager validation/registration/remove/rollback hooks, manifest schema/docs 10 Timeline And Lenses Implemented , , , , 11 Visual Builder And Packs Implemented , , , , 2.2 App Owned Migration Strategy Keep current apps in until their AppForge equivalents are proven and the old app surfaces can be removed manually. For each migration slice: 1. Keep the app manifest and existing launch entry working. 2. Add for that app's panels, tools, commands, services, workflows, and profiles. 3. Keep any old top level AppForge files as re export shims until manual cleanup removes them. 4. Promote shared code into only after at least two apps need the same primitive. 5. Verify the app still launches through Desktop and the AppForge smoke runner still passes. Migration order remains Files, Notepad, Terminal, Paint, then admin/system apps. Files and Notepad are the first app owned migration slices. 3. Phase 0: Baseline Guard Purpose: prove the current OS still works before adding AppForge code. Deliverables Record current app manifest


APPFORGE IMPLEMENTATION PLAN

migration slices. 3. Phase 0: Baseline Guard Purpose: prove the current OS still works before adding AppForge code. Deliverables Record current app manifest count from . Record current OS boot entry points: Record current launch path: Add no source changes in this phase unless a baseline test already exists and needs a non behavioral documentation update. Verification Manual browser checks: Desktop boots at . Files opens. Terminal opens. Notepad opens. Paint opens. Package manager opens. Permission manager opens. Exit gate: current behavior is understood and reproducible. 4. Phase 1: Registry Foundation Purpose: add the AppForge part registry without changing current app launch. New Folders And Files Required AP


APPFORGE SUPER PLAN

Phase 8: Timeline, Lenses, Builder, Packs

<! SPDX FileCopyrightText: 2026 Jake Wehmeier (BTSpaniel) <https://github.com/BTSpaniel SPDX License Identifier: LicenseRef ParticleRealms Alpha APPFORGE SUPER PLAN 1. Executive Decision AppForge OS should be implemented as a deterministic refactor layer over the existing WebGPU OS stack, not as a replacement. The repository already has the hard operating system pieces that AppForge needs: A kernel bootstrap and service owner. An app discovery and launch path. A package manager with trust, verification, rollback, and built in sync. A permission system with default deny syscall guards. A desktop shell with window hosting and app lifecycle. Plauna panels, workspaces, DOM/GPU panel primitives, and layout primitives. Many reusable apps and domain modules: Files, Terminal, Notepad, Paint, package managers, permission managers, log/service monitors, GPU demos, editor tools, and AGI tools. The missing AppForge layer is a unified semantic runtime: A registry for all app building parts. Namespaced tags and deterministic scoring. A context graph for provides/consumes wiring. A service container facade. An app factory that assembles blueprints into running workspaces. A zone layout system with docking, tabs, layout diffs, and restoration. First class registered commands, tools, panels, services, workflows, themes, packages, and blueprints. The guiding rule is simple: reuse the current OS primitives wherever they are already correct, then refactor them into AppForge contracts. 2. Scan Basis Repository root: Git snapshot inspected: Worktree state during scan: dirty; existing user changes must be preserved. Attached briefing reviewed: AppForge tag semantic deterministic assembly plan. Session memory found: Targeted scan: 35 core/app/source/doc files, 38 app manifests, and broad repo


APPFORGE SUPER PLAN

AppForge tag semantic deterministic assembly plan. Session memory found: Targeted scan: 35 core/app/source/doc files, 38 app manifests, and broad repo searches across , , , and . No runtime LLM planner should be added. AppForge selection must remain deterministic, inspectable, and reproducible. 3. Current Codebase Map 3.1 OS Kernel And Runtime Central kernel bootstrap and service owner. Owns GPU initialization, scheduler, event bus, process table, permissions, virtual filesystem, surfaces, VRAM tracking, drivers, schema registry, package manager, trust store, theme engine, session store, tool driver, syscalls, and built in commands. This should become the backing runtime for AppForge services. Discovers app manifests from . Validates app manifests and supports packaged app registration. Current scope is app level only. AppForge needs a broader registry for every reusable part. Registers, aliases, dispatches, lists, and logs commands. Already supports dot namespaced command IDs and history. Needs AppForge command object metadata: tags, inputs, outputs, permissions, undo behavior, risk, and pipeline compatibility. Provides capability checks, manifest registration, grants, revokes, requests, audit logging, and persistence. Should remain canonical. AppForge permission names should map into this existing model. Handles install, remove, update, verify, repair, rollback, built in sync, trust tiers, execution policy, provenance, integrity, and package app registration. Should be extended to export/import AppForge parts. Provides iframe based isolation for untrusted packages. Should become the sandbox foundation for AppForge package parts. Applies, previews, imports, exports, and emits theme changes. Should be exposed as a registered theme service. Allocates WebGPU surfaces to


APPFORGE SUPER PLAN

package parts. Applies, previews, imports, exports, and emits theme changes. Should be exposed as a registered theme service. Allocates WebGPU surfaces to panels and tracks VRAM quota. Should back registered GPU panels. Tracks running apps, panels, process like metadata, and resource estimates. Should back AppForge process/session visibility. Provides command palette search over apps, commands, and providers. Should be reused for registry search and discovery. Provides OS native tool registration and execution for tool callers. Should inform AppForge tool contract design. 3.2 Shell And Plauna Hosts app windows, launches apps, gates quarantine, applies manifest patches, creates panels, registers pro


AppForge Contracts

AppForge Contracts
Part Definition
Tags And Scoring
Registry
Service Container
Context Graph
Command Objects
Layout
Blueprints And AppFactory
Terminal Service
Package Exports
Timeline
Lenses
Starter Packs
Workspace Builder
AppForge Syscalls
Security Invariants

Public contracts for the AppForge registry, tags, services, context graph, command objects, layouts, blueprints, package exports, timeline, lenses, builder, and starter packs. AppForge Contracts AppForge is the deterministic assembly layer inside WebGPU OS. It does not replace the kernel, shell, package manager, permission model, or current apps. It registers reusable parts, scores them with tags, assembles blueprints into workspace layouts, records workspace history, and exposes builder tooling. Primary source files: Part Definition Every registered part is a plain object. The shared definition validator accepts these part types: Required fields: Field Meaning Dot or dash namespaced ID that starts with a lowercase letter. One of the supported AppForge part types. Human readable title. Semver like string. Defaults to when omitted. Common optional fields: Field Meaning Human readable summary. Namespaced semantic tags. Capabilities or outputs this part offers. Context, service, or capability dependencies. OS permissions this part needs. / Structured command or tool IO metadata. Numeric scoring tiebreaker. Plain object describing lifecycle hooks or module entry data. Provenance metadata such as app manifest, package export, or starter pack. Part specific metadata. Definitions are cloned on public reads. Callers should treat returned values as snapshots, not live registry objects. Tags And Scoring Tags use form. Supported namespaces are: Examples: uses deterministic scoring from tags, type, zone affinity, permissions, available context, co occurrence data, and risk filters. It returns scored candidates with explanation strings. Registry is the source of truth for reusable AppForge parts. Public API: Rules: Duplicate IDs are rejected unless the caller unregisters the prior


AppForge Contracts

strings. Registry is the source of truth for reusable AppForge parts. Public API: Rules: Duplicate IDs are rejected unless the caller unregisters the prior part first. and return clones. returns scored results and never mutates the registry. Existing app manifests remain in ; AppForge imports them as panel candidates with . Service Container exposes existing kernel owned services through stable IDs. Public API: Kernel provided AppForge services include: ID Backing owner Context Graph stores current OS context as directed nodes and edges. It is used for active file, selection, project, shell cwd, process, theme, panel, registry, layout, terminal, builder, and pack state. Public API: Invalidations are microtask batched. Tests that assert subscriber behavior should wait for a tick before reading callback results. Command Objects AppForge command objects promote local app actions into typed command contracts. Required shape: validates the command object, wraps it in the existing , and exposes public metadata without the handler function. Object pipelines intentionally require exact AppForge command object IDs. Layout owns serializable AppForge workspace state. It does not replace the Desktop window manager. Existing floating windows still launch through the current shell path. Required zones: Public API: is the DOM adapter that exposes AppForge zones while keeping the normal Desktop launch behavior intact. Blueprints And AppFactory A blueprint is a part that declares workspace slots. Slots can require exact parts, prefer optional parts, or select parts by wanted tags. Slot shape: resolves a blueprint and returns selections, permission summary, proposed workspace state, and layout diff without mutating live state. applies a valid preview to the live layout engine. Terminal


AppForge Contracts

permission summary, proposed workspace state, and layout diff without mutating live state. applies a valid preview to the live layout engine. Terminal Service backs the Terminal panel with persistent sessions. Sessions store session ID, cwd, pid, command, stdout/stderr records, exit state, history, and timestamps. The Terminal app attaches to the service and runs commands through the guarded syscall object attached to the session, not through raw kernel syscalls. Exposed syscall namespace: . Package Exports manifests may include AppForge exports: Rules: Export groups imply the part type when is omitted. Exported part permissions must be declared in package or . Export IDs cannot replace parts owned b


Architecture Overview

Tier 2 migration contract (stable surfaces)

The big picture — how the engine, editor, Plauna, AGI, and the WebGPU OS compose into one layered system. Architecture Overview This page is the big picture: how the engine, editor, Plauna, AGI, and the WebGPU OS compose into one system. Read it before diving into any single subsystem. Layered composition The stack is built in reusable layers. Lower layers know nothing about higher ones; higher layers consume lower ones as libraries. The composition rule is composition glue only . It consumes , , , and as libraries and must not fork them. If something needs fixing, it is fixed upstream in the owning subsystem, not patched inside the OS layer. (Source: §4.) How the OS maps onto the subsystems The WebGPU OS does not reimplement runtime services — it reuses the engine and Plauna: OS concern Provided by Kernel / scheduler / GPU device Engine , , , , plus glue Compositor / window manager / shell Plauna , , , + Filesystem / project / packages Engine , + + IPC / events / "syscalls" Engine , Plauna + Intelligence layer AGI , , (Source: §3, "Asset inventory → OS subsystems".) Tier framing The OS is delivered in tiers; Tier 1 (browser resident) is the current implementation target: Tier What it is Status 1 — Browser resident OS Desktop like environment in a browser tab, built from the existing stack Implementation target 2 — WASM + native host Rust + Wasmtime/WASI host wrapping Dawn/wgpu, exposing capability mediated APIs Documented migration path 3 — Native microkernel Kernel + user space services around WebGPU/WGSL Research only A core decision (adopted from the research): do not put WebGPU "in the kernel." In every tier the GPU service is a user space process owning validation, shader compilation, and pipeline creation; the kernel handles scheduling, memory protection, and


Architecture Overview

the GPU service is a user space process owning validation, shader compilation, and pipeline creation; the kernel handles scheduling, memory protection, and device mediation only. This mirrors the browser GPU process model. Tier 2 migration contract (stable surfaces) These must survive a future Tier 2 swap, so treat them as the stable contract: App manifest — same JSON boots a Plauna panel today and a WASI sandbox tomorrow. Syscall surface ( ) — JS shape today, WASI capability table tomorrow. WGSL shaders — already portable. Capability gates — the rule graph is the Tier 1 stand in for the Tier 2 capability broker. Cross cutting concerns These topics span every subsystem and have dedicated pages: Boot Sequence — how the OS comes up. GPU Device Sharing — one device, many apps. Security & Trust Model — capabilities, trust rings, package verification. Data Flow — how state moves (ECS, save, collab). History & Evolution — why the layering looks the way it does.


Boot Sequence

Boot Sequence
Entry points
The boot phases
Kernel init order
Boot options
Failure handling
See also

How the WebGPU OS comes up — from the HTML page to a mounted desktop — via boot.js and the bootWebGpuOS() entry point. Boot Sequence How the WebGPU OS comes up, from the HTML page to a mounted desktop. This reflects and the function in . Entry points — a side effect free barrel exporting . Importing it does not auto boot, which makes it the clean entry point for the static bundler ( ). — a thin wrapper that calls on for plain ES module/dev usage. The boot phases runs these phases, updating the on screen boot status as it goes: 1. Initializing kernel — brings up kernel services against the WebGPU canvas. 2. Discovering apps — finds apps from (errors are logged as warnings, not fatal). Discovered built ins are synced into the package registry via (idempotent). 3. Loading mods — loads runtime mods from . 4. Mounting desktop shell — then . Missing shell root elements throw. 5. Optional security self tests — when is true or the URL contains : , , and run and log findings. is also exposed for on demand use. 6. Ready — the boot loader is hidden and (frozen). resolves to . Kernel init order Inside , the package/trust subsystem initializes in this order (Source: ): Because installed packages are re registered on init, installed apps survive a reload. Boot options accepts selector overrides (defaults shown): Option Default Failure handling If any phase throws, the boot status is set to , the error is logged via , and the promise rejects. App/mod discovery errors are non fatal and surface as console warnings. See also GPU Device Sharing — what the kernel sets up on the canvas. Security & Trust Model — what the boot time audits check. WebGPU OS API Reference — , , .


Data Flow

Data Flow
State lives in ECS
Persistence and the filesystem
Inter-app messaging (IPC)
Optional multi-user sync
Authoritative UI state
End-to-end example
See also

How state moves through the stack — ECS state, persistence, the virtual filesystem, inter-app messaging, and optional multi-user sync. Data Flow How state moves through the stack: ECS state, persistence, the virtual filesystem, inter app messaging, and optional multi user sync. This page orients you before the per subsystem references. State lives in ECS The engine is ECS driven : runtime state lives in components, owned by a world, and mutated by systems. Plauna defines its own UI components in a dedicated UI world (e.g. , , , , , , ). See: Engine ECS: ( , , components, systems, world). Plauna UI ECS: and + . Persistence and the filesystem The OS exposes a virtual filesystem and storage layer over browser primitives: Layer Component Backed by Virtual FS (syscall facing) , OPFS / IndexedDB Origin private files OPFS Key value / structured IndexedDB External mounts user picked dirs Caching Cache API Per app isolation scoped paths Orchestration — Engine side asset/resource loading and save go through , , and . Inter app messaging (IPC) Apps communicate through kernel mediated IPC syscalls ( / ), gated by capabilities. Lower level event buses exist in the engine ( ) and Plauna ( ), and the kernel adds buses such as , , and . Optional multi user sync For collaborative or multi user scenarios, the engine's collab mesh ( ) provides identity, integrity, presence, signaling, host migration, and scene/transform sync. State that needs to be shared is replicated over this mesh; identity and integrity are enforced by , , and . Authoritative UI state Particle State Channels connect Plauna views to ECS, CSE, or another authority. UI events become typed intents. Confirmed snapshots or merge patches return as projections. SSE is the standard downstream browser transport, paired with


Data Flow

UI events become typed intents. Confirmed snapshots or merge patches return as projections. SSE is the standard downstream browser transport, paired with HTTP for upstream intents. Particle signaling and BroadcastChannel remain available for peer oriented routes. (Source: , ) End to end example A note created in the Notepad app: 1. The app calls (a guarded syscall) → → . 2. The capability guard checks against the app's grants. 3. On reload, re registers the app and its sandboxed storage path persists, so the note is still there. See also GPU Device Sharing — GPU resource flow. Security & Trust Model — how the syscalls above are gated. Particle State Channels — authoritative intent and projection flow. Engine, Plauna, and WebGPU OS API References .


GPU Device Sharing

GPU Device Sharing
Why one device
Key components
The model
device-lost fan-out
What an app should assume
See also

The single shared WebGPU device model — one device brokered by the kernel with per-app budgets and barriers. GPU Device Sharing The whole OS runs against a single WebGPU device shared by the shell and every app. This page explains the model and where it lives. It expands the notes in . Why one device WebGPU devices are expensive and the browser already runs GPU work in a dedicated process. The OS follows the same principle: one device, brokered by the kernel, with per app budgets and barriers — rather than each app creating its own device. Design rule: the GPU service is user space, not "in the kernel." The kernel mediates the device (scheduling, memory protection, fan out); validation, shader compilation, and pipeline creation happen above it. See Architecture Overview. Key components Concern Component Device acquisition + sharing Adapter/device info VRAM accounting Virtual GPU abstraction (VGPU) Multi queue submission Resource barriers engine VGPU resource barrier enforcement Device recovery Canvas bootstrap The model Single device — acquired once by the broker and handed to the VGPU abstraction. Frame loop ownership — the kernel owns the loop and allocates per app tick budgets ; apps do not each spin their own loop. Multi queue + barriers — concurrent GPU work is ordered through and resource barrier enforcement so apps don't corrupt each other's state. VRAM tracking — accounts for allocations so the OS can show usage (e.g. the GPU Manager app) and enforce limits. device lost fan out When the browser raises WebGPU's , the broker fans the event out to every app and the shell so each can release and rebuild GPU resources. Recovery logic lives in . Apps should treat their GPU resources as reconstructable and listen for the fan out rather than assuming the device is


GPU Device Sharing

GPU resources. Recovery logic lives in . Apps should treat their GPU resources as reconstructable and listen for the fan out rather than assuming the device is permanent. What an app should assume It shares the device; it must respect its tick budget and not block the frame loop. GPU resources can be lost at any time; handle the fan out. Heavy compute belongs in WebGPU compute passes, scheduled through the VGPU layer. See also Boot Sequence — when the device is acquired. Engine API Reference — . WebGPU OS API Reference — , , .


History & Evolution

Why documentation stopped — and why it's being redone

How the stack grew (engine to editor to Plauna to AGI to WebGPU OS) and why the subsystem boundaries sit where they do. History & Evolution This is the canonical story of how the stack grew. Understanding the order in which the layers appeared explains why the boundaries sit where they do — and why is glue rather than a rewrite. The order of creation 1. Engine The foundation. A pure browser, GPU first runtime: a shared WebGPU device, frame graph, ECS, rendering pipeline, simulation systems, networking, and audio. Everything else consumes it. Its development principles — no Node.js, GPU first, ECS driven, modular — propagate to every later layer. (Source: .) 2. Editor The first major application built on the engine: a scene and asset authoring IDE ( ). It established the panel/workbench patterns and the project/filesystem abstraction ( ) that Plauna and the OS later generalize. 3. Plauna A UI runtime extracted to serve UI needs the editor exposed. Plauna adds hybrid DOM/GPU rendering , DOM free text measurement, a GPU surface graph , and a dockable workbench (workspaces, panels, tabs). It integrates with the engine using the same bootstrap and VGPU patterns as the editor, and is explicitly zero dependency, no build step . (Source: .) 4. AGI An intelligence layer: a "Doc Octavius" style parasite rig that injects into a humanoid ragdoll and learns to control it via reinforcement learning (PPO). It ships its own WebGPU tensor library ( ), neural networks ( ), a curriculum system, and AGI Studio — a full training workspace application. (Source: .) 5. WebGPU OS The unifying layer. Rather than rebuild runtime services, it composes the engine, Plauna, AGI, and editor into a desktop like, GPU first OS in a browser tab : a kernel (syscalls, scheduling, GPU mediation,


History & Evolution

services, it composes the engine, Plauna, AGI, and editor into a desktop like, GPU first OS in a browser tab : a kernel (syscalls, scheduling, GPU mediation, trust/permissions), a shell (desktop, taskbar, windows), a signed package system, and a runtime app catalog. (Source: .) Why documentation stopped — and why it's being redone Documentation was written per layer as each was built, then drifted as the OS absorbed everything. The result was scattered across , , , and many per component files, with overlapping and stale content. This set restructures all of it into one audience segmented source of truth, leaving the original files in place as read only references. See the Contribution Workflow for how to keep it from drifting again. Naming note Older docs and source headers may refer to the project as "Particle Engine" / "Particle Engine v2" and to game content as "Particle Realms Online." These are the historical names of the engine and a game built on it; the current umbrella is the WebGPU OS stack described here.


Schema Evolution and Expand-Contract

Schema Evolution and Expand-Contract
Non-negotiable invariants
One policy, five mechanisms
Repository coverage
Relational expand-contract
Document and browser-storage evolution
Protocol evolution
Retirement gates
Deployment and rollback runbook
Adding a contract
Audit baseline

Repository-wide rules for evolving SQLite, JSON, browser storage, binary saves, protocols, and signed packages without destructive upgrades. Schema Evolution and Expand Contract Particle Realms treats every durable or independently deployed data boundary as a versioned contract. This includes SQLite tables, JSON files, browser storage, OPFS trees, binary saves, network messages, checkpoints, and signed packages. The expand contract pattern applies directly to the active SQLite service and to any storage layout shared by old and new application instances. The same safety goal applies elsewhere, but the mechanism changes with the medium: JSON uses explicit readers and pure upcasters, live protocols negotiate overlapping versions, signed artifacts use immutable generations, and disposable caches are namespaced and invalidated. The machine readable source of truth is . Its meta schema is , and checks the catalog, every first party JSON document, every formal JSON Schema, and every direct production use of browser persistence APIs. A browser storage call must be owned by a declared contract or carry one exact, reviewed classification such as primitive preference, ephemeral session state, disposable cache, storage infrastructure, or compatibility shim. Structured durable state cannot be hidden behind an exclusion. Expand contract is not a blanket rewrite rule. It is the correct mechanism for relational columns, shared browser keys, and rolling network deployments. Immutable hashed events, signed packages, procedural voxel snapshots, and disposable caches need different strategies because dual writing them would weaken integrity or manufacture a lossy conversion. Non negotiable invariants 1. Every authoritative value has a format discriminator and an explicit version. 2.


Schema Evolution and Expand-Contract

integrity or manufacture a lossy conversion. Non negotiable invariants 1. Every authoritative value has a format discriminator and an explicit version. 2. Writers emit one declared current version. Readers may accept an ordered compatibility window. 3. Reading never silently relabels old data. A pure migration must produce the new shape and pass the new validator. 4. Unknown and future durable versions fail closed without overwriting the source. 5. Durable commits are transactional, copy on write, manifest last, or generation swapped. A partially written value is never promoted as current. 6. Rollback data remains readable until the catalog's retirement gates pass. 7. Cache records are never treated as authoritative. They may be invalidated and rebuilt. 8. Signed packages are immutable. A schema change creates a new signed generation; it never mutates an installed generation in place. One policy, five mechanisms Contract class Evolution strategy Commit boundary Unknown version SQLite authoritative data Expand, backfill, switch reads, contract One database transaction per migration or backfill batch Reject startup/readiness JSON, IndexedDB, OPFS, binary saves Read old, pure upcast in memory, validate, copy on write Verified backup, manifest last, or generation swap Reject or quarantine WebSocket, SSE, HTTP envelopes Advertise capabilities and negotiate current plus previous Acknowledged message or request transaction Protocol error; never reinterpret Signed package/export Side by side immutable generation Verify hashes/signature, then publish manifest Reject UI and derived cache Namespace by version and rebuild Replace disposable entry Invalidate Repository coverage The catalog currently records 125 independently evolving contract families. The implementation wave covers


Schema Evolution and Expand-Contract

disposable entry Invalidate Repository coverage The catalog currently records 125 independently evolving contract families. The implementation wave covers the following high risk boundaries: The Python service uses ordered, checksummed SQLite migrations and transactional cursor based backfills. Physical drift checks include columns, defaults, nullability, checks, unique keys, indexes, and foreign keys. (Source: , .) Engine and Life saves use exact format readers. World WAL recovery validates the entire sequence, CRCs, entry types, coordinates, lengths, and LSN order before replay. Flush and checkpoint share one operation queue, and a failed region save cannot truncate the log. ANI motion NPZ files use bou


Security & Trust Model

Security & Trust Model
Two enforcement layers
Capability enforcement
Permission vocabulary
Trust verdicts → capability defaults
The verification choke point
Consent & trust-on-first-use (TOFU)
Install-time execution policy
Boot-time self-audit
Audit logs
See also

How the OS contains code via capability-gated apps and mods plus package trust verdicts that combine to limit untrusted code. Security & Trust Model How the OS contains code it runs. Apps and mods are capability gated and packages carry a trust verdict ; the two combine so that untrusted code is contained even if it declares broad permissions. This page consolidates and . Two enforcement layers 1. Capabilities — a package may only call a syscall if it declared the matching permission and the user/policy granted it. 2. Trust verdict — the result of verifying the package's integrity, signature, provenance, and scan risk. The verdict can override grants (e.g. block network egress regardless of declared permissions). Capability enforcement A package declares in its manifest. At launch, wraps the panel's syscalls with . Each guarded method calls before running; missing/denied capabilities throw or prompt per policy. resolves decisions; persists grants. Permission vocabulary Capabilities are dotted strings. Declare only what you use — the consent prompt lists requested permissions. Namespace Examples Gated action , , , virtual filesystem , , , OPFS / cache / mounts , inter app messaging raw GPU device model inference , network egress , shell UI , , — package/patch management Trust verdicts → capability defaults Installed packages carry a verdict ( ): Verdict Network egress Notes (root chained) as granted full capability set available to grant (TOFU) as granted accepted by the user on first install (self signed, unpinned) no auto grant restricted; must be explicitly granted (integrity fail / high scan risk / key change) hard blocked throws on any regardless of grants This is default deny egress : it blunts credential exfiltration and worm C2 even if a malicious package


Security & Trust Model

change) hard blocked throws on any regardless of grants This is default deny egress : it blunts credential exfiltration and worm C2 even if a malicious package declares . The verification choke point All installs route through (Source: ): Ring 0 roots live in ; handles roots + publisher pinning. Provenance is checked by and . Scanning is performed by . Consent & trust on first use (TOFU) First install of a self signed package prompts with: publisher fingerprint , trust verdict , scan risk , and requested permissions . Accepting pins the publisher fingerprint ( ). Anti takeover: if the same publisher later presents a different fingerprint, the install is flagged ( ) and requires explicit re consent — defending against style account takeover. The shell can register a rich modal via ; otherwise a fallback is used. Install time execution policy Packages run no install scripts . Code executes only when the app is opened (its ), inside the per app sandbox ( ) with guarded syscalls. There is no / style hook — the top real world infection vector is removed by design. Boot time self audit Boot with (or ) to run: — reports guarded / open / unguarded syscalls. — detects capability map drift (unclassified or stale entries). — full posture report; also exposed as . Audit logs Package lifecycle → ; updates → . Per package trust metadata ( , , , ) is stored in the package registry. See also WebGPU OS API Reference — , , , , . App manifest fields — WebGPU OS Architecture.


Particle State Channels

Particle State Channels
Standard flow
Place state by owner
Define a channel
Connect Plauna
Connect ECS replication
Connect CSE app state
Embedded network runtime
Run the proof
See also

The authoritative intent and projection path that connects Plauna, ECS, CSE, and Particle Network transports. Particle State Channels Particle State Channels define where shared state lives and how views receive it. This guide is for app, game, and UI authors who need one authoritative state path across Plauna, ECS, WebGPU OS state, and Particle Network. Standard flow A State Channel accepts typed intents and emits revisioned projections plus receipts. An intent asks an authority to perform an action. A projection contains confirmed state for a consumer to render. Plauna never treats an input event as shared truth. (Source: , ) The standard browser client transport uses Server Sent Events (SSE) downstream and HTTP upstream. reconnects the projection stream. Event IDs and synthesized snapshots recover missed revisions. The local development server and V3 Masterserver enable this route by default. The production route requires a short lived signed lease bound to a proven V3 key, route, channel, and role. Set on the Masterserver only when an operator intentionally disables this V3 capability. (Source: , , ) keeps that default while removing per app setup. A server authority resolves to SSE and can acquire its production lease from . A same origin authority resolves to . A peer authority opens the existing Particle WebRTC route and resolves to mesh. An in process authority stays local. (Source: , , ) Place state by owner State Owner Example Delivery Local presentation Plauna open menu, hover, draft input in process Authoritative simulation ECS world transform, particle emitter, combat state mesh or State Channel projection App owned durable state WebGPU OS CSE preferences, document state, workflow state Shared mergeable state CRDT or semantic replication workstation layout,


Particle State Channels

App owned durable state WebGPU OS CSE preferences, document state, workflow state Shared mergeable state CRDT or semantic replication workstation layout, offline edits Particle Network Remote view State Channel client dashboard value, inspector state SSE by default Do not mirror the same authoritative value into independent UI, ECS, and network stores. Keep one owner. Derive projections for every other consumer. Define a channel The authority serializes submissions. It validates the channel, action, payload, expected revision, authority epoch, and optional fencing token. Duplicate intent IDs receive duplicate receipts without reapplying the mutation. (Source: ) Connect Plauna holds the latest projection for rendering. updates retained nodes. and dispatch actions; they do not write an authoritative projection before a receipt arrives. A state channel descriptor creates the client and resolves its transport, then owns cleanup. Callers may still provide an existing client. (Source: , , ) Connect ECS replication version 2 selects a named profile. Profiles set authority, cadence, projection strategy, component interest, and transport. Use for state exposed to browser views over SSE. Use or for peer simulation traffic over mesh. (Source: , ) SSE is the State Channel standard, not a replacement for every network lane. WebRTC mesh carries peer gameplay and semantic replication. BroadcastChannel remains useful for same origin peer tabs. In process transport remains useful for tests and local authorities. Connect CSE app state commits each accepted intent through with . The compare and swap result becomes the new authority state. External CSE writes produce a replacement snapshot. (Source: , ) The OS persists bounded authority checkpoints and offline intent outboxes through . A


Particle State Channels

state. External CSE writes produce a replacement snapshot. (Source: , ) The OS persists bounded authority checkpoints and offline intent outboxes through . A standby restores only valid, non regressing checkpoints. uses signed, replay rejected heartbeats, deterministic takeover, and strictly increasing fencing tokens before a promoted peer accepts writes. This is browser availability and stale writer fencing, not Byzantine consensus across a physical network partition. (Source: , , ) An authority is eligible only while its scoped mesh route is active. Suspending that route removes local authority immediately. On resume, the coordinator waits for a current authority heartbeat before deterministic failove


AI & Accessibility

How this documentation stays safe and useful for both AI agents and humans — discovery files, agent boundaries, self-contained sections, metadata, and accessibility. AI & Accessibility This documentation is built to be AI safe (readable by and guiding to LLM agents) and human safe (accessible, accurate, and clear). This page records those conventions. They draw on the emerging llmstxt.org proposal, the agents.md convention, the Diátaxis framework, and AI/RAG writing guidance. is supplemental discovery metadata, not a replacement for canonical Markdown and source code. Making the docs AI safe Discovery files (guide the AI to its places) — a curated, machine readable index at the web root so agents can discover it without knowing the documentation layout. A portable copy also lives in . — the curated pages concatenated for full context ingestion (the large generated reference is linked, not inlined). — an ES module catalog with the source path, source server import specifier, source hash, detected exports, and signatures. Summaries appear only where source JSDoc provides them; quantifies the remaining gaps and distinguishes repository source mode from compiled production mode. — bounded documentation chunks generated from the search index. Each UTF 8 line is an independent JSON object with source metadata, a stable chunk position, and a SHA 256 content hash. — the API catalog flattened to one source backed module or detected export per UTF 8 line. It preserves module paths, source imports, source hashes, signatures, and empty summaries when JSDoc has no description. and — crawler discovery files generated alongside the LLM indexes. Curated pages point to raw Markdown, API catalogs point to JSON, and bundled generated references use stable URLs. (at the root) — a "README


AI & Accessibility

the LLM indexes. Curated pages point to raw Markdown, API catalogs point to JSON, and bundled generated references use stable URLs. (at the root) — a "README for agents": where things live, which commands to run, what may be changed, and the hard boundaries. AI agents should read it first. Regenerate discovery files after content changes: refreshes both the copies and the web root discovery files. It generates the canonical sitemap by default; pass and only for another deployment. The validator rejects stale local ports, malformed or stale JSONL records, oversized feeds, malformed enriched API indexes, known nonexistent GPU symbols, missing root discovery files, and public wrappers that expose documentation only through an iframe. Self contained sections LLMs retrieve chunks , not whole pages, and document order is not preserved. So each section must make sense in isolation: Front load context — start a section by naming the subsystem/feature it concerns. Use descriptive headings that say what the section accomplishes. Avoid back references like "as mentioned above," "now that you've," or "with everything configured." Include complete steps within a section rather than relying on earlier ones. Page metadata (frontmatter) Pages may begin with a YAML frontmatter block. The viewer strips it (showing the description as a subtitle) and the build tools use it for richer search and freshness signals: and improve retrieval; is a freshness signal valued by AI search. Verifiability over fluency Every behavioral claim must be traceable to a source file — cite it. The per symbol API reference is machine extracted and may lag the source; the generated banner marks it. Improve accuracy by editing JSDoc upstream , then regenerating. Prefer Markdown/HTML over PDFs; keep semantic


AI & Accessibility

lag the source; the generated banner marks it. Improve accuracy by editing JSDoc upstream , then regenerating. Prefer Markdown/HTML over PDFs; keep semantic structure (real headings, lists, tables) so crawlers and models parse it cleanly. Making the docs human safe Accessibility Descriptive link text — never "click here". Alt text on every image; text equivalents near every diagram (a screen reader may not read a rendered SVG). No layout relative references ("above"/"below"/"on the right") — refer to sections by name. Meaningful, ordered headings; sufficient color contrast in the dark theme. The viewer honors , exposes / on navigation, and provides a skip link and keyboard shortcuts. Safety & accuracy Never inclu