@volter/editor-core 0.5.57

package/src/authoring/viewport-tool-context.ts

@@ -0,0 +1,73 @@
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import type { EditorShellStore } from '../editor-shell-store';
+import { adapterOnlyToolOwner, type ViewportToolOwner } from '../viewport-authoring-policy';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { resolveThreeViewportRootId } from './world-hidden-viewport';
+import { isRootHidden } from './world-session-state';
+
+/**
+ * The one native root whose viewport tools may claim the current selection.
+ *
+ * A composed game can contain several native surfaces at once, but editing
+ * chrome needs one unambiguous coordinate system and capability owner. Empty,
+ * organizational, and cross-root selections therefore resolve to `null`.
+ */
+export interface ViewportToolContext extends ViewportToolOwner {
+  readonly adapter: AuthoringAdapter;
+}
+
+function compositeContext(
+  composite: CompositeAuthoringAdapter,
+  selectedIds: readonly string[],
+): ViewportToolContext | null {
+  const children = composite.childAdapters();
+  let owner: (typeof children)[number] | null = null;
+
+  for (const id of selectedIds) {
+    const child =
+      children.find((candidate) => composite.groupNodeId(candidate.worldId) === id) ??
+      children.find((candidate) => composite.ownerOf(id) === candidate.worldId);
+    // Kind/projection folders and stale ids do not claim native-world tools.
+    if (!child) return null;
+    // A heterogeneous selection has no single native editing context.
+    if (owner && owner.worldId !== child.worldId) return null;
+    owner = child;
+  }
+
+  return owner ? { worldId: owner.worldId, kind: owner.kind, adapter: owner.adapter } : null;
+}
+
+/**
+ * Resolve viewport-tool ownership from selection, never from which roots
+ * merely exist or happen to be visible.
+ */
+export function resolveViewportToolContext(
+  adapter: AuthoringAdapter,
+  selectedIds: Iterable<string>,
+): ViewportToolContext | null {
+  const ids = [...selectedIds];
+  if (ids.length === 0) return null;
+  if (adapter instanceof CompositeAuthoringAdapter) return compositeContext(adapter, ids);
+
+  // Legacy/single-adapter sessions have no manifest kind metadata, and that
+  // fallback is `adapterOnlyToolOwner` — it speaks only the adapter contract,
+  // so it lives below the shell (`viewport-authoring-policy.ts`) as the gizmo
+  // viewport's own default. One copy, read from both sides.
+  const owner = adapterOnlyToolOwner(adapter, ids);
+  return owner ? { ...owner, adapter } : null;
+}
+
+/**
+ * Whether the selected owner is actually painted in this viewport. DOM
+ * layers follow their world eye; the manifest's sole Three root owns the 3D
+ * viewport chrome only while that root is visible.
+ */
+export function isViewportToolContextVisible(
+  store: EditorShellStore,
+  context: ViewportToolOwner | null,
+): boolean {
+  if (!context) return false;
+  if (context.worldId !== null && isRootHidden(context.worldId)) return false;
+  if (context.kind !== 'three' || context.worldId === null) return true;
+  return resolveThreeViewportRootId(store) === context.worldId;
+}

package/src/authoring/world-canvas-viewport-state.ts

@@ -0,0 +1,35 @@
+/** Session-only responsive canvas size for DOM-backed authoring roots. */
+export interface RootCanvasViewport {
+  readonly width: number | null;
+  readonly height: number | null;
+}
+
+const FILL_VIEWPORT: RootCanvasViewport = { width: null, height: null };
+let viewport: RootCanvasViewport = FILL_VIEWPORT;
+const listeners = new Set<() => void>();
+
+export function getRootCanvasViewport(): RootCanvasViewport {
+  return viewport;
+}
+
+export function setRootCanvasViewport(width: number | null, height: number | null): void {
+  const nextWidth = width === null ? null : Math.max(1, Math.round(width));
+  const nextHeight = height === null ? null : Math.max(1, Math.round(height));
+  if (viewport.width === nextWidth && viewport.height === nextHeight) return;
+  viewport = { width: nextWidth, height: nextHeight };
+  for (const listener of listeners) listener();
+}
+
+export function resetRootCanvasViewport(): void {
+  setRootCanvasViewport(null, null);
+}
+
+export function subscribeRootCanvasViewport(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function _resetRootCanvasViewportForTest(): void {
+  viewport = FILL_VIEWPORT;
+  listeners.clear();
+}

package/src/authoring/world-hidden-viewport.ts

@@ -0,0 +1,152 @@
+/**
+ * World-hidden eye (D9, `world-session-state.ts`) applied to the EDIT-mode
+ * three viewport.
+ *
+ * Bug this fixes: the eye on a hierarchy world-group row (`world:<id>
+ * (<kind>)`, shown for 2+ world manifests) toggles `isRootHidden(worldId)`
+ * and culls the hierarchy subtree, but for a react/pixi world that's ALSO the
+ * only thing that mattered — `design-time-layers.ts`'s `applySessionStyle`
+ * sets `display:none` on that world's DOM layer. A three world has no DOM
+ * layer; nothing else consumes `isRootHidden` for its actual
+ * `THREE.Object3D`s, so without this module the eye is a viewport no-op.
+ *
+ * Session-local only — it writes no file and pushes no undo entry, matching
+ * the DOM roots' own `display:none` semantics. Every call RECOMPUTES
+ * `obj.visible` rather than remembering a previous value, which is what makes
+ * it rebuild-proof: an adapter that re-renders its tree re-stamps
+ * `obj.visible` from its own truth and would silently drop a one-shot
+ * override, but the very next call here puts the world-hidden override back.
+ * Callers must re-invoke this after every rebuild
+ * AND after the toggle itself; `editor-viewport.ts`'s `syncFromStore()` is
+ * exactly that seam — it already re-runs on every `store.subscribe` notify,
+ * which covers both an adapter rebuild (which notifies) and
+ * `GameHierarchy.tsx`'s toggle handler (`toggleRootHidden` +
+ * `store.notifyIngestEdit()`).
+ *
+ * A composite's `store.objectMap`/live THREE.Scene holds the manifest's sole
+ * three content root. `GameManifestSchema` rejects a second content root of
+ * the same medium, so `resolveThreeViewportRootId` below only needs to name
+ * that one world id rather than arbitrate per-object ownership.
+ */
+
+import { getUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+import type { EditorShellStore } from '../editor-shell-store';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { isRootHidden } from './world-session-state';
+
+/**
+ * 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: EditorShellStore): 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;
+}
+
+/**
+ * Apply the eye toggle to every object in `objectMap` (see module doc
+ * comment for the full rebuild-proofing rationale). `threeRootId` is
+ * accepted as a parameter (rather than re-resolved internally) so a caller
+ * that already computed it once per call (e.g. for a cheap re-apply
+ * signature) doesn't pay for `resolveThreeViewportRootId`'s composite walk
+ * twice.
+ */
+export function applyRootHiddenVisibility(
+  objectMap: ReadonlyMap<string, THREE.Object3D>,
+  threeRootId: string | null,
+): void {
+  const hidden = threeRootId !== null && isRootHidden(threeRootId);
+  if (!hidden) return;
+  // The live `Object3D.visible` IS the authored truth, so the SHOW edge has
+  // nothing to restore FROM — the adapter re-renders its own tree there.
+  // Hiding wins over everything: nothing in a hidden world renders.
+  for (const obj of objectMap.values()) obj.visible = false;
+}
+
+/**
+ * The background an editor viewport with NO authored environment shows. A
+ * single shared instance so the per-notify re-apply below never allocates.
+ */
+const HIDDEN_WORLD_BACKGROUND = new THREE.Color('#aaaaaa');
+
+/**
+ * The scene-level half of the eye: `applyRootHiddenVisibility` above only
+ * covers entity `Object3D`s (the `objectMap`), but a three world also
+ * renders things that live directly on the `THREE.Scene` — the authored
+ * `background` color/skybox, `fog`, IBL `environment`, and the
+ * `envObject`-tagged ambient light `applyEnvironment` adds. None of those are
+ * entities, so without this function hiding the world leaves the viewport
+ * painted in the world's background color — looking exactly like "the eye
+ * didn't work".
+ *
+ * Same recompute-don't-remember contract as above: this only ever writes the
+ * SUPPRESSED state, idempotently, and callers invoke it on every notify while
+ * the world is hidden (an inspector environment edit mid-hide re-paints the
+ * authored values via `_applyEnvironment` — the very next notify re-suppresses
+ * them here). The restore path is `EditorShellStore.reapplyEnvironment()`, whose
+ * truth is `_sceneMeta.environment` — never a snapshot taken here.
+ *
+ * Post-processing (bloom/vignette) is the composer's half: `the world root's stage`'s
+ * `rebuildComposer` passes `undefined` instead of `store.environment` while
+ * the world is hidden; `editor-viewport.ts` bumps `composerVersion` (via
+ * `reapplyEnvironment`) on both hide/show edges so that rebuild actually runs.
+ */
+export function suppressRootEnvironment(scene: THREE.Scene): void {
+  scene.background = HIDDEN_WORLD_BACKGROUND;
+  scene.fog = null;
+  scene.environment = null;
+  scene.traverse((obj) => {
+    if (getUserData(obj, 'envObject')) obj.visible = false;
+  });
+}
+
+/**
+ * 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: EditorShellStore): 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);
+}

package/src/authoring/world-pan-state.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared DOM-world canvas transform (spec27 §8 "space-pan" row, D4 rebuild) — a
+ * module-level subscribable singleton (mirrors `eyedropper-session.ts`'s "bare
+ * singleton + own listener set" shape) holding the CURRENT SHARED pan + zoom
+ * applied, in LOCKSTEP, to both every design-time world-layer host
+ * (`design-time-layers.ts`'s `createLayerElement`-produced react/pixi layers)
+ * and `RootSelectionOverlay`'s visual-chrome wrapper. Its independent input
+ * sibling deliberately remains untransformed and covers the full viewport.
+ *
+ * SOUNDNESS (why lockstep preserves the "zero-correction" host-relative rect
+ * invariant `RootSelectionOverlay.tsx`'s own doc comment establishes):
+ * `RectProvider.rect(id)` is computed as `el.getBoundingClientRect()` MINUS
+ * the owning world's own root/host `getBoundingClientRect()`
+ * (`react-world-authoring-adapter.ts`'s `toHostRelative`/`hostRect` — `this
+ * .root` IS the exact layer div `createLayerElement` produces). A CSS
+ * `transform: translate()` applied directly to that host element shifts the
+ * host's OWN rendered rect AND every descendant's rendered rect by the
+ * IDENTICAL `(x, y)` delta — a rigid subtree translation — so the
+ * subtraction is invariant under pan: `rect(id)` returns the SAME
+ * host-relative numbers at any pan offset, unmodified, with no pan-awareness
+ * needed in `inspect.ts`'s geometry math or the overlay chrome consumers.
+ * Zoom scales both measured rectangles; `toHostRelative` divides their
+ * offsets and dimensions by the shared zoom before exposing authored-space
+ * geometry, while `RootSelectionOverlay.toHostLocal` performs the inverse
+ * for pointer gestures. `PickProvider.pick` needs no changes — it
+ * hit-tests real rendered rects against the real client cursor position,
+ * both of which already reflect the applied transform natively.
+ *
+ * Applying the exact SAME transform to `RootSelectionOverlay`'s own visual-
+ * chrome wrapper (a SIBLING of every world-layer host inside the SAME
+ * `the world root's stage` containerRef parent — see that file's own mount-site doc
+ * comment) shifts and scales the overlay by the identical transform — so
+ * drawing a chrome element at `rect(id)`'s authored coordinates lands it at the
+ * SAME screen position as the panned live element it describes. This is the
+ * entire "lockstep" contract: every consumer on both sides of the pan reads
+ * ONE shared value (`getRootPan()`) and applies it through the ONE shared
+ * pure helper (`panTransformValue`) — never two independently-computed
+ * transforms that could drift.
+ */
+
+export interface RootPan {
+  readonly x: number;
+  readonly y: number;
+  readonly zoom: number;
+}
+
+const ZERO_PAN: RootPan = { x: 0, y: 0, zoom: 1 };
+
+/**
+ * One document camera over a 2D authoring plane.
+ *
+ * DOM component boards still use the historical shared instance exported
+ * below. A native canvas Scene creates its own instance, because a scene
+ * camera and a component-board camera are different documents and must not
+ * inherit one another's pose merely because both happen to be 2D.
+ */
+export interface RootViewController {
+  get(): RootPan;
+  setView(x: number, y: number, zoom: number): void;
+  setPan(x: number, y: number): void;
+  setZoom(zoom: number): void;
+  reset(): void;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createRootViewController(initial: RootPan = ZERO_PAN): RootViewController {
+  let current: RootPan = initial;
+  const subscribers = new Set<() => void>();
+  const notifySubscribers = (): void => {
+    for (const listener of subscribers) listener();
+  };
+  return {
+    get: () => current,
+    setView: (x, y, zoom) => {
+      const nextZoom = Math.min(4, Math.max(0.1, zoom));
+      if (current.x === x && current.y === y && current.zoom === nextZoom) return;
+      current = { x, y, zoom: nextZoom };
+      notifySubscribers();
+    },
+    setPan: (x, y) => {
+      const nextZoom = current.zoom;
+      if (current.x === x && current.y === y) return;
+      current = { x, y, zoom: nextZoom };
+      notifySubscribers();
+    },
+    setZoom: (zoom) => {
+      const nextZoom = Math.min(4, Math.max(0.1, zoom));
+      if (current.zoom === nextZoom) return;
+      current = { x: current.x, y: current.y, zoom: nextZoom };
+      notifySubscribers();
+    },
+    reset: () => {
+      if (current.x === 0 && current.y === 0 && current.zoom === 1) return;
+      current = ZERO_PAN;
+      notifySubscribers();
+    },
+    subscribe: (listener) => {
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    },
+  };
+}
+
+let _pan: RootPan = ZERO_PAN;
+const listeners = new Set<() => void>();
+
+/** The historical DOM-board camera, exposed as a controller for generic
+ * navigation/overlay code. Existing function exports below remain the
+ * compatibility surface for board-specific callers. */
+export const sharedRootViewController: RootViewController = {
+  get: () => getRootPan(),
+  setView: (x, y, zoom) => setRootView(x, y, zoom),
+  setPan: (x, y) => setRootPan(x, y),
+  setZoom: (zoom) => setRootZoom(zoom),
+  reset: () => resetRootPan(),
+  subscribe: (listener) => subscribeRootPan(listener),
+};
+
+function notify(): void {
+  for (const l of listeners) l();
+}
+
+/** The current shared canvas transform; x/y are CSS px and zoom is unitless. */
+export function getRootPan(): RootPan {
+  return _pan;
+}
+
+/** Set the complete shared canvas transform in one subscriber notification. */
+export function setRootView(x: number, y: number, zoom: number): void {
+  const nextZoom = Math.min(4, Math.max(0.1, zoom));
+  if (_pan.x === x && _pan.y === y && _pan.zoom === nextZoom) return;
+  _pan = { x, y, zoom: nextZoom };
+  notify();
+}
+
+/** Set the shared pan translate to an absolute `(x, y)`. */
+export function setRootPan(x: number, y: number): void {
+  setRootView(x, y, _pan.zoom);
+}
+
+/** Set the shared canvas zoom while preserving its current pan. */
+export function setRootZoom(zoom: number): void {
+  setRootView(_pan.x, _pan.y, zoom);
+}
+
+/** Set the shared pan translate by a RELATIVE `(dx, dy)` — a convenience
+ *  wrapper over `setRootPan` (not used by `RootSelectionOverlay`'s own
+ *  space-drag, which composes onto a captured drag-start snapshot instead —
+ *  see its own doc comment — but kept here as the natural pure counterpart
+ *  for any future incremental caller, e.g. a nudge-pan keybinding). */
+export function panRootBy(dx: number, dy: number): void {
+  setRootPan(_pan.x + dx, _pan.y + dy);
+}
+
+/** Reset pan to `(0, 0)` and zoom to 100% — called on a world-layer remount (`design-time-
+ *  layers.ts`'s `mountDesignTimeLayers`, invoked on initial edit-mode install
+ *  AND every acknowledged edit-mode rebuild), so switching/reloading the active
+ *  world set never leaves a stale pan offset applied over a DIFFERENT layer
+ *  stack. A no-op (no `notify()`) when already at rest, so a fresh session
+ *  never fires a spurious subscriber tick. */
+export function resetRootPan(): void {
+  if (_pan.x === 0 && _pan.y === 0 && _pan.zoom === 1) return;
+  _pan = ZERO_PAN;
+  notify();
+}
+
+/** Subscribe to canvas-transform changes — both `design-time-layers.ts` (imperative DOM
+ *  style writes) and `RootSelectionOverlay` (`useSyncExternalStore`) bind
+ *  this so every lockstep mount point re-applies the SAME new value the
+ *  instant it changes. */
+export function subscribeRootPan(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * The ONE shared CSS `transform` value both visual lockstep mount points apply —
+ * pure, so a unit test can assert the world-layer host and the overlay
+ * wrapper are handed byte-identical strings for any given pan (the actual
+ * "lockstep" proof). `undefined` at rest `(0, 0)` so neither mount point ever
+ * carries a no-op `transform: translate(0px, 0px)` — keeps every pre-pan
+ * pixel-position snapshot (the full 27x suite, pinned at pan=0) byte-identical
+ * to its pre-this-feature output.
+ */
+export function panTransformValue(pan: RootPan): string | undefined {
+  if (pan.x === 0 && pan.y === 0 && pan.zoom === 1) return undefined;
+  if (pan.zoom === 1) return `translate(${pan.x}px, ${pan.y}px)`;
+  if (pan.x === 0 && pan.y === 0) return `scale(${pan.zoom})`;
+  return `translate(${pan.x}px, ${pan.y}px) scale(${pan.zoom})`;
+}
+
+/** Test-only reset (mirrors `eyedropper-session.ts`'s/`world-session-
+ *  state.ts`'s identical helpers) — drops pan + every subscriber so unit
+ *  tests don't leak state across cases. */
+export function _resetRootPanStateForTest(): void {
+  _pan = ZERO_PAN;
+  listeners.clear();
+}

package/src/authoring/world-session-state.ts

@@ -0,0 +1,101 @@
+/**
+ * World session state (B1) — a module-level subscribable singleton (same shape as
+ * `./mount-failure-report.ts`: a bare get/set slot, no subscribe of its own — every
+ * caller that mutates it follows up with `store.notifyIngestEdit()`, which every
+ * panel already re-renders off via `useSyncExternalStore(store.subscribe, …)`)
+ * holding THREE session-local, per-worldId toggles that are NEVER
+ * serialized/persisted (D9: "eye = session-local viewport visibility, never
+ * serialized" — generalized here to all three, none of which is an authored
+ * property):
+ *
+ *  - `hidden` — the eye (A2/D9). LIFTED out of `GameHierarchy.tsx`'s former
+ *    local `useState<Set<string>> hiddenRootIds` (module-private React state
+ *    the design-time layer stack could never see) so `design-time-layers.ts`
+ *    can hide/show a world's actual DOM layer, not just dim its hierarchy row.
+ *  - `interactive` — forwards real pointer events to the layer (for testing
+ *    hover/press states at design time); off by default (`pointer-events:none`
+ *    is the layer's resting state — see `design-time-layers.ts`).
+ *  - `pickLock` — stored here for B4 to consume (layered viewport picking,
+ *    D12): a pick-locked layer is skipped by the topmost-first pick walk.
+ *    B1 only stores/exposes the toggle; nothing reads it yet.
+ *
+ * Keyed by the RAW manifest world id (`CompositeChild.worldId` /
+ * `ResolvedAdapterRoot.id`) — the SAME id `design-time-layers.ts` gets from
+ * `composite.childAdapters()`, NOT the composite's synthetic `world:<id>`
+ * group-node id. `GameHierarchy.tsx` (whose rows ARE keyed by the group-node
+ * id) resolves the raw worldId via `compositeGroupBadge`'s `worldId` field
+ * before calling into this module — see that file's row component.
+ *
+ * A process-lifetime singleton (not project-scoped): switching projects
+ * within the same tab does not reset these toggles. That's a deliberate
+ * relaxation of the former per-mount-React-state behavior (which reset on
+ * every `GameHierarchy` remount) — "session-local" here means "this browser
+ * tab's session", matching D9's own framing; nothing depends on a
+ * project-switch reset.
+ */
+
+export interface RootSessionState {
+  readonly hidden: boolean;
+  readonly interactive: boolean;
+  readonly pickLock: boolean;
+}
+
+const DEFAULT_STATE: RootSessionState = { hidden: false, interactive: false, pickLock: false };
+
+const _states = new Map<string, RootSessionState>();
+
+function get(worldId: string): RootSessionState {
+  return _states.get(worldId) ?? DEFAULT_STATE;
+}
+
+function patch(worldId: string, partial: Partial<RootSessionState>): void {
+  _states.set(worldId, { ...get(worldId), ...partial });
+}
+
+/** The eye (A2/D9): true while `worldId`'s design-time layer is hidden. */
+export function isRootHidden(worldId: string): boolean {
+  return get(worldId).hidden;
+}
+
+export function setRootHidden(worldId: string, hidden: boolean): void {
+  patch(worldId, { hidden });
+}
+
+export function toggleRootHidden(worldId: string): void {
+  setRootHidden(worldId, !isRootHidden(worldId));
+}
+
+/** True while `worldId`'s layer forwards real pointer events (design-time
+ *  hover/press testing) instead of its resting `pointer-events:none`. */
+export function isRootInteractive(worldId: string): boolean {
+  return get(worldId).interactive;
+}
+
+export function setRootInteractive(worldId: string, interactive: boolean): void {
+  patch(worldId, { interactive });
+}
+
+export function toggleRootInteractive(worldId: string): void {
+  setRootInteractive(worldId, !isRootInteractive(worldId));
+}
+
+/** B4 will read this to skip a layer in the topmost-first pick walk; B1 only
+ *  stores/exposes the toggle. */
+export function isRootPickLocked(worldId: string): boolean {
+  return get(worldId).pickLock;
+}
+
+export function setRootPickLock(worldId: string, pickLock: boolean): void {
+  patch(worldId, { pickLock });
+}
+
+export function toggleRootPickLock(worldId: string): void {
+  setRootPickLock(worldId, !isRootPickLocked(worldId));
+}
+
+/** Test-only: drop every world's session state back to defaults so unit
+ *  tests don't leak toggles across cases (this module is a process-lifetime
+ *  singleton — see the header comment). */
+export function _resetRootSessionStateForTest(): void {
+  _states.clear();
+}