@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/components/tool-documents.tsx

@@ -0,0 +1,302 @@
+import { themeVars } from '@volter/sdk/widgets';
+/**
+ * Project-tool DOCUMENTS (W3 — inventory rows B12/T2-behavior/T3): a
+ * `placement: 'document'` project tool (including every legacy `'dock'` tool
+ * — the W0 alias rule) opens as a CENTER workspace document (kind `'tool'`,
+ * title = the tool's own declared title per §8), hosted in the same
+ * error-boundaried `ToolHost` the bottom ⚙ tabs used. `placement: 'utility'`
+ * tools stay in the bottom area — rendered as sections of the ONE Dev
+ * utility (`components/DevPanel.tsx`), never as tabs of their own.
+ * The ⚙ dock-tab row is gone.
+ *
+ * Open gesture: one `Open Tool: <title>` command-palette action per
+ * discovered document tool (`buildToolActions`) — the fixed-layout menu the
+ * ⚙ row used to be, now a searchable command.
+ *
+ * HMR/lifecycle: the document's CONTENT reads the LIVE tool store — an HMR
+ * reload bumps the tool's `version`, which re-keys the mount (fresh
+ * component + cleared error boundary, the same physics the dock tabs had);
+ * a deleted tool file leaves an honest "no longer available" message in any
+ * open document (discovery is the folder scan, D3).
+ */
+
+import { type ComponentType, useSyncExternalStore } from 'react';
+import type { EditorAction } from '../action-registry';
+import {
+  awaitAnnouncedObject3DDocumentSession,
+  waitForContributedDocumentMount,
+} from '@volter/sdk/kit/document-context-registry';
+import { registerDocumentOpener } from '@volter/sdk/kit/document-open-registry';
+import {
+  contributionFailureHint,
+  getDocumentToolContributions,
+  getGlobalToolContributions,
+  refreshProjectToolContributions,
+  subscribeToolContributions,
+} from '../tool-loader';
+import {
+  closeWorkspaceDocument,
+  type OpenWorkspaceDocumentOptions,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  type WorkspaceDocumentContentProps,
+} from '@volter/sdk/kit/workspace-document-registry';
+import { registerWorkspaceDocumentRestorer } from '@volter/sdk/kit/workspace-document-restore';
+import { ToolHost } from './ToolHost';
+
+/** The narrow store surface tool documents need (T6.3 tab hand-off). */
+/** Stable §7.1 identity for one project tool's document. */
+export function toolDocumentId(toolId: string): string {
+  return `tool:${toolId}`;
+}
+
+/** Resolve either the canonical tool-qualified id or one unambiguous package-local id. */
+export function resolveToolDocumentContributionId(id: string): string | null {
+  const contributions = getDocumentToolContributions();
+  const exact = contributions.find((item) => item.id === id);
+  if (exact) return exact.id;
+  // Ids are no longer tool-prefixed, so an exact match above is the only
+  // lookup left — there is no local-vs-qualified form to reconcile.
+  return null;
+}
+
+/**
+ * Open (or activate) the center document for one document-placement project
+ * tool. Returns `false` (opens nothing) when no discovered document tool
+ * carries that id — no fabricated documents for deleted/renamed tools.
+ */
+export function openToolDocument(
+  toolId: string,
+  options: OpenWorkspaceDocumentOptions = {},
+  /** THE WORKSPACE AREA this document fills, when a workspace's own `areas`
+   *  list is what opened it (`WorkspaceDocumentDescriptor.area`). Absent for
+   *  every other opener, which is what keeps an ordinary tool document a
+   *  centre tab. */
+  area?: string,
+): boolean {
+  const resolvedId = resolveToolDocumentContributionId(toolId);
+  const contribution = getDocumentToolContributions().find((item) => item.id === resolvedId);
+  if (!contribution) return false;
+  openWorkspaceDocument(
+    {
+      id: toolDocumentId(contribution.id),
+      ...(area === undefined ? {} : { area }),
+      // §8: the tool's own declared title, never a tech bucket.
+      title: contribution.title,
+      kind: 'tool-contribution',
+      workspaceRole: 'workspace-reference',
+      provenance: {
+        sourcePath: contribution.file,
+        origin: contribution.tool?.name ?? contribution.file,
+      },
+      Content: ToolDocumentContent,
+      // The contribution's header rides the host's own strip — the region the
+      // Game and Story documents already use — so a project document gets the
+      // same header anatomy as a built-in, drawn by the host.
+      ...(contribution.Toolbar ? { Toolbar: ToolDocumentToolbar } : {}),
+      ...(contribution.Shelf ? { Shelf: ToolDocumentShelf } : {}),
+      // A STANDING document is a place in the project, not an errand — pinned
+      // like the `3D`/`UI`/`Dev` boards. See `GlobalToolContribution.standing`.
+      // AN AREA DOCUMENT IS PINNED TOO, and for a stronger reason: it is not
+      // a tab at all, it IS the workspace's second editor group, and a close
+      // affordance on it would offer to empty a group nothing refills.
+      closeable: area === undefined && !contribution.standing,
+      presentation: () => ({ kind: 'tool', id: contribution.id }),
+      // AN AREA DOCUMENT DOES NOT PERSIST ITSELF. The WORKSPACE reopens it,
+      // from its own `areas` list, and it does so knowing the area id — a
+      // restorer running first would reopen the same contribution with NO
+      // area and strand it as a centre tab beside the model. `undefined` is
+      // the descriptor's own documented opt-out for "something else
+      // re-derives this at boot", which is exactly the case here.
+      ...(area === undefined ? { persist: () => ({ contributionId: contribution.id }) } : {}),
+    },
+    options,
+  );
+  return true;
+}
+
+/** Reopen a persisted tool document. `openToolDocument` is self-verifying —
+ *  a deleted or renamed contribution opens nothing and answers `false`, so
+ *  the stale panel is reconciled away. No `prepare`: the discovery pass this
+ *  kind used to await for itself is now the restore's own first step, run for
+ *  EVERY record because a package owns its restorer as well as its documents
+ *  (`workspace-state-persistence.ts`, "contributions load first"). Keeping
+ *  both ran the pass twice per boot — three reports of each unimplemented
+ *  stub instead of one, measured on a `full` scaffold 2026-09-18. */
+registerWorkspaceDocumentRestorer({
+  kind: 'tool-contribution',
+  owner: 'tool-documents',
+  restore: ({ state }) => {
+    const record = state as { contributionId?: unknown } | null | undefined;
+    const contributionId =
+      typeof record?.contributionId === 'string' ? record.contributionId : null;
+    return contributionId !== null && openToolDocument(contributionId);
+  },
+});
+
+/**
+ * THE `tool` ADDRESS (`document-open-registry.ts`) — the other half of the
+ * `presentation()` above, so the presenter reaches a contributed document
+ * without importing this module. Registered at module load, the shape
+ * `packages/editor-game/src/three/story-documents/three-story-documents.tsx:239` uses.
+ *
+ * SETTLING is the discovery pass this kind opens out of. A cold Vite graph can
+ * register the project catalog before its document contribution modules finish
+ * loading, and an explicit address is durable intent, so the owning pass is
+ * DRIVEN rather than raced with a timeout — what the presenter did by hand.
+ * "Not registered" then has two causes that need different fixes (no such
+ * contribution exists, or one exists and its module threw on import) and
+ * `contributionFailureHint` is what tells them apart; a generic refusal used to
+ * send the reader hunting for a missing file that was on disk all along, so
+ * this address refuses in its own words.
+ */
+registerDocumentOpener<{ readonly id: string }>({
+  id: 'tool',
+  owner: 'tool-documents',
+  open: (_store, request) => {
+    // Resolve FIRST: `openToolDocument` resolves the same way and the document
+    // id is built from what it found, so the resolution is the answer.
+    const resolvedId = resolveToolDocumentContributionId(request.id);
+    if (resolvedId === null) return null;
+    return openToolDocument(resolvedId) ? toolDocumentId(resolvedId) : null;
+  },
+  settle: async (request) => {
+    await refreshProjectToolContributions();
+    if (resolveToolDocumentContributionId(request.id) !== null) return;
+    throw new Error(
+      `Tool document is not registered: ${request.id}.${contributionFailureHint(request.id)}`,
+    );
+  },
+  /**
+   * THE KIND'S OWN READINESS — a contributed document is ready to be driven
+   * once its React root has committed and, if that root mounted a stage, once
+   * the stage has registered its Object3D session. The presenter used to hold
+   * this rule for this address by name (`editor-view-presentation.ts`'s
+   * `kind === 'tool' || 'asset'`); it belongs here, where the contribution the
+   * host mounted is what answers.
+   */
+  ready: async (documentId) => {
+    await waitForContributedDocumentMount(documentId);
+    await awaitAnnouncedObject3DDocumentSession(documentId);
+  },
+});
+
+/**
+ * Open every STANDING document contribution, and keep that set in step with
+ * discovery: a capability added mid-session brings its tab with it, and a
+ * capability whose source is deleted takes its tab away rather than leaving a
+ * pinned panel nothing backs.
+ *
+ * Returns the teardown for the subscription (it does not close the documents —
+ * the project-open path owns that, the same way it owns the boards).
+ */
+export function installStandingToolDocuments(): () => void {
+  const opened = new Set<string>();
+  const reconcile = () => {
+    const standing = getDocumentToolContributions().filter((item) => item.standing);
+    const live = new Set(standing.map((item) => item.id));
+    for (const id of opened) {
+      if (live.has(id)) continue;
+      closeWorkspaceDocument(toolDocumentId(id), { discardDirty: true });
+      opened.delete(id);
+    }
+    for (const item of standing) {
+      if (opened.has(item.id)) continue;
+      if (openToolDocument(item.id, { activate: false })) opened.add(item.id);
+    }
+    // EVERY open tool document takes its slots afresh on discovery change,
+    // standing or not: a module re-evaluated on save may have gained or lost
+    // its `Toolbar`, and `openWorkspaceDocument` on an open id is what
+    // refreshes the descriptor's mount slots (see the registry).
+    const open = new Set(openWorkspaceDocuments().map((d) => d.descriptor.id));
+    for (const item of getDocumentToolContributions()) {
+      if (!open.has(toolDocumentId(item.id))) continue;
+      openToolDocument(item.id, { activate: false });
+    }
+  };
+  reconcile();
+  return subscribeToolContributions(reconcile);
+}
+
+/** `Open Tool: <title>` palette actions — one per discovered document tool
+ *  (the B12 discovery gesture). A standing document is always open, so its
+ *  action ACTIVATES the tab rather than teaching a way to summon it. */
+export function buildToolActions(): EditorAction[] {
+  return getDocumentToolContributions().map((t) => ({
+    id: `tool-doc:${t.id}`,
+    label: t.standing ? `Show ${t.title}` : `Open Tool: ${t.title}`,
+    category: 'action' as const,
+    execute: () => void openToolDocument(t.id),
+  }));
+}
+
+/** Content host: resolves the LIVE tool by id on every render (HMR re-key,
+ *  honest deleted-tool state). */
+/** The header strip's contents for a tool document: the contribution's own
+ *  `Toolbar`, mounted through the same host so it reads the same props. */
+export function ToolDocumentToolbar({ documentId, active }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeToolContributions, getGlobalToolContributions);
+  const toolId = documentId.startsWith('tool:') ? documentId.slice('tool:'.length) : documentId;
+  const contribution = getDocumentToolContributions().find((item) => item.id === toolId);
+  if (!contribution?.Toolbar) return null;
+  return (
+    <ToolHost
+      key={`${contribution.id}:${contribution.version}:toolbar`}
+      contribution={contribution}
+      Component={contribution.Toolbar as unknown as ComponentType<Record<string, unknown>>}
+      documentId={documentId}
+      active={active}
+    />
+  );
+}
+
+/** The shelf rail's contents for a tool document: the contribution's own
+ *  `Shelf`, mounted through the same host so it reads the same props. */
+export function ToolDocumentShelf({ documentId, active }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeToolContributions, getGlobalToolContributions);
+  const toolId = documentId.startsWith('tool:') ? documentId.slice('tool:'.length) : documentId;
+  const contribution = getDocumentToolContributions().find((item) => item.id === toolId);
+  if (!contribution?.Shelf) return null;
+  return (
+    <ToolHost
+      key={`${contribution.id}:${contribution.version}:shelf`}
+      contribution={contribution}
+      Component={contribution.Shelf as unknown as ComponentType<Record<string, unknown>>}
+      documentId={documentId}
+      active={active}
+    />
+  );
+}
+
+export function ToolDocumentContent({ documentId, active }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeToolContributions, getGlobalToolContributions);
+  const toolId = documentId.startsWith('tool:') ? documentId.slice('tool:'.length) : documentId;
+  const contribution = getDocumentToolContributions().find((item) => item.id === toolId);
+  if (!contribution) {
+    return (
+      <div
+        style={{ padding: 12, fontSize: 12, color: themeVars.content.muted, pointerEvents: 'auto' }}
+      >
+        This tool contribution is no longer registered — close this document.
+      </div>
+    );
+  }
+  return (
+    <div
+      key={`${contribution.id}:${contribution.version}`}
+      data-testid={`tool-document:${contribution.id}`}
+      style={{
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        pointerEvents: 'auto',
+        // B-11: the editor-provided baseline breathing room every hosted
+        // surface's content root has by convention (carried from the dock).
+        padding: 12,
+      }}
+    >
+      <ToolHost contribution={contribution} documentId={documentId} active={active} />
+    </div>
+  );
+}

package/src/kit/components/tool-schema-form.tsx

@@ -0,0 +1,262 @@
+import { Checkbox, Select, TextInput, text } from '@volter/sdk/widgets';
+import type { CSSProperties } from 'react';
+
+type JsonSchema = Record<string, unknown>;
+
+function schemaRecord(value: unknown): JsonSchema {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as JsonSchema) : {};
+}
+
+function schemaType(schema: JsonSchema): string | undefined {
+  const type = schema['type'];
+  if (typeof type === 'string') return type;
+  if (Array.isArray(type)) return type.find((item): item is string => item !== 'null');
+  return undefined;
+}
+
+export function defaultValueForSchema(value: unknown): unknown {
+  const schema = schemaRecord(value);
+  if ('default' in schema) return structuredClone(schema['default']);
+  const type = schemaType(schema);
+  if (type === 'object' || schema['properties']) {
+    const result: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(schemaRecord(schema['properties']))) {
+      const childSchema = schemaRecord(child);
+      if (
+        'default' in childSchema ||
+        (Array.isArray(schema['required']) && schema['required'].includes(key))
+      ) {
+        result[key] = defaultValueForSchema(childSchema);
+      }
+    }
+    return result;
+  }
+  if (type === 'array') return [];
+  if (type === 'boolean') return false;
+  if (type === 'number' || type === 'integer') return Number(schema['minimum'] ?? 0);
+  return '';
+}
+
+function humanize(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]/g, ' ')
+    .replace(/^./, (letter) => letter.toUpperCase());
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: this is the deliberately small JSON-Schema widget dispatch; each primitive type remains native HTML.
+function PrimitiveField({
+  name,
+  schema,
+  value,
+  required,
+  onChange,
+}: {
+  name: string;
+  schema: JsonSchema;
+  value: unknown;
+  required: boolean;
+  onChange(value: unknown): void;
+}) {
+  const type = schemaType(schema);
+  const description = typeof schema['description'] === 'string' ? schema['description'] : null;
+  const choices = Array.isArray(schema['enum']) ? schema['enum'] : null;
+  const id = `tool-field:${name}`;
+
+  if (type === 'boolean') {
+    return (
+      <label style={{ ...fieldStyle, gridTemplateColumns: '18px minmax(0, 1fr)' }}>
+        <Checkbox
+          id={id}
+          checked={value === true}
+          onChange={(event) => onChange(event.target.checked)}
+        />
+        <span>
+          <span style={fieldLabelStyle}>{humanize(name)}</span>
+          {description && <span style={descriptionStyle}>{description}</span>}
+        </span>
+      </label>
+    );
+  }
+
+  const label = (
+    <span style={fieldLabelStyle}>
+      {humanize(name)} {!required && <span style={optionalStyle}>optional</span>}
+    </span>
+  );
+
+  if (choices) {
+    return (
+      <label style={fieldStyle} htmlFor={id}>
+        {label}
+        <Select
+          id={id}
+          value={String(value ?? '')}
+          onChange={(event) => onChange(event.target.value)}
+          style={controlLayoutStyle}
+        >
+          {!required && <option value="">Not set</option>}
+          {choices.map((choice) => (
+            <option key={String(choice)} value={String(choice)}>
+              {String(choice)}
+            </option>
+          ))}
+        </Select>
+        {description && <span style={descriptionStyle}>{description}</span>}
+      </label>
+    );
+  }
+
+  if (type === 'number' || type === 'integer') {
+    return (
+      <label style={fieldStyle} htmlFor={id}>
+        {label}
+        <TextInput
+          id={id}
+          type="number"
+          value={typeof value === 'number' ? value : ''}
+          min={typeof schema['minimum'] === 'number' ? schema['minimum'] : undefined}
+          max={typeof schema['maximum'] === 'number' ? schema['maximum'] : undefined}
+          step={type === 'integer' ? 1 : 'any'}
+          onChange={(event) =>
+            onChange(event.target.value === '' ? undefined : Number(event.target.value))
+          }
+          style={controlLayoutStyle}
+        />
+        {description && <span style={descriptionStyle}>{description}</span>}
+      </label>
+    );
+  }
+
+  if (type === 'array' && schemaType(schemaRecord(schema['items'])) === 'string') {
+    return (
+      <label style={fieldStyle} htmlFor={id}>
+        {label}
+        <TextInput
+          id={id}
+          value={Array.isArray(value) ? value.join(', ') : ''}
+          onChange={(event) =>
+            onChange(
+              event.target.value
+                .split(',')
+                .map((item) => item.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder="Comma-separated values"
+          style={controlLayoutStyle}
+        />
+        {description && <span style={descriptionStyle}>{description}</span>}
+      </label>
+    );
+  }
+
+  return (
+    <label style={fieldStyle} htmlFor={id}>
+      {label}
+      <TextInput
+        id={id}
+        value={typeof value === 'string' ? value : ''}
+        onChange={(event) => onChange(event.target.value || (required ? '' : undefined))}
+        style={controlLayoutStyle}
+      />
+      {description && <span style={descriptionStyle}>{description}</span>}
+    </label>
+  );
+}
+
+function ObjectFields({
+  schema,
+  value,
+  onChange,
+  path = '',
+}: {
+  schema: JsonSchema;
+  value: Record<string, unknown>;
+  onChange(value: Record<string, unknown>): void;
+  path?: string;
+}) {
+  const properties = schemaRecord(schema['properties']);
+  const required = new Set(Array.isArray(schema['required']) ? schema['required'] : []);
+  return (
+    <div style={{ display: 'grid', gap: 14 }}>
+      {Object.entries(properties).map(([key, child]) => {
+        const childSchema = schemaRecord(child);
+        const childType = schemaType(childSchema);
+        const update = (next: unknown) => {
+          const copy = { ...value };
+          if (next === undefined) delete copy[key];
+          else copy[key] = next;
+          onChange(copy);
+        };
+        if (childType === 'object' || childSchema['properties']) {
+          return (
+            <fieldset key={key} style={fieldsetStyle}>
+              <legend style={legendStyle}>{humanize(key)}</legend>
+              {typeof childSchema['description'] === 'string' && (
+                <p style={{ ...descriptionStyle, marginTop: 0 }}>{childSchema['description']}</p>
+              )}
+              <ObjectFields
+                schema={childSchema}
+                value={schemaRecord(value[key])}
+                onChange={update}
+                path={path ? `${path}.${key}` : key}
+              />
+            </fieldset>
+          );
+        }
+        return (
+          <PrimitiveField
+            key={key}
+            name={path ? `${path}.${key}` : key}
+            schema={childSchema}
+            value={value[key]}
+            required={required.has(key)}
+            onChange={update}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+export function ToolSchemaForm({
+  schema: schemaValue,
+  value,
+  onChange,
+}: {
+  schema: unknown;
+  value: Record<string, unknown>;
+  onChange(value: Record<string, unknown>): void;
+}) {
+  const schema = schemaRecord(schemaValue);
+  if (!schema['properties']) {
+    return <div style={descriptionStyle}>This schema has no form-compatible fields.</div>;
+  }
+  return <ObjectFields schema={schema} value={value} onChange={onChange} />;
+}
+
+const fieldStyle: CSSProperties = { display: 'grid', gap: 5 };
+const fieldLabelStyle: CSSProperties = {
+  color: text[1],
+  fontWeight: 600,
+  fontSize: 'var(--volter-font-sm)',
+};
+const optionalStyle: CSSProperties = { color: text[3], fontWeight: 400, marginLeft: 5 };
+const descriptionStyle: CSSProperties = {
+  display: 'block',
+  color: text[2],
+  fontSize: 'var(--volter-font-sm)',
+  lineHeight: 1.4,
+};
+const controlLayoutStyle: CSSProperties = {
+  boxSizing: 'border-box',
+  width: '100%',
+};
+const fieldsetStyle: CSSProperties = {
+  margin: 0,
+  padding: 14,
+  border: '1px solid var(--volter-boundary-default)',
+  borderRadius: 'var(--volter-radius-md)',
+};
+const legendStyle: CSSProperties = { padding: '0 6px', color: text[1], fontWeight: 600 };

package/src/kit/components/use-after-paint.ts

@@ -0,0 +1,41 @@
+/**
+ * "Mount this AFTER the browser has painted the commit that asked for it."
+ *
+ * The inspector's live preview is the case this exists for: its mount effect
+ * builds a scene snapshot and draws the first frame, and React runs that effect
+ * in the SAME task as the selection commit — so the card, the name and the
+ * preview all appeared together, whenever the preview was finally done. Gating
+ * the heavy child on this hook lets the commit paint first; the picture arrives
+ * in a later frame and nothing is waiting on it.
+ *
+ * Two frames, not one: the first `requestAnimationFrame` callback runs BEFORE
+ * the paint of the commit that scheduled it, so only the second is past it.
+ * `startTransition` is the wrong tool here — the work is not React rendering,
+ * it is a `useEffect` doing GL work, which a transition does not defer.
+ *
+ * `key` identifies what is being waited for (a subject id, a preview key). It
+ * matters because these hosts are RE-RENDERED rather than remounted as the
+ * selection changes: comparing against the key that became ready is what makes
+ * the next subject wait again instead of inheriting the last one's readiness.
+ *
+ * Callers put the gate where their PLACEHOLDER is — the mini card's preview
+ * shows its quiet kind glyph, the section body shows its empty box — which is
+ * why this is a hook and not a wrapper component with one built-in fallback.
+ */
+
+import { useEffect, useState } from 'react';
+
+export function useAfterPaint(key: string): boolean {
+  const [readyKey, setReadyKey] = useState<string | null>(null);
+  useEffect(() => {
+    let second = 0;
+    const first = requestAnimationFrame(() => {
+      second = requestAnimationFrame(() => setReadyKey(key));
+    });
+    return () => {
+      cancelAnimationFrame(first);
+      cancelAnimationFrame(second);
+    };
+  }, [key]);
+  return readyKey === key;
+}

package/src/kit/components/use-project-image-assets.ts

@@ -0,0 +1,86 @@
+/**
+ * The project's own IMAGE assets, for the inspector's `asset` slots.
+ *
+ * This is the existing asset-workflow seam and nothing new: the same
+ * `listAssets` walk over `public/` that the Asset Browser's Content gallery
+ * runs (`collectProjectContentAssets`), narrowed with the same facet
+ * classifier (`projectContentAssetFacet`). A texture slot must offer the same
+ * files the Asset Browser shows, so it reads them from the same place rather
+ * than growing a second listing.
+ *
+ * ONE scan is shared by every slot on screen — a `MeshStandardMaterial`
+ * publishes six of them, and six independent walks of `public/` per selection
+ * is the kind of quiet cost a panel never recovers from. The cached scan
+ * expires so an asset imported mid-session shows up on the next selection
+ * without a reload; the Asset Browser is still the surface that IMPORTS.
+ */
+
+import { useEffect, useState } from 'react';
+import {
+  collectProjectContentAssets,
+  projectContentAssetFacet,
+} from '@volter/sdk/kit/asset-workflow/project-content';
+import { listAssets } from '@volter/sdk/kit/editor-api';
+
+/** How long a scan is reused. Long enough to cover one selection's worth of
+ *  slots mounting together, short enough that a just-imported texture appears
+ *  without a reload. */
+const CACHE_MS = 10_000;
+
+export interface ProjectImageAssets {
+  /** Public-root-relative paths, sorted. */
+  readonly paths: readonly string[];
+  /** Directories whose listing FAILED — an empty picker over a failed scan
+   *  would tell the author their project has no textures. */
+  readonly failures: readonly string[];
+}
+
+const EMPTY: ProjectImageAssets = { paths: [], failures: [] };
+
+let cached: { at: number; scan: Promise<ProjectImageAssets> } | null = null;
+
+async function scanProjectImageAssets(): Promise<ProjectImageAssets> {
+  // SHIPPED IMAGES ONLY. A material slot names a file the GAME loads at
+  // runtime, and reference material is never exported — offering a moodboard
+  // plate here would author a texture path that 404s in the built game.
+  const listed = await collectProjectContentAssets(listAssets, ['public']);
+  return {
+    paths: listed.assets
+      .filter((asset) => projectContentAssetFacet(asset.entry.name) === 'image')
+      .map((asset) => asset.path)
+      .sort((a, b) => a.localeCompare(b)),
+    failures: listed.failedListings,
+  };
+}
+
+/** The shared scan, refreshed when the cached one has expired. */
+export function projectImageAssets(): Promise<ProjectImageAssets> {
+  const now = Date.now();
+  if (!cached || now - cached.at > CACHE_MS) {
+    cached = {
+      at: now,
+      scan: scanProjectImageAssets().catch((error: unknown) => {
+        cached = null;
+        return { paths: [], failures: [error instanceof Error ? error.message : String(error)] };
+      }),
+    };
+  }
+  return cached.scan;
+}
+
+/** Read the shared scan into a component. `enabled: false` skips it entirely,
+ *  so a panel with no asset row never walks `public/`. */
+export function useProjectImageAssets(enabled: boolean): ProjectImageAssets {
+  const [assets, setAssets] = useState<ProjectImageAssets>(EMPTY);
+  useEffect(() => {
+    if (!enabled) return;
+    let live = true;
+    void projectImageAssets().then((next) => {
+      if (live) setAssets(next);
+    });
+    return () => {
+      live = false;
+    };
+  }, [enabled]);
+  return assets;
+}