@volter/editor-core 0.5.57

package/src/transform-mode-request.ts

@@ -0,0 +1,57 @@
+/**
+ * H2, third half — honest gizmo refusal.
+ *
+ * WHY THE TRIGGER IS TOOL ACTIVATION AND NOT DRAG-START. The design record
+ * says "attempting to drag a refused node shows a transient hint". Read
+ * against the code, a literal drag-start trigger is unreachable: a fully
+ * refused selection never gets a gizmo in the first place —
+ * `EditorViewport.syncFromStore` computes `selectedTransformWritable` and
+ * calls `this.detach()` (editor-viewport.ts, the `attach`/`detach` branch), so
+ * `TransformControls` fires no `dragging-changed`: there is nothing attached
+ * to drag. THAT detach is the exact spot where the silence lives.
+ *
+ * The earliest point at which the user has made a real, unambiguous attempt to
+ * transform — as opposed to merely selecting something — is therefore ARMING
+ * the move/rotate/scale tool (W/E/R, the toolbar's mode buttons, the command
+ * palette's Translate/Rotate/Scale Mode actions) while that refused selection
+ * is live. That is the second trigger the brief explicitly allows, and
+ * it is what this module implements. Every UI mode-switch call site routes
+ * through {@link requestTransformMode} instead of `store.setTransformMode`.
+ * (The programmatic `command-listener` path deliberately does not: an
+ * automated `set-transform-mode` command is not a user attempt, and a headless
+ * caller has no viewport to read a hint in.)
+ *
+ * The hint text is the adapter's own `reason`, verbatim — the same sentence
+ * the hierarchy lock tooltip and the inspector field show (doctrine rule 2).
+ * When an adapter refuses without giving a reason we show NOTHING rather than
+ * invent a sentence to paraphrase it with.
+ */
+
+import { getActiveAuthoring } from './authoring/active-adapter';
+import type { EditorShellStore, TransformMode } from './editor-shell-store';
+import { transformLockSummary } from './hierarchy-row-model';
+import { showTransientHint } from './transient-hint';
+
+/** Set the transform mode, and NAME the refusal if the live selection is one
+ *  the active adapter will not write. */
+export function requestTransformMode(store: EditorShellStore, mode: TransformMode): void {
+  store.setTransformMode(mode);
+  // Arming SELECT is not an attempt to transform anything — it is the tool
+  // that transforms nothing (`TransformMode`'s own note) — so the refusal
+  // below, whose whole trigger is "a real, unambiguous attempt to transform",
+  // has nothing to report about it.
+  if (mode === 'select') return;
+  const ids = [...store.selectedEntityIds];
+  if (ids.length === 0) return;
+  const editability = getActiveAuthoring(store).transforms?.editability;
+  if (!editability) return;
+  let reason: string | undefined;
+  for (const id of ids) {
+    const summary = transformLockSummary((channel) => editability(id, channel));
+    // Anything movable in the selection means the gesture is not refused —
+    // the gizmo attaches and moves what it can.
+    if (!summary.locked) return;
+    reason ??= summary.reason;
+  }
+  if (reason) showTransientHint(reason);
+}

package/src/transient-hint.ts

@@ -0,0 +1,78 @@
+/**
+ * The editor's one transient, non-blocking hint channel (H2).
+ *
+ * There was no toast/notification/status-message mechanism in the editor when
+ * this landed (grepped: `toast`, `notification`, `statusMessage`, `hint` —
+ * only unrelated hits), so this is the minimal one. Deliberately: one hint at
+ * a time (a new one replaces the old), auto-dismissing, carrying nothing but
+ * a string it did not write. Blocking dialogs (`window.alert`/`prompt`) are
+ * banned in editor UI.
+ *
+ * Publisher lives here (plain module state, no React) so non-React callers —
+ * hotkeys, the action registry — can raise a hint without importing the
+ * component. `components/TransientHint.tsx` renders it.
+ */
+
+export const TRANSIENT_HINT_MS = 3000;
+
+export interface TransientHint {
+  /** Monotonic — lets the renderer restart its animation on a repeat message. */
+  readonly id: number;
+  readonly message: string;
+}
+
+let current: TransientHint | null = null;
+let timer: ReturnType<typeof setTimeout> | null = null;
+let nextId = 1;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Show `message` for {@link TRANSIENT_HINT_MS}, replacing any live hint. */
+export function showTransientHint(message: string): void {
+  current = { id: nextId++, message };
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(() => {
+    current = null;
+    timer = null;
+    emit();
+  }, TRANSIENT_HINT_MS);
+  emit();
+}
+
+export function dismissTransientHint(): void {
+  if (timer) clearTimeout(timer);
+  timer = null;
+  current = null;
+  emit();
+}
+
+export const subscribeTransientHint = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+export const transientHint = (): TransientHint | null => current;
+
+/**
+ * A drag that ended with NOTHING accepting it says so.
+ *
+ * `dropEffect === 'none'` at `dragend` is the browser's own word that no drop
+ * target took the payload: the card was released over editor chrome (a tab
+ * strip, the toolbar, a console row) instead of the viewport or a hierarchy
+ * row. That used to be perfectly silent — no hint, no console line, nothing
+ * changed — and a verifier lost a whole round to it before checking
+ * `elementFromPoint` (2026-09-02). A human just sees "the drop did nothing".
+ */
+export function reportUnacceptedAssetDrop(event: { dataTransfer: DataTransfer | null }): void {
+  if (event.dataTransfer?.dropEffect !== 'none') return;
+  // Surface-neutral on purpose: the source cannot know whether the scene is
+  // three or canvas, and a 2D tester told 'the 3D view' would be misled.
+  showTransientHint(
+    'Nothing accepted that drop — release it over the scene view or a hierarchy row.',
+  );
+}

package/src/trigger-volume-helper.ts

@@ -0,0 +1,116 @@
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import { triggerVolumeOf } from '@volter/editor-threejs/adapter/trigger-volume';
+import { setUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+
+const RING = new THREE.Color(0x4fd1c5);
+const RING_SELECTED = new THREE.Color(0x9ff0e8);
+const SEGMENTS = 64;
+/** How far the corner ticks rise off the ring, in world units. */
+const TICK_HEIGHT = 0.6;
+
+/**
+ * Editor-only visualization for a project-owned trigger volume — the group
+ * whose radius decides where a hazard fires or a quest arrives. The game's
+ * source says nothing about being authored; it just carries the radius in
+ * `userData`, and this helper draws it: a ground circle in the source's local
+ * XZ plane that extends upward at ±X/±Z, which is what such a volume tests.
+ *
+ * Same contract as `ReflectionProbeHelper`: it follows the live Object3D but
+ * owns every line and material it draws, sits on EDITOR_LAYER, and therefore
+ * never enters the game's tree or its runtime camera.
+ */
+export class TriggerVolumeHelper extends THREE.Group {
+  private signature = '';
+  private selected = false;
+
+  constructor(readonly source: THREE.Object3D) {
+    super();
+    this.name = 'Trigger Volume Helper';
+    this.matrixAutoUpdate = false;
+    this.renderOrder = 998;
+    setUserData(this, 'editorHelper', true);
+    setUserData(this, 'editorHelperType', 'trigger-volumes');
+    this.layers.set(EDITOR_LAYER);
+    this.refresh(true);
+  }
+
+  setSelected(selected: boolean): void {
+    if (this.selected === selected) return;
+    this.selected = selected;
+    this.refresh(true);
+  }
+
+  update(): void {
+    this.refresh(false);
+    this.source.updateWorldMatrix(true, false);
+    this.matrix.copy(this.source.matrixWorld);
+    this.matrixWorldNeedsUpdate = true;
+  }
+
+  dispose(): void {
+    this.clearVisuals();
+    this.removeFromParent();
+  }
+
+  private refresh(force: boolean): void {
+    const volume = triggerVolumeOf(this.source);
+    if (!volume) return;
+    const radius = volume.radius;
+    const next = String(radius);
+    if (!force && next === this.signature) return;
+    this.signature = next;
+    this.clearVisuals();
+
+    const color = this.selected ? RING_SELECTED : RING;
+    const opacity = this.selected ? 1 : 0.62;
+
+    const ring: number[] = [];
+    for (let i = 0; i < SEGMENTS; i += 1) {
+      const angle = (i / SEGMENTS) * Math.PI * 2;
+      ring.push(Math.cos(angle) * radius, 0, Math.sin(angle) * radius);
+    }
+    const ringGeometry = new THREE.BufferGeometry();
+    ringGeometry.setAttribute('position', new THREE.Float32BufferAttribute(ring, 3));
+    const loop = new THREE.LineLoop(ringGeometry, this.lineMaterial(color, opacity));
+    loop.renderOrder = this.renderOrder;
+    this.add(loop);
+
+    const ticks: number[] = [];
+    for (const [x, z] of [
+      [radius, 0],
+      [-radius, 0],
+      [0, radius],
+      [0, -radius],
+    ] as const) {
+      ticks.push(x, 0, z, x, TICK_HEIGHT, z);
+    }
+    const tickGeometry = new THREE.BufferGeometry();
+    tickGeometry.setAttribute('position', new THREE.Float32BufferAttribute(ticks, 3));
+    const tickLines = new THREE.LineSegments(tickGeometry, this.lineMaterial(color, opacity));
+    tickLines.renderOrder = this.renderOrder;
+    this.add(tickLines);
+
+    this.traverse((object) => object.layers.set(EDITOR_LAYER));
+  }
+
+  private lineMaterial(color: THREE.Color, opacity: number): THREE.LineBasicMaterial {
+    return new THREE.LineBasicMaterial({
+      color,
+      depthTest: false,
+      transparent: true,
+      opacity,
+      toneMapped: false,
+    });
+  }
+
+  private clearVisuals(): void {
+    for (const child of [...this.children]) {
+      child.removeFromParent();
+      const line = child as THREE.LineSegments;
+      line.geometry?.dispose();
+      const materials = Array.isArray(line.material) ? line.material : [line.material];
+      for (const material of materials) material?.dispose();
+    }
+  }
+}

package/src/ui-source/adapter-region-includes.ts

@@ -0,0 +1,241 @@
+import ts from 'typescript';
+
+/**
+ * A SYNCHRONOUS, source-only read of what a project's `vgai.adapter.ts`
+ * declares about which files belong to which SURFACE: each region's `include`
+ * globs, and the additional surfaces it `mounts` — stated either as parameters
+ * layered onto the `'manifest-roots'` rule (`regionIncludes`, what every
+ * first-party project uses) or inside an explicit `regions` list (the
+ * full-replacement form). Pure — the dev server adds
+ * the filesystem and a cache (`server/adapter-region-includes.ts`); the
+ * browser-hosted Content index reads the same file through its storage backend.
+ *
+ * WHY A STATIC READ AND NOT AN IMPORT. The adapter module's contract
+ * (`@volter/editor-project/adapter/adapter-module`, ARCHITECTURE-CORE §The editor protocol) is
+ * that its TOP LEVEL is "a STATICALLY EVALUABLE BINDING TABLE, readable without
+ * booting the game" — plain data, closures only inside `observation[].answer`.
+ * This module takes the contract at its word for the one consumer that cannot
+ * take any other route: the OID stamping transform runs in a Vite `transform`
+ * hook, synchronously, per project `.tsx`, long before any browser-tier adapter
+ * load has happened (and in `vite build`, where none ever will). The same
+ * placement test ARCHITECTURE-CORE applies to manifest-vs-adapter fields —
+ * "readable WITHOUT EVALUATING ANY MODULE … e.g. Vite config time" — is what
+ * makes a static read of a statically-evaluable table the right instrument here
+ * rather than a second declaration home.
+ *
+ * It reads those properties and reads them literally. Anything it cannot read
+ * literally is reported as {@link AdapterRegionIncludes.unreadable} — never
+ * silently treated as "no includes", because a silently dropped declaration is
+ * indistinguishable from a declaration that worked, which is the whole failure
+ * class this rung exists to end. `packages/editor/src/project-adapter.ts` (the
+ * real loader, which IMPORTS the module) stays the validation authority: this
+ * read never accepts anything that loader would reject, it only declines to
+ * answer.
+ */
+
+/** One ADDITIONAL mounted surface a region declares — see
+ *  `@volter/editor-project/adapter/adapter-module`'s `AdapterRegion.mounts`. */
+export interface AdapterRegionMountDeclaration {
+  readonly surface: 'three' | 'canvas' | 'dom';
+  readonly include: readonly string[];
+}
+
+/** Region id -> the `include` globs it declares, and the additional surfaces it
+ *  mounts. */
+export interface AdapterRegionIncludes {
+  readonly byRegionId: ReadonlyMap<string, readonly string[]>;
+  /** Region id -> the surfaces it mounts BESIDE its manifest root's own
+   *  adapter, each with the files that render on it. Read here for the same
+   *  reason `include` is: it is the one place a root's second surface can be
+   *  stated, and every OID/HMR/Content reader answers from the same table. */
+  readonly mountsByRegionId: ReadonlyMap<string, readonly AdapterRegionMountDeclaration[]>;
+  /**
+   * `true` when the file HAS a `regions` binding this static read could not
+   * evaluate (a spread, an imported constant, a computed value). The caller
+   * reports it; it never reads as "declares nothing".
+   */
+  readonly unreadable: boolean;
+}
+
+export const EMPTY_REGION_INCLUDES: AdapterRegionIncludes = {
+  byRegionId: new Map(),
+  mountsByRegionId: new Map(),
+  unreadable: false,
+};
+
+const UNREADABLE_REGION_INCLUDES: AdapterRegionIncludes = {
+  byRegionId: new Map(),
+  mountsByRegionId: new Map(),
+  unreadable: true,
+};
+
+/** The game's adapter module lives beside `vgai.project.json`, by contract. */
+export const ADAPTER_MODULE_FILENAME = 'vgai.adapter.ts';
+
+function stringLiteralOf(node: ts.Node | undefined): string | undefined {
+  return node && ts.isStringLiteralLike(node) ? node.text : undefined;
+}
+
+function stringArrayOf(node: ts.Node | undefined): string[] | undefined {
+  if (!node || !ts.isArrayLiteralExpression(node)) return undefined;
+  const out: string[] = [];
+  for (const element of node.elements) {
+    const value = stringLiteralOf(element);
+    if (value === undefined) return undefined;
+    out.push(value);
+  }
+  return out;
+}
+
+function propertyOf(object: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined {
+  for (const member of object.properties) {
+    if (!ts.isPropertyAssignment(member)) continue;
+    const key = ts.isIdentifier(member.name)
+      ? member.name.text
+      : (stringLiteralOf(member.name) ?? null);
+    if (key === name) return member.initializer;
+  }
+  return undefined;
+}
+
+/**
+ * What the module's default export gives this reader.
+ *
+ * The three outcomes are deliberately distinct, because two of them used to
+ * collapse into one and that collapse WAS a silent hole: `export default def`
+ * (a hoisted `const def = defineAdapter({…})`) and `defineAdapter(config)`
+ * both evaluate fine in `project-adapter.ts` — which validates the exported
+ * VALUE — while this reader saw "not a readable literal" and answered "no
+ * includes, nothing to report". The loader would honor an `include` this tier
+ * had silently dropped, which is exactly the disagreement the module docblock
+ * promises cannot happen. Both are now `'unreadable'`.
+ */
+type DefinitionRead =
+  /** A statically readable argument object (possibly with no `regions`). */
+  | { readonly kind: 'literal'; readonly literal: ts.ObjectLiteralExpression }
+  /** A zero-argument call — `nativeAdapter()`. The legitimate empty. */
+  | { readonly kind: 'empty' }
+  /** No default export at all: nothing here worth flagging; the loader is the
+   *  validation authority and an absent adapter is the native default. */
+  | { readonly kind: 'absent' }
+  /** A default export this reader cannot evaluate but the loader can. */
+  | { readonly kind: 'unreadable' };
+
+function readDefinition(source: ts.SourceFile): DefinitionRead {
+  for (const statement of source.statements) {
+    if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+    const call = statement.expression;
+    if (!ts.isCallExpression(call)) return { kind: 'unreadable' };
+    const arg = call.arguments[0];
+    if (arg === undefined) return { kind: 'empty' };
+    return ts.isObjectLiteralExpression(arg)
+      ? { kind: 'literal', literal: arg }
+      : { kind: 'unreadable' };
+  }
+  return { kind: 'absent' };
+}
+
+/** Read `regions[].include` out of one adapter source. Pure — the fs half is
+ *  `server/adapter-region-includes.ts`, so this is directly testable, and
+ *  `adapter-region-includes-conformance.test.ts` pins it against what
+ *  `parseAdapterDefinition` yields from EVALUATING the same source. */
+export function parseAdapterRegionIncludes(code: string): AdapterRegionIncludes {
+  const source = ts.createSourceFile('vgai.adapter.ts', code, ts.ScriptTarget.Latest, true);
+  const definition = readDefinition(source);
+  if (definition.kind === 'unreadable') return UNREADABLE_REGION_INCLUDES;
+  if (definition.kind !== 'literal') return EMPTY_REGION_INCLUDES;
+  const regions = propertyOf(definition.literal, 'regions');
+  const overlay = propertyOf(definition.literal, 'regionIncludes');
+  const listed = regions !== undefined && !ts.isStringLiteralLike(regions);
+  // The two forms may not be combined — `defineAdapter` rejects that pairing by
+  // name, so the module never loads. This tier declines to answer rather than
+  // reporting half of an invalid table.
+  if (listed && overlay !== undefined) return UNREADABLE_REGION_INCLUDES;
+  // Absent, or the `'manifest-roots'` RULE: the derivation runs, and the
+  // declared PARAMETERS beside it are what a native project states (decision,
+  // 2026-08-17). Neither present is a real answer — pure reach — not a gap.
+  if (!listed) return overlay ? layeredIncludes(overlay) : EMPTY_REGION_INCLUDES;
+  if (!ts.isArrayLiteralExpression(regions)) return UNREADABLE_REGION_INCLUDES;
+
+  const byRegionId = new Map<string, readonly string[]>();
+  const mountsByRegionId = new Map<string, readonly AdapterRegionMountDeclaration[]>();
+  for (const element of regions.elements) {
+    if (!ts.isObjectLiteralExpression(element)) return UNREADABLE_REGION_INCLUDES;
+    const id = stringLiteralOf(propertyOf(element, 'id'));
+    if (id === undefined) return UNREADABLE_REGION_INCLUDES;
+    const include = propertyOf(element, 'include');
+    if (include !== undefined) {
+      const globs = stringArrayOf(include);
+      if (globs === undefined) return UNREADABLE_REGION_INCLUDES;
+      byRegionId.set(id, globs);
+    }
+    const mounts = propertyOf(element, 'mounts');
+    if (mounts === undefined) continue;
+    const declared = mountArrayOf(mounts);
+    if (declared === undefined) return UNREADABLE_REGION_INCLUDES;
+    mountsByRegionId.set(id, declared);
+  }
+  return { byRegionId, mountsByRegionId, unreadable: false };
+}
+
+/**
+ * Read the LAYERED form: `regionIncludes`, the per-region parameters the
+ * `'manifest-roots'` rule takes (`@volter/editor-project/adapter/adapter-module`'s
+ * {@link AdapterDefinition.regionIncludes}, decision 2026-08-17).
+ *
+ * Statically readable BY CONSTRUCTION — it is an object literal of object
+ * literals of string arrays, sitting beside the `regions` string in the same
+ * argument object — which is exactly why the decision put the parameters here
+ * rather than behind a builder call. Anything that is NOT that literal shape
+ * (a spread, an imported table, a computed key) is `unreadable`, on the same
+ * terms as every other shape this reader declines: the loader would honor it,
+ * so silence about it would be the drift this module exists to prevent.
+ */
+function layeredIncludes(node: ts.Expression): AdapterRegionIncludes {
+  if (!ts.isObjectLiteralExpression(node)) return UNREADABLE_REGION_INCLUDES;
+  const byRegionId = new Map<string, readonly string[]>();
+  const mountsByRegionId = new Map<string, readonly AdapterRegionMountDeclaration[]>();
+  for (const member of node.properties) {
+    if (!ts.isPropertyAssignment(member)) return UNREADABLE_REGION_INCLUDES;
+    const id = ts.isIdentifier(member.name) ? member.name.text : stringLiteralOf(member.name);
+    const overlay = overlayOf(member.initializer);
+    if (id === undefined || overlay === undefined) return UNREADABLE_REGION_INCLUDES;
+    if (overlay.include) byRegionId.set(id, overlay.include);
+    if (overlay.mounts) mountsByRegionId.set(id, overlay.mounts);
+  }
+  return { byRegionId, mountsByRegionId, unreadable: false };
+}
+
+/** One `regionIncludes` entry, read literally. `undefined` for anything this
+ *  reader cannot evaluate — never a partial answer. */
+function overlayOf(
+  node: ts.Expression,
+): { include?: string[]; mounts?: AdapterRegionMountDeclaration[] } | undefined {
+  if (!ts.isObjectLiteralExpression(node)) return undefined;
+  const includeNode = propertyOf(node, 'include');
+  const include = includeNode === undefined ? undefined : stringArrayOf(includeNode);
+  if (includeNode !== undefined && include === undefined) return undefined;
+  const mountsNode = propertyOf(node, 'mounts');
+  const mounts = mountsNode === undefined ? undefined : mountArrayOf(mountsNode);
+  if (mountsNode !== undefined && mounts === undefined) return undefined;
+  return { ...(include ? { include } : {}), ...(mounts ? { mounts } : {}) };
+}
+
+/** Read a region's `mounts` array literally. `undefined` — not an empty list —
+ *  for anything this reader cannot evaluate, so the caller reports it rather
+ *  than silently dropping a surface the real loader will honor. */
+function mountArrayOf(node: ts.Expression): AdapterRegionMountDeclaration[] | undefined {
+  if (!ts.isArrayLiteralExpression(node)) return undefined;
+  const out: AdapterRegionMountDeclaration[] = [];
+  for (const element of node.elements) {
+    if (!ts.isObjectLiteralExpression(element)) return undefined;
+    const surface = stringLiteralOf(propertyOf(element, 'surface'));
+    if (surface !== 'three' && surface !== 'canvas' && surface !== 'dom') return undefined;
+    const include = propertyOf(element, 'include');
+    if (include === undefined) return undefined;
+    const globs = stringArrayOf(include);
+    if (globs === undefined || globs.length === 0) return undefined;
+    out.push({ surface, include: globs });
+  }
+  return out;
+}

package/src/ui-source/ensure-import.ts

@@ -0,0 +1,132 @@
+/**
+ * `ensureNamedImport` — make a named import available in a module, idempotently.
+ *
+ * Why this is not in `writer.ts`: that file is deliberately parser-free ("pure
+ * string ops", see its header), and an import list is the one region of a source
+ * file where a scan-based guess is genuinely unsafe — a string, a comment, or a
+ * type-only clause all look like the thing being matched. This is a real parse.
+ *
+ * The one caller is the `create`/`create-sibling` struct op
+ * (`plan-source-edit.ts`): an inserted element whose tag is a COMPONENT is broken
+ * source until its import exists, so the import rides the same plan (and therefore
+ * the same single history transaction) as the insert itself.
+ */
+
+import * as ts from 'typescript';
+import { parseAuthoringTsx } from './ts-ast';
+import type { StructEditResult } from './writer';
+
+/** Insert `name` into the module's named imports from `moduleSpecifier`, adding
+ *  the whole import statement when the module is not imported yet. Already
+ *  present ⇒ `changed: false` with the code untouched (the idempotent case every
+ *  drop after the first takes). */
+export function ensureNamedImport(
+  code: string,
+  name: string,
+  moduleSpecifier: string,
+): StructEditResult {
+  const sf = parseAuthoringTsx('module.tsx', code);
+  const imports = sf.statements.filter(ts.isImportDeclaration);
+
+  for (const declaration of imports) {
+    if (!ts.isStringLiteral(declaration.moduleSpecifier)) continue;
+    if (declaration.moduleSpecifier.text !== moduleSpecifier) continue;
+    // A type-only import of the same module cannot host a VALUE import; leave it
+    // alone and let the new-statement path below add a separate one.
+    if (declaration.importClause?.isTypeOnly) continue;
+    const bindings = declaration.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    if (bindings.elements.some((element) => element.name.text === name)) {
+      return { code, changed: false };
+    }
+    // Keep the clause alphabetical — the order every formatter in this repo's
+    // toolchain writes, so an inserted name does not read as a stray.
+    const after = bindings.elements.find((element) => element.name.text > name);
+    if (after) {
+      const at = after.getStart(sf);
+      return { code: `${code.slice(0, at)}${name}, ${code.slice(at)}`, changed: true };
+    }
+    const last = bindings.elements[bindings.elements.length - 1];
+    const at = last ? last.getEnd() : bindings.getEnd() - 1;
+    const separator = last ? ', ' : '';
+    return { code: `${code.slice(0, at)}${separator}${name}${code.slice(at)}`, changed: true };
+  }
+
+  const statement = `import { ${name} } from ${quoteOf(sf, code)}${moduleSpecifier}${quoteOf(sf, code)}${semicolonOf(imports, code)}`;
+  const lastImport = imports[imports.length - 1];
+  if (!lastImport) return { code: `${statement}\n${code}`, changed: true };
+  const at = lastImport.getEnd();
+  return { code: `${code.slice(0, at)}\n${statement}${code.slice(at)}`, changed: true };
+}
+
+/** Ensure either ecosystem-native import spelling. Component discovery knows
+ * whether a project component is a default or named export; preserving that
+ * fact avoids inventing a registry or wrapper merely to place it. */
+export function ensureValueImport(
+  code: string,
+  name: string,
+  moduleSpecifier: string,
+  kind: 'default' | 'named' = 'named',
+): StructEditResult {
+  if (kind === 'named') return ensureNamedImport(code, name, moduleSpecifier);
+  const sf = parseAuthoringTsx('module.tsx', code);
+  const imports = sf.statements.filter(ts.isImportDeclaration);
+  for (const declaration of imports) {
+    if (!importsFrom(declaration, moduleSpecifier)) continue;
+    const defaultBinding = defaultBindingStatus(declaration.importClause, name);
+    if (defaultBinding === 'same') return { code, changed: false };
+    // A module may have only one default binding per import declaration. If
+    // this file already chose another local name, import the same ecosystem
+    // value through standard ESM's named-default spelling instead of emitting
+    // a second default clause.
+    if (defaultBinding === 'different') {
+      const statement = `import { default as ${name} } from ${quoteOf(sf, code)}${moduleSpecifier}${quoteOf(sf, code)}${semicolonOf(imports, code)}`;
+      const at = declaration.getEnd();
+      return { code: `${code.slice(0, at)}\n${statement}${code.slice(at)}`, changed: true };
+    }
+  }
+  const statement = `import ${name} from ${quoteOf(sf, code)}${moduleSpecifier}${quoteOf(sf, code)}${semicolonOf(imports, code)}`;
+  const lastImport = imports[imports.length - 1];
+  if (!lastImport) return { code: `${statement}\n${code}`, changed: true };
+  const at = lastImport.getEnd();
+  return { code: `${code.slice(0, at)}\n${statement}${code.slice(at)}`, changed: true };
+}
+
+function importsFrom(declaration: ts.ImportDeclaration, moduleSpecifier: string): boolean {
+  return (
+    ts.isStringLiteral(declaration.moduleSpecifier) &&
+    declaration.moduleSpecifier.text === moduleSpecifier
+  );
+}
+
+function defaultBindingStatus(
+  clause: ts.ImportClause | undefined,
+  name: string,
+): 'same' | 'different' | 'absent' {
+  if (!clause || clause.isTypeOnly) return 'absent';
+  if (clause.name?.text === name) return 'same';
+  const named = clause.namedBindings;
+  if (
+    named &&
+    ts.isNamedImports(named) &&
+    named.elements.some(
+      (element) => element.propertyName?.text === 'default' && element.name.text === name,
+    )
+  ) {
+    return 'same';
+  }
+  return clause.name ? 'different' : 'absent';
+}
+
+/** Match the file's own import spelling rather than imposing one. */
+function quoteOf(sf: ts.SourceFile, code: string): string {
+  const first = sf.statements.find(ts.isImportDeclaration);
+  if (!first) return "'";
+  return code[first.moduleSpecifier.getStart(sf)] === '"' ? '"' : "'";
+}
+
+function semicolonOf(imports: readonly ts.ImportDeclaration[], code: string): string {
+  const last = imports[imports.length - 1];
+  if (!last) return ';';
+  return code.slice(0, last.getEnd()).trimEnd().endsWith(';') ? ';' : '';
+}