@ai-matrx/rich-editor 0.2.11 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.1
+### A block goes above only from the very start of its paragraph (G15, 2026-10-07)
+
+- `blockSide` / `nearestSide` / `blockSideOfSelection` (`"nearest"`): a caret at offset 0 of a non-empty block → BEFORE it; anywhere else → AFTER. The 0.3.0 "first half → before" rule counted characters, so a right-click 89% along the first visual line of a wrapped paragraph put the block above it.
+
+Consumer action: none; hosts already pass `"nearest"`.
+
+## 0.3.0
+### A block lands on the side of the click; a trailing space stays typed (G11B, 2026-10-07)
+
+- `insertText(text, where)` takes `"nearest"` (new `BlockPlacement` type, `core/text-insertion`): from the start or the first half of the caret's paragraph the block goes BEFORE it, otherwise AFTER. `insertAtRichCaret(…, "block")` uses it. New helpers `blockSide`, `nearestSide` (plain text) and `blockSideOfSelection` (visual).
+- A space typed at the end of a paragraph or heading survives the editor rebuilding from its own text — typing after "six." used to give "six.Then".
+- A reference/action card in Write takes the whole line on a phone; its grip and tools wrap under it.
+
+Consumer action: none required; a host passing `"before" | "after"` keeps that exact behaviour.
+
 ## 0.2.11
 ### Bold (and every inline mark) toggles like a real editor
 

package/dist/core/block-insert.d.ts

@@ -18,10 +18,18 @@
  */
 import { type Node as PMNode, type Schema } from "@tiptap/pm/model";
 import type { Transaction } from "@tiptap/pm/state";
+import { type BlockPlacement } from "./text-insertion.js";
 /** The top-level boundary a block goes to, relative to [from, to]. */
 export declare function blockInsertPosition(doc: PMNode, from: number, to: number, where: "before" | "after"): number;
+/**
+ * The side of its block a selection belongs on (`blockSide`): a collapsed
+ * caret at the very start of a textblock → "before"; anything else — the
+ * middle, the end, an empty block, a selected chip, ⌘A, a position between
+ * blocks — → "after".
+ */
+export declare function blockSideOfSelection(doc: PMNode, from: number, to: number): "before" | "after";
 /**
  * Insert markdown as its own block(s) before / after the selection's block.
  * Throws nothing it can avoid; returns false when the text parses to nothing.
  */
-export declare function insertMarkdownBlock(tr: Transaction, schema: Schema, text: string, where: "before" | "after"): boolean;
+export declare function insertMarkdownBlock(tr: Transaction, schema: Schema, text: string, where: BlockPlacement): boolean;

package/dist/core/block-insert.js

@@ -1,15 +1,23 @@
 import { Fragment, Slice } from "@tiptap/pm/model";
 import { Selection } from "@tiptap/pm/state";
 import { markdownToSlice } from "./paste-markdown.js";
+import { blockSide } from "./text-insertion.js";
 function blockInsertPosition(doc, from, to, where) {
   const clamp = (pos) => Math.max(0, Math.min(pos, doc.content.size));
   const $pos = doc.resolve(clamp(where === "before" ? from : to));
   if ($pos.depth === 0) return $pos.pos;
   return where === "before" ? $pos.before(1) : $pos.after(1);
 }
+function blockSideOfSelection(doc, from, to) {
+  if (from !== to) return "after";
+  const $pos = doc.resolve(Math.max(0, Math.min(from, doc.content.size)));
+  if ($pos.depth === 0 || !$pos.parent.isTextblock) return "after";
+  return blockSide($pos.parentOffset, $pos.parent.content.size);
+}
 function insertMarkdownBlock(tr, schema, text, where) {
   const { from, to } = tr.selection;
-  const at = blockInsertPosition(tr.doc, from, to, where);
+  const side = where === "nearest" ? blockSideOfSelection(tr.doc, from, to) : where;
+  const at = blockInsertPosition(tr.doc, from, to, side);
   const parsed = markdownToSlice(text, schema);
   if (parsed.size === 0) return false;
   const blocks = new Slice(Fragment.from(parsed.content), 0, 0);
@@ -20,5 +28,6 @@ function insertMarkdownBlock(tr, schema, text, where) {
 }
 export {
   blockInsertPosition,
+  blockSideOfSelection,
   insertMarkdownBlock
 };

package/dist/core/markdown-parse.js

@@ -453,7 +453,8 @@ function parseProseBlock(block, schema, adjacency, nextId, linkDefinitions) {
     if (!last || children.length === segmentStart) {
       return { children: [], lockedReason: "markdown the parser could not map" };
     }
-    last.trail += segment.after;
+    const kept = keepTrailingSpaces(last, segment.after, state);
+    last.trail += segment.after.slice(kept);
   }
   children.forEach(
     (child, index) => adjacency.set(child.id, { trail: child.trail, next: children[index + 1]?.id ?? null })
@@ -494,6 +495,30 @@ function trimSegmentEnd(text, after) {
   const tail = /[ \t]+$/.exec(text)?.[0] ?? "";
   return tail ? { text: text.slice(0, text.length - tail.length), after: tail + after } : { text, after };
 }
+function keepTrailingSpaces(last, after, state) {
+  const tail = /^[ \t]+/.exec(after)?.[0] ?? "";
+  if (!tail || last.lockedReason !== null || last.trail !== "") return 0;
+  const type = last.json.type;
+  if (type !== "paragraph" && type !== "heading") return 0;
+  const content = [...last.json.content ?? []];
+  const end = content[content.length - 1];
+  if (end?.type === "text" && !end.marks?.length) {
+    content[content.length - 1] = { ...end, text: `${end.text ?? ""}${tail}` };
+  } else {
+    content.push({ type: "text", text: tail });
+  }
+  const json = { ...last.json, content };
+  try {
+    const node = state.schema.nodeFromJSON(json);
+    node.check();
+    if (serializeBlock(node, createSerializeContext(new Map(state.adjacency))) !== last.raw + tail) return 0;
+  } catch {
+    return 0;
+  }
+  last.json = json;
+  last.raw += tail;
+  return tail.length;
+}
 function parseTopToken(token, state) {
   const { schema, islands, adjacency, nextId } = state;
   const { body, trail } = splitTrail(token.raw);

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

@@ -11,4 +11,23 @@ export declare function insertTextByRef(textareaRef: HTMLTextAreaElement | null,
  * 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;
+export declare function blockBoundary(text: string, from: number, to: number, where?: BlockPlacement): number;
+/**
+ * Where a block goes relative to the caret's block: `before` it, `after` it, or
+ * `nearest` — before it from the very start of the block, after it otherwise.
+ */
+export type BlockPlacement = "before" | "after" | "nearest";
+/**
+ * 🚨 A BLOCK GOES ABOVE ONLY FROM THE VERY START OF ITS BLOCK. A matrx fence is
+ * block-level, so it never sits mid-sentence: a caret at offset 0 of a
+ * non-empty block (a right-click left of its first character lands there too)
+ * puts the block BEFORE it; anywhere else (the middle, the end, an empty block)
+ * puts it AFTER. The old "first half → before" rule measured characters, so a
+ * right-click at 89% along the first visual line of a wrapped paragraph put the
+ * block ABOVE it (G15 review, 2026-10-07). `offset` is the caret's place inside
+ * its block, `length` the block's size. ONE rule for the visual editor, the
+ * source view and every plain-text field.
+ */
+export declare function blockSide(offset: number, length: number): "before" | "after";
+/** `blockSide` for the caret's LINE in plain text (a non-empty selection keeps "after"). */
+export declare function nearestSide(text: string, from: number, to: number): "before" | "after";

package/dist/core/text-insertion.js

@@ -40,6 +40,7 @@ function insertTextByRef(textareaRef, text) {
   return insertTextAtTextareaCursor(textareaRef, text);
 }
 function blockBoundary(text, from, to, where = "after") {
+  if (where === "nearest") where = nearestSide(text, from, to);
   if (where === "after") {
     const newline2 = text.indexOf("\n", to);
     return newline2 === -1 ? text.length : newline2;
@@ -48,8 +49,21 @@ function blockBoundary(text, from, to, where = "after") {
   const newline = text.lastIndexOf("\n", from - 1);
   return newline === -1 ? 0 : newline + 1;
 }
+function blockSide(offset, length) {
+  if (length <= 0) return "after";
+  return offset <= 0 ? "before" : "after";
+}
+function nearestSide(text, from, to) {
+  if (from !== to) return "after";
+  const start = from <= 0 ? 0 : text.lastIndexOf("\n", from - 1) + 1;
+  const newline = text.indexOf("\n", from);
+  const end = newline === -1 ? text.length : newline;
+  return blockSide(from - start, end - start);
+}
 export {
   blockBoundary,
+  blockSide,
   insertTextAtTextareaCursor,
-  insertTextByRef
+  insertTextByRef,
+  nearestSide
 };

package/dist/editor/RichEditorImpl.d.ts

@@ -4,6 +4,7 @@ import type { SourceFeature } from "@ai-matrx/agents/generated/source-attributio
 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 { BlockPlacement } from "../core/text-insertion.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";
@@ -20,7 +21,7 @@ export interface RichEditorController {
     /** 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;
+    insertText: (text: string, where: BlockPlacement) => boolean;
     /**
      * Replace the WHOLE text (the context menu's full-content `onTextReplace`
      * contract: Cut / Paste / an AI result's Replace / an agent's

package/dist/editor/caretInsert.d.ts

@@ -2,10 +2,11 @@
  * THE context menu's insert-at-the-caret for a host that drives a RichEditor.
  *
  * `inline` text replaces the selection where it is. A `block` (a reference
- * fence) goes through `insertText(…, "after")`, which places it on its own
- * paragraph at the END of the caret's block — never inside a word (G5 review,
- * 2026-10-02: "of" became "o" + block + "f"). One helper so the three note
- * hosts (desktop, content editor, mobile) cannot drift.
+ * fence) goes through `insertText(…, "nearest")`: its own paragraph, never
+ * inside a word (G5 review, 2026-10-02: "of" became "o" + block + "f"), on the
+ * side of the caret's block the click was nearer to — BEFORE it from its start
+ * or first half, AFTER it otherwise (G11B review, 2026-10-07). One helper so
+ * the three note hosts (desktop, content editor, mobile) cannot drift.
  */
 import type { RichEditorController } from "./RichEditorImpl.js";
 export declare function insertAtRichCaret(rich: RichEditorController | null, text: string, placement?: "inline" | "block"): boolean;

package/dist/editor/caretInsert.js

@@ -1,6 +1,6 @@
 function insertAtRichCaret(rich, text, placement = "inline") {
   if (!rich) return false;
-  if (placement === "block") return rich.insertText(text, "after");
+  if (placement === "block") return rich.insertText(text, "nearest");
   rich.replaceSelection(text);
   return true;
 }

package/dist/source/SourceEditor.js

@@ -44,7 +44,7 @@ import {
   setFindHighlights,
   setIslandRendering
 } from "./live-preview.js";
-import { blockBoundary } from "../core/text-insertion.js";
+import { blockBoundary, nearestSide } from "../core/text-insertion.js";
 const RAW_THEME = EditorView.theme({
   ".cm-content, .cm-line": {
     fontFamily: "var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)",
@@ -300,8 +300,10 @@ function SourceEditor({
       const v = view.current;
       if (!v) return false;
       const { from, to } = v.state.selection.main;
-      const at = blockBoundary(v.state.doc.toString(), from, to, where);
-      const insert = where === "before" ? `${text}
+      const doc = v.state.doc.toString();
+      const side = where === "nearest" ? nearestSide(doc, from, to) : where;
+      const at = blockBoundary(doc, from, to, side);
+      const insert = side === "before" ? `${text}
 
 ` : `
 

package/dist/visual/VisualEditor.d.ts

@@ -1,4 +1,5 @@
 import { type Ref } from "react";
+import type { BlockPlacement } from "../core/text-insertion.js";
 import { type VisualLoadStats } from "../core/visual-document.js";
 import { type CaretCarry, type CaretContext } from "../core/caret-context.js";
 import type { FindOptions } from "../core/find-replace.js";
@@ -19,7 +20,7 @@ export interface EditorViewHandle {
     /** Replace the selection with literal text (markdown typed by an AI stays markdown). */
     replaceSelection: (text: string) => void;
     /** Insert a block before / after the selection; false when it could not. */
-    insertText: (text: string, where: "before" | "after") => boolean;
+    insertText: (text: string, where: BlockPlacement) => boolean;
     /** Flush pending text now (before a save or a view switch). */
     flush: () => string;
     /**

package/dist/visual/nodes/IslandBlockView.js

@@ -61,7 +61,7 @@ function IslandBlockView({ node, updateAttributes, deleteNode, selected, editor,
       NodeViewWrapper,
       {
         className: cn(
-          "rich-editor-island rich-editor-reference group/island relative my-1 flex min-w-0 items-start gap-1 rounded-md transition-colors",
+          "rich-editor-island rich-editor-reference group/island relative my-1 flex min-w-0 flex-wrap items-center gap-1 rounded-md transition-colors sm:flex-nowrap sm:items-start",
           selected && "ring-1 ring-primary/40"
         ),
         "data-island-type": "matrx",
@@ -71,13 +71,13 @@ function IslandBlockView({ node, updateAttributes, deleteNode, selected, editor,
             "span",
             {
               "data-drag-handle": true,
-              className: "mt-1.5 shrink-0 cursor-grab touch-none text-muted-foreground/60 opacity-100 hover:text-foreground sm:opacity-0 sm:group-hover/island:opacity-100",
+              className: "shrink-0 cursor-grab touch-none text-muted-foreground/60 opacity-100 hover:text-foreground sm:mt-1.5 sm:opacity-0 sm:group-hover/island:opacity-100",
               "aria-hidden": true,
               children: /* @__PURE__ */ jsx(GripVertical, { className: "h-3.5 w-3.5" })
             }
           ),
-          /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1", children: /* @__PURE__ */ jsx(IslandPreview, { raw, islandType }) }),
-          /* @__PURE__ */ jsxs("div", { className: "flex shrink-0 items-center gap-0.5 text-muted-foreground opacity-100 sm:opacity-0 sm:transition-opacity sm:group-hover/island:opacity-100 sm:group-focus-within/island:opacity-100", children: [
+          /* @__PURE__ */ jsx("div", { className: "order-first min-w-0 basis-full sm:order-none sm:basis-0 sm:flex-1", "data-island-body": "", children: /* @__PURE__ */ jsx(IslandPreview, { raw, islandType }) }),
+          /* @__PURE__ */ jsxs("div", { className: "ml-auto flex shrink-0 items-center gap-0.5 text-muted-foreground opacity-100 sm:ml-0 sm:opacity-0 sm:transition-opacity sm:group-hover/island:opacity-100 sm:group-focus-within/island:opacity-100", children: [
             /* @__PURE__ */ jsx("button", { type: "button", className: "rounded p-1 hover:bg-muted hover:text-foreground pointer-coarse:flex pointer-coarse:h-11 pointer-coarse:w-11 pointer-coarse:items-center pointer-coarse:justify-center", onClick: copy, title: `Copy this ${meta.label.toLowerCase()}`, children: copied ? /* @__PURE__ */ jsx(Check, { className: "h-3.5 w-3.5" }) : /* @__PURE__ */ jsx(Copy, { className: "h-3.5 w-3.5" }) }),
             !readOnly && /* @__PURE__ */ jsx(
               "button",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/rich-editor",
-  "version": "0.2.11",
+  "version": "0.3.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",