@volter/editor-ui 0.5.211 → 0.5.212

package/src/host/realm-services.ts

@@ -0,0 +1,53 @@
+/** Project module loading and React mounting, bound to one project and mount epoch. */
+
+import {
+  type ProjectMountEpoch,
+  projectEntryImportUrl,
+} from '@volter/sdk/project-module-url';
+import { type ReactRootMountRuntime, resolveReactRootMountRuntime } from './react-mount-runtime';
+
+/**
+ * The realm's services, bound to ONE project root and ONE mount epoch — a
+ * realm value is "how THIS project's modules are reached in THIS mount
+ * generation", which is why it is constructed per resolve rather than being a
+ * module-level singleton.
+ */
+export interface RealmServices {
+  /**
+   * Import one root's entry module.
+   *
+   * The entry path is resolved within this realm's project and mount epoch.
+   */
+  loadEntryModule(
+    entry: string,
+  ): Promise<Record<string, unknown>>;
+  /** The react-world mount's own react/react-dom. */
+  readonly reactDomRuntime: () => Promise<ReactRootMountRuntime>;
+}
+
+const SHARED_RUNTIMES = {
+  reactDomRuntime: resolveReactRootMountRuntime,
+} as const;
+
+/** Import project entries through /@fs/ with this mount epoch's cache key. */
+function fsLoader(projectRoot: string, epoch: ProjectMountEpoch) {
+  return async (
+    entry: string,
+  ): Promise<Record<string, unknown>> =>
+    (await import(
+      /* @vite-ignore */ projectEntryImportUrl(projectRoot, entry, epoch)
+    )) as Record<string, unknown>;
+}
+
+/**
+ * Construct this session's realm for one project and one mount epoch.
+ */
+export async function activeRealmServices(
+  projectRoot: string,
+  epoch: ProjectMountEpoch,
+): Promise<RealmServices> {
+  return {
+    loadEntryModule: fsLoader(projectRoot, epoch),
+    ...SHARED_RUNTIMES,
+  };
+}

package/src/host/roots/react-root.ts

@@ -0,0 +1,82 @@
+/** Mount a project's React DOM root with the project's own React instance. */
+
+import type { MountedReactRoot, RootAdapter } from '@volter/project/adapter';
+import type { DomHostContext } from '@volter/project/adapter/host-context';
+import type { ResolvedAdapterRoot } from '@volter/project/manifest/load';
+import type { ComponentType } from 'react';
+import type { RealmServices } from '../realm-services';
+
+import { markMountCssScope } from '@volter/sdk/mount-css-scope';
+
+type ReactEntryDeclaration = Pick<ResolvedAdapterRoot, 'id'> & { entry: string };
+
+/**
+ * The shape a react world's `entry` module must satisfy: default-export a
+ * React component. Validated loudly at import time — a project whose entry
+ * exports the wrong shape gets a named error naming the world and the export
+ * it actually found, not a cryptic "X is not a function" deep inside
+ * `createRoot`/`render`.
+ */
+function loadReactEntryComponent(
+  world: ReactEntryDeclaration,
+  mod: { default?: unknown },
+): ComponentType {
+  if (typeof mod.default !== 'function') {
+    throw new Error(
+      `resolveReactAdapterRootComponent: world "${world.id}" (dom) entry module does not ` +
+        `default-export a component — got ${typeof mod.default}. A react world's \`entry\` must ` +
+        'default-export a React component.',
+    );
+  }
+  return mod.default as ComponentType;
+}
+
+/** Load and validate the React component shared by the UI board and Play. */
+export async function resolveReactAdapterRootComponent(
+  world: ReactEntryDeclaration,
+  realm: RealmServices,
+): Promise<ComponentType> {
+  const mod = await realm.loadEntryModule(world.entry);
+  return loadReactEntryComponent(world, mod);
+}
+
+/** Mount into the host-owned DOM layer. */
+function reactMount(
+  world: ResolvedAdapterRoot,
+  Entry: ComponentType,
+  realm: RealmServices,
+): RootAdapter<'dom'> {
+  return {
+    id: world.id,
+    async mount(host: DomHostContext): Promise<MountedReactRoot> {
+      // The host owns this DOM surface, so its served project CSS must have
+      // a scope root even when the entry component has no special wrapper.
+      markMountCssScope(host.container);
+      // Entry hooks and mounting share the project's React runtime.
+      const runtime = await realm.reactDomRuntime();
+      const root = runtime.createRoot(host.container);
+      const render = () => {
+        root.render(runtime.createElement(Entry));
+      };
+      // The authoring adapter reads the committed OID tree as soon as mount resolves.
+      runtime.flushSync(render);
+      return {
+        kind: 'dom',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose(): void {
+          root.unmount();
+        },
+      };
+    },
+  };
+}
+
+/** A first-party `dom` root. */
+export async function resolveDomAdapter(
+  world: ResolvedAdapterRoot & { entry: string },
+  realm: RealmServices,
+): Promise<RootAdapter<'dom'>> {
+  const Entry = await resolveReactAdapterRootComponent(world, realm);
+  return reactMount(world, Entry, realm);
+}

package/src/host/stories/story-arg-descriptors.ts

@@ -0,0 +1,50 @@
+/**
+ * ONE rule for "which portable-story args are editable, and as what" —
+ * extracted verbatim from `authoring/react-world-authoring-adapter.ts`'s
+ * private `portableStoryArgDescriptors` (the Storybook-Controls semantic it has
+ * always applied to a story node in the React hierarchy), so the three-story
+ * board's per-story document describes its args the SAME way instead of
+ * inventing a second answer.
+ *
+ * Storybook's own Controls semantic: a story's arg is editable when it carries
+ * a primitive value the author can meaningfully type; anything else (a
+ * callback, a symbol, an unset arg) stays out of the visual form while
+ * remaining present in the complete args object the composed story is rendered
+ * with. Non-primitive OBJECT/array values are surfaced as `json`, which is what
+ * the generic inspector's JSON widget is for.
+ */
+
+import type { PropertyDescriptor } from '@volter/project/adapter';
+
+/**
+ * Descriptors for one composed story's args, under `pathPrefix`.
+ *
+ * `pathPrefix` is the caller's, because the path namespace belongs to whoever
+ * owns the inspector node the descriptors are read back through — the React
+ * world adapter keys its story nodes under `story.arg.`, and the three-story
+ * document uses its own.
+ */
+export function storyArgPropertyDescriptors(
+  args: Record<string, unknown>,
+  pathPrefix: string,
+): PropertyDescriptor[] {
+  return Object.entries(args).flatMap(([name, value]) => {
+    if (typeof value === 'function' || typeof value === 'symbol' || value === undefined) return [];
+    const type: PropertyDescriptor['type'] =
+      typeof value === 'boolean'
+        ? 'boolean'
+        : typeof value === 'number'
+          ? 'number'
+          : typeof value === 'string'
+            ? 'string'
+            : 'json';
+    return [
+      {
+        path: `${pathPrefix}${name}`,
+        label: name,
+        type,
+        group: 'Args',
+      },
+    ];
+  });
+}

package/src/host/stories/story-media-presence.ts

@@ -0,0 +1,89 @@
+/** Board presence follows declared story media, independent of runtime roots.
+ * An empty registry clears every medium. */
+
+import { editorHost } from '@volter/sdk/host';
+import { declaredStoryMedium, type StoryMedium } from '@volter/sdk/stories/story-declared-medium';
+
+/** Which component boards the project's stories call for. */
+export interface StoryMediaPresence {
+  /** ≥1 story declared as `stage` — the 3D board's existence. */
+  readonly stage: boolean;
+  /** ≥1 story declared as `canvas` — the 2D board's existence. */
+  readonly canvas: boolean;
+  /** ≥1 story declared as `dom` — the UI board's existence. */
+  readonly dom: boolean;
+}
+
+const NONE: StoryMediaPresence = { stage: false, canvas: false, dom: false };
+
+let _presence: StoryMediaPresence = NONE;
+const _listeners = new Set<() => void>();
+let _subscribed = false;
+
+/** The current verdict (stable reference between changes). */
+export function getStoryMediaPresence(): StoryMediaPresence {
+  ensureSubscribed();
+  return _presence;
+}
+
+/** Subscribe to verdict changes. Returns an unsubscribe function. */
+export function subscribeStoryMediaPresence(listener: () => void): () => void {
+  ensureSubscribed();
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+function ensureSubscribed(): void {
+  if (_subscribed) return;
+  _subscribed = true;
+  editorHost().stories.subscribe(() => {
+    recomputeStoryMediaPresence();
+  });
+  recomputeStoryMediaPresence();
+}
+
+function publish(next: StoryMediaPresence): void {
+  if (
+    next.stage === _presence.stage &&
+    next.canvas === _presence.canvas &&
+    next.dom === _presence.dom
+  )
+    return;
+  _presence = next;
+  for (const listener of _listeners) listener();
+}
+
+function classifyDeclared(story: { readonly modulePath: string }): StoryMedium | undefined {
+  const declared = declaredStoryMedium({
+    modulePath: story.modulePath,
+    regions: editorHost().stories.regions(),
+  });
+  if (declared.medium) return declared.medium;
+  editorHost().stories.reportUndeclaredMedium(story.modulePath, declared.reason);
+  return undefined;
+}
+
+/** Publish media declared by the current registry. */
+function recomputeStoryMediaPresence(): void {
+  const stories = editorHost().stories.modules().flatMap((module_) =>
+    module_.ok
+      ? module_.stories.map((story) => ({ ...story, modulePath: module_.modulePath }))
+      : [],
+  );
+
+  // An empty registry removes every component board.
+  if (stories.length === 0) {
+    publish(NONE);
+    return;
+  }
+
+  const found: Record<StoryMedium, boolean> = { stage: false, canvas: false, dom: false };
+  for (const story of stories) {
+    const medium = classifyDeclared(story);
+    if (medium) found[medium] = true;
+  }
+  const { stage, canvas, dom } = found;
+  publish({ stage, canvas, dom });
+}

package/src/host/stories/story-presentation.ts

@@ -0,0 +1,203 @@
+/**
+ * PORTABLE CSF'S ANSWER to the board substrate's presentation contract
+ * (`@volter/sdk/authoring/story-board-presentation`): Storybook's slash
+ * title/path model organizes the frames, and Storybook's viewport parameters
+ * size them.
+ *
+ * The TYPES are the host's — `react-story-board.ts` is host chrome's
+ * substrate and declares what it needs, the same way `design-time-mount-registry.ts`
+ * declares `LayerMountResult` for the mounts that fill it. This module
+ * IMPLEMENTS them and re-exports them so a reader following a story does not
+ * have to know which side owns which half.
+ */
+
+import { MINIMAL_VIEWPORTS } from 'storybook/viewport';
+import type {
+  ResolvedStoryPresentation,
+  StoryBoardPresentation,
+  StoryLayout,
+  StoryPresentationIndex,
+  StoryPresentationInput,
+  StoryPresentationTreeNode,
+} from '@volter/sdk/authoring/story-board-presentation';
+import { deriveStoryGroupPath, formatStoryGroupPath } from '@volter/sdk/stories/story-grouping';
+
+export type {
+  StoryBoardPresentation,
+  StoryPresentationIndex,
+  StoryPresentationInput,
+} from '@volter/sdk/authoring/story-board-presentation';
+
+/** The name and size read from a story's `parameters.viewport.options`.
+ *  Internal: the board sees the resolved `StoryViewportChoice`, never this. */
+interface StoryViewportOption {
+  readonly name: string;
+  readonly styles: { readonly width: string; readonly height: string };
+}
+
+function stableNodeId(role: 'folder' | 'component', path: readonly string[]): string {
+  return `portable-${role}:${path.map((part) => encodeURIComponent(part)).join('/')}`;
+}
+
+/**
+ * Build the one Storybook navigation index used by both the hierarchy and
+ * the Figma-style board. Storybook's slash title/path model remains the
+ * organization source: first segment is the category, middle segments are
+ * folders, the final segment is the component, and named exports are stories.
+ */
+export function createStoryPresentationIndex(
+  stories: readonly StoryPresentationInput[],
+): StoryPresentationIndex {
+  const mutableNodes = new Map<string, StoryPresentationTreeNode & { childIds: string[] }>();
+  const rootIds: string[] = [];
+  const storyParentIds = new Map<string, string>();
+  const sections = new Map<string, { id: string; label: string; storyIds: string[] }>();
+
+  for (const story of stories) {
+    const group = deriveStoryGroupPath({
+      modulePath: story.modulePath,
+      ...(story.title ? { title: story.title } : {}),
+    });
+    const fullPath = [...group.segments, group.leaf];
+    let parentId: string | null = null;
+    for (let index = 0; index < fullPath.length; index++) {
+      const path = fullPath.slice(0, index + 1);
+      const component = index === fullPath.length - 1;
+      const id = stableNodeId(component ? 'component' : 'folder', path);
+      if (!mutableNodes.has(id)) {
+        mutableNodes.set(id, {
+          id,
+          label: path.at(-1)!,
+          role: component ? 'component' : 'folder',
+          kind: component ? 'component' : 'group',
+          typeLabel: component ? 'Component' : index === 0 ? 'Category' : 'Folder',
+          parentId,
+          childIds: [],
+          ...(component ? { secondaryLabel: story.modulePath } : {}),
+        });
+        if (parentId) mutableNodes.get(parentId)?.childIds.push(id);
+        else rootIds.push(id);
+      }
+      parentId = id;
+    }
+
+    const componentId = parentId!;
+    mutableNodes.get(componentId)?.childIds.push(story.id);
+    storyParentIds.set(story.id, componentId);
+    const section = sections.get(componentId);
+    if (section) section.storyIds.push(story.id);
+    else {
+      sections.set(componentId, {
+        id: componentId,
+        label: formatStoryGroupPath(group),
+        storyIds: [story.id],
+      });
+    }
+  }
+
+  return {
+    sections: [...sections.values()],
+    nodes: [...mutableNodes.values()],
+    rootIds,
+    storyParentIds,
+  };
+}
+
+function object(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : null;
+}
+
+function pixels(value: unknown): number | null {
+  if (typeof value !== 'string') return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function viewportOptions(
+  parameters: Readonly<Record<string, unknown>>,
+): Record<string, StoryViewportOption> {
+  const custom = object(object(parameters['viewport'])?.['options']);
+  const options: Record<string, StoryViewportOption> = { ...MINIMAL_VIEWPORTS };
+  if (!custom) return options;
+  for (const [id, raw] of Object.entries(custom)) {
+    const option = object(raw);
+    const styles = object(option?.['styles']);
+    if (
+      !option ||
+      !styles ||
+      typeof option['name'] !== 'string' ||
+      typeof styles['width'] !== 'string' ||
+      typeof styles['height'] !== 'string'
+    ) {
+      continue;
+    }
+    options[id] = {
+      name: option['name'],
+      styles: { width: styles['width'], height: styles['height'] },
+    };
+  }
+  return options;
+}
+
+function viewportGlobal(globals: Readonly<Record<string, unknown>>): {
+  value: string | null;
+  isRotated: boolean;
+} {
+  const viewport = globals['viewport'];
+  if (typeof viewport === 'string') return { value: viewport || null, isRotated: false };
+  const value = object(viewport);
+  return {
+    value: typeof value?.['value'] === 'string' && value['value'] ? value['value'] : null,
+    isRotated: value?.['isRotated'] === true,
+  };
+}
+
+/** Resolve only Storybook-native layout/viewport values into an artboard. */
+function resolveStoryPresentation(
+  story: StoryPresentationInput,
+  fallback: { readonly width: number; readonly height: number },
+  sessionViewportId?: string | null,
+  sessionRotated?: boolean,
+): ResolvedStoryPresentation {
+  const parameters = story.parameters ?? {};
+  const globals = story.globals ?? {};
+  const authoredLayout = parameters['layout'];
+  const layout: StoryLayout =
+    authoredLayout === 'centered' || authoredLayout === 'fullscreen' || authoredLayout === 'padded'
+      ? authoredLayout
+      : 'padded';
+  const options = viewportOptions(parameters);
+  const choices = Object.entries(options).flatMap(([id, option]) => {
+    const width = pixels(option.styles.width);
+    const height = pixels(option.styles.height);
+    return width && height ? [{ id, label: option.name, width, height }] : [];
+  });
+  const authoredViewport = viewportGlobal(globals);
+  const selectedViewportId =
+    sessionViewportId === undefined ? authoredViewport.value : sessionViewportId;
+  const choice = choices.find((candidate) => candidate.id === selectedViewportId);
+  const baseWidth = choice?.width ?? fallback.width;
+  const baseHeight = choice?.height ?? fallback.height;
+  const rotated = sessionRotated ?? authoredViewport.isRotated;
+  return {
+    layout,
+    choices,
+    selectedViewportId: choice?.id ?? null,
+    locked: story.viewportLocked === true,
+    rotated,
+    width: rotated ? baseHeight : baseWidth,
+    height: rotated ? baseWidth : baseHeight,
+  };
+}
+
+/**
+ * The board substrate's {@link StoryBoardPresentation} for one set of stories
+ * — what a caller hands `createReactStoryBoard` instead of letting it reach
+ * for this module. `index` is built once; `resolve` runs inside the board's
+ * layout pass, per story and per viewport override.
+ */
+export function storyBoardPresentation(
+  index: StoryPresentationIndex,
+): StoryBoardPresentation {
+  return { index, resolve: resolveStoryPresentation };
+}

package/src/host/surface-content.ts

@@ -0,0 +1,44 @@
+const RENDERABLE_DOM_TAGS = new Set([
+  'canvas',
+  'svg',
+  'img',
+  'picture',
+  'video',
+  'input',
+  'button',
+]);
+const NON_RENDERING_DOM_TAGS = new Set(['script', 'style', 'template']);
+
+function elementIsHidden(element: Element): boolean {
+  if (element.hasAttribute('hidden')) return true;
+  if (typeof getComputedStyle !== 'function') return false;
+  const style = getComputedStyle(element);
+  return style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0';
+}
+
+function styledBoxRenders(element: Element): boolean {
+  if (typeof getComputedStyle !== 'function') return false;
+  const style = getComputedStyle(element);
+  const rect = element.getBoundingClientRect();
+  if (!(rect.width > 0 && rect.height > 0)) return false;
+  const hasBackground =
+    style.backgroundImage !== 'none' ||
+    (style.backgroundColor !== 'transparent' && style.backgroundColor !== 'rgba(0, 0, 0, 0)');
+  return hasBackground || style.borderTopStyle !== 'none' || style.outlineStyle !== 'none';
+}
+
+function domNodeRenders(node: Node): boolean {
+  if (node.nodeType === Node.TEXT_NODE) return Boolean(node.textContent?.trim());
+  if (!(node instanceof Element)) return false;
+  const tag = node.tagName.toLowerCase();
+  if (NON_RENDERING_DOM_TAGS.has(tag) || elementIsHidden(node)) return false;
+  if (RENDERABLE_DOM_TAGS.has(tag)) return true;
+  for (const child of node.childNodes) if (domNodeRenders(child)) return true;
+  return styledBoxRenders(node);
+}
+
+/** Structural DOM content test used after React has committed into a root. */
+export function domHasRenderableContent(root: HTMLElement): boolean {
+  for (const child of root.childNodes) if (domNodeRenders(child)) return true;
+  return false;
+}