@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/editor-viewport.ts

@@ -9,6 +9,18 @@ import { BatchedRenderer } from 'three.quarks';
 import { getActiveAuthoring } from './authoring/active-adapter';
 import { pickTopmost } from './authoring/layered-pick';
 import { setViewportPickContext } from './authoring/viewport-pick-context';
+import {
+  isViewportToolContextVisible,
+  resolveViewportToolContext,
+} from './authoring/viewport-tool-context';
+import {
+  applyWorldHiddenVisibility,
+  isThreejsSurfaceVisible,
+  resolveFocusedViewportWorldId,
+  suppressWorldEnvironment,
+} from './authoring/world-hidden-viewport';
+import { isWorldHidden } from './authoring/world-session-state';
+import { themeVars, zIndex } from './design-system';
 import { downloadOnlineAsset, getDownloadedAssetPath, getOnlineAssetFiles } from './editor-api';
 import { EDITOR_LAYER } from './editor-layers';
 import type { EditorStore } from './editor-store';
@@ -37,6 +49,23 @@ const VC_DIRS: THREE.Vector3[] = [
   /* 5 -Z */ new THREE.Vector3(0, 0, -1),
 ];
 
+/**
+ * Godot axis color RGB triples (X/Y/Z) — EDITOR-STYLE-AUDIT.md V-13:
+ * previously defined independently, from scratch, in BOTH
+ * `_initOrientationGizmo` (the view-cube) and `_patchGizmo` (the transform
+ * gizmo), each with its own identical "Godot axis colors" comment. Hoisted
+ * to one module-level constant so a future retouch of one can't silently
+ * drift from the other. Kept as plain `[r,g,b]` triples rather than shared
+ * `THREE.Color` instances — call sites construct their own `new
+ * THREE.Color(...)` from these, so nothing here can be mutated in place by
+ * one call site (materials, sprite canvases) and leak into the other.
+ */
+const GODOT_AXIS_COLOR_RGB: readonly [number, number, number][] = [
+  [0.96, 0.2, 0.32], // X
+  [0.53, 0.84, 0.01], // Y
+  [0.16, 0.55, 0.96], // Z
+];
+
 export class EditorViewport {
   readonly camera: THREE.PerspectiveCamera;
   readonly orbitControls: OrbitControls;
@@ -58,6 +87,9 @@ export class EditorViewport {
   private _store: EditorStore;
   private _objectMap = new Map<string, THREE.Object3D>();
   private _canvas: HTMLCanvasElement;
+  /** Camera input belongs to the whole viewport surface, including authoring
+   * overlays rendered above the WebGL canvas. */
+  private _interactionElement: HTMLElement;
   private _pointerDownPos = new THREE.Vector2();
   private _skipNextSync = false;
 
@@ -83,6 +115,15 @@ export class EditorViewport {
    *  during a transform drag, which notifies per frame but changes none of them). */
   private _lastGizmoObjectMap: Map<string, THREE.Object3D> | null = null;
   private _lastGizmoSig = '';
+  /** Previous world-hidden eye state — edge detection for environment suppress/restore. */
+  private _lastWorldHidden = false;
+  /**
+   * Spec 28 — recomputed from surface visibility AND selection ownership on every
+   * `syncFromStore`; read by the per-frame render hooks (`renderViewCube`,
+   * `renderCameraPreview`) and the view-cube click path, which run between
+   * notifies and must not re-walk the composite 60×/s.
+   */
+  private _threejsToolContextActive = false;
   private _vcRaycaster = new THREE.Raycaster();
 
   // -- Asset drop --
@@ -147,8 +188,14 @@ export class EditorViewport {
   private _flyEuler = new THREE.Euler(0, 0, 0, 'YXZ');
   private _rightMouseDown = false;
 
-  constructor(canvas: HTMLCanvasElement, scene: THREE.Scene, store: EditorStore) {
+  constructor(
+    canvas: HTMLCanvasElement,
+    scene: THREE.Scene,
+    store: EditorStore,
+    interactionElement: HTMLElement = canvas,
+  ) {
     this._canvas = canvas;
+    this._interactionElement = interactionElement;
     this._scene = scene;
     this._store = store;
 
@@ -183,7 +230,7 @@ export class EditorViewport {
     scene.add(this.batchedRenderer);
 
     // OrbitControls – Unity-style: right-drag = orbit, middle-drag = pan, scroll = zoom
-    this.orbitControls = new OrbitControls(this.camera, canvas);
+    this.orbitControls = new OrbitControls(this.camera, interactionElement);
     this.orbitControls.enableDamping = true;
     this.orbitControls.dampingFactor = 0.1;
     this.orbitControls.mouseButtons = {
@@ -361,10 +408,10 @@ export class EditorViewport {
     // -- Fly camera input (right-click + WASD) --
     window.addEventListener('keydown', this._onFlyKeyDown);
     window.addEventListener('keyup', this._onFlyKeyUp);
-    canvas.addEventListener('pointerdown', this._onFlyPointerDown);
-    canvas.addEventListener('pointerup', this._onFlyPointerUp);
-    canvas.addEventListener('pointermove', this._onFlyPointerMove);
-    canvas.addEventListener('wheel', this._onFlyWheel, { passive: false });
+    interactionElement.addEventListener('pointerdown', this._onFlyPointerDown);
+    interactionElement.addEventListener('pointerup', this._onFlyPointerUp);
+    interactionElement.addEventListener('pointermove', this._onFlyPointerMove);
+    interactionElement.addEventListener('wheel', this._onFlyWheel, { passive: false });
 
     // Alt+Left-drag = orbit (Unity-style), via capture phase so it fires before OrbitControls
     canvas.addEventListener(
@@ -527,8 +574,22 @@ export class EditorViewport {
     this.transformControls.setRotationSnap(snap ? THREE.MathUtils.degToRad(vals.rotate) : null);
     this.transformControls.setScaleSnap(snap ? vals.scale : null);
 
-    // Grid visibility
-    this.grid.visible = this._store.showGrid;
+    // Spec 28 step 2 — visibility says a Three.js surface is painted;
+    // selection ownership says it is the native world the user is editing.
+    // The grid, view cube, camera preview, and transform gizmo require BOTH.
+    // Empty/organizational/cross-world selections deliberately leave only
+    // shell chrome rather than advertising an arbitrary coordinate system.
+    const toolContext = resolveViewportToolContext(
+      getActiveAuthoring(this._store),
+      this._store.selectedEntityIds,
+    );
+    this._threejsToolContextActive =
+      isThreejsSurfaceVisible(this._store) &&
+      isViewportToolContextVisible(this._store, toolContext) &&
+      toolContext?.kind === 'threejs';
+
+    // Grid visibility — the user's toggle, AND'd with the surface actually showing
+    this.grid.visible = this._store.showGrid && this._threejsToolContextActive;
 
     // The two passes below (apply gizmos + per-type helper/icon visibility) are
     // idempotent and O(total scene nodes). Their only inputs are the objectMap
@@ -536,11 +597,49 @@ export class EditorViewport {
     // transform drag/scrub (which still fires syncFromStore every frame). Gate
     // them on a cheap signature so a drag doesn't re-walk the whole graph 60×/s.
     const vis = this._store.helperVisibility;
-    const gizmoSig = `${this._objectMap.size}|${this._store.showHelpers}|${JSON.stringify(vis)}`;
+    // World-hidden eye (D9) folded into the SAME cheap signature/gate as the
+    // gizmo/helper passes below — see `world-hidden-viewport.ts`'s doc
+    // comment for why this must be recomputed from scratch on every rebuild
+    // (never a one-shot flip) and why folding it in here (rather than a
+    // separate always-on pass) is safe: the toggle itself
+    // (`GameHierarchy.tsx`'s `toggleWorldHidden` + `store.notifyIngestEdit()`)
+    // changes `hiddenWorldId`'s hidden state, which changes this signature,
+    // so it re-applies on the very next `syncFromStore()` call — exactly the
+    // same notify path that already re-triggers this whole method.
+    const hiddenWorldId = resolveFocusedViewportWorldId(this._store);
+    const hidden = hiddenWorldId !== null && isWorldHidden(hiddenWorldId);
+    // While hidden, re-apply on EVERY notify, not just signature changes: a
+    // SINGLE-entity rebuild (scene-sync `updateEntityPreview`) mutates the
+    // existing objectMap in place — same instance, same size, so the gate
+    // below never re-fires — while re-stamping the rebuilt object visible
+    // from its descriptor. Cost is one map walk per notify only while a
+    // world is actually hidden; the gated call below still handles the
+    // hide→show transition (restoring per-entity visibility).
+    if (hidden) applyWorldHiddenVisibility(this._objectMap, hiddenWorldId);
+    // Scene-LEVEL environment (background/skybox/fog/IBL/ambient — none of it
+    // in the objectMap) + the post-processing chain. Edge: both directions
+    // re-apply the authored environment from `_sceneMeta` truth and bump
+    // `composerVersion` (ViewportPanel's rebuild strips scene effects while
+    // hidden). While hidden: suppress on EVERY notify — same rationale as the
+    // per-notify `applyWorldHiddenVisibility` above, because an inspector
+    // environment edit mid-hide re-paints the authored values.
+    if (hidden !== this._lastWorldHidden) {
+      this._lastWorldHidden = hidden;
+      this._store.reapplyEnvironment();
+    }
+    if (hidden) suppressWorldEnvironment(this._scene);
+    const gizmoSig = `${this._objectMap.size}|${this._store.showHelpers}|${JSON.stringify(vis)}|${hiddenWorldId ?? ''}|${hidden}`;
     if (this._objectMap !== this._lastGizmoObjectMap || gizmoSig !== this._lastGizmoSig) {
       this._lastGizmoObjectMap = this._objectMap;
       this._lastGizmoSig = gizmoSig;
 
+      // Threejs roots have no DOM layer to `display:none` (unlike react/pixi
+      // — `design-time-layers.ts`'s `applySessionStyle`), so this is what
+      // actually makes a hidden threejs world's group-row eye hide its
+      // objects in THIS viewport. ABOVE the per-entity `visible` flag (ANDed
+      // in, never overwritten) — see `world-hidden-viewport.ts`.
+      applyWorldHiddenVisibility(this._objectMap, hiddenWorldId);
+
       // Ensure gizmos (icon billboards + wireframe helpers) exist on all objects.
       // Idempotent — needed for game scene objects created by the runtime without gizmos.
       for (const obj of this._objectMap.values()) {
@@ -557,6 +656,10 @@ export class EditorViewport {
           }
           if (!getUserData(child, 'editorHelper')) return;
           const type = getUserData(child, 'editorHelperType') as string | undefined;
+          if (type === 'skeletons') {
+            child.visible = vis.skeletons || Boolean(getUserData(child, 'skeletonEnabled'));
+            return;
+          }
           if (type && type in vis) {
             child.visible = vis[type as keyof typeof vis];
           } else {
@@ -570,8 +673,11 @@ export class EditorViewport {
       }
     }
 
-    // Attach gizmo based on pivot mode
-    const selectedId = this._store.selectedEntityId;
+    // Attach gizmo based on pivot mode. Spec 28: no gizmo without a visible
+    // threejs surface — this whole block re-derives per notify, so detaching
+    // here is self-healing (the un-hide notify re-attaches to the same
+    // selection with no extra bookkeeping).
+    const selectedId = this._threejsToolContextActive ? this._store.selectedEntityId : null;
     if (selectedId) {
       if (!this.transformControls.dragging) {
         if (this._store.pivotMode === 'median-point' && this._store.selectedEntityIds.size > 1) {
@@ -803,6 +909,7 @@ export class EditorViewport {
 
   /** Render the orientation gizmo overlaid in the top-right corner. */
   renderViewCube(renderer: THREE.WebGLRenderer): void {
+    if (!this._threejsToolContextActive) return; // spec 28 — no selected 3D context, no compass
     const w = renderer.domElement.clientWidth;
     const h = renderer.domElement.clientHeight;
     const size = this._vcSize;
@@ -833,6 +940,7 @@ export class EditorViewport {
 
   /** Render a small camera preview in the bottom-right corner if a camera entity is selected. */
   renderCameraPreview(renderer: THREE.WebGLRenderer): void {
+    if (!this._threejsToolContextActive) return; // spec 28 — no selected 3D context, no preview
     const selectedEntity = this._store.selectedEntity;
     if (!selectedEntity?.camera) return;
 
@@ -904,10 +1012,10 @@ export class EditorViewport {
     setViewportPickContext(null);
     window.removeEventListener('keydown', this._onFlyKeyDown);
     window.removeEventListener('keyup', this._onFlyKeyUp);
-    this._canvas.removeEventListener('pointerdown', this._onFlyPointerDown);
-    this._canvas.removeEventListener('pointerup', this._onFlyPointerUp);
-    this._canvas.removeEventListener('pointermove', this._onFlyPointerMove);
-    this._canvas.removeEventListener('wheel', this._onFlyWheel);
+    this._interactionElement.removeEventListener('pointerdown', this._onFlyPointerDown);
+    this._interactionElement.removeEventListener('pointerup', this._onFlyPointerUp);
+    this._interactionElement.removeEventListener('pointermove', this._onFlyPointerMove);
+    this._interactionElement.removeEventListener('wheel', this._onFlyWheel);
     this._canvas.removeEventListener('pointerdown', this._onPointerDown);
     this._canvas.removeEventListener('pointermove', this._onPointerMove);
     this._canvas.removeEventListener('pointerup', this._onPointerUp);
@@ -939,12 +1047,8 @@ export class EditorViewport {
     light.position.set(1, 2, 3);
     this._vcScene.add(light);
 
-    // Godot axis colors
-    const colors = [
-      new THREE.Color(0.96, 0.2, 0.32), // X
-      new THREE.Color(0.53, 0.84, 0.01), // Y
-      new THREE.Color(0.16, 0.55, 0.96), // Z
-    ];
+    // Godot axis colors (V-13 — see module-level `GODOT_AXIS_COLOR_RGB`)
+    const colors = GODOT_AXIS_COLOR_RGB.map(([r, g, b]) => new THREE.Color(r, g, b));
     const axes = [
       new THREE.Vector3(1, 0, 0),
       new THREE.Vector3(0, 1, 0),
@@ -1283,10 +1387,11 @@ export class EditorViewport {
 
   /** Recolor gizmo handles to Godot axis colors & shift plane geometry to meet at center. */
   private _patchGizmo(gizmoHelper: THREE.Object3D): void {
-    // Godot axis colors: Color(0.96,0.20,0.32), Color(0.53,0.84,0.01), Color(0.16,0.55,0.96)
-    const axisX = new THREE.Color(0.96, 0.2, 0.32);
-    const axisY = new THREE.Color(0.53, 0.84, 0.01);
-    const axisZ = new THREE.Color(0.16, 0.55, 0.96);
+    // Godot axis colors (V-13 — see module-level `GODOT_AXIS_COLOR_RGB`)
+    const [axisRgbX, axisRgbY, axisRgbZ] = GODOT_AXIS_COLOR_RGB;
+    const axisX = new THREE.Color(...axisRgbX!);
+    const axisY = new THREE.Color(...axisRgbY!);
+    const axisZ = new THREE.Color(...axisRgbZ!);
 
     // Handle color: axis handles use axis color, plane handles use normal-axis color
     const colorMap: Record<string, THREE.Color> = {
@@ -1591,12 +1696,16 @@ export class EditorViewport {
 
       if (!this._marqueeDiv) {
         this._marqueeDiv = document.createElement('div');
+        // V-12 — was the string `'999'` (a stray string literal in an
+        // otherwise-numeric z-index scale); now the canonical `zIndex.sticky`
+        // token (numeric `1000`, same absorbed tier as the old `999`/`1000`
+        // pair per the audit's own z-index reconciliation).
         Object.assign(this._marqueeDiv.style, {
           position: 'fixed',
-          border: '1px solid #579EFF',
-          background: 'rgba(87, 158, 255, 0.15)',
+          border: `1px solid ${themeVars.accent.default}`,
+          background: themeVars.accent.muted,
           pointerEvents: 'none',
-          zIndex: '999',
+          zIndex: zIndex.sticky,
         });
         document.body.appendChild(this._marqueeDiv);
       }
@@ -1653,6 +1762,16 @@ export class EditorViewport {
       for (const [id, obj] of this._objectMap) {
         // Skip locked entities in marquee selection
         if (this._store.isEntityLocked(id)) continue;
+        // Skip invisible entities — mirrors `raycastPick`'s single-click
+        // behavior for free (THREE.Raycaster's own `intersectObject` already
+        // stops descending into an `obj.visible === false` subtree, so a
+        // single click can never land on one). Marquee did its own screen-
+        // space rect test with no such check, so a world hidden via the
+        // group-row eye (`world-hidden-viewport.ts` — forces `obj.visible =
+        // false` for the whole world while hidden) stayed marquee-selectable
+        // even though it was invisible and unclickable. Also correctly skips
+        // an entity hidden via its OWN eye, for the same reason.
+        if (!obj.visible) continue;
         const screen = this._projectToScreen(obj);
         if (screen.x >= left && screen.x <= right && screen.y >= top && screen.y <= bottom) {
           hitIds.push(id);
@@ -1680,8 +1799,9 @@ export class EditorViewport {
     // Don't interfere with gizmo clicks
     if (this.transformControls.dragging) return;
 
-    // Check orientation gizmo click first
-    if (this._handleViewCubeClick(e)) return;
+    // Check orientation gizmo click first (spec 28 — the cube isn't rendered
+    // without a visible threejs surface, so it can't be clicked either)
+    if (this._threejsToolContextActive && this._handleViewCubeClick(e)) return;
 
     // D12 (B4) — topmost-first layered pick: the composite's non-threejs
     // children (react/pixi design-time layers) are tried topmost-first before
@@ -1720,13 +1840,19 @@ export class EditorViewport {
   private _showDropOverlay(): void {
     if (this._dropOverlay) return;
     const overlay = document.createElement('div');
+    // V-12 — the stray string `'5'` (below every named tier in the z-index
+    // scale) becomes the numeric `zIndex.base`, the lowest defined tier,
+    // preserving its relative order (still below the marquee's `zIndex.
+    // sticky` and every dropdown/menu). The semantic accent tokens reconcile this
+    // block's one-off `#579EFF`/`rgba(87,158,255,0.08)` onto the canonical
+    // accent tint per the audit's own §3 absorption list.
     Object.assign(overlay.style, {
       position: 'fixed',
       inset: '0',
       pointerEvents: 'none',
-      border: '2px dashed #579EFF',
-      background: 'rgba(87, 158, 255, 0.08)',
-      zIndex: '5',
+      border: `2px dashed ${themeVars.accent.default}`,
+      background: themeVars.accent.muted,
+      zIndex: zIndex.base,
     });
     document.body.appendChild(overlay);
     this._dropOverlay = overlay;
@@ -1787,7 +1913,7 @@ export class EditorViewport {
       const baseName = online.name.replace(/\.[^.]+$/, '');
 
       // Already downloaded? Create entity instantly, no placeholder needed.
-      const cachedPath = getDownloadedAssetPath(online.source, online.name);
+      const cachedPath = getDownloadedAssetPath(online.source, online.id);
       if (cachedPath) {
         this._store.addEntity(null, {
           id: crypto.randomUUID(),

package/src/entity-factory.ts

@@ -4,6 +4,7 @@ import { buildClipMap } from '@engine/animation/clip-map';
 // disposal-safe clone (own materials + `__sharedGeometry` tags) — the same
 // clone-safety contract the runtime relies on.
 import { loadGLTF, resolveGltfNode } from '@engine/scene/asset-loaders';
+import { applyImportCorrection, getAssetMeta, loadRegistry } from '@engine/scene/asset-registry';
 import { DEFAULTS } from '@engine/scene/defaults';
 import { deleteUserData, getUserData, setUserData } from '@engine/scene/user-data';
 import '@engine/scene/geometries';
@@ -20,6 +21,7 @@ import '@engine/scene/materials';
 import { createParticleSystemFromData } from '@engine/scene/particles-factory';
 import type { SceneEntity } from '@engine/scene/scene-types';
 import * as THREE from 'three';
+import { ensureSkeletonHelper } from './skeleton-helper';
 
 /**
  * Load a GLTF and return a disposal-safe clone + its animation clips for the
@@ -40,9 +42,10 @@ function setupAnimation(
   animations: THREE.AnimationClip[],
   autoplay?: string,
   loop?: boolean,
+  clipAliases?: Record<string, string>,
 ): void {
   if (animations.length === 0) return;
-  const clipMap = buildClipMap(animations);
+  const clipMap = buildClipMap(animations, clipAliases);
 
   // Expose available clip names for the inspector dropdown
   setUserData(group, '_availableClips', [...clipMap.keys()]);
@@ -95,10 +98,16 @@ export function createEntityObject(entity: SceneEntity): THREE.Object3D {
       const group = new THREE.Group();
       const src = entity.mesh.src;
 
-      const gltfPromise = loadGltfWithClips(src);
+      // Runtime scene loading awaits this same registry before constructing a
+      // model. Await it alongside the GLTF so editor preview and Play apply the
+      // exact same visual-only scale/facing correction.
+      const gltfPromise = Promise.all([loadGltfWithClips(src), loadRegistry()]).then(
+        ([gltf]) => gltf,
+      );
 
       const autoplay = entity.animation?.autoplay;
       const loop = entity.animation?.loop;
+      const clipAliases = entity.animation?.clipAliases;
 
       const nodeName = entity.mesh.node;
       const lod = entity.mesh.lod;
@@ -128,6 +137,7 @@ export function createEntityObject(entity: SceneEntity): THREE.Object3D {
           content.rotation.set(0, 0, 0);
           content.scale.set(1, 1, 1);
         }
+        applyImportCorrection(content, getAssetMeta(src)?.importCorrection);
         group.add(content);
         // The shared loadGLTF already gave the clone its own materials and tagged
         // every mesh `__sharedGeometry` (so editor disposal in scene-sync never
@@ -136,7 +146,8 @@ export function createEntityObject(entity: SceneEntity): THREE.Object3D {
         content.traverse((n) => {
           setUserData(n, '__sharedGeometry', true);
         });
-        setupAnimation(group, clone, animations, autoplay, loop);
+        setupAnimation(group, clone, animations, autoplay, loop, clipAliases);
+        ensureSkeletonHelper(group);
       });
       obj = group;
     } else {

package/src/gizmo-registry.ts

@@ -24,6 +24,7 @@ import type {
 import { getUserData, setUserData } from '@engine/scene/user-data';
 import * as THREE from 'three';
 import { EDITOR_LAYER } from './editor-layers';
+import { ensureSkeletonHelper } from './skeleton-helper';
 
 // ---------------------------------------------------------------------------
 // Registry types
@@ -361,7 +362,7 @@ const audioGizmo: GizmoEntry = {
  * `dims` already has the entity's composed world scale (self × ancestors)
  * applied, so this function itself must NOT apply any further scale.
  */
-function createColliderHelper(
+export function createColliderHelper(
   collider: SceneCollider,
   dims: ColliderWorldDimensions,
 ): THREE.Object3D | null {
@@ -424,7 +425,9 @@ function createColliderHelper(
       return null;
   }
 
-  return group.children.length > 0 ? group : null;
+  if (group.children.length === 0) return null;
+  if (collider.offset) group.position.fromArray(collider.offset);
+  return group;
 }
 
 const colliderGizmo: GizmoEntry = {
@@ -566,11 +569,23 @@ const GIZMO_REGISTRY: GizmoEntry[] = [
  */
 export function applyEntityGizmos(obj: THREE.Object3D): void {
   const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
-  if (!entity) return;
+  if (!entity) {
+    ensureSkeletonHelper(obj);
+    return;
+  }
 
-  // Idempotent: skip if gizmos already applied
-  if (obj.children.some((c) => getUserData(c, 'editorHelper') || getUserData(c, 'editorIcon')))
+  // Skeletons are created independently from entity gizmos and must not make
+  // collider/light/etc. setup look complete.
+  const hasEntityGizmos = obj.children.some(
+    (child) =>
+      getUserData(child, 'editorIcon') ||
+      (getUserData(child, 'editorHelper') &&
+        getUserData(child, 'editorHelperType') !== 'skeletons'),
+  );
+  if (hasEntityGizmos) {
+    ensureSkeletonHelper(obj);
     return;
+  }
 
   let added = false;
   for (const entry of GIZMO_REGISTRY) {
@@ -605,4 +620,5 @@ export function applyEntityGizmos(obj: THREE.Object3D): void {
 
   // Force matrix computation so helpers render at the correct position immediately
   if (added) obj.updateMatrixWorld(true);
+  ensureSkeletonHelper(obj);
 }

package/src/harness-chat-editor-context.ts

@@ -0,0 +1,37 @@
+/** Lightweight bridge from the editor shell into the coding-agent panel.
+ * Kept free of EditorContext's engine import graph so the panel remains
+ * independently testable and the Supercode-facing UI stays framework-thin. */
+export interface HarnessChatEditorStore {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): number;
+  readonly selectedEntityId: string | null;
+  readonly selectedEntity: {
+    id?: string | undefined;
+    name?: string | undefined;
+  } | null;
+  readonly playState: 'stopped' | 'playing' | 'paused';
+}
+
+let current: HarnessChatEditorStore | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+export function setHarnessChatEditorStore(store: HarnessChatEditorStore | null): void {
+  if (current === store) return;
+  current = store;
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function harnessChatEditorStore(): HarnessChatEditorStore | null {
+  return current;
+}
+
+export function subscribeHarnessChatEditorStore(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function harnessChatEditorStoreVersion(): number {
+  return version;
+}

package/src/harness-chat-indicator.ts

@@ -0,0 +1,68 @@
+import type { HarnessChatSnapshot } from './harness-chat-types';
+
+export interface HarnessChatIndicator {
+  /** This editor owns the selected runtime. This is deliberately a state,
+   * not a fabricated multi-agent count. */
+  controlled: boolean;
+  working: boolean;
+  needsInput: boolean;
+  following: boolean;
+  unavailable: boolean;
+}
+
+let current: HarnessChatIndicator = {
+  controlled: false,
+  working: false,
+  needsInput: false,
+  following: false,
+  unavailable: false,
+};
+let version = 0;
+const listeners = new Set<() => void>();
+
+export function updateHarnessChatIndicator(snapshot: HarnessChatSnapshot): void {
+  const next: HarnessChatIndicator = {
+    controlled: snapshot.connection.ownsRuntime,
+    working: snapshot.turn.state !== 'idle',
+    needsInput: snapshot.requests.some((request) => request.status === 'pending'),
+    following: snapshot.connection.follow !== 'inactive',
+    unavailable: snapshot.status === 'unavailable',
+  };
+  if (
+    next.controlled === current.controlled &&
+    next.working === current.working &&
+    next.needsInput === current.needsInput &&
+    next.following === current.following &&
+    next.unavailable === current.unavailable
+  ) {
+    return;
+  }
+  current = next;
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function harnessChatIndicator(): HarnessChatIndicator {
+  return current;
+}
+
+export function harnessChatIndicatorVersion(): number {
+  return version;
+}
+
+export function subscribeHarnessChatIndicator(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function __resetHarnessChatIndicatorForTest(): void {
+  current = {
+    controlled: false,
+    working: false,
+    needsInput: false,
+    following: false,
+    unavailable: false,
+  };
+  version++;
+  for (const listener of listeners) listener();
+}

package/src/harness-chat-layout.ts

@@ -0,0 +1,53 @@
+/** Presentation state for the permanent coding-agent surface.
+ *
+ * Chat is a Dockview panel, so Dockview owns its position and size. This tiny
+ * store owns only whether the optional panel is present. Supercode's server
+ * controller remains independent of either surface, so closing/moving the
+ * panel never detaches or hands off a controlled harness session.
+ */
+
+export interface HarnessChatLayoutState {
+  readonly collapsed: boolean;
+}
+
+let state: HarnessChatLayoutState = { collapsed: false };
+let version = 0;
+const listeners = new Set<() => void>();
+
+function publish(next: HarnessChatLayoutState): void {
+  if (next.collapsed === state.collapsed) return;
+  state = next;
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeHarnessChatLayout(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function harnessChatLayoutVersion(): number {
+  return version;
+}
+
+export function harnessChat(): HarnessChatLayoutState {
+  return state;
+}
+
+export function setHarnessChatCollapsed(collapsed: boolean): void {
+  publish({ ...state, collapsed });
+}
+
+export function toggleHarnessChatCollapsed(): void {
+  setHarnessChatCollapsed(!state.collapsed);
+}
+
+export function hydrateHarnessChatLayout(next: Partial<HarnessChatLayoutState>): void {
+  publish({ collapsed: next.collapsed ?? state.collapsed });
+}
+
+export function __resetHarnessChatLayoutForTest(): void {
+  state = { collapsed: false };
+  version = 0;
+  listeners.clear();
+}