Navi Architecture and Delivery Plan

Historical Phase 0 pre-migration procedure

Phase 0: contracts, boundaries, and rollback

Phase 1: Continuity Kernel, Covenant, and genesis lineage

Phase 2: remote-first Cognition Fabric and self-model

Phase 3: Faculty Runtime and Authority Membrane

Phase 8.5 modular Artifact project projection

Phase 4: Causal Memory Weave and Relationship Graph

Phase 5: autonomy, resources, and delegation

Phase 6: Manifestations and Construct handoff

Phase 7: recovery, reconciliation, network hooks, and alpha

AI Echo Intelligence Upgrade — Post-Alpha Phase 8

Phase 8.0: Contracts and Regression Baseline

Phase 8.1: Unified Task State, Steering, and Progress

Phase 8.2: Deterministic Sherlock Investigation Episode

Phase 8.3: Context, Resource Discovery, and Dynamic Skills

Phase 8.4: Outputs, Dossiers, and Explainability

Phase 8.5 operator-controlled repair duration

Phase 8.5 provider-token accounting boundary

Phase 8.5 receipt-bound Artifact delivery

Phase 8.5 OS-owned saved-Artifact authoring lane

Phase 8.5 approved Smart-pool exhaustion

Phase 8.5 verified Artifact file activity

Phase 8.5 adaptive built-in signing and revision activation

Phase 8.5 trusted-default Faculty reconciliation and visible recovery

Phase 8.5 signed descriptor emission continuity

Phase 8.5 Artifact mutation settlement continuity

Phase 8.5 Codex-style incoming Artifact change visibility

Phase 8.5 durable approval popup recovery

Phase 8.5 semantic active steering and follow-up turns

Phase 8.5 operation-bound Artifact continuation

Phase 8.6 semantic Artifact formats and generated-code routing

Phase 8.7 isolated free-model steering lane

Phase 8.8 hard Artifact direct authoring and post-dispatch reconciliation

Phase 8.9 release-coherence crash containment

Phase 8.10 canonical Artifact revision references

Phase 8.11 receipt-warmed Artifact Studio loading

Phase 8.12 provider-native tool planning and endpoint restore containment

Phase 8.13 provider-native tool envelopes and mounted-workspace authority

Phase 8.14 workload-aware routing and per-Navi execution modes

Phase 8.15 Dodad compatibility naming and shared work-product workspace

Phase 8.16 human-first Navi and Presence studios

Phase 8.17 project-aware coding, verified Dodads, and reusable app surfaces

Phase 8.18 AI Echo remote cognition boundary

Phase 8.19 non-blocking AI Echo request preflight

Phase 8.20 exact Bypass prompt suppression

Phase 8.21 provider-native tool-only completion admission

Phase 8.22 unified Bypass at the signed Faculty boundary

Phase 8.23 live mounted-workspace resolution

Phase 8.24 final-answer tool-envelope containment

Phase 8.25 non-blocking auxiliary cognition

Phase 8.26 terminal next-turn ownership handoff

Phase 8.27 bounded mounted-workspace follow-up routing

Phase 8.28 fail-closed final-answer tool transport

Phase 8.29 bounded background cognition and current-turn journals

Phase 8.30 Dodad Forge recipes and mounted coding execution

Phase 8.31 Dodad Forge and mounted-project hardening

Phase 8.32 Surface Intelligence and visual coding context

Phase 8.33 Progressive Skills and specialist Dodad quality

Phase 8.34 AI Echo startup and background crash containment

Phase 8.35 bounded recovery indexes and permanent settlement isolation

Phase 8.36 clean-room semantic execution and mounted verification

Phase 8.37 AI Echo fast-open and correlated diagnostics

Phase 8.38 revision-bound mounted mutation and Cognition isolation

Canonical N1-N12 terminology, built-in runtime policy, security boundaries, migration rules, phased gates, and rollback procedures for the WebGPU OS Navi platform. Navi Architecture and Delivery Plan This page defines the target Navi architecture and the gated delivery plan for engineers working on WebGPU OS and AI Echo. It is a design contract. A checked design item means its decision is frozen. A checked implementation or exit gate item means its named verification evidence passes. Status and progress rules means the named design decision or verified implementation is complete. means the work has not passed its stated gate. A phase cannot start until the previous phase's exit gate passes. A failed gate returns to its originating phase. Do not defer it as later work. Every phase must leave the OS bootable and retain a tested rollback path. Navi is a built in WebGPU OS runtime and starts automatically. No user or app can enable or disable it, and no authority exists. Automatic startup never grants identity or action authority by itself. Operator bound services require a live, current, non revoked Passport and fail closed with exact health and error codes when that authority or another prerequisite is unavailable. Services that await the first primary Navi remain non authoritative in a typed dependency state, then rebind at the exact Continuity generation after genesis or primary selection. Planning status [x] Audit current AI Echo, AI Hub, VFS, tool firewall, autonomy, skills, memory, profiles, and recovery systems. [x] Audit PROJECT L.U.N.A. for reusable architectural concepts. [x] Choose a browser native implementation with no LUNA runtime dependency. [x] Choose remote first model routing. [x] Choose AI Echo as the Navi chat, setup, approval, and management console.


Navi Architecture and Delivery Plan

Historical Phase 0 pre-migration procedure

Phase 0: contracts, boundaries, and rollback

Phase 1: Continuity Kernel, Covenant, and genesis lineage

Phase 2: remote-first Cognition Fabric and self-model

Phase 3: Faculty Runtime and Authority Membrane

Phase 8.5 modular Artifact project projection

Phase 4: Causal Memory Weave and Relationship Graph

Phase 5: autonomy, resources, and delegation

Phase 6: Manifestations and Construct handoff

Phase 7: recovery, reconciliation, network hooks, and alpha

AI Echo Intelligence Upgrade — Post-Alpha Phase 8

Phase 8.0: Contracts and Regression Baseline

Phase 8.1: Unified Task State, Steering, and Progress

Phase 8.2: Deterministic Sherlock Investigation Episode

Phase 8.3: Context, Resource Discovery, and Dynamic Skills

Phase 8.4: Outputs, Dossiers, and Explainability

Phase 8.5 operator-controlled repair duration

Phase 8.5 provider-token accounting boundary

Phase 8.5 receipt-bound Artifact delivery

Phase 8.5 OS-owned saved-Artifact authoring lane

Phase 8.5 approved Smart-pool exhaustion

Phase 8.5 verified Artifact file activity

Phase 8.5 adaptive built-in signing and revision activation

Phase 8.5 trusted-default Faculty reconciliation and visible recovery

Phase 8.5 signed descriptor emission continuity

Phase 8.5 Artifact mutation settlement continuity

Phase 8.5 Codex-style incoming Artifact change visibility

Phase 8.5 durable approval popup recovery

Phase 8.5 semantic active steering and follow-up turns

Phase 8.5 operation-bound Artifact continuation

Phase 8.6 semantic Artifact formats and generated-code routing

Phase 8.7 isolated free-model steering lane

Phase 8.8 hard Artifact direct authoring and post-dispatch reconciliation

Phase 8.9 release-coherence crash containment

Phase 8.10 canonical Artifact revision references

Phase 8.11 receipt-warmed Artifact Studio loading

Phase 8.12 provider-native tool planning and endpoint restore containment

Phase 8.13 provider-native tool envelopes and mounted-workspace authority

Phase 8.14 workload-aware routing and per-Navi execution modes

Phase 8.15 Dodad compatibility naming and shared work-product workspace

Phase 8.16 human-first Navi and Presence studios

Phase 8.17 project-aware coding, verified Dodads, and reusable app surfaces

Phase 8.18 AI Echo remote cognition boundary

Phase 8.19 non-blocking AI Echo request preflight

Phase 8.20 exact Bypass prompt suppression

Phase 8.21 provider-native tool-only completion admission

Phase 8.22 unified Bypass at the signed Faculty boundary

Phase 8.23 live mounted-workspace resolution

Phase 8.24 final-answer tool-envelope containment

Phase 8.25 non-blocking auxiliary cognition

Phase 8.26 terminal next-turn ownership handoff

Phase 8.27 bounded mounted-workspace follow-up routing

Phase 8.28 fail-closed final-answer tool transport

Phase 8.29 bounded background cognition and current-turn journals

Phase 8.30 Dodad Forge recipes and mounted coding execution

Phase 8.31 Dodad Forge and mounted-project hardening

Phase 8.32 Surface Intelligence and visual coding context

Phase 8.33 Progressive Skills and specialist Dodad quality

Phase 8.34 AI Echo startup and background crash containment

Phase 8.35 bounded recovery indexes and permanent settlement isolation

Phase 8.36 clean-room semantic execution and mounted verification

Phase 8.37 AI Echo fast-open and correlated diagnostics

Phase 8.38 revision-bound mounted mutation and Cognition isolation

with no LUNA runtime dependency. [x] Choose remote first model routing. [x] Choose AI Echo as the Navi chat, setup, approval, and management console. [x] Lock product, authority, privacy, recovery, branching, Faculty, and autonomy defaults. [x] Confirm the resource hardening baseline: 6 tests passing. [x] Begin implementation. [x] Complete the Phase 0 automated exit gate. [x] Complete the Phase 1 continuity exit gate. [x] Complete the Phase 2 cognition exit gate. [x] Complete the Phase 3 Faculty exit gate. [x] Complete the Phase 4 memory and relationship exit gate. [x] Complete the Phase 5 autonomy and resource exit gate. [x] Complete the Phase 6 Manifestation exit gate. [x] Complete the Phase 7 implementation and automated Navi Alpha exit gate. [x] Make Navi built in and automatic, retire the Settings release control, and remove user/app feature toggle authority. [x] Make AI Echo the automatic first primary Navi and add progressive, device protected recovery onboarding without blocking first use. [x] Complete the post alpha RealmForge workflow, evidence, transaction, and resumable task extension for AI Echo. [ ] Complete live deployment validation on the intended operator devices. The current AI Echo app provides conversations, editable Mind state, an inspectable operational journal, autonomous reflection scheduling, dynamic skills, managed files, and model routing. Editable identity, self model, Soul, personality, and history now bind to the selected in kernel owned, encrypted cognition records. The remaining app owned facilities are integration sources, not Navi identity authority. (Sources: , , , , and .) Locked architecture AI Echo is the primary chat, setup, approval, and management Manifestation for a Navi. AI Echo does not own the Navi's identity or


Navi Architecture and Delivery Plan

Historical Phase 0 pre-migration procedure

Phase 0: contracts, boundaries, and rollback

Phase 1: Continuity Kernel, Covenant, and genesis lineage

Phase 2: remote-first Cognition Fabric and self-model

Phase 3: Faculty Runtime and Authority Membrane

Phase 8.5 modular Artifact project projection

Phase 4: Causal Memory Weave and Relationship Graph

Phase 5: autonomy, resources, and delegation

Phase 6: Manifestations and Construct handoff

Phase 7: recovery, reconciliation, network hooks, and alpha

AI Echo Intelligence Upgrade — Post-Alpha Phase 8

Phase 8.0: Contracts and Regression Baseline

Phase 8.1: Unified Task State, Steering, and Progress

Phase 8.2: Deterministic Sherlock Investigation Episode

Phase 8.3: Context, Resource Discovery, and Dynamic Skills

Phase 8.4: Outputs, Dossiers, and Explainability

Phase 8.5 operator-controlled repair duration

Phase 8.5 provider-token accounting boundary

Phase 8.5 receipt-bound Artifact delivery

Phase 8.5 OS-owned saved-Artifact authoring lane

Phase 8.5 approved Smart-pool exhaustion

Phase 8.5 verified Artifact file activity

Phase 8.5 adaptive built-in signing and revision activation

Phase 8.5 trusted-default Faculty reconciliation and visible recovery

Phase 8.5 signed descriptor emission continuity

Phase 8.5 Artifact mutation settlement continuity

Phase 8.5 Codex-style incoming Artifact change visibility

Phase 8.5 durable approval popup recovery

Phase 8.5 semantic active steering and follow-up turns

Phase 8.5 operation-bound Artifact continuation

Phase 8.6 semantic Artifact formats and generated-code routing

Phase 8.7 isolated free-model steering lane

Phase 8.8 hard Artifact direct authoring and post-dispatch reconciliation

Phase 8.9 release-coherence crash containment

Phase 8.10 canonical Artifact revision references

Phase 8.11 receipt-warmed Artifact Studio loading

Phase 8.12 provider-native tool planning and endpoint restore containment

Phase 8.13 provider-native tool envelopes and mounted-workspace authority

Phase 8.14 workload-aware routing and per-Navi execution modes

Phase 8.15 Dodad compatibility naming and shared work-product workspace

Phase 8.16 human-first Navi and Presence studios

Phase 8.17 project-aware coding, verified Dodads, and reusable app surfaces

Phase 8.18 AI Echo remote cognition boundary

Phase 8.19 non-blocking AI Echo request preflight

Phase 8.20 exact Bypass prompt suppression

Phase 8.21 provider-native tool-only completion admission

Phase 8.22 unified Bypass at the signed Faculty boundary

Phase 8.23 live mounted-workspace resolution

Phase 8.24 final-answer tool-envelope containment

Phase 8.25 non-blocking auxiliary cognition

Phase 8.26 terminal next-turn ownership handoff

Phase 8.27 bounded mounted-workspace follow-up routing

Phase 8.28 fail-closed final-answer tool transport

Phase 8.29 bounded background cognition and current-turn journals

Phase 8.30 Dodad Forge recipes and mounted coding execution

Phase 8.31 Dodad Forge and mounted-project hardening

Phase 8.32 Surface Intelligence and visual coding context

Phase 8.33 Progressive Skills and specialist Dodad quality

Phase 8.34 AI Echo startup and background crash containment

Phase 8.35 bounded recovery indexes and permanent settlement isolation

Phase 8.36 clean-room semantic execution and mounted verification

Phase 8.37 AI Echo fast-open and correlated diagnostics

Phase 8.38 revision-bound mounted mutation and Cognition isolation

, and .) Locked architecture AI Echo is the primary chat, setup, approval, and management Manifestation for a Navi. AI Echo does not own the Navi's identity or cryptographic authority. The following boundaries are fixed: Kernel Navi services own identity, Covenant, memory, authority, lineage, Faculties, relationships, resource leases, and recovery. Remote models are the default cognition engines. A provider account, model, prompt, response, or conversation never becomes canonical Navi state. Local inference remains an optional privacy and availability route. Keys, credentials, tool enforcement, verification, storage, and deterministic operations remain local to the OS or its trusted extension. The OS sends only Co


WebGPU OS Overview

WebGPU OS Overview
What it is (and isn't)
Tier 1 today
Subsystems
Key documents (read-only sources)
Next steps

The composition layer that turns the engine, Plauna, AGI, and editor into a GPU-first, desktop-like OS that boots in a single browser tab. WebGPU OS Overview WebGPU OS ( ) is the composition layer that turns the engine, Plauna, AGI, and editor into a GPU first, desktop like OS that boots in a single browser tab . It provides a kernel, a shell, a signed package system, storage, drivers, and a runtime app catalog. Composition, not forking: the OS consumes , , , and as libraries. Fixes go upstream, not into the glue layer. (Source: §4.) What it is (and isn't) Is: a secure, GPU accelerated app platform with a web native developer experience — closer to OS.js + WebContainers + WASI than to a native game launcher. Isn't: a Steam class native game platform. Browser sandboxing rules out native overlays/input. (Source: §1.) Tier 1 today The current implementation is Tier 1 — browser resident . Tier 2 (Rust + Wasmtime/WASI host wrapping Dawn/wgpu) is a documented migration path; Tier 3 (native microkernel) is research only. See Architecture Overview for the tier framing and the stable Tier 2 migration contract. Subsystems Subsystem Path Purpose Kernel syscalls, scheduling, GPU mediation, trust, permissions, theming, surfaces, logging, FS Shell desktop, taskbar, start menu, windows, dialogs, notifications Packages build/sign/verify/install/update, capability map Storage virtual FS over OPFS/IndexedDB/cache/mounts, per app sandbox Drivers audio, crypto, net, profile, web surface Browser bridge / extension , native browser integration + adblock relay Apps 35 runtime discovered apps (see App Catalog) AppForge deterministic part registry, tags, services, context graph, commands, layouts, blueprints, packages, timeline, lenses, starter packs, and builder Key documents (read only


WebGPU OS Overview

part registry, tags, services, context graph, commands, layouts, blueprints, packages, timeline, lenses, starter packs, and builder Key documents (read only sources) — asset inventory, tiers, folder layout, security model. — phased delivery plan. — source research. — , , , . AppForge Contracts — modular public contracts layered over the current kernel, package, permission, app, and Plauna systems. Next steps Architecture — kernel, shell, packages, storage. AppForge Contracts — deterministic registry, assembly, context, layout, package export, timeline, lens, pack, and builder contracts. Getting Started — boot and build an app. App Catalog — every shipped app. WebGPU OS API Reference — generated from , , , , .


Particle Realms Studio

Particle Realms Studio
Studio workspaces
Recipe-backed demo catalog
Versioned Studio projects
Project API example
Typed recipe graph
GPU runtime paths
Bounded views and measured evidence
Legacy Twin compatibility boundary
Causal and durable persistence
Current limitations
See also

Current workspaces, project schema, native GPU path, evidence boundaries, persistence, and recovery behavior in Particle Realms Studio. Particle Realms Studio Particle Realms Studio is the WebGPU OS runtime for running, tuning, validating, and inspecting recipe built particle simulations. The portable project and typed recipe formats are shared authoring contracts: Paint Studio owns brush driven construction, while the developing RealmForge owns the reusable node/part builder. Particle Realms consumes those recipes and forms its demos through the same project path. The interface does not treat a visual preview as calibrated or scientifically validated output. Studio workspaces The shell exposes six keyboard accessible workspaces. Arrow keys move among workspace tabs, status updates use an ARIA live region, and the tuning drawer opens only from the explicit Tuning action or keyboard shortcut. (Source: ) Workspace Current behavior Truth boundary Discover Searches and filters 40 recipe backed demos with distinct animated previews, tracks favorites and recent demos, and provides Run Demo, Build from Recipe, and Inspect Recipe Graph actions. Every demo creates a normal project and typed recipe graph through the same public authoring path. Create Provides the current compatibility scene workbench and bounded top, density, velocity, and history projections from one native sample. New brush based construction belongs in Paint Studio. Secondary views are Canvas 2D projections of one bounded readback, not independent solver runs or validated engineering fields. Recipe Builds the portable typed graph visually: add/remove parts, connect compatible sockets, drag nodes, tune parameters, inspect diagnostics, and view a compact measured preview. RealmForge remains the intended reusable


Particle Realms Studio

connect compatible sockets, drag nodes, tune parameters, inspect diagnostics, and view a compact measured preview. RealmForge remains the intended reusable cross product node/part authoring owner as it matures. The embedded preview is a bounded projection of native readback, not a second solver. Only documented ParticleApp bindings execute; unsupported node families remain authored plan intent. Simulate Hosts the live canvas, playback, camera, interaction, an explicit tuning drawer, and an automatic particle population targeting 60 FPS. The reported backend identifies the active native, custom WGSL, or recovery path. Population is bounded only by the active runtime/device safety contract, not a user configurable cap. Analyze Displays accepted measured sensor and runtime series and exports them as CSV or JSON with provenance. Missing measurements and stage attribution remain absent. The Studio does not synthesize them. Compare Captures explicit settings snapshots and compares compatible measured and imported external series. A settings snapshot is not a second simulation. External data does not automatically validate the preview. Create, Recipe, Analyze, and Compare are coordinated by . It edits versioned sidecars and displays supplied runtime measurements, but it does not step a solver or invent sensor values. Legacy Artist and Twin sidecar fields remain readable in project v2 so older documents round trip without data loss, but they are not current workspaces. (Source: ) Recipe backed demo catalog The catalog contains 40 stable demos across Cosmic, Fields, Matter, Life, and Events. Running a demo creates a fresh project with a canonical typed recipe; building from it creates an editable remix through the same project factory. Every source preset uses one of two


Particle Realms Studio

a fresh project with a canonical typed recipe; building from it creates an editable remix through the same project factory. Every source preset uses one of two classifications: or . Each record also declares tags, difficulty, fidelity, macro controls, known limitations, and native migration metadata. (Source: ) Category Presets Cosmic Spiral Galaxy, Orbital Clusters, Supernova Shell, Black Hole Accretion, Comet Storm, Planetary Rings, Pulsar Jets, Globular Star Cluster Fields Quantum Vortex, Curl Noise Nebula, Magnetosphere, Aurora Curtains, Tornado Field, Lightning Cage, Solar Wind Stream, Gravity Lens, Magnetic Reconnection, Vector Weave Matter Thermal Fountain, Reaction Chamber, Cohesive Fluid, Molecular Latti


Particle Recipe Schema

Particle Recipe Schema
Related schema family
Module boundary
Graph document
Validation and compilation
Change impact
Current runtime bindings
Direct-control synchronization
Editing and migration
Capability boundary
See also

Canonical recipe graph, execution plan, runtime bindings, validation, and migration contracts. Particle Recipe Schema Particle recipes use the strict JSON schema version 1. The graph is an authored, typed description. Compilation produces a deterministic version 1; the plan is not itself a general purpose runtime. (Source: ) This page is for app developers and preset authors who create, inspect, or integrate current recipe documents. Related schema family The current repository uses a family of bounded documents rather than the design pack's proposed monolithic file: Document Current schema/version Persisted project aggregate , version 2 Immutable built in preset , version 1 Recipe graph , version 1 Compiled plan description , version 1 Scene sidecar , version 1 View sidecar , version 1 Artist sidecar , version 1 Compare sidecar , version 1 Sensor definition/sample / Twin project configuration , version 1 External study , version 1 (Sources: , , , , , ) Project v2 is the save/load envelope. Its exact top level fields are , , , , , , , , , , , , , , , , , and . Unknown v2 fields fail validation. Runtime settings are limited to the canonical mode, palette preset, interaction, count, force, size, exposure, pause, camera, trails, bloom, orbit, brush, gravity, drag, turbulence, cohesion, temperature, reaction, charge, and seed keys declared by . (Source: ) Module boundary owns cycle free preset construction, setting normalization, seed normalization, and deterministic project hashing. may consume those primitives but never imports the project aggregate. then composes both layers into the strict project v2 envelope. This dependency direction is required by the classic release bundler, whose eager named import snapshots cannot emulate ES module live bindings across a cycle.


Particle Recipe Schema

This dependency direction is required by the classic release bundler, whose eager named import snapshots cannot emulate ES module live bindings across a cycle. Project/graph sidecar helpers are exported by : , , , and . Callers that previously imported these four helpers from must update only the module path; their document contracts are unchanged. (Sources: , ) Graph document The normalized document contains schema and version identifiers, graph identity and revision, metadata and provenance, a seed, nodes, edges, and extensions. Node and edge IDs are stable and serialization is canonical even when input arrays arrive in a different order. A graph is limited to 2 MiB, 512 nodes, and 2,048 edges. Unknown graph, node, port, and edge fields are rejected by strict validation. (Source: ) The supported node families are: Project/Metadata, World/Units, Domain/Coordinates, Geometry, and Discretization. Boundary, Material, Substance, Emitter, Initial Condition, Field, Force, Solver, Coupling, Constraint, and Physics Body. Sensor, Reduction, Visualizer, Camera, View Layout, Timeline, Audio Input, Audio Graph/Patch, Telemetry Input, Data Transform, and Alert/Rule. External Study and Export/Output. The type system includes , , , , , , , , , , , , , , , , , , , , , , , , , , and . (Source: ) Validation and compilation Validation checks the schema and version, identifiers, limits, registered node types, port names, edge direction and type compatibility, input cardinality, required inputs, cycles, and declared subsystem availability. Compilation only runs for a valid graph and produces a deterministic topological step list, required subsystem list, output bindings, source graph snapshot, graph hash, signature, and aggregate change impact. The plan validator can independently confirm


Particle Recipe Schema

subsystem list, output bindings, source graph snapshot, graph hash, signature, and aggregate change impact. The plan validator can independently confirm that output against its source graph. (Source: ) If a current graph is invalid, the compiler may return a separately validated previous plan marked stale. An invalid previous plan is ignored. does not apply invalid authored settings to the running simulation. (Sources: , ) Change impact Every node declares one of these impacts, ordered from least to most invasive: Impact Runtime meaning No runtime mutation is required. The change is retained as authored metadata. Mapped live settings may be updated without rebuilding resources. Size dependent resources may


Particle Studio Architecture

Particle Studio Architecture
Dynamic population controller
Runtime layers
Canonical project state
Recipe-to-runtime seam
Visual Recipe Builder state boundary
GPU and recovery paths
Evidence architecture
Persistence and concurrency
Capability boundary
See also

Runtime, authoring, evidence, persistence, and recovery architecture for Particle Realms Studio. Particle Studio Architecture Particle Realms Studio is a WebGPU OS application, not a separate native desktop editor. owns its lifecycle and composes the Studio shell, versioned project, GPU runtime, evidence stores, and OS persistence services. The current product exposes Discover, Create, Recipe, Simulate, Analyze, and Compare. Simulate is the default/fallback workspace and keeps its tuning drawer closed until explicitly requested. (Sources: , ) Authoring ownership is deliberately outside the runtime app. Paint Studio owns brush driven simulation construction, and RealmForge is the developing home of the reusable node/part recipe builder. Particle Realms retains portable recipe inspection and safe parameter tuning so one document can be run, measured, compared, and promoted into a built in demo without a private second format. This page is for app and engine developers who need the current ownership, data flow, and integration boundaries. Dynamic population controller targets 60 FPS using a settled mean of measured RAF cadence. Sustained pressure reduces particle count multiplicatively; sustained headroom grows it conservatively. A deadband prevents oscillation, a cooldown accounts for GPU reallocation cost, and workgroup aligned quantization keeps dispatch sizes stable. Decisions stop at the active device/runtime safety maximum. That maximum is not exposed as a preference or user cap. applies decisions only while Simulate is visible, running, and GPU backed. Each accepted change updates the canonical count binding, reports the automatic population, and performs one resource reallocation. Paused, hidden, authoring, fallback, and warm up samples cannot change population.


Particle Studio Architecture

reports the automatic population, and performs one resource reallocation. Paused, hidden, authoring, fallback, and warm up samples cannot change population. (Sources: , ) Runtime layers Text equivalent: the factory registers the app. creates the shell, selects a runtime, applies validated projects, advances the native or custom simulation, records measured runtime metrics, and coordinates save and recovery. The advanced controller edits project sidecars and renders evidence; it does not step a solver or open a live transport. (Sources: , , ) Canonical project state The persisted aggregate is version 2. It contains project identity and settings plus these versioned sidecars: Sidecar Responsibility Scene objects, view layout, comparison state, and compatibility only legacy artist data. Typed authored graph with stable IDs, ports, edges, and parameters. Provenance aware definitions for accepted measurements. Compatibility only disconnected safe data retained for lossless legacy project round trips. Bounded normalized CSV or JSON reference studies. Authored automatic/profile/target frame time intent. Project validation is strict, serialization is deterministic, and the complete document is capped at 32 MiB. Runtime samples, credentials, live connector state, and transient memory pressure are not canonical project truth. (Source: ) The project dependency graph is deliberately acyclic: . The core layer owns settings, seeds, hashing, and immutable built in presets; the aggregate layer owns project/graph sidecar composition. This ordering preserves the same public project behavior in raw ES modules and the eager classic release bundle. (Sources: , ) Recipe to runtime seam validates and compiles a deterministic execution plan description. is the current execution seam. It


Particle Studio Architecture

release bundle. (Sources: , ) Recipe to runtime seam validates and compiles a deterministic execution plan description. is the current execution seam. It applies the graph seed and the mapped count, force, temperature, point size, exposure, camera distance, solver mode, fixed step, and substep values to . Direct Quick and Standard control changes synchronize those named default graph nodes while preserving custom topology, IDs, provenance, and unsupported authored nodes. (Sources: , , ) An invalid graph does not replace the live project or settings. The graph compiler and Recipe workspace can report authored diagnostics, while retains the last validated runtime configuration. Unsupported solver types and node


Particle Studio External Studies

Particle Studio External Studies
Schema and limits
CSV format
JSON format
Provenance and validation levels
Import workflow
Comparison semantics
Security and interpretation
Capability boundary
See also

Import, provenance, comparison, and interpretation contracts for external Particle Studio data. Particle Studio External Studies Particle Studio can retain and compare bounded local scalar series studies in CSV or JSON. An external study is reference evidence with its own provenance; it never automatically validates the active native or custom preview. (Source: ) This page is for users and reviewers who prepare and interpret local external study imports. Schema and limits The canonical schema is version 1. A project may retain up to eight studies in canonical ID order. Each imported document is limited to 4 MiB, each study to 64 series, and each series to 100,000 finite samples. (Sources: , ) Field Purpose , Stable study identity and display name. , Producer provenance. Declared spatial frame or . Optional quantity to unit metadata. , , Origin and review provenance. , , , or . , Explicit interpretation constraints. Canonical import timestamp. Quantity, unit, and finite scalar samples. Always . Every series has a stable ID, label, quantity, unit, and samples. A sample has an index, numeric time, finite value, optional canonical timestamp, and quality label. (Source: ) CSV format CSV requires one header row and at least one data row. A or column is recognized case insensitively. Other headers may declare a unit as ; without brackets, the unit defaults to . Quoted fields and doubled quotes are supported. Non finite value cells are skipped. (Source: ) Numeric time values are stored as time. Non numeric time text is parsed as a timestamp when possible. If there is no time column, row order supplies time indices. CSV import options may add the study name, solver/version, coordinate system, source, author, review metadata, assumptions, and limitations. JSON format JSON may


Particle Studio External Studies

import options may add the study name, solver/version, coordinate system, source, author, review metadata, assumptions, and limitations. JSON format JSON may already use the canonical schema. For compatible object input without the schema marker, the parser supplies the current schema/version and forces before validation. The document must contain at least one series with at least one finite sample. Serialization validates the study before writing canonical JSON. (Source: ) Provenance and validation levels Validation requires an explicit supported level and rejects any claim that the study validates the native preview. A study marked must include a reviewer, a named solver, and a solver version. This validates the imported record's minimum provenance requirements only; it does not review equations, mesh, convergence, calibration, or compatibility with the Studio model. (Source: ) An unspecified coordinate system produces a warning and disables any spatial overlay interpretation. The current UI performs time series comparison only, so even a specified coordinate system does not activate a 3D overlay. Import workflow 1. In Compare , select a local CSV or JSON document. 2. Studio parses and normalizes the document within the import bounds. 3. Validation errors stop the import; warnings remain visible context. 4. A study with the same ID replaces the retained copy; otherwise it is added subject to the eight study project limit. 5. Saving the project persists the normalized study as project v2 content. The UI labels every retained study as not validating the native preview and logs the local import. (Sources: , ) Comparison semantics The Compare workspace selects a measured sensor series only when its quantity and unit exactly match an external series. compares up to the


Particle Studio External Studies

semantics The Compare workspace selects a measured sensor series only when its quantity and unit exactly match an external series. compares up to the shorter series length by array index and reports baseline, external, delta, and ratio. A zero baseline produces a null ratio. The helper reports whether units are equal, but callers must enforce compatibility; the Studio UI does so before comparison. (Sources: , ) This comparison does not interpolate time, align timestamps, convert units, transform coordinate systems, propagate uncertainty, or compute spatial error norms. Array index alignment is suitable only when the reviewer has established that the records correspond. Security and interpretation Imports


Particle Studio Fidelity and Validation

Particle Studio Fidelity and Validation
Interpretation labels
Runtime-path fidelity
Evidence classes
External-study boundary
Reproducible comparison record
Determinism boundary
Engineering-use gate
Capability boundary
See also

Interpretation, evidence, comparison, and validation boundaries for Particle Realms Studio. Particle Studio Fidelity and Validation Particle Realms Studio separates an attractive interactive result from a validated result. A functioning GPU path, deterministic seed, high particle count, smooth frame rate, or imported reference file does not establish physical accuracy. Claims must be supported by the implemented model and explicit evidence. (Sources: , ) This page is for users and reviewers who decide what a Studio result can and cannot support. Interpretation labels Label or state Meaning in the current product The preset prioritizes composition and motion. Physical names may be thematic. The preset demonstrates a concept with explicit approximations and omissions. A compatible device may use mapped engine systems; another path remains available. A relevant engine system exists, but the preset is not wired to it in the app. External Imported data has no review claim. External Data is retained as a comparison reference. External Review is asserted in the imported provenance. External The study supplies reviewer, solver, and solver version provenance. It still does not validate Studio automatically. (Sources: , ) Runtime path fidelity The native path and custom WGSL path are different implementations. Seven preset modes can map to native engine systems on compatible devices. Other modes use the custom visual model. The Canvas 2D path is a generic recovery preview. Backend status therefore belongs in every reproducibility record. (Sources: , ) Native rendering binds the engine world's position buffer directly, while CPU side views use a bounded readback prefix. The direct renderer proves that the displayed positions came from the native world; it does not prove that the


Particle Studio Fidelity and Validation

CPU side views use a bounded readback prefix. The direct renderer proves that the displayed positions came from the native world; it does not prove that the world is calibrated. The Create secondary views are projections of one compact sample, not full resolution solution fields. (Sources: , , ) Evidence classes Keep these records distinct: Evidence Required provenance Permitted conclusion Runtime telemetry Supplied timestamp and measured metric Runtime behavior for the recorded session. Sensor sample Sensor ID, quantity, unit, source ID, sequence, timestamp, quality, and origin The accepted measurement represented by that definition. Compact reduction Explicit finite values and, for integrals, explicit weights The stated reduction over the supplied compact input. External study Source, author, solver/version, coordinate system, units, review metadata, assumptions, and limitations as applicable Comparison to that imported reference. Missing measurements remain missing. Profiler stages remain empty until the host supplies them. Compatibility only prediction modules are not part of the current six workspace Studio. (Sources: , , ) External study boundary Every normalized study sets to ; validation rejects any other value. A study marked must name a reviewer, solver, and solver version, but this describes the study's provenance only. An unspecified coordinate system disables spatial overlay claims. The current Compare workspace matches measured and external series by exact quantity and unit and displays an index aligned comparison. (Sources: , ) The current implementation does not perform time interpolation, coordinate registration, mesh conversion, uncertainty propagation, norm computation, full field comparison, or automatic pass/fail acceptance. Do those operations in a


Particle Studio Fidelity and Validation

registration, mesh conversion, uncertainty propagation, norm computation, full field comparison, or automatic pass/fail acceptance. Do those operations in a reviewed external workflow before claiming validation. Reproducible comparison record For a meaningful review, retain at least: project JSON, project schema version, preset ID, classification, and provenance; recipe graph and compiled graph signature; seed, supported mapped recipe settings, fixed step, and substeps; selected backend, browser/device information, granted limits, and quality profile; sensor definitions and exported samples with units and quality; external study source, solver/version, coordinate system, assumptions, limitations, and revi


Particle Studio Integration Map

Particle Studio Integration Map
Active Studio path
Active modules
Project and authoring contracts
Recipe graph boundary
GPU device and limit contract
Native lifecycle
Active native mappings
Readback and evidence flow
Causal state and sandbox storage
Remaining integration boundaries
See also

Verified source map for Particle Realms Studio, including project v2, native ParticleSimWorld integration, advanced workspaces, evidence boundaries, and OS services. Particle Studio Integration Map This map shows the active Particle Realms Studio paths and the boundaries that remain host or engine integration work. It distinguishes direct GPU state, bounded readback, measured evidence, authored configuration, external data, and predictions. Active Studio path Text equivalent: the app factory mounts . The app owns the shell, project, persistence, telemetry, advanced controller, and runtime selection. Eligible modes create and step an engine ; the native renderer binds its borrowed position buffer directly. Other WebGPU cases use the custom WGSL model, while Canvas 2D is a generic recovery preview. Active modules Module Main symbols Current responsibility Factory registration Registers the Particle Sandbox app for WebGPU OS. , custom WGSL exports Owns lifecycle, runtime selection, native stepping, custom simulation, interaction, reporting, persistence snapshots, and recovery. , Builds accessible Discover, Create, Recipe, Simulate, Analyze, and Compare workspaces and owns automatic tuning visibility. Coordinates the four visible authoring/evidence workspaces without stepping a solver. , Defines the 40 classified presets, catalog identities, custom solver family IDs, animated preview compositions, limitations, macros, and migration metadata. Settings, seed, hash, and immutable preset functions Provides the cycle free project primitives shared by graph and aggregate layers. Project create, migrate, validate, remix, serialize, deserialize, and graph sidecar functions Defines the strict project v2 aggregate, composes recipe graphs, and re exports the core preset API. Scene,


Particle Studio Integration Map

serialize, deserialize, and graph sidecar functions Defines the strict project v2 aggregate, composes recipe graphs, and re exports the core preset API. Scene, view, artist, and comparison normalizers and edit helpers Defines versioned Studio authoring sidecars embedded in project v2. Typed graph edit, validation, migration, serialization, impact, and compilation functions Defines recipe graph v1 and deterministic plan descriptions. It does not execute a plan. , Applies the validated ParticleApp subset of a plan and keeps direct controls synchronized with mapped graph nodes. , Maps seven project modes to audited systems and creates deterministic typed CPU seed state. Discovers native engine exports, validates granted limits, owns a , uploads state, steps systems, exposes borrowed buffers, and performs bounded readback. Renders the borrowed native position buffer as additive LDR points without copying it into an app owned simulation buffer. , Produces bounded Canvas 2D projections and measured history from one runtime sample while preserving world space aspect ratio. Retains bounded measured runtime metrics without synthetic values. Sensor definition, sample, reduction, and runtime APIs Validates definitions and provenance bearing measured samples. Import, validation, comparison, and serialization APIs Parses bounded CSV/JSON studies and compares only compatible quantity/unit series. , Applies authored quality policy from observed frame windows and keeps unsupported attribution absent. , Retained internal compatibility module; it is not exposed as a current Studio workspace. Debounces complete workspace snapshots and writes through CSE and the sandbox, with legacy local storage as fallback. , , Wraps shared or dedicated devices, validates exact required limits, observes


Particle Studio Integration Map

and writes through CSE and the sandbox, with legacy local storage as fallback. , , Wraps shared or dedicated devices, validates exact required limits, observes loss, and respects device ownership. Project and authoring contracts The canonical project schema is version 2. It embeds , , , , , and authored beside the project's identity, provenance, seed, classification, tags, and normalized settings. Version 1 projects migrate deterministically, and legacy workspace v4 settings remain importable. (Source: ) Strict v2 validation rejects unknown project and settings fields. Sensor definitions and external studies receive stable ordering. Persisted Twin configuration rejects credential like keys and excludes runtime tr


Particle Studio Performance

Particle Studio Performance
Runtime tiers
Native eligibility and ceilings
GPU limits and ownership
Direct rendering and readback
Quality profiles
Measurements and attribution
Device loss and recovery
Performance report checklist
Capability boundary
See also

Runtime selection, resource ownership, bounded readback, adaptive quality, and measurement guidance. Particle Studio Performance Particle Realms Studio chooses a runtime from granted browser and device capabilities. Particle count alone is not a performance guarantee, and no single frame rate claim applies across modes, GPUs, browsers, display sizes, or quality profiles. Report measured results together with their runtime path and configuration. (Sources: , ) This page is for developers and reviewers who tune Studio or publish measured performance results. Runtime tiers Tier Selection Performance boundary Native engine Mapped mode, eligible count, required exports, known device limits, and at least ten storage buffers per shader stage. Steps systems and renders the borrowed native position buffer. Custom WGSL WebGPU is available but the native mapping, eligibility, or native limit is unavailable. Runs the preset's lightweight app model with an app owned HDR pipeline. Canvas 2D recovery WebGPU initialization or recovery is unavailable. Draws 5,000 generic points for continuity; the selected model is inactive. The app first considers an OS shared GPU device. If native eligibility needs a limit the shared device lacks, it may request a dedicated device for the app's WebGPU fallback. A shared device is never destroyed by the app. (Sources: , ) Native eligibility and ceilings The seven native mapped modes are Galaxy and Orbital Clusters ( ), Flocking Ribbons ( ), Cohesive Fluid ( ), Reaction Chamber ( ), Magnetosphere ( ), and Molecular Lattice ( ). Native CPU seed state creation has a one million particle hard bound. N body profiles declare a 100,000 state bound, while the interactive app further caps Galaxy and Orbital Clusters native selection at 10,000 because their


Particle Studio Performance

N body profiles declare a 100,000 state bound, while the interactive app further caps Galaxy and Orbital Clusters native selection at 10,000 because their current pairwise solve is expensive. All bounds remain subject to the granted device limits. (Sources: , ) Other catalog modes are not native connected and use the custom WGSL path. The catalog macro permits counts up to ten million, but project normalization and the tier selector clamp to the active runtime's recommended maximum. (Sources: , ) GPU limits and ownership derives its hard maximum from granted storage buffer, buffer size, dispatch, and workgroup limits and requires . Initialization fails closed when required native exports, limits, buffers, or configuration are invalid. (Source: ) The native runtime owns its and readback staging buffers. The native renderer owns its pipelines, bind groups, and uniforms but borrows the world's position buffer. Teardown drains pending readback, destroys owned world and renderer resources, and leaves a borrowed shared alive. (Sources: , ) Direct rendering and readback Native presentation binds one 16 byte position record per particle and renders additive LDR billboards without copying positions into a second app simulation buffer. The renderer reports no HDR or trail capability. The custom path instead stores 48 bytes of particle state and uses the app's HDR compute/render/tone pipeline. (Sources: , ) Advanced workspaces request a native sample no more often than every 500 ms in Create, Analyze, or Compare. Each automatic sample is capped at 4,096 particles; each requested vector stream allocates exactly count × 16 bytes. The result is labeled and reports truncation. This is bounded inspection, not full particle state readback. (Sources: , ) Quality profiles Profile View


Particle Studio Performance

bytes. The result is labeled and reports truncation. This is bounded inspection, not full particle state readback. (Sources: , ) Quality profiles Profile View scale View rate Max secondary views Sensor rate scale Trails Post quality : : : : : Economy 0.5 5 Hz 1 0.5 off 0.35 Interactive 0.7 15 Hz 3 1 on 0.7 High 1 30 Hz 5 1 on 1 Cinematic 1 60 Hz 7 1 on 1.25 The current advanced UI applies the maximum secondary view policy and optional view quality behavior. Not every profile field controls every native/custom solver or renderer feature yet. In particular, the native renderer reports no trails even when the authored profile permits them. (Sources: , , ) Automatic quality uses a 45 sample frame window by default,


Particle Studio Preset Authoring

Particle Studio Preset Authoring
Required preset record
Current catalog
Macro controls
Defaults and reproducibility
Model and limitation text
Native-engine status
Recipe and project generation
Author review checklist
Capability boundary
See also

Contracts and review guidance for built-in Particle Realms Studio presets. Particle Studio Preset Authoring Particle Realms presets are curated source records in . The catalog currently contains 40 immutable built in presets. It is not a user installable preset marketplace, and importing a project does not register a new global preset. (Sources: , ) This guide is for developers who maintain the built in catalog and its project and recipe defaults. Required preset record Each entry supplies: Field Contract Stable, versioned catalog identity. and Short and display names. Stable numeric catalog identity used by projects and discovery. Numeric custom solver family ID. Variants may share an audited solver family, while a dedicated solver uses its own ID. Named animated Discover composition. It must visually distinguish the preset rather than reuse a generic particle cloud. One of , , , , or . Exactly or . Search and discovery labels. and User facing complexity and model fidelity description. , , and Concise account of the behavior that is actually present. Explicit omissions and interpretation limits. Keys from the shared macro registry. Honest native engine connection status, systems, and note. Complete normalized ParticleApp starting settings. freezes tags, limitations, defaults, and resolved macro descriptors. Unknown macro keys throw during module evaluation. Keep IDs and values stable after release; project provenance depends on them. (Source: ) Current catalog Category Built in presets Cosmic Spiral Galaxy, Orbital Clusters, Supernova Shell, Black Hole Accretion, Comet Storm, Planetary Rings, Pulsar Jets, Globular Star Cluster Fields Quantum Vortex, Curl Noise Nebula, Magnetosphere, Aurora Curtains, Tornado Field, Lightning Cage, Solar Wind Stream, Gravity Lens,


Particle Studio Preset Authoring

Globular Star Cluster Fields Quantum Vortex, Curl Noise Nebula, Magnetosphere, Aurora Curtains, Tornado Field, Lightning Cage, Solar Wind Stream, Gravity Lens, Magnetic Reconnection, Vector Weave Matter Thermal Fountain, Reaction Chamber, Cohesive Fluid, Molecular Lattice, Ocean Waves, Waterfall Canyon, Lava Flow, Crystal Growth, Smoke Chamber Life Strange Attractor, Flocking Ribbons, Jellyfish Bloom, Firefly Swarm, Mycelium Growth, Plankton Current, Neural Pulse Web Events Event Fireworks, Meteor Shower, Rainstorm, Snow Globe, Sandstorm Wall, Geyser Burst The classification is intentionally conservative and declared independently on every record. A title alone must never imply a solver that the model does not implement. For example, Quantum Vortex explicitly states that its name is thematic rather than a quantum fluid solve, while Ocean Waves identifies its layered procedural wave sheet and its non CFD limitation. (Source: ) Macro controls Authors select controls from a shared registry rather than defining ad hoc UI ranges inside a preset: Key Range Unit 1,000..10,000,000, integer step 1,000 particles 0.1..4 relative 0.35..8 px 0.35..3 EV 3..3 relative 0.94..1 ratio 0..4 relative 0..4 relative 50..15,000 K 0..3 relative 3..3 relative 0.7..0.98 ratio 0..2 relative 0..1 speed Use the shared label, type, minimum, maximum, step, and unit exactly. The runtime normalizer remains authoritative and may clamp against device or app limits. A physical looking unit on one control does not make the entire model calibrated. (Sources: , ) Defaults and reproducibility Defaults should form a complete, finite settings patch accepted by the project normalizer. Preserve a fixed seed in derived project fixtures when a visual or behavioral comparison must be repeatable. Count affects


Particle Studio Preset Authoring

accepted by the project normalizer. Preserve a fixed seed in derived project fixtures when a visual or behavioral comparison must be repeatable. Count affects allocation and native eligibility; do not use a large default merely to make the preset look dense. Camera distance, palette, exposure, size, and optional trails should produce a legible first frame without hiding the model's limitations. (Sources: , ) Model and limitation text A useful preset description answers four separate questions: 1. What algorithm or approximation moves the particles? 2. Which controls have meaningful effects in that implementation? 3. Which familiar physical process is only suggested visually? 4. Which conclusions must not be drawn from the


Particle Studio Telemetry

Particle Studio Telemetry
Runtime telemetry
Sensor definitions
Sensor samples and provenance
Compact reductions
Analyze and export
Stage attribution and adaptive quality
Legacy Twin runtime compatibility
Capability boundary
See also

Runtime metrics, sensor evidence, profiling, and legacy compatibility contracts in Particle Realms Studio. Particle Studio Telemetry Particle Realms Studio accepts measured values; it does not generate missing measurements. Runtime metrics, sensor evidence, and external references use separate contracts so derived values cannot silently become canonical truth. (Sources: , ) This page is for integrators and users who ingest, export, or interpret current Studio measurements. Runtime telemetry accepts a sample only when it has a finite, non negative timestamp and at least one finite, non negative supported metric. Its default history is 120 samples; configured limits are clamped to 1..10,000. Integer metrics are rounded and absent metrics remain absent. (Source: ) Metric Meaning Value handling Observed frames per second Finite, non negative number. Observed frame duration Finite, non negative milliseconds. Measured queue submit duration Recorded only when supplied. Measured GPU duration Recorded only when supplied. Active particle count Rounded non negative integer. Allocated particle bytes Rounded non negative integer. Each metric can be exported as timestamp/value points. Summaries report count, latest, minimum, maximum, average, and p95; an unsampled metric has a summary. Studio records an app runtime sample at an approximately 500 ms cadence when those observations are available. (Sources: , ) Sensor definitions Sensor definitions use schema . A definition has a stable ID, sensor type, quantity, unit, source ID, sampling rate, reduction, value type, and stale policy. The runtime supports up to 4,096 definitions (default 256) and 1..10,000 samples per sensor (default 600). (Source: ) Contract Supported values Sensor type , , , , , , , , , , Reduction , , , , , , , , ,


Particle Studio Telemetry

(default 256) and 1..10,000 samples per sensor (default 600). (Source: ) Contract Supported values Sensor type , , , , , , , , , , Reduction , , , , , , , , , Value type , , , , , Data quality , , , , , , Sampling rates are bounded to 0.001..1,000 Hz. Validation checks that the selected reduction and value type are compatible and that IDs remain unique. (Source: ) Sensor samples and provenance Samples use schema . Validation requires the sample's sensor ID, quantity, unit, and source provenance to match its definition. Sequence and timestamp must remain monotonic. Normal samples carry a value; only and quality permit a null value. The origin identifies an ingested or compact reduction source. (Source: ) Staleness is calculated from the latest timestamp and the definition's stale policy. It does not rewrite the recorded sample's original quality or value. Rejected samples increment a diagnostic count rather than being repaired into apparently valid measurements. Compact reductions The reducer accepts at most 65,536 explicit finite values. It implements the supported scalar reductions over that supplied input. An integral requires explicit weights; the module does not guess cell size, area, volume, or time spacing. Histogram output is bounded and explicit. (Source: ) This is a data contract and compact reduction seam. It does not locate probes in a solver, read arbitrary GPU fields, schedule a GPU reduction pass, or calibrate a sensor. A host must supply the measured compact values and their provenance. Analyze and export The Analyze workspace displays registered definitions, accepted series, latest values, quality, origin, rejection count, and bounded diagnostics. JSON and CSV exports are sorted and retain provenance. Runtime metrics are projected into predefined


Particle Studio Telemetry

quality, origin, rejection count, and bounded diagnostics. JSON and CSV exports are sorted and retain provenance. Runtime metrics are projected into predefined performance sensor samples only when the corresponding metric was supplied. Missing sources remain empty. (Sources: , ) Stage attribution and adaptive quality accepts only explicitly supplied timing for , , , , , and stages. Analyze shows an empty row until a host supplies that stage; it does not divide frame time heuristically. The quality governor separately uses observed windows and authored policy to select Economy, Interactive, High, or Cinematic behavior. (Sources: , ) Legacy Twin runtime compatibility can maintain an append only measured truth history fr


Particle Studio Test Plan

Particle Studio Test Plan
Evidence levels
Automated inventory
Core contract gate
Recipe-runtime gate
GPU and lifecycle matrix
Manual UX and accessibility gate
Performance and resource gate
Master Prompt acceptance traceability
Release gates
Known gaps
Capability boundary
See also

Automated, real-device, manual, performance, and release verification for Particle Realms Studio. Particle Studio Test Plan This plan verifies current repository behavior and records gaps against the broader Simulation Studio design pack. Passing structural and runtime tests does not establish scientific validity or performance on hardware that was not measured. This page is for developers and release reviewers who need repeatable coverage and explicit acceptance test gaps. Evidence levels Level Evidence Contract Pure validation, normalization, migration, serialization, and deterministic helper checks. Browser integration DOM, controller, persistence seam, and fallback behavior in a served ES module page. Real WebGPU Pipeline creation or real engine world execution on an actual granted . Manual UX Keyboard, focus, responsive layout, warning semantics, reduced motion, and recovery observation. Scientific validation Independent equation, convergence, calibration, uncertainty, and reference review. Not supplied by current tests. All browser pages must be served over HTTP. Start the repository server with the repository command, then open the relevant test route under . (Source: ) Automated inventory Suite Current scope 29 project v2 creation, deterministic serialization, migration, strict field, Studio sidecar, sensor, Twin, external study, quality, and round trip cases. 28 graph registry, type, topology, validation, deterministic compile, impact, migration, last valid, runtime adapter, direct sync, and observability cases. 36 checks covering the four current advanced workspaces, visual Recipe add/connect/remove/recovery behavior, measured preview, compatibility only Artist/Twin controller contracts, canonical edits, bounded samples, external import, overflow, and


Particle Studio Test Plan

behavior, measured preview, compatibility only Artist/Twin controller contracts, canonical edits, bounded samples, external import, overflow, and ownership. Browser harness for sensor and Twin runtime unit modules. 20 advanced domain checks including automatic count pressure, headroom, quantization, and hardware ceiling decisions. Focused home camera, stratified readback, projection aspect ratio, render, and sample provenance checks. Definition, sample, quality, reduction, export, and provenance contracts. Connector state, append only truth, replay, branches, predictions, and alerts. Deterministic native state generation and mapped mode contracts. Native discovery, limits, world lifecycle, stepping, bounded readback, and teardown. Borrowed buffer validation, rendering, ownership, and teardown. Engine world regressions used by the app's native path. 22 real device checks covering native selection, closed by default tuning, automatic population UI and reallocation, recipe mapping, invalid plan retention, fixed clock, readback, layout, and unmount ownership. Fourteen real WebGPU render/compute pipeline compile checks for exported particle shaders. (Sources: the listed test files.) Core contract gate Run the project, recipe, sensor, and compatibility Twin suites and require zero failures. Confirm these negative paths explicitly: unknown project v2, settings, Studio sidecar, graph, node, port, and edge fields fail closed; future project and graph versions fail closed; project v1, graph v0, and legacy workspace v4 compatible inputs migrate deterministically; duplicate IDs, cycles, incompatible ports, cardinality violations, missing required inputs, and unavailable required subsystems report exact errors; a tampered previous plan is rejected and an invalid current graph cannot


Particle Studio Test Plan

missing required inputs, and unavailable required subsystems report exact errors; a tampered previous plan is rejected and an invalid current graph cannot replace the live settings; credentials and Twin runtime truth cannot enter the project document; external studies cannot claim to validate the native preview; missing measurements remain missing and integral reduction requires weights. (Sources: , , , ) Recipe runtime gate Verify both pure and app integrated behavior: 1. The compiled plan validates against its source graph and has a stable signature and topological order. 2. Seed, count, force, temperature, point size, exposure, camera distance, supported solver type, fixed step, and substeps appl


Particle Studio User Guide

Particle Studio User Guide
Before opening Studio
Choose and run a recipe demo
Tune the live simulation
Choose a simulation view
Author the scene in Create
Edit a recipe
Analyze measured data
Compare projects and external data
Compatibility-only legacy sidecars
Choose a quality profile
Save, export, import, and recover
Keyboard and accessibility behavior
Troubleshooting checklist
Capability boundary
See also

Task-oriented guide to the current Particle Realms Studio workspaces and evidence boundaries. Particle Studio User Guide Particle Realms Studio is the Particle Sandbox application inside WebGPU OS. It provides six workspaces for selecting, running, safely tuning, inspecting, and comparing particle projects. Full brush construction belongs in Paint Studio; the reusable node/part builder belongs in the developing RealmForge. Particle Realms reads the same portable project and recipe documents they produce. Results are artistic or educational previews unless your own evidence and validation process establishes otherwise. (Sources: , ) This guide is for users who want to run and inspect current Studio projects without confusing authored previews with measured or validated evidence. Before opening Studio Run WebGPU OS over HTTP in a browser with WebGPU enabled for the native or custom GPU paths. The application can remain accessible in generic Canvas 2D recovery mode when WebGPU is unavailable, but that mode does not execute the selected model. Open Particle Sandbox from the WebGPU OS app catalog and check the backend label before interpreting the scene. (Sources: , ) Choose and run a recipe demo 1. Open Discover and filter the 40 built in recipe demos by category, tag, difficulty, or search text. 2. Read the demo's classification, model description, and limitations. 3. Use Run Demo to create a fresh normal project from its canonical recipe, or Build from Recipe to create an editable remix. Inspect Recipe Graph shows the actual typed graph used by the demo. 4. Simulate opens with the full canvas visible. Choose Tuning or press only when you want the advanced drawer. Favorites and recent choices are local convenience state. A preset labeled prioritizes composition;


Particle Studio User Guide

Tuning or press only when you want the advanced drawer. Favorites and recent choices are local convenience state. A preset labeled prioritizes composition; demonstrates a concept with stated limitations. Neither label means calibrated or certified. Each card has an animated composition specific preview, so an ocean, fountain, galaxy, flock, or storm is recognizable before the full runtime opens. (Sources: , ) Tune the live simulation The tuning drawer stays closed when Simulate becomes active. Open it with the toolbar action or , and close it with the drawer button, toolbar action, , or . Particle population is automatic. Studio samples delivered frame cadence, smooths several observations, and uses hysteresis plus a reallocation cooldown to move population toward a stable 60 FPS. The Simulate row shows the current automatic population but provides no count or cap input. The only ceiling is the current GPU/runtime safety contract; users do not configure it. Population changes rebuild size dependent resources. Other controls update the active configuration according to their declared impact. The active backend report identifies whether Studio is using the native engine path, the custom WGSL path, or the generic recovery preview. (Sources: , ) Direct controls synchronize the mapped nodes in the current recipe on save. That synchronization preserves custom graph topology and unsupported authored intent. It does not convert every recipe node into running engine state. (Source: ) Studio has three control detail levels. Quick shows Effect, automatic Particles, Force, and Size. Standard also shows Palette and Brush. Advanced keeps the Standard row. Changing detail level never opens the tuning drawer. The drawer groups the remaining current settings under Interaction, Dynamics,


Particle Studio User Guide

keeps the Standard row. Changing detail level never opens the tuning drawer. The drawer groups the remaining current settings under Interaction, Dynamics, Matter, and Presentation. Advanced is a broader settings surface, not a promise that every typed recipe node has a dedicated widget. (Source: ) Choose a simulation view The three buttons at the top center of Simulate select one authoritative perspective and two bounded inspection views: Perspective ( ) shows the live 3D renderer. Drag to orbit, use the mouse wheel to dolly, and choose Home camera to restore the complete camera authored for the selected preset. Changing presets also resolves a fresh complete home camera, so yaw or pitch from the previous prese


Modular Pinball Parts

Build counted spinner and drop-target objectives

Return drained balls through a physical machine

Build active rollover sockets, not decorative rings

Author the cabinet backbox and player display

Use Cinema Focus as a staged-ball presentation

How engine contributors and table authors define reusable pinball parts, register aliases, and assemble a table without coupling mechanisms to one layout. Modular Pinball Parts The pinball parts system turns each physical mechanism into a reusable, immutable part definition. This guide is for engine contributors who build parts and table authors who assemble those parts into a machine. Use one implementation for each reusable part type. Create left, right, upper, or themed variants as independent instances in a table definition. Do not duplicate the implementation into folders such as and . Use canonical pinball names Canonical names keep table definitions, editor tools, events, saves, and mods interoperable. Compatibility aliases accept familiar informal terms, but new code should use the canonical type. Informal term Canonical part Meaning flapper The current machine uses a spring return one way gate. A future route selecting mechanism should use a separate type. twanger The compatibility alias resolves to the current switch, coil, and rubber slingshot package. sensor A switch like input that reports contact, occupancy, position, or passage. bouncer A pop bumper applies an active kick. Passive restitution remains a collider surface property. launcher A manual, automatic, or combined ball launch mechanism. door A powered lock or routing barrier. Use for a passive one way flap. drain and A sensor detects the crossing. The trough owns ball inventory and serving. The alias resolves to the trough assembly. flipper The player controlled bat and its mechanical state. target A scoring target with a dedicated switch contract. drop target A rectangular switch backed target that moves below the playfield and resets through a coil. target bank A logical reference group for


Modular Pinball Parts

contract. drop target A rectangular switch backed target that moves below the playfield and resets through a coil. target bank A logical reference group for independent drop target IDs and a shared reset coil. spinner A freely rotating metal blade that reports one switch pulse per revolution. light An addressable playfield lamp or guidance insert. The public parts index keeps a narrow compatibility layer: Compatibility name Canonical name , , , , , , , remains canonical. The alias resolves to for compatibility, even though authors may use the word for other mechanisms. New table definitions should state the intended canonical type. (Source: .) Architecture and dependencies The modular path has four stages: owns the immutable authoring contract. resolves canonical types and aliases to factories. A table creates independent instances through those factories. validates and combines the instances into one frozen table contract. creates the mutable solver records, retaining a link to the authored owner. (Sources: , , , .) The Dimensional Foundry table is an assembly root, not a mechanism implementation. It supplies table metadata, ordered part instances, and the playfield level compatibility settings required by the current simulator. (Source: .) Target folder contract Keep shared contracts, registry behavior, assembly, reusable parts, and authored tables in separate folders: Each reusable part folder exposes its public factory through . The and folders are reusable electromechanical subcomponents used by mechanisms; the other folders define complete semantic parts. Slingshots compose a leaf switch and kick coil, pop bumpers compose a skirt switch and kick coil, targets compose a hit switch and optional powered assist or reset coil, flippers compose a power coil and end of


Modular Pinball Parts

bumpers compose a skirt switch and kick coil, targets compose a hit switch and optional powered assist or reset coil, flippers compose a power coil and end of stroke switch, and the trough composes entry and serve switches with an eject coil. A complex part may split physics, visuals, mechanics, wiring, or runtime support into focused sibling modules. Other subsystems should import the folder's public entry rather than its internal files. The shared definition accepts these concerns without forcing them into the table layout: Field Purpose Stable instance identity using lowercase words separated by underscores. Canonical reusable type in the form. Positive schema version. The default is . Additional names attached


Realm Network

Discovery, health, and bounded resources

Architecture, contracts, security boundaries, V3 compatibility, verification, and deployment policy for the Realm Network. Realm Network The Realm Network adds portable identity, immutable content, resumable links, semantic replication, offline branches, governance, bounded task exchange, and safe Realm discovery to the WebGPU OS. It builds on the existing Particle Network and keeps V1/V2 compatibility intact. The implementation is complete through the local Realm Network Alpha gates. The Raspberry Pi service is not deployed. Only the server owner performs that single physical cutover. (Source: .) Architecture Layer Responsibility Source OS ownership One owns network lifecycle; remains a compatibility adapter , Embedded endpoint One leader tab owns the backbone; resident, supernode, witness, and authority are roles on the same browser endpoint , App boundary syscalls expose feature state, contract metadata, verification, and Passport operations Protocol routing Exact versioned descriptors negotiate State Channel, chunk, carrier, and DHT traffic; unknown versions fail closed , Rollout control Versioned flags keep experimental Realm features independent while the bounded endpoint runtime is enabled by default Protocol modules Identity, Chronicle, Capsules, links, authority, branches, governance, Accord, Atlas, Gate, Shield, and publishing Public contracts Eighteen immutable V1 descriptors bind the public names to concrete implementations Rendezvous service Additive signed V3 admission, opaque rendezvous, default on authenticated State Channel SSE, optional bounded Atlas, health, and metrics , Swarm content Signed manifests drive bounded multi provider chunk fetch, per chunk verification, retry, cache, and provider announcement , Deployment Source bound receipt,


Realm Network

Signed manifests drive bounded multi provider chunk fetch, per chunk verification, retry, cache, and provider announcement , Deployment Source bound receipt, checksummed archive, preflight, cutover, smoke, and rollback The Masterserver remains ephemeral. It does not store Realm identity, Chronicle, Capsules, branches, organizations, or durable Atlas data. (Source: , .) Public V1 contracts The stable registry exports these exact names: Area Contracts Identity and history , , Content and links , , , , Authority and branches , , Governance , Bounded task exchange , , Discovery and entry , Importing is inert. It creates no connection, timer, store, worker, or database. (Source: .) Guarded app API Apps use kernel syscalls instead of importing engine internals. The catalog contains metadata only; it never returns implementation functions or key handles. Contract verification requires . Feature changes and Passport mutations require . (Source: , .) Verification fails before dispatch when the contract's rollout feature is disabled. Passport operations delegate to the existing ; the Realm layer does not create a second private key store. (Source: , .) V3 selection and downgrade policy The Masterserver source and r7 deployment environment advertise V3 by default. The client first verifies the pinned signed V2 advertisement. If that valid advertisement has no V3 marker, the client selects V2. If it advertises V3, the client commits to V3 and verifies the complete V3 endpoint set, manifest, pin, and signatures. Any V3 integrity failure stops the connection and never downgrades to V2 or V1. A separate legacy V1 server entry is tried only as an availability fallback when the preferred V3/V2 entry cannot be acquired; it is not an integrity error fallback. (Source: , , , .) V3 uses for


Realm Network

tried only as an availability fallback when the preferred V3/V2 entry cannot be acquired; it is not an integrity error fallback. (Source: , , , .) V3 uses for admission and session proof, plus for opaque route attachment, discovery, and directed rendezvous. A signed V3 manifest also advertises , its short lived lease endpoint, and its SSE/HTTP base URL. HPKE context uses the V3 specific domain. (Source: , , .) Embedded resident and supernode roles Every enabled WebGPU OS browser profile starts an embedded Particle node. The node owns one mesh identity and one route set. describes its availability. , , and are elected or assigned roles on the same node, not separate networks or installations. Browser locks or a renewa


browser-bridge/BrowserBridgeClient.js

validateBridgeArgs(args, service = '', method = '')

<! 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 Verify END TO END bridge health. Unlike a relay only ping (which returns a false positive when the background service worker is dead/asleep), this does a real round trip to the background via a cheap, side effect free call (rules.list). Resolves within ms. Observe a newly injected extension relay after an extension reload/update. Force a fresh availability check (e.g. extension enabled after boot). Low level liveness check for relay.js ONLY (answered locally by the content script via postMessage — does NOT touch the background service worker). Used to distinguish "relay not injected" from "background not responding". Functions Constants — Singleton — shared by all syscall consumers. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


browser-bridge/BrowserBridgeDriver.js

browser-bridge/BrowserBridgeDriver.js
Classes
class BrowserBridgeDriver
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: BrowserBridgeDriver.js — kernel level wrapper around BrowserBridgeClient. Held at kernel.browserBridge. Manages availability probing on boot, event relay to the kernel event bus, and exposes the full typed client for syscalls. Classes Method Signature Summary Re check availability on demand (the extension may have been enabled/reloaded after boot). Binds event relays the first time it becomes available. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


browser-extension/adblock-content.js

browser-extension/adblock-content.js
Exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: adblock content.js — in frame cosmetic ad filtering (Layer 2). Runs in the DEFAULT (ISOLATED) world, in ALL frames, at document start. ISOLATED world is required so chrome.runtime / chrome.storage are available (the MAIN world content.js cannot reach them). Cosmetic hiding and DOM node removal only need access to the SHARED DOM, which the isolated world has. Responsibilities: Inject cosmetic CSS hiding known ad containers. Watch the DOM and remove ad/tracker <iframe /<script /<img nodes whose src targets a blocked domain (defence in depth alongside the DNR rule). Report removals to the background counter. Strictly scoped: only activates inside frames that belong to the WebGPU OS browser (top page is an OS host, or the outermost ancestor is an OS host), and only while ad blocking is enabled. Stays completely inert during the user's normal browsing. 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.


browser-extension/adblock-list.js

browser-extension/adblock-list.js
Functions
hostnameOf(url)
isAdDomain(url)
looksLikeAd(url)
cosmeticCss()
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: adblock list.js — shared ad/tracker blocklist for the WebGPU OS browser. SINGLE SOURCE OF TRUTH, consumed by three enforcement layers: 1. background.js → declarativeNetRequest BLOCK rules (network layer, scoped to OS tabs only — never the user's normal browsing) 2. adblock content.js → cosmetic hiding + DOM ad node removal inside OS embedded frames 3. extProxyFetch → ad tag stripping for proxied (srcdoc) pages Ported and expanded from the Playwright stealth blocker (C:\Coding\fail\server\tools\stealth.py — ADBLOCK DOMAINS / ADBLOCK URL KEYWORDS). This is an ES module: background.js imports it directly; the content script loads it via dynamic import(chrome.runtime.getURL('adblock list.js')), which is why it is also listed under web accessible resources in the manifest. The hand curated CORE list below is augmented at runtime by an optional, build generated list (adblock domains.generated.js) produced from EasyList / EasyPrivacy via build adblock rules.py. The generated file ships empty until you run that script, so the extension always loads. Functions Lowercased hostname from a URL, or '' if unparseable. True if the URL targets a known ad/tracker domain (or a subdomain of one). Broader match incl. keyword patterns — for the cosmetic/proxy layers only. A single <style string that hides all cosmetic selectors. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


browser-extension/ai-settings.js

browser-extension/ai-settings.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.


browser-extension/background.js

browser-extension/background.js
Exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: background.js — WebGPU OS Frame Unblocker + Browser Bridge service worker. Static rules (rules.json) are the primary mechanism. Dynamic rules (updateDynamicRules) are registered as a fallback on every startup in case Chrome silently rejected the static ruleset. Browser Bridge: handles os bridge request messages routed from relay.js, delegating to the four service modules (Tabs, Injection, Navigation, Rules). 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.


browser-extension/content.js

browser-extension/content.js
Exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: content.js — runs in the page's MAIN world at document start. 1. Sets window. frameUnblockerActive so the OS browser app can detect the extension. 2. In sub frames (iframes): overrides window.top / window.parent / window.frameElement so frame busting scripts (e.g. DuckDuckGo: "if (top !== self) top.location = ...") think they are the top level page and do not navigate away. Must run in world: "MAIN" and all frames: true to take effect before site JS. 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.


browser-extension/offscreen.js

browser-extension/offscreen.js
Exports
Notes & Examples


browser-extension/options.js

browser-extension/options.js
Exports
Notes & Examples


browser-extension/popup-ai.js

mountSecureProviderList({ root, summary, manageButton, refreshButton, send = runtimeMessageSender, onChange = ()

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


browser-extension/popup-size.js

browser-extension/popup-size.js
Exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SPDX FileCopyrightText: 2026 Jake Wehmeier (BTSpaniel) <https://github.com/BTSpaniel SPDX License Identifier: LicenseRef ParticleRealms Alpha 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.


browser-extension/popup.js

browser-extension/popup.js
Exports
Notes & Examples


browser-extension/relay.js

browser-extension/relay.js
Exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: relay.js — runs in the ISOLATED content script world (default). chrome.runtime IS available here (unlike world: "MAIN"). Acts as a bridge between the OS page (MAIN world) and the extension background. Two way channels: 1. Proxy fetch (legacy): page → os proxy request → relay → background → os proxy response → page 2. Browser Bridge requests: page → os bridge request → relay → background → os bridge response → page 3. Push events from background (nav/tab changes): background →sendMessage→ relay → os bridge event → page 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.


resolveProviderDataPolicy(providerId, route = {}, { authority = 'catalog' } = {})

resolveModelAccess(providerId, model = {}, { authority = 'catalog' } = {})

detectProvider({ key = '', endpoint = '' } = {})

normalizeEndpoint(value, { defaultBase = '' } = {})

endpointFor(providerId, customBase = '')

inferModelTaskAffinities(providerId, model = {})

inferModelCapabilities(providerId, model = {})

normalizeReasoningControl(model = {}, modelId = '')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Shared provider metadata and OpenAI compatible endpoint normalization. Keep this module free of chrome. calls so the service worker and tests can use the exact same routing and capability rules. Functions Decide whether an entered credential can be stored for the explicitly selected provider. Prefix detection is advisory only; it must never move a secret to another provider slot behind the user's back. Infer preference only task affinities from bounded catalog evidence. These hints may improve ranking, but must never authorize tools, strict output, private disclosure, or any other compatibility or security decision. Preserve the endpoint's own reasoning control surface. A single boolean cannot answer the questions a caller has to ask before touching reasoning: whether the endpoint rejects a disable ( ), whether it reasons unless told otherwise ( ), and which gateway knobs are real for it. OpenRouter reports effort levels and token budgets per model, and both are honoured for only a few families, so a caller that guesses either sends a parameter that silently does nothing or one that fails the request. is inferred from the model family because it is a training time prompt convention that no catalog reports. Preserve exact provider compatibility evidence in one deterministic shape. Some provider APIs use supported parameters while saved OS routes use supportedParameters, so merge both aliases instead of allowing one to hide the other. Values are bounded before they can enter extension storage. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AIProviderService.js — remote LLM provider bridge for the OS AI Hub. Runs in the extension background service worker context (privileged fetch, no CORS; host permissions already grant <all urls for this extension, so no additional host permissions are needed for the built in providers). The OS page NEVER sees provider URLs, headers, or API keys — it only sends {provider, model, messages, params} and gets back {message, usage}. Keys are read via KeyVaultService.getRawKeyInternal(), which is not reachable through the bridge router (see KeyVaultService.js for why). Allowlists: providerAllowlist/pathAllowlist: AIProviderCatalog is the only set of provider ids + exact endpoint URLs ever fetched for non custom requests. originAllowlist (custom provider): CUSTOM ENDPOINTS is a user approved https only allowlist, persisted in chrome.storage.local, populated only via allowCustomEndpoint(). Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AudioService.js — privileged tab audio bridge for WebGPU OS. Browser page audio inside the OS tab (YouTube, video sites, embedded frames) does not pass through the OS AudioDriver. Chrome extensions can control that audio by capturing the tab stream, replaying it through an offscreen AudioContext, and applying a GainNode. The OS mixer sends the effective gain here; the service worker owns tabCapture permission and the offscreen document owns Web Audio playback. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! 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 Memory only session boundary between the isolated relay and background worker. Secrets never cross window.postMessage. A service worker restart invalidates every session and forces the still isolated relay to open a fresh one. 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.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CorsService.js — per site opt in CORS/API unblocking for the OS bridge. Runs in the extension background service worker context. The blanket rule 9005 only injects on NON credentialed static assets (scripts/fonts/etc.), deliberately leaving a framed site's own credentialed /XHR/API calls untouched — a wildcard ACAO is illegal for credentialed requests and would break logins. This service lets the user OPT IN, per trusted site, to also unblock those credentialed API calls. For each enabled origin O (host H) we add session rules (tab scoped to OS tabs) that, for requests INITIATED BY that site's frames (initiatorDomains: [H]), set on the response: Access Control Allow Origin: O (echoes the page origin, not ) Access Control Allow Credentials: true Access Control Allow Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS Access Control Allow Headers: Scoping by initiatorDomains keeps this correct with multiple sites open and never affects the user's normal browsing (session rules are tab scoped). Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Authenticate privileged runtime messages from this extension's own pages. Extension pages opened in a popup window can have sender.tab; content scripts also have sender.tab, so ownership must be decided from the sender URL/origin rather than from tab presence alone. Functions Authenticate privileged runtime messages from this extension's own pages. Extension pages opened in a popup window can have sender.tab; content scripts also have sender.tab, so ownership must be decided from the sender URL/origin rather than from tab presence alone. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


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


class KeyVaultContractError extends Error

normalizeKeyVaultEnvelope(provider, raw, { persisted = false, label = 'AI key record' } = {})

normalizeKeyVaultState(provider, raw, label = 'AI key state')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: KeyVaultService.js — provider API key storage for the AI Bridge. Runs in the extension background service worker context. Keys are NEVER exposed to the OS page/bridge caller — only status booleans cross the bridge. getRawKeyInternal() remains a module only worker export. V2 binds provider and generation into AES GCM additional authenticated data. V1 encrypted envelopes and bounded legacy plaintext remain read only inputs and migrate on first use. A durable generation tombstone prevents an older persistent credential from reappearing after a session only switch or an interrupted clear. Classes Method Signature Summary Functions Internal only accessor; deliberately absent from KeyVaultService dispatch. Constants — Page/bridge facing surface — status only, never the raw key. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


runBrowserLivePatch(command, payload = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Clean room declarative browser surface editor. This module deliberately accepts data, never JavaScript source. The exported page function is self contained so chrome.scripting can serialize it into the extension's ISOLATED world without eval, Function, or page owned callbacks. Functions Validate and reduce a kernel patch before it crosses the 64 KiB bridge. Self contained function executed by chrome.scripting in the ISOLATED world. Do not introduce references to module scope bindings here. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Memory only projection of kernel owned Browser Semantic Faculty readiness. The Companion does not sign, verify, install, enable, or approve Faculties. It accepts a content free status only through an authenticated OS bridge session so extension owned UI can show which exact kernel package revision the OS reports as verified. A service worker restart or bridge revocation clears the projection. Classes Method Signature Summary Constants — Memory only projection of kernel owned Browser Semantic Faculty readiness. The Companion does not sign, verify, install, enable, or approve Faculties. It accepts a content free status only through an authenticated OS bridge session so extension owned UI can show which exact kernel package revision the OS reports as verified. A service worker restart or bridge revocation clears the projection. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: NavigationService.js — webNavigation history + OS push events. Runs in the extension background service worker context. The background registers webNavigation listeners that call NavigationService.addEvent(). The OS can poll history() or receive live push events via the os bridge event channel. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: OpenRouterAuthService.js — extension owned OAuth PKCE sign in. The authorization code and generated API key never cross the page bridge. Only the extension credential window can start this flow, and the resulting key is immediately encrypted through KeyVaultService. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.