@volter/editor-core 0.5.57

package/src/asset-workflow/thumbnail-system.ts

@@ -0,0 +1,256 @@
+import { z } from 'zod';
+import { projectFiles } from '../files/project-files';
+import type { StorageBackend } from '../storage';
+import type { AssetCatalog } from './asset-types';
+
+/**
+ * The deterministic render profile a generated thumbnail is stamped with.
+ *
+ * Every key here is a recipe step something in this repo actually PERFORMS. A
+ * profile that describes work nobody does is a declaration with no reader — the
+ * inverse of the manifest-schema rule, and the way a heuristic acquires
+ * provenance it never earned.
+ *
+ * The representative STATE of a component is its STORY: the editor captures
+ * `StoryComponentThumbnail`'s registered story, which the author wrote and can
+ * change. That is a declaration, and it is why no name-matching pose heuristic
+ * lives here (ARCHITECTURE-CORE §The editor protocol, "Zero inference").
+ */
+export const THUMBNAIL_PROFILE = {
+  version: 'vgai-thumbnail-v2',
+  width: 256,
+  height: 256,
+  background: 'neutral',
+  framing: 'bounds-isometric-1.3',
+  lighting: 'studio-key-fill-v1',
+  colorManagement: 'srgb-aces-filmic',
+} as const;
+
+export const thumbnailManifestSchema = z
+  .object({
+    version: z.literal(1),
+    /**
+     * Which profile last REGENERATED this manifest — a record, not a gate.
+     *
+     * It was `z.literal(THUMBNAIL_PROFILE.version)`, which made a profile bump
+     * (v2 → v3) fail every manifest already on disk. The read collapsed that
+     * into `null`, the toolbar read `null` as "no manifest yet", and the next
+     * framing save wrote `entries: {}` — so bumping this constant silently
+     * DESTROYED every hand-authored camera framing in the project.
+     *
+     * A bump must migrate or preserve, and preserving is the honest answer here:
+     * each entry already carries its own `profileVersion`, which is precisely
+     * what tells a consumer that entry was rendered by an older profile and
+     * wants regenerating. Nothing is gained by throwing the framing away too.
+     * `version` below stays a literal on purpose — that is the DOCUMENT format,
+     * and an unrecognized one is refused rather than overwritten.
+     */
+    profile: z.string().min(1),
+    generatedAt: z.string(),
+    entries: z.record(
+      z.string(),
+      z
+        .object({
+          state: z.enum(['generated', 'upstream', 'fallback', 'unsupported', 'failed']),
+          path: z.string().optional(),
+          profileVersion: z.string(),
+          sourceHash: z.string().optional(),
+          resultHash: z.string().optional(),
+          issueCode: z.string().optional(),
+          framing: z
+            .object({
+              position: z.tuple([z.number(), z.number(), z.number()]),
+              target: z.tuple([z.number(), z.number(), z.number()]),
+              fov: z.number().positive().lt(180).optional(),
+            })
+            .strict()
+            .optional(),
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+export type ThumbnailManifest = z.infer<typeof thumbnailManifestSchema>;
+
+export const THUMBNAIL_MANIFEST_PATH = '.vgai/thumbnails.json';
+
+/**
+ * The three OUTCOMES of reading `.vgai/thumbnails.json`, which used to be one
+ * `null`.
+ *
+ * `absent` and `unreadable` are opposite instructions and collapsing them lost
+ * a project's work: a rebuild-and-write is correct when the file is not there
+ * and DESTRUCTIVE when it is there and merely could not be parsed. Every
+ * consumer that only READS may treat both as "no thumbnails"; the one consumer
+ * that WRITES must refuse on `unreadable`.
+ */
+export type ThumbnailManifestRead =
+  | { readonly status: 'absent' }
+  | { readonly status: 'ok'; readonly manifest: ThumbnailManifest }
+  | { readonly status: 'unreadable'; readonly reason: string };
+
+let manifestPromise: Promise<ThumbnailManifestRead> | null = null;
+
+/**
+ * Optional project thumbnail metadata must never block live fallback previews,
+ * and must never be silently discarded either.
+ *
+ * `absent` covers the two ways the file genuinely is not there: `read` rejects
+ * (the documented `StorageBackend.read` contract for a missing path), and an
+ * HTTP-backed project answering with the Vite HTML shell instead of a 404.
+ * Everything else — a truncated or hand-broken JSON document, a shape this
+ * schema does not recognize — is `unreadable`, and the caller decides.
+ */
+export async function readProjectThumbnailManifest(
+  backend: Pick<StorageBackend, 'read'>,
+): Promise<ThumbnailManifestRead> {
+  let text: string;
+  try {
+    text = await backend.read(THUMBNAIL_MANIFEST_PATH);
+  } catch {
+    return { status: 'absent' };
+  }
+  const trimmed = text.trim();
+  if (trimmed === '' || trimmed.startsWith('<')) return { status: 'absent' };
+  let json: unknown;
+  try {
+    json = JSON.parse(trimmed);
+  } catch (cause) {
+    return {
+      status: 'unreadable',
+      reason: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+  const parsed = thumbnailManifestSchema.safeParse(json);
+  return parsed.success
+    ? { status: 'ok', manifest: parsed.data }
+    : { status: 'unreadable', reason: parsed.error.issues.map((i) => i.message).join('; ') };
+}
+
+export function loadProjectThumbnailManifest(): Promise<ThumbnailManifestRead> {
+  if (!manifestPromise) {
+    manifestPromise = readProjectThumbnailManifest(projectFiles).then(async (read) => {
+      // Reported ONCE per cache lifetime (the promise is memoized), and
+      // through the editor console because a file the editor refuses to
+      // rewrite is remaining work, not log noise.
+      if (read.status === 'unreadable') {
+        const { editorConsole } = await import('../editor-console');
+        editorConsole.error(
+          `${THUMBNAIL_MANIFEST_PATH} is present but could not be read (${read.reason}). ` +
+            'Thumbnail framing will not be saved until it is fixed or deleted; previews ' +
+            'fall back to live renders.',
+          'asset-workflow',
+        );
+      }
+      return read;
+    });
+  }
+  return manifestPromise;
+}
+export function resetProjectThumbnailManifestCache(): void {
+  manifestPromise = null;
+}
+
+interface QueueJob<T> {
+  key: string;
+  priority: number;
+  consumers: number;
+  started: boolean;
+  resolve(value: T): void;
+  reject(error: unknown): void;
+  promise: Promise<T>;
+}
+
+/** Bounded, priority-aware, deduplicating fallback queue shared by all visible cards. */
+export class ThumbnailJobQueue<T> {
+  private active = 0;
+  private readonly jobs = new Map<string, QueueJob<T>>();
+  private pending: QueueJob<T>[] = [];
+  constructor(
+    private readonly execute: (key: string) => Promise<T>,
+    readonly concurrency = 2,
+  ) {}
+  request(key: string, priority = 0): { promise: Promise<T>; cancel(): void } {
+    let job = this.jobs.get(key);
+    if (!job) {
+      let resolve!: (value: T) => void;
+      let reject!: (error: unknown) => void;
+      const promise = new Promise<T>((ok, fail) => {
+        resolve = ok;
+        reject = fail;
+      });
+      job = { key, priority, consumers: 0, started: false, resolve, reject, promise };
+      this.jobs.set(key, job);
+      this.pending.push(job);
+    }
+    job.consumers++;
+    job.priority = Math.max(job.priority, priority);
+    this.pending.sort((a, b) => b.priority - a.priority);
+    this.pump();
+    let cancelled = false;
+    return {
+      promise: job.promise,
+      cancel: () => {
+        if (cancelled) return;
+        cancelled = true;
+        job!.consumers--;
+        if (!job!.started && job!.consumers === 0) {
+          this.pending = this.pending.filter((item) => item !== job);
+          this.jobs.delete(job!.key);
+          job!.reject(new DOMException('Thumbnail request cancelled', 'AbortError'));
+        }
+      },
+    };
+  }
+  snapshot(): { active: number; pending: number; keys: number } {
+    return { active: this.active, pending: this.pending.length, keys: this.jobs.size };
+  }
+  private pump(): void {
+    while (this.active < this.concurrency) {
+      const job = this.pending.shift();
+      if (!job) return;
+      if (job.consumers === 0) continue;
+      job.started = true;
+      this.active++;
+      void this.execute(job.key)
+        .then(job.resolve, job.reject)
+        .finally(() => {
+          this.active--;
+          this.jobs.delete(job.key);
+          this.pump();
+        });
+    }
+  }
+}
+
+export interface ThumbnailQualitySample {
+  alphaCoverage: number;
+  luminanceVariance: number;
+  edgeCoverage: number;
+}
+export function auditThumbnailQuality(sample: ThumbnailQualitySample): string[] {
+  const issues: string[] = [];
+  if (sample.alphaCoverage < 0.01) issues.push('thumbnail.blank-transparent');
+  if (sample.luminanceVariance < 0.0005 && sample.edgeCoverage < 0.01)
+    issues.push('thumbnail.near-uniform');
+  if (sample.edgeCoverage > 0.45) issues.push('thumbnail.possibly-clipped');
+  return issues;
+}
+
+export function catalogThumbnailCoverage(catalog: AssetCatalog): {
+  total: number;
+  generated: number;
+  upstream: number;
+  fallback: number;
+  unsupported: number;
+  failed: number;
+} {
+  const result = { total: 0, generated: 0, upstream: 0, fallback: 0, unsupported: 0, failed: 0 };
+  for (const family of catalog.families) {
+    for (const variant of family.variants) {
+      result.total++;
+      result[variant.thumbnail.state]++;
+    }
+  }
+  return result;
+}

package/src/authoring/active-adapter.ts

@@ -0,0 +1,199 @@
+/**
+ * The editor's active {@link AuthoringAdapter} handle.
+ *
+ * The editor UI talks to the authoring contract through THIS accessor rather than
+ * reaching into `EditorShellStore` or any adapter's private model directly. The accessor names no
+ * concrete adapter: a SURFACE's live adapter is REGISTERED by the integration
+ * that owns that surface's document model ({@link setBaseAuthoringFactory}), an
+ * ingest/play/edit-mode session can override it globally, and the UI code below
+ * it does not change either way.
+ *
+ * The adapter is a stateless delegating wrapper over the store, so we memoize one
+ * per store (a store's identity is stable for the editor session).
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { inspectAuthoringAdapterSeams } from '../coverage/authoring-seam-evidence';
+import type { EditorShellStore } from '../editor-shell-store';
+import { makeNoAuthoringAdapter } from './no-authoring-adapter';
+
+const byStore = new WeakMap<EditorShellStore, AuthoringAdapter>();
+
+/**
+ * The LIVE authoring adapter a declared world of one surface gets: the
+ * projection over whatever that surface has actually mounted, as opposed to
+ * the manifest-only `BoundaryAuthoringAdapter` a surface with no registration
+ * falls back to.
+ *
+ * The key is the world's `surface` (`three`, `canvas`, `dom`, …) because that
+ * is what decides which projection can read it, and the factory is a
+ * PACKAGE's code rather than a store's state — it takes the store as an
+ * argument. (It was keyed per STORE until 2026-09-21 and had no caller at all:
+ * `getActiveAuthoring` read a map nothing ever wrote. Its one real caller is
+ * `edit-mode-authoring.ts`'s installer, which is what this shape is for.)
+ */
+export type BaseAuthoringFactory = (store: EditorShellStore, worldId: string) => AuthoringAdapter;
+
+const baseFactoryBySurface = new Map<string, BaseAuthoringFactory>();
+
+/**
+ * Register the live authoring adapter for one SURFACE. Returns the unregister.
+ *
+ * A registration arriving LATE is ordinary: the contribution pass that loads
+ * an integration is deferred behind the first viewport frame, so the
+ * edit-mode composite is routinely installed before it. The registrant asks
+ * for a rebuild (`queueEditModeRebuild`) — the same door a source change uses
+ * — rather than this seam growing a notification of its own.
+ */
+export function setBaseAuthoringFactory(
+  surface: string,
+  factory: BaseAuthoringFactory,
+): () => void {
+  baseFactoryBySurface.set(surface, factory);
+  return () => {
+    if (baseFactoryBySurface.get(surface) === factory) baseFactoryBySurface.delete(surface);
+  };
+}
+
+/** The registered live adapter factory for `surface`, or null. */
+export function baseAuthoringFactory(surface: string): BaseAuthoringFactory | null {
+  return baseFactoryBySurface.get(surface) ?? null;
+}
+
+/**
+ * A non-first-party adapter (today: the ingest adapter for an unmodified game)
+ * that, while set, becomes the active authoring adapter. The editor renders its
+ * adapter-driven (format-neutral) hierarchy/inspector panels instead of the
+ * base adapter's while an override is active.
+ */
+let _override: AuthoringAdapter | null = null;
+
+/**
+ * Change notification for the override slot.
+ *
+ * The slot is module state the shared panels READ every render, so it must
+ * tell them when it changes. Relying on a side effect instead is the trap:
+ * every ingest entry path also calls `store.setActiveViewportTab(…)`, which
+ * in a project WITH a Three root activates a different center document and
+ * the workspace-document registry's own `notifyChanged()` re-renders the
+ * panels for free. In a project with NO Three root there is exactly one
+ * center document (`workspace:game`), that activation is a no-op, nothing
+ * notifies, and the Hierarchy/Inspector keep rendering the adapter they
+ * resolved BEFORE the ingest session installed its own — `getAuthoringOverride()`
+ * returns the right adapter with `{transform, inspectorFields, persist}` all
+ * true while the panels still show "No authoring adapter". A stale render,
+ * not a resolution error.
+ *
+ * So the slot notifies for itself and the panels subscribe. One mechanism,
+ * no per-session choreography.
+ */
+const _listeners = new Set<() => void>();
+let _version = 0;
+
+/** Subscribe to override changes (`useSyncExternalStore` shape). */
+export function subscribeActiveAuthoring(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+/** Monotonic version of the override slot (`useSyncExternalStore` snapshot). */
+export function activeAuthoringVersion(): number {
+  return _version;
+}
+
+/** Install/clear the active authoring override (ingest enters/exits). */
+export function setActiveAuthoring(adapter: AuthoringAdapter | null): void {
+  if (_override === adapter) return;
+  if (adapter) {
+    const evidence = inspectAuthoringAdapterSeams({ adapter, subject: 'active-authoring' });
+    const failures = [evidence.hierarchy, ...Object.values(evidence.providers)].filter(
+      (verdict) => verdict.state === 'failed',
+    );
+    if (failures.length > 0) {
+      throw new Error(
+        `authoring adapter refused: ${failures.map((failure) => failure.detail).join('; ')}`,
+      );
+    }
+  }
+  _override = adapter;
+  _version++;
+  for (const listener of [..._listeners]) listener();
+}
+
+/** True when a non-first-party adapter is driving authoring (e.g. ingest). */
+export function hasAuthoringOverride(): boolean {
+  return _override !== null;
+}
+
+/**
+ * Brand for the edit-mode composite (`edit-mode-authoring.ts`). Unlike an
+ * ingest/play override — a FOREIGN adapter whose document the store does not
+ * own — the edit-mode composite's FOCUSED child writes through the store's
+ * own save path, so
+ * the store's save guard (`_blockedForSave`) must NOT block it: an edit to the
+ * focused world must Ctrl+S/autosave to disk exactly like a single-scene
+ * project. The brand lives on the composite instance and disappears the moment
+ * `setActiveAuthoring(null)` clears the slot (the predicate checks the CURRENT
+ * `_override`'s identity), so no separate lifecycle state can go stale.
+ */
+const EDIT_MODE_BRAND = Symbol('vgai.editModeComposite');
+
+/** Mark `adapter` as the edit-mode composite. */
+export function markEditModeOverride(adapter: AuthoringAdapter): void {
+  (adapter as unknown as Record<symbol, unknown>)[EDIT_MODE_BRAND] = true;
+}
+
+/** True when the ACTIVE override is the edit-mode composite — the store's
+ *  save guard allows the focused first-party child to persist through it. */
+export function activeOverrideIsEditMode(): boolean {
+  return (
+    _override !== null &&
+    (_override as unknown as Record<symbol, unknown>)[EDIT_MODE_BRAND] === true
+  );
+}
+
+/**
+ * Peek the raw override slot (or null) without a store handle — for a session
+ * that needs to install ITS OWN override while preserving whatever was active
+ * before it, so it can restore that exact value on exit instead of assuming
+ * null (e.g. play-mode's ephemeral-persistence wrapper).
+ */
+export function getAuthoringOverride(): AuthoringAdapter | null {
+  return _override;
+}
+
+/** Every node id in an adapter's hierarchy (for select-all over an ingested tree). */
+export function collectAllNodeIds(adapter: AuthoringAdapter): string[] {
+  const ids: string[] = [];
+  const walk = (node: { id: string; childIds: string[] }): void => {
+    ids.push(node.id);
+    for (const cid of node.childIds) {
+      const c = adapter.hierarchy.node(cid);
+      if (c) walk(c);
+    }
+  };
+  for (const r of adapter.hierarchy.roots()) walk(r);
+  return ids;
+}
+
+/**
+ * The authoring adapter the editor UI should drive for `store`.
+ *
+ * The floor is HONEST and not a fallback factory: a store nothing has claimed
+ * has no document model, and inventing one for it is what the no-authoring
+ * adapter exists to refuse. Who DOES claim it is `setActiveAuthoring` (the
+ * edit-mode composite, an ingest session, play) — a live adapter for a
+ * declared world is asked for by SURFACE through {@link baseAuthoringFactory},
+ * which is a different question from "what does this store fall back to".
+ */
+export function getActiveAuthoring(store: EditorShellStore): AuthoringAdapter {
+  if (_override) return _override;
+  let a = byStore.get(store);
+  if (!a) {
+    a = makeNoAuthoringAdapter(store, 'No authoring adapter');
+    byStore.set(store, a);
+  }
+  return a;
+}