@ai-matrx/rich-editor 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.1
+### The toolbar measures its layout width (2026-10-08)
+
+- `FormatButtons` folds by the row's layout width (`clientWidth`), not its painted box: in a dialog that opens with a scale animation it measured a shrunken rect and kept only Bold and Italic.
+
+Consumer action: none.
+
+## 0.5.0
+### Write behaves like a notes app (2026-10-08)
+
+- **Typed markdown converts** (`core/typing-rules.ts`, in the schema extensions): `[] `, `[ ] `, `[x] ` at a line's start make a checklist item; `- [ ] ` / `* [ ] ` turn the bullet into a task; an address followed by a space (`https://…`, `www.…`) becomes a link stored bare; `![alt](url) ` becomes an image. Only on the key press that completes the pattern — load, paste and drags never convert.
+- **Table menu**: while the caret is in a table, a handle on its top-right corner opens add row above/below, add column left/right, Header row (on/off — off stores GFM's empty header line), delete row/column/table (`visual/table-menu.ts`, `visual/TableHandle.tsx`). `core/commands.ts` adds `toggleTableHeaderRow` / `tableHeaderRowShown`.
+- **Image**: a new `image` format command. `FormatButtons` always has More, and More always holds **Image**. In Write it opens the image prompt — paste an address, or upload a file (uploaded to the platform's files as before); text engines insert `![alt](https://)` with the address selected. The `/image` slash item opens the same prompt.
+- **`format/editor-keys`**: `editorOwnsKeyEvent(event)` — true inside a format host, a contenteditable or a CodeMirror view. App-wide shortcuts (the shell's ⌘K bar) stand down there so ⌘K is the editor's link prompt.
+
+Consumer action: an app-wide ⌘K (or other chord) listener calls `editorOwnsKeyEvent(e)` and skips when true. A host with an exhaustive `Record<FormatCommandId, …>` adds `image`.
+
 ## 0.4.3
 ### `chrome="format"`: the toolbar for hosts with no row of their own (2026-10-08)
 

package/dist/core/commands.d.ts

@@ -63,3 +63,6 @@ export type ColumnAlignment = "left" | "center" | "right" | null;
  * rewritten and nothing else in the table moves.
  */
 export declare function setColumnAlign(editor: Editor, align: ColumnAlignment): boolean;
+/** Is the caret's table showing a header row (a first row with any text)? */
+export declare function tableHeaderRowShown(editor: Editor): boolean;
+export declare function toggleTableHeaderRow(editor: Editor): boolean;

package/dist/core/commands.js

@@ -269,6 +269,55 @@ function setColumnAlign(editor, align) {
     return true;
   });
 }
+function tableAt(editor) {
+  const { $from } = editor.state.selection;
+  for (let depth = $from.depth; depth > 0; depth -= 1) {
+    const node = $from.node(depth);
+    if (node.type.name === "table") return { table: node, pos: $from.before(depth) };
+  }
+  return null;
+}
+function tableHeaderRowShown(editor) {
+  const found = tableAt(editor);
+  return Boolean(found?.table.firstChild && found.table.firstChild.textContent.trim().length > 0);
+}
+function toggleTableHeaderRow(editor) {
+  const found = tableAt(editor);
+  if (!found) return false;
+  const { table, pos } = found;
+  const { schema } = editor.state;
+  const headerType = schema.nodes.tableHeader;
+  const cellType = schema.nodes.tableCell;
+  const rowType = schema.nodes.tableRow;
+  const paragraph = schema.nodes.paragraph;
+  const first = table.firstChild;
+  if (!headerType || !cellType || !rowType || !paragraph || !first) return false;
+  const shown = first.textContent.trim().length > 0;
+  if (!shown && table.childCount < 2) return false;
+  return editor.chain().focus().command(({ tr }) => {
+    const rowPos = pos + 1;
+    if (shown) {
+      let cellPos = rowPos + 1;
+      first.forEach((cell) => {
+        tr.setNodeMarkup(cellPos, cellType, cell.attrs);
+        cellPos += cell.nodeSize;
+      });
+      const cells = [];
+      first.forEach((cell) => cells.push(headerType.create({ align: cell.attrs.align ?? null }, paragraph.create())));
+      tr.insert(rowPos, rowType.create(null, cells));
+    } else {
+      tr.delete(rowPos, rowPos + first.nodeSize);
+      const promoted = tr.doc.nodeAt(rowPos);
+      if (!promoted) return false;
+      let cellPos = rowPos + 1;
+      promoted.forEach((cell) => {
+        tr.setNodeMarkup(cellPos, headerType, cell.attrs);
+        cellPos += cell.nodeSize;
+      });
+    }
+    return true;
+  }).run();
+}
 export {
   CALLOUT_TYPES,
   TASK_DONE,
@@ -292,6 +341,8 @@ export {
   replaceIslandRaw,
   setCallout,
   setColumnAlign,
+  tableHeaderRowShown,
+  toggleTableHeaderRow,
   toggleTaskChecked,
   toggleTaskList,
   topLevelAt,

package/dist/core/extensions.js

@@ -21,6 +21,7 @@ import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table
 import { Dropcursor, Focus, Gapcursor, Placeholder, UndoRedo } from "@tiptap/extensions";
 import { MarkdownTextPaste } from "./paste-markdown.js";
 import { ClipboardPlainText } from "./clipboard-text.js";
+import { MarkdownTypingRules } from "./typing-rules.js";
 const mdAttr = () => ({ default: null, rendered: false, keepOnSplit: false });
 const MD_ID_NODE_TYPES = [
   "paragraph",
@@ -310,7 +311,8 @@ function createRichEditorExtensions(options = {}) {
     Dropcursor,
     Placeholder.configure({ placeholder: options.placeholder ?? "Write\u2026" }),
     MarkdownTextPaste.configure({ onNotice: options.onPasteNotice ?? null }),
-    ClipboardPlainText
+    ClipboardPlainText,
+    MarkdownTypingRules
   ];
   return list.map((extension) => extension.extend({ addPasteRules: () => [] }));
 }

package/dist/core/markdown-format.d.ts

@@ -1,5 +1,5 @@
 import type { SourceEditResult } from "./source-format.js";
-export type FormatCommandId = "bold" | "italic" | "strike" | "code" | "link" | "heading1" | "heading2" | "heading3" | "bulletList" | "orderedList" | "taskList" | "quote" | "codeBlock" | "paragraph" | "table" | "horizontalRule" | "undo" | "redo";
+export type FormatCommandId = "bold" | "italic" | "strike" | "code" | "link" | "heading1" | "heading2" | "heading3" | "bulletList" | "orderedList" | "taskList" | "quote" | "codeBlock" | "paragraph" | "table" | "horizontalRule" | "image" | "undo" | "redo";
 export declare const FORMAT_COMMAND_IDS: readonly FormatCommandId[];
 export declare function isFormatCommandId(id: string): id is FormatCommandId;
 /** Run one formatting command on markdown text. Returns the minimal change. */

package/dist/core/markdown-format.js

@@ -16,6 +16,7 @@ const FORMAT_COMMAND_IDS = [
   "paragraph",
   "table",
   "horizontalRule",
+  "image",
   "undo",
   "redo"
 ];
@@ -390,11 +391,19 @@ function formatMarkdown(text, from, to, command) {
       return insertBlockAfter(text, a, b, "| Column 1 | Column 2 | Column 3 |\n| --- | --- | --- |\n|  |  |  |\n|  |  |  |", 2, 8);
     case "horizontalRule":
       return insertBlockAfter(text, a, b, "---", null, 0);
+    case "image":
+      return imageCommand(text, a, b);
     case "undo":
     case "redo":
       return { changes: [], anchor: a, head: b };
   }
 }
+function imageCommand(text, from, to) {
+  const alt = text.slice(from, to).replace(/[[\]\n]/g, " ").trim() || "image";
+  const insert = `![${alt}](https://)`;
+  const urlStart = from + 2 + alt.length + 2;
+  return { changes: [{ from, to, insert }], anchor: urlStart, head: urlStart + "https://".length };
+}
 function paragraphCommand(text, from, to) {
   const changes = [];
   for (const line of linesTouched(text, from, to)) {
@@ -455,6 +464,7 @@ function isFormatActive(text, from, to, command) {
     case "codeBlock":
     case "table":
     case "horizontalRule":
+    case "image":
     case "undo":
     case "redo":
       return false;
@@ -486,6 +496,7 @@ const FORMAT_COMMAND_KEYS = {
   paragraph: ["Mod-Alt-0"],
   table: [],
   horizontalRule: [],
+  image: [],
   // The engine's own history answers ⌘Z / ⌘⇧Z; a host never rebinds them.
   undo: [],
   redo: []

package/dist/core/typing-rules.d.ts

@@ -0,0 +1,11 @@
+import { Extension } from "@tiptap/core";
+/** `[ ] ` / `[] ` / `[x] ` typed at the very start of a line. */
+export declare const TASK_TYPED: RegExp;
+/** An address followed by the whitespace that ends it. */
+export declare const URL_TYPED: RegExp;
+/** `![alt](url)` followed by whitespace. */
+export declare const IMAGE_TYPED: RegExp;
+/** Trailing punctuation is sentence, not address (GFM's extended-autolink rule). */
+export declare function trimUrl(url: string): string;
+/** The typed-markdown conversions (header). Image first: its URL must never be autolinked. */
+export declare const MarkdownTypingRules: Extension<any, any>;

package/dist/core/typing-rules.js

@@ -0,0 +1,96 @@
+import { Extension, InputRule } from "@tiptap/core";
+import { findWrapping } from "@tiptap/pm/transform";
+import { TASK_DONE, TASK_OPEN } from "./commands.js";
+const TASK_TYPED = /^\s*\[([ xX]?)\]\s$/;
+const URL_TYPED = /(?:^|\s)((?:https?:\/\/|www\.)[^\s<>]+)(\s)$/;
+const IMAGE_TYPED = /!\[([^\]\n]*)\]\(([^()\s]+)\)(\s)$/;
+function trimUrl(url) {
+  let out = url.replace(/[.,;:!?'"*_~]+$/, "");
+  while (out.endsWith(")") && (out.match(/\(/g)?.length ?? 0) < (out.match(/\)/g)?.length ?? 0)) {
+    out = out.slice(0, -1).replace(/[.,;:!?'"*_~]+$/, "");
+  }
+  return out;
+}
+function listItemDepth($from) {
+  for (let depth = $from.depth; depth > 0; depth -= 1) {
+    if ($from.node(depth).type.name === "listItem") return depth;
+  }
+  return -1;
+}
+const taskRule = new InputRule({
+  find: TASK_TYPED,
+  handler: ({ state, range, match }) => {
+    const { tr } = state;
+    const mdTask = /[xX]/.test(match[1] ?? "") ? TASK_DONE : TASK_OPEN;
+    const $from = state.doc.resolve(range.from);
+    const textblock = $from.parent;
+    if (textblock.type.name !== "paragraph") return null;
+    const itemDepth = listItemDepth($from);
+    tr.delete(range.from, range.to);
+    if (itemDepth !== -1 && $from.index(itemDepth) === 0) {
+      const itemPos = $from.before(itemDepth);
+      const item = tr.doc.nodeAt(itemPos);
+      if (!item) return null;
+      tr.setNodeMarkup(itemPos, void 0, { ...item.attrs, mdTask });
+      return void 0;
+    }
+    const bulletList = state.schema.nodes.bulletList;
+    const listItem = state.schema.nodes.listItem;
+    if (!bulletList || !listItem) return null;
+    const $start = tr.doc.resolve(tr.mapping.map(range.from));
+    const blockRange = $start.blockRange();
+    const wrapping = blockRange && findWrapping(blockRange, bulletList);
+    if (!blockRange || !wrapping) return null;
+    tr.wrap(
+      blockRange,
+      wrapping.map((wrap) => wrap.type === listItem ? { type: listItem, attrs: { ...wrap.attrs, mdTask } } : wrap)
+    );
+    return void 0;
+  }
+});
+const imageRule = new InputRule({
+  find: IMAGE_TYPED,
+  handler: ({ state, range, match }) => {
+    const island = state.schema.nodes.inlineIsland;
+    if (!island || state.doc.resolve(range.from).parent.type.spec.code) return null;
+    const alt = (match[1] ?? "").replace(/[[\]]/g, "");
+    const url = match[2] ?? "";
+    const space = match[3] ?? " ";
+    const { tr } = state;
+    tr.replaceWith(range.from, range.to, island.create({ raw: `![${alt}](${url})`, islandType: "md_image" }));
+    tr.insertText(space, tr.mapping.map(range.to));
+    return void 0;
+  }
+});
+const urlRule = new InputRule({
+  find: URL_TYPED,
+  handler: ({ state, range, match }) => {
+    const link = state.schema.marks.link;
+    const typed = match[1] ?? "";
+    const url = trimUrl(typed);
+    if (!link || url.length < 5 || /^www\.$/i.test(url)) return null;
+    const start = range.from + match[0].indexOf(typed);
+    const end = start + url.length;
+    if (state.doc.rangeHasMark(start, end, link)) return null;
+    const $start = state.doc.resolve(start);
+    if ($start.parent.type.spec.code || $start.marks().some((mark) => mark.type.name === "code")) return null;
+    const href = /^www\./i.test(url) ? `https://${url}` : url;
+    const { tr } = state;
+    tr.addMark(start, end, link.create({ href, mdForm: "bare", mdTailHref: href, mdText: url }));
+    tr.removeStoredMark(link);
+    return void 0;
+  }
+});
+const MarkdownTypingRules = Extension.create({
+  name: "richEditorTypingRules",
+  addInputRules() {
+    return [taskRule, imageRule, urlRule];
+  }
+});
+export {
+  IMAGE_TYPED,
+  MarkdownTypingRules,
+  TASK_TYPED,
+  URL_TYPED,
+  trimUrl
+};

package/dist/editor/RichEditorImpl.js

@@ -135,6 +135,7 @@ function RichEditorImpl({
   const [saving, setSaving] = useState(false);
   const [saveState, setSaveState] = useState(null);
   const [linkDialog, setLinkDialog] = useState({ open: false, href: "" });
+  const [imageDialogOpen, setImageDialogOpen] = useState(false);
   const [kindRequest, setKindRequest] = useState(null);
   const approved = useRef(/* @__PURE__ */ new Set());
   const handle = useRef(null);
@@ -256,7 +257,11 @@ function RichEditorImpl({
     }
     void doSave(plan);
   };
-  const pickImage = () => imageInput.current?.click();
+  const pickImage = () => setImageDialogOpen(true);
+  const uploadImageFile = () => {
+    setImageDialogOpen(false);
+    imageInput.current?.click();
+  };
   const uploadImage = async (file) => {
     try {
       const uploaded = await upload({ kind: "file", file }, { folderPath: "Editor images" });
@@ -695,6 +700,36 @@ function RichEditorImpl({
         }
       }
     ),
+    /* @__PURE__ */ jsx(
+      TextInputDialog,
+      {
+        open: imageDialogOpen,
+        onOpenChange: setImageDialogOpen,
+        title: "Image",
+        description: /* @__PURE__ */ jsxs("span", { children: [
+          "Paste the image address, or",
+          " ",
+          /* @__PURE__ */ jsx("button", { type: "button", "data-image-upload": "", className: "font-medium text-primary underline-offset-2 hover:underline", onClick: uploadImageFile, children: "upload a file" }),
+          "."
+        ] }),
+        placeholder: "https://",
+        defaultValue: "",
+        confirmLabel: "Insert",
+        validate: (value2) => /^(https?:\/\/|\/)\S+$/i.test(value2.trim()) ? null : "Paste an address that starts with https://",
+        onConfirm: (href) => {
+          const url = href.trim();
+          const last = url.split(/[?#]/)[0].split("/").pop() ?? "";
+          let name = last;
+          try {
+            name = decodeURIComponent(last);
+          } catch {
+          }
+          const alt = name.replace(/\.[^.]+$/, "").replace(/[[\]]/g, "") || "image";
+          handle.current?.replaceSelection(`![${alt}](${url})`);
+          setImageDialogOpen(false);
+        }
+      }
+    ),
     /* @__PURE__ */ jsx(
       "input",
       {

package/dist/format/FormatButtons.d.ts

@@ -11,6 +11,8 @@ export interface FormatButtonSpec {
 export declare const BLOCK_STYLES: readonly FormatButtonSpec[];
 /** The toolbar, in its groups (a divider between each). The text-style menu sits after history. */
 export declare const FORMAT_GROUPS: readonly (readonly FormatButtonSpec[])[];
+/** Always under More (never a strip button): inserts people reach for less often. */
+export declare const MORE_ONLY: readonly FormatButtonSpec[];
 /** Every button the toolbar shows, in order (the text-style menu aside). */
 export declare const FORMAT_BUTTONS: readonly FormatButtonSpec[];
 /** The phone set (Arman, 2026-10-07): text style, B, I, list, checklist, link — the rest under More. */

package/dist/format/FormatButtons.js

@@ -10,6 +10,7 @@ import {
   Heading2,
   Heading3,
   Italic,
+  Image as ImageIcon,
   Link2,
   List,
   ListChecks,
@@ -52,6 +53,7 @@ const FORMAT_GROUPS = [
   [spec("link", "Link", Link2)],
   [spec("codeBlock", "Code block", SquareCode), spec("table", "Table", Table), spec("horizontalRule", "Horizontal rule", Minus)]
 ];
+const MORE_ONLY = [spec("image", "Image", ImageIcon)];
 const FORMAT_BUTTONS = FORMAT_GROUPS.flat();
 const ESSENTIAL_COMMANDS = ["bold", "italic", "bulletList", "taskList", "link"];
 const KEEP = {
@@ -131,7 +133,7 @@ function FormatButtons({ resolve, disabled = false, className, size = "sm", vari
   React.useEffect(() => {
     const el = rootRef.current;
     if (!el || typeof ResizeObserver === "undefined") return void 0;
-    const ro = new ResizeObserver(() => setWidth(el.getBoundingClientRect().width));
+    const ro = new ResizeObserver(() => setWidth(el.clientWidth || el.getBoundingClientRect().width));
     ro.observe(el);
     return () => ro.disconnect();
   }, []);
@@ -155,7 +157,7 @@ function FormatButtons({ resolve, disabled = false, className, size = "sm", vari
   let kept = all;
   let folded = variant === "essential" ? slotsOf("full").filter((s) => s.kind === "button" && !ESSENTIAL_COMMANDS.includes(s.spec.command)) : [];
   const rowWidth = (slots, more) => withDividers(slots).reduce((sum, s) => sum + widthOf(s), 0) + (more ? button : 0);
-  if (width > 0 && rowWidth(kept, folded.length > 0) > width + 4) {
+  if (width > 0 && rowWidth(kept, true) > width + 4) {
     const byKeep = [...all].sort((x, y) => keepOf(x) - keepOf(y));
     const dropped = /* @__PURE__ */ new Set();
     for (const slot of byKeep) {
@@ -234,7 +236,7 @@ function FormatButtons({ resolve, disabled = false, className, size = "sm", vari
             command
           );
         }),
-        (foldedButtons.length > 0 || styleFolded) && /* @__PURE__ */ jsxs(DropdownMenu, { children: [
+        (foldedButtons.length > 0 || styleFolded || MORE_ONLY.length > 0) && /* @__PURE__ */ jsxs(DropdownMenu, { children: [
           /* @__PURE__ */ jsx(DropdownMenuTrigger, { asChild: true, children: /* @__PURE__ */ jsx("button", { type: "button", "aria-label": "More formatting", title: "More formatting", "data-format-more": "", "data-matrx-button": "", className: buttonClass, children: /* @__PURE__ */ jsx(MoreHorizontal, { className: iconClass }) }) }),
           /* @__PURE__ */ jsxs(DropdownMenuContent, { align: "end", className: "w-56", onCloseAutoFocus: keepEditorFocus, children: [
             styleFolded && BLOCK_STYLES.map((style) => /* @__PURE__ */ jsxs(DropdownMenuItem, { "data-format-command": style.command, onSelect: () => run(style.command), children: [
@@ -247,6 +249,11 @@ function FormatButtons({ resolve, disabled = false, className, size = "sm", vari
               /* @__PURE__ */ jsx(b.icon, { className: "mr-2 h-4 w-4" }),
               /* @__PURE__ */ jsx("span", { className: "flex-1", children: b.label }),
               b.command !== "undo" && b.command !== "redo" && isActive(b.command) && /* @__PURE__ */ jsx(Check, { className: "ml-2 h-4 w-4 text-primary" })
+            ] }, b.command)),
+            (styleFolded || foldedButtons.length > 0) && /* @__PURE__ */ jsx(DropdownMenuSeparator, {}),
+            MORE_ONLY.map((b) => /* @__PURE__ */ jsxs(DropdownMenuItem, { "data-format-command": b.command, onSelect: () => run(b.command), children: [
+              /* @__PURE__ */ jsx(b.icon, { className: "mr-2 h-4 w-4" }),
+              /* @__PURE__ */ jsx("span", { className: "flex-1", children: b.label })
             ] }, b.command))
           ] })
         ] })
@@ -261,5 +268,6 @@ export {
   FORMAT_BUTTONS,
   FORMAT_GROUPS,
   FormatButtons,
+  MORE_ONLY,
   FormatButtons_default as default
 };

package/dist/format/editor-keys.d.ts

@@ -0,0 +1,4 @@
+/** True when `target` (else the focused element) sits inside an editor. */
+export declare function insideEditor(target: EventTarget | null | undefined): boolean;
+/** True when a key press belongs to the editor it was pressed in (shell shortcuts skip it). */
+export declare function editorOwnsKeyEvent(event: Pick<KeyboardEvent, "target">): boolean;

package/dist/format/editor-keys.js

@@ -0,0 +1,14 @@
+const EDITOR_SELECTOR = "[data-format-host], [contenteditable=''], [contenteditable='true'], [contenteditable='plaintext-only'], .cm-editor";
+function insideEditor(target) {
+  const element = target && typeof target.closest === "function" ? target : typeof document !== "undefined" ? document.activeElement : null;
+  if (!element || typeof element.closest !== "function") return false;
+  if (element.closest(EDITOR_SELECTOR)) return true;
+  return element.isContentEditable === true;
+}
+function editorOwnsKeyEvent(event) {
+  return insideEditor(event.target);
+}
+export {
+  editorOwnsKeyEvent,
+  insideEditor
+};

package/dist/visual/TableHandle.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+import type { Editor } from "@tiptap/core";
+export declare function TableHandle({ editor, container }: {
+    editor: Editor | null;
+    container: RefObject<HTMLDivElement | null>;
+}): import("react").JSX.Element | null;

package/dist/visual/TableHandle.js

@@ -0,0 +1,129 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import {
+  cn,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from "@ai-matrx/design-system";
+import {
+  ArrowDownToLine,
+  ArrowLeftToLine,
+  ArrowRightToLine,
+  ArrowUpToLine,
+  Check,
+  Columns3,
+  Heading,
+  Rows3,
+  Table2,
+  Trash2
+} from "lucide-react";
+import { useRichEditorContext } from "../editor/RichEditorContext.js";
+import { TABLE_MENU } from "./table-menu.js";
+const ICONS = {
+  "row-above": ArrowUpToLine,
+  "row-below": ArrowDownToLine,
+  "col-left": ArrowLeftToLine,
+  "col-right": ArrowRightToLine,
+  "header-row": Heading,
+  "del-row": Rows3,
+  "del-col": Columns3,
+  "del-table": Trash2
+};
+function anchorOf(editor, host) {
+  if (editor.isDestroyed || !editor.isEditable || !editor.isActive("table")) return null;
+  const { $from } = editor.state.selection;
+  for (let depth = $from.depth; depth > 0; depth -= 1) {
+    if ($from.node(depth).type.name !== "table") continue;
+    const dom = editor.view.nodeDOM($from.before(depth));
+    const element = dom instanceof HTMLElement ? dom.closest(".tableWrapper") ?? dom : null;
+    if (!element) return null;
+    const box = element.getBoundingClientRect();
+    const hostBox = host.getBoundingClientRect();
+    return { top: box.top - hostBox.top + host.scrollTop, right: hostBox.right - box.right };
+  }
+  return null;
+}
+function TableHandle({ editor, container }) {
+  const context = useRichEditorContext();
+  const [anchor, setAnchor] = useState(null);
+  const [menuOpen, setMenuOpen] = useState(false);
+  useEffect(() => {
+    const host = container.current;
+    if (!editor || !host || context.readOnly) return void 0;
+    const update = () => {
+      if (menuOpen) return;
+      setAnchor(editor.isFocused ? anchorOf(editor, host) : null);
+    };
+    update();
+    editor.on("selectionUpdate", update);
+    editor.on("transaction", update);
+    editor.on("focus", update);
+    editor.on("blur", update);
+    return () => {
+      editor.off("selectionUpdate", update);
+      editor.off("transaction", update);
+      editor.off("focus", update);
+      editor.off("blur", update);
+    };
+  }, [editor, container, context.readOnly, menuOpen]);
+  if (!editor || !anchor || context.readOnly) return null;
+  let section = null;
+  return /* @__PURE__ */ jsx("div", { className: "absolute z-10", style: { top: Math.max(0, anchor.top - 14), right: Math.max(0, anchor.right - 10) }, children: /* @__PURE__ */ jsxs(
+    DropdownMenu,
+    {
+      open: menuOpen,
+      onOpenChange: (open) => {
+        setMenuOpen(open);
+        if (!open) editor.commands.focus();
+      },
+      children: [
+        /* @__PURE__ */ jsx(DropdownMenuTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            "aria-label": "Table options",
+            title: "Table options",
+            "data-table-handle": "",
+            onMouseDown: (event) => event.preventDefault(),
+            className: cn(
+              "flex h-6 w-6 items-center justify-center rounded-md border border-border bg-background text-muted-foreground shadow-sm",
+              "hover:bg-accent hover:text-foreground"
+            ),
+            children: /* @__PURE__ */ jsx(Table2, { className: "h-3.5 w-3.5" })
+          }
+        ) }),
+        /* @__PURE__ */ jsx(DropdownMenuContent, { align: "end", className: "w-52", onCloseAutoFocus: (event) => event.preventDefault(), children: TABLE_MENU.map((item) => {
+          const Icon = ICONS[item.id] ?? Table2;
+          const divider = section !== null && section !== item.section;
+          section = item.section;
+          const checked = item.checked?.(editor) ?? false;
+          return /* @__PURE__ */ jsxs("div", { children: [
+            divider && /* @__PURE__ */ jsx(DropdownMenuSeparator, {}),
+            /* @__PURE__ */ jsxs(
+              DropdownMenuItem,
+              {
+                "data-table-action": item.id,
+                className: cn(item.destructive && "text-destructive focus:text-destructive"),
+                onSelect: () => {
+                  item.run(editor);
+                },
+                children: [
+                  /* @__PURE__ */ jsx(Icon, { className: "mr-2 h-4 w-4" }),
+                  /* @__PURE__ */ jsx("span", { className: "flex-1", children: item.label }),
+                  item.checked && checked && /* @__PURE__ */ jsx(Check, { className: "ml-2 h-4 w-4 text-primary" })
+                ]
+              }
+            )
+          ] }, item.id);
+        }) })
+      ]
+    }
+  ) });
+}
+export {
+  TableHandle
+};

package/dist/visual/VisualEditor.js

@@ -21,6 +21,7 @@ import { contextAtIndex, locateCaret } from "../core/caret-context.js";
 import { createVisualExtensions } from "./visual-extensions.js";
 import { findHighlightKey } from "./decorations.js";
 import { BlockHandle } from "./BlockHandle.js";
+import { TableHandle } from "./TableHandle.js";
 import { useSelectionZone } from "@ai-matrx/rich-content/selection-toolbar/selection-zones";
 import { registerFormatElement } from "../format/format-target.js";
 import { RICH_EDITOR_HOST_KEY, editorFormatTarget, islandSelectionOf, tableAnchorOf } from "./format-actions.js";
@@ -153,7 +154,7 @@ function VisualEditor({
   };
   const shellRef = useRef(shell);
   shellRef.current = shell;
-  const formatTarget = useMemo(() => editor ? editorFormatTarget(editor, () => shellRef.current.editLink()) : null, [editor]);
+  const formatTarget = useMemo(() => editor ? editorFormatTarget(editor, () => shellRef.current.editLink(), () => shellRef.current.pickImage()) : null, [editor]);
   const [formatZone, setFormatZone] = useState(null);
   useEffect(() => {
     if (!formatZone || !formatTarget || context.readOnly) return void 0;
@@ -286,6 +287,7 @@ function VisualEditor({
     kind: "rich-editor",
     editor,
     onEditLink: shell.editLink,
+    onInsertImage: shell.pickImage,
     offerVariables: context.variables !== null,
     inTable: () => !editor.isDestroyed && editor.isActive("table")
   } : null;
@@ -327,6 +329,7 @@ function VisualEditor({
       "data-testid": "rich-editor-visual",
       children: [
         /* @__PURE__ */ jsx(BlockHandle, { editor, container }),
+        /* @__PURE__ */ jsx(TableHandle, { editor, container }),
         /* @__PURE__ */ jsx(EditorContent, { editor, className: "mx-auto max-w-3xl pb-[40dvh]" })
       ]
     }

package/dist/visual/format-actions.d.ts

@@ -6,6 +6,8 @@ export interface RichEditorSelectionHost {
     kind: "rich-editor";
     editor: Editor;
     onEditLink: () => void;
+    /** Open the image prompt (upload a file or paste an address). */
+    onInsertImage?: () => void;
     offerVariables: boolean;
     /** The caret or selection is inside a table (its table actions show). */
     inTable: () => boolean;
@@ -22,6 +24,6 @@ export declare function tableAnchorOf(editor: Editor): DOMRect | null;
  * (link field, checklist, code-block island) — the selection toolbar and the
  * visible toolbar (`FormatButtons`, through `registerFormatElement`) share it.
  */
-export declare function editorFormatTarget(editor: Editor, onEditLink: () => void): FormatTarget;
+export declare function editorFormatTarget(editor: Editor, onEditLink: () => void, onInsertImage?: () => void): FormatTarget;
 /** The formatting provider (declared on load; the toolbar root registers it). */
 export declare const richEditorFormatProvider: ActionProvider;

package/dist/visual/format-actions.js

@@ -44,11 +44,12 @@ function editorOf(target) {
 }
 function visualTargetOf(target) {
   const visual = editorOf(target);
-  return visual ? editorFormatTarget(visual.editor, visual.onEditLink) : null;
+  return visual ? editorFormatTarget(visual.editor, visual.onEditLink, visual.onInsertImage) : null;
 }
-function editorFormatTarget(editor, onEditLink) {
+function editorFormatTarget(editor, onEditLink, onInsertImage) {
   return visualFormatTarget(editor, {
     link: () => (onEditLink(), true),
+    image: () => onInsertImage ? (onInsertImage(), true) : false,
     taskList: () => toggleTaskList(editor),
     codeBlock: () => {
       markAutoEdit(editor, insertCodeBlock(editor));

package/dist/visual/table-menu.d.ts

@@ -0,0 +1,13 @@
+import type { Editor } from "@tiptap/core";
+export interface TableMenuItem {
+    id: string;
+    label: string;
+    /** A divider goes before this item. */
+    section: "rows" | "columns" | "header" | "delete";
+    destructive?: boolean;
+    run: (editor: Editor) => boolean;
+    /** A toggle's state (the header row). */
+    checked?: (editor: Editor) => boolean;
+}
+export declare const TABLE_MENU: readonly TableMenuItem[];
+export declare function tableMenuItem(id: string): TableMenuItem;

package/dist/visual/table-menu.js

@@ -0,0 +1,20 @@
+import { tableHeaderRowShown, toggleTableHeaderRow } from "../core/commands.js";
+const TABLE_MENU = [
+  { id: "row-above", section: "rows", label: "Add row above", run: (e) => e.chain().focus().addRowBefore().run() },
+  { id: "row-below", section: "rows", label: "Add row below", run: (e) => e.chain().focus().addRowAfter().run() },
+  { id: "col-left", section: "columns", label: "Add column left", run: (e) => e.chain().focus().addColumnBefore().run() },
+  { id: "col-right", section: "columns", label: "Add column right", run: (e) => e.chain().focus().addColumnAfter().run() },
+  { id: "header-row", section: "header", label: "Header row", run: (e) => toggleTableHeaderRow(e), checked: tableHeaderRowShown },
+  { id: "del-row", section: "delete", label: "Delete row", destructive: true, run: (e) => e.chain().focus().deleteRow().run() },
+  { id: "del-col", section: "delete", label: "Delete column", destructive: true, run: (e) => e.chain().focus().deleteColumn().run() },
+  { id: "del-table", section: "delete", label: "Delete table", destructive: true, run: (e) => e.chain().focus().deleteTable().run() }
+];
+function tableMenuItem(id) {
+  const item = TABLE_MENU.find((candidate) => candidate.id === id);
+  if (!item) throw new Error(`No table menu item "${id}"`);
+  return item;
+}
+export {
+  TABLE_MENU,
+  tableMenuItem
+};

package/dist/visual/visual-format-target.js

@@ -17,6 +17,8 @@ const VISUAL = {
   paragraph: { run: (e) => e.chain().focus().setParagraph().run(), active: (e) => e.isActive("paragraph") },
   table: { run: (e) => e.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run(), active: (e) => e.isActive("table") },
   horizontalRule: { run: (e) => e.chain().focus().setHorizontalRule().run(), active: () => false },
+  // The image prompt (upload or address) is the host shell's — passed in as an override.
+  image: { run: () => false, active: () => false },
   undo: { run: (e) => e.chain().focus().undo().run(), active: () => false },
   redo: { run: (e) => e.chain().focus().redo().run(), active: () => false }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/rich-editor",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "The AI Matrx editor: Visual (Tiptap), Source (CodeMirror), Preview, the markdown formatting command layer, and edit-in-place — over @ai-matrx/rich-content. Consumers that only render never install it.",
   "type": "module",
   "license": "MIT",
@@ -91,12 +91,12 @@
     "github-slugger": "^2.0.0",
     "lucide-react": "^1.48.0",
     "@ai-matrx/agents": "latest",
-    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/content-ir": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/kit": "latest",
     "@ai-matrx/print": "latest",
-    "@ai-matrx/rich-content": "latest"
+    "@ai-matrx/rich-content": "latest",
+    "@ai-matrx/alchemy": "latest"
   },
   "peerDependencies": {
     "react": ">=19.0.0",