@volter/editor-core 0.5.57

package/src/command-registry.ts

@@ -0,0 +1,70 @@
+/**
+ * CONTRIBUTED COMMANDS — the registry behind `@volter/editor-sdk/commands`.
+ * `command-listener.ts` asks here before its own table, so a package's verb
+ * is answered by the package's handler with the host's relay, ack and
+ * status-derivation machinery unchanged around it. The rows are also what the
+ * loader reports to the server (`/__editor/contributed-commands`), which
+ * sizes its wait per verb from them.
+ */
+import type {
+  CommandContribution,
+  CommandDerivedRefresh,
+  CommandSpec,
+  ContributedCommandRow,
+} from '@volter/editor-sdk/commands';
+import {
+  DEFAULT_RELAY_COMMAND_TIMEOUT_MS,
+  isRelayCommandType,
+} from '@volter/editor-sdk/session/command-table';
+
+interface Registered {
+  readonly entryPath: string;
+  readonly spec: CommandSpec;
+}
+const registered = new Map<string, Registered>();
+
+/**
+ * Register a contribution's commands. Every type is checked before any is
+ * claimed, so a module with one bad row registers nothing. Returns the
+ * unregister.
+ */
+export function registerContributedCommands(
+  entryPath: string,
+  commands: CommandContribution['commands'],
+): () => void {
+  const types = Object.keys(commands);
+  for (const type of types) {
+    if (isRelayCommandType(type))
+      throw new Error(`command "${type}" is the editor's own; a contribution cannot redefine it.`);
+    const other = registered.get(type);
+    if (other) throw new Error(`command "${type}" is already contributed by ${other.entryPath}.`);
+    const spec = commands[type];
+    if (typeof spec?.handle !== 'function')
+      throw new Error(`command "${type}" must carry a \`handle\` function.`);
+    if (spec.timeoutMs !== undefined && !(Number.isFinite(spec.timeoutMs) && spec.timeoutMs > 0))
+      throw new Error(`command "${type}" has a timeoutMs that is not a positive number.`);
+  }
+  for (const type of types) registered.set(type, { entryPath, spec: commands[type]! });
+  return () => {
+    for (const type of types)
+      if (registered.get(type)?.entryPath === entryPath) registered.delete(type);
+  };
+}
+
+export function contributedCommand(type: unknown): CommandSpec | null {
+  return typeof type === 'string' ? (registered.get(type)?.spec ?? null) : null;
+}
+
+export function contributedCommandDerivedRefresh(type: unknown): CommandDerivedRefresh | null {
+  const spec = contributedCommand(type);
+  return spec ? (spec.derivedRefresh ?? 'always') : null;
+}
+
+/** Every registered row, as reported to the server. */
+export function contributedCommandRows(): ContributedCommandRow[] {
+  return [...registered.entries()].map(([type, { spec }]) => ({
+    type,
+    timeoutMs: spec.timeoutMs ?? DEFAULT_RELAY_COMMAND_TIMEOUT_MS,
+    derivedRefresh: spec.derivedRefresh ?? 'always',
+  }));
+}

package/src/component-board-registry.ts

@@ -0,0 +1,205 @@
+/**
+ * A COMPONENT BOARD IS REGISTERED — the sixth registry in the family of
+ * `workspace-document-restore.ts` (a kind owns its persisted state),
+ * `document-open-registry.ts` (a kind owns how it opens),
+ * `chrome-slot-registry.ts` (the host owns the place, a package owns what sits
+ * there), `content-entry-source-registry.ts` (the host owns the Content scope,
+ * a package owns why a component is content) and
+ * `authoring/design-time-mount-registry.ts` (the host owns the layer stack, a
+ * package owns how a medium mounts). Here: the host owns WHERE a project's
+ * component boards sit in the workspace — installing one, closing one,
+ * answering why one is absent — and a package owns WHICH medium it is a board
+ * of, whether this project has one, and what goes in it.
+ *
+ * WHY IT EXISTS. `components/world-documents.tsx` held a literal table of
+ * three media with an installer each (`COMPONENT_BOARDS`), reconciled against
+ * `getStoryMediaPresence()`, plus two absence thunks gated on
+ * `projectStoriesReady()`. Three statements about CSF, made in the host: that
+ * a project's boards are `dom`/`three`/`canvas`; that a board exists because
+ * the project has stories of that medium; and that "no board yet" and "no
+ * board ever" are told apart by a story-DISCOVERY flag. The host does not
+ * author portable CSF and must not know any of it (WORK.md §The open-source
+ * launch item 18a).
+ *
+ * THE SHAPE is transcribed from `content-entry-source-registry.ts:80-149`:
+ * register / list / subscribe with the owner-replaces-owner rule, and the
+ * registry RE-FANS each board's own `subscribe` into one signal, because the
+ * host's single reconciler must re-read when any board's verdict moves and
+ * which board moved is never its question (`:89-91`, `:122`). Three
+ * deliberate differences from `design-time-mount-registry.ts`, the sibling
+ * this door most resembles, each with its reason:
+ *
+ *  - NO VERSION COUNTER, for that registry's reason: the only reader is
+ *    `installRootDocuments`, which subscribes and re-reads. A counter with no
+ *    caller is a name that got built because it was named.
+ *  - PRESENCE IS RE-FANNED, where a design-time mount's staleness deliberately
+ *    is not. The distinction is the one that registry's own note draws: a
+ *    staleness signal must reach the ONE stack that mounted that medium
+ *    carrying which action to take, while board presence is a registration-wide
+ *    fact the single reconciler acts on uniformly.
+ *  - NO `remountWhen`, AND THAT IS A MEASUREMENT. The membership rule this door
+ *    was specified to absorb (a story added or deleted while a board is
+ *    mounted must put the new frame on screen without F5) is a statement about
+ *    a MEDIUM's mounted layers, which is exactly `DesignTimeMount.remountWhen`
+ *    / `reprojectWhen` — already bound per medium by `mountDesignTimeLayers`
+ *    (`design-time-layers.ts:717-742`) and already carrying this lane's two
+ *    other staleness rules. A second hook here would fire on a board whose
+ *    layers are not stories at all: the rule lived in `RootDocumentContent`,
+ *    which mounts the dom board AND the canvas Scene, so a canvas world was
+ *    being torn down and rebuilt every time an unrelated dom story was saved.
+ *    It travels with the dom mount instead.
+ *
+ * PRESENCE IS TRI-STATE, and the third state is the whole point. `null` means
+ * "cannot answer yet" — a board whose census has not run. The host used to
+ * spell that condition itself as `projectStoriesReady()`, so it knew that a
+ * board waits on story discovery; now it knows only that a registration may
+ * not have a verdict, which is the same thing a document opener's `ready` and
+ * a design-time mount's late registration already say. An absence is spoken
+ * only when the owner has a verdict.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. A build whose package list carries no
+ * board installs none and says so through the generic "no workspace document
+ * is named …" — the same honest emptiness a document kind with no registered
+ * opener gives.
+ */
+
+import type { CompositeAuthoringAdapter } from './authoring/composite-authoring-adapter';
+import type { EditorShellStore } from './editor-shell-store';
+
+/** Everything a board reads from the HOST at install, and deliberately
+ *  nothing more — measured against the three installers as they stood:
+ *  `installThreeBoardDocument` and `installCanvasBoardDocument` read the shell
+ *  store alone; the UI board additionally reads the session's composite,
+ *  because it is a document OF a root and carries that root's provenance. */
+export interface ComponentBoardContext {
+  /** The ONE format-neutral shell store the session's documents are opened
+   *  against. */
+  readonly store: EditorShellStore;
+  /** The live session's composite authoring adapter — the roots this project
+   *  actually mounted, for a board that is also a root's document. */
+  readonly composite: CompositeAuthoringAdapter;
+}
+
+export interface ComponentBoard {
+  /**
+   * The medium this is the board of, in the registering package's own
+   * vocabulary. The host never spells one: it compares this against a
+   * design-time root descriptor's `kind` to decide whether that root's
+   * document IS this board, and otherwise only passes it back.
+   */
+  readonly medium: string;
+  /** Which module registered it. Re-registering the same owner+medium
+   *  REPLACES, so an HMR re-evaluation leaves one board, not two. */
+  readonly owner: string;
+  /** The workspace document id this board installs under. The host closes by
+   *  it and answers "why is this id absent" from it. */
+  readonly documentId: string;
+  /** How the board is named to a human, for the host's own absence prose
+   *  ("this project has no <title> board"). */
+  readonly title: string;
+  /**
+   * Does this project have this board? `'present'` installs it, `'absent'`
+   * closes it, and `null` is "no verdict yet" — the host neither installs nor
+   * speaks an absence, because a census that has not run is not a No.
+   */
+  readonly presence: () => 'present' | 'absent' | null;
+  /** The board's OWN change signal — its census settling, its discovery pass
+   *  finishing. The host re-reconciles on it without knowing what moved. */
+  readonly subscribe: (listener: () => void) => () => void;
+  /**
+   * Open this board's workspace document. Called once per transition into
+   * `'present'`; the host closes it by {@link documentId}, exactly as it did
+   * when the table was a literal. Never activates: a board arrives
+   * asynchronously and must not yank the author off what they were looking at.
+   *
+   * MAY BE ASYNCHRONOUS — a board whose renderer costs a whole substrate
+   * (the 2D board initializes Pixi) loads its implementation only for a
+   * project that has one. A rejected promise or a throw un-reserves the id
+   * here, so the next verdict retries; saying WHAT failed is the board's own
+   * job, because only it knows what it was loading.
+   */
+  readonly install: (context: ComponentBoardContext) => void | Promise<void>;
+  /**
+   * Why THIS project has no board of this medium, and what would make one
+   * appear — the fix text, in the lane's own vocabulary. Read only while
+   * {@link presence} says `'absent'`.
+   */
+  readonly absentReason: () => string;
+}
+
+const _boards: ComponentBoard[] = [];
+const listeners = new Set<() => void>();
+/** Live teardowns for the per-board presence subscriptions the registry
+ *  re-fans (`content-entry-source-registry.ts:102`). */
+const boardSubscriptions = new Map<ComponentBoard, () => void>();
+
+function publish(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Install a board. Returns the teardown. */
+export function registerComponentBoard(board: ComponentBoard): () => void {
+  const stale = _boards.findIndex(
+    (item) => item.owner === board.owner && item.medium === board.medium,
+  );
+  if (stale >= 0) {
+    const [removed] = _boards.splice(stale, 1);
+    if (removed) {
+      boardSubscriptions.get(removed)?.();
+      boardSubscriptions.delete(removed);
+    }
+  }
+  _boards.push(board);
+  boardSubscriptions.set(board, board.subscribe(publish));
+  publish();
+  return () => {
+    const at = _boards.indexOf(board);
+    if (at < 0) return;
+    _boards.splice(at, 1);
+    boardSubscriptions.get(board)?.();
+    boardSubscriptions.delete(board);
+    publish();
+  };
+}
+
+const EMPTY: readonly ComponentBoard[] = [];
+
+/** Everything registered, in registration order. A stable array while nothing
+ *  changes, so a reader can compare identities across a notification. */
+export function componentBoards(): readonly ComponentBoard[] {
+  return _boards.length === 0 ? EMPTY : _boards;
+}
+
+/** The board of one medium, or `null` — "no package registered one", which is
+ *  a real answer and never an error. The LAST registration wins, the same way
+ *  a later design-time mount of the same kind does. */
+export function componentBoardForMedium(medium: string): ComponentBoard | null {
+  for (let i = _boards.length - 1; i >= 0; i--) {
+    const board = _boards[i];
+    if (board && board.medium === medium) return board;
+  }
+  return null;
+}
+
+/** The board installed under a workspace document id, or `null`. */
+export function componentBoardForDocument(documentId: string): ComponentBoard | null {
+  return _boards.find((board) => board.documentId === documentId) ?? null;
+}
+
+/** ONE subscription for the reconciler: the registry's own changes AND every
+ *  registered board's presence signal. What changed is never its question. */
+export function subscribeComponentBoards(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot, content-source and
+ *  design-time-mount registries'). */
+export function __resetComponentBoardsForTest(): void {
+  for (const stop of boardSubscriptions.values()) stop();
+  boardSubscriptions.clear();
+  _boards.length = 0;
+  publish();
+}

package/src/component-states-registry.ts

@@ -0,0 +1,200 @@
+/**
+ * A COMPONENT'S NAMED STATES ARE SOURCED, NOT CONSTRUCTED — the seventh
+ * registry in the family, and the direct sibling of the member unit 11 minted
+ * next door: `content-entry-source-registry.ts:166-176`'s
+ * `contentEntryForComponent(ref)` answers "what does this component LOOK
+ * like?" by registration; this answers "what named STATES does it have, and
+ * what does applying one do?".
+ *
+ * WHY IT EXISTS. `StoriesProvider` (`@volter/editor-project/adapter` authoring.ts:706) is the
+ * ENGINE's contract and does not change — an adapter says which named states a
+ * node has, in its own vocabulary. What changed is who FILLS it. Three
+ * keep-bucket host adapters CONSTRUCTED the CSF implementation inside their own
+ * constructors:
+ *
+ *   authoring/r3f-source-authoring-adapter.ts:637   unconditional
+ *   authoring/three-authoring-adapter.ts:506        gated on `sourceDeclaresStories`
+ *   authoring/pixi-authoring-adapter.ts:773         gated on the target's identity
+ *
+ * and no registry reaches into a constructor, so no existing point carried it
+ * — which is why `authoring/project-three-stories.ts` (and through it
+ * `stories/story-registry.ts`, and through THAT `storybook/internal/preview-api`)
+ * could not leave the host however many boards moved (WORK.md §The open-source
+ * launch item 18b).
+ *
+ * WHAT THE MEASUREMENT SAID THE THREE CONSTRUCTIONS DIFFER BY, and therefore
+ * what a source must be handed rather than hold:
+ *
+ *  - THE COMPONENT-IDENTITY CLOSURE. All three produce the same SHAPE
+ *    ({@link ComponentStatesRef}) by three different routes: the R3F source
+ *    adapter resolves a definition/callsite and can name the defining FILE;
+ *    the three adapter reads its hierarchy node's `typeLabel` and has no file;
+ *    the pixi adapter delegates to its write target's `componentIdentity`.
+ *    That closure stays with the adapter — it is the adapter's own semantic
+ *    knowledge of what a node IS — and travels per call.
+ *  - THE SURFACE. The three-flavoured construction applied a state by opening
+ *    the Object3D turntable; the canvas one opened the ordinary isolated story
+ *    document. That was the ONLY difference between the two factory functions.
+ *    A source is handed the asking adapter's surface and dispatches on it, the
+ *    way the story opener's own readiness does.
+ *
+ * WHAT THE HOST KEEPS, and why it is not a leak: the per-node ACTIVE map and
+ * the change notification — identical in all three constructions, about the
+ * editor session rather than about states — and the refusal when an `apply`
+ * names a state that does not belong to the node. {@link componentStatesProvider}
+ * is that bookkeeping and nothing else.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER, and here it is a SPOKEN one: the
+ * provider's `unavailable()` says that no package registered a source, which
+ * is precisely the distinction that member exists to draw ("an empty
+ * `storiesFor` and an UNREAD one look identical from the section that draws
+ * them, and only the provider knows which").
+ *
+ * DELIBERATELY ABSENT: `isolate` and `title`. `StoriesProvider` publishes
+ * both, no CSF construction ever supplied either (`resolveComposeStoriesInput`
+ * passes `isolation: null` unconditionally), and a member on a registry gets
+ * built whether or not anything wants it. They belong here the day a source
+ * has one.
+ */
+
+import type { AdapterSurface, StoriesProvider, StoryRef } from '@volter/editor-project/adapter';
+import { editorConsole } from './editor-console';
+import type { EditorShellStore } from './editor-shell-store';
+
+/**
+ * A component as a STATES source sees it — the exact shape all three adapter
+ * closures already produced. `sourcePath` is absent for an adapter that knows
+ * the component's NAME but not the module it is defined in.
+ */
+export interface ComponentStatesRef {
+  readonly name: string;
+  readonly sourcePath?: string;
+}
+
+/** What a source is asked the question IN. */
+export interface ComponentStatesContext {
+  /** The authoring surface the asking adapter mounts on. A source that means
+   *  different things on different surfaces (opening a state in the Object3D
+   *  turntable versus the isolated story document) dispatches on it; the host
+   *  never reads it. */
+  readonly surface: AdapterSurface;
+  /** The ONE format-neutral shell store, for a state whose application opens a
+   *  document or moves the session. */
+  readonly store: EditorShellStore;
+}
+
+export interface ComponentStatesSource {
+  /** The source's id, in its own vocabulary. */
+  readonly id: string;
+  /** Which module registered it. Re-registering the same owner+id REPLACES,
+   *  so an HMR re-evaluation leaves one source, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  /** This component's named states, or `[]` — "none of mine", which lets the
+   *  next source answer. */
+  readonly statesFor: (
+    component: ComponentStatesRef,
+    context: ComponentStatesContext,
+  ) => readonly StoryRef[];
+  /** Apply one of the states this source just named. Whether that opens a
+   *  document, swaps a world or writes source is the source's business. */
+  readonly apply: (
+    component: ComponentStatesRef,
+    stateId: string,
+    context: ComponentStatesContext,
+  ) => void;
+}
+
+const _sources: ComponentStatesSource[] = [];
+
+/** Install a source. Returns the teardown. */
+export function registerComponentStatesSource(source: ComponentStatesSource): () => void {
+  const stale = _sources.findIndex((item) => item.owner === source.owner && item.id === source.id);
+  if (stale >= 0) _sources.splice(stale, 1);
+  _sources.push(source);
+  _sources.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  return () => {
+    const at = _sources.indexOf(source);
+    if (at >= 0) _sources.splice(at, 1);
+  };
+}
+
+const EMPTY: readonly ComponentStatesSource[] = [];
+
+/** Everything registered, in order. */
+export function componentStatesSources(): readonly ComponentStatesSource[] {
+  return _sources.length === 0 ? EMPTY : _sources;
+}
+
+/**
+ * THE ADAPTER'S `stories` MEMBER, bound over the registry — a thin binding an
+ * adapter constructs instead of constructing an implementation.
+ *
+ * `componentForNode` is the adapter's own semantic knowledge of what a node
+ * IS; everything past it is a registered source's. The FIRST source that names
+ * a state for a component owns that component, the way
+ * `contentEntryForComponent` takes the first source that admits one.
+ */
+export function componentStatesProvider(
+  surface: AdapterSurface,
+  store: EditorShellStore,
+  componentForNode: (nodeId: string) => ComponentStatesRef | null,
+): StoriesProvider {
+  const activeByNode = new Map<string, string>();
+  const context: ComponentStatesContext = { surface, store };
+
+  /** The source that answers for this node, and what it answered. */
+  const resolve = (
+    nodeId: string,
+  ): { source: ComponentStatesSource; states: readonly StoryRef[] } | null => {
+    const component = componentForNode(nodeId);
+    if (!component) return null;
+    for (const source of _sources) {
+      const states = source.statesFor(component, context);
+      if (states.length > 0) return { source, states };
+    }
+    return null;
+  };
+
+  return {
+    storiesFor: (nodeId) => [...(resolve(nodeId)?.states ?? [])],
+    active: (nodeId) => activeByNode.get(nodeId) ?? null,
+    apply: (nodeId, stateId) => {
+      if (stateId === null) {
+        activeByNode.delete(nodeId);
+        store.notifyIngestEdit();
+        return;
+      }
+      const answer = resolve(nodeId);
+      if (!answer?.states.some((state) => state.id === stateId)) {
+        editorConsole.warn(
+          `[component-states] stories.apply: state "${stateId}" does not belong to node ` +
+            `"${nodeId}" on the ${surface} surface — ignoring.`,
+          'authoring',
+        );
+        return;
+      }
+      const component = componentForNode(nodeId);
+      if (!component) return;
+      activeByNode.set(nodeId, stateId);
+      answer.source.apply(component, stateId, context);
+      store.notifyIngestEdit();
+    },
+    // The distinction this member exists to draw: an empty list because this
+    // component has no states, and an empty list because nothing in this
+    // editor can read them, are different answers.
+    unavailable: () =>
+      _sources.length > 0
+        ? null
+        : 'No package in this editor registered a source of component states, so this ' +
+          "component's named states could not be read. A build ships the packages its own " +
+          'entry in `builds/` lists.',
+  };
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot, content-source,
+ *  design-time-mount and component-board registries'). */
+export function __resetComponentStatesSourcesForTest(): void {
+  _sources.length = 0;
+}

package/src/components/AgentPresentationNotice.tsx

@@ -0,0 +1,75 @@
+/**
+ * "Agent presented this view" — published as a NOTIFICATION
+ * (`editor-notifications.ts`), with Copy Link and Return inline. It used to be
+ * a banner floated over the document's top centre, across the tab row; the
+ * owner named that shape as wrong (2026-09-04) and the notification stack is
+ * where an event like this goes. This component keeps no DOM: it watches the
+ * presentation-notice store and mirrors it into a card.
+ */
+
+import { useEffect, useSyncExternalStore } from 'react';
+import { editorConsole } from '../editor-console';
+import { dismissNotification, notify } from '../editor-notifications';
+import {
+  clearEditorPresentationNotice,
+  editorPresentationNotice,
+  editorPresentationNoticeVersion,
+  subscribeEditorPresentationNotice,
+} from '../editor-presentation-notice';
+import { useEditorStore } from '../editor-runtime';
+import { presentEditorView } from '../editor-view-presentation';
+
+const NOTIFICATION_ID = 'agent-presented-view';
+
+export function AgentPresentationNotice() {
+  const store = useEditorStore();
+  useSyncExternalStore(
+    subscribeEditorPresentationNotice,
+    editorPresentationNoticeVersion,
+    editorPresentationNoticeVersion,
+  );
+  const notice = editorPresentationNotice();
+  useEffect(() => {
+    if (!notice) {
+      dismissNotification(NOTIFICATION_ID);
+      return;
+    }
+    notify({
+      id: NOTIFICATION_ID,
+      tone: 'info',
+      title: 'Agent presented this view.',
+      ...(notice.presented.warnings.length > 0
+        ? { detail: notice.presented.warnings.join(' ') }
+        : {}),
+      onDismiss: clearEditorPresentationNotice,
+      actions: [
+        {
+          label: 'Copy Link',
+          keeps: true,
+          run: () => {
+            void Promise.resolve()
+              .then(() => navigator.clipboard.writeText(notice.presented.url))
+              .catch(() => {
+                editorConsole.warn('Could not copy the view link to the clipboard.', 'editor');
+              });
+          },
+        },
+        {
+          label: 'Return',
+          primary: true,
+          run: () => {
+            void presentEditorView(store, notice.previousView, { origin: 'return' }).catch(
+              (error) => {
+                editorConsole.error(
+                  `Could not return to the previous editor view: ${error instanceof Error ? error.message : String(error)}`,
+                  'editor',
+                );
+              },
+            );
+          },
+        },
+      ],
+    });
+  }, [notice, store]);
+  return null;
+}