@volter/editor-core 0.5.57

package/src/components/InspectorStoriesSection.tsx

@@ -0,0 +1,92 @@
+/**
+ * The Stories inspection section's renderer (D4/B3) — the story picker for a
+ * `world:<id>` group row whose owning child adapter advertises `stories`, and
+ * for a `kind:'component'` catalog node (which also gets the Isolate toggle).
+ *
+ * The governing adapter decides which nodes own portable states. React roots
+ * can apply them in place; Three component nodes open the same CSF state in
+ * the standard Object3D story document. This renderer knows neither substrate
+ * — it renders the provider data it is handed.
+ */
+
+import { Button, Select, themeVars } from '@volter/editor-sdk/widgets';
+
+export interface InspectorStoriesSectionProps {
+  /** The selection's available portable-CSF previews (`[]` ⇒ the disclosure). */
+  readonly stories: readonly { readonly id: string; readonly label: string }[];
+  /** Currently applied story id, or `''` for none. */
+  readonly activeStoryId: string;
+  readonly onApplyStory: (storyId: string | null) => void;
+  /** B3 — a catalog component node also gets the Isolate toggle. */
+  readonly isolation: { readonly isolated: boolean; readonly toggle: () => void } | null;
+  /** The PROVIDER's own reason its list could not be read
+   *  (`StoriesProvider.unavailable`), or `null`/absent when it ran. This
+   *  renderer reaches into no particular provider's discovery to find out:
+   *  the same section draws an ingested game's screens and a project's CSF. */
+  readonly unavailableReason?: string | null;
+}
+
+export function InspectorStoriesSection({
+  stories,
+  activeStoryId,
+  onApplyStory,
+  isolation,
+  unavailableReason,
+}: InspectorStoriesSectionProps) {
+  // No "Stories" label and no divider of its own: the projection heads every
+  // section with its title + icon and owns the separator
+  // (`components/InspectionProjection.tsx`).
+  return (
+    <div style={{ padding: '4px 0' }}>
+      {stories.length > 0 ? (
+        <Select
+          data-testid="ingest-stories-select"
+          value={activeStoryId}
+          onChange={(e) => {
+            const v = e.target.value;
+            onApplyStory(v === '' ? null : v);
+          }}
+          style={{ width: '100%' }}
+        >
+          <option value="">(none)</option>
+          {stories.map((s) => (
+            <option key={s.id} value={s.id}>
+              {s.label}
+            </option>
+          ))}
+        </Select>
+      ) : (
+        <div
+          data-testid="ingest-stories-none"
+          style={{
+            fontSize: 'var(--vgai-font-base)',
+            color: themeVars.content.dim,
+            fontStyle: 'italic',
+          }}
+        >
+          {/* "This root has no previews" is a claim about the PROJECT, and it
+              is only true when discovery actually ran. When it could not, say
+              which realm limitation or host failure stopped it instead — an
+              empty list and an unread list look identical from here. */}
+          {unavailableReason ?? 'No stories — this root has no associated portable CSF previews.'}
+        </div>
+      )}
+      {/* B3 — Isolate toggle: render ONLY this catalog component (alone,
+          against whichever story is currently selected in the dropdown
+          above) on the world's design-time layer; exiting restores the
+          Live Preview. Session-only — mirrors the story overlay writes,
+          never persisted to source. */}
+      {isolation && (
+        <Button
+          data-testid="catalog-isolate"
+          onClick={isolation.toggle}
+          variant={isolation.isolated ? 'primary' : 'secondary'}
+          aria-pressed={isolation.isolated}
+          style={{ marginTop: 6, width: '100%' }}
+        >
+          {isolation.isolated ? 'Exit isolation' : 'Isolate'}
+        </Button>
+      )}
+    </div>
+  );
+}

package/src/components/InspectorToolSection.tsx

@@ -0,0 +1,96 @@
+/**
+ * Inspector-tool section host (W3) — renders one project tool (`placement:
+ * 'inspector'`) as a section in the ONE inspector shell (`Inspector.tsx`), via
+ * `inspector-section-registry`.
+ *
+ * The chrome is the editor's (§3.4): a bordered section with a semantic tool
+ * icon in its title row, matching
+ * the shell's own section styling (`Inspector.tsx`'s Stories block). What the
+ * tool renders inside is its own business — plain React, ideally built from
+ * `@volter/editor-sdk/widgets` so fields sit flush with the built-in sections.
+ *
+ * Crash containment mirrors the dock (`ToolHost.tsx`, shared boundary): a
+ * throwing tool component swaps THIS section for a teaching message; the
+ * rest of the inspector, and every other tool, keep working. The loader
+ * re-registers a fresh registration per (re)load, so an HMR save remounts
+ * the section and clears a tripped boundary for free.
+ *
+ * W3.1 (§3.3): the tool render is wrapped in `EditorSelectionProvider`, INSIDE
+ * the error boundary, so `useSelection()` works for any inspector tool
+ * without adding to `InspectorToolProps` — richer data arrives through hooks,
+ * not more props. Utility tools get no such provider (`ToolHost` inside a
+ * utility has no adapter/selection in scope) — `useSelection` throws a
+ * teaching error, contained the same way a render crash is.
+ */
+
+import type { ToolInspectorContributionProps } from '@volter/editor-sdk/contributions';
+import { EditorSelectionProvider } from '@volter/editor-sdk/selection';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { type ComponentType, useSyncExternalStore } from 'react';
+import { accountVersion, contributionAccount, subscribeAccount } from '../account';
+import type { ProjectToolCatalogEntry } from '../project-tools';
+import {
+  subscribeToolContributionPlay,
+  toolContributionPlay,
+  toolContributionPlayKey,
+} from '../tool-contribution-play';
+import { getToolContributionClient } from '../tool-loader';
+import { toolContributionSurfaces } from './ToolContributionSurfaces';
+import { ToolErrorBoundary } from './ToolHost';
+
+export interface InspectorToolSectionProps {
+  /** `ToolConfig.id` — the section's `data-testid` suffix (`inspector-tool-<id>`). */
+  id: string;
+  /** The contribution's title — shown by the SECTION HEADER (the collapsible
+   *  row the inspector owns); the body deliberately does not repeat it. */
+  title: string;
+  /** Project-relative source file, shown in crash/teaching messages. */
+  file: string;
+  /** The registered callable the module named, when it named one at all. */
+  tool?: ProjectToolCatalogEntry;
+  Component: ComponentType<ToolInspectorContributionProps>;
+  /** Live adapter + selection, as the section registry hands them over. */
+  adapter: AuthoringAdapter;
+  nodeId: string | null;
+}
+
+/** One inspector tool's section: editor-styled chrome + boundary + the tool. */
+export function InspectorToolSection({
+  id,
+  title: _title,
+  file,
+  tool,
+  Component,
+  adapter,
+  nodeId,
+}: InspectorToolSectionProps) {
+  useSyncExternalStore(subscribeAccount, accountVersion, accountVersion);
+  // Re-render when the bound play instance changes, so a section mounted
+  // before Play (or while another seat was inspected) does not keep reporting
+  // "no game" to a contribution whose whole subject is the running one.
+  useSyncExternalStore(
+    subscribeToolContributionPlay,
+    toolContributionPlayKey,
+    toolContributionPlayKey,
+  );
+  const node = nodeId ? adapter.hierarchy.node(nodeId) : null;
+  return (
+    <div className="vgai-inspector-tool-section" data-testid={`inspector-tool-${id}`}>
+      <ToolErrorBoundary file={file}>
+        <EditorSelectionProvider adapter={adapter} nodeId={nodeId}>
+          <Component
+            {...(tool ? { tool } : {})}
+            contributionId={id.slice(id.lastIndexOf(':') + 1)}
+            client={getToolContributionClient()}
+            surfaces={toolContributionSurfaces}
+            account={contributionAccount()}
+            play={toolContributionPlay()}
+            node={node}
+            nodeId={nodeId}
+            adapter={adapter}
+          />
+        </EditorSelectionProvider>
+      </ToolErrorBoundary>
+    </div>
+  );
+}

package/src/components/InspectorTransformSection.tsx

@@ -0,0 +1,245 @@
+import { FieldGroup, FieldRow, NumberInput, Text } from '@volter/editor-sdk/widgets';
+import type { Transform, TransformChannel } from '@volter/editor-project/adapter';
+import { useRef, useState } from 'react';
+import { rotationDegrees, type TransformAxis, withRotationDegrees } from './inspector-transform';
+
+/** The industry-convention axis tint (X red, Y green, Z blue) — muted to the
+ *  panel's palette. A first-time tester reported the three unlabeled number
+ *  boxes made "Position X" unguessable (runhuman, 2026-08-27); the aria-label
+ *  alone labels nothing a sighted user can see. */
+const AXIS_COLORS: Record<string, string> = { x: '#e0726d', y: '#83bd66', z: '#6390dd' };
+
+/**
+ * One row of axis fields, each the editor's shared scrub field (`NumberInput`):
+ * drag to scrub, click to type with the whole value selected, commit on
+ * Enter/blur. This used to be three native `<input type="number">`s committing
+ * on EVERY keystroke — so typing "10" wrote 1 and then 10 (two source writes,
+ * two remounts, the second re-rendering the field mid-word: "it didn't give me
+ * time to type", runhuman pass 128), and a click landing on the native spinner
+ * bumped the value by one before the author typed anything (measured on the
+ * GPU instrument: click a field showing -5, type -7 → -47; double-click, type
+ * -9 → -459 — runhuman passes 122 and 127's "everything's there, just not
+ * where I wanted it").
+ *
+ * The three callbacks are ONE gesture shape for both scrub and typing: the
+ * first change opens it (`onBegin`), every change previews (`onPreview`), the
+ * release/Enter commits (`onCommit`) — the same begin/apply/end the gizmo
+ * drives, so a scrub is one undo step and one source write.
+ */
+function AxisRow({
+  axes,
+  label,
+  values,
+  testidPrefix,
+  step,
+  precision,
+  onBegin,
+  onPreview,
+  onCommit,
+  readOnly,
+  readOnlyReason,
+}: {
+  readonly axes: Array<{ axis: TransformAxis; name: string }>;
+  readonly label: string;
+  readonly values: [number, number, number];
+  readonly testidPrefix: string;
+  readonly step: number;
+  readonly precision: number;
+  readonly onBegin: (() => void) | undefined;
+  readonly onPreview: ((axis: TransformAxis, value: number) => void) | undefined;
+  readonly onCommit: (axis: TransformAxis, value: number) => void;
+  readonly readOnly: boolean;
+  readonly readOnlyReason?: string;
+}) {
+  // The value under the hand while a gesture is open: the projection's
+  // `values` follow the adapter's own notifications, which need not arrive
+  // per scrub move, and a field that lags its own drag reads as stuck.
+  const [live, setLive] = useState<{ axis: TransformAxis; value: number } | null>(null);
+  const gestureOpen = useRef(false);
+  return (
+    <FieldRow label={label} style={{ padding: '4px 8px' }}>
+      {axes.map(({ axis, name }) => (
+        <NumberInput
+          key={name}
+          testId={`${testidPrefix}-${name}`}
+          label={name}
+          labelColor={AXIS_COLORS[name]}
+          // The reason shows whether or not the field is disabled. A `reason`
+          // does not imply `writable: false`: the ingest adapter declares a
+          // WRITABLE channel whose reason states that the edit is live-only and
+          // names the source line it would have to be written to.
+          title={readOnlyReason}
+          disabled={readOnly}
+          step={step}
+          precision={precision}
+          value={
+            live?.axis === axis ? live.value : Number.isFinite(values[axis]) ? values[axis] : 0
+          }
+          style={{ flex: 1, minWidth: 0 }}
+          onChange={(value) => {
+            if (!gestureOpen.current) {
+              gestureOpen.current = true;
+              onBegin?.();
+            }
+            setLive({ axis, value });
+            onPreview?.(axis, value);
+          }}
+          onChangeEnd={(value) => {
+            gestureOpen.current = false;
+            setLive(null);
+            onCommit(axis, value);
+          }}
+        />
+      ))}
+    </FieldRow>
+  );
+}
+
+export function InspectorTransformSection({
+  dimensions = '3d',
+  transform,
+  readOnly = false,
+  channelEditability,
+  note,
+  onBegin,
+  onPreview,
+  onCommit,
+}: {
+  readonly dimensions?: '2d' | '3d';
+  readonly transform: Transform;
+  readonly readOnly?: boolean;
+  readonly channelEditability?: Partial<
+    Record<TransformChannel, { writable: boolean; reason?: string }>
+  >;
+  /**
+   * A sentence about what editing THESE numbers does, when that is not what a
+   * reader would assume — today the world-anchored instanced class
+   * (`instanced-presentation.ts`), whose container transform offsets future
+   * placements rather than moving the content already on screen.
+   *
+   * It is a visible line rather than a `title` like the per-channel reasons
+   * above, because it is not a refusal to explain on hover: the channels are
+   * writable and the surprise arrives after the write.
+   */
+  readonly note?: string | undefined;
+  /** A gesture is opening — the adapter's `beginEdit` (one undo step, one
+   *  write, however many previews follow). Optional: a caller with no live
+   *  path gets `onCommit` alone, which is a complete gesture by itself. */
+  readonly onBegin?: () => void;
+  /** The value under the hand mid-gesture — the adapter's live `apply`,
+   *  never a write. */
+  readonly onPreview?: (transform: Transform) => void;
+  /** The gesture's end — the adapter's `endEdit`, the one write. */
+  readonly onCommit: (transform: Transform) => void;
+}) {
+  const xyAxes: Array<{ axis: TransformAxis; name: string }> = [
+    { axis: 0, name: 'x' },
+    { axis: 1, name: 'y' },
+  ];
+  const xyzAxes: Array<{ axis: TransformAxis; name: string }> = [...xyAxes, { axis: 2, name: 'z' }];
+  const withVector = (axis: TransformAxis, key: 'position' | 'scale', value: number) => {
+    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],
+    };
+    next[key][axis] = value;
+    return next;
+  };
+  const vector =
+    (key: 'position' | 'scale', deliver: ((transform: Transform) => void) | undefined) =>
+    (axis: TransformAxis, value: number) => {
+      if (Number.isFinite(value)) deliver?.(withVector(axis, key, value));
+    };
+  const rotation =
+    (deliver: ((transform: Transform) => void) | undefined) =>
+    (axis: TransformAxis, value: number) => {
+      if (Number.isFinite(value)) deliver?.(withRotationDegrees(transform, axis, value));
+    };
+  const channelState = (channel: TransformChannel) => {
+    const state = channelEditability?.[channel];
+    const channelReadOnly = readOnly || state?.writable === false;
+    return state?.reason
+      ? { readOnly: channelReadOnly, readOnlyReason: state.reason }
+      : { readOnly: channelReadOnly };
+  };
+  // A GRAYED FIELD SAYS WHY WHERE THE EYE IS. The reason used to live only in
+  // the field's hover title, so a tester who dropped a self-placing prefab
+  // met "the Position X field is grayed out and uneditable" and concluded the
+  // test could not continue (runhuman pass 130) — the sentence that would
+  // have sent them to the component's own code was one hover away. Each
+  // distinct reason of a read-only channel is printed once, below the rows.
+  const readOnlyReasons = [
+    ...new Set(
+      (['position', 'rotation', 'scale'] as const)
+        .map((channel) => channelState(channel))
+        .filter((state) => state.readOnly && state.readOnlyReason)
+        .map((state) => state.readOnlyReason as string),
+    ),
+  ];
+
+  // No header of its own: the PROJECTION heads every section with its title
+  // and icon (`components/InspectionProjection.tsx`), so a "Transform" title
+  // printed here would be the second one on screen.
+  return (
+    <FieldGroup>
+      <AxisRow
+        axes={dimensions === '2d' ? xyAxes : xyzAxes}
+        label="Position"
+        testidPrefix="ingest-position"
+        values={transform.position}
+        step={0.1}
+        precision={3}
+        {...channelState('position')}
+        onBegin={onBegin}
+        onPreview={onPreview && vector('position', onPreview)}
+        onCommit={vector('position', onCommit)}
+      />
+      <AxisRow
+        axes={dimensions === '2d' ? [{ axis: 2, name: 'z' }] : xyzAxes}
+        label={dimensions === '2d' ? 'Rotation (degrees)' : 'Rotation'}
+        testidPrefix="ingest-rotation"
+        values={rotationDegrees(transform.rotation)}
+        step={1}
+        precision={1}
+        {...channelState('rotation')}
+        onBegin={onBegin}
+        onPreview={onPreview && rotation(onPreview)}
+        onCommit={rotation(onCommit)}
+      />
+      <AxisRow
+        axes={dimensions === '2d' ? xyAxes : xyzAxes}
+        label="Scale"
+        testidPrefix="ingest-scale"
+        values={transform.scale}
+        step={0.01}
+        precision={3}
+        {...channelState('scale')}
+        onBegin={onBegin}
+        onPreview={onPreview && vector('scale', onPreview)}
+        onCommit={vector('scale', onCommit)}
+      />
+      {readOnlyReasons.map((reason) => (
+        <Text
+          key={reason}
+          data-testid="inspector-transform-readonly-reason"
+          variant="caption"
+          tone="muted"
+          style={{ display: 'block', padding: '4px 8px', overflowWrap: 'anywhere' }}
+        >
+          {reason}
+        </Text>
+      ))}
+      {note && (
+        <Text
+          data-testid="inspector-transform-note"
+          variant="caption"
+          tone="muted"
+          style={{ display: 'block', padding: '4px 8px', overflowWrap: 'anywhere' }}
+        >
+          {note}
+        </Text>
+      )}
+    </FieldGroup>
+  );
+}