@vgai/engine 0.5.41 → 0.5.44

package/src/render/environment-capture.ts

@@ -10,7 +10,7 @@
  * game altered.
  *
  * Consumers today: the `reflections` capability's native probe system, and
- * `godot-compat`'s Godot 3 `ReflectionProbe`.
+ * `godot-compat`'s versioned Godot `ReflectionProbe` binding.
  */
 import type { Light, Object3D, Scene, WebGLRenderer } from 'three';
 
@@ -88,6 +88,35 @@ export function withCaptureShadows(scene: Scene, enabled: boolean, capture: () =
   }
 }
 
+/**
+ * Include or suppress the scene's global sky/environment for one cube capture.
+ *
+ * This is renderer plumbing rather than a Godot policy: the caller decides whether the capture is
+ * interior. Clearing both properties is necessary because Three uses `background` for the cube's
+ * visible pixels and `environment` for the materials being photographed. Restoring only one makes
+ * a nominally isolated capture retain half of the outside lighting.
+ */
+export function withCaptureSceneEnvironment(
+  scene: Scene,
+  enabled: boolean,
+  capture: () => void,
+): void {
+  if (enabled) {
+    capture();
+    return;
+  }
+  const background = scene.background;
+  const environment = scene.environment;
+  scene.background = null;
+  scene.environment = null;
+  try {
+    capture();
+  } finally {
+    scene.background = background;
+    scene.environment = environment;
+  }
+}
+
 /**
  * Whether this renderer can run an environment capture at all.
  *

package/src/render/ibl-override-material.ts

@@ -24,10 +24,19 @@
  * hands back three's own shader object and gets out of the way.
  *
  * Consumers today: the `reflections` capability's native probe system, and
- * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * `godot-compat`'s Godot `ReflectionProbe`, whose per-fragment models are
  * deliberately different renderers over this one splice.
  */
-import { type Mesh, type MeshStandardMaterial, ShaderChunk } from 'three';
+import {
+  CubeUVReflectionMapping,
+  DataTexture,
+  type Mesh,
+  type MeshStandardMaterial,
+  RGBAFormat,
+  ShaderChunk,
+  type Texture,
+  UnsignedByteType,
+} from 'three';
 
 /** The shader object three hands to `onBeforeCompile`. */
 export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
@@ -67,6 +76,27 @@ export function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[]
   );
 }
 
+/**
+ * A black native texture whose only job is to compile Three's IBL branch.
+ *
+ * Local reflection systems can light a scene from captured probes when neither
+ * `scene.environment` nor a material `envMap` exists. Three removes both IBL
+ * entry points from that program unless one native input is present, so the
+ * caller temporarily assigns this neutral texture and restores what it found.
+ */
+export function createIblSentinelTexture(): Texture {
+  const texture = new DataTexture(
+    new Uint8Array(16 * 16 * 4),
+    16,
+    16,
+    RGBAFormat,
+    UnsignedByteType,
+  );
+  texture.mapping = CubeUVReflectionMapping;
+  texture.needsUpdate = true;
+  return texture;
+}
+
 export interface IblOverrideOptions {
   /**
    * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at

package/src/render/matcap-texture.ts

@@ -0,0 +1,92 @@
+import * as THREE from 'three';
+
+/**
+ * The neutral matcap sphere, DRAWN rather than shipped.
+ *
+ * A matcap is just a picture of a lit sphere sampled by view-space normal, so
+ * there is nothing to vendor: the same three numbers a shader would use
+ * (key, fill, rim) evaluated once per texel produce the image. Keeping it
+ * procedural means the diagnostic look has no binary asset, no license, no
+ * provenance row, and no way to go missing from a build.
+ *
+ * The look is deliberately CLAY: one warm key from the upper left, a cool
+ * fill from the lower right, a tight rim, and a broad soft highlight — the
+ * neutral sculpting material whose whole job is to let form read without
+ * colour, texture or authored lighting getting a vote.
+ */
+
+const SIZE = 256;
+
+/** sRGB transfer curve — the canvas holds display-referred bytes. */
+function encode(value: number): number {
+  const c = Math.min(1, Math.max(0, value));
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+
+function normalize(x: number, y: number, z: number): [number, number, number] {
+  const length = Math.hypot(x, y, z) || 1;
+  return [x / length, y / length, z / length];
+}
+
+export function drawNeutralMatcap(size = SIZE): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = size;
+  canvas.height = size;
+  const context = canvas.getContext('2d');
+  if (!context) return canvas;
+  const image = context.createImageData(size, size);
+
+  const key = normalize(-0.45, 0.62, 0.64);
+  const fill = normalize(0.65, -0.35, 0.5);
+  // View direction is +Z for a matcap: the sphere is drawn facing the camera.
+  const half = normalize(key[0], key[1], key[2] + 1);
+  const base = [0.7, 0.69, 0.68];
+  const fillColor = [0.34, 0.4, 0.52];
+  const rimColor = [0.85, 0.88, 1];
+
+  for (let py = 0; py < size; py++) {
+    for (let px = 0; px < size; px++) {
+      const nx = (px + 0.5) / size / 0.5 - 1;
+      const ny = 1 - (py + 0.5) / size / 0.5;
+      const r2 = nx * nx + ny * ny;
+      // Outside the unit disc a matcap is never sampled by a facing surface,
+      // but bilinear filtering reaches one texel past the silhouette. Clamp
+      // to the rim normal so the edge stays the rim colour instead of
+      // bleeding whatever happened to be there.
+      const clamped = r2 > 1;
+      const scale = clamped ? 1 / Math.sqrt(r2) : 1;
+      const x = nx * scale;
+      const y = ny * scale;
+      const z = clamped ? 0 : Math.sqrt(Math.max(0, 1 - r2));
+
+      const diffuse = Math.max(0, x * key[0] + y * key[1] + z * key[2]);
+      const fillTerm = Math.max(0, x * fill[0] + y * fill[1] + z * fill[2]);
+      const specular = Math.max(0, x * half[0] + y * half[1] + z * half[2]) ** 42 * 0.5;
+      const rim = (1 - z) ** 3.2 * 0.4;
+
+      const offset = (py * size + px) * 4;
+      for (let channel = 0; channel < 3; channel++) {
+        const lit =
+          base[channel]! * (0.16 + 0.8 * diffuse) +
+          fillColor[channel]! * 0.3 * fillTerm +
+          rimColor[channel]! * rim +
+          specular;
+        image.data[offset + channel] = Math.round(encode(lit) * 255);
+      }
+      image.data[offset + 3] = 255;
+    }
+  }
+  context.putImageData(image, 0, 0);
+  return canvas;
+}
+
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export function createNeutralMatcapTexture(size = SIZE): THREE.CanvasTexture {
+  const texture = new THREE.CanvasTexture(drawNeutralMatcap(size));
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.minFilter = THREE.LinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+  texture.needsUpdate = true;
+  return texture;
+}

package/src/render/soft-particle-depth.ts

@@ -1,6 +1,6 @@
 /**
- * Scene DEPTH for three.quarks' soft particles — the pass that makes
- * `ParticlesDescriptor.softParticles` a real effect instead of a footgun.
+ * Opaque scene DEPTH for native consumers, including three.quarks soft particles and translated
+ * Godot `hint_depth_texture` shader uniforms.
  *
  * ## What three.quarks needs, and what it does when nobody supplies it
  *
@@ -61,12 +61,10 @@
  * with the armed particle renderers and every transparent surface hidden and a
  * colour-write-disabled override material in place.
  *
- * That cost is paid ONLY while something is armed. {@link armSoftParticleDepth}
- * is called from `particles-factory.ts`'s `registerParticleSystem` when the
- * system it is registering asked for `softParticles`; with the registry empty
- * {@link SoftParticleDepthPass.render} returns before it touches the scene, so a
- * world with no soft particles pays one `Set.size` read per frame and nothing
- * else. Armed, per frame per camera it costs: one scene traverse (to find the
+ * That cost is paid ONLY while something is armed. Soft particles enter through
+ * {@link armSoftParticleDepth}; translated depth-texture shader programs enter through
+ * {@link armSceneDepthTexture}. With both registries empty {@link SoftParticleDepthPass.render}
+ * returns before it touches the scene. Armed, per frame per camera it costs: one scene traverse (to find the
  * transparent surfaces to hide), one extra geometry-only scene draw with shadow
  * updates suppressed, and a drawing-buffer-sized depth target
  * (`UnsignedIntType` depth + an unread RGBA8 colour attachment ≈ 8
@@ -110,6 +108,13 @@ import type { BatchedRenderer } from 'three.quarks';
  */
 const armed = new Map<BatchedRenderer, number>();
 
+/** Any native material/program that samples Godot's opaque-pass depth texture. */
+export interface SceneDepthTextureConsumer {
+  setDepthTexture(texture: THREE.Texture): void;
+}
+
+const depthTextureConsumers = new Map<SceneDepthTextureConsumer, number>();
+
 let farDepth: THREE.DataTexture | undefined;
 
 /**
@@ -155,6 +160,23 @@ export function disarmSoftParticleDepth(renderer: BatchedRenderer): void {
   renderer.setDepthTexture(farDepthTexture());
 }
 
+/** Retain one consumer of the same opaque scene-depth image Godot exposes as hint_depth_texture. */
+export function armSceneDepthTexture(consumer: SceneDepthTextureConsumer): void {
+  depthTextureConsumers.set(consumer, (depthTextureConsumers.get(consumer) ?? 0) + 1);
+  consumer.setDepthTexture(farDepthTexture());
+}
+
+/** Release one retained Godot depth-texture consumer without leaving a disposed target bound. */
+export function disarmSceneDepthTexture(consumer: SceneDepthTextureConsumer): void {
+  const remaining = (depthTextureConsumers.get(consumer) ?? 0) - 1;
+  if (remaining > 0) {
+    depthTextureConsumers.set(consumer, remaining);
+    return;
+  }
+  if (!depthTextureConsumers.delete(consumer)) return;
+  consumer.setDepthTexture(farDepthTexture());
+}
+
 /** Test/diagnostic read of the registry — how many renderers a pass would consider. */
 export function armedSoftParticleRendererCount(): number {
   return armed.size;
@@ -243,12 +265,12 @@ export function createSoftParticleDepthPass(): SoftParticleDepthPass {
 
   return {
     render(renderer, scene, camera): void {
-      if (armed.size === 0) return;
+      if (armed.size === 0 && depthTextureConsumers.size === 0) return;
       const consumers: BatchedRenderer[] = [];
       for (const candidate of armed.keys()) {
         if (isUnder(candidate, scene)) consumers.push(candidate);
       }
-      if (consumers.length === 0) return;
+      if (consumers.length === 0 && depthTextureConsumers.size === 0) return;
 
       // See REQUIRED_RENDERER_MEMBERS: a renderer that cannot swap render
       // targets cannot run a prepass, and the frame is worth more than the
@@ -259,9 +281,9 @@ export function createSoftParticleDepthPass(): SoftParticleDepthPass {
           warnedIncapable = true;
           // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to throwing out of the frame
           console.warn(
-            `soft-particle depth prepass skipped: this renderer implements none of ${missing.join(', ')}. ` +
-              `${String(consumers.length)} particle batch(es) keep the inert far-depth default, so they ` +
-              'draw unfaded — the same pixels as a batch that never declared a proximity fade. A real ' +
+            `opaque scene-depth prepass skipped: this renderer is missing ${missing.join(', ')}. ` +
+              `${String(consumers.length)} particle batch(es) and ${String(depthTextureConsumers.size)} ` +
+              'shader consumer(s) keep the inert far-depth default. A real ' +
               'WebGLRenderer has these; a design-time settle stand-in does not.',
           );
         }
@@ -317,12 +339,19 @@ export function createSoftParticleDepthPass(): SoftParticleDepthPass {
         hidden.length = 0;
       }
 
-      for (const consumer of consumers) consumer.setDepthTexture(rt.depthTexture);
+      const renderedDepth = rt.depthTexture;
+      if (renderedDepth === null) {
+        throw new Error('opaque scene-depth prepass lost its authored depth texture.');
+      }
+      for (const consumer of consumers) consumer.setDepthTexture(renderedDepth);
+      for (const consumer of depthTextureConsumers.keys()) consumer.setDepthTexture(renderedDepth);
     },
     dispose(): void {
       // Every consumer this pass fed now points at a texture that is about to
       // go away. Hand them the inert default back rather than a disposed one.
       for (const candidate of armed.keys()) candidate.setDepthTexture(farDepthTexture());
+      for (const consumer of depthTextureConsumers.keys())
+        consumer.setDepthTexture(farDepthTexture());
       target?.dispose();
       target = null;
       override.dispose();

package/src/render/viewport-shading.ts

@@ -1,7 +1,15 @@
 import * as THREE from 'three';
+import { createNeutralMatcapTexture } from './matcap-texture';
 
 /** Temporary developer-facing shading modes. These never become scene data. */
-export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+export type ViewportShadingMode =
+  | 'solid'
+  | 'clay'
+  | 'unlit'
+  | 'wireframe'
+  | 'matcap'
+  | 'normals'
+  | 'overdraw';
 
 type MaterialPair = {
   clay: THREE.MeshStandardMaterial;
@@ -30,6 +38,16 @@ function textureOf(material: THREE.Material, key: 'map' | 'alphaMap'): THREE.Tex
 export class ViewportShadingRenderer {
   private readonly _derived = new Map<THREE.Material, MaterialPair>();
   private readonly _normals = new THREE.MeshNormalMaterial();
+  /**
+   * The clay/sculpt look. Built on FIRST USE, not at construction: the matcap
+   * sphere is drawn into a 2D canvas, and every ViewportShadingRenderer that
+   * only ever draws `solid` would otherwise pay for a texture nobody samples.
+   * `toneMapped: false` for the same reason the overdraw material sets it —
+   * a diagnostic look must read exactly as authored, not as the document's
+   * exposure and tone curve happen to grade it.
+   */
+  private _matcap: THREE.MeshMatcapMaterial | null = null;
+  private _matcapTexture: THREE.Texture | null = null;
   private readonly _overdraw = new THREE.MeshBasicMaterial({
     color: 0xffffff,
     transparent: true,
@@ -81,6 +99,10 @@ export class ViewportShadingRenderer {
     this._derived.clear();
     this._normals.dispose();
     this._overdraw.dispose();
+    this._matcap?.dispose();
+    this._matcapTexture?.dispose();
+    this._matcap = null;
+    this._matcapTexture = null;
   }
 
   private _materialFor(
@@ -89,6 +111,16 @@ export class ViewportShadingRenderer {
   ): THREE.Material {
     if (mode === 'normals') return this._normals;
     if (mode === 'overdraw') return this._overdraw;
+    if (mode === 'matcap') {
+      if (!this._matcap) {
+        this._matcapTexture = createNeutralMatcapTexture();
+        this._matcap = new THREE.MeshMatcapMaterial({
+          matcap: this._matcapTexture,
+          toneMapped: false,
+        });
+      }
+      return this._matcap;
+    }
 
     let pair = this._derived.get(material);
     if (!pair) {

package/src/runtime/create-runtime.ts

@@ -375,14 +375,15 @@ export async function createGameRuntime(config: RootsRuntimeConfig): Promise<Gam
 // ---------------------------------------------------------------------------
 
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
- *  roots: a headless mount never calls a render-phase method on
- *  `host.renderer` at all, so
- *  this only needs to satisfy the handful of calls THIS file itself makes
+ *  roots: draw submission is inert while native scene/component evaluation
+ *  still runs. This satisfies Fiber's custom-renderer gate and the calls
  *  (`setPixelRatio`/`setClearColor`/`setSize` at mount, `dispose`/
  *  `forceContextLoss` at teardown) — never a real GL call. Node conformance
  *  tests only; never used when `headless` is left `false`/absent. */
-function createHeadlessRendererStub(): THREE.WebGLRenderer {
+function createHeadlessRendererStub(canvas: HTMLCanvasElement): THREE.WebGLRenderer {
   return {
+    domElement: canvas,
+    render() {},
     setPixelRatio() {},
     setClearColor() {},
     setSize() {},
@@ -477,7 +478,7 @@ async function mountOneThreeRoot(
 ): Promise<OneRootResult> {
   const { game, canvas, w, h, dpr, isBottom, headless, assets, antialias } = ctx;
   const renderer = headless
-    ? createHeadlessRendererStub()
+    ? createHeadlessRendererStub(canvas)
     : createHostRenderer(
         canvas,
         w,

package/src/runtime/debug-bridge.ts

@@ -246,10 +246,13 @@ const HOLD_FOR_POLL_MS = 50;
  *  the same neighborhood. */
 const HOLD_FOR_STALL_POLL_LIMIT = 100;
 
-/** Ticks driven per synchronous starved-loop batch. Sized like
+/** Maximum ticks driven per synchronous starved-loop batch. Sized like
  *  `fast-forward.ts`'s own batching rationale: big enough that per-batch
  *  bookkeeping is negligible, small enough that one batch of a complex game's
- *  phases stays a short synchronous burst. */
+ *  phases stays a short synchronous burst. The actual batch is capped to the
+ *  hold's remaining fixed-tick budget below; otherwise a one-tick `tap()` in a
+ *  hidden tab becomes a 60-tick hold and releases only after short gameplay
+ *  interactions have already completed. */
 const STARVED_DRIVE_BATCH_TICKS = 60;
 
 /** Hard ceiling on starved-drive batches for ONE hold — `STARVED_DRIVE_BATCH_TICKS
@@ -276,6 +279,9 @@ interface HoldClockReading {
   simSeconds: number;
   tick: number;
   loopLiveness?: GameLoopLiveness | null;
+  /** Present for every real Game-backed debug registry. Optional only because a bare adapter
+   *  stand-in can omit it; that case drives one conservative tick at a time. */
+  fixedDt?: number;
 }
 
 /**
@@ -335,7 +341,19 @@ export async function waitForHoldBudget(
       if (!driveStarvedTicks) return { stalled: true, starvedWithoutDriver: true };
       if (starvedBatches >= STARVED_DRIVE_MAX_BATCHES) return { stalled: true };
       starvedBatches += 1;
-      driveStarvedTicks(STARVED_DRIVE_BATCH_TICKS);
+      const remaining = simSeconds - (current.simSeconds - start.simSeconds);
+      const fixedDt = current.fixedDt;
+      // A real Game publishes its fixed timestep, so drive exactly the number of whole ticks
+      // still needed (up to the throughput cap). Subtract a tiny ratio tolerance before `ceil`:
+      // repeated floating-point additions can leave an integer tick budget a few ulps above its
+      // mathematical value, and that must not manufacture one extra held-input frame. A bare
+      // adapter that does not publish `fixedDt` takes the conservative path: one tick, re-read,
+      // repeat. Exact input duration matters more than batching a non-Game test stand-in.
+      const ticksForRemaining =
+        fixedDt !== undefined && Number.isFinite(fixedDt) && fixedDt > 0
+          ? Math.max(1, Math.ceil(remaining / fixedDt - 1e-9))
+          : 1;
+      driveStarvedTicks(Math.min(STARVED_DRIVE_BATCH_TICKS, ticksForRemaining));
       const after = readTime();
       // A batch that moved neither the tick counter nor the sim clock means
       // the drive is a no-op (paused game, torn-down runtime) — the same

package/src/runtime/mount-manifest.ts

@@ -227,6 +227,17 @@ export type MountedManifestSession = GameSession;
  */
 function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
   if (typeof value !== 'object' || value === null) return false;
+  // The loader's own output field is the surest mark: a raw manifest never
+  // carries it (the schema is strict). Without this, a RESOLVED manifest
+  // with `roots: []` — a models project, nothing to play — fell through to
+  // `loadGameManifest`, whose strict parse refused THIS key ("Unrecognized
+  // key: deferredConfigurationKinds") instead of saying "no roots"
+  // (blind lantern round 21, 2026-09-06, sent there by the never-played nag).
+  if (
+    Array.isArray((value as { deferredConfigurationKinds?: unknown }).deferredConfigurationKinds)
+  ) {
+    return true;
+  }
   const roots = (value as { roots?: unknown }).roots;
   if (!Array.isArray(roots) || roots.length === 0) return false;
   return roots.every((world) => {
@@ -245,7 +256,7 @@ function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
  */
 export function resolveManifest(raw: unknown): ResolvedGameManifest {
   if (looksAlreadyResolved(raw)) return raw;
-  return loadGameManifest(raw);
+  return loadGameManifest(raw, { configurationKinds: 'defer' });
 }
 
 // ---------------------------------------------------------------------------
@@ -454,7 +465,7 @@ export async function mountManifestRoots(opts: MountManifestOptions): Promise<Ga
     // `manifest/load.ts`) is `{ room, module } | undefined`; its mere presence
     // is the "this project declares a room" signal, independent of
     // whether/when the game actually joins it.
-    if (manifest.server) {
+    if (manifest.configurations.some((configuration) => configuration.kind === 'process')) {
       debugRegistry.setRoomDeclared(true);
     }
     // Defect 5 fix: `maybeInstallDebugBridge` adds `window` listeners and

package/src/settings/schema.ts

@@ -0,0 +1,127 @@
+/**
+ * THE SETTINGS DOCUMENT — the Zod truth for the two shared settings layers
+ * (ARCHITECTURE-CORE §Editor chrome, "Settings have four layers with named
+ * homes"):
+ *
+ *   ~/.vgai/settings.json     the USER layer — one person, every project
+ *   <project>/.vgai/settings.json   the PROJECT layer — one project, committed,
+ *                             every person who opens it
+ *
+ * Both files 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` →
+ * `packages/engine/schemas/vgai-settings.schema.json`) is what an editor
+ * autocompletes against when a person edits either file by hand.
+ *
+ * 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").
+ */
+import { z } from 'zod';
+
+const RegionVisibility = z.enum(['shown', 'hidden']);
+
+export const ChromeRegionsSettingsSchema = z
+  .object({
+    tabs: RegionVisibility.optional().describe('The document tab strip.'),
+    header: RegionVisibility.optional().describe('The top header bar.'),
+    shelf: RegionVisibility.optional().describe('The utility shelf.'),
+    inspector: z
+      .enum(['column', 'properties'])
+      .optional()
+      .describe('Inspector presentation: the narrow docked column or a properties panel.'),
+    drawer: RegionVisibility.optional().describe('The bottom drawer.'),
+  })
+  .strict()
+  .describe('Which chrome regions a style bundle shows or hides.');
+
+export const EditorSettingsSchema = z
+  .object({
+    $schema: z
+      .string()
+      .optional()
+      .describe('JSON Schema pointer for editor autocomplete; ignored by the editor.'),
+    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` or `glass`).'),
+        regions: ChromeRegionsSettingsSchema.optional(),
+      })
+      .strict()
+      .optional()
+      .describe('How the editor chrome looks.'),
+    keymap: z.string().optional().describe('Active keymap preset id (`vgai`, `blender`, …).'),
+    workspace: z
+      .object({
+        default: z
+          .string()
+          .optional()
+          .describe(
+            'The workspace a fresh checkout opens in, when it applies to the project shape.',
+          ),
+      })
+      .strict()
+      .optional()
+      .describe('Workspace defaults.'),
+    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';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Deep-merge plain objects; anything else (primitives, arrays, null)
+ *  replaces. `merge(user, project)` is the effective document. */
+export function mergeEditorSettings(base: EditorSettings, over: EditorSettings): EditorSettings {
+  const out: Record<string, unknown> = { ...base };
+  const patch = over as Record<string, unknown>;
+  for (const key of Object.keys(patch)) {
+    const value = patch[key];
+    const current = out[key];
+    out[key] =
+      isPlainObject(current) && isPlainObject(value)
+        ? mergeEditorSettings(current as EditorSettings, value as EditorSettings)
+        : value;
+  }
+  return out as EditorSettings;
+}
+
+/** Validate a raw document. The result carries the parsed settings or the
+ *  issues, spelled for a person who has the file open. */
+export function parseEditorSettings(
+  raw: unknown,
+): { settings: EditorSettings; issues: [] } | { settings: null; issues: string[] } {
+  const result = EditorSettingsSchema.safeParse(raw);
+  if (result.success) return { settings: result.data, issues: [] };
+  return {
+    settings: null,
+    issues: result.error.issues.map((issue) =>
+      issue.path.length ? `${issue.path.join('.')}: ${issue.message}` : issue.message,
+    ),
+  };
+}