@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/environment-images.ts

@@ -0,0 +1,58 @@
+/**
+ * ENVIRONMENT IMAGES: panoramas a view can light by and draw behind the scene
+ * (`PreviewLighting.environment.image`), registered as data by the integration
+ * that ships them (a `*.environment.ts` contribution, point `workspace.environment`).
+ * A view names an image by id, never by URL: the URL is a built asset's, which a
+ * rebuild renames, and a saved view outlives the build that wrote it.
+ */
+
+export interface EnvironmentImage {
+  readonly id: string;
+  readonly title: string;
+  /** The image as served: an equirectangular panorama in scene-referred light. */
+  readonly url: string;
+  readonly format: 'exr' | 'hdr';
+}
+
+/** What a `*.environment.ts` contribution exports as `environment`: one integration's images. */
+export interface EnvironmentImageSet {
+  readonly id: string;
+  /** Where the images come from and under what terms, as the shipping integration states it. */
+  readonly source: string;
+  readonly images: readonly EnvironmentImage[];
+}
+
+const images = new Map<string, EnvironmentImage>();
+const listeners = new Set<() => void>();
+
+function changed(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Register a set's images; returns the unregister. An id already registered is refused. */
+export function registerEnvironmentImages(set: EnvironmentImageSet): () => void {
+  for (const image of set.images) {
+    if (images.has(image.id)) throw new Error(`registerEnvironmentImages: "${image.id}" is already registered.`);
+  }
+  for (const image of set.images) images.set(image.id, image);
+  changed();
+  return () => {
+    for (const image of set.images) if (images.get(image.id) === image) images.delete(image.id);
+    changed();
+  };
+}
+
+export function environmentImage(id: string): EnvironmentImage | null {
+  return images.get(id) ?? null;
+}
+
+export function environmentImages(): readonly EnvironmentImage[] {
+  return [...images.values()];
+}
+
+export function subscribeEnvironmentImages(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/kit/eyedropper-session.ts

@@ -0,0 +1,60 @@
+/**
+ * Eyedropper session (D3.d) — a module-level subscribable singleton bridging the
+ * C1 `ColorPicker` (mounted inside the Inspector panel) and the canvas
+ * (`RootSelectionOverlay`), the two SIBLING React trees a "click the eyedropper
+ * button, then click somewhere on the canvas" gesture must cross when the native
+ * `EyeDropper` API is unavailable (the FALLBACK path this whole module exists
+ * for — see `ColorPicker.tsx`'s `handleEyedropper` and the `ColorSampleProvider`
+ * contract doc comment for why the native path needs none of this: it samples
+ * real rendered pixels itself).
+ *
+ * Mirrors `world-session-state.ts`'s "bare module singleton" shape, but keeps
+ * its OWN subscriber list (rather than piggybacking on `EditorShellStore.
+ * notifyIngestEdit`) since this is transient cross-panel UI state, not an
+ * authored/session toggle any editor-store snapshot needs to carry.
+ *
+ * Only ONE fallback pick can be in flight at a time — beginning a new one
+ * silently supersedes whatever was pending (mirrors the ColorPicker's own
+ * "one popover at a time" assumption; nothing today opens two eyedroppers at
+ * once).
+ */
+
+export type EyedropperApply = (color: string | null) => void;
+
+let activeApply: EyedropperApply | null = null;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const l of listeners) l();
+}
+
+/** Begin a fallback eyedropper session — `apply` is the widget's own
+ *  sampled-color callback, called exactly once when the session resolves
+ *  (`null` color means "cancelled", e.g. Escape — never a fabricated color). */
+export function beginEyedropperSession(apply: EyedropperApply): void {
+  activeApply = apply;
+  notify();
+}
+
+/** True while a fallback session is awaiting a canvas click/Escape. */
+export function isEyedropperSessionActive(): boolean {
+  return activeApply !== null;
+}
+
+/** Resolve the active session with a sampled color (or `null` to cancel),
+ *  then close it. A no-op if no session is active. */
+export function resolveEyedropperSession(color: string | null): void {
+  const apply = activeApply;
+  if (!apply) return;
+  activeApply = null;
+  notify();
+  apply(color);
+}
+
+/** Subscribe to session begin/end transitions — `RootSelectionOverlay` binds
+ *  this via `useSyncExternalStore` so it re-renders (shows/hides the cursor
+ *  swatch) the instant a session starts or ends. */
+export function subscribeEyedropperSession(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}

package/src/kit/files/file-provider.ts

@@ -0,0 +1,62 @@
+/**
+ * THE PROJECT'S FILES, WRITTEN THROUGH THE WORKBENCH — the provider it
+ * installs here, and the window before it lands.
+ *
+ * `EditorHost.files` is the door (`packages/sdk/src/kit/files/`) —
+ * read/readBytes/write/exists/list/watch over PROJECT-RELATIVE paths, the same
+ * spelling the history door hands over, so both resolve against one workspace
+ * folder.
+ *
+ * WHAT THE PROVIDER BUYS, measured (U5): a volter write the workbench did not
+ * make is an EXTERNAL change to it — Monaco reloads the file,
+ * `modelService.updateModel` pushes a fresh text element through `EditStack`,
+ * and `IUndoRedoService.pushElement` clears that resource's FUTURE, so a gizmo
+ * drag's redo was lost whenever a text model for that file was open. A write
+ * made THROUGH the workbench is the workbench's own, so no reload fires and
+ * the future survives. That is what this buys, and nothing else.
+ *
+ * IT ARRIVES AFTER THE MOUNT, always: a `ServicesAccessor` is valid only for
+ * the synchronous part of a command, so the contribution cannot build the
+ * provider before the mount it is handed to. Until it does, the door falls
+ * back to the session's transports — a write in that window is a real write
+ * with nowhere else to go.
+ */
+import type { EditorHostFileEvent, EditorHostFileProvider } from '@volter/sdk/host';
+
+export type ProjectFileEvent = EditorHostFileEvent;
+export type ProjectFileProvider = EditorHostFileProvider;
+
+let provider: ProjectFileProvider | null = null;
+const listeners = new Set<() => void>();
+
+/**
+ * Is the provider installed? False until it lands — later than the mount,
+ * because a `ServicesAccessor` is valid only for a command's synchronous part,
+ * so the contribution hands the provider over after the editor is running. In
+ * that window a caller reaches the session's transports instead, which is a
+ * real write with nowhere else to go rather than a refusal.
+ */
+export function filesProviderInstalled(): boolean {
+  return provider !== null;
+}
+
+/** The installed provider, or `null` before it lands. */
+export function filesProvider(): ProjectFileProvider | null {
+  return provider;
+}
+
+/**
+ * Install how the project's files are read and written, or `null` to withdraw
+ * it — the provider is the workbench's, and a workbench that went away takes
+ * it with it.
+ */
+export function setFilesProvider(next: ProjectFileProvider | null): void {
+  if (provider === next) return;
+  provider = next;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeFilesProvider(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}

package/src/kit/files/project-files.ts

@@ -0,0 +1,270 @@
+/**
+ * THE ONE FILE API over the open project, in PROJECT-RELATIVE paths — the
+ * editor's half of `@volter/sdk/host`'s `files` door (U5).
+ *
+ * Under the FRAME this is VS Code's `IFileService`/`ITextFileService` over the
+ * workspace folder, installed as a provider by the Code-OSS bridge. Under the
+ * HOST — standalone the editor's `edit` command, and the hosted browser build — it is today's
+ * transports, and this module is the ONE place that says which transport owns
+ * which path. That statement used to be spread across five files' doc
+ * comments; it is written down once, here, because the fragmentation is the
+ * fact U5 measured:
+ *
+ *   | path class            | the session's route          |
+ *   |-----------------------|------------------------------|
+ *   | read, anything        | Vite `/@fs/<root>/<path>`    |
+ *   | write `public/**`     | `POST /__editor/save-file`   |
+ *   | write `.volter/**`      | `POST /__editor/volter-file`   |
+ *   | write `src/**` source | `POST /__ui-source/apply`    | the storage source-write backend |
+ *   | list `public/**`      | `GET /__editor/assets`       | StorageBackend |
+ *   | watch                 | `EventSource /__editor/events` | StorageBackend.watch |
+ *
+ * A path class with no host transport is REFUSED BY NAME, naming the route
+ * that does own it. It is not this door's business to invent a general
+ * project-root write route on the session: each of those routes is
+ * deliberately narrow (`/__editor/volter-file` accepts only `.volter/**`,
+ * `/__editor/data-file` only `src/data/**\/*.data.json`), and their own header
+ * comments record that as defence in depth. Under the frame the question does
+ * not arise — the workbench's file service owns the whole folder.
+ *
+ * `StorageBackend`'s paths are NOT this door's paths, and that difference is
+ * the measurement the door exists for: `HttpStorage` is rooted at
+ * `<project>/public/` while a project-rooted backend is rooted at the
+ * project root. Callers that still speak `StorageBackend` keep doing so; what
+ * they get under the frame is `storage/host-files-storage.ts`, a `public/`
+ * view onto this door.
+ */
+
+import { bytesToBase64 } from '@volter/sdk/kit/bytes-codec';
+import { getProjectDefinePath } from '../editor-mode';
+import { assertEditorServerAnswered, editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { sourceMutationAttribution } from '@volter/sdk/kit/editor-session-attribution';
+import { filesProvider, filesProviderInstalled, type ProjectFileEvent } from './file-provider';
+
+const BASE = '/__editor';
+
+export interface ProjectFileEntry {
+  readonly name: string;
+  readonly path: string;
+  readonly type: 'file' | 'dir';
+}
+
+/** Project-relative, `/`-separated, no leading slash, no `..`. */
+function normalize(path: string): string {
+  return path.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function assertContained(path: string): string {
+  const normalized = normalize(path);
+  if (!normalized || normalized.split('/').includes('..')) {
+    throw new Error(`projectFiles: "${path}" is not a project-relative path.`);
+  }
+  return normalized;
+}
+
+/**
+ * The same containment check for a DIRECTORY, where the empty string is the
+ * project root and therefore legal.
+ *
+ * It exists because `list` ran bare {@link normalize} while every other member
+ * ran {@link assertContained} — so a `..` segment reached the frame's provider
+ * or a session route while the same segment in a `read` was refused here.
+ * `normalize` strips a LEADING slash; it has never removed a `..` segment, and
+ * a caller reading its name could be forgiven for thinking otherwise. The
+ * empty string is the one thing `assertContained` rejects that a directory
+ * legitimately needs (it is how the project root itself is listed), which is
+ * why this is a second function rather than a flag.
+ */
+function assertContainedDir(dir: string): string {
+  const normalized = normalize(dir);
+  if (normalized.split('/').includes('..')) {
+    throw new Error(`projectFiles: "${dir}" is not a project-relative directory.`);
+  }
+  return normalized;
+}
+
+/**
+ * The refusal a host-tier write to a path class no session route owns gets.
+ * It NAMES the owning route rather than failing generically, because the one
+ * thing a caller can do about it is use that route.
+ */
+function noHostWriteRoute(path: string): Error {
+  return new Error(
+    `projectFiles.write("${path}"): the standalone editor has no general project-root write route, ` +
+      'and this door does not invent one. Source files are written through `/__ui-source/apply` ' +
+      '(`ui-source/source-write-backend.ts`), `public/**` through `/__editor/save-file`, `.volter/**` ' +
+      'through `/__editor/volter-file`. Under the Code-OSS frame the workbench file service owns the ' +
+      'whole folder and this refusal cannot occur.',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The HOST fill — today's transports
+// ---------------------------------------------------------------------------
+
+async function hostRead(path: string): Promise<string> {
+  const res = await fetch(`/@fs/${getProjectDefinePath()}/${path}`);
+  if (!res.ok) throw new Error(`projectFiles.read "${path}": HTTP ${res.status}`);
+  return res.text();
+}
+
+async function hostReadBytes(path: string): Promise<Uint8Array> {
+  const res = await fetch(`/@fs/${getProjectDefinePath()}/${path}`);
+  if (!res.ok) throw new Error(`projectFiles.readBytes "${path}": HTTP ${res.status}`);
+  return new Uint8Array(await res.arrayBuffer());
+}
+
+async function hostWrite(path: string, data: string | Uint8Array): Promise<void> {
+  if (path.startsWith('public/')) {
+    const body =
+      typeof data === 'string'
+        ? { path: path.slice('public/'.length), content: data, ...sourceMutationAttribution() }
+        : {
+            path: path.slice('public/'.length),
+            content: bytesToBase64(data),
+            encoding: 'base64' as const,
+            ...sourceMutationAttribution(),
+          };
+    const res = await fetch(`${BASE}/save-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    assertEditorServerAnswered(res, `Write ${path} failed`);
+    if (!res.ok) throw new Error(`projectFiles.write "${path}": HTTP ${res.status}`);
+    return;
+  }
+  if (path.startsWith('.volter/')) {
+    const body =
+      typeof data === 'string'
+        ? { path, content: data, ...sourceMutationAttribution() }
+        : {
+            path,
+            content: bytesToBase64(data),
+            encoding: 'base64' as const,
+            ...sourceMutationAttribution(),
+          };
+    const res = await fetch(`${BASE}/volter-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    assertEditorServerAnswered(res, `Write ${path} failed`);
+    if (!res.ok) throw new Error(`projectFiles.write "${path}": HTTP ${res.status}`);
+    return;
+  }
+  throw noHostWriteRoute(path);
+}
+
+async function hostExists(path: string): Promise<boolean> {
+  try {
+    const res = await fetch(`/@fs/${getProjectDefinePath()}/${path}`, { method: 'HEAD' });
+    // The dev server's SPA fallback answers 200 with `index.html` for a missing
+    // path, so `res.ok` alone cannot tell existence from absence — the same
+    // measured false positive `api/project-source.ts`'s `probeProjectFile`
+    // records. A real file never answers as an HTML DOCUMENT.
+    if (!res.ok) return false;
+    return !(res.headers.get('content-type') ?? '').toLowerCase().includes('text/html');
+  } catch {
+    return false;
+  }
+}
+
+interface ServerAssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+}
+
+async function hostList(dir: string): Promise<readonly ProjectFileEntry[]> {
+  if (!dir.startsWith('public')) {
+    throw new Error(
+      `projectFiles.list("${dir}"): the standalone editor lists only \`public/**\` ` +
+        '(`/__editor/assets`); source trees are listed by glob through ' +
+        "`/__editor/source-files` (`api/project-source.ts`'s `listProjectSourceFiles`).",
+    );
+  }
+  const inner = dir === 'public' ? '' : dir.slice('public/'.length);
+  const res = await fetch(`${BASE}/assets?${new URLSearchParams({ dir: inner })}`);
+  const { entries } = await editorServerJson<{ entries: ServerAssetEntry[] }>(
+    res,
+    `projectFiles.list "${dir}" failed`,
+  );
+  return entries.map((entry) => ({
+    name: entry.name,
+    path: inner ? `public/${inner}/${entry.name}` : `public/${entry.name}`,
+    type: entry.type === 'directory' ? ('dir' as const) : ('file' as const),
+  }));
+}
+
+function hostWatch(listener: (event: ProjectFileEvent) => void): () => void {
+  const source = new EventSource(`${BASE}/events`);
+  const handler = (ev: MessageEvent) => {
+    try {
+      const data = JSON.parse(ev.data) as { type?: string; file?: string; path?: string };
+      const path = data.path ?? data.file;
+      if (!path) return;
+      listener({
+        type: (data.type as ProjectFileEvent['type']) ?? 'update',
+        path: normalize(path),
+      });
+    } catch {
+      // Non-JSON keepalive frame.
+    }
+  };
+  source.addEventListener('message', handler);
+  return () => {
+    source.removeEventListener('message', handler);
+    source.close();
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The door
+// ---------------------------------------------------------------------------
+
+export const projectFiles = {
+  /** True while the workbench's own file service is answering. A caller with
+   *  a transport of its own (the source-write lane) reads this to decide
+   *  whether its write would be EXTERNAL to the workbench. */
+  frameOwned: filesProviderInstalled,
+
+  // Every door below `return await`s, never returns the promise bare. With a
+  // bare return this frame leaves V8's async stack, and a workbench file
+  // provider's rejection (`FileOperationError`) then carries ONLY workbench
+  // frames — the stack the console ledger reads to decide whether an error is
+  // the project's (`isWorkbenchOrigin`). A Play script's
+  // `await host.files.read('missing.json')` must keep its own frames on it.
+  async read(path: string): Promise<string> {
+    const key = assertContained(path);
+    return await (filesProvider()?.read(key) ?? hostRead(key));
+  },
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const key = assertContained(path);
+    const provider = filesProvider();
+    return await (provider?.readBytes ? provider.readBytes(key) : hostReadBytes(key));
+  },
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const key = assertContained(path);
+    const provider = filesProvider();
+    if (provider) return await provider.write(key, data);
+    return await hostWrite(key, data);
+  },
+
+  async exists(path: string): Promise<boolean> {
+    const key = assertContained(path);
+    return await (filesProvider()?.exists(key) ?? hostExists(key));
+  },
+
+  async list(dir: string): Promise<readonly ProjectFileEntry[]> {
+    const key = assertContainedDir(dir);
+    const provider = filesProvider();
+    return await (provider?.list ? provider.list(key) : hostList(key));
+  },
+
+  watch(listener: (event: ProjectFileEvent) => void): () => void {
+    const provider = filesProvider();
+    return provider?.watch ? provider.watch(listener) : hostWatch(listener);
+  },
+};

package/src/kit/finders/index.ts

@@ -0,0 +1,137 @@
+/**
+ * THE FINDER NAMESPACE — host-owned discovery algorithms an adapter SELECTS.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": what zero
+ * inference forbids is the ENGINE running a finder nobody selected. A
+ * convention (`src/scenes/`, a story registration) is legitimate exactly when
+ * it is an adapter's declared finder parameter, and illegitimate as implicit
+ * engine behavior.
+ *
+ * That is enforced MECHANICALLY, not by policy: everything under this
+ * directory has exactly ONE sanctioned importer — the editor's adapter loader
+ * (`packages/sdk/src/kit/project-adapter.ts`) — and
+ * `packages/engine/test/finder-import-boundary.test.ts` fails by name when any
+ * other engine/editor file imports it. Do not add a second importer; make the
+ * loader answer instead.
+ *
+ * Dependency direction is one-way: finders import their parameter types from
+ * `../adapter-module`, and `adapter-module.ts` imports nothing from here. That
+ * is what keeps a game's `editor/volter.adapter.ts` free of finder implementations.
+ */
+
+import {
+  EXPORTED_COMPOSITION_REGIONS,
+  type FinderSelection,
+  type ScenesFromEntrypointSelectionParams,
+} from '@volter/project/adapter/adapter-module';
+import type { FinderResult } from '@volter/project/adapter/finders/finder-result';
+import { registerFinder, runRegisteredFinder } from '@volter/project/adapter/finders/registry';
+import { type ZodType, z } from 'zod';
+import {
+  type ScenesFromEntrypointSelectionInput,
+  scenesFromEntrypointSelection,
+} from './scenes-from-entrypoint-selection';
+
+export type { FinderResult } from '@volter/project/adapter/finders/finder-result';
+export type {
+  FinderContribution,
+  FinderRegistration,
+} from '@volter/project/adapter/finders/registry';
+export {
+  finderReadsSources,
+  registerContributedFinder,
+  registeredFinderNames,
+  registerFinder,
+  runRegisteredFinder,
+} from '@volter/project/adapter/finders/registry';
+export type {
+  EntrypointSource,
+  ScenesFromEntrypointSelectionInput,
+} from './scenes-from-entrypoint-selection';
+export { scenesFromEntrypointSelection } from './scenes-from-entrypoint-selection';
+
+/** Everything any shipped finder can be handed, gathered once by the loader. */
+/** A project source the host read for a selection's `include` globs. */
+export interface ProjectSourceFile {
+  /** Project-relative path. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** One entry of the host's project component index. */
+export interface ProjectComponentRef {
+  readonly name: string;
+  /** Project-relative source path of the component's own module. */
+  readonly path: string;
+  /** Region this component's surface belongs to, when the host knows it. */
+  readonly region?: string | null;
+}
+
+export type FinderInput = ScenesFromEntrypointSelectionInput & {
+  /**
+   * The project's component index — what a finder joins its own discovery
+   * against (a prefab's source path and region).
+   *
+   * There is deliberately no `stories` here. `prefabsFromStories` used to be
+   * an engine finder whose story registrations the EDITOR filled, which is how
+   * the editor's adapter loader came to import the story registry and, through
+   * it, Storybook. It is a registered finder that reads its own ledger now
+   * (`packages/sdk/src/kit/stories/prefabs-finder.ts`): a finder's data arrives
+   * with the finder.
+   */
+  readonly components?: readonly ProjectComponentRef[];
+  /** The sources matching every selection's `include` globs — empty when
+   *  no selection declares any. A contributed finder reads the project
+   *  through this and {@link FinderInput.files} and nothing else. */
+  readonly sources?: readonly ProjectSourceFile[];
+  /**
+   * The PATHS matching those same globs — every one of them, including the
+   * files `sources` has no text for.
+   *
+   * A finder over BINARY documents needs this and could not use `sources`:
+   * `@volter/editor-blender`'s `modelsFromBlendFiles` lists `.blend` files, and there
+   * is nothing in a `.blend` a text walk could honestly read — the entry IS
+   * the file. Handing it a decoded binary instead would have been the shim.
+   */
+  readonly files?: readonly string[];
+};
+
+/**
+ * Run one adapter-declared selection. The switch is exhaustive over
+ * {@link FinderSelection}: a new finder that forgets a case fails to COMPILE
+ * here rather than silently contributing nothing.
+ */
+export function runFinderSelection(selection: FinderSelection, input: FinderInput): FinderResult {
+  return runRegisteredFinder(selection, input);
+}
+
+// The engine's own finders register here, schemas beside them: what an
+// adapter may select by name is exactly what this registry holds.
+const ScenesFromEntrypointSelectionSchema = z
+  .object({
+    finder: z.literal('scenesFromEntrypointSelection'),
+    regions: z
+      .union([z.array(z.string().min(1)).min(1), z.literal(EXPORTED_COMPOSITION_REGIONS)])
+      .describe('Region ids whose entrypoints carry the selection, or the rule form'),
+    selection: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "Identifier of the entrypoint's module-level scene selection table; omit for a " +
+          'single-composition entrypoint',
+      ),
+  })
+  .strict()
+  .refine((value) => value.selection === undefined || Array.isArray(value.regions), {
+    message:
+      'scenesFromEntrypointSelection: `selection` names an identifier in ONE entrypoint’s ' +
+      `source, so it cannot be paired with the \`${EXPORTED_COMPOSITION_REGIONS}\` rule — ` +
+      'name the region explicitly (`regions: ["<rootId>"]`).',
+  });
+registerFinder<ScenesFromEntrypointSelectionParams, FinderInput>({
+  name: 'scenesFromEntrypointSelection',
+  schema:
+    ScenesFromEntrypointSelectionSchema as unknown as ZodType<ScenesFromEntrypointSelectionParams>,
+  run: scenesFromEntrypointSelection,
+});