@volter/editor-core 0.5.57

package/src/keymap-presets.ts

@@ -0,0 +1,401 @@
+import type { EditorKeyActionId, KeyChord, KeymapContribution } from '@volter/editor-sdk/looks';
+import { editorConsole } from './editor-console';
+import {
+  adapterSettings,
+  projectSettings,
+  subscribeSettings,
+  updatePreferenceSettings,
+  updateProjectSettings,
+  userSettings,
+} from './settings-store';
+
+export type { EditorKeyActionId, KeyChord } from '@volter/editor-sdk/looks';
+/**
+ * KEYMAPS — the binding table behind every editor keyboard action.
+ *
+ * The ruling (docs/ARCHITECTURE-CORE.md §Editor chrome, the "Workspaces are
+ * task-named layout memories" bullet, final sentence): *"Keymaps are
+ * orthogonal to workspaces: a `keymap` setting selects the binding table
+ * (`vgai` default; `blender` — G/R/S, A, Alt+A, `.` frame) through one
+ * indirection at the action-registry/hotkey seam."*
+ *
+ * ONE INDIRECTION means exactly this: nothing in the editor spells a literal
+ * key for a keyboard action any more. `editor-hotkeys.ts` builds its
+ * `HotkeyBinding`s from {@link keyChordsFor}, and every place that PRINTS a
+ * shortcut — the command palette (via `action-registry.ts`), the viewport
+ * toolstrip tooltips, the camera-controls hint, the snap transient hint —
+ * renders {@link shortcutFor} over the same table. Switch the keymap and the
+ * chrome tells the truth on the next paint, with no reload.
+ *
+ * The two axes this module is deliberately NOT: it is not a workspace (that is
+ * `workspace-presets.ts` — layout, keyed per project) and not an appearance
+ * preference (`theme-preference.ts`). A keymap is a per-user input preference,
+ * persisted the way that module persists palette/material: one settings
+ * key, lazily read, written on change, broadcast to `useSyncExternalStore`
+ * subscribers, and simply falling back to the default when unreadable —
+ * nothing a user authored is at stake in a stored preference.
+ *
+ * WHAT THIS DOES NOT GOVERN — the boundary, stated once: this table is the
+ * EDITOR's own chrome bindings, consumed by `hotkeys.ts`'s single `keydown`
+ * dispatcher on the editor's window. Play-mode input isolation is a different
+ * mechanism entirely and is untouched by a keymap switch: the engine's
+ * `InputManager.setEnabled` gate plus `gated-globals.ts`'s lexical
+ * `window`/`document` shadow over project modules decide whether GAME code
+ * hears a key. A game never reads this table, and no keymap entry can widen or
+ * narrow what a running game receives.
+ */
+
+/** Any registered keymap's id: the editor's own `vgai`, or one a package
+ *  contributes (`@volter/editor-sdk/looks`, `KeymapContribution`). */
+export type EditorKeymapId = string;
+
+export interface EditorKeymapDescriptor {
+  readonly id: EditorKeymapId;
+  readonly title: string;
+  readonly description: string;
+}
+
+/** The editor's OWN keymap, the one every project has. Every other keymap is
+ *  a package's contribution (Blender's ships with `@volter/editor-blender`). */
+const BUILT_IN_KEYMAPS: readonly EditorKeymapDescriptor[] = Object.freeze([
+  {
+    id: 'vgai',
+    title: 'vgai',
+    description: "The editor's own bindings: W/E/R gizmo modes, Ctrl+A select all, F frames.",
+  },
+] satisfies readonly EditorKeymapDescriptor[]);
+
+interface ContributedKeymap {
+  readonly descriptor: EditorKeymapDescriptor;
+  readonly table: EditorKeymapTable;
+}
+const contributedKeymaps = new Map<string, ContributedKeymap>();
+let registryVersion = 0;
+
+/** Built-ins first, then contributions in registration order — the switch
+ *  surfaces (View menu, palette) enumerate this. */
+export function editorKeymaps(): readonly EditorKeymapDescriptor[] {
+  return [
+    ...BUILT_IN_KEYMAPS,
+    ...[...contributedKeymaps.values()].map((entry) => entry.descriptor),
+  ];
+}
+
+export function editorKeymapsVersion(): number {
+  return registryVersion;
+}
+
+/**
+ * Register a package's keymap (`workspace.keymap` contribution). The table is
+ * the editor's own bindings with the contribution's chords over them, so a
+ * keymap declares only where it differs. Returns the unregister. A duplicate
+ * id throws — ids are the `keymap` setting's values.
+ */
+export function registerContributedKeymap(contribution: KeymapContribution): () => void {
+  if (
+    BUILT_IN_KEYMAPS.some((entry) => entry.id === contribution.id) ||
+    contributedKeymaps.has(contribution.id)
+  )
+    throw new Error(
+      `registerContributedKeymap: keymap "${contribution.id}" is already registered.`,
+    );
+  const entry: ContributedKeymap = {
+    descriptor: {
+      id: contribution.id,
+      title: contribution.title,
+      description: contribution.description,
+    },
+    table: Object.freeze({ ...VGAI_KEYMAP, ...contribution.bindings }) as EditorKeymapTable,
+  };
+  contributedKeymaps.set(contribution.id, entry);
+  registryVersion++;
+  // A stored preference this contribution satisfies applies now, not on the
+  // next reload: the cache re-reads the setting against the wider registry.
+  cachedKeymap = null;
+  emit();
+  return () => {
+    if (contributedKeymaps.get(contribution.id) !== entry) return;
+    contributedKeymaps.delete(contribution.id);
+    registryVersion++;
+    cachedKeymap = null;
+    emit();
+  };
+}
+
+export function isEditorKeymapId(value: unknown): value is EditorKeymapId {
+  return (
+    typeof value === 'string' &&
+    (BUILT_IN_KEYMAPS.some((entry) => entry.id === value) || contributedKeymaps.has(value))
+  );
+}
+
+export type EditorKeymapTable = Readonly<Record<EditorKeyActionId, readonly KeyChord[]>>;
+
+/**
+ * The vgai table reproduces the bindings the editor shipped before keymaps
+ * existed, chord for chord. It is the regression bar: any change here is a
+ * change to the default editor, not to a keymap.
+ */
+const VGAI_KEYMAP: EditorKeymapTable = Object.freeze({
+  'edit.undo': [{ key: 'z', mod: true }],
+  // Ctrl+Y mirrors Ctrl+Shift+Z (Windows convention).
+  'edit.redo': [
+    { key: 'z', mod: true, shift: true },
+    { key: 'y', mod: true },
+  ],
+  'edit.copy': [{ key: 'c', mod: true }],
+  'edit.cut': [{ key: 'x', mod: true }],
+  'edit.paste': [{ key: 'v', mod: true }],
+  'edit.duplicate': [{ key: 'd', mod: true }],
+  'edit.group': [{ key: 'g', mod: true }],
+  'edit.wrap': [{ key: 'g', mod: true, alt: true }],
+  'edit.unwrap': [{ key: 'g', mod: true, shift: true }],
+  'edit.selectAll': [{ key: 'a', mod: true }],
+  // No dedicated chord: Escape is the vgai deselect, and it carries the
+  // scope-exit semantics too (`edit.exitScopeOrDeselect`). An empty chord list
+  // registers no binding; the printed hint falls back to Escape's.
+  'edit.deselectAll': [],
+  'edit.save': [{ key: 's', mod: true }],
+  'edit.delete': [{ key: 'delete' }, { key: 'backspace' }],
+  'edit.enterScope': [{ key: 'enter' }],
+  'edit.exitScopeOrDeselect': [{ key: 'escape' }],
+  'edit.nudgeUp': [{ key: 'arrowup' }],
+  'edit.nudgeUpCoarse': [{ key: 'arrowup', shift: true }],
+  'edit.nudgeDown': [{ key: 'arrowdown' }],
+  'edit.nudgeDownCoarse': [{ key: 'arrowdown', shift: true }],
+  'edit.nudgeLeft': [{ key: 'arrowleft' }],
+  'edit.nudgeLeftCoarse': [{ key: 'arrowleft', shift: true }],
+  'edit.nudgeRight': [{ key: 'arrowright' }],
+  'edit.nudgeRightCoarse': [{ key: 'arrowright', shift: true }],
+  'view.resetPan': [{ key: '0', mod: true }],
+  'view.commandPalette': [{ key: 'k', mod: true }],
+  'view.toggleConsole': [{ key: '`' }],
+  'view.focusMode': [{ key: 'f', mod: true, shift: true }],
+  // Blender's own workspace cycle keys, and free in this registry.
+  'workspace.cycleNext': [{ key: 'pagedown', mod: true }],
+  'workspace.cyclePrevious': [{ key: 'pageup', mod: true }],
+  // UNBOUND HERE, DELIBERATELY: this editor's own four transform tools already
+  // hold T/W/E/R, and the Select tool arrived with the Blender look (whose
+  // keymap puts it on Blender's own `W`). An empty list is the table's way of
+  // saying a keymap binds nothing to an action, and the strip's button is the
+  // tool's other door.
+  'transform.select': [],
+  'transform.combined': [{ key: 't' }],
+  'transform.translate': [{ key: 'w' }],
+  'transform.rotate': [{ key: 'e' }],
+  'transform.scale': [{ key: 'r' }],
+  'viewport.toggleSnap': [{ key: 's', shift: true }],
+  'viewport.frameSelection': [{ key: 'f' }],
+  'viewport.cyclePivot': [{ key: '.' }],
+  'viewport.vertexSnapHold': [{ key: 'v' }],
+  'viewport.snapToFloor': [{ key: '', code: 'PageDown' }],
+  'view.top': [{ key: '', code: 'Numpad7' }],
+  'view.front': [{ key: '', code: 'Numpad1' }],
+  'view.right': [{ key: '', code: 'Numpad3' }],
+  'view.perspective': [{ key: '', code: 'Numpad5' }],
+} satisfies EditorKeymapTable);
+
+// ---------------------------------------------------------------------------
+// The setting
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_EDITOR_KEYMAP: EditorKeymapId = 'vgai';
+
+let cachedKeymap: EditorKeymapId | null = null;
+let settingsSyncInstalled = false;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+/** The editor's own keymap ids — the ones that exist in every project. */
+function isBuiltInKeymapId(value: unknown): boolean {
+  return typeof value === 'string' && BUILT_IN_KEYMAPS.some((entry) => entry.id === value);
+}
+
+/** What the PROJECT selects: its adapter's declaration, its own settings over it. */
+function projectScopedKeymap(): unknown {
+  return projectSettings().keymap ?? adapterSettings().keymap;
+}
+
+/**
+ * A keymap a PACKAGE contributes is project-scoped: it exists only where that
+ * package is declared, so only the project may select it — its adapter
+ * (`editor: { keymap: blenderKeymap }`) or its own `.vgai/settings.json`. The
+ * USER layer chooses among the editor's own, because a cross-project default
+ * naming a skew's bindings is how a models project's G/R/S reached a game
+ * project that merely happens to declare the same package.
+ */
+function readStoredKeymap(): EditorKeymapId {
+  const scoped = projectScopedKeymap();
+  if (isEditorKeymapId(scoped)) return scoped;
+  const preferred = userSettings().keymap;
+  return isBuiltInKeymapId(preferred) ? (preferred as EditorKeymapId) : DEFAULT_EDITOR_KEYMAP;
+}
+
+const saidUnavailable = new Set<string>();
+/**
+ * Say, once per id, that the STORED keymap is one nothing in this project
+ * contributes, so a models project opened without its Blender package
+ * explains the W/E/R it is showing. Called by the loader AFTER a contribution
+ * pass has registered what the project's packages ship — asked at boot it
+ * would warn about every keymap a package is about to contribute (measured
+ * 2026-09-17: "blender is not available" on a project whose mesh package
+ * registered it a moment later).
+ */
+export function reportUnavailableKeymap(): void {
+  const stored = projectScopedKeymap();
+  if (typeof stored !== 'string' || stored === DEFAULT_EDITOR_KEYMAP) return;
+  if (isEditorKeymapId(stored) || saidUnavailable.has(stored)) return;
+  saidUnavailable.add(stored);
+  editorConsole.warn(
+    `Keymap "${stored}" is not available in this project: no declared package contributes it ` +
+      `(a package ships one as a \`workspace.keymap\` contribution). Using "${DEFAULT_EDITOR_KEYMAP}".`,
+    'editor',
+  );
+}
+
+/** The setting is `keymap` in the settings layers (`settings-store.ts`); a
+ *  load finishing or a project's own override becoming active must not leave
+ *  this module's cache lying. Installed on first read so the module has no
+ *  load-time side effect. */
+function ensureSettingsSync(): void {
+  if (settingsSyncInstalled) return;
+  settingsSyncInstalled = true;
+  subscribeSettings(() => {
+    const next = readStoredKeymap();
+    if (next === cachedKeymap) return;
+    cachedKeymap = next;
+    emit();
+  });
+}
+
+/** Current keymap id (`useSyncExternalStore`-shaped snapshot). */
+export function activeEditorKeymap(): EditorKeymapId {
+  ensureSettingsSync();
+  cachedKeymap ??= readStoredKeymap();
+  return cachedKeymap;
+}
+
+/**
+ * Switch keymaps. Live: every binding registration re-derives from the new
+ * table on this call (`editor-hotkeys.ts`) and every printed hint re-renders,
+ * so there is no reload and no restart. Choosing one of the editor's OWN
+ * keymaps writes where the key is declared; choosing a package's writes the
+ * PROJECT layer, because that is the only layer a contributed keymap is read
+ * from (see {@link readStoredKeymap}) — a gesture must land somewhere it wins.
+ */
+export function setEditorKeymapPreference(id: EditorKeymapId): void {
+  if (activeEditorKeymap() === id) return;
+  cachedKeymap = id;
+  if (isBuiltInKeymapId(id)) updatePreferenceSettings({ keymap: id });
+  else updateProjectSettings({ keymap: id });
+  emit();
+}
+
+export function subscribeEditorKeymap(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function __resetEditorKeymapForTest(): void {
+  cachedKeymap = null;
+  listeners.clear();
+}
+
+// ---------------------------------------------------------------------------
+// The one lookup
+// ---------------------------------------------------------------------------
+
+/** The active table's chords for one action. Empty means deliberately unbound. */
+export function keyChordsFor(action: EditorKeyActionId): readonly KeyChord[] {
+  return keymapTable(activeEditorKeymap())[action];
+}
+
+/** A named table, for a surface that must show a keymap it is not running.
+ *  An unregistered id answers the editor's own table. */
+export function keymapTable(id: EditorKeymapId): EditorKeymapTable {
+  return contributedKeymaps.get(id)?.table ?? VGAI_KEYMAP;
+}
+
+// ---------------------------------------------------------------------------
+// Display
+// ---------------------------------------------------------------------------
+
+function isMacPlatform(): boolean {
+  return typeof navigator !== 'undefined' && navigator.platform.includes('Mac');
+}
+
+/** Named keys whose label is neither the raw `key` nor its uppercase form. */
+const KEY_LABELS: Readonly<Record<string, string>> = {
+  delete: 'Del',
+  backspace: 'Backspace',
+  escape: 'Esc',
+  enter: 'Enter',
+  pagedown: 'PgDn',
+  pageup: 'PgUp',
+  arrowup: '↑',
+  arrowdown: '↓',
+  arrowleft: '←',
+  arrowright: '→',
+  ' ': 'Space',
+  tab: 'Tab',
+};
+
+const CODE_LABELS: Readonly<Record<string, string>> = {
+  Numpad0: 'Num0',
+  Numpad1: 'Num1',
+  Numpad2: 'Num2',
+  Numpad3: 'Num3',
+  Numpad4: 'Num4',
+  Numpad5: 'Num5',
+  Numpad6: 'Num6',
+  Numpad7: 'Num7',
+  Numpad8: 'Num8',
+  Numpad9: 'Num9',
+  NumpadDecimal: 'Num.',
+  PageDown: 'PgDn',
+  PageUp: 'PgUp',
+  End: 'End',
+  KeyG: 'G',
+  KeyH: 'H',
+  KeyJ: 'J',
+  KeyK: 'K',
+};
+
+function keyLabel(chord: KeyChord): string {
+  if (chord.code) return CODE_LABELS[chord.code] ?? chord.code;
+  return KEY_LABELS[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key);
+}
+
+/**
+ * Render one chord the way the editor's chrome has always rendered them —
+ * BOTH existing conventions preserved verbatim, because changing a printed
+ * string is a visible regression: a mod-prefixed chord reads `⌘⇧Z` / `Ctrl+⇧Z`
+ * (the command palette's shape), while a modless chord spells its modifiers
+ * out, `Shift+S` (the toolstrip's shape).
+ */
+export function formatChord(chord: KeyChord): string {
+  const label = keyLabel(chord);
+  if (chord.mod) {
+    const mod = isMacPlatform() ? '⌘' : 'Ctrl+';
+    return `${mod}${chord.alt ? '⌥' : ''}${chord.shift ? '⇧' : ''}${label}`;
+  }
+  const parts: string[] = [];
+  if (chord.alt) parts.push('Alt');
+  if (chord.shift) parts.push('Shift');
+  parts.push(label);
+  return parts.join('+');
+}
+
+/**
+ * The printed hint for an action under the ACTIVE keymap — the first chord,
+ * which every table lists in "the one to teach" order. `undefined` when the
+ * action is deliberately unbound, so a caller can fall back or omit the hint
+ * rather than print a lie.
+ */
+export function shortcutFor(action: EditorKeyActionId): string | undefined {
+  const chord = keyChordsFor(action)[0];
+  return chord ? formatChord(chord) : undefined;
+}

package/src/layout-policy.ts

@@ -0,0 +1,31 @@
+/** Presentation chosen by mounted layout code. No game or website names live here. */
+import type { WorkspaceArrangement } from '@volter/editor-sdk/layout-arrangements';
+import { activeProjectKey } from './active-project';
+export interface LayoutPolicy {
+  readonly immersivePlay?: boolean;
+  readonly playUtilities?: readonly string[];
+  readonly arrangement?: WorkspaceArrangement;
+}
+let owner: string | null = null;
+let policy: LayoutPolicy | null = null;
+const listeners = new Set<() => void>();
+export function layoutPolicy(): LayoutPolicy | null {
+  return owner === activeProjectKey() ? policy : null;
+}
+export function subscribeLayoutPolicy(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+export function installLayoutPolicy(next: LayoutPolicy): () => void {
+  owner = activeProjectKey();
+  policy = next;
+  for (const listener of listeners) listener();
+  return () => {
+    if (policy !== next) return;
+    policy = null;
+    owner = null;
+    for (const listener of listeners) listener();
+  };
+}

package/src/learn-links.ts

@@ -0,0 +1,73 @@
+/**
+ * Editor → Learn-site linkage (G6).
+ *
+ * The whole editor→site half of the FTUE deep-link contract lives here:
+ * the Help/Learn menu's destinations (`ApplicationMenus.tsx`) and the
+ * read-only example viewer's lesson affordance (`status-contributions.tsx`)
+ * both consume these helpers, so the URL shapes are stated exactly once.
+ *
+ * Reference links are VERSION-PINNED: the zero-base platform-vertical plan
+ * serves immutable per-minor snapshots at `/reference/<major>.<minor>/` with
+ * `/reference/latest/` as an explicit 302 alias — so a project pinned to
+ * engine 0.5.x links `/reference/0.5/` and keeps meaning that engine forever.
+ * The pin is derived from the project's `engine.version` manifest field (an
+ * identity pin, not a range — @volter/editor-project/manifest/schema). When the version is
+ * missing or unparseable (or the `0.0.x` dev placeholder), we fall back to
+ * the unpinned reference root rather than fabricating a snapshot that can
+ * never exist.
+ */
+
+/** Learn-site origin (site/astro.config.mjs `site`). */
+export const LEARN_SITE_URL = 'https://vgai-learn.pages.dev/';
+
+/** Quick-starts landing (site/src/content/x). */
+export const LEARN_QUICK_STARTS_URL = `${LEARN_SITE_URL}quick-starts/`;
+
+/** Manual landing (site/src/content/x). */
+export const LEARN_MANUAL_URL = `${LEARN_SITE_URL}manual/`;
+
+/** Unpinned reference root — the fallback when no engine version is known. */
+export const LEARN_REFERENCE_ROOT_URL = `${LEARN_SITE_URL}reference/`;
+
+/**
+ * The `<major>.<minor>` reference-snapshot pin for an engine version, or null
+ * when the version cannot honestly name a snapshot: missing, unparseable, or
+ * the `0.0.x` never-released dev placeholder. Prerelease/build suffixes
+ * (`0.5.0-rc.1`) still pin their minor — the snapshot contract is per-minor.
+ */
+export function referenceVersionPin(engineVersion: string | null | undefined): string | null {
+  const match = /^(\d+)\.(\d+)(?:[.+-]|$)/.exec(engineVersion?.trim() ?? '');
+  if (!match) return null;
+  const pin = `${Number(match[1])}.${Number(match[2])}`;
+  return pin === '0.0' ? null : pin;
+}
+
+/**
+ * Version-pinned Reference URL (`/reference/<major>.<minor>/`) for the given
+ * engine version; the unpinned reference root when no pin can be derived.
+ */
+export function learnReferenceUrl(engineVersion: string | null | undefined): string {
+  const pin = referenceVersionPin(engineVersion);
+  return pin === null ? LEARN_REFERENCE_ROOT_URL : `${LEARN_REFERENCE_ROOT_URL}${pin}/`;
+}
+
+/**
+ * A lesson URL from example `learn` metadata (FT-5), validated to an http(s)
+ * absolute URL — manifests are project-authored content, so anything else
+ * (relative paths, other schemes) renders no link rather than a broken or
+ * unsafe one. Returns null when absent or invalid.
+ */
+export function safeLessonUrl(lesson: string | null | undefined): string | null {
+  if (!lesson) return null;
+  try {
+    const url = new URL(lesson);
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Open a Learn-site destination in a new tab (§6: all Help links open out). */
+export function openLearnLink(url: string): void {
+  window.open(url, '_blank', 'noopener,noreferrer');
+}

package/src/light-explorer-model.ts

@@ -0,0 +1,134 @@
+import type { AuthoringAdapter, EditorNode, PropertyDescriptor } from '@volter/editor-project/adapter';
+import { setAuthoringInspectorField } from './authoring/consumer-actions';
+import { forEachHierarchyNode } from './hierarchy-walk';
+
+export const LIGHT_EXPLORER_PATHS = {
+  enabled: 'visible',
+  color: 'light.color',
+  intensity: 'light.intensity',
+  range: 'light.distance',
+  shadows: 'shadow.cast',
+} as const;
+
+export type LightExplorerField = keyof typeof LIGHT_EXPLORER_PATHS;
+
+export interface LightExplorerCell<T> {
+  readonly supported: boolean;
+  readonly writable: boolean;
+  readonly value: T | null;
+}
+
+export interface LightExplorerRow {
+  readonly id: string;
+  readonly name: string;
+  readonly type: string;
+  readonly enabled: LightExplorerCell<boolean>;
+  readonly color: LightExplorerCell<string>;
+  readonly intensity: LightExplorerCell<number>;
+  readonly range: LightExplorerCell<number>;
+  readonly shadows: LightExplorerCell<boolean>;
+}
+
+interface HierarchyWithInternals {
+  /** Optional editor-side hierarchy projection used by component-owning
+   * adapters. These are still real adapter nodes; they are merely folded out
+   * of the ordinary tree until a person asks to reveal implementation parts. */
+  internalChildren?(id: string): EditorNode[] | undefined;
+}
+
+function lightNodes(adapter: AuthoringAdapter): EditorNode[] {
+  const result: EditorNode[] = [];
+  const hierarchyWithInternals = adapter as AuthoringAdapter & HierarchyWithInternals;
+  forEachHierarchyNode(
+    adapter.hierarchy,
+    (node) => {
+      if (node.kind === 'light') result.push(node);
+    },
+    { extraChildren: (id) => hierarchyWithInternals.internalChildren?.(id) },
+  );
+  return result;
+}
+
+export function activeLightCount(adapter: AuthoringAdapter): number {
+  return lightNodes(adapter).length;
+}
+
+function descriptorFor(
+  descriptors: readonly PropertyDescriptor[],
+  field: LightExplorerField,
+): PropertyDescriptor | null {
+  return descriptors.find((descriptor) => descriptor.path === LIGHT_EXPLORER_PATHS[field]) ?? null;
+}
+
+function cell<T>(
+  adapter: AuthoringAdapter,
+  id: string,
+  descriptors: readonly PropertyDescriptor[],
+  field: LightExplorerField,
+  accept: (value: unknown) => value is T,
+): LightExplorerCell<T> {
+  const descriptor = descriptorFor(descriptors, field);
+  if (!descriptor || !adapter.inspector) {
+    return { supported: false, writable: false, value: null };
+  }
+  let value: unknown;
+  try {
+    value = adapter.inspector.get(id, descriptor.path);
+  } catch {
+    value = undefined;
+  }
+  return {
+    supported: true,
+    writable: descriptor.readonly !== true,
+    value: accept(value) ? value : null,
+  };
+}
+
+const isBoolean = (value: unknown): value is boolean => typeof value === 'boolean';
+const isString = (value: unknown): value is string => typeof value === 'string';
+const isNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+export function lightExplorerRows(adapter: AuthoringAdapter): LightExplorerRow[] {
+  return lightNodes(adapter).map((node) => {
+    let descriptors: readonly PropertyDescriptor[] = [];
+    try {
+      descriptors = adapter.inspector?.properties(node.id) ?? [];
+    } catch {
+      // A broken per-node inspector must not take the scene-wide inventory down.
+    }
+    const nativeType = adapter.hierarchy.object3D?.(node.id)?.type;
+    return {
+      id: node.id,
+      name: node.label,
+      type: node.typeLabel ?? nativeType ?? 'Light',
+      enabled: cell(adapter, node.id, descriptors, 'enabled', isBoolean),
+      color: cell(adapter, node.id, descriptors, 'color', isString),
+      intensity: cell(adapter, node.id, descriptors, 'intensity', isNumber),
+      range: cell(adapter, node.id, descriptors, 'range', isNumber),
+      shadows: cell(adapter, node.id, descriptors, 'shadows', isBoolean),
+    };
+  });
+}
+
+export function setLightExplorerField(
+  adapter: AuthoringAdapter,
+  ids: readonly string[],
+  field: LightExplorerField,
+  value: unknown,
+): number {
+  if (!adapter.inspector) return 0;
+  let changed = 0;
+  for (const id of ids) {
+    let descriptor: PropertyDescriptor | null = null;
+    try {
+      descriptor = descriptorFor(adapter.inspector.properties(id), field);
+    } catch {
+      continue;
+    }
+    if (!descriptor || descriptor.readonly) continue;
+    setAuthoringInspectorField(adapter, id, descriptor.path, value);
+    changed++;
+  }
+  return changed;
+}