@damiro/stylo 0.7.0 → 0.9.1

package/README.md

@@ -28,6 +28,9 @@ built in.
 - **`[[wikilinks]]`** — recognised, styled, and clickable, with an
   `onWikiLinkClick` callback and opt-in `[[` autocomplete from an index you
   supply (`wikiLinkSource`).
+- **`![[embed]]` transclusion** — opt-in on every rendered surface (`preview`,
+  `split`, and the in-place canvas): pass `embedSource` and Stylo hands you the
+  reference, you return the node to render in its place.
 - **Interactive tables** — edit a rendered table cell by cell in the in-place
   canvas, with row / column controls; or keep plain source pipes.
 - **Callouts** — `> [!note]` blockquotes render as tinted admonition blocks
@@ -71,7 +74,11 @@ npm install @codemirror/state @codemirror/view @codemirror/commands \
   @codemirror/language @codemirror/lang-markdown @lezer/common @lezer/highlight
 ```
 
-React 18+ is also a peer dependency. Import lines are in [Usage](#usage).
+React 18 or 19 is also a peer dependency (`react` + `react-dom`). Stylo ships
+**ES modules only** — there is no CommonJS build — so it needs a bundler (Vite,
+Next.js, …) or a native-ESM runtime. Stylesheet imports are in [Usage](#usage);
+the full setup checklist is in the
+[integration guide](./docs/wiki/guides/integration.md#requirements).
 
 The optional `@damiro/stylo/toolbar-settings` component (an end-user toolbar
 customizer) additionally needs `@dnd-kit/core @dnd-kit/sortable
@@ -82,10 +89,23 @@ customizer) additionally needs `@dnd-kit/core @dnd-kit/sortable
 
 ## Why
 
-Most React "Markdown editors" are either a bare `<textarea>` with a preview pane,
-or a full ProseMirror/Lexical rich-text stack that turns your document into an
-in-memory model you must serialize back to Markdown — lossy for frontmatter,
-wikilinks, and math, and hostile to files other tools also edit.
+Round-trip fidelity — plain Markdown in, the same plain Markdown out — rules out
+most of the field before features even enter it:
+
+- **TipTap, Milkdown, BlockNote** (all ProseMirror) and **Lexical** keep their
+  own document tree as the source of truth and serialize to Markdown on save —
+  exactly where frontmatter, `[[wikilinks]]` (not standard Markdown; needs a
+  custom node type), and math risk silently mangling on a round-trip.
+  **Toast UI Editor** is the same shape under different branding, and
+  considerably less themeable.
+- **EasyMDE / SimpleMDE** get the one axis that matters most right — genuinely
+  canonical Markdown in and out — but on CodeMirror 5, with no in-place live
+  rendering (raw source or a separate preview pane, not an Obsidian-style
+  live-preview feel), no wikilinks, no embeds, no frontmatter handling.
+  Adopting one means rebuilding most of what Stylo already does.
+- **Raw CodeMirror 6, no wrapper** is what's left after ruling those out — and
+  building the decoration canvas, the wikilink/embed/frontmatter layer, and a
+  theming contract from scratch is the reinvention Stylo exists to avoid.
 
 Stylo takes the Obsidian stance instead: **the Markdown string is the source of
 truth.** The editor is a thin, composable surface over it.
@@ -103,15 +123,16 @@ truth.** The editor is a thin, composable surface over it.
 
 ## Stack
 
-| Concern          | Library                                                                     |
-| ---------------- | --------------------------------------------------------------------------- |
-| Editing surface  | CodeMirror 6 (`@codemirror/lang-markdown`)                                  |
-| Find / replace   | `@codemirror/search` — `Mod-f` on every editing surface                     |
-| Render / preview | `react-markdown` + `remark-gfm` + `remark-math` + `rehype-katex` + `katex`  |
-| `[[wikilinks]]`  | small custom `remark` plugin                                                |
-| Frontmatter      | `remark-frontmatter` — fences recognised; key/value parsing deferred        |
-| Styling          | CSS Modules + `--stylo-*` CSS custom properties — no Tailwind, no CSS-in-JS |
-| Icons            | inline SVG, swappable via the `icons` prop — no icon-package dependency     |
+| Concern          | Library                                                                                      |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| Editing surface  | CodeMirror 6 (`@codemirror/lang-markdown`)                                                   |
+| Find / replace   | `@codemirror/search` — `Mod-f` on every editing surface                                      |
+| Render / preview | `react-markdown` + `remark-gfm` + `remark-math` + `rehype-katex` + `katex`                   |
+| `[[wikilinks]]`  | small custom `remark` plugin                                                                 |
+| `![[embeds]]`    | `remark` plugin (preview) + `EmbedWidget` portal registry (in-place), one host `embedSource` |
+| Frontmatter      | `remark-frontmatter` — fences recognised; key/value parsing deferred                         |
+| Styling          | CSS Modules + `--stylo-*` CSS custom properties — no Tailwind, no CSS-in-JS                  |
+| Icons            | inline SVG, swappable via the `icons` prop — no icon-package dependency                      |
 
 Styling and icon decisions are recorded in
 [ADR-002](./docs/journal/2026-09/2026-09-01_adr-002-editor-ux-and-customization.md);
@@ -159,6 +180,12 @@ Pass `wikiLinkSource` — `(query) => { target, label? }[]`, sync or async — t
 turn on `[[wikilink]]` autocomplete backed by your own index. See
 [Wikilink autocomplete](./docs/wiki/reference/props.md#wikilink-autocomplete).
 
+Pass `embedSource` — `(ref) => ReactNode`, sync or async — to resolve
+`![[embed]]` transclusion on every rendered surface, the in-place canvas
+included. Stylo detects the `![[…]]` (when it is alone on its line) and renders
+whatever you return; on the canvas the caret reveals the raw source. See
+[Embeds](./docs/wiki/reference/props.md#embeds).
+
 Fenced code blocks render in plain monospace — no token colours — until you pass
 `codeLanguages` with the grammars you want. Stylo bundles none by design (the
 full grammar set is ~110 lazy chunks). See