@volter/project 0.0.0-stage → 0.5.203

package/src/settings/keys.ts

@@ -0,0 +1,152 @@
+/**
+ * THE SETTINGS KEY TABLE — every setting there is, as ONE dotted `volter.*` name
+ * per leaf, with the type and the sentence a person reads beside it.
+ *
+ * ## Why it exists, and why it is DERIVED
+ *
+ * Under the Code-OSS frame (ARCHITECTURE-CORE §The core is Code-OSS, U7) the
+ * settings layers are the configuration service's, and a configuration service
+ * speaks FLAT DOTTED KEYS — `volter.appearance.palette` — 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
+ * 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/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
+ * configuration contribution.
+ *
+ * ## The `volter.` prefix is part of the key, everywhere
+ *
+ * Not a thing the frame adds on the way in. One spelling in the door
+ * (`EditorHost.settings`), in `.vscode/settings.json`, in the Settings editor,
+ * and in what the editor's `eval` command prints — because the moment there are two, a reader
+ * has to know which side of which seam they are on to know which to type.
+ */
+import { z } from 'zod';
+import { type EditorSettings, EditorSettingsSchema } from './schema';
+
+/** The namespace every settings key carries. */
+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`. */
+  readonly key: string;
+  /** The path into the settings document: `['appearance', 'palette']`. */
+  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. */
+  readonly type?: string | undefined;
+  /** The closed set of values, when the field is an enum. */
+  readonly values?: readonly string[] | undefined;
+  /** The field's own `.describe()` sentence — the one a person reads. */
+  readonly description: string;
+}
+
+type JsonSchemaNode = {
+  type?: string | string[];
+  enum?: readonly string[];
+  description?: string;
+  properties?: Record<string, JsonSchemaNode>;
+};
+
+function walk(node: JsonSchemaNode, path: readonly string[], out: SettingsKeyDescriptor[]): void {
+  if (node.properties) {
+    for (const [name, child] of Object.entries(node.properties)) walk(child, [...path, name], out);
+    return;
+  }
+  // `$schema` is the autocomplete pointer the document carries for a person
+  // editing it by hand; it describes the file, not the editor, and there is
+  // nothing for a settings UI to show.
+  if (path.length === 1 && path[0] === '$schema') return;
+  out.push({
+    key: [SETTINGS_KEY_PREFIX, ...path].join('.'),
+    path,
+    type: typeof node.type === 'string' ? node.type : undefined,
+    values: node.enum,
+    description: node.description ?? '',
+  });
+}
+
+let table: readonly SettingsKeyDescriptor[] | null = null;
+let byKey: ReadonlyMap<string, SettingsKeyDescriptor> | null = null;
+
+/** Every settings key, in the schema's own declaration order. */
+export function settingsKeys(): readonly SettingsKeyDescriptor[] {
+  if (!table) {
+    const out: SettingsKeyDescriptor[] = [];
+    walk(z.toJSONSchema(EditorSettingsSchema, { io: 'input' }) as JsonSchemaNode, [], out);
+    table = out;
+    byKey = new Map(out.map((entry) => [entry.key, entry]));
+  }
+  return table;
+}
+
+/** One key's declaration, or `null` for a name no schema field owns. A caller
+ *  that gets `null` is holding a key nobody can read — never a silent miss. */
+export function settingsKey(key: string): SettingsKeyDescriptor | null {
+  settingsKeys();
+  return byKey?.get(key) ?? null;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Read one key out of a settings document. `undefined` means the document
+ *  does not carry it — which is what "this layer is silent about it" means. */
+export function readSettingsValue(document: EditorSettings, key: string): unknown {
+  const descriptor = settingsKey(key);
+  if (!descriptor) return undefined;
+  let cursor: unknown = document;
+  for (const segment of descriptor.path) {
+    if (!isPlainObject(cursor)) return undefined;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+
+/** A settings document built from dotted keys — the inverse of
+ *  {@link flattenSettings}, and what turns a per-key configuration service back
+ *  into the nested document every reader in the editor already speaks. */
+export function settingsFromEntries(entries: Iterable<readonly [string, unknown]>): EditorSettings {
+  const document: Record<string, unknown> = {};
+  for (const [key, value] of entries) {
+    if (value === undefined) continue;
+    const descriptor = settingsKey(key);
+    if (!descriptor) continue;
+    let cursor = document;
+    for (const segment of descriptor.path.slice(0, -1)) {
+      const next = cursor[segment];
+      if (!isPlainObject(next)) cursor[segment] = {};
+      cursor = cursor[segment] as Record<string, unknown>;
+    }
+    const leaf = descriptor.path[descriptor.path.length - 1];
+    if (leaf !== undefined) cursor[leaf] = value;
+  }
+  return document as EditorSettings;
+}
+
+/** A settings document as dotted key/value pairs, skipping keys it is silent
+ *  about. A value at a path no schema field owns is DROPPED rather than
+ *  carried: the document is `.strict()`, so such a path can only come from a
+ *  layer this build does not understand. */
+export function flattenSettings(document: EditorSettings): ReadonlyMap<string, unknown> {
+  const out = new Map<string, unknown>();
+  for (const descriptor of settingsKeys()) {
+    const value = readSettingsValue(document, descriptor.key);
+    if (value !== undefined) out.set(descriptor.key, value);
+  }
+  return out;
+}

package/src/settings/schema.ts

@@ -0,0 +1,151 @@
+/**
+ * THE SETTINGS DOCUMENT — the Zod truth for the two shared settings layers
+ * (ARCHITECTURE-CORE §Editor chrome, "Settings have four layers with named
+ * homes"):
+ *
+ *   ~/.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
+ *
+ * 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/project/schemas/volter-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({
+    workspaceTabs: RegionVisibility.optional().describe(
+      "The workspace tab strip in the top bar (Blender's); 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.'),
+    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.",
+    ),
+    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.",
+    ),
+    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.",
+      ),
+  })
+  .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`, `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`, …).'),
+    play: z
+      .object({
+        keepPanelsVisible: z
+          .boolean()
+          .optional()
+          .describe(
+            '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.',
+          ),
+      })
+      .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';
+
+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,
+    ),
+  };
+}