@volter/editor-core 0.5.57

package/src/harness-chat-types.ts

@@ -0,0 +1,253 @@
+import { normalizeUiState, type SupercodeUiState } from '@volter-ai-dev/supercode-ui/core';
+import type { RemoteUiFrame } from '@volter-ai-dev/supercode-ui/host';
+
+/**
+ * Browser/server contract for the permanent coding-agent surface.
+ *
+ * Supercode owns harness, session, transcript, and runtime semantics. This
+ * wire mirrors its frontend state instead of inventing a second state
+ * machine; VGAI adds only editor-specific presentation and context.
+ */
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type HarnessChatMode = 'none' | 'observe' | 'control';
+export type HarnessChatStatus = 'loading' | 'ready' | 'working' | 'error' | 'unavailable';
+/** Mirrors Supercode's passive/handshake authentication posture exactly. */
+export type HarnessChatAuthState = 'ready' | 'configured' | 'required' | 'unknown';
+export type HarnessChatRuntimeState = 'ready' | 'degraded' | 'unavailable';
+export type HarnessChatOperation =
+  | 'refresh'
+  | 'observe'
+  | 'start'
+  | 'resume'
+  | 'attach'
+  | 'fork'
+  | 'reduce'
+  | 'restore'
+  | 'detach'
+  | 'openTerminal'
+  | 'send'
+  | 'steer'
+  | 'interrupt'
+  | 'respond'
+  | 'configureHarness'
+  | 'loadEarlier'
+  | 'load'
+  | 'import'
+  | 'export'
+  | 'translate'
+  | 'handoff'
+  | 'workspace'
+  | 'close'
+  | null;
+
+export interface HarnessChatCapabilities {
+  startSession: boolean;
+  resumeSession: boolean;
+  attachExistingProcess: boolean;
+  sendInput: boolean;
+  streamEvents: boolean;
+  interrupt: boolean;
+  respondToRequests: boolean;
+}
+
+export interface HarnessChatHarness {
+  id: string;
+  label: string;
+  installed: boolean;
+  auth: HarnessChatAuthState;
+  runtime: HarnessChatRuntimeState;
+  protocol: string;
+  capabilities: HarnessChatCapabilities;
+  availableActions: {
+    start: boolean;
+    resume: boolean;
+    attach: boolean;
+    send: boolean;
+    interrupt: boolean;
+    respond: boolean;
+  };
+  reason: string | null;
+  repair: string | null;
+}
+
+export interface HarnessChatSession {
+  /** Opaque, controller-scoped key used by actions. */
+  id: string;
+  /** Stable, non-display identity used only to restore this exact selection. */
+  identity: string;
+  /** Harness-native identity, display/diagnostics only. */
+  nativeId?: string;
+  harness: string;
+  title: string;
+  cwd: string | null;
+  updatedAt: number | null;
+  messageCount: number | null;
+  model: string | null;
+  storage: 'file' | 'sqlite';
+  /** What the session's process reports for itself RIGHT NOW — a live
+   *  peer's status — or `null` for a persisted session with no process. */
+  live?: 'running' | 'busy' | 'idle' | null;
+}
+
+export interface HarnessChatTaskPlanItem {
+  id: string;
+  title: string;
+  status: 'pending' | 'in_progress' | 'completed' | 'cancelled' | 'unknown';
+  nativeStatus?: string;
+  blockedBy?: string[];
+}
+
+export interface HarnessChatTaskPlan {
+  source: 'codex-update-plan' | 'claude-tasks' | 'opencode-todos' | 'none';
+  items: HarnessChatTaskPlanItem[];
+  residue: unknown[];
+  observedAt: number | null;
+}
+
+export interface HarnessChatRequestOption {
+  optionId: string;
+  name: string;
+  kind: 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always' | 'other';
+}
+
+export interface HarnessChatRequestEntry {
+  id: string;
+  kind: 'request';
+  requestId: JsonValue;
+  requestKind: string;
+  payload: JsonValue;
+  options: HarnessChatRequestOption[];
+  cancellable: boolean;
+  status: 'pending' | 'responded';
+  resolution: { optionId: string | null; name: string; kind: string } | null;
+}
+
+export interface HarnessChatAvailableActions {
+  refresh: boolean;
+  observe: boolean;
+  start: boolean;
+  resume: boolean;
+  attach: boolean;
+  fork: boolean;
+  detach: boolean;
+  openTerminal: boolean;
+  send: boolean;
+  interrupt: boolean;
+  respond: boolean;
+}
+
+export interface HarnessChatError {
+  code: string;
+  message: string;
+  operation: Exclude<HarnessChatOperation, null> | 'runtime' | 'follow';
+  recoverable: boolean;
+}
+
+export interface HarnessChatSnapshot {
+  schema: 'vgai.harness-chat.v4';
+  /** Identifies the editor-server process that issued this snapshot. */
+  serverInstanceId: string | null;
+  revision: number;
+  /** Monotonic host generation. Revisions are only comparable within it. */
+  workspaceGeneration: number;
+  workspace: string | null;
+  status: HarnessChatStatus;
+  mode: HarnessChatMode;
+  operation: HarnessChatOperation;
+  harnesses: HarnessChatHarness[];
+  sessions: HarnessChatSession[];
+  activeHarness: string | null;
+  activeSessionId: string | null;
+  connection: {
+    strategy: 'start' | 'resume' | 'attach' | 'fork' | 'reduce' | null;
+    follow: 'inactive' | 'following' | 'retrying';
+    ownsRuntime: boolean;
+  };
+  turn: {
+    state: 'idle' | 'running' | 'interrupting' | 'reconciling';
+    id: string | null;
+    startedAt: number | null;
+  };
+  /** Ordered Supercode host frame. This is the sole messenger lifecycle authority. */
+  frame: RemoteUiFrame | null;
+  taskPlan: HarnessChatTaskPlan;
+  requests: HarnessChatRequestEntry[];
+  availableActions: HarnessChatAvailableActions;
+  error: HarnessChatError | null;
+  terminalCommand: string | null;
+}
+
+/** VGAI's one editor-host extension. Every reusable messenger mutation uses
+ * SupercodeUiIntent unchanged through the intent route. */
+export type HarnessChatHostAction = {
+  type: 'restore';
+  sessionIdentity: string;
+  connection: 'observe' | 'attach';
+};
+
+/** Read the sole canonical messenger projection. A frame-less loading/error
+ * snapshot gets a local empty view; it is never serialized as a second state. */
+export function harnessChatUiState(snapshot: HarnessChatSnapshot): SupercodeUiState {
+  if (snapshot.frame) return snapshot.frame.state;
+  return normalizeUiState({
+    startup: snapshot.status === 'loading' ? 'connecting' : 'ready',
+    workspace: snapshot.workspace ?? '',
+    error: snapshot.error?.message ?? null,
+    recoverable: snapshot.error?.recoverable ?? true,
+  });
+}
+
+export function unavailableHarnessChatSnapshot(
+  error: string,
+  options?: { code?: string; recoverable?: boolean },
+): HarnessChatSnapshot {
+  return {
+    schema: 'vgai.harness-chat.v4',
+    serverInstanceId: null,
+    revision: 0,
+    workspaceGeneration: 0,
+    workspace: null,
+    status: 'unavailable',
+    mode: 'none',
+    operation: null,
+    harnesses: [],
+    sessions: [],
+    activeHarness: null,
+    activeSessionId: null,
+    connection: { strategy: null, follow: 'inactive', ownsRuntime: false },
+    turn: { state: 'idle', id: null, startedAt: null },
+    frame: null,
+    taskPlan: { source: 'none', items: [], residue: [], observedAt: null },
+    requests: [],
+    availableActions: {
+      refresh: false,
+      observe: false,
+      start: false,
+      resume: false,
+      attach: false,
+      fork: false,
+      detach: false,
+      openTerminal: false,
+      send: false,
+      interrupt: false,
+      respond: false,
+    },
+    error: error
+      ? {
+          code: options?.code ?? 'unavailable',
+          message: error,
+          operation: 'load',
+          recoverable: options?.recoverable ?? true,
+        }
+      : null,
+    terminalCommand: null,
+  };
+}

package/src/hierarchy-component-marks.ts

@@ -0,0 +1,298 @@
+/**
+ * The panel's half of the hierarchy-presentation convention
+ * (`@volter/editor-threejs/adapter/hierarchy-marks`): a game classifies its
+ * component-instance roots and its implementation subtrees on the LIVE nodes,
+ * and this turns that classification into rows.
+ *
+ * CLASSIFICATION ONLY — NEVER FABRICATED STRUCTURE. Nothing here invents a
+ * parent. Where a node belongs is the TREE's answer, and a world whose tree
+ * disagrees with its own ownership is fixed in the world (three's
+ * `matrixWorldAutoUpdate = false` keeps a transform-independent object parented
+ * where it belongs), not papered over here. What this module decides is
+ * narrower and entirely presentational: which rows are the game and which are
+ * the implementation underneath it, and — since an implementation node may sit
+ * BETWEEN two things that are the game — where a row's nearest visible ancestor
+ * is. See {@link componentMarkView} point 5, promotion.
+ *
+ * WHY THIS IS A DECORATOR AND NOT A SECOND ROW PIPELINE. Exactly the reason
+ * `hierarchy-internals.ts` gives for reveal: the panel's cap, collapse, search,
+ * selection-reveal and virtualization all layer on ONE flatten of ONE
+ * `HierarchyProvider`. A marked tree composes by handing that flattener a
+ * richer provider — never by forking the walk. And it composes with reveal
+ * specifically by producing an {@link InternalsSource}: built-internals become
+ * internals of exactly the kind "Reveal Internals" already shows, so the
+ * read-only rule, the search exclusion and the drag refusal that already govern
+ * a revealed row govern these with no second policy.
+ *
+ * THE NO-MARKS FALLBACK IS IDENTITY, BY CONSTRUCTION. Every projection below
+ * short-circuits when a node carries no mark and no child carries one, and
+ * {@link componentMarkView} returns the source's own `hierarchy` object when the
+ * tree cannot carry marks at all (an adapter with no `Object3D` seam — React,
+ * Pixi, DOM). A world that adopts nothing renders exactly as it did.
+ *
+ * PURE ON PURPOSE: the marks arrive through the injected {@link NodeMarkReader},
+ * never by importing three or touching `userData` here, so the whole row
+ * decision is unit-testable with plain objects.
+ */
+
+import type { EditorNode, HierarchyProvider } from '@volter/editor-project/adapter';
+import type { InternalsSource } from './hierarchy-internals';
+import type { HierarchyNodeRow } from './hierarchy-node-rows';
+
+/** What the marks say about ONE node. Both absent is the ordinary node. */
+export interface NodeMarks {
+  /** `vgaiComponentRoot` — the component name this node is one instance of. */
+  readonly componentRoot?: string | undefined;
+  /** A native authoring entity constructor. It stays an ordinary entity row, but like a
+   *  component root it is authored content even when a host implementation node wraps it. */
+  readonly authoredEntity?: boolean | undefined;
+  /** `vgaiBuiltInternal` — this node is the root of an implementation subtree. */
+  readonly builtInternal?: boolean | undefined;
+}
+
+/** Reads the marks off one node id. `undefined` for an id the source has no
+ *  live object for — indistinguishable from an unmarked node, deliberately. */
+export type NodeMarkReader = (id: string) => NodeMarks | undefined;
+
+/** The hierarchy half of an adapter, plus whatever internals capability it
+ *  already had. Structurally satisfied by `AuthoringAdapter` /
+ *  `CompositeAuthoringAdapter` without importing either — the same contract-only
+ *  probe shape `hierarchy-internals.ts` and `hierarchy-row-model.ts` use. */
+export interface MarkedTreeSource {
+  readonly hierarchy: Pick<HierarchyProvider, 'roots' | 'node'>;
+  readonly hasInternals?: ((id: string) => boolean) | undefined;
+  readonly internalChildren?: ((id: string) => EditorNode[] | undefined) | undefined;
+}
+
+export interface MarkedTreeView extends InternalsSource {
+  /** True for a node whose live object carries `vgaiComponentRoot`. */
+  isComponentRoot(id: string): boolean;
+  /** True for a node that is, or descends from, a `vgaiBuiltInternal` root.
+   *  Exposed for tests and for {@link componentMarkView}'s own reuse; the panel
+   *  reads internal-ness off the reveal projection, which is the union of these
+   *  and the adapter's own hidden children. */
+  isBuiltInternal(id: string): boolean;
+}
+
+/** Depth backstop for a pathological live tree — the same belt-and-braces
+ *  constant `hierarchy-internals.ts`/`hierarchy-node-rows.ts` keep. */
+const MAX_DEPTH = 500;
+
+/** The reader for a surface that has no node to read marks off. Identity-checked
+ *  by {@link componentMarkView}, which is why it is a shared constant rather
+ *  than a fresh closure per call. */
+export const NO_MARKS: NodeMarkReader = () => undefined;
+
+/**
+ * Decorate `source` so the marks become rows.
+ *
+ * Five things change, and nothing else:
+ *
+ * 1. A marked component root reports `role: 'component'` and
+ *    `typeLabel: <mark name>`. That is all the panel needs — `rowIdentity`
+ *    already prints `Coin1 ·Coin` for exactly this pair, and `ROLE_ICON`
+ *    already has the component glyph. NO new presentation vocabulary: a second
+ *    way to render "this is an instance" is how two of them drift.
+ *    The mark REPLACES any `typeLabel` the adapter had, because a three
+ *    projection reports the native class there (`Object3D`), and
+ *    `Coin1 ·Object3D` is worse than no suffix at all.
+ * 2. Built-internal children disappear from every `childIds`, so what a
+ *    collapsed tree shows is the game and not its implementation.
+ * 3. A built-internal ROOT disappears from `roots()` for the same reason, but
+ *    meaningful content beneath it is promoted to roots in place. A root has
+ *    no parent row to reveal it under, so the implementation wrapper itself
+ *    stays unreachable while spawned content remains visible.
+ * 4. Both come back through `internalChildren`/`hasInternals` — unioned with
+ *    whatever the adapter already hid — so "Reveal Internals" shows them,
+ *    read-only, under their real parent, in the true chain.
+ * 5. PROMOTION. A component instance does not lose its row because
+ *    implementation nodes sit between it and its owner. A weapon prefab
+ *    attached to a hand bone, a nameplate on a head bone: content the author
+ *    placed, inside a subtree a rig builder marked. `vgaiComponentRoot` beats
+ *    `vgaiBuiltInternal` (see `isBuiltInternal`'s climb), and this lists such a
+ *    row under its nearest VISIBLE ancestor — so a prefab reads as the parent
+ *    of everything meaningful beneath it, however many bones the rig hangs in
+ *    between. A subtree with no instance inside it still folds away whole,
+ *    because there is nothing in it to promote. This is the elision half of the
+ *    same classification: (2) removes an implementation row, (5) keeps what was
+ *    under it from going with it.
+ *
+ * Built-internal is SUBTREE-scoped (see the engine module's header): a node
+ * whose ANCESTOR is marked is internal too, which is what lets a rig cost one
+ * mark. {@link MarkedTreeView.isBuiltInternal} memoizes that climb, so a
+ * repeated walk over the same tree pays once per node.
+ */
+export function componentMarkView(
+  source: MarkedTreeSource,
+  marksOf: NodeMarkReader,
+): MarkedTreeView {
+  if (marksOf === NO_MARKS) {
+    // A surface with no `Object3D` seam (React, Pixi, DOM) cannot carry these
+    // marks at all. Hand back the source itself so the panel's provider is
+    // IDENTICAL, not merely equivalent.
+    return {
+      hierarchy: source.hierarchy,
+      isComponentRoot: () => false,
+      isBuiltInternal: () => false,
+      ...(source.hasInternals ? { hasInternals: (id: string) => source.hasInternals!(id) } : {}),
+      ...(source.internalChildren
+        ? { internalChildren: (id: string) => source.internalChildren!(id) }
+        : {}),
+    };
+  }
+
+  /** id -> "this node is inside a built subtree", memoized across the walk. */
+  const internalCache = new Map<string, boolean>();
+
+  const isBuiltInternal = (id: string): boolean => {
+    const cached = internalCache.get(id);
+    if (cached !== undefined) return cached;
+    // Climb to the first answer we already have (or to a root), then fill the
+    // whole chain in one pass — an ancestor walk per node would be O(depth²).
+    const chain: string[] = [];
+    let cursor: string | null = id;
+    let inherited = false;
+    let guard = 0;
+    while (cursor !== null && guard++ < MAX_DEPTH) {
+      const known = internalCache.get(cursor);
+      if (known !== undefined) {
+        inherited = known;
+        break;
+      }
+      chain.push(cursor);
+      // PRECEDENCE: an explicit component root is content even inside an
+      // implementation subtree. Otherwise an explicit implementation mark on
+      // THIS node wins over the automatic authored-entity stamp: generated
+      // native machinery is still source-addressable JSX, but its attach seam
+      // knows that it is implementation. An authored entity with no such mark
+      // remains content inside an implementation ancestor — a weapon attached
+      // to a rig bone, for example — which is what makes promotion (see
+      // `visibleChildIds`) reachable at all.
+      const marks = marksOf(cursor);
+      if (marks?.componentRoot !== undefined) break;
+      if (marks?.builtInternal === true) {
+        inherited = true;
+        break;
+      }
+      if (marks?.authoredEntity === true) break;
+      cursor = source.hierarchy.node(cursor)?.parentId ?? null;
+    }
+    // `chain` is innermost-first and every entry shares the verdict of the node
+    // that stopped the climb — either an already-known ancestor, or the marked
+    // node itself (which is the last entry pushed).
+    for (const entry of chain) internalCache.set(entry, inherited);
+    return inherited;
+  };
+
+  const isComponentRoot = (id: string): boolean => marksOf(id)?.componentRoot !== undefined;
+
+  /**
+   * The rows that belong directly under `node` — its own visible children,
+   * plus (point 5) the visible descendants that implementation children stand
+   * between. Recursive: an implementation node contributes ITS promoted rows in
+   * its own place, so a two-deep chain of them elides just as one does, and a
+   * subtree with nothing visible in it contributes nothing at all.
+   */
+  const visibleChildIds = (node: EditorNode, depth = 0): string[] => {
+    if (depth > MAX_DEPTH) return [];
+    const out: string[] = [];
+    for (const childId of node.childIds) {
+      if (!isBuiltInternal(childId)) {
+        out.push(childId);
+        continue;
+      }
+      const child = source.hierarchy.node(childId);
+      if (child) out.push(...visibleChildIds(child, depth + 1));
+    }
+    return out;
+  };
+
+  /** The children of `id` this view hides — its DIRECT implementation children,
+   *  which is what "Reveal Internals" puts back and where the true chain lives. */
+  const hiddenChildIds = (node: EditorNode): string[] =>
+    node.childIds.filter((childId) => isBuiltInternal(childId));
+
+  const project = (node: EditorNode | null): EditorNode | null => {
+    if (!node) return null;
+    const componentRoot = marksOf(node.id)?.componentRoot;
+    const childIds = visibleChildIds(node);
+    const sameChildren =
+      childIds.length === node.childIds.length &&
+      childIds.every((childId, index) => childId === node.childIds[index]);
+    if (componentRoot === undefined && sameChildren) return node;
+    return {
+      ...node,
+      ...(componentRoot === undefined
+        ? {}
+        : { role: 'component' as const, typeLabel: componentRoot }),
+      ...(sameChildren ? {} : { childIds }),
+    };
+  };
+
+  const hierarchy: Pick<HierarchyProvider, 'roots' | 'node'> = {
+    roots: () =>
+      source.hierarchy.roots().flatMap((root) => {
+        if (!isBuiltInternal(root.id)) return [project(root)!];
+        return visibleChildIds(root).flatMap((childId) => {
+          const child = project(source.hierarchy.node(childId));
+          return child ? [{ ...child, parentId: root.parentId }] : [];
+        });
+      }),
+    node: (id) => project(source.hierarchy.node(id)),
+  };
+
+  return {
+    hierarchy,
+    isComponentRoot,
+    isBuiltInternal,
+    hasInternals: (id) => {
+      if (source.hasInternals?.(id) === true) return true;
+      const node = source.hierarchy.node(id);
+      return node ? hiddenChildIds(node).length > 0 : false;
+    },
+    internalChildren: (id) => {
+      const own = source.internalChildren?.(id);
+      const node = source.hierarchy.node(id);
+      const hidden = node
+        ? hiddenChildIds(node).flatMap((childId) => {
+            // PROJECTED, not raw: this node's own implementation children are
+            // hidden from its `childIds` here too, and the reveal walk appends
+            // them back itself. Handing back the raw node would list every
+            // sub-bone twice. Reveal therefore shows the TRUE chain of
+            // implementation nodes — each under its real parent, one level per
+            // walk step — which is what the action is for.
+            const child = project(source.hierarchy.node(childId));
+            // Re-parented to `id` — a revealed subtree is displayed as the tree
+            // it literally is, the same rule `internalChildren` states on the
+            // source adapter.
+            return child ? [{ ...child, parentId: id }] : [];
+          })
+        : [];
+      if (own === undefined) return hidden.length > 0 ? hidden : undefined;
+      return [...own, ...hidden];
+    },
+  };
+}
+
+/**
+ * A marked component instance opens CLOSED. This is a default, applied on top
+ * of `defaultExpansionByNode`'s shape rule and under the author's own session /
+ * persisted preference — so "expandable on demand" is the panel's existing
+ * expansion state doing its existing job, and an instance the author opened
+ * stays open across renders.
+ *
+ * Takes the already-flattened structural rows rather than walking the tree
+ * again: the panel has them, and a second walk over a live graph is the cost
+ * this whole cycle exists to remove.
+ */
+export function applyComponentRootExpansionDefaults(
+  defaults: Map<string, boolean>,
+  rows: readonly HierarchyNodeRow[],
+  isComponentRoot: (id: string) => boolean,
+): Map<string, boolean> {
+  for (const row of rows) {
+    if (row.more) continue;
+    if (isComponentRoot(row.node.id)) defaults.set(row.node.id, false);
+  }
+  return defaults;
+}

package/src/hierarchy-drop.ts

@@ -0,0 +1,91 @@
+/**
+ * Cross-world drop validity for the hierarchy shell (spec 29 §3): edge
+ * semantics belong to the kind, so `CompositeAuthoringAdapter`'s structure
+ * provider REFUSES cross-world reparents (loud warn + no-op) and cross-world
+ * reorder anchors. A drop the adapter will refuse must never LOOK valid in the
+ * panel — chrome advertising an operation that will be refused is a false
+ * claim — so `GameHierarchy`'s dragover path gates the drop indicator on this
+ * predicate instead of letting the drop fall through to the adapter's refusal.
+ *
+ * Rule zero: roots are resolved by ASKING the composite (`groupNodeId`/
+ * `ownerOf`), never by decoding adapter-minted id strings here.
+ */
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { CompositeAuthoringAdapter } from './authoring/composite-authoring-adapter';
+
+/** The world that owns `nodeId` for drop purposes: the owning child's
+ *  `worldId` for an ordinary row, the world itself for its synthetic
+ *  `world:<id>` group row (dropping INTO a world's own group row is
+ *  "become a root of my world" — valid), `null` for an organizational or
+ *  unrecognized id
+ *  no child recognizes. */
+function dropRootOf(composite: CompositeAuthoringAdapter, nodeId: string): string | null {
+  for (const child of composite.childAdapters()) {
+    if (composite.groupNodeId(child.worldId) === nodeId) return child.worldId;
+  }
+  return composite.ownerOf(nodeId);
+}
+
+/**
+ * True when reparenting/reordering `dragIds` at row `targetId` will be
+ * accepted by the active adapter's structure provider: the adapter is not a
+ * composite (a bare adapter is single-world by construction), or EVERY
+ * dragged id and the target row live in the same world. A mixed-world
+ * multi-select fails as a whole — the alternative is a drop that half-applies
+ * (same-world ids move, foreign ids warn), which is worse than refusing the
+ * affordance outright. Group-row / organizational drag ids fail the same way
+ * (`ownerOf` → null): roots are reordered through their zOrder, not by
+ * dragging one into another's subtree.
+ */
+export function isSameRootDrop(
+  adapter: AuthoringAdapter,
+  dragIds: string[],
+  targetId: string,
+): boolean {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return true;
+  const targetWorld = dropRootOf(adapter, targetId);
+  if (targetWorld === null) return false;
+  return dragIds.every((id) => adapter.ownerOf(id) === targetWorld);
+}
+
+// ------------------------------------------------------- refusal, by name
+
+/**
+ * A DEAD DRAG IS A BUG. Everything above answers "may the indicator show"; the
+ * two predicates below answer the question the owner actually hit on a
+ * translated port — *the row let me drag it, the drop did nothing, and nothing
+ * said why*. A refusal the panel cannot explain is indistinguishable from a
+ * broken editor, so every path that suppresses the indicator now carries the
+ * sentence that goes with it.
+ *
+ * The sentences are STRUCTURAL, not per-world prose: each names a fact about
+ * the row or the adapter that is true for every game in that state. Where an
+ * adapter has its own sentence for a refusal (`TransformProvider.editability`'s
+ * `reason`), that one is canonical and this module never paraphrases it — these
+ * two cases have no adapter-side reason to forward, because the capability is
+ * absent rather than declined.
+ */
+export const NO_STRUCTURE_WRITE_REFUSAL =
+  "This world's structure comes from its own source, which the editor can't rewrite here — reparenting is not wired for it.";
+
+export const INTERNAL_TARGET_REFUSAL =
+  "That row is part of a component instance's own output, not authored content. Drop onto the instance itself to place relative to it.";
+
+/**
+ * Why this drop will do nothing, or `null` when it will work.
+ *
+ * Order matters and is the honest one: an adapter that cannot reparent AT ALL
+ * refuses first, because "expand the instance instead" would be advice that
+ * also fails. Pure — the caller resolves both facts from the adapter and the
+ * reveal projection it already has.
+ */
+export function hierarchyDropRefusal(input: {
+  /** The active adapter exposes a `structure` provider (reparent/reorder). */
+  readonly hasStructureWritePath: boolean;
+  /** The hovered row exists only because a component's internals were revealed. */
+  readonly targetIsInternal: boolean;
+}): string | null {
+  if (!input.hasStructureWritePath) return NO_STRUCTURE_WRITE_REFUSAL;
+  if (input.targetIsInternal) return INTERNAL_TARGET_REFUSAL;
+  return null;
+}