@volter/editor-core 0.5.57

package/src/components/inspector-revert-label.ts

@@ -0,0 +1,20 @@
+/**
+ * The ONE sentence the inspector's revert arrow says, as a pure function of the
+ * descriptor.
+ *
+ * Extracted rather than inlined in `Inspector.tsx` because the rule it encodes
+ * is a product contract worth a test — the arrow NAMES its destination when the
+ * adapter knows it (`Revert speed to 1.55`) and admits it doesn't when it
+ * doesn't (`Revert speed to default`) — while mounting the whole Inspector panel
+ * to assert a tooltip would be exactly the brittle DOM transcript the
+ * test-proportionality rule bans.
+ *
+ * One string serves both the accessible name and the tooltip: two phrasings of
+ * the same action is the "three paraphrases" failure this design explicitly
+ * legislates against (doctrine rule 2).
+ */
+export function revertActionLabel(property: { label: string; revertsTo?: string }): string {
+  return property.revertsTo === undefined
+    ? `Revert ${property.label} to default`
+    : `Revert ${property.label} to ${property.revertsTo}`;
+}

package/src/components/inspector-selection.ts

@@ -0,0 +1,42 @@
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+
+/**
+ * The inspection SUBJECT id — the selection resolution minus the adapter's
+ * own boot state, and the ONE resolution `Inspector.tsx`,
+ * `CompactInspectorCard.tsx` and the workspace host's availability gate all
+ * read; two of these disagreeing is exactly how the editor booted with an
+ * inspector the dock refused to mount (measured live, 2026-08-06).
+ *
+ * Explicit document contexts (model/source editors) remain sovereign, then
+ * the shared EditorShellStore is the most recent user selection, then the
+ * adapter's own selection — EXCEPT that an adapter which volunteers its
+ * single hierarchy ROOT before the user has selected anything (the R3F world
+ * binding does, so gizmo/hierarchy state has somewhere to live) is not
+ * naming a subject: the root IS the document, and the document's inspector
+ * representation is the surface's NO-SELECTION subject
+ * (`inspection/null-subject.ts` — the same reading the dom provider applies
+ * when it titles its empty state after its one root). A sovereign document
+ * selection of the root and any user selection remain real subjects.
+ *
+ * "MOST RECENT" IS THE LAST ENTRY, and this read the FIRST until 2026-09-18.
+ * The store's selection is an insertion-ordered `Set`, so `[0]` is the OLDEST
+ * id in a multi-selection while the store's own `selectedEntityId` — what the
+ * transform gizmo binds to — is `[...selection].at(-1)`. The two disagreed:
+ * click A, ctrl-click B, and the gizmo moved to B while the inspector kept
+ * showing A, with nothing on screen explaining either. One id now, which is
+ * also what lets the Outliner mark its active row (`GameHierarchy.tsx`'s
+ * `selectionAnchorId`). A single selection is a set of one and is unaffected.
+ */
+export function resolveInspectionSubjectId(
+  documentSelection: { readonly nodeId: string | null } | null,
+  storeSelection: ReadonlySet<string>,
+  adapter: AuthoringAdapter,
+): string | null {
+  if (documentSelection) return documentSelection.nodeId;
+  const stored = [...storeSelection].at(-1);
+  if (stored) return stored;
+  const volunteered = adapter.selection?.get().at(-1) ?? null;
+  if (volunteered === null) return null;
+  const roots = adapter.hierarchy.roots();
+  return roots.length === 1 && roots[0]?.id === volunteered ? null : volunteered;
+}

package/src/components/inspector-stories-gating.ts

@@ -0,0 +1,171 @@
+/**
+ * Whether the composed subject gets a STORIES section, and with what.
+ *
+ * This is an adapter-TOPOLOGY question — which child adapter owns this row —
+ * answered through the composite's public T0 queries, never by decoding an
+ * adapter-minted id. That is why it stays out of `inspection/compose.ts`: the
+ * composer takes the answer (`ComposeStoriesInput`) and composes it; working
+ * the answer out means knowing the shape of the live adapter tree.
+ *
+ * It lives in its own module because BOTH projections of the subject need the
+ * same answer: `components/Inspector.tsx` (the column and the card) and
+ * `inspection/active-subject.ts` (the serialized one, W4). Two copies of this
+ * gating would be two different Stories sections.
+ */
+
+import type { AuthoringAdapter, EditorNode, StoriesProvider } from '@volter/editor-project/adapter';
+import { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
+import { governingAdapterForNode } from '../authoring/provenance';
+import { WORLD_SCOPE_NODE_ID } from '../authoring/stories-scope';
+import { recordAuthoringConsumerUse } from '../coverage/authoring-seam-evidence';
+import type { ComposeStoriesInput } from '../inspection/compose';
+
+/**
+ * D4 (B2) — the CHILD adapter owning `nodeId`'s synthetic world-group row
+ * (`world:<id>`, `CompositeAuthoringAdapter`'s own manufactured node), or
+ * `null` when `adapter` isn't a composite or `nodeId` isn't one of its group
+ * nodes. Mirrors `GameHierarchy.tsx`'s (unexported) `compositeGroupBadge` —
+ * same "ask the public T0 query (`childAdapters()`/`groupNodeId()`), never
+ * decode the reserved id yourself" discipline.
+ *
+ * Used ONLY to gate the Stories section: a world-group row whose owning child
+ * adapter itself advertises `stories` (a live react world) gets the section
+ * (dropdown or "no stories" disclosure); any other row (an ordinary entity,
+ * or a world-group row for a kind that never sets `stories` — three/pixi/an
+ * un-upgraded Boundary placeholder) gets none.
+ */
+export function worldGroupChildAdapter(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return null;
+  for (const child of adapter.childAdapters()) {
+    if (adapter.groupNodeId(child.worldId) === nodeId) return child.adapter;
+  }
+  return null;
+}
+
+/**
+ * The composer's Stories input for this selection, or `null` when the
+ * selection has no stories concept at all.
+ *
+ * WITHIN a gated section the dropdown is fed by `storiesFor(id)` — NEVER by
+ * `adapter.stories` truthiness alone, since the composite's OWN `stories`
+ * pass-through is always present regardless of what (if anything) the routed
+ * child actually offers.
+ *
+ * Any node whose governing adapter publishes `stories` gets the section. This
+ * includes React world/component rows and source-backed Three component nodes;
+ * the shell does not infer a renderer from the node kind.
+ */
+/**
+ * The WORLD-LEVEL stories input with NOTHING selected, or `null` when the
+ * active adapter has no world-level stories to offer.
+ *
+ * A world-level provider (`storiesFor`/`active` ignore the node id — the react
+ * adapter's B2 scope, and every contract-scenes projection) answers for the
+ * whole world, so it is presentable on a world-scoped subject like the ingest
+ * coverage card. Gated on `storiesFor(WORLD_SCOPE_NODE_ID)` returning rows — never on
+ * `adapter.stories` truthiness (a composite's pass-through is always present)
+ * — so a per-node provider, which answers nothing for the empty id, shows
+ * nothing here.
+ */
+export function resolveWorldStoriesInput(adapter: AuthoringAdapter): ComposeStoriesInput | null {
+  const provider = adapter.stories;
+  if (!provider) return null;
+  const stories = provider.storiesFor(WORLD_SCOPE_NODE_ID);
+  if (stories.length === 0) return null;
+  return {
+    stories,
+    activeStoryId: provider.active(WORLD_SCOPE_NODE_ID) ?? '',
+    onApplyStory: (storyId) =>
+      recordAuthoringConsumerUse({
+        adapter,
+        seam: 'editor.stories.apply',
+        stage: 'effect',
+        detail: `the Inspector applied world story ${storyId}`,
+        run: () => provider.apply(WORLD_SCOPE_NODE_ID, storyId),
+      }),
+    isolation: null,
+    ...(provider.title === undefined ? {} : { title: provider.title }),
+  };
+}
+
+/**
+ * The stories provider scoped to `nodeId` ITSELF, or `null` when the adapter
+ * governing that node publishes a WORLD-LEVEL provider (or none at all).
+ *
+ * The exact complement of {@link resolveWorldStoriesInput}, on the same
+ * {@link WORLD_SCOPE_NODE_ID} probe: a component-scoped provider (the binding
+ * `component-states-registry.ts` hands an adapter) has no component for the
+ * empty id and answers `[]`; contract scenes and the react adapter's B2 provider answer
+ * their whole list.
+ *
+ * The GOVERNING adapter is probed, never the active one: a composite's
+ * `stories` pass-through routes by node ownership, so it answers `[]` for the
+ * empty id whatever the owning child's scope is — probing the pass-through
+ * would read every ingested game's scenes as node-scoped.
+ *
+ * A node-scoped affordance must route through here rather than reading
+ * `adapter.stories` directly. On an ingest root that provider IS the game's own
+ * scenes, so `apply` navigates the WHOLE GAME — a per-node button wired to it
+ * is not the node's story, it is a screen change wearing the node's label.
+ */
+export function resolveNodeScopedStories(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StoriesProvider | null {
+  const provider = governingAdapterForNode(adapter, nodeId)?.stories;
+  if (!provider) return null;
+  return provider.storiesFor(WORLD_SCOPE_NODE_ID).length > 0 ? null : provider;
+}
+
+export function resolveComposeStoriesInput(
+  adapter: AuthoringAdapter,
+  node: EditorNode | null,
+  nodeId: string | null,
+): ComposeStoriesInput | null {
+  if (!nodeId) return null;
+  const isCatalogNode = node?.kind === 'component';
+  const storiesOwner = governingAdapterForNode(adapter, nodeId);
+  if (!storiesOwner?.stories) return null;
+  const isWorldGroup = worldGroupChildAdapter(adapter, nodeId) !== null;
+  // A world-level provider (ingest screens, a react world's CSF states)
+  // answers for the whole world. Putting it on an ordinary node makes
+  // `apply` navigate the game / swap the world while wearing the node's
+  // label. World-group and catalog rows are the only subjects that own
+  // that scope.
+  if (
+    !isWorldGroup &&
+    !isCatalogNode &&
+    storiesOwner.stories.storiesFor(WORLD_SCOPE_NODE_ID).length > 0
+  ) {
+    return null;
+  }
+  const stories = adapter.stories?.storiesFor(nodeId) ?? [];
+  // `StoriesProvider.storiesFor` owns per-node applicability. Preserve the
+  // established world/catalog disclosure even when empty, but do not put an
+  // empty Stories section on every native child merely because its adapter
+  // can answer for component nodes elsewhere in the same world.
+  if (stories.length === 0 && !isWorldGroup && !isCatalogNode) return null;
+  return {
+    stories,
+    activeStoryId: adapter.stories?.active(nodeId) ?? '',
+    onApplyStory: (storyId) => {
+      const provider = adapter.stories;
+      if (!provider) return;
+      recordAuthoringConsumerUse({
+        adapter: storiesOwner,
+        seam: 'editor.stories.apply',
+        stage: 'effect',
+        detail: `the Inspector applied story ${storyId} to ${nodeId}`,
+        run: () => provider.apply(nodeId, storyId),
+      });
+    },
+    isolation: null,
+    // Asked of the OWNING adapter, not the composite: the composite routes by
+    // node and has no node-free answer, and the reason belongs to whichever
+    // provider would have produced the list.
+    unavailableReason: storiesOwner.stories.unavailable?.() ?? null,
+  };
+}

package/src/components/inspector-transform-subject.ts

@@ -0,0 +1,11 @@
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+
+/** Resolve whether a selected node owns a transform and which vocabulary to show. */
+export function transformDimensionsFor(adapter: AuthoringAdapter, id: string): '2d' | '3d' | null {
+  if (!adapter.transforms) return null;
+  const declared = adapter.transforms.dimensions?.(id);
+  if (declared !== undefined) return declared;
+  return adapter.hierarchy.object3D === undefined || adapter.hierarchy.object3D(id) !== null
+    ? '3d'
+    : null;
+}

package/src/components/inspector-transform.ts

@@ -0,0 +1,75 @@
+import type { Transform } from '@volter/editor-project/adapter';
+import * as THREE from 'three';
+
+export type TransformAxis = 0 | 1 | 2;
+
+/** Present Three.js quaternion rotations as the degree-based XYZ fields editors expect. */
+export function rotationDegrees(rotation: Transform['rotation']): [number, number, number] {
+  const quaternion = new THREE.Quaternion(...rotation);
+  if (quaternion.lengthSq() < Number.EPSILON) quaternion.identity();
+  else quaternion.normalize();
+  const euler = new THREE.Euler().setFromQuaternion(quaternion, 'XYZ');
+  return [
+    THREE.MathUtils.radToDeg(euler.x),
+    THREE.MathUtils.radToDeg(euler.y),
+    THREE.MathUtils.radToDeg(euler.z),
+  ];
+}
+
+/**
+ * Replace one whole displayed CHANNEL — the wire's write, where
+ * {@link withRotationDegrees} is the rendered rows' per-axis one.
+ *
+ * `rotation` arrives in the units the section publishes and the rows display
+ * (Euler XYZ degrees), which is the only reason a caller can hand back a value
+ * it read from `data` and get the pose it read.
+ */
+export function withTransformChannel(
+  transform: Transform,
+  channel: 'position' | 'rotation' | 'scale',
+  value: readonly number[],
+): Transform {
+  if (value.length !== 3 || value.some((n) => !Number.isFinite(n))) {
+    throw new Error(`transform.${channel} expects three finite numbers.`);
+  }
+  const next: Transform = {
+    position: [...transform.position] as [number, number, number],
+    rotation: [...transform.rotation] as [number, number, number, number],
+    scale: [...transform.scale] as [number, number, number],
+  };
+  if (channel === 'rotation') {
+    const q = new THREE.Quaternion().setFromEuler(
+      new THREE.Euler(
+        THREE.MathUtils.degToRad(value[0]!),
+        THREE.MathUtils.degToRad(value[1]!),
+        THREE.MathUtils.degToRad(value[2]!),
+        'XYZ',
+      ),
+    );
+    return { ...next, rotation: [q.x, q.y, q.z, q.w] };
+  }
+  return { ...next, [channel]: [value[0]!, value[1]!, value[2]!] };
+}
+
+/** Replace one displayed Euler axis while preserving the other displayed axes. */
+export function withRotationDegrees(
+  transform: Transform,
+  axis: TransformAxis,
+  degrees: number,
+): Transform {
+  const displayed = rotationDegrees(transform.rotation);
+  displayed[axis] = degrees;
+  const quaternion = new THREE.Quaternion().setFromEuler(
+    new THREE.Euler(
+      THREE.MathUtils.degToRad(displayed[0]),
+      THREE.MathUtils.degToRad(displayed[1]),
+      THREE.MathUtils.degToRad(displayed[2]),
+      'XYZ',
+    ),
+  );
+  return {
+    position: [...transform.position] as [number, number, number],
+    rotation: [quaternion.x, quaternion.y, quaternion.z, quaternion.w],
+    scale: [...transform.scale] as [number, number, number],
+  };
+}