@volter/editor-core 0.5.57

package/src/authoring/provenance.ts

@@ -0,0 +1,99 @@
+/**
+ * Seam-level provenance resolution (spec 29 §5): which {@link
+ * AuthoringProvenance} governs a given hierarchy node. Provenance is declared
+ * once per adapter and rendered at the seam (world group row / panel header);
+ * affordance code also reads it for the REASON string on a disabled operation
+ * ("the subject is present but the operation isn't" — the complement of spec
+ * 28's hide-when-absent rule).
+ *
+ * Rule zero: roots are resolved by ASKING the composite (`groupNodeId` /
+ * `ownerOf`), never by decoding adapter-minted id strings here.
+ */
+import type { AuthoringAdapter, AuthoringProvenance } from '@volter/editor-project/adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+
+/** Resolve the concrete adapter that owns a real hierarchy node. Synthetic
+ * composite rows and unknown ids have no owner. */
+export function authoringAdapterForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter;
+  const worldId = adapter.ownerOf(nodeId);
+  if (worldId === null) return null;
+  return adapter.childAdapters().find((child) => child.worldId === worldId)?.adapter ?? null;
+}
+
+/**
+ * The adapter GOVERNING `nodeId` under the ACTIVE adapter — the one entitled to
+ * answer questions *about that node*: the owning child inside a composite, the
+ * world's own child for a `world:<id>` GROUP row, the adapter itself when it
+ * isn't a composite. `null` when the composite recognizes no owner (a synthetic
+ * organization row, an unknown id).
+ *
+ * Use this — not the active adapter — for any PER-NODE capability check inside
+ * a composite. `CompositeAuthoringAdapter`'s provider fields are unconditional
+ * routing objects: reading presence off the composite is `true` for every node
+ * in every multi-root project, including nodes whose owner exposes no such
+ * provider at all and nodes nobody owns (where `route()` falls back to the
+ * FIRST child). That has the editor assert a capability claim on a child's
+ * behalf — exactly the fabrication the anti-shim rule forbids. Ask the
+ * governing adapter instead, and treat "no governing adapter" as "nobody
+ * declared anything".
+ *
+ * Distinct from {@link authoringAdapterForNode}, which resolves REAL hierarchy
+ * nodes only and is deliberately `null` for a group row.
+ */
+export function governingAdapterForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter;
+  for (const child of adapter.childAdapters()) {
+    if (adapter.groupNodeId(child.worldId) === nodeId) return child.adapter;
+  }
+  return authoringAdapterForNode(adapter, nodeId);
+}
+
+/**
+ * The provenance governing `nodeId` under the ACTIVE adapter: the owning
+ * child's declaration inside a composite (a `world:<id>` group row resolves
+ * to that world's own child), the adapter's own declaration otherwise.
+ * `null` when nothing was declared (the shell shows no badge and falls back
+ * to a generic reason — never fabricates a claim).
+ */
+export function provenanceForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringProvenance | null {
+  return governingAdapterForNode(adapter, nodeId)?.provenance ?? null;
+}
+
+/** The reason string for an affordance that is present but unavailable —
+ *  the adapter's own explanation when it declared one, a plain honest
+ *  fallback when it didn't. */
+export function unavailableReason(provenance: AuthoringProvenance | null): string {
+  return provenance?.detail ?? "Not supported by this world's adapter.";
+}
+/**
+ * WHERE this adapter's truth is written, as one human-readable string.
+ *
+ * One owner, because two surfaces read it and they must agree: the Hierarchy
+ * panel publishes it as its scene name (`components/GameHierarchy.tsx`), and
+ * the Inspector's identity row PRINTS it as the datablock line
+ * (`inspection/model.ts`'s `InspectionDocumentLine`) now that the tree's own
+ * breadcrumb row is gone. When the two were computed separately the
+ * Inspector's half silently showed nothing for every adapter that answers
+ * through its document root instead of a persistence provider — which is the
+ * ordinary three-source case.
+ *
+ * `null` for a session with no single destination (a composite, whose worlds'
+ * destinations differ) — the same silence its `provenance` keeps.
+ */
+export function authoringDestination(adapter: AuthoringAdapter): string | null {
+  const persisted = adapter.persistence?.destination;
+  if (persisted) return persisted;
+  const roots = adapter.hierarchy.roots();
+  const documentRoot = roots.length === 1 && roots[0]?.role === 'document' ? roots[0] : null;
+  return documentRoot?.secondaryLabel ?? documentRoot?.label ?? null;
+}

package/src/authoring/quarks-particle-systems.ts

@@ -0,0 +1,19 @@
+import type * as THREE from 'three';
+import type { ParticleSystem } from 'three.quarks';
+
+/** Native three.quarks systems owned by ParticleEmitter nodes in this graph.
+ * Detection is structural because a project can bring its own compatible
+ * three.quarks module instance; `instanceof` would make that ordinary case
+ * disappear across package boundaries. */
+export function quarksParticleSystems(root: THREE.Object3D): ParticleSystem[] {
+  const systems: ParticleSystem[] = [];
+  const seen = new Set<ParticleSystem>();
+  root.traverse((object) => {
+    if (object.type !== 'ParticleEmitter') return;
+    const system = (object as THREE.Object3D & { system?: ParticleSystem }).system;
+    if (!system || typeof system.getRendererSettings !== 'function' || seen.has(system)) return;
+    seen.add(system);
+    systems.push(system);
+  });
+  return systems;
+}

package/src/authoring/react-canvas-navigation.ts

@@ -0,0 +1,255 @@
+import { type RootPan, type RootViewController, sharedRootViewController } from './world-pan-state';
+
+const MIN_ZOOM = 0.1;
+const MAX_ZOOM = 4;
+const ZOOM_SENSITIVITY = 0.002;
+const SECONDARY_DRAG_THRESHOLD_PX = 4;
+
+export interface ReactCanvasWheelInput {
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly deltaMode: number;
+  readonly ctrlKey: boolean;
+  readonly metaKey: boolean;
+  readonly shiftKey: boolean;
+  readonly bounds: Pick<DOMRect, 'left' | 'top' | 'width' | 'height'>;
+}
+
+function deltaPixels(delta: number, mode: number, pageSize: number): number {
+  if (mode === 1) return delta * 16; // WheelEvent.DOM_DELTA_LINE
+  if (mode === 2) return delta * pageSize; // WheelEvent.DOM_DELTA_PAGE
+  return delta;
+}
+
+/** Resolve one component-board wheel gesture without touching global state. */
+export function resolveReactCanvasWheel(view: RootPan, input: ReactCanvasWheelInput): RootPan {
+  let deltaX = deltaPixels(input.deltaX, input.deltaMode, input.bounds.width);
+  let deltaY = deltaPixels(input.deltaY, input.deltaMode, input.bounds.height);
+
+  if (input.ctrlKey || input.metaKey) {
+    const zoom = Math.min(
+      MAX_ZOOM,
+      Math.max(MIN_ZOOM, view.zoom * Math.exp(-deltaY * ZOOM_SENSITIVITY)),
+    );
+    const pointerX = input.clientX - input.bounds.left;
+    const pointerY = input.clientY - input.bounds.top;
+    const worldX = (pointerX - view.x) / view.zoom;
+    const worldY = (pointerY - view.y) / view.zoom;
+    return {
+      x: pointerX - worldX * zoom,
+      y: pointerY - worldY * zoom,
+      zoom,
+    };
+  }
+
+  // Figma treats a shifted vertical mouse wheel as horizontal movement.
+  // Trackpads already provide deltaX, so preserve that richer input.
+  if (input.shiftKey && deltaX === 0) {
+    deltaX = deltaY;
+    deltaY = 0;
+  }
+  return { x: view.x - deltaX, y: view.y - deltaY, zoom: view.zoom };
+}
+
+/** Resolve the wheel gesture for a native 2D Scene. Like the Three Scene and
+ * Godot's 2D workspace, the wheel changes the spatial camera's zoom around
+ * the cursor; panning belongs to middle-drag, right-drag, or Space-drag. This is
+ * intentionally different from the component board above, where a wheel pans
+ * the layout and a modifier-wheel zooms it. */
+export function resolveCanvasSceneWheel(view: RootPan, input: ReactCanvasWheelInput): RootPan {
+  const deltaY = deltaPixels(input.deltaY, input.deltaMode, input.bounds.height);
+  const zoom = Math.min(
+    MAX_ZOOM,
+    Math.max(MIN_ZOOM, view.zoom * Math.exp(-deltaY * ZOOM_SENSITIVITY)),
+  );
+  const pointerX = input.clientX - input.bounds.left;
+  const pointerY = input.clientY - input.bounds.top;
+  const worldX = (pointerX - view.x) / view.zoom;
+  const worldY = (pointerY - view.y) / view.zoom;
+  return {
+    x: pointerX - worldX * zoom,
+    y: pointerY - worldY * zoom,
+    zoom,
+  };
+}
+
+function isNavigationChrome(target: EventTarget | null): boolean {
+  return (
+    target instanceof Element &&
+    target.closest('[data-vgai-canvas-navigation-ignore="true"]') !== null
+  );
+}
+
+/**
+ * Install viewport-sized navigation for a React design canvas. This stays on
+ * the untransformed document container, unlike authoring chrome that follows
+ * the world transform, so navigation remains available after fit/zoom.
+ */
+function installCanvasNavigation(
+  container: HTMLElement,
+  view: RootViewController,
+  resolveWheel: (view: RootPan, input: ReactCanvasWheelInput) => RootPan,
+  options: { readonly rightDragPans?: boolean } = {},
+): () => void {
+  let drag: {
+    readonly pointerId: number;
+    readonly button: 1 | 2;
+    readonly startClientX: number;
+    readonly startClientY: number;
+    readonly startPan: RootPan;
+    moved: boolean;
+  } | null = null;
+  let suppressNextContextMenu = false;
+  let previousInteractionCursor = '';
+
+  const interactionLayer = (): HTMLElement | null =>
+    container.querySelector<HTMLElement>('[data-testid="world-selection-overlay-interaction"]');
+
+  const setDraggingAppearance = (dragging: boolean): void => {
+    container.dataset['canvasPanning'] = dragging ? 'true' : 'false';
+    container.style.cursor = dragging ? 'grabbing' : '';
+    const interaction = interactionLayer();
+    if (!interaction) return;
+    if (dragging) {
+      previousInteractionCursor = interaction.style.cursor;
+      interaction.style.cursor = 'grabbing';
+    } else {
+      interaction.style.cursor = previousInteractionCursor;
+    }
+  };
+
+  const onPointerMove = (event: PointerEvent): void => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    // PointerEvent's button mask is platform-independent: 4 is middle, 2 is
+    // secondary/right. Windows can drop pointerup around native auto-scroll
+    // or a window boundary, so stop as soon as the active bit disappears.
+    const pressedButtonMask = drag.button === 1 ? 4 : 2;
+    if ((event.buttons & pressedButtonMask) === 0) {
+      endDrag(event);
+      return;
+    }
+    const deltaX = event.clientX - drag.startClientX;
+    const deltaY = event.clientY - drag.startClientY;
+    if (!drag.moved) {
+      if (Math.hypot(deltaX, deltaY) <= SECONDARY_DRAG_THRESHOLD_PX) return;
+      drag.moved = true;
+      setDraggingAppearance(true);
+    }
+    view.setPan(drag.startPan.x + deltaX, drag.startPan.y + deltaY);
+  };
+
+  const endDrag = (event: PointerEvent): void => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    const pointerId = drag.pointerId;
+    if (drag.button === 2 && drag.moved) suppressNextContextMenu = true;
+    drag = null;
+    setDraggingAppearance(false);
+    if (container.hasPointerCapture?.(pointerId)) container.releasePointerCapture(pointerId);
+    window.removeEventListener('pointermove', onPointerMove);
+    window.removeEventListener('pointerup', endDrag);
+    window.removeEventListener('pointercancel', endDrag);
+  };
+
+  const onPointerDown = (event: PointerEvent): void => {
+    const isMiddleButton = event.button === 1;
+    const isRightButton = options.rightDragPans === true && event.button === 2;
+    if ((!isMiddleButton && !isRightButton) || isNavigationChrome(event.target)) return;
+    if (isRightButton) suppressNextContextMenu = false;
+    event.preventDefault();
+    // A secondary press is shared with the selection overlay: navigation owns
+    // movement, while the overlay owns the stationary overlap menu. Let that
+    // one event continue so both can measure the same press; middle drag is
+    // unambiguous and remains navigation-only.
+    if (isMiddleButton) event.stopPropagation();
+    drag = {
+      pointerId: event.pointerId,
+      button: event.button as 1 | 2,
+      startClientX: event.clientX,
+      startClientY: event.clientY,
+      startPan: view.get(),
+      // Middle-drag is unambiguous and retains its immediate response. A
+      // secondary press waits for movement so a stationary secondary click
+      // remains the viewport's overlap/context menu.
+      moved: isMiddleButton,
+    };
+    // Pointer capture is the mouse-equivalent of a trackpad's uninterrupted
+    // gesture stream: middle-drag keeps panning across child frames and past
+    // the viewport edge, including on Windows where window-level move/up
+    // delivery is otherwise inconsistent around native auto-scroll.
+    container.setPointerCapture?.(event.pointerId);
+    setDraggingAppearance(isMiddleButton);
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('pointerup', endDrag);
+    window.addEventListener('pointercancel', endDrag);
+  };
+
+  const onMouseDown = (event: MouseEvent): void => {
+    // Prevent Chromium's native middle-button auto-scroll glyph.
+    if (event.button === 1 && !isNavigationChrome(event.target)) event.preventDefault();
+  };
+
+  const onContextMenu = (event: MouseEvent): void => {
+    if (options.rightDragPans !== true) return;
+    const activeRightDrag = drag?.button === 2 && drag.moved;
+    if (!activeRightDrag && !suppressNextContextMenu) return;
+    suppressNextContextMenu = false;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  const onWheel = (event: WheelEvent): void => {
+    if (isNavigationChrome(event.target)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const next = resolveWheel(view.get(), {
+      clientX: event.clientX,
+      clientY: event.clientY,
+      deltaX: event.deltaX,
+      deltaY: event.deltaY,
+      deltaMode: event.deltaMode,
+      ctrlKey: event.ctrlKey,
+      metaKey: event.metaKey,
+      shiftKey: event.shiftKey,
+      bounds: container.getBoundingClientRect(),
+    });
+    view.setView(next.x, next.y, next.zoom);
+  };
+
+  container.addEventListener('pointerdown', onPointerDown, true);
+  container.addEventListener('lostpointercapture', endDrag, true);
+  container.addEventListener('mousedown', onMouseDown, true);
+  container.addEventListener('contextmenu', onContextMenu, true);
+  container.addEventListener('wheel', onWheel, { capture: true, passive: false });
+  return () => {
+    drag = null;
+    setDraggingAppearance(false);
+    container.removeEventListener('pointerdown', onPointerDown, true);
+    container.removeEventListener('lostpointercapture', endDrag, true);
+    container.removeEventListener('mousedown', onMouseDown, true);
+    container.removeEventListener('contextmenu', onContextMenu, true);
+    container.removeEventListener('wheel', onWheel, true);
+    window.removeEventListener('pointermove', onPointerMove);
+    window.removeEventListener('pointerup', endDrag);
+    window.removeEventListener('pointercancel', endDrag);
+  };
+}
+
+/** Component-board navigation: wheel pans; modifier-wheel zooms. */
+export function installReactCanvasNavigation(
+  container: HTMLElement,
+  view: RootViewController = sharedRootViewController,
+): () => void {
+  return installCanvasNavigation(container, view, resolveReactCanvasWheel);
+}
+
+/** Native 2D Scene navigation: wheel zooms; middle/right/Space drag pans. */
+export function installCanvasSceneNavigation(
+  container: HTMLElement,
+  view: RootViewController,
+): () => void {
+  return installCanvasNavigation(container, view, resolveCanvasSceneWheel, {
+    rightDragPans: true,
+  });
+}

package/src/authoring/react-design-canvas-style.ts

@@ -0,0 +1,20 @@
+/**
+ * React design documents deliberately use an opaque, theme-independent canvas.
+ * Glass theme surface tokens are translucent and would let the chrome's
+ * backdrop frost turn the fine dot grid into a pale blur. These literals describe the
+ * semantic preview media itself, like an alpha checkerboard, rather than editor
+ * chrome colors.
+ */
+export const REACT_DESIGN_CANVAS_COLOR = '#191c22';
+export const REACT_DESIGN_CANVAS_DOT = 'rgba(255, 255, 255, 0.2)';
+export const REACT_STORY_TRANSPARENCY_BASE = '#20242a';
+export const REACT_STORY_TRANSPARENCY_TILE = '#2d323a';
+
+export function reactStoryTransparencyBackground(): string {
+  return (
+    `linear-gradient(45deg, ${REACT_STORY_TRANSPARENCY_TILE} 25%, transparent 25%, ` +
+    `transparent 75%, ${REACT_STORY_TRANSPARENCY_TILE} 75%), ` +
+    `linear-gradient(45deg, ${REACT_STORY_TRANSPARENCY_TILE} 25%, transparent 25%, ` +
+    `transparent 75%, ${REACT_STORY_TRANSPARENCY_TILE} 75%)`
+  );
+}