@volter/editor-ui 0.5.211 → 0.5.212

package/NOTICE

@@ -2,3 +2,15 @@ Copyright 2026 Volter AI, Inc.
 
 This package is developed in the public volter-ai/editor repository.
 LICENSE contains its AGPL-3.0-only license.
+
+The files under src/ were imported from volter-ai/volter-engine at commit
+09c2749ce, and retain the AGPL-3.0-only license in LICENSE.
+
+React authoring was transferred from packages/dom/src and
+packages/dom/contributions. Realm and React tool services retain their
+source licenses from that same revision.
+
+Modules moved under src/host/ from @volter/sdk's src/kit/ because only this package
+imports them (docs/adr/sdk-plugin-api.md, decisions 1 and 4) are Volter AI, Inc.'s
+own work and are AGPL-3.0-only here, as editor source. The @volter/sdk releases
+that carried them remain Apache-2.0.

package/contributions/component-board.service.ts

@@ -1,2 +1,10 @@
-/** Existing DOM authoring tool, composed without the game transport. */
-export { point, start } from '@volter/editor-game/contributions/react/component-board.service.ts';
+/** Register the React UI component board with the editor host. */
+
+import { registerComponentBoard } from '@volter/sdk/component-board-registry';
+import { uiComponentBoard } from '../src/react/ui-component-board.ts';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return registerComponentBoard(uiComponentBoard);
+}

package/contributions/design-time-mount.service.ts

@@ -1,2 +1,39 @@
-/** Existing DOM authoring tool, composed without the game transport. */
-export { point, start } from '@volter/editor-game/contributions/react/design-time-mount.service.ts';
+/** Register React DOM design-time mounting and story-change invalidation. Runtime modules load only when a DOM surface is present. */
+
+import { registerDesignTimeMount } from '@volter/sdk/authoring/design-time-mount-registry';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return registerDesignTimeMount({
+    kind: 'dom',
+    owner: '@volter/editor-ui/react/design-time-mount',
+    // The `ResolvedAdapter['identity']` a mount failure is reported under —
+    // the literal the host reports it under.
+    identity: 'default-react',
+    // Deliberately absent: a dom layer's design-time hover/press testing of
+    // real UI competes with authoring gestures, so it stays behind the `eye`
+    // row's `interactive` toggle. The canvas medium declares the opposite.
+    mount: async (candidate, layer, context) => {
+      const { mountReactDesignLayer } = await import('../src/react/design-time-react-mount.ts');
+      return mountReactDesignLayer(candidate, layer, context);
+    },
+    reprojectWhen: (invalidate) => {
+      let stopped = false;
+      let stop: (() => void) | null = null;
+      // The hook's own module is the mount's, so binding it eagerly would
+      // load the board's whole graph for a project that has no dom root. The
+      // host only calls this when a dom candidate exists, so loading here is
+      // exactly the right moment.
+      void import('../src/react/design-time-react-mount.ts').then((module) => {
+        if (stopped) return;
+        stop = module.reprojectWhenStoriesRepublish(invalidate);
+      });
+      return () => {
+        stopped = true;
+        stop?.();
+        stop = null;
+      };
+    },
+  });
+}

package/contributions/react-inspector.service.ts

@@ -1,2 +1,11 @@
-/** Existing DOM authoring tool, composed without the game transport. */
-export { point, start } from '@volter/editor-game/contributions/react/react-inspector.service.ts';
+/** Register React and DOM layout, appearance and story inspector sections. */
+
+import { ensureReactInspectorSectionRegistered } from '../src/react/react-inspector-section.tsx';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  ensureReactInspectorSectionRegistered();
+  // The HMR registration group owns the section for the module lifetime.
+  return () => {};
+}

package/contributions/story-documents.service.ts

@@ -1,2 +1,14 @@
-/** Existing DOM authoring tool, composed without the game transport. */
-export { point, start } from '@volter/editor-game/contributions/react/story-documents.service.ts';
+/** Register React story documents, argument inspection and story utilities. */
+
+import { ensureStoryContributionsRegistered } from '../src/react/story-documents/story-documents.tsx';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  // The module registers its opener and restorer at module scope; this call
+  // installs the story-scoped Inspector section and utilities. It is idempotent and returns nothing; the
+  // registration group it owns is HMR-safe by construction.
+  ensureStoryContributionsRegistered();
+  // Registrations are HMR-owned and open documents outlive the contribution pass.
+  return () => {};
+}

package/contributions/ui.page.ts

@@ -0,0 +1,28 @@
+/** editor-ui's page half. It registers the composition render (`story-render-movie`, which starts a React
+ * composition rendering frame by frame into a movie, and `story-render-status`, `../src/react/composition-movie.ts`). It
+ * activates on its commands (`package.json#contributes.volter.activationEvents`). */
+import type { PluginContext } from '@volter/sdk/plugins';
+import { registerVerbCommands } from '@volter/sdk/commands';
+import { compositionRenders, startCompositionRender } from '../src/react/composition-movie.ts';
+const frameNumber = (args: Record<string, unknown>, key: string): number | undefined => {
+  const value = args[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== 'number' || !Number.isInteger(value)) throw new Error(`${key} is a whole number.`);
+  return value;
+};
+export function activate(context: PluginContext): void {
+  registerVerbCommands(context, {
+    'story-render-movie': async (args) => {
+      const { story, out } = args;
+      if (typeof story !== 'string' || story === '') return { ok: false, error: 'story-render-movie needs `story`: a story id, or an export name only one story has.' };
+      if (out !== undefined && typeof out !== 'string') return { ok: false, error: '`out` is a project path.' };
+      const render = await startCompositionRender({ story, out, from: frameNumber(args, 'from'), to: frameNumber(args, 'to'), width: frameNumber(args, 'width') });
+      return { ok: true, data: { ...render } };
+    },
+    'story-render-status': async (args) => {
+      const { story } = args;
+      if (typeof story !== 'string') return { ok: false, error: 'story-render-status needs the `story` id story-render-movie answered.' };
+      return { ok: true, data: { ...(await compositionRenders.status(story)) } };
+    },
+  });
+}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@volter/editor-ui",
-  "version": "0.5.211",
+  "publisher": "volter",
+  "version": "0.5.212",
+  "engines": {
+    "vscode": "*"
+  },
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
   "type": "module",
-  "description": "React DOM UI boards and project layers on playing stages.",
+  "description": "React DOM UI authoring for Cyclotron: the React root and realm, component boards, story documents and the React inspector.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/volter-ai/editor.git",
@@ -20,24 +24,85 @@
     "./contributions/*": "./contributions/*",
     "./package.json": "./package.json"
   },
-  "volter": {
-    "contributions": [
-      "./contributions/component-board.service.ts",
-      "./contributions/design-time-mount.service.ts",
-      "./contributions/play-layers.service.ts",
-      "./contributions/react-inspector.service.ts",
-      "./contributions/story-documents.service.ts"
-    ]
+  "contributes": {
+    "volter": {
+      "activationEvents": [
+        "onCommand:volter.story-render-movie",
+        "onCommand:volter.story-render-status"
+      ],
+      "page": [
+        "./contributions/ui.page.ts"
+      ],
+      "editors": [
+        {
+          "kind": "workspace:ui-components"
+        },
+        {
+          "kind": "story",
+          "views": [
+            "story:isolated",
+            "story:docs"
+          ]
+        }
+      ],
+      "services": [
+        "./contributions/component-board.service.ts",
+        {
+          "module": "./contributions/design-time-mount.service.ts",
+          "designTimeMount": "dom"
+        },
+        "./contributions/react-inspector.service.ts",
+        "./contributions/story-documents.service.ts"
+      ]
+    },
+    "commands": [
+      {
+        "command": "volter.story-render-movie",
+        "title": "story-render-movie",
+        "category": "UI Board",
+        "volter": {
+          "derivedRefresh": "none"
+        }
+      },
+      {
+        "command": "volter.story-render-status",
+        "title": "story-render-status",
+        "category": "UI Board",
+        "volter": {
+          "derivedRefresh": "none"
+        }
+      }
+    ],
+    "menus": {
+      "commandPalette": [
+        {
+          "command": "volter.story-render-movie",
+          "when": "false"
+        },
+        {
+          "command": "volter.story-render-status",
+          "when": "false"
+        }
+      ]
+    }
   },
   "dependencies": {
-    "@volter/sdk": "0.5.211",
-    "@volter/editor-game": "0.5.211",
-    "@volter/project": "0.5.211"
+    "@volter/editor-movie": "0.5.212",
+    "@volter/sdk": "0.5.212",
+    "@volter/project": "0.5.212",
+    "@volter/editor-threejs": "0.5.212",
+    "@volter/editor-react": "0.5.212",
+    "@fortawesome/free-solid-svg-icons": "^7.2.0",
+    "axe-core": "^4.12.1",
+    "storybook": "10.6.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/host/authoring/struct-write-pipe.ts

@@ -0,0 +1,102 @@
+/** Shared structural source-write resolution. The backend owns whole-file
+ * history; this pipe reports source-structure or its unavailable destination.
+ * Callers provide OID resolution, destination text, and the changed callback. */
+
+import type { SourceWriteBackend } from '@volter/sdk/ui-source/source-write-backend';
+import { resolvesLiveOnly, runWritePipe, type WriteAck, type WriteResolution } from '@volter/sdk/write-pipe';
+
+/** The `writeStruct` options bag, spelled once (the backend's own shape). */
+export type StructOpOptions = Parameters<SourceWriteBackend['writeStruct']>[2];
+
+interface StructWritePipeConfig {
+  /** Report refusals and no-op writes with the adapter's prefix. */
+  report(message: string): void;
+  /** The live-only floor's reason when no struct door is bound. */
+  readonly noWriterReason: string;
+  /** Read the adapter backend when resolving a structural write. */
+  backend(): SourceWriteBackend | null | undefined;
+  /** Ran after a LANDED structural write, before the ack resolves — the
+   *  lane's own reconcile/notify choreography. */
+  onChanged(): void | Promise<void>;
+}
+
+interface StructWritePipe {
+  /** A refusal through the same resolution path as structural writes. */
+  structRefusal(reason: string): Promise<WriteAck>;
+  /** One `writeStruct` op against a resolved oid; `null` oid refuses by name. */
+  structOp(
+    oid: string | null | undefined,
+    subjectLabel: string,
+    op: string,
+    opts: StructOpOptions,
+    destination: string,
+  ): Promise<WriteAck>;
+  /** Delete OIDs resolved from one source snapshot. */
+  deleteMany(oids: readonly string[], destination: string): Promise<WriteAck>;
+}
+
+export function createStructWritePipe(config: StructWritePipeConfig): StructWritePipe {
+  const pipedStruct = (
+    write: () => Promise<boolean>,
+    op: string,
+    bound: boolean,
+    destination: string,
+  ): Promise<WriteAck> =>
+    runWritePipe({
+      resolve: (): WriteResolution =>
+        bound
+          ? { reaches: 'writer', destination, write }
+          : resolvesLiveOnly(config.noWriterReason),
+      record: () => undefined,
+      report: (reason) => config.report(`"${op}" stays live-only — ${reason}.`),
+    });
+
+  const structRefusal: StructWritePipe['structRefusal'] = (reason) =>
+    runWritePipe({
+      resolve: () => resolvesLiveOnly(reason),
+      record: () => undefined,
+      report: config.report,
+    });
+
+  return {
+    structRefusal,
+    structOp: (oid, subjectLabel, op, opts, destination) => {
+      if (!oid) {
+        return structRefusal(`"${op}" refused: "${subjectLabel}" has no source stamp.`);
+      }
+      return pipedStruct(
+        async () => {
+          const backend = config.backend()!;
+          const res = await backend.writeStruct(oid, op, opts);
+          if (!res.changed) {
+            config.report(
+              `struct "${op}" refused/no-op for oid "${oid}": ${res.error ?? 'no change'}`,
+            );
+            return false;
+          }
+          await config.onChanged();
+          return true;
+        },
+        op,
+        config.backend() != null,
+        destination,
+      );
+    },
+    deleteMany: (oids, destination) =>
+      pipedStruct(
+        async () => {
+          const backend = config.backend()!;
+          const res = await backend.writeStructMany(oids, 'delete');
+          if (!res.changed) {
+            config.report(`batch "delete" refused/no-op: ${res.error ?? 'no change'}`);
+            return false;
+          }
+          await config.onChanged();
+          return true;
+        },
+        'delete (batch)',
+        config.backend() != null,
+        destination,
+      ),
+  };
+}

package/src/host/components/ResolutionPicker.tsx

@@ -0,0 +1,83 @@
+import { faDesktop } from '@fortawesome/free-solid-svg-icons';
+import { AnchoredMenu, Button, EditorIcon, MenuItem, Text } from '@volter/sdk/widgets';
+import { useRef, useState } from 'react';
+
+export interface Resolution {
+  label: string;
+  width: number | null;
+  height: number | null;
+}
+
+const RESOLUTIONS: Resolution[] = [
+  { label: 'Fill', width: null, height: null },
+  { label: 'iPhone SE — 375×667', width: 375, height: 667 },
+  { label: 'iPhone 14 — 390×844', width: 390, height: 844 },
+  { label: 'iPhone 14 Pro Max — 430×932', width: 430, height: 932 },
+  { label: 'iPad Mini — 768×1024', width: 768, height: 1024 },
+  { label: 'iPad Pro 11″ — 834×1194', width: 834, height: 1194 },
+  { label: 'Laptop — 1366×768', width: 1366, height: 768 },
+  { label: 'Desktop — 1920×1080', width: 1920, height: 1080 },
+];
+
+/** Preview-resolution picker for isolated story documents. */
+export function ResolutionPicker({
+  resolution,
+  onResolutionChange,
+  scale,
+}: {
+  resolution: Resolution;
+  onResolutionChange: (resolution: Resolution) => void;
+  scale: number;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLButtonElement>(null);
+
+  const isFill = resolution.width === null;
+  const label = isFill ? 'Fill' : `${resolution.width}×${resolution.height}`;
+
+  return (
+    <div className="volter-playbar-popover-anchor">
+      <Button
+        ref={ref}
+        variant="ghost"
+        size="comfortable"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? 'volter-resolution-picker-menu' : undefined}
+        onClick={() => setOpen((value) => !value)}
+        title="Change preview resolution"
+      >
+        <EditorIcon icon={faDesktop} size="md" />
+        <Text variant="code">{label}</Text>
+        {!isFill && scale < 1 && (
+          <Text variant="caption" tone="dim">
+            {Math.round(scale * 100)}%
+          </Text>
+        )}
+      </Button>
+      {open && (
+        <AnchoredMenu
+          id="volter-resolution-picker-menu"
+          anchorRef={ref}
+          className="volter-resolution-menu"
+          gap={4}
+          onDismiss={() => setOpen(false)}
+        >
+          {RESOLUTIONS.map((candidate) => (
+            <MenuItem
+              key={candidate.label}
+              role="menuitemradio"
+              aria-checked={candidate.label === resolution.label}
+              onSelect={() => {
+                onResolutionChange(candidate);
+                setOpen(false);
+              }}
+            >
+              {candidate.label}
+            </MenuItem>
+          ))}
+        </AnchoredMenu>
+      )}
+    </div>
+  );
+}

package/src/host/crash-null-boundary.ts

@@ -0,0 +1,24 @@
+/** Report render and lifecycle failures, then unmount the failed subtree.
+ * Sibling mounts keep running. React's error-boundary API requires a class. */
+
+import { Component, type ReactNode } from 'react';
+
+export class CrashNullBoundary extends Component<
+  {
+    onCaught: (error: unknown) => void;
+    /** Optional because `createElement` callers pass children VARIADICALLY. */
+    children?: ReactNode;
+  },
+  { crashed: boolean }
+> {
+  override state = { crashed: false };
+  static getDerivedStateFromError(): { crashed: boolean } {
+    return { crashed: true };
+  }
+  override componentDidCatch(error: unknown): void {
+    this.props.onCaught(error);
+  }
+  override render(): ReactNode {
+    return this.state.crashed ? null : this.props.children;
+  }
+}

package/src/host/portable-stories.ts

@@ -0,0 +1,44 @@
+/**
+ * THE UI BOARD'S STORY MEMORY, and the rootless board's descriptor: editor-ui's own state, which its
+ * board mount writes and its board document reads.
+ */
+import type { DesignTimeRootDescriptor } from '@volter/sdk/authoring/design-time-mount-registry';
+
+/** Play tears the design-time adapter down, so the selected CSF state
+ * must live one level above that adapter to survive Stop's rebuild. Keyed by
+ * project + root so equal root ids in different projects never bleed. */
+const selectedPortableStoryByRoot = new Map<string, string>();
+
+function portableStorySelectionKey(projectRoot: string, rootId: string): string {
+  return `${projectRoot}\0${rootId}`;
+}
+
+/** The story a board ROOT last applied (undefined before any selection) —
+ *  the view-address door reads this so a presented workspace document can
+ *  say which frame it is on (`EditorViewDocument`'s workspace `story`). */
+export function rememberedPortableStory(projectRoot: string, rootId: string): string | undefined {
+  return selectedPortableStoryByRoot.get(portableStorySelectionKey(projectRoot, rootId));
+}
+
+/** The write half, for the registered mount that owns the board: it applies
+ *  the story, so it is what knows which frame the root is on. */
+export function rememberPortableStory(projectRoot: string, rootId: string, storyId: string): void {
+  selectedPortableStoryByRoot.set(portableStorySelectionKey(projectRoot, rootId), storyId);
+}
+
+/** Rootless UI-board mount ID. It keys session presentation and is a valid
+ * project-relative history display name, without a URI-scheme colon. */
+const PROJECT_STORY_BOARD_ROOT_ID = 'ui-components-board';
+
+/** The rootless UI board's descriptor — no `path`, because there is no root
+ *  entry to derive a default story from; the board opens on its first story
+ *  the same way it does for a root whose entry names no story. */
+export function projectStoryBoardDescriptor(): DesignTimeRootDescriptor {
+  return {
+    worldId: PROJECT_STORY_BOARD_ROOT_ID,
+    kind: 'dom',
+    path: undefined,
+    zOrder: 0,
+    pausable: true,
+  };
+}

package/src/host/projection/dom.ts

@@ -0,0 +1,40 @@
+/** Project mounted data-oid elements for hierarchy, selection and picking.
+ * Unstamped wrappers are transparent; SVG elements own their whole subtree. */
+
+import type { ProjectedNode } from '@volter/sdk/projection-types';
+
+interface OidWalkable {
+  readonly tagName: string;
+  readonly children: ArrayLike<OidWalkable>;
+  getAttribute(name: string): string | null;
+}
+
+/** The host root is excluded. The first occurrence keeps its source OID;
+ * subsequent occurrences receive #n suffixes in depth-first DOM order. */
+export function projectOidDom<TEl extends OidWalkable>(root: TEl): {
+  nodes: Map<string, ProjectedNode<TEl>>;
+  rootIds: string[];
+} {
+  const nodes = new Map<string, ProjectedNode<TEl>>();
+  const rootIds: string[] = [];
+  const occurrence = new Map<string, number>();
+
+  const visitChildren = (parent: TEl, ownerId: string | null): void => {
+    for (const el of Array.from(parent.children) as TEl[]) {
+      const oid = el.getAttribute('data-oid');
+      let id: string | null = null;
+      if (oid) {
+        const n = occurrence.get(oid) ?? 0;
+        occurrence.set(oid, n + 1);
+        id = n === 0 ? oid : `${oid}#${n}`;
+        nodes.set(id, { object: el, id, parentId: ownerId, childIds: [] });
+        if (ownerId === null) rootIds.push(id);
+        else nodes.get(ownerId)?.childIds.push(id);
+      }
+      if (el.tagName.toLowerCase() !== 'svg') visitChildren(el, id ?? ownerId);
+    }
+  };
+
+  visitChildren(root, null);
+  return { nodes, rootIds };
+}

package/src/host/react-mount-runtime.ts

@@ -0,0 +1,76 @@
+/** Resolve the React and React DOM instance used by the project: loaded from the project's own graph, so component hooks and createRoot share one dispatcher. */
+
+import type {
+  createElement,
+  useEffect as reactUseEffect,
+  useRef as reactUseRef,
+} from 'react';
+import type { flushSync } from 'react-dom';
+import type { createRoot } from 'react-dom/client';
+import { REACT_WORLD_RUNTIME_PATH } from '@volter/sdk/host';
+
+/**
+ * The pieces of "react itself" a react-world mount needs: `createElement`/`createRoot`
+ * to build and render `<Entry />`, and the hooks the editor's own wrappers use.
+ */
+export interface ReactRootMountRuntime {
+  createElement: typeof createElement;
+  createRoot: typeof createRoot;
+  useEffect: typeof reactUseEffect;
+  useRef: typeof reactUseRef;
+  /** `react-dom`'s synchronous-flush escape hatch — the design-time react
+   *  layer mount needs it from the SAME react-dom peer as `createRoot` above
+   *  (both are entry points of the same installed package). */
+  flushSync: typeof flushSync;
+}
+
+/** Load and validate the project-rooted Vite runtime doorway. Its React hooks,
+ * createRoot and flushSync must come from the project's own module graph. */
+async function loadPackagedReactRootMountRuntime(): Promise<ReactRootMountRuntime> {
+  const mod = (await import(/* @vite-ignore */ REACT_WORLD_RUNTIME_PATH)) as {
+    createElement?: unknown;
+    createRoot?: unknown;
+    useEffect?: unknown;
+    useRef?: unknown;
+    flushSync?: unknown;
+  };
+  if (
+    typeof mod.createElement !== 'function' ||
+    typeof mod.createRoot !== 'function' ||
+    typeof mod.useEffect !== 'function' ||
+    typeof mod.useRef !== 'function' ||
+    typeof mod.flushSync !== 'function'
+  ) {
+    throw new Error(
+      "The packaged runtime's synthetic react-world-runtime module " +
+        `("${REACT_WORLD_RUNTIME_PATH}") did not export createElement/createRoot/useEffect/useRef/flushSync ` +
+        'as functions — see vite-plugin-module-doorways.ts.',
+    );
+  }
+  return {
+    createElement: mod.createElement as typeof createElement,
+    createRoot: mod.createRoot as typeof createRoot,
+    useEffect: mod.useEffect as typeof reactUseEffect,
+    useRef: mod.useRef as typeof reactUseRef,
+    flushSync: mod.flushSync as typeof flushSync,
+  };
+}
+
+let cachedPackagedReactRootMountRuntime: Promise<ReactRootMountRuntime> | null = null;
+
+/**
+ * Resolve the react-world mount's own react. A react world is an ISOLATED
+ * `createRoot` (its own DOM subtree / react tree) that does NOT need to share
+ * react with the editor's own UI — it only needs to be internally consistent
+ * (the editor's wrapper and the project's entry component sharing ONE react
+ * instance), which loading it from the project's own graph gives.
+ *
+ * Memoized: this performs at most one dynamic import per editor session however
+ * many react roots mount.
+ */
+export async function resolveReactRootMountRuntime(): Promise<ReactRootMountRuntime> {
+  if (!cachedPackagedReactRootMountRuntime) {
+    cachedPackagedReactRootMountRuntime = loadPackagedReactRootMountRuntime();
+  }
+  return cachedPackagedReactRootMountRuntime;
+}