@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/authoring/selection-scope.ts

@@ -0,0 +1,195 @@
+import type { AuthoringAdapter, EditorNode } from '@volter/project/adapter';
+import { setAuthoringSelection } from './consumer-actions';
+
+/** Session-only contents scope shared by hierarchy, viewport picking, and
+ * hotkeys. The adapter remains the source of hierarchy/ownership truth; this
+ * module only records which semantic boundary the user has opened. */
+interface SelectionScopeState {
+  adapter: AuthoringAdapter;
+  stack: string[];
+}
+
+let state: SelectionScopeState | null = null;
+const listeners = new Set<() => void>();
+let version = 0;
+
+function emit(): void {
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+function isScopeNode(node: EditorNode | null): boolean {
+  return (
+    !!node && (node.role === 'component' || node.role === 'instance' || node.role === 'boundary')
+  );
+}
+
+function isDescendant(adapter: AuthoringAdapter, id: string, ancestorId: string): boolean {
+  let current: string | null = id;
+  let guard = 0;
+  while (current && guard++ < 1000) {
+    if (current === ancestorId) return true;
+    current = adapter.hierarchy.node(current)?.parentId ?? null;
+  }
+  return false;
+}
+
+export function subscribeSelectionScope(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function selectionScopeVersion(): number {
+  return version;
+}
+
+/** Current boundary id for pick resolution. Deliberately adapter-agnostic:
+ * layered picking resolves through a composite's child adapter while the
+ * hierarchy owns the composite adapter that opened the scope. */
+export function currentSelectionScopeId(): string | null {
+  return state?.stack.at(-1) ?? null;
+}
+
+export function selectionScopeStack(adapter: AuthoringAdapter): string[] {
+  if (state?.adapter !== adapter) return [];
+  const valid = state.stack.filter((id) => adapter.hierarchy.node(id) !== null);
+  if (valid.length !== state.stack.length) {
+    state = valid.length > 0 ? { adapter, stack: valid } : null;
+  }
+  return valid;
+}
+
+export function enterSelectionScope(adapter: AuthoringAdapter, id: string): boolean {
+  const node = adapter.hierarchy.node(id);
+  if (!isScopeNode(node) || node!.childIds.length === 0) return false;
+
+  const current = state?.adapter === adapter ? state.stack : [];
+  const parentScope = current.at(-1);
+  if (parentScope && !isDescendant(adapter, id, parentScope)) return false;
+  if (parentScope === id) return false;
+  state = { adapter, stack: [...current, id] };
+  setAuthoringSelection(adapter, [id]);
+  emit();
+  return true;
+}
+
+/** Navigate to an existing breadcrumb boundary, or null for the full Game. */
+export function setSelectionScope(adapter: AuthoringAdapter, id: string | null): void {
+  if (id === null) {
+    if (state === null) return;
+    state = null;
+    emit();
+    return;
+  }
+  const current = selectionScopeStack(adapter);
+  const index = current.indexOf(id);
+  if (index < 0) return;
+  state = { adapter, stack: current.slice(0, index + 1) };
+  setAuthoringSelection(adapter, [id]);
+  emit();
+}
+
+export function exitSelectionScope(adapter: AuthoringAdapter): boolean {
+  if (state && state.adapter !== adapter) {
+    state = null;
+    emit();
+    return true;
+  }
+  const current = selectionScopeStack(adapter);
+  if (current.length === 0) return false;
+  const next = current.slice(0, -1);
+  state = next.length > 0 ? { adapter, stack: next } : null;
+  const selectionId = next.at(-1) ?? current[0]!;
+  setAuthoringSelection(adapter, [selectionId]);
+  emit();
+  return true;
+}
+
+export function enterSelectedScope(adapter: AuthoringAdapter): boolean {
+  const selected = adapter.selection?.get() ?? [];
+  return selected.length === 1 ? enterSelectionScope(adapter, selected[0]!) : false;
+}
+
+/**
+ * Drill in ONE level (the viewport's double-click, Figma's own gesture): open
+ * `boundaryId`'s scope, then select whatever the SAME pointer resolves to now
+ * that the scope is open.
+ *
+ * `repick` is the caller's own pick — `layered-pick.ts` already passes
+ * `currentSelectionScopeId()` into `SelectionProvider.resolve`, and the
+ * adapter's resolve already answers with the next member down its own owner
+ * chain. So there is no second chain-walking rule here, and this module still
+ * knows nothing about how a surface picks. Repeat the gesture to keep
+ * descending; {@link exitSelectionScope} (Escape) walks back out.
+ */
+export function drillIntoSelectionScope(
+  adapter: AuthoringAdapter,
+  boundaryId: string,
+  repick: () => string | null,
+): boolean {
+  if (!enterSelectionScope(adapter, boundaryId)) return false;
+  // `enterSelectionScope` already selected the boundary; a deeper member under
+  // the same pointer is what the gesture actually asked for. When the chain
+  // ends here the boundary stays selected — entering was still correct.
+  const deeper = repick();
+  if (deeper && deeper !== boundaryId) setAuthoringSelection(adapter, [deeper]);
+  return true;
+}
+
+/**
+ * Figma's outside-click rule: a click that lands outside an open scope leaves
+ * it. Pops every entry whose boundary does not CONTAIN `id`, so the stack
+ * follows the click to the level that does; a `null` id (empty space) closes
+ * every scope.
+ *
+ * Selection stays the caller's to set — the pick that produced `id` was
+ * already resolved against the scope that was open (a chain without the scope
+ * in it resolves to its own outermost owner), so this only makes the stack
+ * agree with where the click landed.
+ */
+export function popSelectionScopesToContain(adapter: AuthoringAdapter, id: string | null): boolean {
+  const current = selectionScopeStack(adapter);
+  if (current.length === 0) return false;
+  let depth = 0;
+  while (id !== null && depth < current.length && isDescendant(adapter, id, current[depth]!)) {
+    depth += 1;
+  }
+  if (depth === current.length) return false;
+  state = depth > 0 ? { adapter, stack: current.slice(0, depth) } : null;
+  emit();
+  return true;
+}
+
+/**
+ * ONE click's answer, across the scope exit the click itself causes — the
+ * whole of the viewport's single-click resolution.
+ *
+ * A pick resolves against whatever scope is OPEN (`layered-pick.ts` hands
+ * `currentSelectionScopeId()` to the adapter's own resolve), so a click that
+ * leaves the innermost scope was resolved by a scope that is about to be
+ * wrong. With a one-deep stack that is invisible — popping lands at "no
+ * scope", which is what the stale answer already assumed. With a stack THREE
+ * deep it is visible: the stale resolve answers with the chain's outermost
+ * owner, one level shallower than the same click gives once the stack has
+ * followed it, so the user has to click twice to land where one click should
+ * have (reviewer, #1235).
+ *
+ * So: resolve, let {@link popSelectionScopesToContain} follow the hit, and
+ * re-resolve ONCE — only when the stack actually moved, because a click that
+ * stays inside the open scope has nothing to re-resolve against. The second
+ * answer needs no second pop: it is a member of the scope the first pop
+ * settled on.
+ */
+export function pickAcrossScopeExit(
+  adapter: AuthoringAdapter,
+  repick: () => string | null,
+): string | null {
+  const hit = repick();
+  return popSelectionScopesToContain(adapter, hit) ? repick() : hit;
+}
+
+/** Test-only reset; production scope is intentionally session-local. */
+export function _resetSelectionScopeForTest(): void {
+  state = null;
+  emit();
+}

package/src/kit/authoring/shell-document-ops.ts

@@ -0,0 +1,169 @@
+/**
+ * Format-neutral shell document operations.
+ *
+ * Save destination, save state, hierarchy rows and select-all are questions
+ * about a DOCUMENT, and the shell owns none. Answering them from store fields
+ * would bind the shell chrome — status bar, application menus, command relay,
+ * hotkeys — to one format; these helpers ask the ACTIVE
+ * {@link AuthoringAdapter} instead, so the same chrome works for a TSX/R3F
+ * world, a React root, and an ingested game alike.
+ */
+
+import type { AuthoringAdapter, NodeCreationSite, WriteAnchorKind } from '@volter/project/adapter';
+import type { ShellDocumentState } from '@volter/sdk/kit/shell-document-state';
+import { forEachHierarchyNode } from '@volter/sdk/kit/hierarchy-walk';
+import { getActiveAuthoring } from './active-adapter';
+import { saveAuthoringDocument, setAuthoringSelection } from '@volter/sdk/kit/authoring/consumer-actions';
+import { resolvePanelAuthoring } from './panel-authoring';
+
+/** The authoring adapter owned by the active center document. This is the same
+ * resolution used by Hierarchy and Inspector; shell commands must not keep
+ * driving the scene adapter after an asset/source document becomes active. */
+export function activeDocumentAuthoring(store: ShellDocumentState): AuthoringAdapter {
+  return resolvePanelAuthoring(store).adapter;
+}
+
+/** One flattened hierarchy row — the wire shape `editor.hierarchy.inspect` reports. */
+export interface ShellHierarchyRow {
+  id: string;
+  name: string;
+  childIds: string[];
+}
+
+/**
+ * The active adapter's hierarchy, flattened breadth-first to id/name/childIds
+ * rows. `[]` when the adapter owns no tree (the no-authoring floor).
+ */
+export function activeHierarchyRows(store: ShellDocumentState): ShellHierarchyRow[] {
+  const rows: ShellHierarchyRow[] = [];
+  forEachHierarchyNode(activeDocumentAuthoring(store).hierarchy, (node) => {
+    rows.push({ id: node.id, name: node.label, childIds: [...node.childIds] });
+  });
+  return rows;
+}
+
+/**
+ * The source path represented by an adapter's document node.
+ *
+ * Source-authored adapters persist edits immediately and intentionally expose
+ * no PersistenceProvider. Their hierarchy still owns an honest document node
+ * whose secondary label is the project-relative source path (`src/world.tsx`,
+ * for example). Prefer that source identity for document chrome instead of
+ * leaking a composite persistence fallback such as "(no persistable child)".
+ */
+export function authoringDocumentSourcePath(adapter: AuthoringAdapter): string | null {
+  let found: string | null = null;
+  forEachHierarchyNode(adapter.hierarchy, (node) => {
+    const sourcePath = node.secondaryLabel?.trim();
+    if (node.role !== 'document' || !sourcePath) return;
+    found = sourcePath;
+    return false; // the first document row answers; never walk the whole tree for it
+  });
+  return found;
+}
+
+/** The active source-authored document path, when its adapter exposes one. */
+export function activeDocumentSourcePath(store: ShellDocumentState): string | null {
+  return authoringDocumentSourcePath(getActiveAuthoring(store));
+}
+
+/** The exact source filename represented by a project-relative path. */
+export function sourceFileName(sourcePath: string | null | undefined): string | null {
+  const trimmed = sourcePath?.trim();
+  if (!trimmed) return null;
+  return trimmed.split(/[\\/]/).filter(Boolean).at(-1) ?? null;
+}
+
+/**
+ * Where a save would land, straight from the active adapter's
+ * `PersistenceProvider`, or `null` when this adapter persists nothing.
+ */
+export function activeSaveDestination(store: ShellDocumentState): string | null {
+  const adapter = getActiveAuthoring(store);
+  return adapter.capabilities.persist ? (adapter.persistence?.destination ?? null) : null;
+}
+
+/**
+ * Whether the active adapter has unsaved edits.
+ *
+ * A source-backed adapter may be clean because it rolled a failed write back.
+ * Its provider still reports that failure until a later successful write
+ * clears the project-history error; clean and successful are not synonyms.
+ */
+export function activeSaveState(store: ShellDocumentState): 'saved' | 'unsaved' | 'failed' {
+  const persistence = getActiveAuthoring(store).persistence;
+  if (persistence?.lastError?.()) return 'failed';
+  return persistence?.isDirty() ? 'unsaved' : 'saved';
+}
+
+/** The active adapter's human-readable persistence failure, when any. */
+export function activeSaveFailure(store: ShellDocumentState): string | null {
+  return getActiveAuthoring(store).persistence?.lastError?.() ?? null;
+}
+
+/**
+ * The creation-site anchor for the CURRENT selection, as the control
+ * API reports it (the editor's `status` command / the editor's `eval` command's `editor.status()`).
+ *
+ * `null` has one meaning and one only: there is nothing to ask about — no
+ * selection, or an active adapter that indexes no creation sites. Whenever the
+ * adapter DOES index them the answer is a record, anchored or reasoned; a
+ * silent blank for "we couldn't find it" is exactly what the honest-floor rule
+ * forbids.
+ */
+export function activeSelectionCreationSite(store: ShellDocumentState): NodeCreationSite | null {
+  const adapter = activeDocumentAuthoring(store);
+  const id = adapter.selection?.get()[0] ?? null;
+  if (!id) return null;
+  return adapter.truth?.resolve(id, 'position').site ?? null;
+}
+
+/**
+ * The WRITE-side sibling of {@link activeSelectionCreationSite}: which lane
+ * would carry an edit to the current selection (`WriteAnchorKind`).
+ *
+ * Reported beside the anchor because the anchor alone cannot answer it — two
+ * subjects at the same kind of `file:line` can belong to different lanes with
+ * different correctness contracts. A caller sweeping the hierarchy for one
+ * subject per lane reads this per row; a probe's edit-write walk is that
+ * caller, and it is what makes the walk exhaustive over the kinds a world has
+ * instead of stopping at whichever row answered first.
+ *
+ * `null` on the same terms as the anchor: nothing selected, or an adapter that
+ * plans no distinguishable lanes.
+ *
+ * READ THROUGH THE SAME BINDING THE WRITE TAKES ({@link activeDocumentAuthoring},
+ * which is what `setActiveInspectionField` resolves too). A classifier reached
+ * through a different resolver than the writer is how a subject came to be
+ * reported in one lane while its edit travelled another.
+ */
+export function activeSelectionWriteAnchorKind(store: ShellDocumentState): WriteAnchorKind | null {
+  const adapter = activeDocumentAuthoring(store);
+  const id = adapter.selection?.get()[0] ?? null;
+  if (!id) return null;
+  return adapter.truth?.resolve(id, 'position').writeAnchorKind ?? null;
+}
+
+/** Current document-local selection, shared by UI actions and the control API. */
+export function activeSelectionIds(store: ShellDocumentState): string[] {
+  return [...(activeDocumentAuthoring(store).selection?.get() ?? store.selectedEntityIds)];
+}
+
+/** Route selection through the active document's native adapter. */
+export function selectAuthoringNodes(store: ShellDocumentState, ids: readonly string[]): void {
+  const adapter = activeDocumentAuthoring(store);
+  if (!setAuthoringSelection(adapter, ids)) store.selectMultiple([...ids]);
+}
+
+/** Select every node the active adapter's hierarchy exposes. */
+export function selectAllAuthoringNodes(store: ShellDocumentState): void {
+  selectAuthoringNodes(
+    store,
+    activeHierarchyRows(store).map((row) => row.id),
+  );
+}
+
+/** Save through the active adapter's persistence provider (no-op when it has none). */
+export async function saveActiveAuthoring(store: ShellDocumentState): Promise<void> {
+  await saveAuthoringDocument(getActiveAuthoring(store), 'the shell saved the active document');
+}

package/src/kit/authoring/story-board-chrome-fit.ts

@@ -0,0 +1,107 @@
+/**
+ * Board chrome — frame names and group names — is CONSTANT-SIZE client-space
+ * furniture floating over a board that zooms underneath it (the deliberate
+ * Figma-style choice: names stay readable at any scale). The authored gaps
+ * that chrome lives in DO shrink with zoom, so below some zoom a constant
+ * 26px frame-name stack no longer fits a 64-authored-px row gap and paints
+ * over the frames of the row above.
+ *
+ * This module owns the one rule that prevents that: **chrome degrades, frames
+ * never move**. Given the client-space room above a row of frames, it returns
+ * the scale/opacity/offset the chrome must adopt so its painted box always
+ * ends at or below whatever sits above it. Layout stays zoom-independent.
+ *
+ * Priority: a group name is the navigation anchor at overview zoom, so it is
+ * served FIRST out of the available room and therefore degrades LAST; the
+ * frame name gets whatever is left over.
+ */
+
+export const FRAME_LABEL_HEIGHT = 20;
+export const FRAME_LABEL_GAP = 6;
+export const GROUP_LABEL_HEIGHT = 22;
+export const GROUP_LABEL_GAP = 10;
+
+/** Client px a frame name claims above its frame's top edge at scale 1. */
+export const FRAME_LABEL_STACK = FRAME_LABEL_HEIGHT + FRAME_LABEL_GAP;
+/** Client px a group name claims above the frame-name stack at scale 1. */
+export const GROUP_LABEL_STACK = GROUP_LABEL_HEIGHT + GROUP_LABEL_GAP;
+
+/** Below this scale a name starts fading; below the hide scale it is dropped
+ *  entirely, because an unreadable sliver of text is noise, not information. */
+const FRAME_FADE_FROM = 0.6;
+const FRAME_HIDE_BELOW = 0.4;
+const GROUP_FADE_FROM = 0.7;
+const GROUP_HIDE_BELOW = 0.45;
+
+export interface ChromePlacement {
+  /** Uniform scale, applied with `transform-origin` at the element's bottom-left. */
+  readonly scale: number;
+  /** 0..1; 0 only when `visible` is false. */
+  readonly opacity: number;
+  /** false → do not paint (and do not accept pointer events) at all. */
+  readonly visible: boolean;
+  /** Client px to subtract from the row's top edge to get the element's `top`.
+   *  Accounts for the element's own unscaled height, since the scale pivots on
+   *  its bottom edge. */
+  readonly offset: number;
+}
+
+export interface StoryChromePlacement {
+  readonly frame: ChromePlacement;
+  /** null when the row carries no group name. */
+  readonly group: ChromePlacement | null;
+}
+
+function fade(scale: number, fadeFrom: number, hideBelow: number): [number, boolean] {
+  if (scale >= fadeFrom) return [1, true];
+  if (scale <= hideBelow) return [0, false];
+  return [(scale - hideBelow) / (fadeFrom - hideBelow), true];
+}
+
+/**
+ * Fit one frame row's chrome into the client-space `room` above it — the
+ * distance from the row's top edge to the bottom edge of the nearest frames
+ * above it (`Infinity` for the first row of the board, which has nothing
+ * above it to collide with).
+ *
+ * Invariant: the painted top of every returned placement is at or below
+ * `rowTop - room`, so chrome never paints over a frame that is not its own.
+ */
+export function placeStoryChrome(room: number, withGroupLabel: boolean): StoryChromePlacement {
+  const usable = Math.max(0, room);
+  const groupScale = withGroupLabel ? Math.min(1, usable / GROUP_LABEL_STACK) : 0;
+  const [groupOpacity, groupVisible] = fade(groupScale, GROUP_FADE_FROM, GROUP_HIDE_BELOW);
+
+  const frameRoom = Math.max(0, usable - GROUP_LABEL_STACK * groupScale);
+  const frameScale = Math.min(1, frameRoom / FRAME_LABEL_STACK);
+  const [frameOpacity, frameVisible] = fade(frameScale, FRAME_FADE_FROM, FRAME_HIDE_BELOW);
+
+  // A dropped frame name reserves nothing, which lets the group name settle
+  // closer to the frames instead of floating over an empty band.
+  const frameConsumed = frameVisible ? FRAME_LABEL_STACK * frameScale : 0;
+
+  return {
+    frame: {
+      scale: frameScale,
+      opacity: frameOpacity,
+      visible: frameVisible,
+      offset: FRAME_LABEL_GAP * frameScale + FRAME_LABEL_HEIGHT,
+    },
+    group: withGroupLabel
+      ? {
+          scale: groupScale,
+          opacity: groupOpacity,
+          visible: groupVisible,
+          offset: frameConsumed + GROUP_LABEL_GAP * groupScale + GROUP_LABEL_HEIGHT,
+        }
+      : null,
+  };
+}
+
+/** Paint one chrome element at the placement this module computed. */
+export function applyStoryChrome(element: HTMLElement, placement: ChromePlacement): void {
+  element.style.transformOrigin = '0 100%';
+  element.style.transform = placement.scale >= 1 ? '' : `scale(${placement.scale})`;
+  element.style.opacity = placement.visible ? String(placement.opacity) : '0';
+  element.style.display = placement.visible ? '' : 'none';
+}

package/src/kit/authoring/story-board-presentation.ts

@@ -0,0 +1,111 @@
+/**
+ * THE BOARD SUBSTRATE'S PRESENTATION CONTRACT — types only, no runtime import
+ * of any kind, and that is the whole point.
+ *
+ * `react-story-board.ts` is THE board substrate and stays in the host: two
+ * host chrome files draw OVER it (`components/ReactCanvasControls.tsx`, the
+ * viewport strip; `components/RootSelectionOverlay.tsx`, the frame hit-test),
+ * which is a different question from how a board MOUNTS. But it used to
+ * compute its own layout by calling `stories/story-presentation.ts`, which
+ * imports `storybook/viewport` and `storybook/internal/csf` — so the one file
+ * the host genuinely owns dragged Storybook in behind it.
+ *
+ * The decoupling is an injected RESOLVER, not a dropped default: the board
+ * resolves a presentation per story, per viewport override, INSIDE its own
+ * layout pass ({@link StoryBoardPresentation.resolve}), so a caller cannot
+ * pre-compute the answers and hand over a table. The callers — `@volter/editor-game`'s
+ * design-time mount and the canvas 2D board — each supply an
+ * implementation; `stories/story-presentation.ts` is the one that exists,
+ * and it implements these types rather than declaring its own, the way
+ * `design-time-layers.ts` exports `LayerMountResult` for the mounts that fill
+ * it.
+ *
+ * Storybook's slash title/path model is the organization source behind every
+ * implementation there is today, but nothing here says so: these are a board's
+ * own vocabulary — sections, nodes, a cell size, a viewport choice.
+ */
+
+/** How a frame's content sits inside its cell. */
+export type StoryLayout = 'padded' | 'centered' | 'fullscreen';
+
+/** One selectable frame size, in authored px. */
+export interface StoryViewportChoice {
+  readonly id: string;
+  readonly label: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** What a presentation is resolved FROM — everything a board frame knows
+ *  about its own story. */
+export interface StoryPresentationInput {
+  readonly id: string;
+  readonly label: string;
+  readonly modulePath: string;
+  readonly title?: string | undefined;
+  readonly parameters?: Readonly<Record<string, unknown>> | undefined;
+  readonly globals?: Readonly<Record<string, unknown>> | undefined;
+  readonly viewportLocked?: boolean | undefined;
+}
+
+/** One component section: the frames that belong together on the board. */
+export interface StoryPresentationSection {
+  readonly id: string;
+  readonly label: string;
+  readonly storyIds: readonly string[];
+}
+
+/** One row of the navigation tree the hierarchy and the board share. */
+export interface StoryPresentationTreeNode {
+  readonly id: string;
+  readonly label: string;
+  readonly role: 'folder' | 'component';
+  readonly kind: 'group' | 'component';
+  readonly parentId: string | null;
+  readonly childIds: readonly string[];
+  readonly secondaryLabel?: string;
+  readonly typeLabel: 'Category' | 'Folder' | 'Component';
+}
+
+/** The whole navigation index: how a set of stories is organized. */
+export interface StoryPresentationIndex {
+  readonly sections: readonly StoryPresentationSection[];
+  readonly nodes: readonly StoryPresentationTreeNode[];
+  readonly rootIds: readonly string[];
+  readonly storyParentIds: ReadonlyMap<string, string>;
+}
+
+/** One frame's resolved cell. */
+export interface ResolvedStoryPresentation {
+  readonly layout: StoryLayout;
+  readonly choices: readonly StoryViewportChoice[];
+  readonly selectedViewportId: string | null;
+  readonly locked: boolean;
+  readonly rotated: boolean;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * What a board is handed instead of an implementation: the index it lays out
+ * by, and the per-frame resolver it calls during that layout.
+ */
+export interface StoryBoardPresentation {
+  /** How this board's stories are organized into sections and tree rows. */
+  readonly index: StoryPresentationIndex;
+  /**
+   * This story's cell, right now. Called per story and again on every
+   * viewport/rotation override, which is why it is a function the board holds
+   * rather than a table it was given.
+   *
+   * `fallback` is the board's own default cell for a story that authored
+   * none; `sessionViewportId` is `undefined` for "whatever the story
+   * authored" and `null` for "explicitly none".
+   */
+  readonly resolve: (
+    story: StoryPresentationInput,
+    fallback?: { readonly width: number; readonly height: number },
+    sessionViewportId?: string | null,
+    sessionRotated?: boolean,
+  ) => ResolvedStoryPresentation;
+}

package/src/kit/authoring/three-root.ts

@@ -0,0 +1,67 @@
+/**
+ * Which declared world is the Three root this viewport paints, read from the composite's
+ * manifest kinds and capabilities only (no scene, no renderer), so kit panels can ask without
+ * importing the viewport.
+ */
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import { isRootHidden } from '@volter/sdk/kit/authoring/world-session-state';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { getActiveAuthoring } from './active-adapter';
+
+/**
+ * The worldId of the ONE three world actually rendered in this viewport
+ * (`store.objectMap`'s contents), or `null` when the active adapter isn't a
+ * composite (single-world project — no world-group row/eye exists for it at
+ * all, so there is nothing to resolve) or declares no three world.
+ *
+ * Identifies the LIVE Three child by `capabilities.transform` — a transient
+ * Boundary adapter reports no transform capability until the R3F design
+ * session attaches. This reuses an existing, already-load-bearing signal
+ * instead of adding an `instanceof` check or parallel bookkeeping slot.
+ */
+export function resolveThreeViewportRootId(store: ShellStore): string | null {
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) return null;
+  const focused = active
+    .childAdapters()
+    .find((c) => c.kind === 'three' && c.adapter.capabilities.transform);
+  return focused?.worldId ?? null;
+}
+
+/**
+ * Is a three surface currently SHOWING in the viewport? This is the single
+ * derived truth the 3D viewport chrome gates on (spec 28): the grid,
+ * orientation gizmo, transform toolstrip, camera readout, shading modes, and
+ * the transform gizmo itself are claims about what the user can do RIGHT NOW
+ * — showing them over a viewport with no visible 3D content is a false claim
+ * (same spirit as the adapter-reach rule: report what isn't there, never
+ * advertise it). The DOM half of the chrome (`RootSelectionOverlay`)
+ * already self-gates this way; this selector brings the pre-contract 3D
+ * chrome under the same rule.
+ *
+ * Truth table (deliberately conservative — every non-composite mode keeps
+ * today's behavior exactly):
+ *  - active adapter is not a composite (single-world project, ingest):
+ *    `true` — no world-group eyes exist there, so there is nothing to derive
+ *    from.
+ *  - composite with NO threejs-kind child at all (e.g. react-only
+ *    multi-world manifest): `false` — no 3D content can EVER show.
+ *  - composite whose three child is still a read-only Boundary
+ *    (`resolveThreeViewportRootId` → null): `true` — this is reachable
+ *    transiently while the R3F design session attaches; keep the chrome rather
+ *    than flickering it around adapter-install timing.
+ *  - composite with a live three world: `!isRootHidden(worldId)`
+ *    — the eye is the "what we're showing" signal.
+ *
+ * Recompute-per-call like everything else in this module: callers read it on
+ * every store notify (`syncFromStore` / `the world root's stage` render), never cache
+ * it across notifies.
+ */
+export function isThreejsSurfaceVisible(store: ShellStore): boolean {
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) return true;
+  const children = active.childAdapters();
+  if (!children.some((c) => c.kind === 'three')) return false;
+  const threeRootId = resolveThreeViewportRootId(store);
+  return threeRootId === null ? true : !isRootHidden(threeRootId);
+}