@ai-matrx/rich-content 0.2.10 → 0.2.16

package/dist/selection-toolbar/selection-actions.d.ts

@@ -0,0 +1,126 @@
+import type { Action, ActionProvider, ClickTarget } from "@ai-matrx/alchemy/actions";
+import type { SelectionMode, SelectionToolbarUi } from "./selection-zones.js";
+import type { FeedbackSubject } from "../host/feedback-subject.js";
+/** The toolbar's knobs (platform.feature_knob, feature `selection_toolbar`). */
+export declare const SELECTION_TOOLBAR_KNOB_FEATURE = "selection_toolbar";
+export declare const HIGHLIGHT_WHILE_EDITING_KNOB: {
+    readonly feature: "selection_toolbar";
+    readonly key: "highlight_while_editing";
+};
+/** The code default while the knob loads (and the seeded default): off. */
+export declare const HIGHLIGHT_WHILE_EDITING_DEFAULT = false;
+/**
+ * The comment composer's "Send with my next message" switch on a chat answer
+ * (Turn References, ruling 5): its starting position. Default ON — a comment on
+ * an answer is usually meant for the agent, and the person can switch it off
+ * per comment.
+ */
+export declare const COMMENT_SENDS_WITH_NEXT_MESSAGE_KNOB: {
+    readonly feature: "selection_toolbar";
+    readonly key: "comment_sends_with_next_message";
+};
+export declare const COMMENT_SENDS_WITH_NEXT_MESSAGE_DEFAULT = true;
+export interface SelectionToolbarKnobs {
+    highlightWhileEditing: boolean;
+}
+/** The toolbar's own half of the composite host. */
+export interface SelectionToolbarHost {
+    kind: "selection-toolbar";
+    mode: SelectionMode;
+    knobs: SelectionToolbarKnobs;
+    ui: SelectionToolbarUi;
+    /**
+     * How many buttons fit in one row (the docked phone bar), or null when the
+     * strip is unbounded (desktop). Past it, the lowest-priority actions move
+     * into the registry's overflow (More) so the bar never scrolls.
+     */
+    slots: number | null;
+}
+export declare function selectionToolbarHostOf(target: ClickTarget): SelectionToolbarHost | null;
+/** Read another provider's half of the composite host. */
+export declare function hostHalf<T>(target: ClickTarget, key: string): T | null;
+type ModeRule = readonly SelectionMode[] | ((knobs: SelectionToolbarKnobs) => readonly SelectionMode[]);
+/**
+ * THE MODE TABLE. Editing: formatting + AI + comment. Reading: highlight,
+ * comment, suggest, AI, link and report. AI shows in both.
+ */
+export declare const SELECTION_ACTION_MODES: Readonly<Record<string, ModeRule>>;
+/**
+ * THE HOST KINDS — what a person gets, by where the text is. Documentation that
+ * the census test checks against the providers (selection-host-kinds.test.ts):
+ * a host kind is the set of host halves present on the target.
+ *
+ *   annotated reading  (annotation + context menu)  highlight ×5, comment, suggest, link, report, AI and more —
+ *                                                    the study guide, document Annotate, and EVERY saved record
+ *                                                    (annotations/RecordAnnotations): a note's preview, a chat
+ *                                                    answer, the studio previewing an unedited saved document.
+ *                                                    Highlight/Link are absent on a kind with no association pair
+ *                                                    (a chat answer until its pairs are applied).
+ *   rich editor        (richEditor + context menu)   formatting, copy, AI and more; COMMENT only when the buffer
+ *                                                    is a saved record (a saved document or note) — absent for an
+ *                                                    unsaved buffer; table actions while the caret/selection is in
+ *                                                    a table. Notes' own editor modes: pending the notes migration
+ *                                                    onto the one editor (RC-A4).
+ *   plain reading      (context menu only)           copy, save to notes, AI and more — unsaved content: a stream
+ *                                                    in flight, raw text, an edited studio copy, window panels
+ *   text field         (context menu, editable)      copy, save to notes, AI and more
+ */
+export declare const SELECTION_HOST_KINDS: {
+    readonly annotatedReading: readonly ["annotation", "contextMenuSelection"];
+    readonly richEditor: readonly ["richEditor", "contextMenuSelection"];
+    readonly plainReading: readonly ["contextMenuSelection"];
+};
+/** Does the toolbar show `actionId` for this target's mode? */
+export declare function shownInSelectionMode(actionId: string, target: ClickTarget): boolean;
+export declare const SELECTION_COMMON_HOST_KEY = "selectionCommon";
+/** Set by the root on every target: the selected text and the app's doors. */
+export interface SelectionCommonHost {
+    kind: "selection-common";
+    text: string;
+    saveToNotes(content: string): void;
+    /** The one "Save to a table" (SAVE-AS-TABLE-EVERYWHERE) for a selection that reads as rows. */
+    saveToTable(content: string): void;
+    /**
+     * The selection written back as the shapes it was drawn from (`shapeTextOfNode` over the
+     * selected DOM): a rendered table's rows as a markdown table, a list's bullets as bullets. The
+     * flattened `text` loses both. Null where the selection is not over rendered content.
+     */
+    shapeText: string | null;
+    /** The app's feedback window (a passage report). */
+    openFeedback(report: {
+        title: string;
+        subject: FeedbackSubject;
+    }): void;
+    /** Open a new chat with this passage of a chat answer staged as a comment (empty body). */
+    newChatAbout(passage: {
+        quote: string;
+        conversationId: string;
+        messageId: string;
+    }): void;
+}
+/**
+ * Which actions keep a button when the bar cannot show them all (a phone).
+ * Everything else — including "AI and more" when space is tight — moves into
+ * the registry's overflow (the layout's More), so the bar never scrolls.
+ */
+export declare const SELECTION_PRIORITY: Readonly<Record<SelectionMode, readonly string[]>>;
+/** "primary" (a button) or "overflow" (a More row) for this action at this target. */
+export declare function selectionPlacement(id: string, target: ClickTarget): "primary" | "overflow";
+/** A provider's actions, placed for this target (every selection provider returns through this). */
+export declare function placeSelectionActions(actions: readonly Action[], target: ClickTarget): Action[];
+/**
+ * A surface adds passage actions (the study guide's "I don't get this") by
+ * putting ordinary Alchemy actions on its zone's `passageActions` host half;
+ * this provider yields them, gated by the mode table like every other
+ * selection action. One provider, so a surface never hand-renders buttons.
+ */
+export declare const PASSAGE_ACTIONS_HOST_KEY = "passageActions";
+export declare const passageActionsProvider: ActionProvider;
+export declare function declareSelectionProvider(provider: ActionProvider): void;
+export declare function declaredSelectionProviders(): readonly ActionProvider[];
+export declare function subscribeDeclaredSelectionProviders(listener: () => void): () => void;
+/** Register a provider into a registry, once per registry (the root calls this). */
+export declare function ensureProvider(registry: {
+    register(p: ActionProvider): () => void;
+}, provider: ActionProvider): void;
+export {};

package/dist/selection-toolbar/selection-actions.js

@@ -0,0 +1,240 @@
+const SELECTION_TOOLBAR_KNOB_FEATURE = "selection_toolbar";
+const HIGHLIGHT_WHILE_EDITING_KNOB = {
+  feature: SELECTION_TOOLBAR_KNOB_FEATURE,
+  key: "highlight_while_editing"
+};
+const HIGHLIGHT_WHILE_EDITING_DEFAULT = false;
+const COMMENT_SENDS_WITH_NEXT_MESSAGE_KNOB = {
+  feature: SELECTION_TOOLBAR_KNOB_FEATURE,
+  key: "comment_sends_with_next_message"
+};
+const COMMENT_SENDS_WITH_NEXT_MESSAGE_DEFAULT = true;
+function selectionToolbarHostOf(target) {
+  const half = target.host?.selectionToolbar;
+  return half?.kind === "selection-toolbar" ? half : null;
+}
+function hostHalf(target, key) {
+  const host = target.host;
+  return host?.[key] ?? null;
+}
+const HIGHLIGHT = (knobs) => knobs.highlightWhileEditing ? ["read", "edit"] : ["read"];
+const SELECTION_ACTION_MODES = {
+  // Formatting (rich editor)
+  "selection:format-bold": ["edit"],
+  "selection:format-italic": ["edit"],
+  "selection:format-strike": ["edit"],
+  "selection:format-code": ["edit"],
+  "selection:format-link": ["edit"],
+  "selection:format-h1": ["edit"],
+  "selection:format-h2": ["edit"],
+  "selection:format-h3": ["edit"],
+  "selection:format-quote": ["edit"],
+  "selection:format-list": ["edit"],
+  "selection:format-numbered": ["edit"],
+  "selection:format-tasks": ["edit"],
+  "selection:format-codeblock": ["edit"],
+  "selection:format-variable": ["edit"],
+  // Annotations (the annotation sidecar)
+  "selection:highlight-yellow": HIGHLIGHT,
+  "selection:highlight-green": HIGHLIGHT,
+  "selection:highlight-blue": HIGHLIGHT,
+  "selection:highlight-pink": HIGHLIGHT,
+  "selection:highlight-purple": HIGHLIGHT,
+  "selection:comment": ["read", "edit"],
+  "selection:suggest": ["read"],
+  "selection:link-record": ["read"],
+  // AI — every mode
+  "selection:ai": ["read", "edit"],
+  "selection:tutor-explain": ["read"],
+  "selection:tutor-ask": ["read"],
+  // Reporting (every annotated passage: study guides, documents in Annotate)
+  "selection:report": ["read"],
+  // A chat answer's passage, taken to a new conversation as a comment
+  "selection:new-chat": ["read"],
+  // Rich-editor tables (the caret or a selection in a table cell)
+  "selection:table-row-above": ["edit"],
+  "selection:table-row-below": ["edit"],
+  "selection:table-col-left": ["edit"],
+  "selection:table-col-right": ["edit"],
+  "selection:table-align-left": ["edit"],
+  "selection:table-align-center": ["edit"],
+  "selection:table-align-right": ["edit"],
+  "selection:table-del-row": ["edit"],
+  "selection:table-del-col": ["edit"],
+  "selection:table-del-table": ["edit"],
+  // Every selection that has no richer home: copy it, keep it
+  "selection:copy": ["read", "edit"],
+  "selection:copy-markdown": ["read", "edit"],
+  "selection:copy-text": ["read", "edit"],
+  "selection:save-to-notes": ["read", "edit"],
+  // A selection that reads as rows (a table, a list, Key: value lines, CSV) — SAVE-AS-TABLE-EVERYWHERE
+  "selection:save-to-table": ["read", "edit"]
+};
+const SELECTION_HOST_KINDS = {
+  annotatedReading: ["annotation", "contextMenuSelection"],
+  richEditor: ["richEditor", "contextMenuSelection"],
+  plainReading: ["contextMenuSelection"]
+};
+function shownInSelectionMode(actionId, target) {
+  const toolbar = selectionToolbarHostOf(target);
+  if (!toolbar) return false;
+  const rule = SELECTION_ACTION_MODES[actionId];
+  if (!rule) return false;
+  const modes = typeof rule === "function" ? rule(toolbar.knobs) : rule;
+  return modes.includes(toolbar.mode);
+}
+const SELECTION_COMMON_HOST_KEY = "selectionCommon";
+const SELECTION_PRIORITY = {
+  edit: [
+    "selection:format-bold",
+    "selection:format-italic",
+    "selection:format-link",
+    "selection:ai",
+    "selection:comment",
+    "selection:table-row-below",
+    "selection:table-col-right",
+    "selection:copy",
+    "selection:format-strike",
+    "selection:format-code",
+    "selection:format-h1",
+    "selection:format-h2",
+    "selection:format-quote",
+    "selection:format-list",
+    "selection:format-variable",
+    "selection:highlight-yellow",
+    "selection:highlight-green",
+    "selection:highlight-blue",
+    "selection:highlight-pink",
+    "selection:highlight-purple",
+    "selection:table-row-above",
+    "selection:table-col-left",
+    "selection:table-align-left",
+    "selection:table-align-center",
+    "selection:table-align-right",
+    "selection:table-del-row",
+    "selection:table-del-col",
+    "selection:table-del-table",
+    "selection:save-to-notes",
+    "selection:save-to-table"
+  ],
+  read: [
+    "selection:highlight-yellow",
+    "selection:comment",
+    "selection:ai",
+    "selection:suggest",
+    "selection:tutor-explain",
+    "selection:highlight-green",
+    "selection:highlight-blue",
+    "selection:highlight-pink",
+    "selection:highlight-purple",
+    "selection:tutor-ask",
+    "selection:link-record",
+    "selection:report",
+    "selection:new-chat",
+    "selection:copy",
+    "selection:save-to-notes",
+    "selection:save-to-table"
+  ]
+};
+function hostKeyOf(id) {
+  if (id.startsWith("selection:format-") || id.startsWith("selection:table-")) return "richEditor";
+  if (id === "selection:copy" || id === "selection:save-to-notes" || id === "selection:save-to-table") return SELECTION_COMMON_HOST_KEY;
+  if (id === "selection:ai") return "contextMenuSelection";
+  if (id.startsWith("selection:tutor-")) return PASSAGE_ACTIONS_HOST_KEY;
+  return "annotation";
+}
+function presentAt(id, target) {
+  const key = hostKeyOf(id);
+  if (key === SELECTION_COMMON_HOST_KEY && id !== "selection:save-to-table") {
+    const annotation = hostHalf(target, "annotation");
+    if (annotation && (!annotation.capture || annotation.capture({ silent: true }))) return false;
+  }
+  if (id === "selection:new-chat") {
+    const annotation = hostHalf(target, "annotation");
+    if (annotation?.source?.token !== "message" || !annotation.source.conversationId) return false;
+  }
+  if (id.startsWith("selection:table-")) {
+    const editor = hostHalf(target, "richEditor");
+    if (!editor?.inTable?.()) return false;
+  }
+  const half = hostHalf(target, key);
+  if (!half) return false;
+  if (key === PASSAGE_ACTIONS_HOST_KEY) return half.some((a) => a.id === id);
+  return shownInSelectionMode(id, target);
+}
+function selectionPlacement(id, target) {
+  const toolbar = selectionToolbarHostOf(target);
+  if (!toolbar || toolbar.slots === null) return "primary";
+  const shown = SELECTION_PRIORITY[toolbar.mode].filter((x) => presentAt(x, target));
+  if (shown.length <= toolbar.slots) return "primary";
+  const rank = shown.indexOf(id);
+  return rank >= 0 && rank < Math.max(1, toolbar.slots - 1) ? "primary" : "overflow";
+}
+function placeSelectionActions(actions, target) {
+  return actions.map((a) => a.placement === "overflow" ? a : { ...a, placement: selectionPlacement(a.id, target) });
+}
+const PASSAGE_ACTIONS_HOST_KEY = "passageActions";
+const passageActionsProvider = {
+  id: "selection-passage",
+  tier: "T0",
+  actions: (target) => {
+    const list = hostHalf(target, PASSAGE_ACTIONS_HOST_KEY) ?? [];
+    return placeSelectionActions(list, target).map((a) => ({
+      ...a,
+      eligible: (t) => shownInSelectionMode(a.id, t) ? a.eligible(t) : { status: "absent" }
+    }));
+  }
+};
+const declared = /* @__PURE__ */ new Map();
+const declaredListeners = /* @__PURE__ */ new Set();
+function declareSelectionProvider(provider) {
+  const existing = declared.get(provider.id);
+  if (existing === provider) return;
+  if (existing && false) {
+    throw new Error(`Selection provider "${provider.id}" was declared twice by different modules.`);
+  }
+  declared.set(provider.id, provider);
+  for (const l of [...declaredListeners]) l();
+}
+function declaredSelectionProviders() {
+  return [...declared.values()];
+}
+function subscribeDeclaredSelectionProviders(listener) {
+  declaredListeners.add(listener);
+  return () => {
+    declaredListeners.delete(listener);
+  };
+}
+declareSelectionProvider(passageActionsProvider);
+const REGISTERED = /* @__PURE__ */ new WeakMap();
+function ensureProvider(registry, provider) {
+  let seen = REGISTERED.get(registry);
+  if (!seen) {
+    seen = /* @__PURE__ */ new Map();
+    REGISTERED.set(registry, seen);
+  }
+  if (seen.has(provider.id)) return;
+  seen.set(provider.id, registry.register(provider));
+}
+export {
+  COMMENT_SENDS_WITH_NEXT_MESSAGE_DEFAULT,
+  COMMENT_SENDS_WITH_NEXT_MESSAGE_KNOB,
+  HIGHLIGHT_WHILE_EDITING_DEFAULT,
+  HIGHLIGHT_WHILE_EDITING_KNOB,
+  PASSAGE_ACTIONS_HOST_KEY,
+  SELECTION_ACTION_MODES,
+  SELECTION_COMMON_HOST_KEY,
+  SELECTION_HOST_KINDS,
+  SELECTION_PRIORITY,
+  SELECTION_TOOLBAR_KNOB_FEATURE,
+  declareSelectionProvider,
+  declaredSelectionProviders,
+  ensureProvider,
+  hostHalf,
+  passageActionsProvider,
+  placeSelectionActions,
+  selectionPlacement,
+  selectionToolbarHostOf,
+  shownInSelectionMode,
+  subscribeDeclaredSelectionProviders
+};

package/dist/selection-toolbar/selection-copy.d.ts

@@ -0,0 +1,19 @@
+import { type CopyFlavor } from "../copy/copy-commands.js";
+/** The live selection's range when it lies over rendered (non-editable) content. */
+export declare function renderedSelectionRange(): Range | null;
+/** The selected DOM as HTML (what the person sees, formatted), links as their author wrote them. */
+export declare function rangeHtml(range: Range): string;
+/**
+ * The selected DOM as markdown, through THE editor's HTML → markdown converter
+ * (the same one every paste uses), loaded at copy time. Falls back to the
+ * shape reader (tables and lists kept) when the converter cannot run.
+ */
+export declare function rangeMarkdown(html: string): Promise<string | null>;
+/** Copy the live rendered selection in one flavor. False when there is no rendered selection. */
+export declare function copyRenderedSelection(flavor: CopyFlavor, fallbackText: string): Promise<boolean>;
+/**
+ * The keyboard half, installed once at the app root (SelectionToolbarRoot):
+ * ⌘C on rendered content writes formatted HTML + a markdown text flavor;
+ * ⌘⇧C writes readable plain text.
+ */
+export declare function installRichCopyKeys(): () => void;

package/dist/selection-toolbar/selection-copy.js

@@ -0,0 +1,98 @@
+import { copyRich } from "@ai-matrx/kit/clipboard";
+import {
+  copyRichContent,
+  defaultCopyFlavor,
+  markdownToReadableText,
+  richCopyPlainText,
+  writeClipboardFlavors
+} from "../copy/copy-commands.js";
+import { liveSelectionShapeText } from "./selection-shape.js";
+import { announceBareHost, hostCapability } from "../host/registry.js";
+import { stripOwnUtmSource } from "../utils/lifted/url-utm.js";
+function renderedSelectionRange() {
+  if (typeof window === "undefined") return null;
+  const sel = window.getSelection();
+  if (!sel || sel.rangeCount === 0 || sel.isCollapsed) return null;
+  const range = sel.getRangeAt(0);
+  const host = range.commonAncestorContainer;
+  const el = host.nodeType === 1 ? host : host.parentElement;
+  if (!el || el.closest("textarea, input, [contenteditable='true'], [contenteditable=''], .cm-editor")) return null;
+  const active = document.activeElement;
+  if (active && active.matches("textarea, input, [contenteditable='true']")) return null;
+  return range;
+}
+function rangeHtml(range) {
+  const box = document.createElement("div");
+  box.appendChild(range.cloneContents());
+  for (const a of Array.from(box.querySelectorAll("a[href]"))) {
+    const href = a.getAttribute("href") ?? "";
+    const clean = stripOwnUtmSource(href);
+    if (clean !== href) a.setAttribute("href", clean);
+  }
+  return box.innerHTML;
+}
+async function rangeMarkdown(html) {
+  try {
+    const load = hostCapability("loadHtmlToMarkdown");
+    if (!load) {
+      announceBareHost("loadHtmlToMarkdown", "a copied selection keeps its shape text");
+      return liveSelectionShapeText();
+    }
+    const md = (await load())(html);
+    return md.trim() ? md : null;
+  } catch (error) {
+    console.warn("[copy] the selection could not be read as markdown; copying its shape text instead:", error);
+    return liveSelectionShapeText();
+  }
+}
+async function copyRenderedSelection(flavor, fallbackText) {
+  const range = renderedSelectionRange();
+  const html = range ? rangeHtml(range) : null;
+  const markdown = (html ? await rangeMarkdown(html) : null) ?? fallbackText;
+  if (flavor === "default" && html) {
+    return writeClipboardFlavors(richCopyPlainText(markdown, "default", defaultCopyFlavor()), html);
+  }
+  return copyRichContent(markdown, flavor, { toast: false });
+}
+function installRichCopyKeys() {
+  const onCopy = (event) => {
+    if (event.defaultPrevented || !event.clipboardData) return;
+    const range = renderedSelectionRange();
+    if (!range) return;
+    const html = rangeHtml(range);
+    const quick = liveSelectionShapeText() ?? range.toString();
+    event.clipboardData.setData("text/html", html);
+    event.clipboardData.setData("text/plain", quick);
+    event.preventDefault();
+    void rangeMarkdown(html).then(async (markdown) => {
+      if (!markdown || markdown === quick) return;
+      const plain = richCopyPlainText(markdown, "default", defaultCopyFlavor());
+      const upgraded = await copyRich({ text: plain, html }, { plainFallback: false });
+      if (!upgraded) console.warn("[copy] the markdown flavor could not be added to this copy; the shape text stands");
+    });
+  };
+  const onKeyDown = (event) => {
+    const mod = event.metaKey || event.ctrlKey;
+    if (!mod || !event.shiftKey || event.altKey || event.code !== "KeyC" && event.key.toLowerCase() !== "c") return;
+    const range = renderedSelectionRange();
+    if (!range) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const html = rangeHtml(range);
+    const fallback = liveSelectionShapeText() ?? range.toString();
+    void rangeMarkdown(html).then((markdown) => writeClipboardFlavors(markdownToReadableText(markdown ?? fallback)));
+  };
+  document.addEventListener("copy", onCopy);
+  document.addEventListener("keydown", onKeyDown, true);
+  return () => {
+    document.removeEventListener("copy", onCopy);
+    document.removeEventListener("keydown", onKeyDown, true);
+  };
+}
+export {
+  copyRenderedSelection,
+  installRichCopyKeys,
+  rangeHtml,
+  rangeMarkdown,
+  renderedSelectionRange
+};

package/dist/selection-toolbar/selection-shape.d.ts

@@ -0,0 +1 @@
+export declare function liveSelectionShapeText(): string | null;

package/dist/selection-toolbar/selection-shape.js

@@ -0,0 +1,15 @@
+import { shapeTextOfNode } from "@ai-matrx/records-ui/table-shape";
+function liveSelectionShapeText() {
+  if (typeof window === "undefined") return null;
+  const sel = window.getSelection();
+  if (!sel || sel.rangeCount === 0 || sel.isCollapsed) return null;
+  const range = sel.getRangeAt(0);
+  const host = range.commonAncestorContainer;
+  const el = host.nodeType === 1 ? host : host.parentElement;
+  if (el?.closest("textarea, input, [contenteditable='true']")) return null;
+  const text = shapeTextOfNode(range.cloneContents());
+  return text.trim() ? text : null;
+}
+export {
+  liveSelectionShapeText
+};

package/dist/selection-toolbar/selection-zones.d.ts

@@ -0,0 +1,90 @@
+import { type ReactNode } from "react";
+/** Editing shows formatting; reading shows highlight / suggest / link. */
+export type SelectionMode = "edit" | "read";
+/** What a running action (or a panel) may do to the toolbar. */
+export interface SelectionToolbarUi {
+    /** Swap the strip for one of the zone's panels (a comment composer), handing it `payload`. */
+    openPanel(panel: string, payload?: unknown): void;
+    /** Back to the strip. */
+    closePanel(): void;
+    /** Close the toolbar. `clearSelection` also drops the text selection. */
+    close(options?: {
+        clearSelection?: boolean;
+    }): void;
+}
+export interface SelectionZoneContribution {
+    /**
+     * This zone's halves of the composite ClickTarget host, keyed by provider
+     * (`{ annotation: … }`, `{ richEditor: … }`). Providers narrow their own key.
+     */
+    host?: Record<string, unknown>;
+    /** The text here is being edited (a rich editor, an editable field). */
+    editable?: boolean;
+    /**
+     * Stop here: zones OUTSIDE this one contribute nothing for a selection in
+     * it, and when nothing deeper contributes the toolbar stays closed (a
+     * surface that owns its own passage UI, e.g. a chat answer's action bar).
+     */
+    suppress?: boolean;
+    /** Panels this zone draws inside the toolbar frame. Null = not this zone's. */
+    renderPanel?(panel: string, ui: SelectionToolbarUi, payload: unknown): ReactNode | null;
+    /**
+     * CARET MODE: where to anchor the toolbar when the selection is only a caret
+     * here, or null to stay closed. The rich editor answers with its table's box
+     * while the caret is in a table (the table actions are toolbar actions).
+     */
+    caretAnchor?(): {
+        left: number;
+        top: number;
+        bottom: number;
+        width: number;
+    } | null;
+    /** The text a caret-mode toolbar acts on (a selected code block's source), if any. */
+    caretText?(): string;
+    /** A panel (and its payload) to show immediately when the toolbar opens here (a pending reattach). */
+    initialPanel?(): {
+        panel: string;
+        payload?: unknown;
+    } | null;
+    /**
+     * A zone whose own state decides what its actions can do (an editor's model selection, which
+     * the editor syncs a beat AFTER the DOM selection the toolbar reads) calls `onChange` when that
+     * state moves; the open toolbar then re-resolves its actions. Returns the unsubscribe.
+     */
+    subscribe?(onChange: () => void): () => void;
+}
+export declare function subscribeSelectionZones(listener: () => void): () => void;
+export declare function selectionZonesVersion(): number;
+/** Re-render when zones mount/unmount (the root re-evaluates an open toolbar). */
+export declare function useSelectionZonesVersion(): number;
+/** Tell the root a zone's contribution changed (a pending reattach started). */
+export declare function notifySelectionZonesChanged(): void;
+export interface ResolvedZone {
+    id: string;
+    element: HTMLElement;
+    contribution: SelectionZoneContribution;
+}
+/**
+ * Every zone holding `node`, deepest first, cut at the first `suppress` zone
+ * (which itself contributes nothing).
+ */
+export declare function zonesContaining(node: Node | null): ResolvedZone[];
+/**
+ * Register `element` as a selection zone for as long as the caller is mounted.
+ * The contribution is read fresh at every selection (a ref), so passing a new
+ * object each render never re-registers.
+ */
+export declare function useSelectionZone(element: HTMLElement | null, contribution: SelectionZoneContribution | null): void;
+/** A collapsed caret inside a contenteditable, measured on demand. */
+export interface EditableCaret {
+    /** The node the caret sits in. */
+    node: Node;
+    /** The contenteditable element (or its descendant) holding it. */
+    host: Element;
+    /** Where the caret is on screen now. */
+    rect: () => DOMRect | null;
+}
+/** Hear every caret move inside an editable surface. Returns the unsubscribe. */
+export declare function subscribeEditableCaret(listener: (caret: EditableCaret) => void): () => void;
+/** The root calls this on every `selectionchange`. */
+export declare function publishEditableCaret(): void;

package/dist/selection-toolbar/selection-zones.js

@@ -0,0 +1,85 @@
+"use client";
+import { useEffect, useId, useLayoutEffect, useRef, useSyncExternalStore } from "react";
+const zones = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Set();
+let version = 0;
+function notify() {
+  version += 1;
+  for (const l of [...listeners]) l();
+}
+function subscribeSelectionZones(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function selectionZonesVersion() {
+  return version;
+}
+function useSelectionZonesVersion() {
+  return useSyncExternalStore(subscribeSelectionZones, selectionZonesVersion, () => 0);
+}
+function notifySelectionZonesChanged() {
+  notify();
+}
+function zonesContaining(node) {
+  if (!node) return [];
+  const hits = [];
+  for (const z of zones.values()) {
+    if (z.element.isConnected && z.element.contains(node)) {
+      hits.push({ id: z.id, element: z.element, contribution: z.read() });
+    }
+  }
+  hits.sort((a, b) => a.element === b.element ? 0 : a.element.contains(b.element) ? 1 : -1);
+  const out = [];
+  for (const z of hits) {
+    if (z.contribution.suppress) break;
+    out.push(z);
+  }
+  return out;
+}
+function useSelectionZone(element, contribution) {
+  const id = useId();
+  const latest = useRef(contribution);
+  useLayoutEffect(() => {
+    latest.current = contribution;
+  });
+  const enabled = contribution !== null;
+  useEffect(() => {
+    if (!element || !enabled) return;
+    zones.set(id, { id, element, read: () => latest.current ?? {} });
+    notify();
+    return () => {
+      zones.delete(id);
+      notify();
+    };
+  }, [id, element, enabled]);
+}
+const caretListeners = /* @__PURE__ */ new Set();
+function subscribeEditableCaret(listener) {
+  caretListeners.add(listener);
+  return () => {
+    caretListeners.delete(listener);
+  };
+}
+function publishEditableCaret() {
+  if (caretListeners.size === 0) return;
+  const sel = document.getSelection();
+  if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return;
+  const node = sel.anchorNode;
+  const host = node instanceof Element ? node : node?.parentElement;
+  if (!node || !host?.closest("[contenteditable='true'], [contenteditable='']")) return;
+  const range = sel.getRangeAt(0);
+  const caret = { node, host, rect: () => range.getClientRects()[0] ?? range.getBoundingClientRect() };
+  for (const l of [...caretListeners]) l(caret);
+}
+export {
+  notifySelectionZonesChanged,
+  publishEditableCaret,
+  selectionZonesVersion,
+  subscribeEditableCaret,
+  subscribeSelectionZones,
+  useSelectionZone,
+  useSelectionZonesVersion,
+  zonesContaining
+};