@volter/editor-core 0.5.57

package/src/inspector-presentation.ts

@@ -0,0 +1,201 @@
+/**
+ * Inspector PRESENTATION — how the inspector box is physically laid out on the
+ * surface you are looking at. Three projections (`inspection/model.ts`'s
+ * `InspectionPresentation`):
+ *
+ *  - `'column'` (the DEFAULT): the subject's full inspector as a slim vertical
+ *    column — identity row, a section-icon strip that signposts what the
+ *    subject has and jumps to a section, then every section stacked and
+ *    collapsible. With agents doing most editing the inspector's daily job is
+ *    looking, and an always-present slim column reads details with no
+ *    discovery-dependent expand gesture (owner, 2026-08-19).
+ *  - `'properties'`: the docked column with its sections TABBED — a vertical
+ *    icon rail, one section body at a time. Blender's and Substance's
+ *    properties editors are this shape; a workspace asks for it as data
+ *    (`workspace-presets.ts`, `EditorWorkspaceRegions.inspector`).
+ *  - `'card'`: the space-tight fallback the user opts into — a MINI card
+ *    (preview, name, the same icon strip, the labeled open-for-edit) that
+ *    collapses at the floor to a single-line PILL. Clicking any collapsed form
+ *    restores the column.
+ *
+ * The resolution is per SURFACE, not global (W3): the affinity is the same
+ * narrow column everywhere, but the PREFERENCE is keyed by surface, so
+ * collapsing the scene's inspector to a card leaves the asset document's
+ * alone. `resolved = user override for THIS surface ?? the active workspace's
+ * choice ?? the subject's affinity`, where the affinity is
+ * `inspectionAffinityFor(kind)`. The expand/collapse affordances write the
+ * override for the surface they are on and no other.
+ *
+ * The layout host consumes the resolution physically (column present vs
+ * overlay card vs neither); `components/Inspector.tsx` consumes it visually
+ * (narrow column vs mini card). Overrides are persisted per-user in
+ * localStorage (same convenience-not-truth rationale as
+ * `workspace-state-persistence.ts`'s storage decision), global across projects
+ * like the theme preference — how you like your inspector is not a property of
+ * any one game.
+ */
+
+import type { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import type {
+  InspectionPresentation,
+  InspectionSection,
+  InspectionSurfaceKind,
+} from './inspection/model';
+
+/** What a user can ASK for — both projections, on any surface. */
+export type InspectorPresentationOverride = InspectionPresentation;
+
+const STORAGE_KEY = 'vgai-inspector-presentation-v2';
+
+type OverrideMap = Partial<Record<InspectionSurfaceKind, InspectorPresentationOverride>>;
+
+function storage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function isOverride(value: unknown): value is InspectorPresentationOverride {
+  return value === 'card' || value === 'column' || value === 'properties';
+}
+
+function readPersisted(): OverrideMap {
+  const raw = storage()?.getItem(STORAGE_KEY);
+  if (!raw) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return {};
+    const map: OverrideMap = {};
+    for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+      if (isOverride(value)) map[key as InspectionSurfaceKind] = value;
+    }
+    return map;
+  } catch {
+    return {};
+  }
+}
+
+let _overrides: OverrideMap | null = null;
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function overrides(): OverrideMap {
+  if (_overrides === null) _overrides = readPersisted();
+  return _overrides;
+}
+
+/** The user's stored preference for one surface, or `null` when they have
+ *  never expressed one there. */
+export function inspectorPresentationOverride(
+  surface: InspectionSurfaceKind,
+): InspectorPresentationOverride | null {
+  return overrides()[surface] ?? null;
+}
+
+export function setInspectorPresentationOverride(
+  surface: InspectionSurfaceKind,
+  value: InspectorPresentationOverride,
+): void {
+  if (inspectorPresentationOverride(surface) === value) return;
+  _overrides = { ...overrides(), [surface]: value };
+  _version++;
+  try {
+    storage()?.setItem(STORAGE_KEY, JSON.stringify(_overrides));
+  } catch {
+    // Persistence is convenience; the in-memory preference is already applied.
+  }
+  for (const listener of _listeners) listener();
+}
+
+export function subscribeInspectorPresentation(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function inspectorPresentationVersion(): number {
+  return _version;
+}
+
+// ---- Resolution (pure — headlessly testable) -----------------------------
+
+/**
+ * The resolver, whole: a surface's affinity, under the active WORKSPACE's
+ * choice (`workspace-regions.ts`; only the docked layouts — a workspace never
+ * collapses the inspector to a card), under whatever the user asked for ON
+ * THAT SURFACE. Every surface is overridable — an asset document expands to
+ * the column and collapses back exactly as a scene does, because an asset
+ * document is the same paradigm scoped to a subtree.
+ */
+export function resolveInspectorPresentation(
+  affinity: InspectionPresentation,
+  override: InspectorPresentationOverride | null,
+  workspaceDefault: 'column' | 'properties' | 'card' | null = null,
+): InspectionPresentation {
+  return override ?? workspaceDefault ?? affinity;
+}
+
+export function __resetInspectorPresentationForTest(): void {
+  _overrides = null;
+  _version = 0;
+  _listeners.clear();
+  try {
+    storage()?.removeItem(STORAGE_KEY);
+  } catch {
+    // ignore
+  }
+}
+
+// ---- Section-icon-strip derivation (pure — headlessly testable) -----------
+
+/** One glyph on the section-icon strip — one SECTION of the composed
+ *  {@link InspectionSubject}, and nothing else: the live preview, Transform,
+ *  each property GROUP (Physics, Material, a component block…) and each
+ *  matched contribution individually, never one lumped "everything else"
+ *  entry. The strip signposts what the subject HAS and jumps to a section; it
+ *  is not a tab that opens one section into a floating panel. */
+export interface CompactInspectorTab {
+  /** The section's own id, which is the strip's jump target
+   *  (`'preview'`, `'transform'`, `'properties'`, `` `group:<groupId>` ``,
+   *  `'stories'`, a contribution's id). */
+  readonly id: string;
+  /** Tooltip / accessible name for the icon button. */
+  readonly title: string;
+  /** The section's own glyph. Required by the model, so every entry has one. */
+  readonly icon: IconDefinition;
+  /** The rail GROUP this section named (`InspectionSection.railGroup`), if
+   *  any. The Properties rail draws a separator wherever it changes, the way
+   *  `ED_buttons_tabs_list` inserts `BCONTEXT_SEPARATOR`
+   *  (`space_buttons/space_buttons.cc:201-255`). */
+  readonly railGroup?: string | undefined;
+  /** This section is the tab the rail opens on when nothing has been chosen
+   *  for the subject yet (`InspectionSection.railDefault`). */
+  readonly railDefault?: boolean | undefined;
+}
+
+/**
+ * The section-icon strip for a subject: its sections, in their composed order,
+ * ONE FOR ONE. This is the whole function, and that is the point — "the row of
+ * buttons is what the sections are" (owner, 2026-08-07) is true by construction
+ * here, not by two renderers agreeing. A subject with no sections has no strip
+ * and shows its headline.
+ *
+ * The strip knows nothing about what any section CONTAINS; identity, title,
+ * icon and order all come off the model (`inspection/compose.ts`). There is
+ * no synthesized entry: the live preview is an ordinary section like the rest.
+ */
+export function compactInspectorTabs(subject: {
+  readonly sections: readonly InspectionSection[];
+}): CompactInspectorTab[] {
+  return subject.sections.map((section) => ({
+    id: section.id,
+    title: section.title,
+    icon: section.icon,
+    ...(section.railGroup === undefined ? {} : { railGroup: section.railGroup }),
+    ...(section.railDefault === undefined ? {} : { railDefault: section.railDefault }),
+  }));
+}

package/src/inspector-section-registry.ts

@@ -0,0 +1,221 @@
+/**
+ * Inspector section-contribution registry (C2) — the PERMANENT, sanctioned
+ * adapter-module seam for contributing rich React sections to the ONE
+ * inspector shell. A matched registration becomes a custom-bodied
+ * `InspectionSection` in the composed subject (`inspection/compose.ts`), which
+ * both inspector presentations then project. Mirrors `hierarchy-menu-registry.ts`'s
+ * `register(match, …)` / `get(ctx)` / `__resetForTest` pattern one-for-one —
+ * same "test the pure logic headlessly" convention (no jsdom in this repo's
+ * default `vitest.config.ts` `environment: 'node'`).
+ *
+ * A contribution CLAIMS the section it provides, by id. Claiming a built-in
+ * id (`transform`, `properties`, `stories`) replaces that built-in for a
+ * matched selection — a rich typed section stands in for the thin generic
+ * grid, and the shell never double-renders the same affordance. Replacement
+ * is positive space: the contribution says what it IS, never what it hides.
+ * The composer (`inspection/compose.ts`) is the one place that resolves it.
+ *
+ * The generic property grid (`PropertyDescriptor.group` →
+ * `inspector-property-grouping.ts`'s `groupProperties()` →
+ * `ingest-group-<id>` sub-sections) is one such claimable block: it and its
+ * groups are `PROPERTIES_SECTION_ID`'s channel (see that constant), so a
+ * contribution claiming `properties` presents the node's groups too.
+ *
+ * Engine stays React-free (D6): this module, every contribution, and every
+ * `Section` component live in the editor package only.
+ */
+
+import type { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import type { AuthoringAdapter, EditorNode } from '@volter/editor-project/adapter';
+import type { ComponentType } from 'react';
+import type { InspectionSection } from './inspection/model';
+
+export interface InspectorSectionProps {
+  readonly adapter: AuthoringAdapter;
+  /** Selected node id; `null` in the no-selection (environment) state. */
+  readonly nodeId: string | null;
+}
+
+/**
+ * The composition a contribution is being matched INSIDE — the one fact
+ * `(node, adapter)` cannot carry.
+ *
+ * With nothing selected, `node` is `null` on every surface alike: an open
+ * Asset Lab document's empty state and the play surface's Game subject hand a
+ * matcher the identical two arguments, so a contribution matching `node ===
+ * null` matched both and leaked its sections into whichever empty state
+ * happened to be showing. `nullSubjectId` names the empty-state subject
+ * actually being composed (`inspection/null-subject.ts`), so a contribution
+ * scopes itself POSITIVELY to the subject it belongs to. `null` whenever a
+ * node IS selected — there is no empty-state subject in that composition.
+ */
+export interface InspectorSectionMatchContext {
+  readonly nullSubjectId: string | null;
+}
+
+/** The context handed to a match that asks for none — a selected-node
+ *  composition, and the honest default for a caller outside the shell. */
+const NO_NULL_SUBJECT: InspectorSectionMatchContext = { nullSubjectId: null };
+
+interface InspectorContributionBase {
+  /** `node` is `null` when nothing is selected (environment state); `context`
+   *  says WHICH empty state that is. */
+  readonly match: (
+    node: EditorNode | null,
+    adapter: AuthoringAdapter,
+    context: InspectorSectionMatchContext,
+  ) => boolean;
+  /**
+   * WHO SHIPPED THIS — the package (or project folder) whose module registered
+   * it (`tool-loader.ts`'s `LoadedToolContributionBase.owner`). It is what
+   * makes a document's OWNED Properties rail answerable: with
+   * `inspectorRail = 'owned'` the composer keeps the sections whose owner is
+   * the active document's own package and stands every other one down
+   * (`inspection/compose.ts`). Absent on a first-party registration made by
+   * the host itself, which is exactly the set an owned rail excludes.
+   */
+  readonly owner?: string;
+}
+
+/**
+ * A SECTION'S GLYPH, static or resolved from the subject. Blender's Object
+ * Data tab is the case that needs the second shape: `buttons_context_compute`
+ * (`space_buttons/buttons_context.cc:795-810`) sets the tab's icon from
+ * `RNA_struct_ui_icon(ptr->type)`, so a mesh's mark and an armature's differ.
+ * `inspection/compose.ts` resolves it once, at composition.
+ */
+export type InspectorSectionIcon =
+  | IconDefinition
+  | ((node: EditorNode | null, adapter: AuthoringAdapter) => IconDefinition);
+
+/**
+ * An adapter-side PRODUCER of subject data: it answers "what identified
+ * sections does this node have?" with a list, computed from the node itself.
+ *
+ * This is the shape an adapter with a rich, node-dependent inspector uses —
+ * the react/DOM adapter's Layout / Style / Position / Spacing / component-prop
+ * blocks are its descriptor GROUPS, so their identities (and how many there
+ * are) can only come from the node. Before it existed, that adapter
+ * contributed ONE section titled "React" whose body privately rendered all of
+ * them: one opaque tab on the card, one opaque block in the column, and
+ * nothing the model could name (owner, 2026-08-06 — "every section its own
+ * identified tab, no lumps").
+ *
+ * A produced section is an ordinary {@link InspectionSection}: it claims its
+ * id exactly like a static contribution does, so a produced `properties` or
+ * `group:<id>` section REPLACES the generic built-in of the same id.
+ */
+export interface InspectorSectionsProducer extends InspectorContributionBase {
+  readonly sections: (
+    node: EditorNode | null,
+    adapter: AuthoringAdapter,
+  ) => readonly InspectionSection[];
+  /** Section ids this contribution claims even when it produces no section
+   *  for them — e.g. an adapter that renders the descriptor channel itself
+   *  and must stand the generic grid down even for a node with no loose
+   *  fields. */
+  readonly claims?: readonly string[];
+}
+
+export interface InspectorSectionRegistration extends InspectorContributionBase {
+  /**
+   * The `InspectionSection` identity this contribution PROVIDES. A built-in
+   * id (`inspection/model.ts`'s `TRANSFORM_SECTION_ID`,
+   * `PROPERTIES_SECTION_ID`, `STORIES_SECTION_ID`) claims — and so replaces —
+   * that block; any other id is a section of its own. Ids are a contract: the
+   * compact card persists the active tab by id.
+   */
+  readonly id: string;
+  /** Section title — the stacked header, and the compact card's tab tooltip. */
+  readonly title: string;
+  /** Section icon — the compact card's tab glyph, or a resolver of one
+   *  ({@link InspectorSectionIcon}). */
+  readonly icon: InspectorSectionIcon;
+  /** The rail GROUP this section belongs to, where the Properties
+   *  presentation draws separators between groups — Blender's
+   *  `BCONTEXT_SEPARATOR` (`space_buttons.cc:201-255`). See
+   *  `InspectionSection.railGroup`. */
+  readonly railGroup?: string | undefined;
+  /** This is the tab the Properties rail OPENS ON before a person has chosen
+   *  one for the subject. See `InspectionSection.railDefault`. */
+  readonly railDefault?: boolean | undefined;
+  /** Display order on `InspectionSection.order`'s scale
+   *  (`CONTRIBUTED_SECTION_ORDER` unless this section belongs elsewhere). */
+  readonly order: number;
+  /** The section's body: an opaque React block the model does not model. */
+  readonly Section: ComponentType<InspectorSectionProps>;
+}
+
+/** One registration: a single identified section, or a producer of them. */
+export type InspectorSectionContribution = InspectorSectionRegistration | InspectorSectionsProducer;
+
+/** Whether this registration produces its sections from the node. */
+export function isSectionsProducer(
+  contribution: InspectorSectionContribution,
+): contribution is InspectorSectionsProducer {
+  return 'sections' in contribution;
+}
+
+const registrations: InspectorSectionContribution[] = [];
+
+// --- Change notification (W3) --------------- First-party registrations all
+// happen at import time (main.tsx side effects), before React ever renders —
+// nothing needed to observe them. W3's project inspector TOOLS register
+// asynchronously (folder scan) and re-register on HMR, while a selection may
+// already be showing — so the one inspector shell subscribes here
+// (`useSyncExternalStore`-shaped, mirroring `tool-loader.ts`'s registry
+// store) and re-renders on any (un)registration.
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyRegistryChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to (un)registrations. Returns an unsubscribe function. */
+export function subscribeInspectorSectionRegistry(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function inspectorSectionRegistryVersion(): number {
+  return _version;
+}
+
+/**
+ * Register a section contribution. `match` decides whether this contribution
+ * applies to a given selection (or the no-selection state); `Section` renders
+ * when it does. Returns an unregister function.
+ */
+export function registerInspectorSections(reg: InspectorSectionContribution): () => void {
+  registrations.push(reg);
+  notifyRegistryChanged();
+  return () => {
+    const idx = registrations.indexOf(reg);
+    if (idx >= 0) {
+      registrations.splice(idx, 1);
+      notifyRegistryChanged();
+    }
+  };
+}
+
+/** Every contribution whose `match` applies to `node`/`adapter`, in registration
+ *  order. `context` names the empty-state subject being composed; omitting it
+ *  means there is none (a selected-node composition). */
+export function matchedInspectorSections(
+  node: EditorNode | null,
+  adapter: AuthoringAdapter,
+  context: InspectorSectionMatchContext = NO_NULL_SUBJECT,
+): InspectorSectionContribution[] {
+  return registrations.filter((r) => r.match(node, adapter, context));
+}
+
+/** Test-only reset (mirrors `__resetHierarchyMenuRegistryForTest`). */
+export function __resetInspectorSectionRegistryForTest(): void {
+  registrations.length = 0;
+  notifyRegistryChanged();
+}

package/src/instance-source-actions.ts

@@ -0,0 +1,163 @@
+/**
+ * "enter the component".
+ *
+ * An instance row's two source destinations, and the sentences the editor says
+ * about them. Kept pure and adapter-free so the applicability mapping and the
+ * fallback wording are unit-testable without a DOM, a live source tree, or a
+ * mounted design session — the wiring that knows about adapters lives in
+ * `authoring/instance-source-menu.ts`.
+ *
+ * TWO DESTINATIONS, NOT ONE. Both come from the OID index, but from DIFFERENT
+ * entries of it, and conflating them is the mistake this module exists to
+ * prevent:
+ *
+ * - **callsite** — where the instance is USED (`<Enemy position={…} />` in the
+ *   world file). This is `sourceLocation(id)`, because a component boundary's
+ *   node id resolves through `userData.authoringInstance`, which the oid
+ *   transform propagates INTO the component from its callsite.
+ * - **definition** — where the component is WRITTEN (the root `<group>` inside
+ *   `Enemy.tsx`). That is the boundary object's OWN `userData.oid`, stamped by
+ *   the same transform in the file the element literally appears in.
+ *
+ * WHY "OPEN" COPIES. There is no code-editing surface in the editor workspace
+ * the dev server exposes no launch-editor route (`/__editor/reveal` opens a
+ * FILE MANAGER at a path, with no line and no caller), and `launch-editor` is
+ * not in the dependency tree — adding a dependency for this was explicitly out
+ * of scope. So "open" degrades to copying the `file:line` locator and SAYING
+ * so, which is the same honest degradation `@vgai/dom/react-inspector-section.tsx`'s
+ * `SourceLocationRow` already ships for the identical problem. Never a silent
+ * no-op.
+ */
+
+/** The subset of an OID index entry these actions need (structurally satisfied
+ *  by `OidEntry` without importing the ui-source module here). */
+export interface SourceRef {
+  readonly file: string;
+  readonly line: number;
+}
+
+/** Which of an instance row's two source destinations an action addresses. */
+export type InstanceSourceTarget = 'callsite' | 'definition';
+
+/**
+ * The minimal adapter surface an instance-source action reads. Structurally
+ * satisfied by `R3fSourceAuthoringAdapter` (which owns both methods) and by
+ * any adapter that offers only `sourceLocation` — the definition item simply
+ * never applies there, which is the honest answer rather than a fabricated one.
+ */
+export interface InstanceSourceLocator {
+  readonly sourceLocation?: ((id: string) => SourceRef | undefined) | undefined;
+  readonly definitionLocation?: ((id: string) => SourceRef | undefined) | undefined;
+}
+
+/** Menu capitalization follows the panel's existing Title Case idiom
+ *  (`Rename`, `Duplicate`, `Group Selection`, `Select Parent`). */
+export const INSTANCE_SOURCE_LABELS: Readonly<Record<InstanceSourceTarget, string>> = {
+  callsite: 'Go to Callsite',
+  definition: 'Open Component Source',
+};
+
+/** Probe order — the menu lists the callsite first (it is the row's own line of
+ *  source; the definition is one hop further away). */
+const TARGETS: readonly InstanceSourceTarget[] = ['callsite', 'definition'];
+
+/** `src/world.tsx:42` — the exact text an action copies, and the exact text the
+ *  hint then quotes back. One formatter so the two can never disagree. */
+export function formatSourceRef(ref: SourceRef): string {
+  return `${ref.file}:${ref.line}`;
+}
+
+/**
+ * Resolve one destination, or `null`. `null` covers every honest unavailability
+ * in one value: the adapter has no such accessor, the id is unknown to it, or
+ * the OID index has not landed / no longer contains that entry.
+ */
+export function locateInstanceSource(
+  locator: InstanceSourceLocator | null | undefined,
+  id: string,
+  target: InstanceSourceTarget,
+): SourceRef | null {
+  if (!locator) return null;
+  const resolve = target === 'callsite' ? locator.sourceLocation : locator.definitionLocation;
+  return resolve?.call(locator, id) ?? null;
+}
+
+/**
+ * H3 applicability: which items a row earns. A row must BOTH be a component
+ * instance (`role: 'component'` — the same predicate H1's row identity uses)
+ * and have the destination actually resolve. A row with neither destination
+ * gets neither item; nothing is ever rendered disabled here, because the
+ * registry's items have no disabled state (`getHierarchyMenuItems` returns
+ * label/action/color only) and the panel's own idiom is to omit an item whose
+ * SUBJECT is absent, reserving disabled-with-reason for a present subject the
+ * adapter refuses.
+ */
+export function instanceSourceTargets(
+  node: { readonly role?: string | undefined } | null | undefined,
+  locator: InstanceSourceLocator | null | undefined,
+  id: string,
+): InstanceSourceTarget[] {
+  if (node?.role !== 'component') return [];
+  return TARGETS.filter((target) => locateInstanceSource(locator, id, target) !== null);
+}
+
+// ------------------------------------------------------------------ sentences
+
+const SUBJECT: Readonly<Record<InstanceSourceTarget, string>> = {
+  callsite: 'callsite',
+  definition: 'component source',
+};
+
+/** What was copied, verbatim, plus why that is all the editor can do. */
+export function copiedSourceHint(target: InstanceSourceTarget, ref: SourceRef): string {
+  return (
+    `Copied the ${SUBJECT[target]} ${formatSourceRef(ref)} to the clipboard — ` +
+    'the editor has no code surface to open it in.'
+  );
+}
+
+/** The destination resolved when the menu was built and is gone by click time
+ *  (a source edit or an HMR remount between the two). */
+export function missingSourceHint(target: InstanceSourceTarget): string {
+  return `This row's ${SUBJECT[target]} is not in the source index — there is nothing to open.`;
+}
+
+/** The clipboard refused or is unavailable (insecure context, denied
+ *  permission). The locator still travels in the sentence, so the action is
+ *  never a dead end. */
+export function clipboardRefusedHint(target: InstanceSourceTarget, ref: SourceRef): string {
+  return `Could not write to the clipboard. The ${SUBJECT[target]} is ${formatSourceRef(ref)}.`;
+}
+
+// ------------------------------------------------------------------ the action
+
+/** Injected in tests; production uses the real clipboard. */
+export type ClipboardWriter = (text: string) => Promise<void>;
+
+const systemClipboard: ClipboardWriter = async (text) => {
+  const clipboard = navigator.clipboard;
+  if (!clipboard) throw new Error('no clipboard');
+  await clipboard.writeText(text);
+};
+
+/**
+ * Run one instance-source action end to end and return the sentence it should
+ * say — ALWAYS a sentence, never silence, on every path (copied / index no
+ * longer has it / clipboard refused). The caller shows it; returning it instead
+ * of raising it keeps this function testable without the hint module's timers.
+ */
+export async function runInstanceSourceAction(
+  locator: InstanceSourceLocator | null | undefined,
+  id: string,
+  target: InstanceSourceTarget,
+  writeText: ClipboardWriter = systemClipboard,
+): Promise<string> {
+  const ref = locateInstanceSource(locator, id, target);
+  if (!ref) return missingSourceHint(target);
+  try {
+    await writeText(formatSourceRef(ref));
+  } catch {
+    return clipboardRefusedHint(target, ref);
+  }
+  return copiedSourceHint(target, ref);
+}