@volter/project 0.5.211 → 0.5.212

package/src/semver.ts

@@ -0,0 +1,16 @@
+// Compares two exact versions (`1.2.3`, with an optional prerelease or build suffix, which is not ordered),
+// such as a project's pinned engine and the engine an editor runs. Anything else compares as `null`.
+const EXACT_SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function compareSemver(a: string, b: string): -1 | 0 | 1 | null {
+  const aMatch = EXACT_SEMVER.exec(a);
+  const bMatch = EXACT_SEMVER.exec(b);
+  if (!aMatch || !bMatch) return null;
+  for (let index = 1; index <= 3; index++) {
+    const aPart = Number(aMatch[index]);
+    const bPart = Number(bMatch[index]);
+    if (aPart < bPart) return -1;
+    if (aPart > bPart) return 1;
+  }
+  return 0;
+}

package/src/settings/keys.ts

@@ -4,22 +4,21 @@
  *
  * ## Why it exists, and why it is DERIVED
  *
- * Under the Code-OSS frame (ARCHITECTURE-CORE §The core is Code-OSS, U7) the
+ * Under the Code-OSS frame  the
  * settings layers are the configuration service's, and a configuration service
- * speaks FLAT DOTTED KEYS — `volter.appearance.palette` — while
+ * speaks FLAT DOTTED KEYS — `volter.appearance.regions.header` — while
  * `schema.ts`'s document is a nested object. Something has to be the one place
  * those two spellings meet, and the same table is what the fork's
  * `contributes.configuration` is generated from, so VS Code's Settings editor
  * shows every volter setting with the description its `.describe()` call already
  * carries.
  *
- * It is DERIVED from {@link EditorSettingsSchema} rather than written, for the
- * reason `PROVIDER_GAP` in `adapter-reach.ts` is a `Record` over a pinned key
- * union: a hand-kept second list of the same seventeen keys drifts the first
+ * It is DERIVED from {@link EditorSettingsSchema} rather than written: a
+ * hand-kept second list of the same keys drifts the first
  * time somebody adds a field, and a settings key with no declaration is
  * invisible in the one settings UI rather than loud. The walk is over the JSON
  * Schema Zod itself produces (`z.toJSONSchema`) — the SAME derivation
- * `scripts/generate-schema.ts` commits as
+ * `packages/project/scripts/generate-schema.mjs` commits as
  * `packages/project/schemas/volter-settings.schema.json`, which is what the
  * fork's generator reads. One derivation, three consumers: this table, the
  * committed schema a person's editor autocompletes against, and the frame's
@@ -40,13 +39,12 @@ export const SETTINGS_KEY_PREFIX = 'volter';
 
 /** What a key is, and what the Settings editor shows for it. */
 export interface SettingsKeyDescriptor {
-  /** The dotted name, prefix included: `volter.appearance.palette`. */
+  /** The dotted name, prefix included: `volter.appearance.regions.header`. */
   readonly key: string;
-  /** The path into the settings document: `['appearance', 'palette']`. */
+  /** The path into the settings document: `['appearance', 'regions', 'header']`. */
   readonly path: readonly string[];
-  /** JSON Schema `type`, when the field has exactly one. A nullable field
-   *  (`devicePreview.touch`) has none, and the frame declares no type for it
-   *  rather than picking one of the two. */
+  /** JSON Schema `type`, when the field has exactly one. A nullable field has
+   *  none, and the frame declares no type for it rather than picking one. */
   readonly type?: string | undefined;
   /** The closed set of values, when the field is an enum. */
   readonly values?: readonly string[] | undefined;

package/src/settings/schema.ts

@@ -1,13 +1,13 @@
 /**
- * THE SETTINGS DOCUMENT — the Zod truth for the two shared settings layers
- * (ARCHITECTURE-CORE §Editor chrome, "Settings have four layers with named
- * homes"):
+ * THE SETTINGS DOCUMENT — the Zod truth for the two shared settings layers:
  *
- *   ~/.volter/settings.json     the USER layer — one person, every project
- *   <project>/.volter/settings.json   the PROJECT layer — one project, committed,
- *                             every person who opens it
+ *   ~/.volter/settings.json           the USER layer — one person, every project
+ *   <project>/.vscode/settings.json   the PROJECT layer — one project, committed,
+ *                                     every person who opens it: its `volter.*`
+ *                                     keys, in Code-OSS's own workspace settings
+ *                                     (`editor-core/server/project-settings-file.ts`)
  *
- * Both files carry the same shape; the project layer overrides the user layer
+ * Both layers carry the same shape; the project layer overrides the user layer
  * key by key (`mergeEditorSettings`). Neither layer holds authored content —
  * an unreadable file is reported by name and falls back to defaults, never
  * migrated. The generated JSON Schema (`npm run generate-schema` →
@@ -16,9 +16,8 @@
  *
  * Every field here has a runtime reader in the editor's settings store
  * consumers (`theme-preference.ts`, `workspace-regions.ts`,
- * `keymap-presets.ts`, `workspace-presets.ts`, `device-preview.ts`); a field
- * with no reader does not get declared (CLAUDE.md, "Do not author schema
- * fields that have no runtime reader").
+ * `keymap-presets.ts`, `workspace-presets.ts`); a field
+ * with no runtime reader has no setting to govern.
  */
 import { z } from 'zod';
 
@@ -27,29 +26,26 @@ const RegionVisibility = z.enum(['shown', 'hidden']);
 export const ChromeRegionsSettingsSchema = z
   .object({
     workspaceTabs: RegionVisibility.optional().describe(
-      "The workspace tab strip in the top bar (Blender's); hidden unless a style shows it.",
+      'The workspace tab strip in the top bar; hidden unless a style shows it.',
     ),
     header: RegionVisibility.optional().describe('The top header bar.'),
     shelf: RegionVisibility.optional().describe('The utility shelf.'),
     inspector: z
       .enum(['column', 'properties', 'card'])
       .optional()
-      .describe('Inspector presentation: the narrow docked column or a properties panel.'),
+      .describe('Inspector presentation: a narrow docked column, properties panel or card.'),
     drawer: RegionVisibility.optional().describe('The bottom drawer.'),
-    telemetry: RegionVisibility.optional().describe(
-      "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.",
-    ),
     hierarchyTypeSuffix: RegionVisibility.optional().describe(
-      "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.",
+      "The `·TypeName` a component-instance row prints after its name in the hierarchy. Hidden leaves the row its name alone; the type stays reachable through the row's own tooltip and the inspector.",
     ),
     hierarchyInstanceRule: RegionVisibility.optional().describe(
-      "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.",
+      "The dotted rule a component-instance row draws under its name in the hierarchy. Hidden leaves the name unmarked; the fact stays reachable through the row's own tooltip, its source actions and the inspector.",
     ),
     hierarchyRestrictions: z
       .enum(['select+viewport', 'viewport+render'])
       .optional()
       .describe(
-        "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.",
+        "Which restriction columns a hierarchy row carries at its right edge: the selection lock beside the eye, or the eye in its own column with the render column reserved and blank, the viewport having one visibility flag for viewport and render alike.",
       ),
   })
   .strict()
@@ -61,26 +57,20 @@ export const EditorSettingsSchema = z
       .string()
       .optional()
       .describe('JSON Schema pointer for editor autocomplete; ignored by the editor.'),
+    style: z
+      .string()
+      .optional()
+      .describe(
+        'Editor style id (`classic`, `glass`, or one a package carries): its material, icon set and type. Choosing one also applies the colour theme it was drawn with.',
+      ),
     appearance: z
       .object({
-        palette: z
-          .string()
-          .optional()
-          .describe('Editor palette id — a built-in or a custom theme document.'),
-        material: z
-          .string()
-          .optional()
-          .describe('Editor material id (`classic`, `glass`, or one a style bundle carries).'),
-        icons: z
-          .string()
-          .optional()
-          .describe('Editor icon set id (`default`, or one a style bundle carries).'),
         regions: ChromeRegionsSettingsSchema.optional(),
       })
       .strict()
       .optional()
       .describe('How the editor chrome looks.'),
-    keymap: z.string().optional().describe('Active keymap preset id (`volter`, `blender`, …).'),
+    keymap: z.string().optional().describe('Active keymap preset id (`volter`, or a contributed preset).'),
     play: z
       .object({
         keepPanelsVisible: z
@@ -93,24 +83,11 @@ export const EditorSettingsSchema = z
       .strict()
       .optional()
       .describe('How the editor presents Play mode.'),
-    devicePreview: z
-      .object({
-        preset: z.string().optional().describe('Device preview frame preset id.'),
-        touch: z
-          .boolean()
-          .nullable()
-          .optional()
-          .describe('Touch emulation override; null follows the preset.'),
-      })
-      .strict()
-      .optional()
-      .describe('The device frame the Game document previews in.'),
   })
   .strict()
   .describe('Editor settings — the user layer and the project layer share this shape.');
 
 export type EditorSettings = z.infer<typeof EditorSettingsSchema>;
-export type ChromeRegionsSettings = z.infer<typeof ChromeRegionsSettingsSchema>;
 
 /** Which layer a file is; the file paths are the server's. */
 export type SettingsLayer = 'user' | 'project';
@@ -149,3 +126,37 @@ export function parseEditorSettings(
     ),
   };
 }
+
+/** A settings FILE's text, read: `null` (no file) is the empty document; text that is not JSON or
+ *  not a valid document carries its issues and no settings. */
+export function parseEditorSettingsText(
+  text: string | null,
+): { settings: EditorSettings; issues: [] } | { settings: null; issues: string[] } {
+  if (text === null) return { settings: {}, issues: [] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (cause) {
+    return { settings: null, issues: [`not JSON: ${(cause as Error).message}`] };
+  }
+  return parseEditorSettings(raw);
+}
+
+/**
+ * The refusal of a write over a settings file that is invalid on disk, or `null` when the write
+ * may go ahead. Every door that writes a settings layer answers with this one (HTTP 409): an
+ * invalid file is the person's to fix, never the editor's to replace, because writing the
+ * session's document over it would discard everything else the file holds.
+ */
+export function settingsWriteRefusal(
+  layer: 'user' | 'project',
+  path: string,
+  onDiskIssues: readonly string[],
+): { error: string; issues: readonly string[]; path: string } | null {
+  if (onDiskIssues.length === 0) return null;
+  return {
+    error: `${path} is invalid (${onDiskIssues.join('; ')}); fix it before the editor writes ${layer} settings again.`,
+    issues: onDiskIssues,
+    path,
+  };
+}

package/schemas/engine-api.json

@@ -1,57 +0,0 @@
-{
-  "$comment": "AUTO-GENERATED by scripts/generate-engine-manifest.ts — do not edit manually. Run 'npm run generate-engine-manifest'.",
-  "phases": [
-    {
-      "name": "input",
-      "description": "Sample input devices (keyboard, mouse, gamepad) at the top of the frame."
-    },
-    {
-      "name": "prePhysics",
-      "description": "Apply forces/intents to rigid bodies before the physics step."
-    },
-    {
-      "name": "physics",
-      "description": "Step the Rapier physics world (fixed timestep)."
-    },
-    {
-      "name": "postPhysics",
-      "description": "Read physics results back; sync transforms from bodies to Object3D."
-    },
-    {
-      "name": "gameLogic",
-      "description": "General gameplay behavior."
-    },
-    {
-      "name": "animation",
-      "description": "Advance animation graphs / mixers."
-    },
-    {
-      "name": "preRender",
-      "description": "Final per-frame fixups (cameras, HUD state) before drawing."
-    },
-    {
-      "name": "render",
-      "description": "Draw the frame."
-    }
-  ],
-  "phaseOrder": [
-    "input",
-    "prePhysics",
-    "physics",
-    "postPhysics",
-    "gameLogic",
-    "animation",
-    "preRender",
-    "render"
-  ],
-  "phaseConstants": {
-    "INPUT": "input",
-    "PRE_PHYSICS": "prePhysics",
-    "PHYSICS": "physics",
-    "POST_PHYSICS": "postPhysics",
-    "GAME_LOGIC": "gameLogic",
-    "ANIMATION": "animation",
-    "PRE_RENDER": "preRender",
-    "RENDER": "render"
-  }
-}

package/schemas/engine-api.md

@@ -1,22 +0,0 @@
-<!-- AUTO-GENERATED by scripts/generate-engine-manifest.ts — do not edit manually. -->
-<!-- Run 'npm run generate-engine-manifest' to regenerate. -->
-
-# Engine API Manifest
-
-The schema-as-source-of-truth artifact for the engine's imperative surface — generated from the actual code so docs can never drift (see ROADMAP P0.3 / P2.9).
-
-## System Phases
-
-Each frame, systems run in this exact order (from `PHASE_ORDER` in `packages/project/src/core/system-phase.ts`):
-
-| # | Phase | Constant | Description |
-| - | ----- | -------- | ----------- |
-| 1 | `input` | `SystemPhase.INPUT` | Sample input devices (keyboard, mouse, gamepad) at the top of the frame. |
-| 2 | `prePhysics` | `SystemPhase.PRE_PHYSICS` | Apply forces/intents to rigid bodies before the physics step. |
-| 3 | `physics` | `SystemPhase.PHYSICS` | Step the Rapier physics world (fixed timestep). |
-| 4 | `postPhysics` | `SystemPhase.POST_PHYSICS` | Read physics results back; sync transforms from bodies to Object3D. |
-| 5 | `gameLogic` | `SystemPhase.GAME_LOGIC` | General gameplay behavior. |
-| 6 | `animation` | `SystemPhase.ANIMATION` | Advance animation graphs / mixers. |
-| 7 | `preRender` | `SystemPhase.PRE_RENDER` | Final per-frame fixups (cameras, HUD state) before drawing. |
-| 8 | `render` | `SystemPhase.RENDER` | Draw the frame. |
-