@volter/editor-core 0.5.57

package/src/components/Inspector.tsx

@@ -0,0 +1,233 @@
+/**
+ * `Inspector` — the connected inspector: it RESOLVES what is being inspected
+ * and hands it to a projection. It renders no content of its own.
+ *
+ * Two halves, and the split is the whole point:
+ *  - the MODEL side is `inspection/use-active-inspection.ts` → ONE
+ *    {@link InspectionDisplay} (`inspection/display.ts`): the composed
+ *    subject, its surface, whether an inspector exists at all, and which
+ *    projection shows it. the workspace host gates the dock panel
+ *    and the floating card on the SAME hook, so "the dock floats a card while
+ *    the inspector renders a column" is not a state the app can reach;
+ *  - the VIEW side is `components/InspectionProjection.tsx`, which reads
+ *    identity/verbs/sections off the subject and knows nothing else.
+ *
+ * `inspection/compose.ts` is the one assembler: the active
+ * {@link AuthoringAdapter}'s providers (`hierarchy` / `selection` /
+ * `transforms` / `inspector`) plus whatever `inspector-section-registry.ts`
+ * registrations match become ONE `InspectionSubject`. Which built-ins a
+ * contribution replaces (by CLAIMING their section ids) is resolved there and
+ * is never visible here.
+ */
+
+import { faUpRightAndDownLeftFromCenter } from '@fortawesome/free-solid-svg-icons';
+import { EditorIcon, IconButton, Panel, themeVars } from '@volter/editor-sdk/widgets';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { useEffect, useReducer, useSyncExternalStore } from 'react';
+import { assetSelectionVersion, subscribeAssetSelection } from '../asset-selection';
+import { getActiveCamera } from '../authoring/active-systems';
+import { resolvePanelAuthoring } from '../authoring/panel-authoring';
+import { useAvailabilitySelector } from '../availability-tick';
+import { useEditorStore } from '../editor-runtime';
+import type { EditorShellStore } from '../editor-shell-store';
+import { setActiveScope } from '../hotkeys';
+import { composeInspectionForBinding } from '../inspection/active-subject';
+import type { InspectionPresentation, InspectionSurfaceKind } from '../inspection/model';
+import { useActiveInspection } from '../inspection/use-active-inspection';
+import { setInspectorPresentationOverride } from '../inspector-presentation';
+import {
+  inspectorSectionRegistryVersion,
+  subscribeInspectorSectionRegistry,
+} from '../inspector-section-registry';
+import { liveAuthoringRefusal } from '../live-session-registry';
+import { projectMounts } from '../project-shape';
+import type { WorkspaceDocumentSelection } from '../workspace-document-registry';
+import { InspectionProjectionView } from './InspectionProjection';
+
+export interface AuthoringInspectorSurfaceProps {
+  readonly store: EditorShellStore;
+  readonly adapter: AuthoringAdapter;
+  readonly documentSelection: WorkspaceDocumentSelection | null;
+  /** The RESOLVED presentation for this surface (`inspection/display.ts`):
+   *  `'card'` tabs the sections behind icon buttons in the bottom-right card,
+   *  `'column'` stacks them in the classic column, `'properties'` tabs them
+   *  behind a vertical rail in that same column. Omitted (bounded
+   *  design-system hosts) behaves as `'column'` without the mode-switch
+   *  affordance — presentation is the live shell's concern. */
+  readonly presentation?: InspectionPresentation;
+  /** Which surface this is — the key the mode-switch affordances write their
+   *  override under, so a preference expressed here changes no other
+   *  surface. Omitted alongside `presentation`. */
+  readonly surface?: InspectionSurfaceKind;
+}
+
+/**
+ * The honest copy for an adapter with NO inspector surface at all — a
+ * `{ module }` root that publishes none, or an ingested native-React world
+ * (no-authoring by design, D-N8). It is deliberately not a projection of a
+ * subject — there is no subject, because the adapter cannot describe one.
+ */
+function NoAuthoringInspector({
+  presentation,
+  surface,
+}: {
+  readonly presentation: InspectionPresentation | undefined;
+  readonly surface?: InspectionSurfaceKind | undefined;
+}) {
+  const authoringRefusal = liveAuthoringRefusal();
+  const noAuthoringNote = (
+    <div
+      data-testid="no-authoring-note"
+      style={{
+        padding: 12,
+        color: themeVars.semantic.warning,
+        fontSize: 'var(--vgai-font-md)',
+        lineHeight: 1.5,
+      }}
+    >
+      {authoringRefusal !== null ? (
+        <>
+          <strong>Nothing to author.</strong> {authoringRefusal}
+        </>
+      ) : (
+        <>
+          <strong>Nothing to author.</strong> This root's adapter publishes no inspector surface, so
+          there is nothing here to describe or edit. The root is still hosted, sized, and disposed;
+          play it in the Game tab.
+        </>
+      )}
+    </div>
+  );
+  // The one affordance back to the narrow column: this card has no subject and
+  // no icon strip, so without it a collapsed nothing-to-author card has no
+  // route back. Shown only in the live shell (a known `surface`).
+  const expandRow = surface ? (
+    <div style={{ display: 'flex', justifyContent: 'flex-end', padding: '2px 4px' }}>
+      <IconButton
+        size="compact"
+        data-testid="inspector-expand"
+        aria-label="Expand inspector to side panel"
+        title="Expand inspector to side panel"
+        onClick={() => setInspectorPresentationOverride(surface, 'column')}
+      >
+        <EditorIcon icon={faUpRightAndDownLeftFromCenter} />
+      </IconButton>
+    </div>
+  ) : null;
+  if (presentation === 'card') {
+    return (
+      <div
+        className="vgai-mini-inspector"
+        data-testid="inspector-panel"
+        data-vgai-inspector-presentation="card"
+        onPointerDown={() => setActiveScope('inspector')}
+      >
+        {expandRow}
+        {noAuthoringNote}
+      </div>
+    );
+  }
+  return (
+    <Panel
+      name="Inspector (nothing to author)"
+      hideHeader
+      className="vgai-content-frost"
+      data-testid="inspector-panel"
+      onPointerDown={() => setActiveScope('inspector')}
+    >
+      {noAuthoringNote}
+    </Panel>
+  );
+}
+
+/**
+ * Production authoring Inspector with explicit application dependencies —
+ * the BOUNDED host entry point (design-system stories): it composes a subject
+ * from the adapter it is handed and projects it, so a host can exercise this
+ * exact surface through an adapter fixture instead of reproducing its fields
+ * in a visual facsimile. The live shell does NOT come through here; it goes
+ * through {@link Inspector}, which reads the one shared resolution.
+ *
+ * "Composes" is the SAME call either way — `composeInspectionForBinding`
+ * (`inspection/active-subject.ts`). The two paths differ only in where the
+ * binding comes from: handed in here, resolved from live state there.
+ */
+export function AuthoringInspectorSurface({
+  store,
+  adapter,
+  documentSelection,
+  presentation,
+  surface,
+}: AuthoringInspectorSurfaceProps) {
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  // Project inspector TOOLS register asynchronously (folder scan) and
+  // re-register on HMR, possibly while a matching selection is showing; the
+  // §5.1 asset selection is another context registrations key on.
+  useSyncExternalStore(subscribeInspectorSectionRegistry, inspectorSectionRegistryVersion);
+  useSyncExternalStore(subscribeAssetSelection, assetSelectionVersion);
+  const [, forceAdapterUpdate] = useReducer((value: number) => value + 1, 0);
+  useEffect(() => adapter.subscribe?.(forceAdapterUpdate), [adapter]);
+  if (!adapter.capabilities.inspectorFields) {
+    return <NoAuthoringInspector presentation={presentation} {...(surface ? { surface } : {})} />;
+  }
+  const { subject } = composeInspectionForBinding({
+    store,
+    adapter,
+    documentSelection,
+    surface,
+  });
+  return (
+    <InspectionProjectionView
+      subject={subject}
+      presentation={presentation ?? 'column'}
+      {...(surface ? { surface } : {})}
+    />
+  );
+}
+
+/**
+ * The LIVE inspector. Whether it shows at all, which layout it uses, and what
+ * is in it are all the ONE resolution
+ * (`inspection/use-active-inspection.ts`) the workspace gates on — read here,
+ * never re-derived. Every surface goes through it, an open asset document
+ * included: that document is the three paradigm scoped to a subtree, so the
+ * same box rides over it as rides over the scene.
+ */
+export function Inspector() {
+  const store = useEditorStore();
+  // A camera controller may register after Play's first React commit. Keep the
+  // contribution match live without making the inspection model own runtime
+  // system state; availability-tick is the existing late-capability seam used
+  // by the Profiler and Frame debugger for the same reason.
+  useAvailabilitySelector(() => getActiveCamera());
+  const display = useActiveInspection(store);
+  const { adapter } = resolvePanelAuthoring(store);
+  if (!display.available) return null;
+  if (!adapter.capabilities.inspectorFields) {
+    // A subject the shared resolver composed WITHOUT the adapter's fields —
+    // an ingest's coverage row, or the project's own asset selection (a
+    // model picked in Content, whose kind's asset inspector takes it from
+    // there) — renders through the ordinary projection. The nothing-to-author
+    // note is the floor for a MOUNTED root whose adapter describes nothing;
+    // a project that mounts nothing has no root to say that about, and with
+    // nothing selected the inspector shows nothing.
+    if (display.subject.identity !== null || display.subject.sections.length > 0) {
+      return (
+        <InspectionProjectionView
+          subject={display.subject}
+          presentation={display.presentation}
+          surface={display.surface}
+        />
+      );
+    }
+    if (!projectMounts()) return null;
+    return <NoAuthoringInspector presentation={display.presentation} surface={display.surface} />;
+  }
+  return (
+    <InspectionProjectionView
+      subject={display.subject}
+      presentation={display.presentation}
+      surface={display.surface}
+    />
+  );
+}

package/src/components/InspectorCanvasPreview.tsx

@@ -0,0 +1,35 @@
+/** The Inspector image captured from an existing native authoring viewport. */
+
+import { useEffect, useState } from 'react';
+
+export function InspectorCanvasPreview({
+  capture,
+  previewKey,
+  size,
+}: {
+  readonly capture: (size: number) => Promise<string | null>;
+  readonly previewKey: string;
+  readonly size: number;
+}) {
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setUrl(null);
+    void capture(size).then(
+      (next) => {
+        if (!cancelled) setUrl(next);
+      },
+      () => {
+        if (!cancelled) setUrl(null);
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [capture, previewKey, size]);
+
+  return url ? (
+    <img src={url} alt="Selected object preview" className="vgai-component-thumbnail" />
+  ) : null;
+}

package/src/components/InspectorFieldsSection.tsx

@@ -0,0 +1,290 @@
+/**
+ * The ONE renderer for an inspection section whose body is `kind: 'fields'`
+ * (`inspection/model.ts`) — a `FieldDescriptor` list plus the io that reads
+ * and writes it. Extracted verbatim from `components/Inspector.tsx`'s former
+ * inline `renderProperty`, so the stacked column and the compact card render
+ * a field identically: one per-`type` switch, one revert arrow rule, one
+ * testid rule.
+ *
+ * Chrome (a collapsible title, a group's `data-testid`) belongs to the
+ * PROJECTION, not here — this component renders rows and nothing else.
+ */
+
+import { faRotateLeft } from '@fortawesome/free-solid-svg-icons';
+import {
+  AssetSlotPicker,
+  Checkbox,
+  DraftTextInput,
+  EditorIcon,
+  IconButton,
+  LABEL_COL_WIDTH,
+  Select,
+  TextArea,
+  themeVars,
+  Vec3Input,
+} from '@volter/editor-sdk/widgets';
+import { useState } from 'react';
+import {
+  type FieldDescriptor,
+  fieldReadonlyReason,
+  type InspectionFieldIo,
+  isMixed,
+} from '../inspection/model';
+import { revertActionLabel } from './inspector-revert-label';
+import { DraftColorInput } from './primitives/DraftColorInput';
+import { useProjectImageAssets } from './use-project-image-assets';
+
+/** Layout-only remnant of the old hand-rolled field style — chrome now comes
+ *  from the shared `.vgai-input`/`.vgai-select` classes (theme.css), so
+ *  every field here shares one height/padding/radius/focus treatment. */
+const NUM_STYLE: React.CSSProperties = { width: 64 };
+
+/** Row label (label-left/field-right grammar) — one width via
+ *  `LABEL_COL_WIDTH` (I-13). */
+export const ROW_LABEL_STYLE: React.CSSProperties = {
+  width: LABEL_COL_WIDTH,
+  fontSize: 'var(--vgai-font-md)',
+  color: themeVars.content.muted,
+};
+
+/** One rule, no exceptions: `visible` used to get a hand-carved
+ *  `ingest-visible` testid for an e2e spec that no longer exists. */
+function testidFor(path: string): string {
+  return `ingest-prop-${path.replace(/\./g, '-')}`;
+}
+
+/**
+ * The `asset` row's control — a project-asset slot (a material's texture map).
+ *
+ * Its own component because it holds two things a stateless row cannot: the
+ * shared project-image scan, and WHAT THE LAST ASSIGNMENT ANSWERED. The second
+ * is the point — a slot whose live half worked and whose file half did not is
+ * indistinguishable from a saved edit unless the ack is shown, so the write
+ * pipe's `persisted: false` is rendered here rather than dropped on the floor.
+ */
+function AssetFieldControl({
+  field,
+  io,
+  value,
+}: {
+  readonly field: FieldDescriptor;
+  readonly io: InspectionFieldIo;
+  readonly value: string;
+}) {
+  const { paths, failures } = useProjectImageAssets(true);
+  // The ack is remembered WITH the value it answered for. A row is reused as
+  // the selection moves between subjects that both publish this path, so an
+  // ack held on its own would go on claiming "not saved" about an edit made to
+  // something else — the exact confusion the note exists to prevent.
+  const [ack, setAck] = useState<{ readonly forValue: string; readonly text: string } | null>(null);
+  const assign = (next: string): void => {
+    setAck(null);
+    // An empty selection CLEARS the slot; `null` is the value an adapter reads
+    // as "no asset", not the empty string, which would be a path of length 0.
+    void Promise.resolve(io.set(field.path, next === '' ? null : next)).then((answer) => {
+      setAck(
+        answer && !answer.persisted
+          ? {
+              forValue: next,
+              text: `Not saved — ${answer.destination}. See the editor console for the mechanism.`,
+            }
+          : null,
+      );
+    });
+  };
+  const ackNote = ack?.forValue === value ? ack.text : undefined;
+  const scanNote =
+    failures.length > 0
+      ? `${failures.length} folder(s) under public/ could not be read — this list may be incomplete.`
+      : undefined;
+  return (
+    <AssetSlotPicker
+      testId={testidFor(field.path)}
+      value={value}
+      options={paths}
+      previewUrlFor={(path) => `/${path}`}
+      disabled={field.readonly}
+      note={ackNote ?? scanNote}
+      onChange={assign}
+    />
+  );
+}
+
+export function InspectorField({
+  field,
+  io,
+}: {
+  readonly field: FieldDescriptor;
+  readonly io: InspectionFieldIo;
+}) {
+  const p = field;
+  const raw = io.get(p.path);
+  // MIXED means "these subjects disagree" — there is no single value to show,
+  // which is exactly the blank/placeholder rendering an unset field already
+  // has. Normalized once, here, so no field widget below carries a second
+  // notion of emptiness.
+  const v = isMixed(raw) ? undefined : raw;
+  // UNSET: the document does not carry this property AND nobody could tell us
+  // what governs it in absence (a library component's defaults live in its
+  // implementation, not its type). Render it as genuinely blank — a `0` in a
+  // number field or an unchecked box would be a claim about the value, and
+  // `gravityScale` actually defaults to 1, `canSleep` to true. The field is
+  // still editable: typing into it writes the property for the first time.
+  const unset = p.defaulted === true && v === undefined;
+  const readonlyReason = p.readonly ? fieldReadonlyReason(p) : undefined;
+  /** The revert arrow, rendered only on rows the adapter says can lose their
+   *  override. Occupies no space otherwise, so rows stay aligned. */
+  const revertButton = p.resettable ? (
+    <IconButton
+      data-testid={`ingest-revert-${p.path.replace(/\./g, '-')}`}
+      aria-label={revertActionLabel(p)}
+      title={revertActionLabel(p)}
+      onClick={() => io.remove?.(p.path)}
+    >
+      <EditorIcon icon={faRotateLeft} />
+    </IconButton>
+  ) : null;
+
+  if (p.type === 'boolean') {
+    return (
+      <label
+        title={readonlyReason}
+        style={{
+          display: 'flex',
+          gap: 6,
+          alignItems: 'center',
+          padding: '6px 8px',
+          fontSize: 'var(--vgai-font-md)',
+        }}
+      >
+        <Checkbox
+          data-testid={testidFor(p.path)}
+          checked={Boolean(v)}
+          // Indeterminate says "not set here" without claiming false.
+          ref={(el: HTMLInputElement | null) => {
+            if (el) el.indeterminate = unset;
+          }}
+          disabled={p.readonly}
+          onChange={(e) => io.set(p.path, e.target.checked)}
+        />
+        <span style={p.defaulted ? { color: themeVars.content.dim } : undefined}>{p.label}</span>
+        {revertButton}
+      </label>
+    );
+  }
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 6, padding: '6px 8px' }}>
+      {/* A defaulted row is greyed: the value is the owner's declared
+          default, not something this document says. Editing it writes the
+          property in for the first time. */}
+      <span
+        style={p.defaulted ? { ...ROW_LABEL_STYLE, color: themeVars.content.dim } : ROW_LABEL_STYLE}
+        title={readonlyReason ?? (p.defaulted ? `${p.label} — default (not set here)` : p.label)}
+      >
+        {p.label}
+      </span>
+      {p.type === 'color' ? (
+        <DraftColorInput
+          data-testid={p.path === 'material.color' ? 'ingest-color' : testidFor(p.path)}
+          value={(v as string) ?? '#ffffff'}
+          disabled={p.readonly}
+          onCommit={(next) => io.set(p.path, next)}
+          // Live while the picker is open (adapters that cannot show a value
+          // without writing it omit `preview`, and this is a no-op).
+          onPreview={(next) => io.preview?.(p.path, next)}
+        />
+      ) : p.type === 'number' ? (
+        <DraftTextInput
+          type="number"
+          data-testid={testidFor(p.path)}
+          disabled={p.readonly}
+          value={typeof v === 'number' ? String(Math.round(v * 1000) / 1000) : ''}
+          placeholder={unset ? '—' : undefined}
+          onCommit={(text) => {
+            const parsed = Number.parseFloat(text);
+            if (Number.isFinite(parsed)) io.set(p.path, parsed);
+          }}
+          style={NUM_STYLE}
+        />
+      ) : p.type === 'enum' ? (
+        <Select
+          data-testid={testidFor(p.path)}
+          disabled={p.readonly}
+          value={String(v ?? '')}
+          onChange={(e) => {
+            const value =
+              p.options?.find((option) => String(option) === e.target.value) ?? e.target.value;
+            io.set(p.path, value);
+          }}
+          style={{ width: 120 }}
+        >
+          {unset && <option value="">—</option>}
+          {(p.options ?? []).map((option) => (
+            <option key={String(option)} value={String(option)}>
+              {String(option)}
+            </option>
+          ))}
+        </Select>
+      ) : p.type === 'vec3' ? (
+        <div style={{ width: 190 }}>
+          <Vec3Input
+            value={
+              Array.isArray(v) && v.length === 3
+                ? [Number(v[0]), Number(v[1]), Number(v[2])]
+                : [null, null, null]
+            }
+            disabled={Boolean(p.readonly)}
+            testIdPrefix={testidFor(p.path)}
+            onChange={(value) => io.set(p.path, value)}
+          />
+        </div>
+      ) : p.type === 'asset' ? (
+        <AssetFieldControl field={p} io={io} value={typeof v === 'string' ? v : ''} />
+      ) : p.type === 'json' ? (
+        <TextArea
+          key={`${p.path}:${JSON.stringify(v ?? null)}`}
+          data-testid={testidFor(p.path)}
+          data-variant="code"
+          disabled={p.readonly}
+          defaultValue={unset ? '' : JSON.stringify(v ?? null)}
+          placeholder={unset ? '—' : undefined}
+          onBlur={(event) => {
+            try {
+              io.set(p.path, JSON.parse(event.target.value));
+            } catch {
+              // Keep the authored value unchanged until the edit is valid JSON.
+            }
+          }}
+          style={{ width: 160 }}
+        />
+      ) : (
+        <DraftTextInput
+          type="text"
+          data-testid={testidFor(p.path)}
+          readOnly={p.readonly}
+          value={String(v ?? '')}
+          placeholder={unset ? '—' : undefined}
+          onCommit={(text) => io.set(p.path, text)}
+          style={{ width: 120 }}
+        />
+      )}
+      {revertButton}
+    </div>
+  );
+}
+
+export function InspectorFieldsSection({
+  fields,
+  io,
+}: {
+  readonly fields: readonly FieldDescriptor[];
+  readonly io: InspectionFieldIo;
+}) {
+  return (
+    <>
+      {fields.map((field) => (
+        <InspectorField key={field.path} field={field} io={io} />
+      ))}
+    </>
+  );
+}

package/src/components/InspectorObjectPreview.tsx

@@ -0,0 +1,57 @@
+import type * as THREE from 'three';
+import { Object3DSnapshotDocument } from './asset-viewers/EntityModelDocument';
+
+/**
+ * Inspector-sized projection of the canonical Asset Lab viewport, over a live
+ * `Object3D` the caller already has in hand.
+ *
+ * It takes the OBJECT, not an id to look one up by: a subject's preview is
+ * composed only when the thing is genuinely previewable
+ * (`inspection/compose.ts`), and the object the composer proved exists is the
+ * one rendered here. A scene node and a part inside an asset document are
+ * therefore the same case — the part is not in the shell's object map, and
+ * with an id this component could only have shown a "no longer available"
+ * alert for a thing that is right there on screen.
+ *
+ * Every host passes `fill`: the section body's square box, the compact card's
+ * round disc, and the minimized card's round thumb all own their own geometry
+ * and this component just fills it.
+ */
+export function InspectorObjectPreview({
+  previewKey,
+  object,
+  displayName,
+  fill = false,
+}: {
+  /** Stable identity for the isolated preview document. */
+  previewKey: string;
+  object: THREE.Object3D;
+  displayName: string;
+  fill?: boolean;
+}) {
+  return (
+    <div
+      data-testid="inspector-object-preview"
+      style={
+        fill
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              width: '100%',
+              height: 220,
+              minHeight: 220,
+              borderBottom: '1px solid var(--vgai-structural-divider)',
+              overflow: 'hidden',
+              position: 'relative',
+            }
+      }
+    >
+      <Object3DSnapshotDocument
+        documentId={`inspector-preview:${previewKey}`}
+        source={object}
+        displayName={displayName}
+        active
+        chromeless
+      />
+    </div>
+  );
+}