@ai-matrx/rich-editor 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.3
+### Unreleased
+
+### Shared fence parsing
+
+- Code-block formatting uses Content IR's canonical fence opener. Invalid
+  backtick info is not mistaken for a block that should be unwrapped.
+
+### Consumer action
+
+- None required. Formatting commands and selection contracts are unchanged.
+
 ## 0.1.2
 
 The packed-tarball canary now uses the public source-edit helper and proves both resulting markdown
@@ -22,3 +34,4 @@ approval, host value, block insert, shortcuts), `in-place/{in-place-session,care
 ### Consumer action
 
 - matrx-frontend: import `@ai-matrx/rich-editor/core/<module>` instead of `@/components/rich-editor/core/<module>`.
+

package/dist/core/markdown-format.js

@@ -1,3 +1,4 @@
+import { fenceOpenerOf } from "@ai-matrx/content-ir/source";
 const FORMAT_COMMAND_IDS = [
   "bold",
   "italic",
@@ -217,12 +218,11 @@ function quoteCommand(text, from, to) {
   const head = from === to ? anchor : mapPos(to, ordered, 1);
   return { changes: ordered, anchor, head };
 }
-const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 function codeBlockCommand(text, from, to) {
   const lines = linesTouched(text, from, to);
   const first = lines[0];
   const last = lines[lines.length - 1];
-  if (lines.length >= 2 && FENCE.test(first.text) && FENCE.test(last.text)) {
+  if (lines.length >= 2 && fenceOpenerOf(first.text) && fenceOpenerOf(last.text)) {
     const changes2 = [
       { from: first.start, to: Math.min(first.end + 1, text.length), insert: "" },
       { from: last.start - 1, to: last.end, insert: "" }
@@ -236,7 +236,7 @@ function codeBlockCommand(text, from, to) {
   const nextStart = last.end + 1;
   const nextBreak = text.indexOf("\n", nextStart);
   const nextLine = nextStart <= text.length ? text.slice(nextStart, nextBreak === -1 ? text.length : nextBreak) : "";
-  if (prevEnd >= 0 && FENCE.test(prevLine) && nextStart <= text.length && FENCE.test(nextLine) && nextLine.trim().replace(/[`~]/g, "") === "") {
+  if (prevEnd >= 0 && fenceOpenerOf(prevLine) && nextStart <= text.length && fenceOpenerOf(nextLine) && nextLine.trim().replace(/[`~]/g, "") === "") {
     const nextEnd = nextBreak === -1 ? text.length : nextBreak;
     const changes2 = [
       { from: prevStart, to: first.start, insert: "" },

package/dist/core/text-insertion.d.ts

@@ -0,0 +1,14 @@
+export declare function insertTextAtTextareaCursor(textarea: HTMLTextAreaElement, text: string, onValueChange?: (nextValue: string) => void): boolean;
+export declare function insertTextByRef(textareaRef: HTMLTextAreaElement | null, text: string): boolean;
+/**
+ * WHERE A BLOCK GOES IN PLAIN TEXT — never inside a word.
+ *
+ * A block (a reference fence, a pasted section) inserted at a caret that sits
+ * inside a word split it: "of" became "o" + block + "f" (G5 review,
+ * 2026-10-02). A block belongs on its own line, so it lands at the END of the
+ * caret's line ("after") or the START of it ("before"). A non-empty selection
+ * is replaced where it is — the person chose that range. Every plain-text
+ * surface (textarea, the rich editor's source view, a contentEditable text
+ * node) uses this one rule.
+ */
+export declare function blockBoundary(text: string, from: number, to: number, where?: "before" | "after"): number;

package/dist/core/text-insertion.js

@@ -0,0 +1,55 @@
+function insertTextAtTextareaCursor(textarea, text, onValueChange) {
+  try {
+    if (!textarea) {
+      return false;
+    }
+    const start = textarea.selectionStart;
+    const end = textarea.selectionEnd;
+    const currentValue = textarea.value;
+    const newValue = currentValue.substring(0, start) + text + currentValue.substring(end);
+    if (typeof onValueChange === "function") {
+      onValueChange(newValue);
+      textarea.focus();
+      requestAnimationFrame(() => {
+        const newCursorPos2 = start + text.length;
+        textarea.setSelectionRange(newCursorPos2, newCursorPos2);
+      });
+      return true;
+    }
+    const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+      window.HTMLTextAreaElement.prototype,
+      "value"
+    )?.set;
+    if (nativeInputValueSetter) {
+      nativeInputValueSetter.call(textarea, newValue);
+    } else {
+      textarea.value = newValue;
+    }
+    const newCursorPos = start + text.length;
+    textarea.setSelectionRange(newCursorPos, newCursorPos);
+    textarea.dispatchEvent(new Event("input", { bubbles: true }));
+    textarea.dispatchEvent(new Event("change", { bubbles: true }));
+    textarea.focus();
+    return true;
+  } catch {
+    return false;
+  }
+}
+function insertTextByRef(textareaRef, text) {
+  if (!textareaRef) return false;
+  return insertTextAtTextareaCursor(textareaRef, text);
+}
+function blockBoundary(text, from, to, where = "after") {
+  if (where === "after") {
+    const newline2 = text.indexOf("\n", to);
+    return newline2 === -1 ? text.length : newline2;
+  }
+  if (from <= 0) return 0;
+  const newline = text.lastIndexOf("\n", from - 1);
+  return newline === -1 ? 0 : newline + 1;
+}
+export {
+  blockBoundary,
+  insertTextAtTextareaCursor,
+  insertTextByRef
+};

package/dist/editor/RichEditor.d.ts

@@ -0,0 +1,4 @@
+import type { RichEditorProps } from "./RichEditorImpl.js";
+export type { RichEditorProps, RichEditorView, RichEditorController } from "./RichEditorImpl.js";
+declare const RichEditor: import("react").ComponentType<RichEditorProps>;
+export default RichEditor;

package/dist/editor/RichEditor.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { clientLazy } from "@ai-matrx/rich-content/utils/client-lazy";
+import { Loader2 } from "lucide-react";
+const RichEditor = clientLazy(() => import("./RichEditorImpl.js"), {
+  loading: () => /* @__PURE__ */ jsxs("div", { className: "flex h-full min-h-40 items-center justify-center gap-2 text-sm text-muted-foreground", children: [
+    /* @__PURE__ */ jsx(Loader2, { className: "h-4 w-4 animate-spin" }),
+    " Opening the editor\u2026"
+  ] })
+});
+var RichEditor_default = RichEditor;
+export {
+  RichEditor_default as default
+};

package/dist/editor/RichEditorContext.d.ts

@@ -0,0 +1,16 @@
+import type { DeclaredVariable } from "../core/variables.js";
+export interface RichEditorContextValue {
+    /** Variables the surface declares; null when it declares none (a note). */
+    variables: readonly DeclaredVariable[] | null;
+    /** Record that the person changed or removed this island ON PURPOSE (its own editor, its Remove). */
+    approveIsland: (raw: string) => void;
+    /** Upload an image and return the markdown that shows it, or null when it failed (the uploader said why). */
+    uploadImage: (file: File) => Promise<string | null>;
+    /** Ask the person for a kind to insert; resolves with the kind JSON's markdown, or null. */
+    pickKind: () => Promise<string | null>;
+    /** A new variable the person created from the {{ menu. */
+    onDeclareVariable?: (name: string) => void;
+    readOnly: boolean;
+}
+export declare const RichEditorContext: import("react").Context<RichEditorContextValue>;
+export declare function useRichEditorContext(): RichEditorContextValue;

package/dist/editor/RichEditorContext.js

@@ -0,0 +1,17 @@
+"use client";
+import { createContext, useContext } from "react";
+const noop = () => void 0;
+const RichEditorContext = createContext({
+  variables: null,
+  approveIsland: noop,
+  uploadImage: async () => null,
+  pickKind: async () => null,
+  readOnly: false
+});
+function useRichEditorContext() {
+  return useContext(RichEditorContext);
+}
+export {
+  RichEditorContext,
+  useRichEditorContext
+};

package/dist/editor/RichEditorImpl.d.ts

@@ -0,0 +1,137 @@
+import "./rich-editor.css";
+import { type ReactNode, type Ref } from "react";
+import type { SourceFeature } from "@ai-matrx/agents/generated/source-attribution";
+import type { ContentSource } from "@ai-matrx/rich-content/rich-document/types";
+import { type SavePlan } from "../core/save-plan.js";
+import type { CaretContext } from "../core/caret-context.js";
+import type { DeclaredVariable } from "../core/variables.js";
+import { type ImagePolicyDeclaration } from "@ai-matrx/rich-content/levels/prose/remote-image-policy";
+import type { AnnotationRecord } from "@ai-matrx/rich-content/rich-document/host-types";
+export type RichEditorView = "visual" | "source" | "preview";
+/**
+ * What a host that carries its OWN chrome (view switch, find, outline, dictation,
+ * its own right-click menu) drives the editor through. Every verb acts on the
+ * view that is showing.
+ */
+export interface RichEditorController {
+    focus: () => void;
+    /** The selected text of the showing view ("" when nothing is selected). */
+    selectedText: () => string;
+    /** Put text at the caret, replacing the selection (markdown stays markdown). */
+    replaceSelection: (text: string) => void;
+    /** Insert a new block before / after the selection; false when it could not. */
+    insertText: (text: string, where: "before" | "after") => boolean;
+    /**
+     * Replace the WHOLE text (the context menu's full-content `onTextReplace`
+     * contract: Cut / Paste / an AI result's Replace / an agent's
+     * widget_text_replace all hand over the entire new value).
+     */
+    setText: (text: string) => void;
+    /** The text now, with any pending keystrokes delivered through onChange first. */
+    flush: () => string;
+    /**
+     * Steps the showing view's own undo history holds (zero in Preview and right
+     * after a mount). A host with a record-level history (notes) answers ⌘Z
+     * itself when this is zero, so undo survives a remount.
+     */
+    historyDepth: () => {
+        undo: number;
+        redo: number;
+    };
+    /** Open the editor's own find (and replace) bar — it skips protected content. */
+    openFind: (withReplace?: boolean) => void;
+    /** Scroll to the heading that starts at (or nearest before) this source offset. */
+    jumpToOffset: (offset: number) => void;
+    /**
+     * Edit in place: put the caret where the person double-clicked the rendered
+     * text (`core/caret-context.ts`). False until the view is ready or when the
+     * text is not found — the caller retries or leaves the caret at the start.
+     */
+    placeCaret: (context: CaretContext) => boolean;
+}
+export interface RichEditorProps {
+    /** The stored text — what the save gate compares against. */
+    value: string;
+    /**
+     * Store the text. Resolve with the text AS STORED (read back) and the editor
+     * proves it byte-for-byte; resolve with nothing to trust the write.
+     */
+    onSave?: (text: string, plan: SavePlan) => Promise<string | void>;
+    /** Every change to the working text. */
+    onChange?: (text: string) => void;
+    /** Variables the surface declares; omit for a surface without variables (a note). */
+    variables?: readonly DeclaredVariable[] | null;
+    onDeclareVariable?: (name: string) => void;
+    /** The view it opens in: source for prompts/templates/skills, visual for prose. */
+    defaultView?: RichEditorView;
+    /**
+     * The view, held by the host (a host whose own control switches views). The
+     * editor delivers pending text before it switches, and reports every switch it
+     * makes itself (a shortcut, a refused switch) through `onViewChange`.
+     */
+    view?: RichEditorView;
+    onViewChange?: (view: RichEditorView) => void;
+    /**
+     * "full" (default): the editor's toolbar row — views, tools, dictation, Save.
+     * "bare": no row of its own; the host's chrome carries the view switch, find,
+     * outline and dictation (a host that saves by itself — autosave — has no Save).
+     * Shortcuts (⌘F, ⌘⌥H, ⌘⇧F, ⌘/) keep working either way.
+     */
+    chrome?: "full" | "bare";
+    /**
+     * The host wraps the editor in its OWN right-click menu (its surface, scope and
+     * record rows) — the editor then mounts none, so one menu answers. Drive text
+     * edits from that menu through `controllerRef`.
+     */
+    hostContextMenu?: boolean;
+    /** Receives the controller (see RichEditorController). */
+    controllerRef?: Ref<RichEditorController>;
+    readOnly?: boolean;
+    placeholder?: string;
+    /** The right-click menu's surface + attribution. */
+    surfaceName?: string;
+    sourceFeature?: SourceFeature;
+    /** The preview's action source (RichDocument). */
+    contentSource?: ContentSource;
+    /**
+     * The SAVED RECORD this buffer is, with its saved bytes, for Comment in the Visual view (chair
+     * ruling 2026-09-26: Comment appears when the buffer is a saved record, and is absent for an
+     * unsaved buffer). Derived from `contentSource` (a note, a chat answer, a saved working
+     * document; body = the last stored text) unless the host names it — the studio does, because
+     * its buffer is a copy of the loaded document. `null` turns it off. It applies only while the
+     * working text is byte-identical to `body`: the anchors index into those bytes.
+     */
+    annotationRecord?: (AnnotationRecord & {
+        body: string;
+    }) | null;
+    /** Label for the save button. */
+    saveLabel?: string;
+    className?: string;
+    /** Extra controls on the right of the toolbar (host actions). */
+    toolbarExtras?: ReactNode;
+    /**
+     * Leave the editor (an in-place editor going back to its reading view). Shows
+     * a Cancel button beside Save; the host decides what to do with unsaved text.
+     */
+    onCancel?: () => void;
+    /** Label for the cancel button. */
+    cancelLabel?: string;
+    /**
+     * Open with the outline beside the text (true) or closed (false). Default:
+     * open on desktop, closed on phones. A narrow host (a chat column) passes false.
+     */
+    defaultOutlineOpen?: boolean;
+    /**
+     * Save was pressed with nothing changed: the stored text is already exactly
+     * this. When given, it replaces the "Nothing changed" notice, so an in-place
+     * host can simply return to its reading view.
+     */
+    onNothingToSave?: () => void;
+    /**
+     * WHO WROTE the content shown — "self" | "other" | "ai" (or "inherit").
+     * Decides whether remote images load by themselves; forwarded to the
+     * renderer (components/rich-content/prose/remote-image-policy.tsx).
+     */
+    imagePolicy?: ImagePolicyDeclaration;
+}
+export default function RichEditorImpl({ value, onSave, onChange, variables, onDeclareVariable, defaultView, view: controlledView, onViewChange, chrome, hostContextMenu, controllerRef, readOnly, placeholder, surfaceName, sourceFeature, contentSource, annotationRecord, saveLabel, className, toolbarExtras, onCancel, cancelLabel, defaultOutlineOpen, onNothingToSave, imagePolicy, }: RichEditorProps): import("react").JSX.Element;