@latentic/live-markdown 0.0.1 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## [0.1.1] - 2026-08-24
+
+### Added
+
+- `inlineScanRulesFacet`, `scanInline`, `escapeText`/`escapeAttr` and their
+  types are exported. 0.1.0 shipped the seam but left it unreachable: a
+  third-party extension could contribute a rule for a construct Lezer parses
+  (`nodeRulesFacet`, public since 0.0.1) but not for one it does not, which is
+  half a contract.
+
+## [0.1.0] - 2026-08-24
+
+First release from the editor's own repository, and the first with CI on more
+than one platform.
+
+### Fixed
+
+- **A `[…]` keeps its brackets until it resolves to a link.** Lezer emits a
+  `Link` node for every bracketed span; CommonMark only makes `[label]` a link
+  when the document also carries a `[label]: url` definition. Reading the node
+  as the answer hid the brackets out of ordinary prose — `arr[0]` rendered as
+  `arr0`, `see [3]` as `see 3` — and stripped every optional argument from a
+  pasted LaTeX block (`\begin{tikzpicture}[scale=0.42]`). Unresolved, the
+  brackets are content: visible, unstyled, and no longer atomic to the caret.
+  This also matches what a CommonMark exporter produces for the same input.
+
+- **A table cell renders what the paragraph above it renders.** Cells walk the
+  Lezer tree, and four constructs have no node in it — wikilinks,
+  `==highlight==`, footnote references and `$math$` are found by scanning text.
+  Cells showed `$x^2$` as source, and mangled two of the others outright
+  (`[[Some Note]]` → `[Some Note]`). Features now contribute a pattern and its
+  markup through `inlineScanRulesFacet`, and the cell renderer carves those
+  spans out before walking the tree.
+
+- **A parse budget that holds on more than the fastest machine.** `treeAt` spent
+  at most 50ms driving the parse to a queried position, against a worst case
+  measured at 43ms — seven milliseconds of headroom. On a slower machine
+  `ensureSyntaxTree` returned null, the lookup fell back to the viewport-limited
+  tree, and a delete crossed a fence boundary the guard should have walled.
+  Now 150ms.
+
+### Added
+
+- `inlineScanRulesFacet` and `scanInline` — the seam for a construct Lezer does
+  not parse, so any renderer can see it, not just the decoration plugins.
+- `linkResolves` / `linkHasVisibleLabel` (`core/linkResolution`).
+
+### Documentation
+
+- `styles.css` still called the package `ai-editor`, and both it and the README
+  promised that mathematics needs no CSS import. It does — KaTeX renders
+  through its own stylesheet, which no CodeMirror theme can supply.
+
+## [0.0.1] - 2026-08-23
+
+Initial publish, extracted from the Compose monorepo.

package/README.md

@@ -1,8 +1,14 @@
 # @latentic/live-markdown
 
-A rich markdown editor for React — write like Notion, store as plain `.md`.
+[![npm](https://img.shields.io/npm/v/@latentic/live-markdown)](https://www.npmjs.com/package/@latentic/live-markdown)
+[![CI](https://github.com/getlatentic/live-markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/getlatentic/live-markdown/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@latentic/live-markdown)](LICENSE)
 
-Built on [CodeMirror 6](https://codemirror.net/). Headings, bold, italic, lists, tables, images, math, footnotes, and code blocks render inline as you type. The file on disk is always standard markdown — no proprietary format, no AST translation layer, no lock-in.
+**WYSIWYG markdown editing for React — where the markdown is still the document.**
+
+A markdown editor built on [CodeMirror 6](https://codemirror.net/). Headings, tables, LaTeX math, Mermaid diagrams, images, footnotes and code blocks render inline as you type — there is no split-screen preview pane to sync, and no syntax left on screen to read past.
+
+And unlike rich-text editors built on ProseMirror, Tiptap, Slate or Lexical, there is no intermediate document model to translate through. `value` in and `onChange` out are the same markdown string, byte for byte, YAML frontmatter included.
 
 ```tsx
 import { CodeMirrorMarkdownEditor } from "@latentic/live-markdown";
@@ -25,7 +31,7 @@ Most markdown editors fall into two camps:
 | **Raw editors** | CodeMirror, Monaco, Ace | Fast, plain text — but users see `## Heading`, not a heading |
 | **Rich editors** | Tiptap, ProseMirror, Slate, Lexical | WYSIWYG — but the internal model is a custom AST, not markdown. Round-tripping to `.md` is lossy or fragile |
 
-**@latentic/live-markdown sits in between.** The source of truth is the raw markdown string. CodeMirror parses it with Lezer, and a decoration engine replaces syntax tokens with rendered widgets in real time — `## Heading` becomes a styled heading, `- item` becomes a bullet, `![alt](src)` becomes an inline image. You get the editing experience of Notion or Google Docs, but `value` in and `onChange` out is always a plain markdown string. No AST translation, no serialization bugs, no format lock-in.
+**@latentic/live-markdown sits in between.** The source of truth is the raw markdown string. CodeMirror parses it with Lezer, and a decoration engine replaces syntax tokens with rendered widgets in real time — `## Heading` becomes a styled heading, `- item` becomes a bullet, `![alt](src)` becomes an inline image. You edit the rendered form directly — no syntax on screen, no preview pane to keep in sync — while `value` in and `onChange` out stays a plain markdown string. No AST translation, no serialization bugs, no format lock-in.
 
 The boundary semantics this demands — what every keystroke does at every construct edge — are specified in [docs/interaction-spec.md](docs/interaction-spec.md) and enforced by its conformance matrix (`interactionMatrix.test.ts`); block-level behaviors are specified executably in `src/codemirror/features/*.feature`.
 
@@ -38,11 +44,14 @@ The boundary semantics this demands — what every keystroke does at every const
 | Round-trip fidelity | Byte-for-byte | Lossy (serializer) | Byte-for-byte | MDX subset | Lossy |
 | YAML frontmatter | Preserved, never stripped | Plugin (varies) | No | Plugin | No |
 | LaTeX math | Inline KaTeX | Plugin | No | Plugin | No |
+| Mermaid diagrams | Rendered inline | Plugin | No | Plugin | No |
 | Large files (1 MB+) | Fast (CodeMirror) | Slow (DOM-per-node) | Fast | Slow | Slow |
 | Tables | GFM, cell navigation | Plugin | Basic | Plugin | Slash command |
 | Image paste/drop | Built-in | Plugin | No | Plugin | Plugin |
 | Framework | React | React / Vue / vanilla | Vanilla / adapters | React | React |
-| Bundle size | ~80 KB (gzip, editor core) | ~120 KB+ | ~40 KB | ~150 KB+ | ~200 KB+ |
+| Bundle size | 57 KB gzipped* | ~120 KB+ | ~40 KB | ~150 KB+ | ~200 KB+ |
+
+\* Measured on the published bundle. CodeMirror, KaTeX and Mermaid are external, so you pay for a renderer only where your documents use one — the other figures are the projects' own published numbers and are not all drawn on the same basis.
 
 ### Key differentiators
 
@@ -72,6 +81,7 @@ The boundary semantics this demands — what every keystroke does at every const
 - **Horizontal rules**
 - **Footnotes** — inline marker with hover preview
 - **LaTeX math** — inline `$...$` and display `$$...$$` via KaTeX
+- **Mermaid diagrams** — a ```` ```mermaid ```` fence renders as a live diagram; click to select, double-click for the source
 - **Wikilinks** — `[[Page]]` and `[[Page|alias]]` with Cmd/Ctrl-click navigation
 - **Links** — Cmd/Ctrl-click to open, auto-detection
 
@@ -102,7 +112,7 @@ pnpm add @latentic/live-markdown
 
 Peer dependencies: `react` and `react-dom` (18+).
 
-All *in-editor* styling (headings, code, lists, tables, image widgets, math, links) ships with the editor as a CodeMirror theme and applies automatically — no CSS import needed. For the outer container layout (so the editor fills its parent and scrolls), import the small stylesheet once:
+All *in-editor* styling (headings, code, lists, tables, image widgets, links) ships with the editor as a CodeMirror theme and applies automatically — no CSS import needed. For the outer container layout (so the editor fills its parent and scrolls), import the small stylesheet once:
 
 ```ts
 import "@latentic/live-markdown/styles.css";
@@ -110,6 +120,12 @@ import "@latentic/live-markdown/styles.css";
 
 Skip it if your app already lays the editor out as a flex child.
 
+Mathematics is the exception. KaTeX renders through its own stylesheet, which no CodeMirror theme can supply — without it `$x$` still typesets, just unstyled (a fraction stops stacking). If your documents use math:
+
+```ts
+import "katex/dist/katex.min.css";
+```
+
 ---
 
 ## Usage
@@ -254,12 +270,62 @@ The decoration engine walks the Lezer syntax tree on every document change, asks
 - [x] Host-environment seams (image storage/resolution, link opening) with browser defaults
 - [x] Self-themed editor surface (CodeMirror theme ships with the package)
 - [x] Public extension API for contributing node rules (`MarkdownExtension.rules` → `nodeRulesFacet`)
+- [ ] [Ship the engine without React](https://github.com/getlatentic/live-markdown/issues/1) — the editor is React only at its edge: of 195 source files, one component and one `type ReactNode` import name it. Splitting `/react` into a subpath entry frees the engine for any framework, or none
 - [ ] Frontmatter as a toggleable extension (default on, disable via prop)
 - [ ] Collaborative editing (CM6 collab extension)
 - [ ] Slash commands (`/` menu for inserting blocks)
 
 ---
 
+## Development
+
+```sh
+pnpm install
+pnpm exec playwright install webkit   # once — for the browser tier below
+pnpm check                            # typecheck + build + both test tiers
+```
+
+Tests run in two tiers, and the split is deliberate:
+
+| tier | command | what it is for |
+|---|---|---|
+| default | `pnpm test` | everything that does not need layout — jsdom and node |
+| browser | `pnpm test:browser` | real WebKit, for what jsdom cannot judge |
+
+jsdom has no layout engine, so caret geometry, click placement, drawn selection
+and KaTeX metrics all pass in it whatever they do on screen. Anything that
+depends on where a box actually lands belongs in a `*.browser.test.ts`.
+
+`pnpm build` is part of the gate rather than a release step: `tsc --noEmit`
+never emits, so the errors that appear only when rolling up declarations — an
+exported anonymous class, an inferred type naming a transitive dependency by
+its package-manager path — stay invisible until a publish fails.
+
+### Releasing
+
+Publishing is caused by green CI, not preceded by it. `cargo`-style local
+publishing is not wired up on purpose: a published version cannot be taken
+back.
+
+```sh
+# 1. bump the version in package.json, land it on main
+# 2. tag the merged commit
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The tag triggers `publish.yml`, which refuses to build at all if the tag is not
+an ancestor of `main` or disagrees with `package.json`, runs the full CI
+workflow against the tagged commit as a job it `needs`, and only then publishes.
+
+There is no npm token anywhere — not in the repository, not on a laptop.
+Publishing uses [trusted publishing](https://docs.npmjs.com/trusted-publishers):
+npm accepts a short-lived OIDC token minted for this workflow in this
+repository, so the credential cannot be leaked, reused, or forgotten about, and
+[provenance](https://docs.npmjs.com/generating-provenance-statements) is
+generated automatically from it.
+
+---
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _codemirror_view from '@codemirror/view';
 import { Decoration, ViewPlugin, DecorationSet, ViewUpdate, EditorView, Command, KeyBinding } from '@codemirror/view';
 import * as _codemirror_state from '@codemirror/state';
@@ -161,6 +160,57 @@ declare function structural(why: string): NodeRule;
  */
 declare const nodeRulesFacet: Facet<Readonly<Record<string, NodeRule>>, Readonly<Record<string, NodeRule>>>;
 
+/**
+ * Constructs Lezer never parses.
+ *
+ * Wikilinks, `==highlight==`, footnote references and `$math$` are not
+ * CommonMark, so no node exists for any of them and the editor finds each by
+ * scanning text (`codeContext.ts` documents the shared code guard). A renderer
+ * that walks the tree is therefore blind to all four — which is how a table cell
+ * came to show `$440 = 2 \times \frac{22}{7} \times r$` as literal source while
+ * the same expression rendered as mathematics in the paragraph above it.
+ *
+ * A feature contributes its pattern and its markup through this facet; the
+ * string renderers consult the facet and stay ignorant of what the constructs
+ * are. The decoration plugins keep their own viewport-scanning path — the two
+ * paths share the pattern, not the machinery, because one produces decorations
+ * over a live document and the other an HTML string.
+ */
+
+interface InlineScanRule {
+    readonly name: string;
+    /** Global-flagged; the scanner drives `exec` and resets `lastIndex`. */
+    readonly pattern: RegExp;
+    /** Markup for one match. Escaping document text is the rule's job. */
+    render(match: RegExpExecArray): string;
+    /**
+     * Upgrade rendered markup to real DOM, after sanitisation. Only for a
+     * construct whose rendering is DOM rather than markup (KaTeX): the generated
+     * nodes bypass the sanitiser, so a hydrate reads inert text from the element
+     * it replaces and never trusts the document.
+     */
+    hydrate?(root: HTMLElement): void;
+}
+declare const inlineScanRulesFacet: Facet<InlineScanRule, readonly InlineScanRule[]>;
+interface InlineScanMatch {
+    readonly from: number;
+    readonly to: number;
+    readonly html: string;
+}
+/**
+ * Every rule's matches in `text`, in document order, offset by `at`.
+ *
+ * Earliest wins, then longest — two constructs cannot both own one span, and
+ * the alternative (rule declaration order) would make the result depend on
+ * extension load order.
+ */
+declare function scanInline(rules: readonly InlineScanRule[], text: string, at?: number): InlineScanMatch[];
+
+/** Entity-escaping for the string renderers (table cells), which build HTML
+ *  text rather than DOM and so must neutralise markup in document content. */
+declare function escapeText(value: string): string;
+declare function escapeAttr(value: string): string;
+
 /**
  * A syntax tree that reaches `pos`.
  *
@@ -406,7 +456,7 @@ interface CodeMirrorMarkdownEditorProps {
      */
     onFlushReady?: (flush: (() => void) | null) => void;
 }
-declare function CodeMirrorMarkdownEditorInner({ mode, onChange, value, workspaceRoot, filePath, linkTargets, onNavigateToLink, toolbar, selectionActions, resolveImageSrc, saveImageBytes, onOpenExternalUrl, onCommentOnExcerpt, renderClipboardHtml, onAfterContentSwap, onFlushReady, }: CodeMirrorMarkdownEditorProps): react_jsx_runtime.JSX.Element;
+declare function CodeMirrorMarkdownEditorInner({ mode, onChange, value, workspaceRoot, filePath, linkTargets, onNavigateToLink, toolbar, selectionActions, resolveImageSrc, saveImageBytes, onOpenExternalUrl, onCommentOnExcerpt, renderClipboardHtml, onAfterContentSwap, onFlushReady, }: CodeMirrorMarkdownEditorProps): react.JSX.Element;
 /**
  * Memoised export — same reason as the Tiptap editor. AppShell
  * re-renders on every chat-thread token; without memoisation each
@@ -802,4 +852,4 @@ interface ResolveWorkspaceLinkOptions {
 }
 declare function resolveWorkspaceLink(href: string, options: ResolveWorkspaceLinkOptions): ResolvedWorkspaceLink | null;
 
-export { type CaretContextSnapshot, type CodeMirrorEditorMode, CodeMirrorMarkdownEditor, type CodeMirrorMarkdownEditorProps, type ComposedExtension, type DocumentTextChange, type EditorSelectionSnapshot, type Frontmatter, type FrontmatterValue, type HighlightedSpan, IMAGE_EDIT_ALT_EVENT, type ImageEditAltEventDetail, type ImageInsertOptions, type ImageInsertResult, type ImageResolveContext, type MarkdownDocument, type MarkdownExtension, type MermaidRenderResult, type NodeContext, type NodeRule, type NodeRules, type OpenExternalUrl, type Paint, type ResolveImageSrc, type ResolveWorkspaceLinkOptions, type ResolvedWorkspaceLink, type SaveImageBytes, type SourceRange, type ToolbarContribution, blockCommands, buildImageMarkdown, composeExtensions, computeFileDir, defaultResolveImageSrc, dirnamePath, editorBaseTheme, extractImageBlobs, extractImageFiles, footnoteExtension, formatCommands, getCachedMermaidPng, hasUriScheme, headingLine, hideAlways, highlightExtension, highlightFenceSpans, imageInsertHandlers, insertImageBlob, isAbsolutePath, isMermaidFenceInfo, joinPath, line, mark, markdownDecorationsPlugin, mathExtension, mermaidExtension, nodeRulesFacet, onEditorUpdate, parseFrontmatter, parseWikilinkBody, pickImageFileForCaret, raw, renderMermaidToSvg, resolveWikilinkTarget, resolveWorkspaceLink, serializeMarkdown, setFrontmatterField, showImageActionMenu, structural, tableExtension, treeAt, warmMermaidPng, wikilinkExtension };
+export { type CaretContextSnapshot, type CodeMirrorEditorMode, CodeMirrorMarkdownEditor, type CodeMirrorMarkdownEditorProps, type ComposedExtension, type DocumentTextChange, type EditorSelectionSnapshot, type Frontmatter, type FrontmatterValue, type HighlightedSpan, IMAGE_EDIT_ALT_EVENT, type ImageEditAltEventDetail, type ImageInsertOptions, type ImageInsertResult, type ImageResolveContext, type InlineScanMatch, type InlineScanRule, type MarkdownDocument, type MarkdownExtension, type MermaidRenderResult, type NodeContext, type NodeRule, type NodeRules, type OpenExternalUrl, type Paint, type ResolveImageSrc, type ResolveWorkspaceLinkOptions, type ResolvedWorkspaceLink, type SaveImageBytes, type SourceRange, type ToolbarContribution, blockCommands, buildImageMarkdown, composeExtensions, computeFileDir, defaultResolveImageSrc, dirnamePath, editorBaseTheme, escapeAttr, escapeText, extractImageBlobs, extractImageFiles, footnoteExtension, formatCommands, getCachedMermaidPng, hasUriScheme, headingLine, hideAlways, highlightExtension, highlightFenceSpans, imageInsertHandlers, inlineScanRulesFacet, insertImageBlob, isAbsolutePath, isMermaidFenceInfo, joinPath, line, mark, markdownDecorationsPlugin, mathExtension, mermaidExtension, nodeRulesFacet, onEditorUpdate, parseFrontmatter, parseWikilinkBody, pickImageFileForCaret, raw, renderMermaidToSvg, resolveWikilinkTarget, resolveWorkspaceLink, scanInline, serializeMarkdown, setFrontmatterField, showImageActionMenu, structural, tableExtension, treeAt, warmMermaidPng, wikilinkExtension };