T-OAY3-md-engine-readme-v2

State: closed/done · Impact: medium · Complexity: small

Goal

The README documents v1 and lists the v2 features as out of scope; once E1–E12 land, that page misdescribes the package. This task rewrites it around the shipped v2 surface: the plugin contract, the command catalogue, anchors, the provider contract, the new widgets, and a hosting-and-chrome section pointing hosts at @sksizer/markdown-ui.

Today

Location	Role today
packages/ts/obsidian-editor/README.md	189 lines: v1 mechanic, usage, keymap, clicks, autocomplete, Vue usage, theming, an “Out of scope for v1 (v2 candidates)” section, deviations, testing
docs/LIBRARIES.md	Package roster; the obsidian-editor line describes the v1 scope

Proposed

The README keeps its opening (package role, the binding D-7VMX constraint) and is restructured:

Section	Content
The live-preview mechanic	Updated decoration families including the new widgets
Plugin API	EditorPlugin field table (id, syntax, inline, block, commands, keymap, completions, clicks, theme, extensions, prec), defineEditorPlugin, pluginsFacet, omit, a worked host-plugin example
Commands	Catalogue groups and ids, commandStates, runCommand, chord derivation (toCodeMirrorKey, keymapFromCommands, chordLabel), toCommandContributions
Anchors	anchorContext, readAnchors, anchorsListener, the link helpers
Provider contract	EditorIndexProvider including loadNote, saveAttachment, searchHeadings; the renderIcon option
Completion	Slash menu, [[note# heading completion, tooltip theming variables
Features	Tables, math, mermaid, details toggle, attachments, transclusion expansion, large-file guard — one short block each with the relevant option or command
Modes and line endings	setMode, modeForced, setOptions, CRLF preservation and the swap-writer guarantee
Vue usage	The full useObsidianEditor return
Hosting and chrome	New section: the engine is headless; toolbar, overlays, find, frontmatter and theming chrome live in @sksizer/markdown-ui (packages/ts/markdown-ui/); names the demo app for running the engine alone
Testing	Corpus, swap-writer suite, bench

The “Out of scope for v1 (v2 candidates)” section is deleted; anything still genuinely out of scope (collaborative editing, WYSIWYG table cell editing) moves to a short non-goals note. The docs/LIBRARIES.md obsidian-editor line is refreshed to the v2 description.

Approach

1. Re-read the shipped exports (packages/ts/obsidian-editor/src/index.ts) and write the section list above against what actually landed, not the plan.
2. Rewrite packages/ts/obsidian-editor/README.md; keep “Known deviations and notes” entries that still hold, delete the ones the v2 work resolved.
3. Refresh the obsidian-editor line in docs/LIBRARIES.md.
4. Cross-check every identifier named in the README against the package entry’s exports; bun test packages/ts/obsidian-editor stays green (docs-only change).

Files to touch

Location	Kind	Change
packages/ts/obsidian-editor/README.md	modify	Rewrite per the section table
docs/LIBRARIES.md	modify	Refresh the obsidian-editor description

Acceptance criteria

• AC-1: grep -n "Out of scope for v1" packages/ts/obsidian-editor/README.md returns nothing.
• AC-2: the README names each of the seven features enumerated in the Features row of the Proposed table, and each of the eleven EditorPlugin fields enumerated in the Plugin API row.
• AC-3: a “Hosting and chrome” heading exists and its section names @sksizer/markdown-ui.
• AC-4: the identifiers defineEditorPlugin, pluginsFacet, commandStates, runCommand, toCommandContributions, anchorContext, readAnchors, anchorsListener, setLinkAt and removeLinkAt are all named in the README and exported from packages/ts/obsidian-editor/src/index.ts (the cross-check pass in Approach step 4).
• AC-5: bun test packages/ts/obsidian-editor passes unchanged.

Out of scope

• The markdown-ui layer README (T-A0HT-md-ui-layer-skeleton creates it).
• The obsidian-md README (its helper additions are documented by T-RCWI-md-obsidian-md-sync-helpers).
• API changes of any kind; this is a docs-only task.

Dependencies

• Every engine task E1–E12, listed in depends_on: — the README documents what shipped, so it lands last in the engine sequence.

Discovery context

Member of milestone M-931L; engine step E13 of decision D-K3EM-markdown-editor-chrome-and-plugin-environment.

Depends on

T-4TE2-md-engine-plugin-contract, T-0GV4-md-engine-line-endings-corpus, T-EXQ7-md-engine-command-catalogue, T-MNRO-md-engine-anchors, T-N58P-md-engine-slash-and-heading-completion, T-UYTR-md-engine-tables, T-JPB0-md-engine-math, T-VCFL-md-engine-mermaid, T-DSVW-md-engine-html-details, T-LNJA-md-engine-large-file-guard, T-0BFS-md-engine-attachments, T-E99V-md-engine-transclusion-expansion

---

← Back to Tasks