packages/PublisherKeyManager.js

packages/PublisherKeyManager.js
Classes
class PublisherKeyManager
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PublisherKeyManager.js — the developer's portable package signing key. Distinct from (the device identity), whose private key is NON extractable and therefore cannot be backed up, moved between machines, or rotated with a lineage. A publisher who ships packages needs a key they can: generate once and KEEP SAFE (encrypted export the dev stores offline), re import on another machine / after reinstall, ROTATE while proving continuity (old key signs the new key — see kernel/SigningLineage.js), so app updates stay verifiable and isolated. The keypair is ECDSA P 256, extractable , stored locally (JWK in the IDB kv store) for day to day signing, plus an AES 256 GCM (PBKDF2 SHA256) encrypted backup the dev downloads and keeps. Signatures are raw IEEE P1363 (WebCrypto default), the same format / CollabIdentity expects, and fingerprints are computed via so the publisher fingerprint scheme matches the rest of the trust system. Classes Method Signature Summary Load a previously generated/imported publisher key from local storage. Status snapshot for UI. A shaped adapter so existing signing paths (PackageBuilder .buildV2 / AppCompiler) can sign with the PUBLISHER key instead of the device key, with zero changes to their signing logic. Generate a brand new publisher key (replaces any current one). Sign a string with the publisher private key (raw P1363 signature). Encrypted backup the developer downloads and keeps safe. AES 256 GCM with a key derived from via PBKDF2 SHA256. Returns a JSON serialisable envelope; the passphrase is NEVER stored. Restore a publisher key from an encrypted backup envelope + passphrase. Genesis (single node) signing lineage for an app, anchored at the current key.


packages/PublisherKeyManager.js

stored. Restore a publisher key from an encrypted backup envelope + passphrase. Genesis (single node) signing lineage for an app, anchored at the current key. Rotate the signing key: the CURRENT key signs the NEW key (proof of rotation), the new key becomes current, and the extended lineage is returned. Pass the app's existing lineage (or omit for a fresh genesis→rotate). <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


packages/UpdateManager.js

packages/UpdateManager.js
Classes
class UpdateManager
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: UpdateManager.js — block level differential update engine (MSIX style, web native). Update flow: check(appId) → fetch remote blockmap from sourceUrl, diff against installed blockmap, return UpdateJob with changed/removed file lists. apply(appId) → download only changed chunks, verify each sha256, verify package ECDSA P256 signature, atomic swap installed dirs, save previous version to rollback slot, update registry. rollback(appId)→ delegate to PackageManager.rollback() checkAll() → check all installed packages that have a sourceUrl setSource() → delegate to PackageManager.setSource() Remote blockmap format (served at {sourceUrl}/blockmap.json): { "appId": "os.my app", "version": "1.2.0", "files": [ { "path": "index.js", "sha256": "hex...", "size": 8192 }, { "path": "manifest.json", "sha256": "hex...", "size": 512 } ], "signature": "base64 ecdsa der...", // optional — over canonical payload "signerPublicKey": { "kty":"EC","crv":"P 256", ... } // optional JWK } Storage layout (under /os/packages/): .updates/{appId}/remote blockmap.json ← cached remote blockmap post check .updates/{appId}/staged/ ← downloaded changed files installed/{appId}/{version}/ ← live package (PackageManager layout) rollback/{appId}/{version}/ ← previous version slot Classes Method Signature Summary Configure the version cooldown window (ms). Set enabled=false to disable. Fetch the remote blockmap and diff against the installed blockmap. Returns a serialisable UpdateJob snapshot. Check all installed packages that have a sourceUrl. Skips pinned packages. Download changed chunks, verify sha256, verify signature, atomic swap. Re runs check() if the job is not in 'available' state. Roll back to the previous


packages/UpdateManager.js

Download changed chunks, verify sha256, verify signature, atomic swap. Re runs check() if the job is not in 'available' state. Roll back to the previous installed version. Delegates to PackageManager. Set or update the source URL for a package. Validates the URL first. Validate + normalise a package source base URL (https; http only for localhost dev). Resolve a per file download URL and refuse origin escape / path traversal. Current UpdateJob snapshot for one package. List snapshots for all tracked packages. Return all packages with updates available (state === 'available'). Decide whether a remote release is within the cooldown window. Uses remote.builtAt / publishedAt; if absent, cannot enforce (returns not held). An explicit remote.urgent=true bypasses cooldown (security fixes). Normalize blockmap v1 (v3 JHC1: files object, packageId) and legacy v2 (files array, appId) into a common shape. Preserves signature fields. Compare two blockmaps and return the diff. Fetch a single file, verify its sha256, return ArrayBuffer. Throws on HTTP error or hash mismatch. Verify the ECDSA P256 signature over the canonical blockmap payload. Canonical payload = JSON.stringify({ appId, version, files }) — no signature fields. Trust order: 1. Key stored in the local registry (TOFU — prevents signer substitution attacks) 2. Key embedded in the remote blockmap (first time install or trust upgrade) Returns { ok, reason } where reason='missing' means unsigned (not an error per se). <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security &


packages/UpdateManager.js

key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes command


packages/Zip.js

packages/Zip.js
Classes
class Zip
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! 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 Create a ZIP archive. Entries are DEFLATE compressed (method 8) when that shrinks them, else STORED (method 0) — the result is always a valid ZIP. Parse a ZIP archive into a { name → Uint8Array } map. Supports STORE (0) and DEFLATE (8). <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/Desktop.js

createProvisionalMountHandoff({ controller = new AbortController()

guardMountRegistrations(namespace, signal, methods = [], label = 'app capability')

<! 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 Desktop.js — the OS shell compositor. Owns: Plauna workspace (virtual desktops, panel chrome, window management). Taskbar (bottom bar: start menu + running apps + status tray). NotificationCenter (toast/banner delivery). Routing of kernel 'ui:open panel' events to WorkspaceManager. Phase 2 adds AppManifestLoader → dynamic app registration. Phase 3 adds GPU panel wiring (canvas surface allocation per app). Method Signature Summary Route an "open Settings" request to the Control Panel's Settings tab. The optional (e.g. 'appearance') selects the settings sub tab. If the Control Panel is not yet running, the target is stashed on the kernel so the app applies it on mount; otherwise a live event navigates it. Debounce window state writes so rapid drag/resize events don't thrash localStorage. Persist position/size + maximized flag. While maximized, store the pre maximize rect. Re clamp every open window into the work area when the viewport resizes. Enter/exit the immersive 3D desktop. Safe no op if unsupported. True when the focused app is maximized or the page is in browser fullscreen — in which case middle click belongs to the app, not the OS. Whether the immersive parallax Exposé is enabled (Personalization → Effects → "Immersive Desktop"). Read live from os.appearance so the toggle takes effect immediately; defaults ON when unset. True only when a pointer event lands on the BLANK main desktop surface — i.e. inside the desktop workspace but NOT over any running app window or a desktop shortcut. Used to scope the immersive middle click so it never steals the middle button


shell/Desktop.js

the desktop workspace but NOT over any running app window or a desktop shortcut. Used to scope the immersive middle click so it never steals the middle button (autoscroll/paste) from apps or other surfaces. Initialize the experimental GPU native UI compositor. This renders the desktop's windows as live 3D quads with no DOM. The classic DOM/Plauna stack is kept intact underneath as the always available fallback — the GPU UI just hides it while active and restores it on exit. The F4 toggle is disabled; the GPU UI is only entered programmatically (Escape exits). Enter/exit the GPU native UI. While active the DOM workspace is hidden (not destroyed) so it remains a working fallback. Extension capture sees the visible tab — which is the opaque GPU canvas once shown — so to refresh we briefly hide the canvas, let the live DOM show for a couple frames, capture+crop, then restore. Debounced and only fired after interactions / focus changes to keep the blink rare. One time feature detection with a real trial draw. Forward a GPU window pointer event into the underlying live DOM panel. Window local px map 1:1 to panel local px (the window mirrors the panel), so we add the panel's live screen rect and dispatch synthetic events to the real element. Focusing on 'down' lets the physical keyboard flow to the app natively (no synthetic key handling needed). Live mode only. Attach a live Element Capture <video to each running app's panel and register it with the compositor. Returns true if any window went live. On denial/failure, cleans up and returns false (→ snapshot fallback). Cheap perceptual hash of a frame (downscaled) for change detection. Adaptive self scheduling capture loop. Each iteration grabs ONE fully isolated Element Capture frame for the most overdue window and uploads it


shell/Desktop.js

detection. Adaptive self scheduling capture loop. Each iteration grabs ONE fully isolated Element Capture frame for the most overdue window and uploads it to that window's own texture (no smear). Per window interval ADAPTS: frames that changed → interval shrinks toward 60fps; unchanged (static page) → grows toward 250ms. The focused/interacting window is pinned to the max rate. The capture pipeline itself drops frames for static surfaces, so this matches each window's real update rate. Resolve the logical cursor type the real DOM wants at a screen point, so the virtual cursor matches the app (pointer/text/grab/default). The GPU canvas sits on top, so we briefly disable its hit testing for the probe. Apply Elem


shell/DialogManager.js

shell/DialogManager.js
Classes
class DialogManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: DialogManager.js — OS level dialog system. Handles kernel events and renders styled alert / confirm / prompt dialogs as a layered overlay above all panels. API (via kernel.events or syscalls.ui. ): ui:modal { type, title, message, icon, buttons, defaultValue, resolve } Promise returning syscalls (see Syscalls.js): syscalls.ui.alert(msg, opts) → Promise<void syscalls.ui.confirm(msg, opts) → Promise<boolean syscalls.ui.prompt(msg, default, opts) → Promise<string null Classes DialogManager.js — OS level dialog system. Handles kernel events and renders styled alert / confirm / prompt dialogs as a layered overlay above all panels. API (via kernel.events or syscalls.ui. ): ui:modal { type, title, message, icon, buttons, defaultValue, resolve } Promise returning syscalls (see Syscalls.js): syscalls.ui.alert(msg, opts) → Promise<void syscalls.ui.confirm(msg, opts) → Promise<boolean syscalls.ui.prompt(msg, default, opts) → Promise<string null Method Signature Summary Attach to a container (usually document.body or the desktop root). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/NotificationCenter.js

shell/NotificationCenter.js
Classes
class NotificationCenter
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: NotificationCenter.js — routes kernel ui:notify events to Plauna's ToastManager. Uses Plauna ToastManager directly (the same underlying system NotificationSystem uses). Falls back to a minimal DOM toast only if Plauna has not mounted yet. Classes Method Signature Summary Called by Desktop after Plauna mounts (CSS/theme guaranteed ready). Start listening to kernel ui:notify events. Remove a single notification by id. Returns true if one was removed. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/PackageHostRealm.js

shell/PackageHostRealm.js
Classes
class PackageHostRealm
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageHostRealm.js — run an installed NATIVE package app inside an opaque origin sandboxed iframe, bridging the kernel syscalls over a nonce bound postMessage RPC. WHY: imports a package's entry module straight into the OS origin (S2). Trusted/root packages may keep that fast shared realm, but pinned/untrusted packages must NOT touch , the OS DOM, localStorage, the extension bridge, or any accidental globals. This realm gives them an (NO ) iframe — a true origin boundary — and proxies the syscall surface back to the host's GUARDED syscalls for that app. BRIDGE SCOPE (honest limits): Async, structured cloneable syscalls (fs. , storage. , ui.notify/alert/ confirm/prompt, log. , sandbox. , net send/fetch, pkg reads, etc.) work: each call round trips to the host, which invokes the real guarded method. Subscriptions / callbacks ( , , , …) CANNOT cross the boundary; the in iframe proxy returns a no op unsubscribe so apps that register listeners do not crash (they simply receive no host events yet). Raw / GPU surfaces cannot cross an opaque origin boundary, so GPU panel apps are NOT isolated here (the launcher keeps them shared). SECURITY: the host only ever services RPC bearing the exact per instance nonce from the iframe it created, and only invokes (already guarded + capability checked for THIS appId). Unknown namespaces/methods are refused. Classes Method Signature Summary Gather files, build the sandboxed iframe, and boot the app inside it. The in iframe bootstrap. Runs in the opaque origin. Waits for pkgInit, builds a blob URL module graph from the shipped files, creates a syscall RPC proxy, imports the entry module, and mounts the default export app. <! HUMAN NOTES Notes &


shell/PackageHostRealm.js

blob URL module graph from the shipped files, creates a syscall RPC proxy, imports the entry module, and mounts the default export app. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/StartMenu.js

shell/StartMenu.js
Classes
class StartMenu
Notes & Examples
Command Bus Pattern

<! 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 <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/StatusTray.js

shell/StatusTray.js
Classes
class StatusTray
Notes & Examples
Command Bus Pattern

<! 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 StatusTray.js — rightmost section of the taskbar. A thin orchestrator: it composes stateless tray widgets (see ./tray/ tray widgets.js) and owns the per frame update loop. It does NOT render the calendar — clicking the clock requests the Calendar app's flyout surface. Layout (left → right): GPU stat FPS stat 🔍 ⚡ Clock 🔔 Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/Taskbar.js

shell/Taskbar.js
Classes
class Taskbar
Notes & Examples
Command Bus Pattern

<! 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 Taskbar.js bottom shell coordinator. Rendering and behavior live in shell/taskbar modules so the taskbar can grow without becoming another monolithic desktop controller. Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/WindowSizer.js

computeWindow(manifest, cascadeIndex = 0)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WindowSizer.js — Viewport aware window sizing and placement. Computes default window dimensions and screen position based on: 1. The LIVE available desktop area (viewport minus taskbar) — not device type. 2. The app manifest's (and optional ) to pick a sizing profile. 3. The manifest's treated as design time values at a 1440px reference viewport, then scaled proportionally to the actual viewport. Windows are centered in the available desktop area, with a configurable cascade offset for stacking multiple windows. ── Viewport contexts (based on available desktop width) ────────────────── compact < 640px — very constrained (browser in half screen, etc.) medium 640–1024 — tablet / laptop / small desktop window wide 1024–1440 — typical desktop ultrawide 1440 — large monitor / maximized on 4K ── Sizing profiles (per manifest category / sizingHint) ────────────────── compact → small, fixed size utility (calculator, clock) utility → small utility panel tools → medium tool (settings, pkg manager) system → medium large system panel (sysmon, task manager, terminal, files) debug → narrow + tall (devconsole, log viewer) creative → large workspace (paint, notepad) webgpu → large with canvas (fractal, particles, gpu manager) games → large, prefers square ish (minesweeper, snake, solitaire) workspace → near full (browser, heavy editors) [sizingHint override] full → fills entire desktop area [sizingHint override] Functions Returns the current available desktop dimensions (px). Compute the optimal window { width, height, x, y } for a given manifest. Parameters: (object) — — app manifest (category, sizingHint?, defaultWidth?, defaultHeight?) (number) — — how many windows are already open (for


shell/WindowSizer.js

manifest. Parameters: (object) — — app manifest (category, sizingHint?, defaultWidth?, defaultHeight?) (number) — — how many windows are already open (for cascade offset) Returns: } <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/WindowStateStore.js

saveState(appId, { x, y, width, height, maximized = false })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WindowStateStore.js — Persist and restore per app window position/size. Stored in localStorage under 'os.windowStates' as a versioned envelope whose field maps appId → state. The historical bare map remains readable. Validates a restored state against the current viewport before using it; if the position is out of bounds or the size is unreasonable the saved state is silently ignored and the app opens at its computed default. Functions Validate a saved state for corruption only (finite, positive size). Position reachability is no longer a reject reason — clampToViewport() moves an off screen window back into view instead of discarding the saved state. Reposition a state so a reachable strip of its titlebar stays inside the work area. Handles smaller screens / resolution changes / disconnected monitors — the window is pulled back on screen rather than left unclickable. Clamp a state's width and height so neither falls below 15% nor exceeds 100% of the available desktop area. Position is preserved as is. Load the saved window state for an app. Returns null when nothing is stored yet. Persist the current window state for an app. Remove the saved window state for an app (e.g. after a reset). Remove every persisted window geometry record. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/app-icon.js

renderAppIcon(container, icon, { fallback = '▪' } = {})

async bytesToIcon(bytes, filename = 'icon')

async urlToIcon(url, { fetchImpl = null } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: app icon.js — custom app icons: emoji/glyph OR an uploaded/online image, animated GIF/WebP, or a short video. A manifest value may be ANY of: • an emoji / short glyph — "🧩" (default; what the shell drew before) • a still image data/URL — data:image/… or https://…/x.png • an ANIMATED image — animated GIF / WebP (plays via <img ) • a short video — data:video/… or https://…/x.webm (muted loop) renderAppIcon() paints the right element into a container — drop in for the old . Media icons size to the container's font size (1em square), so each call site keeps its existing sizing. fileToIcon()/urlToIcon() turn a chosen file or remote URL into a compact, self contained data URL (downscaled + size capped; animation preserved when it fits) suitable for embedding in a manifest at compile time. Functions Render into (cleared first). Emoji/glyph → text (so the caller's font size applies); image/video → a 1em square media element. Parameters: (HTMLElement) — No description in source JSDoc. (string) — No description in source JSDoc. Turn a chosen File into a compact icon data URL. • video → kept as is if ≤ VIDEO CAP (muted loop). • animated → kept as is if ≤ FULL CAP (preserves animation); else flattened. • SVG → kept as is if small; else rasterised. • other img → center cropped + downscaled to a 128² WebP. Build an icon data URL from raw bundled file bytes (Uint8Array/ArrayBuffer) or a string (SVG/text), inferring the MIME type from the filename. Used to auto detect an icon from an app's own files at ingest time. Fetch a remote image/video URL and embed it as a compact data URL (so the icon is self contained — no live remote dependency, no privacy leak at render time). Cross origin hosts that


shell/app-icon.js

URL and embed it as a compact data URL (so the icon is self contained — no live remote dependency, no privacy leak at render time). Cross origin hosts that block CORS will reject; the caller should suggest downloading + uploading instead. Parameters: (string) — http(s) URL of an image/GIF/video <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


computeLayoutRect(layout, inputArea, inputGap = 8)

detectEdgeLayout(pointer, inputArea, threshold = 34)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Pure window layout geometry shared by the desktop shell and Theme Manager. Functions Compute a pixel rect for a named layout. Gaps are applied at outer and inner edges. Resolve an edge/corner pointer position into a snap layout. Constants <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/desktop/shellEnhancements.js
Functions
installShellEnhancements(desktop)
Notes & Examples
Command Bus Pattern

<! 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 <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/desktop/windowActions.js
Functions
bindViewportReclamp(desktop)
unbindViewportReclamp(desktop)
minimizePanel(desktop, appId)
restorePanel(desktop, appId)
focusPanel(desktop, appId)
Notes & Examples
Command Bus Pattern


shell/gpu-ui/GPUTextRenderer.js
Classes
class GPUTextRenderer
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPUTextRenderer.js — Level 4 GPU native text. The browser gives us no GPU text primitive, so we rasterize each glyph ONCE with Canvas2D (white on transparent) and pack it into the engine's VGPUTextureAtlas. Drawing a string then becomes a run of tinted textured quads sampled from that atlas — fully GPU composited, no DOM. Glyphs are cached per (sizePx, weight, char). Whitespace stores advance only (no atlas region). Coordinates are CSS pixels, top left origin, matching the compositor's quad space. Classes GPUTextRenderer.js — Level 4 GPU native text. The browser gives us no GPU text primitive, so we rasterize each glyph ONCE with Canvas2D (white on transparent) and pack it into the engine's VGPUTextureAtlas. Drawing a string then becomes a run of tinted textured quads sampled from that atlas — fully GPU composited, no DOM. Glyphs are cached per (sizePx, weight, char). Whitespace stores advance only (no atlas region). Coordinates are CSS pixels, top left origin, matching the compositor's quad space. Method Signature Summary Rasterize (or fetch cached) a single glyph and pack it into the atlas. Total advance width of a string at the given size/weight. Emit glyph quads for a string. is the TOP of the line box. Draw text clipped/ellipsized to a max pixel width. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/gpu-ui/GPUUICompositor.js
Classes
class GPUUICompositor
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPUUICompositor.js — Level 4 GPU native UI compositor (3D by default). Renders the desktop's windows as tinted textured quads in a real perspective scene on a full screen WebGPU canvas. There is NO DOM in this path: text is rasterized into a glyph atlas (GPUTextRenderer) and everything — window surfaces, titlebars, glyphs — is one unified quad primitive. Camera: a perspective camera placed on +Z at d = (vpH/2)/tan(fov/2) so the z=0 plane maps 1:1 to CSS pixels. A window at z=0 with no tilt is therefore pixel perfect and fully usable, yet it's a genuine 3D quad — depth (z) and tilt are first class, focused windows come forward, and a subtle pointer parallax sells the 3D space. Coordinate spaces: window local px: origin top left, +x right, +y down (what widgets author) world units == CSS px, origin = viewport center, +Y up, desktop on z=0 per window model matrix maps local px → world (bakes centering + Y flip) Transparency uses painter's order (windows sorted far→near, widgets in emit order) so there is no depth buffer and no coplanar z fighting. Engine tech reused (no duplication): VirtualGPU (isolated instance), VGPUTextureAtlas (glyph/solid atlas), engine/core/math (camera + unproject). Classes Method Signature Summary True while the user is dragging or interacting with a window's content. Windows whose screen space AABB is within px of a screen point. Returns [{ id, title, bounds:{x,y,width,height}, distance, inside }]. (Windows map 1:1 to pixels at z≈0, so x/y/w/h are good screen bounds.) Topmost window id under a screen point (ray cast), or null. Solid filled (optionally rounded) rect using the white atlas region. Textured quad sampling the content atlas (layer 1). uv =


screen point (ray cast), or null. Solid filled (optionally rounded) rect using the white atlas region. Textured quad sampling the content atlas (layer 1). uv = {u0,v0,u1,v1}. Upload (or replace) a window's content into its OWN dedicated GPU texture. One texture per window (never shared) → windows can never leak into each other. Source = ImageBitmap/Canvas/Video frame. Get/create a per window content texture, recreating on size change. Drop a window's content texture (revert to native rendering). Drop all content textures (e.g. on GPU UI exit). Opaque backdrop hides the on screen DOM behind the canvas (live mode). Register a live <video source for a window; updated every frame. Make the SOLE live window (only one element can be restricted at a time with Element Capture). Previously live windows keep their last frame as a static texture (NOT destroyed). Copy each live window's current video frame into its OWN texture. Per window model matrix: local px (top left,+y down) → world (+Y up). Unproject a screen point into a world ray using the current viewProj. Project a screen point onto a specific window's plane → { lx, ly } or null. Topmost window hit by the pointer → { win, lx, ly } or null. Rasterize cursor sprites (arrow / hand / I beam) + a ripple ring into the atlas. Burst of staggered ripples on click (the 'spam splash'). Emit the screen space overlay layer: ripples then the virtual cursor (on top). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS


Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/gpu-ui/GPUWindow.js
Classes
class GPUWindow
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPUWindow.js — a GPU native window for the Level 4 3D UI. The window is authored entirely in LOCAL pixel space (origin = top left, +x right, +y down) and emits tinted atlas quads through the compositor's sink. It knows nothing about the camera: the compositor builds a per window model matrix from this window's desktop space rect + 3D placement (z/tilt) and applies the shared viewProj. This keeps widgets camera agnostic so the same window is pixel perfect head on (z=0) or tilted in the immersive spread. Hit testing is done in local space (compositor unprojects the pointer ray onto the window plane, then asks the window what was hit). Classes Method Signature Summary Center of the window in desktop space (CSS px). Emit this window's geometry as local space quads. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/gpu-ui/GPUWindowCapture.js
Classes
class GPUWindowCapture
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPUWindowCapture.js — live per window content via the Element Capture API. Chrome 132+ lets us restrict a getDisplayMedia track to a single DOM element (RestrictionTarget + track.restrictTo), yielding a live MediaStream of just that element's rendered subtree (no occlusion / "hall of mirrors"). We take ONE getDisplayMedia('this tab') stream, clone its track per window, restrict each clone to that app's panel element, and feed a hidden <video . The GPU compositor then copyExternalImageToTexture()s each video frame into the window's content atlas region every frame → fully live GPU windows. Requirements (per spec) on each captured element: it must form a stacking context (isolation:isolate) and be flattened (transform style:flat) with an opaque background. Desktop applies these before attaching. Gracefully unsupported on non Chromium / older builds (supported=false) so callers fall back to extension snapshot, then native chrome. Classes GPUWindowCapture.js — live per window content via the Element Capture API. Chrome 132+ lets us restrict a getDisplayMedia track to a single DOM element (RestrictionTarget + track.restrictTo), yielding a live MediaStream of just that element's rendered subtree (no occlusion / "hall of mirrors"). We take ONE getDisplayMedia('this tab') stream, clone its track per window, restrict each clone to that app's panel element, and feed a hidden <video . The GPU compositor then copyExternalImageToTexture()s each video frame into the window's content atlas region every frame → fully live GPU windows. Requirements (per spec) on each captured element: it must form a stacking context (isolation:isolate) and be flattened (transform style:flat) with an opaque


Requirements (per spec) on each captured element: it must form a stacking context (isolation:isolate) and be flattened (transform style:flat) with an opaque background. Desktop applies these before attaching. Gracefully unsupported on non Chromium / older builds (supported=false) so callers fall back to extension snapshot, then native chrome. Method Signature Summary Element Capture restrictTo() REJECTS on tracks that have clones (Chromium issue 41482026), so we keep exactly ONE track and never clone. Acquire (once) the shared display capture stream + shared video. Prompts. Restrict the single shared track to one element's rendered subtree (Element Capture). One element at a time; re call to switch. Never used on a cloned track (Chromium rejects), which is why we keep ONE track. Remove any element restriction (back to whole tab). Wait for the next decoded video frame (bounded). Grab ONE isolated frame of : restrict the track to it, wait for a fresh frame, snapshot to an ImageBitmap. Element Capture guarantees the frame contains only that element's subtree → no overlap bleed. Grab a whole tab frame (removes any restriction first). Used by the generic viewport capture path. No extension required. Stop everything including the shared display stream. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Immersive3DCompositor.js — Level 3 GPU compositor (Exposé style 3D desktop). Captures every live DOM panel to a GPU texture (via PanelCapture), then renders each as a textured quad in a perspective 3D scene on a full screen WebGPU overlay canvas. ALL matrix/camera math comes from the engine's direct named shader math library (engine/core/math) — we only add the WebGPU plumbing and the DOM→bitmap bridge the browser doesn't provide. Coordinate system (pixel perfect at immersion=0): World units == CSS pixels. Origin at viewport center, +Y up, desktop on z=0. Camera sits on +Z at distance d = (vpH/2)/tan(fov/2) so the z=0 plane fills the viewport exactly. A panel quad at z=0 therefore maps 1:1 to its DOM rect. immersion ∈ [0,1] pushes panels apart in Z by stacking order and adds a gentle mouse driven camera yaw/pitch for parallax — the "3D world" feel. Lifecycle: const c = new Immersive3DCompositor({ device, getPanels }); c.mount(); // create overlay canvas + pipeline await c.enter(); // capture panels, hide DOM, animate in await c.exit(panelId?); // animate out, restore DOM (focus panelId if given) c.unmount(); // full teardown Engine math used: mat4Identity, mat4Translate, mat4Scale, mat4Multiply, mat4LookAt, mat4PerspectiveDegWebGPU. Classes Method Signature Summary Capture all live panels, hide the DOM workspace, animate into 3D view. Animate out of 3D view, restore the DOM. If panelId given, that panel is focused/raised on exit (Exposé style selection). Crop one panel's region out of the full viewport screenshot and upload it. Default panel source: scan the DOM for Plauna DOM panels. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus


it. Default panel source: scan the DOM for Plauna DOM panels. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/immersive/PanelCapture.js
Classes
class PanelCapture
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ⚠ SUPERSEDED for GPU use. The bitmaps this produces are PERMANENTLY cross origin tainted (SVG <foreignObject rule) and are REJECTED by . The immersive compositor now captures the viewport via the extension bridge (chrome.tabs.captureVisibleTab → Desktop. captureViewport), which yields untainted, GPU uploadable pixels. This file is kept only for display only canvas uses (which tolerate taint). PanelCapture.js — live DOM element → ImageBitmap via SVG foreignObject. Everything else in the immersive compositor (3D quads, perspective camera, texture upload) is done with the engine's shader math + WebGPU stack. But the browser provides no API to turn an arbitrary <div (text + Plauna widgets) into pixels — only accepts <img /<canvas /<video /Blob. The zero dependency route is SVG <foreignObject : clone the element, inline its computed styles (a standalone SVG blob has no access to the page's stylesheets), serialize to XHTML, wrap in an SVG, rasterize through an <img , then . The resulting bitmap is uploaded by the engine's TextureManager ( ). Known limitations (inherent to foreignObject, documented for callers): <canvas /<video children don't serialize (their live pixels are lost). Cross origin images taint and are skipped by the browser. is not honored inside foreignObject. Custom web fonts must already be loaded (we don't embed font files). Usage: const cap = new PanelCapture(); const bitmap = await cap.capture(panel.element, { scale: devicePixelRatio }); // → upload bitmap via engine TextureManager. uploadBitmap(bitmap, label) bitmap.close(); Classes Method Signature Summary Capture a DOM element to an ImageBitmap. Walk source and clone trees in lockstep, baking the source's


label) bitmap.close(); Classes Method Signature Summary Capture a DOM element to an ImageBitmap. Walk source and clone trees in lockstep, baking the source's computed style onto each clone node as an inline attribute. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/overlay/AIOverlay.js
Classes
class AIOverlay
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AIOverlay.js — shell owned approval and elicitation popup. The surface is hidden unless the shared ElicitationManager has a pending request. It deliberately has no ambient bar, chat console, task browser, or timeline. Approval notes are bound to the exact request and elicitation and recorded before the resumed task can observe the decision promise. Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: The shell gives adaptation reviews distinct trusted UI only when the request is the exact AI Echo operation. Caller controlled schema labels alone are never enough to obtain privileged wording or non blocking decision behavior. Functions The shell gives adaptation reviews distinct trusted UI only when the request is the exact AI Echo operation. Caller controlled schema labels alone are never enough to obtain privileged wording or non blocking decision behavior. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


createApprovalCard(elicitation, { onApprove, onDeny })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ApprovalCard.js — overlay card for a pending AI tool call approval. Driven through the SAME ElicitationManager as questions (an approval is a boolean elicitation whose schema carries { kind:'approval', toolName, params, risk }) — no parallel approval queue. Parameters are shown through ParameterPreviewer (Phase 5) so secrets are masked before they ever hit the DOM. Functions <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


createElicitationCard(elicitation, { onRespond, onDecline })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ElicitationCard.js — overlay card for a mid task AI question to the user (Phase 4 ElicitationManager). Renders a text input, or buttons when the schema declares an enum of options. Answer → respond(); dismiss → decline(). Functions Validate the kernel owned checkpoint envelope before exposing choices. The UI does not infer choices or authority from prompts. It only renders the exact bounded values supplied by the active task elicitation. Parameters: (object null) — No description in source JSDoc. Returns: null} <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/start-menu/actions.js
Functions
makeDraggable(menu, node, app)
launchApp(menu, app)
addToDesktop(menu, appId)
Notes & Examples
Command Bus Pattern


shell/start-menu/apps.js
Functions
visibleApps()
searchApps(query)
groupAppsByCategory(apps)
categoryLabel(category)
categoryIcon(category)
appMap(apps)
Notes & Examples
Command Bus Pattern


shell/start-menu/constants.js
Constants
Notes & Examples
Command Bus Pattern

<! 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. Constants <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/start-menu/contextMenu.js
Functions
showContextMenu(menu, event, app)
dismissContextMenu(menu)
Notes & Examples
Command Bus Pattern

<! 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 <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/start-menu/dom.js
Functions
el(tag, options = {}, children = [])
append(parent, children = [])
clear(node)
sectionTitle(label, action = null)
Notes & Examples
Command Bus Pattern


shell/start-menu/state.js
Functions
loadPinned()
savePinned(pinned)
loadRecent()
saveRecent(recent)
loadCollapsed()
saveCollapsed(collapsed)
trackRecent(recent, appId)
Notes & Examples
Command Bus Pattern


shell/start-menu/vfsPins.js
Functions
writePinFile(menu, appId)
deletePinFile(menu, appId)
async initVFSPins(menu)
Notes & Examples
Command Bus Pattern


shell/start-menu/views.js
Functions
buildShell(menu)
renderAll(menu)
renderSearch(menu, query)
Notes & Examples
Command Bus Pattern


shell/taskbar/appButtons.js
Functions
mountAppsArea(taskbar)
bindProcessButtons(taskbar)
Notes & Examples
Command Bus Pattern


shell/taskbar/devBadge.js
Functions
mountDevBadge(taskbar)
bindModeBadge(taskbar)
Notes & Examples
Command Bus Pattern


shell/taskbar/showDesktop.js
Functions
mountShowDesktop(taskbar)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: showDesktop.js — the far right "Show desktop" sliver (Windows style). Click once to minimize every open window; click again to restore the same set. Mirrors the Win+D peek/minimize all corner button. We track which panels are currently minimized via the kernel's panel events so the toggle stays correct even as the user opens/closes/minimizes windows manually. Functions showDesktop.js — the far right "Show desktop" sliver (Windows style). Click once to minimize every open window; click again to restore the same set. Mirrors the Win+D peek/minimize all corner button. We track which panels are currently minimized via the kernel's panel events so the toggle stays correct even as the user opens/closes/minimizes windows manually. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/taskbar/startButton.js
Functions
mountStartButton(taskbar)
Notes & Examples
Command Bus Pattern


shell/tray/system-tray.js
Functions
createSystemTray(kernel)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: system tray.js — the notification area icon strip. Renders app registered status icons (kernel.tray) inline, collapsing extras into an overflow popup (the "^" chevron) just like Windows' notification area. Left click runs the icon's onClick; right click opens its menu (if any). createSystemTray(kernel) { el, dispose } Functions <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


shell/tray/tray-widgets.js
Functions
makeStatPill(modClass = '')
makeIconButton(icon, tooltip, onClick)
makeBellButton(onClick)
makeClockButton(onClick)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: tray widgets.js — stateless builders for the status tray DOM widgets. Un nested from StatusTray so the tray class stays a thin orchestrator. Each factory returns plain DOM (plus refs where the tray needs to update them); none of them hold tray state. Functions Stat pill with a status dot + text (used for GPU / FPS readouts). Square icon button (search / quick settings / bell). Bell button with an unread badge. Returns { wrap, badge, setCount }. Clock button (time + date stacked). Returns { btn, tick, dispose }. refreshes the displayed time; clears its interval. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


storage/AppDataReadbackService.js

storage/AppDataReadbackService.js
Classes
class AppDataReadbackService
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: OS wide catalog and encrypted readback coordinator for durable app data. Classes Method Signature Summary Return immutable, content free output contracts for index rebuilding. Re exports , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/AppSandbox.js

storage/AppSandbox.js
Classes
class AppSandbox
Functions
createSandboxSyscalls(sandbox)
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AppSandbox.js — Per app isolated, AES 256 GCM encrypted IndexedDB storage. Each app runs in its own IndexedDB database: os.sandbox.<appId completely separate from the kernel database (os.kernel). ── Isolation guarantees ───────────────────────────────────────────────────── • Different IDB database per app → app A can never query app B's IDB. • AES 256 GCM encryption at rest → even if raw IDB is accessed directly, values are unreadable without the derived key. • Key is PBKDF2 derived from: OS fingerprint (ECDSA public key hash) + appId → keys are device bound AND app bound; exporting the raw IDB to another OS instance or another appId produces only garbage. ── API ────────────────────────────────────────────────────────────────────── const sb = new AppSandbox('os.calculator', cryptoDriver); await sb.init(); await sb.set('lastResult', 42); // encrypt + store const v = await sb.get('lastResult'); // decrypt + return (null if missing) const keys = await sb.list(); // returns key names (not values) await sb.delete('lastResult'); await sb.clear(); // wipe all of this app's data const info = sb.info(); // { appId, dbName, encrypted: true } ── Syscall surface (apps see syscalls.sandbox. ) ──────────────────────────── Created by createSandboxSyscalls(sandbox) exported below. Apps never receive a reference to AppSandbox directly. Classes Method Signature Summary Open the IDB database and derive the AES key. Must be called once before use. Read and decrypt a value. Returns null if key is absent or decryption fails. Strict read for authority bearing callers. Missing and corrupt records are distinct: corruption is never converted into a blank value. Exact read with an opaque ciphertext


storage/AppSandbox.js

for authority bearing callers. Missing and corrupt records are distinct: corruption is never converted into a blank value. Exact read with an opaque ciphertext version token for conditional writes. Strict exact key batch read in one IndexedDB transaction. Encrypt and store a value. Value must be JSON serialisable. Encrypt and store multiple values, then publish one readback snapshot. Atomically apply a batch only while one exact logical record is unchanged. Return all stored key names (not values). Wipe all keys in this app's sandbox. Force the encrypted Files visible container to match the current IDB. Restore the encrypted container. Existing data requires an exact phrase. Functions Wrap an AppSandbox as the namespace for an app. Apps receive this — they never get a reference to the AppSandbox itself. Usage in app code: await syscalls.sandbox.set('prefs', { theme: 'dark' }); const p = await syscalls.sandbox.get('prefs'); const keys = await syscalls.sandbox.list(); await syscalls.sandbox.delete('prefs'); await syscalls.sandbox.clear(); const { appId, dbName, encrypted } = syscalls.sandbox.info(); <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/AppSettingsFile.js

async readAppSettings(syscalls, { migrate = true } = {})

async patchAppSetting(syscalls, appId, value)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Shared, Files visible settings document used by OS apps. Functions Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/BoundedTraversal.js

class StorageTraversalLimitError extends Error

isIgnoredEntry(name, rules = [], path = '')

async walkPaged(rootPath, listPage, options = {}, defaultIgnore = [])

<! 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 Functions Breadth first, paged traversal shared by OPFS and mounted folders. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/CacheDriver.js

storage/CacheDriver.js
Classes
class CacheDriver
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CacheDriver.js — Cache API wrapper for rebuildable assets. Used for content that can always be re downloaded/rebuilt: CDN assets and web dependencies Downloaded package chunks (sha256 keyed) App bundles and compiled shaders Prefetched update manifests Keys are URLs or opaque cache keys like "chunk:sha256 abc123". All methods are async. Classes Method Signature Summary Get a cached response body as text. Returns null if not cached. Get a cached response as ArrayBuffer. Returns null if not cached. Store a string or ArrayBuffer under the given key. Check if a key is cached. List all keys in a named cache. Delete an entire named cache. Get storage estimate for cached data. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/IndexedDBDriver.js

class IndexedDBDriverError extends Error

class IndexedDBBlockedError extends IndexedDBDriverError

class IndexedDBStaleConnectionError extends IndexedDBDriverError

class IndexedDBRecordVersionError extends IndexedDBDriverError

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: IndexedDBDriver.js — IndexedDB backed metadata store. The driver waits for transaction completion, closes connections when another tab upgrades the database, and refuses to reuse such stale connections. Store owners may opt into per record schema metadata and synchronous migrations; unregistered stores retain their original record shape. Classes Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary ${store} record Constants — IndexedDBDriver.js — IndexedDB backed metadata store. The driver waits for transaction completion, closes connections when another tab upgrades the database, and refuses to reuse such stale connections. Store owners may opt into per record schema metadata and synchronous migrations; unregistered stores retain their original record shape. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/KernelMetadataReadback.js

storage/KernelMetadataReadback.js
Classes
class KernelMetadataReadback
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Encrypted readback snapshot for the structured metadata DB. Non extractable CryptoKeys and native directory handles are represented by safe descriptors; their browser security boundary is intentionally retained. Classes Method Signature Summary <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/LegacyStorageReadback.js

storage/LegacyStorageReadback.js
Classes
class LegacyStorageReadback
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: LegacyStorageReadback.js — encrypted VFS readback for durable localStorage. Older OS modules still use localStorage directly. Rewriting every caller at once would create migration risk, so this service mirrors the durable keys into an AppSandbox. AppSandbox then publishes one authenticated, device bound ciphertext container under /user/app data. Raw names and values never appear in Files. OPFS fallback records and rebuildable caches are deliberately excluded because their authoritative data already lives elsewhere. Classes Method Signature Summary Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/MountDriver.js

storage/MountDriver.js
Classes
class MountDriver
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: MountDriver.js — File System Access API driver for user mounted folders. Manages persistent directory handles for: /mnt/engine — local engine source folder /mnt/assets — local asset folder /mnt/projects — local projects folder /mnt/apps — local user app folder Directory handles are persisted via IndexedDB (idbDriver) so mounts survive page reloads without re prompting the user (if permission granted). All read/write methods are async. Classes Method Signature Summary Open a directory picker and mount it at the given name. Restore persisted mount handles (call on OS boot). Request permission for an already stored mount handle. Prompts the user if permission was not already granted. Parse /mnt/<name /... → { mountName, relativeParts } Resolve a FileSystemFileHandle, optionally creating parent dirs and the file. Resolve a FileSystemDirectoryHandle, optionally creating along the path. Return { parent: DirectoryHandle, name: string } for the leaf of a path. Return the native File/Blob so callers can avoid a full memory copy. Move/rename within or across mounts. The FSAA has no rename primitive, so we copy then delete. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/MountGraph.js

storage/MountGraph.js
Classes
class MountGraph
Re-exports
Notes & Examples

<! 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 Ordered provider layers with GMod style read fallthrough and one write layer. Method Signature Summary Re exports <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/MountRegistry.js

storage/MountRegistry.js
Classes
class MountAliasError extends Error
class MountRegistry
Functions
validateMountAlias(value)
mountAliasKey(value)
Notes & Examples

<! 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 Case insensitive registry for provider neutral mount metadata. Method Signature Summary Functions Return a portable, single segment mount alias without changing its case. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/OPFSDriver.js

storage/OPFSDriver.js
Classes
class OPFSDriver
Constants
Notes & Examples

<! 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 OPFSDriver.js — Origin Private File System driver. Uses navigator.storage.getDirectory() to provide a private OS disk that: survives page reloads and browser restarts is not subject to the 5 MB localStorage quota supports byte level writes and sync access from workers is not visible or accessible to other origins All methods are async. Paths are POSIX style: /os/state/foo.json Method Signature Summary Return the native File/Blob without copying it through an ArrayBuffer. Stream a Blob/File directly into OPFS without base64 or an eager byte copy. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/RealmContentStore.js

storage/RealmContentStore.js
Classes
class RealmContentStore
Notes & Examples

<! 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 <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/StorageCoordination.js

class StorageCoordinationUnavailableError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Same origin storage coordination shared by tabs and workers. BroadcastChannel keeps observers coherent; Web Locks serializes lifecycle mutations. Both degrade to an in process queue when unavailable. Classes Method Signature Summary Method Signature Summary <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/StorageManager.js

class StorageAtomicConflictError extends Error

class StorageAtomicUnsupportedError extends Error

class StorageAtomicOutcomeUnknownError extends Error

class StorageAtomicAbortError extends Error

class RecycleBinSafetyError extends Error

class StorageContractError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StorageManager.js — unified storage facade. Routes filesystem paths to the correct backend: /os/ → OPFSDriver (OS internal files, packages, patches, logs) /user/ → OPFSDriver (user documents, settings, projects) /run/ → OPFSDriver (ephemeral runtime state — cleared on boot) /mnt/ → MountDriver (user mounted native folders via FSAA) /cache/ → CacheDriver (rebuildable assets, package chunks) (other) → OPFSDriver (fallback) IndexedDB (idbDriver) is NOT path routed — it is accessed directly by structured subsystems (PackageManager, PermissionManager, etc.). This is the backend for kernel/VirtualFS.js (which keeps its sync friendly public API and delegates here for persistence). Classes Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary Method Signature Summary True if the path lives in the compiled in, immutable /system tree. True if the path may be created/edited/deleted by the user. Throw a clear error when a mutating op targets the immutable system tree. Read a file without UTF 8 decoding. Required for PDFs and other binary assets. Read as a Blob/File without forcing an eager ArrayBuffer copy when supported. Compare and swap one exact text file under the same global mutation lock used by every cooperating StorageManager mutation. must describe either an absent path or the SHA 256 of the current exact UTF 8 text. A mismatch never reaches the backend write. Compare and swap exact binary bytes under the global mutation lock used by writeAtomic(). The caller buffer is copied before the first await, and the persisted bytes are hashed and compared byte for byte


storage/StorageManager.js

global mutation lock used by writeAtomic(). The caller buffer is copied before the first await, and the persisted bytes are hashed and compared byte for byte before the immutable receipt is returned. Persist a Blob/File directly; avoids base64 and avoids File.arrayBuffer(). Copy files or complete directory trees across OPFS and native mounts. Return an immutable observation token suitable for compare and swap edits. Constants <! HUMAN NOTES Notes & Examples Backup restore authority boundary Portable and native backups include checksummed files, but their ordinary merge and replace restore paths never import or . Replace mode preserves the active kernel owned records while removing and restoring ordinary user data. Preview and restore results expose and ; replace receipts also expose . Restoring those control records requires a separate kernel authorized recovery workflow.


storage/StorageSafety.js

class StorageContentValidationError extends Error

assertNoSecrets(value, { path = 'managed file' } = {})

async validateImportedFile(blob, name = '')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Browser file validation and secret detection. Files remain untrusted after validation. Classes Method Signature Summary Functions <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/StorageWorker.js

storage/StorageWorker.js
Exports
Notes & Examples

<! 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 No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/StorageWorkerClient.js

class StorageWorkerUnavailableError extends Error

<! 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 Method Signature Summary <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/SystemFS.js

storage/SystemFS.js
Classes
class SystemFS
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SystemFS.js — read only virtual filesystem for the compiled in OS. The engine, Plauna shell, editor, AGI runtime and the built in apps are packaged directly into the OS bundle (ES modules compiled into the runtime). They are NOT stored in OPFS or IndexedDB, so they can never be edited, moved, or deleted — they are part of the system image. This driver surfaces them as a browsable, read only tree mounted at so the Files app can SHOW where they live and clearly mark them immutable, while user/installed content (OPFS + IndexedDB) stays fully writable. Every entry returned carries so the UI and the StorageManager guards can treat it as immutable. All methods are async to match the other storage drivers. Classes Method Signature Summary True for any path inside the read only system tree. Relative parts under /system, e.g. /system/apps/os.files → ['apps','os.files']. Navigate the SYSTEM DOCS stub tree (dev/raw mode fallback). Lazily build a directory tree index from globalThis. OS SOURCE FILES (populated by the bundle engine source tree barrel in bundle mode). Returns Map<relDirPath, { subdirs: Set<name , files: Map<name, content } where the root directory key is ''. Returns null when the global is absent (dev / raw mode). Bundled (compiled in) apps from the global the AppRegistry also reads. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/UserDataPaths.js

cleanUserFileName(value, fallback = 'untitled')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Canonical user owned locations shown and managed by the Files app. Functions Device bound encrypted readback container for an app owned sandbox. Constants — Canonical user owned locations shown and managed by the Files app. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/WorkspaceOutputTerminology.js

workspaceOutputPresentation(entry, outputContracts = [])

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Presentation only terminology for canonical Workspace Output references. Functions Classify an indexed output for human facing UI without changing its signed identity or treating a derived index entry as a second copy of the file. Human facing catalog projection for settings and Files coverage views. Constants — Presentation only terminology for canonical Workspace Output references. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


storage/system-docs.js

storage/system-docs.js
Classes
class MyGpuApp
class HelloApp
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: system docs.js — the "examples database" surfaced as the read only /system tree. Goal: expose HOW to use each part of the compiled in OS (engine, Plauna shell, editor, AGI runtime, built in apps) WITHOUT shipping the proprietary source. Every leaf here is a usage/recipe document — it shows the public API and example calls a developer would write, not the implementation. Shape — a recursive node: { icon?: string, // shown in the Files app files?: { '<name ': '<text ' }, // leaf docs (markdown / example text) dirs?: { '<name ': <node }, // sub folders } Notes for authors: Use 4 space indented code blocks (NOT triple backticks) so content stays valid inside these template literal strings. Only document verified, public API surface (syscalls, app lifecycle, manifest schema, VFS). Keep deep internals conceptual. This is a database: add files/dirs freely — SystemFS renders them as is. Classes Method Signature Summary Method Signature Summary Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


Smith Lab

Smith Lab
Start here
Synchronized workbench
Physical and mathematical 3D
RF calculation core
Matching and tolerance automation
Touchstone and datasets
Public modules
Verification
Engineering references

Guided 2D and 3D Smith Chart learning, RF measurement analysis, and deterministic impedance-matching design in WebGPU OS. Smith Lab Smith Lab is the RF learning and design application. It combines an accessible Smith Chart academy, deterministic matching network synthesis, bounded Touchstone import, and synchronized SVG and WebGPU visualizations. The same frequency, load, reference impedance, selected marker, and sampled component path drive every visible result. (Source: ) The opening surface uses an original generated scientific cinematic coax and reflection field illustration. It is stored with its exact prompt and SHA 256 provenance and is explicitly labeled as a not to scale concept visualization. It never supplies chart coordinates or calculation results; the SVG, WebGPU, and RF model remain authoritative. Start here The opening screen separates three jobs instead of exposing every RF control at once: Learn the chart opens seven interactive lessons covering traveling waves, reflections, impedance, Smith mapping, components, stubs, and measurements. Match an impedance accepts ordinary , frequency, reference impedance, and velocity factor values, then synthesizes and ranks matching networks. Open measurement data accepts Touchstone files or pasted frequency tables and converts them to one canonical frequency indexed dataset. Guided mode uses plain language prompts and staged decisions. Engineer mode exposes overlays, exact numerical results, optimization, preferred value snapping, and tolerance controls. A metric can be selected to inspect its symbolic formula, substitutions, assumptions, result, and units. Synchronized workbench The central workbench provides an accessible SVG Smith Chart with impedance, admittance, and combined grids. Its marker supports pointer


Smith Lab

Synchronized workbench The central workbench provides an accessible SVG Smith Chart with impedance, admittance, and combined grids. Its marker supports pointer dragging and arrow keys. The selected point is synchronized with normalized impedance, admittance, reflection coefficient, phase, VSWR, return loss, mismatch loss, reflected power, voltage extrema, wavelength, and electrical length. A circuit strip shows each proposed element in source to load order and its value or electrical length. Selecting an element seeks the transformation timeline to that exact operation. The chart draws each impedance, admittance, or line segment separately, while the right panel shows the current substituted state and the calculated terminal residual. The linked Cartesian plot evaluates the selected network at every displayed frequency rather than repeating the unmatched load. (Source: ) The path record stores the load, ordered transformation steps, exact sampled impedance and admittance, normalized values, reflection coefficient, metrics, formula, and terminal state. Lossless line samples preserve reflection magnitude. Shunt stub samples add the calculated branch susceptance in the admittance domain. Exports include project JSON, chart SVG, 3D PNG, calculation CSV, Touchstone 2.1, and a printable report. Physical and mathematical 3D The physical RF view renders the current animated reflection coefficient as separate incident, reflected, and total voltage waves. It derives voltage and current envelopes from the same complex reflection state, uses selected line and stub electrical lengths, and adds energy flow and voltage stress cues. Dragging changes orientation and the wheel changes zoom. Smith Lab creates the WebGPU device and pipeline only when this view first opens, then retains


Smith Lab

cues. Dragging changes orientation and the wheel changes zoom. Smith Lab creates the WebGPU device and pipeline only when this view first opens, then retains that runtime while the user switches views. A visible backend badge reports startup and fallback state. The scene is explanatory rather than a validated electromagnetic field solver. (Source: ) Three mathematical views are separate from the engineering chart: Calculated network path lifts the exact per element Smith trajectory into depth and colors impedance, admittance, and line operations separately. Frequency tower projects the evaluated sweep into a three dimensional Smith trajectory and synchronizes its selected frequency marker. Riemann view maps the s