@volter/editor-core 0.5.57

package/src/inspection/display.ts

@@ -0,0 +1,170 @@
+/**
+ * The DISPLAY resolution — "is there an inspector right now, and which
+ * projection is showing it?" — derived from the composed subject itself.
+ *
+ * ## The defect this exists for (measured live, 2026-08-06)
+ *
+ * With the UI document active and nothing selected, the inspector rendered
+ * the dom surface's own no-selection subject INSIDE the floating compact
+ * card, and `dock-panel:workspace:inspector` did not exist — while the dom
+ * surface's affinity is `column`. Two components had each open-coded the
+ * same "resolve the active surface, then resolve its presentation"
+ * expression over their own hand-rolled subscription sets: `components/Inspector.tsx` re-rendered when
+ * the active adapter notified, the workspace host did not, so the
+ * dock kept gating on the surface it had resolved before the document swap.
+ * "Both call the same function" is discipline, not structure, and it
+ * desynchronized within hours.
+ *
+ * ## The shape that makes disagreement unrepresentable
+ *
+ * There is ONE resolution — this type — and it is computed in ONE place
+ * (`inspection/active-subject.ts`, subscribed through
+ * `inspection/use-active-inspection.ts`). The presentation is read OFF THE
+ * COMPOSED SUBJECT (`InspectionSubject.presentation.preferred`, stamped by
+ * the composer from the surface it composed for), never re-derived from a
+ * surface the caller resolved for itself, and the dock's physical gating
+ * is nothing but that one value projected onto two booleans. A consumer
+ * cannot choose a projection the subject did not carry,
+ * because there is no second expression to choose it with.
+ *
+ * Pure: no React, no store, no subscription — `resolveInspectionDisplay` is a
+ * function of (subject, surface, override), which is what makes the invariant
+ * testable headlessly (`packages/editor/test/inspection-display.test.ts`).
+ */
+
+import {
+  type InspectorPresentationOverride,
+  resolveInspectorPresentation,
+} from '../inspector-presentation';
+import type {
+  WorkspaceDocumentKind,
+  WorkspaceDocumentSelection,
+} from '../workspace-document-registry';
+import {
+  type InspectionPresentation,
+  type InspectionSubject,
+  type InspectionSurfaceKind,
+  inspectionAffinityFor,
+} from './model';
+
+/** The two document kinds a project TOOL opens as: the generic runner
+ *  (`project-tool`) and a capability's own React surface (`tool-contribution`).
+ *  Both own their whole viewport — a tool document IS its own UI. */
+const PROJECT_TOOL_DOCUMENT_KINDS: readonly WorkspaceDocumentKind[] = [
+  'project-tool',
+  'tool-contribution',
+];
+
+/**
+ * Would the inspector be describing a document OTHER than the one on screen?
+ *
+ * Only a project-tool document can reach this state: `authoring/panel-authoring.ts`
+ * has no branch for one, so it falls through to the scene's composite adapter
+ * and the inspector composes the SCENE's lingering selection — which the
+ * compact card then renders on top of the tool's own surface (owner-reported,
+ * 2026-08-14; measured with the Data sheet active and `world:world` still
+ * selected in the 3D scene).
+ *
+ * The test is POSITIVE, like `inspection/active-surface.ts`'s Asset Lab test:
+ * a tool document that publishes its OWN selection context (the humanoid
+ * builder's Object3D preview does) is showing its own inspector and keeps it.
+ * One that publishes none is not the subject's document, and gets nothing —
+ * the same answer the doctrine already gives an empty selection.
+ */
+export function inspectorBelongsToAnotherDocument(input: {
+  readonly activeDocumentKind: WorkspaceDocumentKind | null;
+  readonly documentSelection: WorkspaceDocumentSelection | null;
+}): boolean {
+  const { activeDocumentKind, documentSelection } = input;
+  if (activeDocumentKind === null) return false;
+  if (!PROJECT_TOOL_DOCUMENT_KINDS.includes(activeDocumentKind)) return false;
+  return documentSelection === null;
+}
+
+export interface InspectionDisplay {
+  /** The composed subject. Always present — a surface with nothing to inspect
+   *  composes an empty subject rather than a null one — so read
+   *  {@link available} for "is there an inspector at all". */
+  readonly subject: InspectionSubject;
+  /** The surface the subject was composed for. */
+  readonly surface: InspectionSurfaceKind;
+  /** The resolved projection for this subject: the subject's own affinity,
+   *  overridden by whatever the user asked for on this surface. */
+  readonly presentation: InspectionPresentation;
+  /** Whether an inspector SUBJECT exists at all — a selection, or a surface
+   *  whose adapter answered `describeSubject(null)`, or a contribution that
+   *  matched the empty selection. `false` empties the inspector's CONTENT
+   *  (`components/Inspector.tsx` renders nothing) and withholds the floating
+   *  card; it does not remove the dock column — see {@link column}. */
+  readonly available: boolean;
+  /** The viewport-local compact box is the projection showing. Floats over
+   *  the viewport, so its coming and going moves no other pixel — it stays
+   *  gated on {@link available}. */
+  readonly card: boolean;
+  /**
+   * The `workspace:inspector` dock panel exists — true for BOTH docked
+   * layouts (`column` and `properties`). WORKSPACE GEOMETRY, not subject
+   * state — deliberately NOT gated on {@link available}.
+   *
+   * It used to be (`available && presentation === 'column'`), which made
+   * every select/deselect mount/unmount the dock panel and RESIZE THE
+   * VIEWPORT — measured live on the hosted editor: 587px wide with nothing
+   * selected, 309px with a selection, the camera reframing with it. Aim
+   * taken in one layout landed in the other, so clicking a second object
+   * "did nothing" or grabbed the arena behind it, and objects near the edge
+   * (the citadel's west tower) left the frame entirely on select. Four
+   * independent testers reported it as an unselectable-instances bug
+   * (runhuman passes 100/109/110/111) and every identity-layer suspect —
+   * occurrence ids, stamps, locks, resolve — measured correct; the world was
+   * simply MOVING between their clicks. One tester said "the shapes are
+   * changing on their own", which was exactly true.
+   *
+   * The content doctrine is unchanged: with nothing selected the inspector
+   * SHOWS nothing. The panel it shows nothing IN no longer comes and goes
+   * with the selection.
+   */
+  readonly column: boolean;
+}
+
+/**
+ * Resolve the display for a composed subject. The two booleans are mutually
+ * exclusive derivations of the ONE `presentation` value, so "the dock says
+ * card while the inspector renders a column" is not a state this type can
+ * hold.
+ *
+ * `subject === null` means the active surface has nothing to inspect; the
+ * caller still gets a display (with `available: false` and every projection
+ * off) so both consumers read the same object shape either way.
+ */
+export function resolveInspectionDisplay(input: {
+  readonly subject: InspectionSubject;
+  readonly surface: InspectionSurfaceKind;
+  readonly available: boolean;
+  readonly override: InspectorPresentationOverride | null;
+  /** The active workspace's docked-layout choice (`workspace-regions.ts`),
+   *  beneath the user's override and above the affinity. */
+  readonly workspaceDefault?: 'column' | 'properties' | 'card' | null;
+}): InspectionDisplay {
+  const { subject, surface, available, override, workspaceDefault = null } = input;
+  // The subject carries the affinity the composer stamped on it. A surface
+  // whose subject somehow did not compose still resolves the same way its
+  // subject would have, so the two can never name different affinities.
+  const affinity = subject.presentation.preferred ?? inspectionAffinityFor(surface);
+  // ONE resolver, shared with every other caller of the preference
+  // (`inspector-presentation.ts`).
+  const presentation: InspectionPresentation = resolveInspectorPresentation(
+    affinity,
+    override,
+    workspaceDefault,
+  );
+  return {
+    subject,
+    surface,
+    presentation,
+    available,
+    card: available && presentation === 'card',
+    // Geometry, not subject state — see the field's doc for the measured
+    // defect behind dropping the `available &&` guard here.
+    column: presentation !== 'card',
+  };
+}

package/src/inspection/document-subject.ts

@@ -0,0 +1,109 @@
+/**
+ * An open asset document's own SUBJECT, published for the one composer.
+ *
+ * ## What an asset document is, in the model
+ *
+ * "What is an asset in three.js but a hierarchical group of other three.js
+ * assets" (owner, 2026-08-07). An asset document is the three paradigm scoped
+ * to a SUBTREE — Unity's prefab-isolation mode: the same viewport, the same
+ * hierarchy, the same inspector box, with only the root changed. So it gets
+ * the ordinary inspector over it, in the ordinary place, and clicking a part
+ * inside it composes that part's subject exactly as clicking a node in the
+ * scene composes that node's.
+ *
+ * What is left for a document to say is what IT is when you have not pointed
+ * at one of its parts: its name, what kind of document it is, its provenance,
+ * and its own identified sections. It describes that as a SUBJECT and
+ * publishes it here; `authoring/null-inspection-subjects.tsx` hands it to the
+ * ONE composer as the `asset-lab` surface's `describeSubject(null)` answer, so
+ * a document's identity floor and a scene's empty state travel the same road.
+ *
+ * The shape this replaces published loose `InspectionSection[]` and let the
+ * document render them directly — sections reaching a renderer without ever
+ * being a subject's sections, which is exactly the side channel the model
+ * exists to remove.
+ *
+ * ## A latest-value holder that says when it changed
+ *
+ * The value is still written by the document that is RENDERING and read on
+ * demand — there is no state here the publisher does not already hold. What it
+ * also does is notify, because a publisher whose subject changes WITHOUT the
+ * inspector re-rendering for some other reason is otherwise invisible: the 2D
+ * components board publishes the picked frame's identity, nothing else about
+ * that pick reaches the inspector, and a human clicked frame after frame
+ * against an empty panel (runhuman pass 92). `use-active-inspection.ts`
+ * subscribes, per its own rule that everything the resolution reads is
+ * subscribed there once.
+ *
+ * The token discipline mirrors `activateAssetEditorContext`: a disposer only
+ * clears the exact publication it created, so an older document's unmount
+ * cannot erase a newer one's subject.
+ */
+
+import type { NullInspectionSubject } from './null-subject';
+
+/** What a document says it IS — the same shape any surface's
+ *  `describeSubject(null)` answer takes, so the composer needs no special
+ *  case for an asset document. */
+export type DocumentInspectionSubject = NullInspectionSubject;
+
+interface Published {
+  readonly documentId: string;
+  /** Read at consumption time so a mounted document can keep its section
+   * closures current without publishing again merely because React rendered
+   * it again. */
+  readonly readSubject: () => DocumentInspectionSubject;
+  readonly token: symbol;
+}
+
+let published: Published | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeDocumentInspectionSubject(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function documentInspectionSubjectVersion(): number {
+  return version;
+}
+
+/** Publish the subject the open document describes. Returns a disposer that
+ *  clears exactly this publication. */
+export function publishDocumentInspectionSubject(
+  documentId: string,
+  readSubject: () => DocumentInspectionSubject,
+): () => void {
+  const token = Symbol(documentId);
+  published = { documentId, readSubject, token };
+  notifyChanged();
+  return () => {
+    if (published?.token !== token) return;
+    published = null;
+    notifyChanged();
+  };
+}
+
+/** The subject the open document describes, or `null` when no document is
+ *  publishing one. */
+export function documentInspectionSubject(): {
+  readonly documentId: string;
+  readonly subject: DocumentInspectionSubject;
+} | null {
+  return published === null
+    ? null
+    : { documentId: published.documentId, subject: published.readSubject() };
+}
+
+export function __resetDocumentInspectionSubjectForTest(): void {
+  published = null;
+  notifyChanged();
+}

package/src/inspection/game-subject.ts

@@ -0,0 +1,85 @@
+/**
+ * THE GAME as an inspection subject — the play surface's empty state (owner
+ * ruling, `docs/ARCHITECTURE-CORE.md`, 2026-08-19: "while a runtime is live,
+ * nothing-selected on the play surface composes THE GAME as the inspector's
+ * subject").
+ *
+ * It passes the recorded empty-state test rather than weakening it: "with
+ * nothing selected the inspector shows nothing" holds except where a surface's
+ * empty space IS a real thing, and the play surface's empty space is the
+ * running game. Edit mode is unchanged — no runtime, no subject — and that is
+ * enforced by LIFETIME, not by a predicate: `play-mode.ts` registers this
+ * provider when a session starts and disposes it when the session stops, so
+ * outside play there is no provider to match at all.
+ *
+ * Sections are project contributions scoped to this subject. A game with no
+ * sections has nothing to inspect; its identity alone does not open a card.
+ */
+
+import { GAME_DOCUMENT_ID } from '../workspace-document-ids';
+import { activeWorkspaceDocumentId } from '../workspace-document-registry';
+import type { NullInspectionSubject } from './null-subject';
+import { registerNullSubjectProvider } from './null-subject';
+
+/**
+ * The Game subject's id — and therefore the SCOPING KEY a project inspector
+ * contribution matches on (`context.nullSubjectId === GAME_SUBJECT_ID`). It is
+ * a stable literal rather than a per-instance id precisely because it is a
+ * contract: a contribution scopes itself to "the game", and which mount that
+ * is follows the inspected instance underneath it.
+ */
+export const GAME_SUBJECT_ID = 'game';
+
+/** The live facts the subject shows. Read at describe time, never captured. */
+export interface GameSubjectFacts {
+  /** The project's display name (`vgai.project.json`'s `name`). */
+  readonly projectName: string | null;
+  /**
+   * The inspected seat's name, and ONLY when more than one seat is live —
+   * with a single mount "which game is this?" is not a question, and a row
+   * answering it would be chrome. With several, this is the one thing that
+   * distinguishes two mounts of the same project.
+   */
+  readonly instanceName: string | null;
+}
+
+/** The Game subject, shaped. Pure, so the identity contract is testable
+ *  without a play session or a DOM. */
+export function gameNullInspectionSubject(facts: GameSubjectFacts): NullInspectionSubject {
+  const name = facts.projectName?.trim();
+  return {
+    id: GAME_SUBJECT_ID,
+    // The project's own name, because the subject IS this project's game. The
+    // fallback is not a display choice — a project with no name is a broken
+    // manifest, and the row still has to say what kind of thing it is.
+    title: name && name.length > 0 ? name : 'Game',
+    // Present ⇒ the composer gives the subject a read-only identity ROW. The
+    // identity row is editor-owned per the facet ruling; no contribution
+    // stands in for it.
+    kindLabel: 'Game',
+    ...(facts.instanceName ? { note: { text: facts.instanceName } } : {}),
+    sections: [],
+  };
+}
+
+/**
+ * Publish the Game subject for the lifetime of one play session.
+ *
+ * `read` is a live reader rather than a snapshot: the subject FOLLOWS the
+ * inspected instance, so which seat's name it shows is resolved every time the
+ * inspector composes, not once at Play.
+ *
+ * The match is the active-document test and nothing more. The Game document is
+ * play-time only, so "a runtime is live" is already this registration's
+ * existence, and asking it twice would be two answers to one question. It also
+ * keeps the provider off every other surface: an Asset Lab document active
+ * means `activeWorkspaceDocumentId()` is that document's, so this never
+ * matches, and the asset-lab provider — registered at import time, therefore
+ * FIRST in the first-match-wins list — answers instead.
+ */
+export function registerGameNullSubject(read: () => GameSubjectFacts): () => void {
+  return registerNullSubjectProvider({
+    match: () => activeWorkspaceDocumentId() === GAME_DOCUMENT_ID,
+    describe: () => gameNullInspectionSubject(read()),
+  });
+}