@elabs-ai/components-editor 4.0.0

package/src/markdown-editor/milkdown-react/use-get-editor.ts

@@ -0,0 +1,56 @@
+/**
+ * Vendored + adapted from `@milkdown/react` (MIT — © 2020-present Mirone).
+ *
+ * The actual ProseMirror mount/destroy lifecycle. This is the file that matters
+ * for React 19 StrictMode: the effect kicks off an async `editor.create()` on
+ * mount and `editor.destroy()` on cleanup. StrictMode runs mount → cleanup →
+ * mount in dev, so a destroy can fire while the first create is still pending —
+ * which `@milkdown/core`'s Editor guards (it defers destroy until OnCreate
+ * settles), so the double-mount converges to a single editor. The co-located
+ * `markdown-editor.strictmode.test.tsx` is the gate that proves that convergence
+ * for our vendored copy; harden here only if that test ever shows >1 surface.
+ */
+import { createContext, useContext, useEffect, useRef } from "react";
+
+import type { EditorInfoCtx } from "./types";
+
+export const editorInfoContext = createContext<EditorInfoCtx>({} as EditorInfoCtx);
+
+export function useGetEditor() {
+  const {
+    dom,
+    editor: editorRef,
+    setLoading,
+    editorFactory: getEditor,
+  } = useContext(editorInfoContext);
+  const domRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const div = domRef.current;
+
+    if (!getEditor) return;
+    if (!div) return;
+
+    dom.current = div;
+
+    const editor = getEditor(div);
+    if (!editor) return;
+
+    setLoading(true);
+    editor
+      .create()
+      .then((editor) => {
+        editorRef.current = editor;
+      })
+      .finally(() => {
+        setLoading(false);
+      })
+      .catch(console.error);
+
+    return () => {
+      editor.destroy().catch(console.error);
+    };
+  }, [dom, editorRef, getEditor, setLoading]);
+
+  return domRef;
+}

package/src/markdown-editor/milkdown-react/use-instance.ts

@@ -0,0 +1,23 @@
+/**
+ * Vendored + adapted from `@milkdown/react` (MIT — © 2020-present Mirone).
+ *
+ * `useInstance()` reads the live editor instance from context. Returns
+ * `[loading, getInstance]`; only call `getInstance()` once `loading` is false.
+ */
+import type { Editor } from "@milkdown/kit/core";
+
+import { useCallback, useContext } from "react";
+
+import { editorInfoContext } from "./use-get-editor";
+
+export type Instance = [true, () => undefined] | [false, () => Editor];
+
+export function useInstance() {
+  const editorInfo = useContext(editorInfoContext);
+
+  const getInstance = useCallback(() => {
+    return editorInfo.editor.current;
+  }, [editorInfo.editor]);
+
+  return [editorInfo.loading, getInstance] as Instance;
+}

package/src/markdown-editor/paste-embed.ts

@@ -0,0 +1,355 @@
+/**
+ * paste-embed — ProseMirror plugin + helper for image paste/drop embedding.
+ *
+ * When `onEmbedAsset` is provided by the host:
+ *   1. Intercepts paste (from clipboard) or drop events carrying image files.
+ *   2. Inserts an inline "uploading…" widget Decoration at the caret/drop position.
+ *   3. Calls `onEmbedAsset(file)` and on resolve inserts a real image node, removing
+ *      the placeholder.
+ *   4. On reject removes the placeholder and renders a transient inline error
+ *      decoration (role="alert", auto-dismissed after 4 s) + toast.error().
+ *
+ * The plugin is a raw `$prose` ProseMirror plugin (same pattern as the slash menu),
+ * so it pulls zero new dependencies beyond what Milkdown already provides.
+ *
+ * A11y:
+ *   - Upload placeholder: role="status" aria-live="polite"
+ *   - Error decoration: role="alert" (assertive; fires once and auto-dismisses)
+ *
+ * Motion: gated via `duration-normal ease-standard motion-reduce:transition-none`
+ * token utilities (defined in @elabs-ai/components-tokens).
+ */
+
+import type { MilkdownPlugin } from "@milkdown/kit/ctx";
+import { $prose } from "@milkdown/kit/utils";
+import { Plugin, PluginKey, type Transaction } from "@milkdown/kit/prose/state";
+import { Decoration, DecorationSet } from "@milkdown/kit/prose/view";
+import type { EditorView } from "@milkdown/kit/prose/view";
+import { toast } from "@elabs-ai/components-ui";
+
+/** The host-provided hook: receives a File, resolves to a URL/path string. */
+export type EmbedAssetFn = (file: File) => Promise<string>;
+
+/** A unique key for each in-flight upload. */
+type UploadId = string;
+
+function uniqueId(): UploadId {
+  return `embed-${Math.random().toString(36).slice(2)}`;
+}
+
+/** Meta tags for the plugin's own transactions. */
+interface EmbedMetaAdd {
+  type: "add";
+  id: UploadId;
+  pos: number;
+  filename: string;
+}
+interface EmbedMetaRemove {
+  type: "remove";
+  id: UploadId;
+}
+interface EmbedMetaError {
+  type: "error";
+  id: UploadId;
+  /** Position at which the error chip should appear. */
+  pos: number;
+  message: string;
+}
+interface EmbedMetaClearError {
+  type: "clear-error";
+  id: UploadId;
+}
+type EmbedMeta = EmbedMetaAdd | EmbedMetaRemove | EmbedMetaError | EmbedMetaClearError;
+
+/** Runtime state: active upload placeholders + transient error chips. */
+interface EmbedState {
+  /** Decoration set that maps through doc changes. */
+  decos: DecorationSet;
+  /** Map from upload id → decoration for fast lookup / removal. */
+  byId: Map<UploadId, Decoration>;
+  /** Set of error ids currently showing. */
+  errorIds: Set<UploadId>;
+}
+
+const embedPluginKey = new PluginKey<EmbedState>("brand-embed");
+
+/** DOM element for the uploading placeholder chip. */
+function makePlaceholderChip(filename: string): HTMLElement {
+  const chip = document.createElement("span");
+  chip.setAttribute("role", "status");
+  chip.setAttribute("aria-live", "polite");
+  chip.setAttribute("aria-label", `Uploading ${filename}`);
+  chip.setAttribute("title", `Uploading ${filename}…`);
+  chip.className =
+    "inline-flex items-center gap-1 rounded px-2 py-0.5 text-caption bg-muted text-muted-foreground " +
+    "border border-border select-none transition-opacity duration-normal ease-standard motion-reduce:transition-none";
+
+  // SVG spinner (token-colored, no Spinner component needed here — widget is a raw DOM node)
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("aria-hidden", "true");
+  svg.style.cssText = "width:0.85em;height:0.85em;animation:spin 1s linear infinite;flex-shrink:0;";
+  const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+  circle.setAttribute("cx", "12");
+  circle.setAttribute("cy", "12");
+  circle.setAttribute("r", "9");
+  circle.setAttribute("stroke", "currentColor");
+  circle.setAttribute("stroke-width", "2.5");
+  circle.setAttribute("stroke-dasharray", "56.5");
+  circle.setAttribute("stroke-dashoffset", "42");
+  circle.setAttribute("stroke-linecap", "round");
+  svg.appendChild(circle);
+  chip.appendChild(svg);
+
+  // Ensure the keyframe is injected once per document.
+  if (!chip.ownerDocument.head.querySelector("#embed-spin-keyframe")) {
+    const style = chip.ownerDocument.createElement("style");
+    style.id = "embed-spin-keyframe";
+    style.textContent = "@keyframes spin{to{transform:rotate(360deg)}}";
+    chip.ownerDocument.head.appendChild(style);
+  }
+
+  const label = document.createElement("span");
+  label.textContent = `${filename.length > 24 ? filename.slice(0, 22) + "…" : filename} Uploading…`;
+  chip.appendChild(label);
+
+  return chip;
+}
+
+/** DOM element for the error chip (transient, auto-dismissing). */
+function makeErrorChip(message: string): HTMLElement {
+  const chip = document.createElement("span");
+  chip.setAttribute("role", "alert");
+  chip.setAttribute("aria-live", "assertive");
+  chip.setAttribute("title", message);
+  chip.className =
+    "inline-flex items-center gap-1 rounded px-2 py-0.5 text-caption bg-destructive/10 text-destructive " +
+    "border border-destructive/30 select-none";
+
+  const label = document.createElement("span");
+  label.textContent = `⚠ Upload failed`;
+  chip.appendChild(label);
+  return chip;
+}
+
+/**
+ * Core embed helper — exported so tests can call it directly against a live
+ * ProseMirror view without synthesizing ClipboardEvent/DragEvent.
+ */
+export function embedAsset(
+  view: EditorView,
+  file: File,
+  pos: number,
+  onEmbedAsset: EmbedAssetFn,
+  onError?: (msg: string) => void,
+): void {
+  const id = uniqueId();
+
+  // 1. Insert the uploading placeholder widget.
+  const addMeta: EmbedMeta = { type: "add", id, pos, filename: file.name };
+  view.dispatch(view.state.tr.setMeta(embedPluginKey, addMeta));
+
+  // 2. Call the host hook.
+  onEmbedAsset(file).then(
+    (path) => {
+      // 3a. Resolve: find the placeholder's current mapped position.
+      const pluginState = embedPluginKey.getState(view.state);
+      const deco = pluginState?.byId.get(id);
+
+      // Remove the placeholder decoration.
+      const removeMeta: EmbedMeta = { type: "remove", id };
+      const tr: Transaction = view.state.tr.setMeta(embedPluginKey, removeMeta);
+
+      if (deco) {
+        // Insert the image node at the placeholder's current mapped position.
+        const decoPos = (deco as unknown as { from: number }).from;
+        const imageNode = view.state.schema.nodes.image?.create({
+          src: path,
+          alt: file.name.replace(/\.[^.]+$/, ""),
+          title: null,
+        });
+        if (imageNode) {
+          // We need to insert the image: insert then dispatch remove separately.
+          // Insert first so the position is relative to the current doc.
+          const insertTr = view.state.tr.insert(decoPos, imageNode);
+          view.dispatch(insertTr);
+          // Now remove the deco (after the doc has shifted).
+          const removeTr = view.state.tr.setMeta(embedPluginKey, removeMeta);
+          view.dispatch(removeTr);
+          return;
+        }
+      }
+      // Fallback: just remove the placeholder.
+      view.dispatch(tr);
+    },
+    (err) => {
+      // 3b. Reject: find the placeholder position, show error.
+      const pluginState = embedPluginKey.getState(view.state);
+      const deco = pluginState?.byId.get(id);
+      const errPos = deco ? (deco as unknown as { from: number }).from : pos;
+      const message = err instanceof Error ? err.message : "Upload failed";
+
+      // Remove placeholder + add error chip.
+      const errorMeta: EmbedMeta = { type: "error", id, pos: errPos, message };
+      view.dispatch(view.state.tr.setMeta(embedPluginKey, errorMeta));
+
+      // Surface the error via toast (additional signal; not the only cue).
+      toast.error(`Upload failed: ${message}`);
+      onError?.(message);
+
+      // Auto-dismiss the error chip after 4 s.
+      setTimeout(() => {
+        if (view.isDestroyed) return;
+        const clearMeta: EmbedMeta = { type: "clear-error", id };
+        view.dispatch(view.state.tr.setMeta(embedPluginKey, clearMeta));
+      }, 4000);
+    },
+  );
+}
+
+/** Read image Files from a FileList (or null). */
+function imageFiles(list: FileList | null | undefined): File[] {
+  if (!list) return [];
+  const files: File[] = [];
+  for (let i = 0; i < list.length; i++) {
+    const f = list[i];
+    if (f && f.type.startsWith("image/")) files.push(f);
+  }
+  return files;
+}
+
+/**
+ * Build the paste-embed Milkdown plugin. Pass the `onEmbedAsset` hook from the
+ * host. When `onEmbedAsset` is undefined the plugin is still registered but never
+ * intercepts events — normal ProseMirror behavior is preserved.
+ */
+export function pasteEmbedPlugin(onEmbedAsset?: EmbedAssetFn): MilkdownPlugin {
+  return $prose(() => {
+    return new Plugin<EmbedState>({
+      key: embedPluginKey,
+      state: {
+        init: () => ({
+          decos: DecorationSet.empty,
+          byId: new Map(),
+          errorIds: new Set(),
+        }),
+        apply: (tr, prev, _oldState, newState) => {
+          // Map existing decorations through the transaction.
+          let decos = prev.decos.map(tr.mapping, tr.doc);
+          const byId = new Map(prev.byId);
+          const errorIds = new Set(prev.errorIds);
+
+          // Also map the positions stored on each deco (they're widget decorations
+          // whose .from tracks through the mapping automatically via DecorationSet.map).
+          // We just need to keep byId in sync: after mapping, find each id's deco.
+          for (const [id, oldDeco] of prev.byId.entries()) {
+            // Find the mapped deco in the new set (same key).
+            const key = (oldDeco.spec as { key?: string }).key;
+            if (key) {
+              // Re-fetch from the mapped set so .from is up to date.
+              const found = decos.find(undefined, undefined, (spec) => spec.key === key);
+              if (found.length > 0 && found[0]) {
+                byId.set(id, found[0]);
+              } else {
+                byId.delete(id);
+              }
+            }
+          }
+
+          const meta = tr.getMeta(embedPluginKey) as EmbedMeta | undefined;
+          if (!meta) return { decos, byId, errorIds };
+
+          switch (meta.type) {
+            case "add": {
+              const chip = makePlaceholderChip(meta.filename);
+              const deco = Decoration.widget(meta.pos, chip, {
+                key: `embed-placeholder:${meta.id}`,
+                side: -1,
+              });
+              decos = decos.add(newState.doc, [deco]);
+              byId.set(meta.id, deco);
+              break;
+            }
+            case "remove": {
+              const key = `embed-placeholder:${meta.id}`;
+              const toRemove = decos.find(undefined, undefined, (spec) => spec.key === key);
+              if (toRemove.length > 0) {
+                decos = decos.remove(toRemove);
+              }
+              byId.delete(meta.id);
+              errorIds.delete(meta.id);
+              break;
+            }
+            case "error": {
+              // Remove the placeholder chip.
+              const placeholderKey = `embed-placeholder:${meta.id}`;
+              const placeholders = decos.find(
+                undefined,
+                undefined,
+                (spec) => spec.key === placeholderKey,
+              );
+              if (placeholders.length > 0) {
+                decos = decos.remove(placeholders);
+              }
+              byId.delete(meta.id);
+
+              // Add the error chip.
+              const chip = makeErrorChip(meta.message);
+              const errorKey = `embed-error:${meta.id}`;
+              const deco = Decoration.widget(meta.pos, chip, { key: errorKey, side: 1 });
+              decos = decos.add(newState.doc, [deco]);
+              errorIds.add(meta.id);
+              break;
+            }
+            case "clear-error": {
+              const errorKey = `embed-error:${meta.id}`;
+              const toRemove = decos.find(undefined, undefined, (spec) => spec.key === errorKey);
+              if (toRemove.length > 0) {
+                decos = decos.remove(toRemove);
+              }
+              errorIds.delete(meta.id);
+              break;
+            }
+          }
+
+          return { decos, byId, errorIds };
+        },
+      },
+      props: {
+        decorations: (state) => embedPluginKey.getState(state)?.decos ?? DecorationSet.empty,
+
+        handlePaste: (view, event) => {
+          if (!onEmbedAsset) return false;
+          const files = imageFiles(event.clipboardData?.files);
+          if (files.length === 0) return false;
+
+          event.preventDefault();
+          const pos = view.state.selection.from;
+          for (const file of files) {
+            embedAsset(view, file, pos, onEmbedAsset);
+          }
+          return true;
+        },
+
+        handleDrop: (view, event) => {
+          if (!onEmbedAsset) return false;
+          const files = imageFiles((event as DragEvent).dataTransfer?.files);
+          if (files.length === 0) return false;
+
+          event.preventDefault();
+          // Compute drop position from coordinates.
+          const coords = view.posAtCoords({
+            left: (event as DragEvent).clientX,
+            top: (event as DragEvent).clientY,
+          });
+          const pos = coords?.pos ?? view.state.selection.from;
+          for (const file of files) {
+            embedAsset(view, file, pos, onEmbedAsset);
+          }
+          return true;
+        },
+      },
+    });
+  }) as unknown as MilkdownPlugin;
+}

package/src/markdown-editor/slash/brand-slash-commands.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Unit tests for the slash-command registry — pure data: shape, grouping, and the
+ * query filter. (The `run` insertion path is covered against a real editor in
+ * insert-directive.test.ts.)
+ */
+import type { Ctx } from "@milkdown/kit/ctx";
+import { describe, expect, test } from "vitest";
+
+import type {
+  IterationEditHandler,
+  IterationEditRequest,
+} from "../../markdown-iteration/edit-context";
+import {
+  BRAND_SLASH_COMMANDS,
+  filterSlashCommands,
+  groupSlashCommands,
+} from "./brand-slash-commands";
+
+describe("BRAND_SLASH_COMMANDS shape", () => {
+  test("every command has a unique id, a label, a group, and a run", () => {
+    const ids = new Set<string>();
+    for (const c of BRAND_SLASH_COMMANDS) {
+      expect(typeof c.id).toBe("string");
+      expect(c.id.length).toBeGreaterThan(0);
+      expect(ids.has(c.id)).toBe(false);
+      ids.add(c.id);
+      expect(typeof c.label).toBe("string");
+      expect(c.label.length).toBeGreaterThan(0);
+      expect(typeof c.group).toBe("string");
+      expect(typeof c.run).toBe("function");
+    }
+  });
+
+  test("covers the four brand directives + the basic blocks", () => {
+    const labels = BRAND_SLASH_COMMANDS.map((c) => c.label);
+    expect(labels).toEqual(expect.arrayContaining(["Card", "Callout", "Metric", "Timeline"]));
+    expect(labels).toEqual(
+      expect.arrayContaining([
+        "Heading",
+        "Bullet list",
+        "Numbered list",
+        "Quote",
+        "Code block",
+        "Divider",
+      ]),
+    );
+  });
+
+  test("brand blocks are in the 'Brand blocks' group, basics in 'Basic'", () => {
+    const brand = BRAND_SLASH_COMMANDS.filter((c) => c.group === "Brand blocks");
+    const basic = BRAND_SLASH_COMMANDS.filter((c) => c.group === "Basic");
+    expect(brand.map((c) => c.label)).toEqual([
+      "Card",
+      "Callout",
+      "Metric",
+      "Timeline",
+      "Iterate",
+      "Pivot",
+      "Calc",
+    ]);
+    expect(basic.length).toBe(6);
+  });
+
+  test("the /calc command (#220) is registered and inserts a calc fence", () => {
+    const calc = BRAND_SLASH_COMMANDS.find((c) => c.id === "brand-calc");
+    expect(calc).toBeDefined();
+    expect(calc?.label).toBe("Calc");
+    expect(calc?.keywords).toEqual(expect.arrayContaining(["calc", "math", "formula"]));
+  });
+});
+
+describe("filterSlashCommands", () => {
+  test("an empty query returns the full list in order", () => {
+    expect(filterSlashCommands(BRAND_SLASH_COMMANDS, "")).toBe(BRAND_SLASH_COMMANDS);
+    expect(filterSlashCommands(BRAND_SLASH_COMMANDS, "   ")).toBe(BRAND_SLASH_COMMANDS);
+  });
+
+  test("matches on the label (case-insensitive substring)", () => {
+    const r = filterSlashCommands(BRAND_SLASH_COMMANDS, "ca");
+    const labels = r.map((c) => c.label);
+    // "ca" matches Card + Callout (label) and others via keywords.
+    expect(labels).toEqual(expect.arrayContaining(["Card", "Callout"]));
+  });
+
+  test("matches on keywords too (e.g. 'kpi' → Metric)", () => {
+    const r = filterSlashCommands(BRAND_SLASH_COMMANDS, "kpi");
+    expect(r.map((c) => c.label)).toContain("Metric");
+  });
+
+  test("matches 'alert' → Callout via keyword", () => {
+    const r = filterSlashCommands(BRAND_SLASH_COMMANDS, "alert");
+    expect(r.map((c) => c.label)).toContain("Callout");
+  });
+
+  test("a no-match query returns an empty list", () => {
+    expect(filterSlashCommands(BRAND_SLASH_COMMANDS, "zzzznotacommand")).toHaveLength(0);
+  });
+});
+
+describe("groupSlashCommands", () => {
+  test("preserves first-seen group order and keeps every command", () => {
+    const grouped = groupSlashCommands(BRAND_SLASH_COMMANDS);
+    expect(grouped.map((g) => g.group)).toEqual(["Brand blocks", "Basic"]);
+    const total = grouped.reduce((n, g) => n + g.commands.length, 0);
+    expect(total).toBe(BRAND_SLASH_COMMANDS.length);
+  });
+
+  test("a filtered list groups correctly (only matching groups appear)", () => {
+    const filtered = filterSlashCommands(BRAND_SLASH_COMMANDS, "card");
+    const grouped = groupSlashCommands(filtered);
+    // "card" only matches a brand block → only the Brand blocks group shows.
+    expect(grouped.map((g) => g.group)).toEqual(["Brand blocks"]);
+  });
+});
+
+describe("source-mode snippets (A4 — source/split Insert-menu parity)", () => {
+  test("every Brand block carries a markdown snippet; basics carry none", () => {
+    for (const c of BRAND_SLASH_COMMANDS) {
+      if (c.group === "Brand blocks") {
+        expect(typeof c.snippet).toBe("string");
+        expect((c.snippet ?? "").length).toBeGreaterThan(0);
+      } else {
+        expect(c.snippet).toBeUndefined();
+      }
+    }
+  });
+
+  test("each snippet carries the matching directive / fence marker", () => {
+    const byId = new Map(BRAND_SLASH_COMMANDS.map((c) => [c.id, c.snippet ?? ""]));
+    expect(byId.get("brand-card")).toContain(":::card");
+    expect(byId.get("brand-callout")).toContain(":::callout");
+    expect(byId.get("brand-metric")).toContain("::metric");
+    expect(byId.get("brand-timeline")).toContain(":::timeline");
+    expect(byId.get("brand-iterate")).toContain(":::iterate");
+    expect(byId.get("brand-pivot")).toContain(":::pivot");
+    expect(byId.get("brand-calc")).toContain("```calc");
+  });
+
+  test("iterate / pivot snippets seed a template token so the block isn't empty", () => {
+    const byId = new Map(BRAND_SLASH_COMMANDS.map((c) => [c.id, c.snippet ?? ""]));
+    expect(byId.get("brand-iterate")).toContain("{{item.name}}");
+    expect(byId.get("brand-pivot")).toContain("{{cell}}");
+  });
+});
+
+describe("guided commands (#223 — /iterate and /pivot open the guided modal when wired)", () => {
+  test("only iterate and pivot carry a `guided` variant", () => {
+    const byId = new Map(BRAND_SLASH_COMMANDS.map((c) => [c.id, c]));
+    expect(typeof byId.get("brand-iterate")?.guided).toBe("function");
+    expect(typeof byId.get("brand-pivot")?.guided).toBe("function");
+    for (const id of [
+      "brand-card",
+      "brand-callout",
+      "brand-metric",
+      "brand-timeline",
+      "brand-calc",
+    ]) {
+      expect(byId.get(id)?.guided).toBeUndefined();
+    }
+  });
+
+  test("guided path: iterate emits an edit request seeded BLANK (no values, default template) — not a bare insert", () => {
+    const iterate = BRAND_SLASH_COMMANDS.find((c) => c.id === "brand-iterate")!;
+    let captured: IterationEditRequest | undefined;
+    const handler: IterationEditHandler = (request) => {
+      captured = request;
+    };
+    iterate.guided!({ ctx: {} as Ctx, range: null }, handler);
+    expect(captured?.kind).toBe("iterate");
+    expect(captured?.attributes).toEqual({});
+    expect(captured?.template).toBe("{{item.name}}");
+    expect(typeof captured?.onSave).toBe("function");
+    expect(typeof captured?.onSaveData).toBe("function");
+  });
+
+  test("guided path: pivot emits an edit request seeded with the pivot default template", () => {
+    const pivot = BRAND_SLASH_COMMANDS.find((c) => c.id === "brand-pivot")!;
+    let captured: IterationEditRequest | undefined;
+    pivot.guided!({ ctx: {} as Ctx, range: null }, (request) => {
+      captured = request;
+    });
+    expect(captured?.kind).toBe("pivot");
+    expect(captured?.attributes).toEqual({});
+    expect(captured?.template).toBe("{{row}} · {{col}}");
+  });
+
+  test("fallback path: without a handler, `run` still inserts the bare directive directly (unchanged)", () => {
+    // Covered end-to-end (against a real ProseMirror doc) in insert-directive.test.ts;
+    // this only asserts the command still exposes the plain `run` unconditionally, so
+    // a consumer with no IterationEditContext wired keeps today's behaviour.
+    const iterate = BRAND_SLASH_COMMANDS.find((c) => c.id === "brand-iterate")!;
+    expect(typeof iterate.run).toBe("function");
+  });
+});