@volter/project 0.0.0-stage → 0.5.204

package/schemas/volter-project.schema.json

@@ -0,0 +1,468 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-schema.ts — do not edit manually",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Optional JSON Schema URI for editor autocomplete and validation",
+      "type": "string"
+    },
+    "manifestVersion": {
+      "type": "number",
+      "const": 2,
+      "description": "Manifest file format version (v2 clean roots)"
+    },
+    "name": {
+      "type": "string",
+      "description": "Game display name"
+    },
+    "appId": {
+      "description": "Stable reverse-domain application id used by packaged targets",
+      "type": "string"
+    },
+    "version": {
+      "type": "string",
+      "description": "The game's own version (used for orphan detection)"
+    },
+    "engine": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "Exact @volter/project semver this game was scaffolded/last upgraded against — an identity pin, not a range"
+        }
+      },
+      "required": [
+        "version"
+      ],
+      "additionalProperties": false,
+      "description": "Engine version pin"
+    },
+    "roots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique id for this root within the manifest (enforced-unique, D-V6 — GameManifestSchema.roots rejects duplicates)"
+          },
+          "description": {
+            "description": "Optional one-line description of this root's game/content (e.g. an ingested game's blurb — the manifest-native replacement for a registry entry's description field)",
+            "type": "string"
+          },
+          "adapter": {
+            "description": "This root's adapter and sole rendering/lifecycle discriminator",
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "three",
+                  "canvas",
+                  "dom"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "module": {
+                    "type": "string",
+                    "description": "Game-folder-relative path to a custom adapter module (trust boundary)"
+                  },
+                  "surface": {
+                    "type": "string",
+                    "enum": [
+                      "three",
+                      "canvas",
+                      "dom"
+                    ],
+                    "description": "Native surface exposed by this custom adapter contract"
+                  }
+                },
+                "required": [
+                  "module",
+                  "surface"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "surface": {
+                    "type": "string",
+                    "enum": [
+                      "three",
+                      "canvas",
+                      "dom"
+                    ],
+                    "description": "Native surface captured from the unmodified game"
+                  },
+                  "ingest": {
+                    "type": "object",
+                    "properties": {
+                      "contractShim": {
+                        "description": "Project-relative path to a HOST-ADDED ES module that declares this game's `window.volterGame` contract (adapter/ingest/game-contract.ts) WITHOUT editing a vendored byte — the pristine-copy door. The host imports it immediately BEFORE the game's own entry module, in the editor's realm. TIMING CONTRACT, which a shim author must obey: because it runs before the game`s entry, it MUST assign `window.volterGame` SYNCHRONOUSLY at top level. Anything that needs the game`s own modules must be LAZY: a dynamic `import()` INSIDE each verb/provider closure, resolved at call time. Importing a game module eagerly from the shim would evaluate it ahead of the game`s own entry and reorder its module side effects. Every such `import()` MUST take a STRING LITERAL, never a variable/table lookup. A variable specifier is not statically analyzable, so the dev server leaves it alone and it resolves at runtime against the shim`s own `/@fs/` url — while the game`s entry has had ITS relative imports rewritten to whatever url the server considers canonical for those files. Module identity is per-url, so the shim silently binds a SECOND, freshly-evaluated copy of the whole game and every provider reports a game that never started. Measured on a vendored three game: 285 world segments through the game`s own graph, 0 through the shim`s, and no error anywhere.",
+                        "type": "string"
+                      },
+                      "dataWriter": {
+                        "description": "Project-relative path to a HOST-ADDED ES module that writes this game's own DATA file back — the sibling of a source write for a game whose authorable truth is not source. A level-based game places its enemies, pickups and objectives in binary records inside a level file, reaching no source literal, so an authored move of one is an edit to that file and nothing else can write it. The module declares two exports and the host knows nothing else about it: `dataFile` (a project-relative string — the ONE file this writer edits) and `planDataEdit(bytes, {record, property, baseline, next})`, which returns `{changed: true, bytes}` or `{changed: false, reason}` and may be async. It is loaded in the editor realm beside the game, so it may `import()` the game's own modules to resolve what only a running game knows (a level writer asks the game`s own spatial lookup which cell a moved object landed in, and refuses \"outside the level\" rather than writing data the game would read back wrong). It NEVER fabricates: a record it cannot address, or a property it does not model, is a named refusal. An object is anchored to a record by carrying `userData.volterRecordIndex` — the game declares that identity itself (a recorded patch or a shim); the host never infers one.",
+                        "type": "string"
+                      },
+                      "assets": {
+                        "description": "Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)",
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      },
+                      "moduleAliases": {
+                        "description": "The game's OWN bundler path aliases, restated as a mounting fact so its source resolves unedited. A game built with its own Vite/webpack config routinely imports itself through an alias (`~/lib/config`, `@/store/x`); the editor boots Vite from the ENGINE's config and never reads a game's own, so without this every such import is an unresolvable specifier and the mount dies at transform time. Key = the specifier PREFIX exactly as the game writes it (\"~/\"); value = the repo-root-relative directory it means (\"/vendor/games/<id>/src/\"). SELF-SCOPING: the host honors an entry only for importers inside the vendored game folder the value points into, so one game's alias can never capture another module's import. Rewriting the game's own imports instead would be a large non-seam-shaped diff against unmodified source — this declares the fact rather than editing it away.",
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      },
+                      "domStubs": {
+                        "description": "DOM API stub ids this ingested game requires to run headlessly/in-realm",
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "captureTimeoutMs": {
+                        "description": "How long the host waits for this game's first captured frame before the mount FAILS by name. A game that needs a long boot (streamed world assets, a menu the player must clear) raises it; the default is 10s.",
+                        "type": "number"
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "Ingest adapter configuration for an unmodified game (a repo-vendored game or your own external folder)"
+                  }
+                },
+                "required": [
+                  "surface",
+                  "ingest"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          },
+          "entry": {
+            "description": "Module exporting a world root — a TSX/R3F component or a setup()/adapter (three), or a React component (dom). Required for every built-in adapter root.",
+            "type": "string"
+          },
+          "styles": {
+            "description": "Project-root-relative CSS files this root's mount needs — the PAGE-level stylesheet a game written to own a browser tab keeps its layout in (an ingested game is the standing case: its own entry imported the sheet, the host shim that replaces that entry cannot, because `html`/`body`/`*` rules would restyle the editor). Declared here, the editor serves each file rewritten to apply ONLY inside the container it mounts the root's DOM in (`@scope`; packages/editor/server/scoped-game-css.ts), so the HUD is styled on the UI board's story cards and on the game surface without the editor seeing a single one of those rules. The files themselves are never modified.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "world": {
+            "description": "The component this root's WORLD is, in the game's own source. Two readers, and they mount different things: the EDITOR mounts THIS component alone as the root's design-time document, while `entry` above stays what PLAY mounts (the whole game — its own composition, its own HUD, its own loop). It sits on the ROOT rather than inside any one adapter because the split it names is not about ingest: a game whose runtime entry is a SHELL over the thing an author actually edits has this shape whether the source is vendored or first-party. Two shipped cases, one field: an ingested game whose `entry` mounts game+HUD+loop while the named export is the world alone; and a translated Unity/Godot port, whose `entry` is a scene HOST that mounts the scene the built player starts on (`EditorBuildSettings` index 0 — routinely a menu with no 3D content at all) while the named export opens the scene an author edits. That is Unity's own split: build settings say where the PLAYER starts; the Scene view opens a scene, and Unity keeps that fact somewhere else entirely. A game whose world is not a separate component omits this and keeps mounting through `entry` in both modes.",
+            "type": "object",
+            "properties": {
+              "entry": {
+                "type": "string",
+                "description": "Project-relative path to the game's OWN module exporting that component"
+              },
+              "export": {
+                "description": "Named export to read from that module; omit when the module default-exports it",
+                "type": "string"
+              }
+            },
+            "required": [
+              "entry"
+            ],
+            "additionalProperties": false
+          },
+          "zOrder": {
+            "default": 0,
+            "description": "Canvas stacking order; ties broken by array order",
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "pausable": {
+            "default": true,
+            "description": "Whether play-mode pause/step applies to this root",
+            "type": "boolean"
+          },
+          "loop": {
+            "default": "gated",
+            "description": "gated: host-driven loop (default). self-driven: this root drives its own loop (composited, unsynchronized)",
+            "type": "string",
+            "enum": [
+              "gated",
+              "self-driven"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "adapter"
+        ],
+        "additionalProperties": false
+      },
+      "description": "The project's explicit adapter-root composition — ZERO OR MORE roots, and no implicit root: a project with no roots mounts nothing (a library of models, a folder of documents) and the editor derives its chrome from what IS declared. Root ids are unique, and a project declares at most ONE world root per medium — one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest and canvas module are the same medium)."
+    },
+    "authoring": {
+      "description": "Editor-only authoring metadata; never runtime ownership",
+      "type": "object",
+      "properties": {
+        "hierarchy": {
+          "description": "Editor projection for native adapter roots",
+          "type": "object",
+          "properties": {
+            "rootLabels": {
+              "description": "Optional editor labels keyed by adapter-root id",
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "groups": {
+              "description": "Optional editor-only hierarchy groups",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Unique editor-only group id"
+                  },
+                  "label": {
+                    "type": "string",
+                    "description": "Editor-only group label"
+                  },
+                  "roots": {
+                    "minItems": 1,
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Adapter-root ids shown under this editor-only group"
+                  }
+                },
+                "required": [
+                  "id",
+                  "label",
+                  "roots"
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "configurations": {
+      "description": "The project's run configurations — its ENTRYPOINTS beyond the host mount (`play`): each an id and a registered kind (`process`, `compound`, and whatever a capability registers) with that kind's own fields. The editor's transport and a harness start the same declaration.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Configuration id, unique in the manifest"
+          },
+          "kind": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A registered run kind"
+          }
+        },
+        "required": [
+          "id",
+          "kind"
+        ],
+        "additionalProperties": {}
+      }
+    },
+    "resolution": {
+      "description": "Canvas resolution",
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "number",
+          "description": "Canvas width in pixels"
+        },
+        "height": {
+          "type": "number",
+          "description": "Canvas height in pixels"
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "additionalProperties": false
+    },
+    "rendering": {
+      "description": "Construction-time renderer properties, which no world can declare after the fact. Everything a world CAN declare (tone mapping, output colour space, clear colour, shadow filter) lives on the world's own renderer config instead.",
+      "type": "object",
+      "properties": {
+        "antialias": {
+          "type": "boolean",
+          "description": "Whether every three root is built with a multisampled drawing buffer. This is the ONE render property a world cannot declare for itself (adapter/renderer-config.ts): a WebGL context fixes its sample count at CREATION from this boolean, long before a world mounts, so it belongs to the PROJECT. The runtime reader is mount-manifest.ts, which threads it into createHostRenderer for each three root. WebGL exposes no sample COUNT — the implementation picks one (4x on every desktop browser measured), so a source engine that authored 8x/16x gets multisampling but not its exact count."
+        }
+      },
+      "required": [
+        "antialias"
+      ],
+      "additionalProperties": false
+    },
+    "debug": {
+      "description": "Debug-bridge production gating (D18) — governs whether ?volter-debug=1 installs window.__volter outside dev builds.",
+      "type": "object",
+      "properties": {
+        "allowInProduction": {
+          "type": "boolean",
+          "description": "Allow the ?volter-debug=1 introspection bridge and debug-command invocation in production builds. Default false: the bridge only installs in dev builds. The runtime reader is the debug-bridge installer (D18)."
+        }
+      },
+      "required": [
+        "allowInProduction"
+      ],
+      "additionalProperties": false
+    },
+    "determinism": {
+      "description": "Seeded-RNG determinism contract (D15) — governs whether ctx.random is boot-seeded from a reproducible seed and whether the gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.",
+      "type": "object",
+      "properties": {
+        "seededRandom": {
+          "type": "boolean",
+          "description": "Declares that ALL gameplay RNG in this project flows through ctx.random (the named-stream seeded PRNG) rather than raw Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: the boot-time seeding reader (mount-manifest.ts seeds ctx.random from defaultSeed/?volter-seed=/explicit config, in that precedence, only when true), the gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay frame, never throws). Default false: an undeclared project gets no determinism contract at all (that IS the opt-out — no dead field)."
+        },
+        "defaultSeed": {
+          "description": "The seed ctx.random boots from when seededRandom is true, unless overridden by ?volter-seed=<int> (the query param always wins over this manifest default) or an even higher-precedence explicit config value a host passes directly. Optional — omit to fall back to the runtime's own fixed default seed.",
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "seededRandom"
+      ],
+      "additionalProperties": false
+    },
+    "budget": {
+      "description": "Performance budget (W3d, F11 perf regression gates) asserted by `volter perf --assert-budget`: a seeded, fixed-step headless run samples the engine profiler and fails (nonzero exit) when any metric here is exceeded. Only headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).",
+      "type": "object",
+      "properties": {
+        "frameCpuMsP95": {
+          "description": "Maximum allowed p95 of per-frame CPU time (ms) across the measured frames of a `volter perf` seeded headless run. CPU-side only: headless runs rasterize under SwiftShader, so this is main-thread frame cost, NOT real GPU frame time. Machine-dependent — prefer the baseline-diff tolerance band for regression gating and use this as a coarse absolute ceiling.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "physicsMsP95": {
+          "description": "Maximum allowed p95 of the profiler's `physics` phase time (ms) per fixed-step frame in a `volter perf` run. Same CPU-timing caveats as frameCpuMsP95.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "maxEntities": {
+          "description": "Maximum allowed entity-tagged scene-graph nodes (nodes carrying userData.entityId) summed across the game's three/canvas worlds at the end of a `volter perf` run. Exact and deterministic under a seed — no tolerance band.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxDrawCalls": {
+          "description": "Maximum allowed renderer draw calls in any measured frame of a `volter perf` run (the profiler's per-frame render.drawCalls, from renderer.info). Exact and deterministic under a seed.",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxTriangles": {
+          "description": "Maximum allowed rendered triangles in any measured frame of a `volter perf` run (the profiler's per-frame render.triangles, from renderer.info). Exact and deterministic under a seed.",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "additionalProperties": false
+    },
+    "learn": {
+      "description": "Optional learner-facing metadata (FT-5) — set on shipped example projects so the gallery/wizard/Learn-catalog registries can be generated from the manifest itself",
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "starter",
+            "feature",
+            "sample-game",
+            "lesson-companion"
+          ],
+          "description": "Content kind in the FTUE taxonomy (§3): starter (minimal per-genre starting point), feature (demonstrates a subsystem), sample-game (complete game as an architectural reference), lesson-companion (exists to back a Learn-site lesson)"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Learner-facing display title (gallery card headline)"
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One-sentence learner-facing summary (gallery card body)"
+        },
+        "difficulty": {
+          "type": "string",
+          "enum": [
+            "beginner",
+            "intermediate",
+            "advanced"
+          ],
+          "description": "Learner-facing difficulty rating"
+        },
+        "features": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "description": "Short kebab-case feature tags used as gallery/catalog filter facets"
+        },
+        "thumbnail": {
+          "description": "Optional thumbnail image reference, PROJECT-relative (canonical path: learn/thumbnail.png — the §3 schema path). Generated per FT-11 by the deterministic render tooling (scripts/generate-learn-thumbnails.ts), never hand-made",
+          "type": "string"
+        },
+        "preview": {
+          "description": "Optional short preview video/loop reference, PROJECT-relative (canonical path: learn/preview.mp4; generated per FT-11)",
+          "type": "string"
+        },
+        "lesson": {
+          "description": "Optional Learn-site lesson URL that teaches this project 1:1 (e.g. https://example.com/manual/physics/joints/)",
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "title",
+        "summary",
+        "difficulty",
+        "features"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "manifestVersion",
+    "name",
+    "version",
+    "engine",
+    "roots"
+  ],
+  "additionalProperties": false,
+  "description": "Game manifest (volter.project.json) — the complete v2 project configuration"
+}

package/schemas/volter-settings.schema.json

@@ -0,0 +1,149 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-schema.ts — do not edit manually",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema pointer for editor autocomplete; ignored by the editor.",
+      "type": "string"
+    },
+    "appearance": {
+      "description": "How the editor chrome looks.",
+      "type": "object",
+      "properties": {
+        "palette": {
+          "description": "Editor palette id — a built-in or a custom theme document.",
+          "type": "string"
+        },
+        "material": {
+          "description": "Editor material id (`classic`, `glass`, or one a style bundle carries).",
+          "type": "string"
+        },
+        "icons": {
+          "description": "Editor icon set id (`default`, or one a style bundle carries).",
+          "type": "string"
+        },
+        "regions": {
+          "type": "object",
+          "properties": {
+            "workspaceTabs": {
+              "description": "The workspace tab strip in the top bar (Blender's); hidden unless a style shows it.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "header": {
+              "description": "The top header bar.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "shelf": {
+              "description": "The utility shelf.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "inspector": {
+              "description": "Inspector presentation: the narrow docked column or a properties panel.",
+              "type": "string",
+              "enum": [
+                "column",
+                "properties",
+                "card"
+              ]
+            },
+            "drawer": {
+              "description": "The bottom drawer.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "telemetry": {
+              "description": "The top bar's runtime telemetry cluster: the frame-rate readout, its sparkline and the audio meter. The Profiler utility is the same information's other door.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "hierarchyTypeSuffix": {
+              "description": "The `·TypeName` a component-instance row prints after its name in the hierarchy. Hidden leaves the row its name alone, the way Blender's Outliner does; the type stays reachable through the row's own tooltip and the inspector.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "hierarchyInstanceRule": {
+              "description": "The dotted rule a component-instance row draws under its name in the hierarchy. Hidden leaves the name unmarked, the way Blender's Outliner does; the fact stays reachable through the row's own tooltip, its source actions and the inspector.",
+              "type": "string",
+              "enum": [
+                "shown",
+                "hidden"
+              ]
+            },
+            "hierarchyRestrictions": {
+              "description": "Which restriction columns a hierarchy row carries at its right edge: this editor's selection lock beside the eye, or Blender's default filter — the eye in its own column with the render column reserved and blank, three.js having one visibility flag for viewport and render alike.",
+              "type": "string",
+              "enum": [
+                "select+viewport",
+                "viewport+render"
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Which chrome regions a style bundle shows or hides."
+        }
+      },
+      "additionalProperties": false
+    },
+    "keymap": {
+      "description": "Active keymap preset id (`volter`, `blender`, …).",
+      "type": "string"
+    },
+    "play": {
+      "description": "How the editor presents Play mode.",
+      "type": "object",
+      "properties": {
+        "keepPanelsVisible": {
+          "description": "Keep editor panels visible when starting Play, instead of letting an immersive workspace hide them. Turning this on during Play restores the panels; turning it off applies on the next Play.",
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "devicePreview": {
+      "description": "The device frame the Game document previews in.",
+      "type": "object",
+      "properties": {
+        "preset": {
+          "description": "Device preview frame preset id.",
+          "type": "string"
+        },
+        "touch": {
+          "description": "Touch emulation override; null follows the preset.",
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "description": "Editor settings — the user layer and the project layer share this shape."
+}