@damiro/stylo 0.4.0 → 0.7.0

package/README.md

@@ -8,6 +8,8 @@ with Obsidian and any other Markdown tool. CodeMirror 6 handles editing;
 `remark` / `rehype` + KaTeX handle rendering; `[[wikilinks]]` and `$…$` math are
 built in.
 
+![The Stylo in-place canvas: a formatting toolbar above a document where headings, emphasis, a callout, KaTeX math, a table, task checkboxes, and highlighted code all render inline while the focused heading shows its `#` marker.](./docs/assets/stylo-in-place.png)
+
 > **Status:** working library, pre-1.0. The in-place canvas, `source` / `preview`
 > / `split` modes, the formatting toolbar, `[[wikilinks]]`, and KaTeX math all
 > ship and are covered by an integration test suite (`npm run test`). The public
@@ -15,15 +17,50 @@ built in.
 
 ---
 
-## Install
+## Features
+
+- **In-place canvas** — a live Obsidian-style surface: Markdown markers stay
+  hidden until the caret reaches the line, and headings, emphasis, links, and
+  math render inline without leaving the text. Plus `source`, `preview`, and
+  `split` modes.
+- **First-class math** — `$…$` and `$$…$$` rendered with KaTeX, live in the
+  canvas and in preview.
+- **`[[wikilinks]]`** — recognised, styled, and clickable, with an
+  `onWikiLinkClick` callback and opt-in `[[` autocomplete from an index you
+  supply (`wikiLinkSource`).
+- **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
+  (`note` / `tip` / `warning` / `danger` / `example`).
+- **Declarative toolbar** — trim, reorder, or extend the command set, supply
+  your own buttons, swap the icons.
+  [Reference](./docs/wiki/reference/toolbar.md).
+- **End-user toolbar customizer** — an optional `<StyloToolbarSettings>`
+  component: drag- and keyboard-reorderable.
+  [Reference](./docs/wiki/reference/toolbar-settings.md).
+- **Find / replace** — `Mod-f` on every editing surface.
+- **Frontmatter-aware** — YAML frontmatter round-trips untouched; `onFrontmatter`
+  hands you the raw block to parse.
+- **Opt-in code highlighting** — fenced code is coloured through a
+  `--stylo-syntax-*` token palette once you pass the grammars you want.
+  [Reference](./docs/wiki/reference/code-languages.md).
+- **Themeable** — structural CSS only; a `--stylo-*` custom-property palette with
+  a built-in dark mode.
+- **Imperative handle** — `focus()`, `scrollToHeading()`, `insertAtCursor()`, and
+  `getView()` for the raw CodeMirror `EditorView`.
 
-Not on npm yet — install straight from git. The `prepare` script builds the
-bundle during install, so there is nothing else to wire up:
+---
+
+## Install
 
 ```bash
-npm install github:studiodamiro/stylo
+npm install @damiro/stylo
 ```
 
+To track an unreleased commit, install from git instead
+(`npm install github:studiodamiro/stylo`) — the `prepare` script builds the
+bundle during install, so there is nothing else to wire up.
+
 CodeMirror, Lezer, and React are **peer dependencies** — Stylo shares the host's
 copy rather than bundling its own, so editor state, facets, and the syntax tree
 have a single identity (see [ADR-008](docs/journal/2026-09/2026-09-04_adr-008-codemirror-peer-dependency.md)).
@@ -113,11 +150,15 @@ function Editor() {
 your own `ToolbarCustomItem` buttons, and a `render` slot to wrap it. See the
 [toolbar reference](./docs/wiki/reference/toolbar.md).
 
-`inPlace` and `codeLanguages` are read once, when the editing surface mounts —
-give `<Stylo>` a `key` derived from the config to apply a change. Every other
-prop is fully reactive. See
+`inPlace`, `codeLanguages`, and `wikiLinkSource` are read once, when the editing
+surface mounts — give `<Stylo>` a `key` derived from the config to apply a
+change. Every other prop is fully reactive. See
 [props · applied at mount](./docs/wiki/reference/props.md#config-applied-at-mount).
 
+Pass `wikiLinkSource` — `(query) => { target, label? }[]`, sync or async — to
+turn on `[[wikilink]]` autocomplete backed by your own index. See
+[Wikilink autocomplete](./docs/wiki/reference/props.md#wikilink-autocomplete).
+
 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
@@ -128,17 +169,60 @@ full grammar set is ~110 lazy chunks). See
 Every colour is a `--stylo-*` custom property; override any of them on `.stylo`
 or an ancestor. A dark palette ships built in and activates under a `.dark` or
 `[data-theme="dark"]` ancestor — the `next-themes` / shadcn convention.
+`--stylo-font-size` (default `0.9375rem`) sets the base editor size and
+everything inside scales from it; `--stylo-font-family` and
+`--stylo-font-family-mono` set the prose and code fonts.
+
+---
+
+## Documentation
+
+Full documentation lives in the [wiki](./docs/wiki/index.md).
+
+**Architecture**
+
+- [System overview](./docs/wiki/architecture/overview.md) — the plain-text-first
+  model, the composed stack, and the render pipeline.
+
+**Guides**
+
+- [Integrating Stylo](./docs/wiki/guides/integration.md) — live vs. mount-time
+  props, persistence, stylesheet and peer-dependency setup, the theming
+  contract.
+- [Auto-save](./docs/wiki/guides/autosave.md) — why it is not a prop, and a
+  `useAutosave` hook to copy.
+- [Layout and touch](./docs/wiki/guides/layout-and-touch.md) — the page layouts,
+  the full-height recipe that pins a toolbar for free, and touch behaviour.
+
+**Reference**
+
+- [`<Stylo>` props](./docs/wiki/reference/props.md) — the prop surface, styling
+  tokens, and math setup.
+- [Formatting toolbar](./docs/wiki/reference/toolbar.md) — the `toolbar` prop,
+  command ids, keyboard shortcuts, and the `icons` override.
+- [`<StyloToolbarSettings />`](./docs/wiki/reference/toolbar-settings.md) — the
+  opt-in end-user customizer for the formatting bar.
+- [In-place canvas configuration](./docs/wiki/reference/in-place-config.md) — the
+  `inPlace` prop and its decoration toggles.
+- [Fenced-code highlighting](./docs/wiki/reference/code-languages.md) — the
+  `codeLanguages` prop and how to opt into language grammars.
+
+Engineering journal and Architectural Decision Records:
+[`docs/PROJECT_JOURNAL.md`](./docs/PROJECT_JOURNAL.md).
 
 ## Development
 
 ```bash
 npm install
-npm run dev        # playground
+npm run dev            # playground
 npm run typecheck
-npm run test
-npm run build      # library bundle
+npm run test           # unit suite (Vitest + jsdom)
+npm run test:browser   # in-place canvas in real Chromium (Playwright)
+npm run build          # library bundle
 ```
 
+`npm run test:browser` needs the browser once: `npx playwright install chromium`.
+
 ## License
 
 MIT © damiro