@canvist/web 0.0.0-stage → 0.2.0

package/dist/menus.js

@@ -0,0 +1,173 @@
+/** The gap between a menu and its anchor, in CSS px. */
+const DEFAULT_OFFSET = 8;
+/** The least distance between a menu and the viewport's edges, in CSS px. */
+const DEFAULT_PADDING = 8;
+/**
+ * Keep `element` above selected text. By default it shows while the editor
+ * is editable and focused (or focus is in the menu) and the selection is a
+ * range or whole blocks, never a caret.
+ */
+export function bubbleMenu(editor, element, options = {}) {
+    return attach(editor, element, {
+        placement: options.placement ?? "top",
+        offset: options.offset ?? DEFAULT_OFFSET,
+        padding: options.padding ?? DEFAULT_PADDING,
+        shouldShow: options.shouldShow ?? showsBubble,
+    });
+}
+/**
+ * Keep `element` beside the caret on an empty line, for inserting blocks.
+ * By default it shows while the editor is editable and focused (or focus is
+ * in the menu) and the caret is in an empty text block.
+ */
+export function floatingMenu(editor, element, options = {}) {
+    return attach(editor, element, {
+        placement: options.placement ?? "left",
+        offset: options.offset ?? DEFAULT_OFFSET,
+        padding: options.padding ?? DEFAULT_PADDING,
+        shouldShow: options.shouldShow ?? showsFloating,
+    });
+}
+/**
+ * Position `element` (`position: fixed`) beside `anchor`, a rectangle in
+ * viewport coordinates, on the preferred side if it fits and the opposite
+ * side if not, then shifted along that side to stay inside the viewport.
+ */
+export function placeMenu(element, anchor, options) {
+    const offset = options.offset ?? DEFAULT_OFFSET;
+    const padding = options.padding ?? DEFAULT_PADDING;
+    const view = element.ownerDocument.defaultView;
+    const viewport = {
+        width: view?.innerWidth ?? 0,
+        height: view?.innerHeight ?? 0,
+    };
+    // Out of the flow first, so it measures at the size it shows at.
+    element.style.position = "fixed";
+    const size = element.getBoundingClientRect();
+    const placement = fits(options.placement, anchor, size, viewport, offset)
+        ? options.placement
+        : OPPOSITE[options.placement];
+    const vertical = placement === "top" || placement === "bottom";
+    const [x, y] = vertical
+        ? [
+            anchor.x + anchor.width / 2 - size.width / 2,
+            placement === "top"
+                ? anchor.top - offset - size.height
+                : anchor.bottom + offset,
+        ]
+        : [
+            placement === "left"
+                ? anchor.left - offset - size.width
+                : anchor.right + offset,
+            anchor.y + anchor.height / 2 - size.height / 2,
+        ];
+    Object.assign(element.style, {
+        left: `${clamp(x, padding, viewport.width - size.width - padding)}px`,
+        top: `${clamp(y, padding, viewport.height - size.height - padding)}px`,
+    });
+    element.dataset["placement"] = placement;
+}
+const OPPOSITE = {
+    top: "bottom",
+    bottom: "top",
+    left: "right",
+    right: "left",
+};
+/** Follow `editor` with `element` until the returned menu is destroyed. */
+function attach(editor, element, attachment) {
+    const abort = new AbortController();
+    const signal = abort.signal;
+    const view = element.ownerDocument.defaultView;
+    let visible = false;
+    let frame = 0;
+    const update = () => {
+        cancelAnimationFrame(frame);
+        frame = 0;
+        const anchor = attachment.shouldShow(editor)
+            ? editor.selectionRect()
+            : null;
+        visible = anchor !== null;
+        element.style.visibility = visible ? "visible" : "hidden";
+        if (anchor !== null) {
+            placeMenu(element, editor.toClientRect(anchor), attachment);
+        }
+    };
+    // Edits and scrolling come in bursts: place once per frame.
+    const schedule = () => {
+        frame ||= requestAnimationFrame(update);
+    };
+    const unsubscribe = editor.subscribe(schedule);
+    // Focus inside the menu counts as focus in the editor.
+    element.dataset["canvistMenu"] = "";
+    // Hidden by visibility, so it keeps its size for placing, whatever
+    // `display` the page gives it.
+    element.hidden = false;
+    element.style.position = "fixed";
+    // Keep the editor's focus, and its selection, when the menu is pressed.
+    element.addEventListener("pointerdown", (event) => event.preventDefault(), {
+        signal,
+    });
+    element.addEventListener("focusout", schedule, { signal });
+    view?.addEventListener("scroll", schedule, {
+        capture: true,
+        passive: true,
+        signal,
+    });
+    view?.addEventListener("resize", schedule, { signal });
+    update();
+    const destroy = () => {
+        abort.abort();
+        unsubscribe();
+        cancelAnimationFrame(frame);
+        element.style.visibility = "hidden";
+        visible = false;
+    };
+    return {
+        get visible() {
+            return visible;
+        },
+        update,
+        destroy,
+        [Symbol.dispose]: destroy,
+    };
+}
+/** Whether `editor`, or a menu inside its document, holds focus while it is editable. */
+function active(editor) {
+    if (!editor.editable) {
+        return false;
+    }
+    const focused = editor.canvas.ownerDocument.activeElement;
+    return editor.focused ||
+        (focused !== null && focused.closest("[data-canvist-menu]") !== null);
+}
+function showsBubble(editor) {
+    const selection = editor.selection;
+    return active(editor) &&
+        (selection === null || !samePosition(selection.anchor, selection.head));
+}
+function showsFloating(editor) {
+    const selection = editor.selection;
+    return active(editor) && selection !== null &&
+        samePosition(selection.anchor, selection.head) &&
+        editor.blockText() === "";
+}
+function samePosition(a, b) {
+    return a.offset === b.offset && a.path.length === b.path.length &&
+        a.path.every((step, index) => step === b.path[index]);
+}
+/** Whether a menu of `size` fits on `placement`'s side of `anchor`. */
+function fits(placement, anchor, size, viewport, offset) {
+    switch (placement) {
+        case "top":
+            return anchor.top - offset - size.height >= 0;
+        case "bottom":
+            return anchor.bottom + offset + size.height <= viewport.height;
+        case "left":
+            return anchor.left - offset - size.width >= 0;
+        case "right":
+            return anchor.right + offset + size.width <= viewport.width;
+    }
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, Math.max(min, max)));
+}

package/dist/mirror.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The accessibility mirror: the document as semantic HTML, visually hidden
+ * beside the canvas, so screen readers and find-in-page tools can read
+ * what the canvas paints.
+ *
+ * It is the same HTML the server renders, refreshed when the browser is
+ * idle after a change rather than on every keystroke.
+ *
+ * @module
+ */
+/** A visually hidden copy of the document for assistive technology. */
+export declare class AccessibilityMirror {
+    #private;
+    /**
+     * A mirror inside `parent`, labelled `label`, whose content `render`
+     * returns as HTML.
+     */
+    constructor(parent: HTMLElement, label: string, render: () => string);
+    /** The document changed: refresh when the browser is next idle. */
+    schedule(): void;
+    /** Refresh now. */
+    refresh(): void;
+    dispose(): void;
+}

package/dist/mirror.js

@@ -0,0 +1,73 @@
+/**
+ * The accessibility mirror: the document as semantic HTML, visually hidden
+ * beside the canvas, so screen readers and find-in-page tools can read
+ * what the canvas paints.
+ *
+ * It is the same HTML the server renders, refreshed when the browser is
+ * idle after a change rather than on every keystroke.
+ *
+ * @module
+ */
+/** How long to wait for an idle moment before refreshing anyway. */
+const IDLE_TIMEOUT_MS = 500;
+/** A visually hidden copy of the document for assistive technology. */
+export class AccessibilityMirror {
+    #element;
+    #render;
+    #pending = 0;
+    /**
+     * A mirror inside `parent`, labelled `label`, whose content `render`
+     * returns as HTML.
+     */
+    constructor(parent, label, render) {
+        this.#render = render;
+        this.#element = parent.ownerDocument.createElement("div");
+        this.#element.className = "cv-mirror";
+        this.#element.setAttribute("role", "document");
+        this.#element.setAttribute("aria-label", label);
+        Object.assign(this.#element.style, {
+            position: "absolute",
+            width: "1px",
+            height: "1px",
+            margin: "-1px",
+            padding: "0",
+            border: "0",
+            overflow: "hidden",
+            clipPath: "inset(50%)",
+            whiteSpace: "nowrap",
+        });
+        parent.append(this.#element);
+        // Serializing a long document costs milliseconds: not before first paint.
+        this.schedule();
+    }
+    /** The document changed: refresh when the browser is next idle. */
+    schedule() {
+        if (this.#pending !== 0) {
+            return;
+        }
+        this.#pending = typeof requestIdleCallback === "function"
+            ? requestIdleCallback(() => this.refresh(), { timeout: IDLE_TIMEOUT_MS })
+            : window.setTimeout(() => this.refresh(), IDLE_TIMEOUT_MS);
+    }
+    /** Refresh now. */
+    refresh() {
+        this.#cancel();
+        this.#element.innerHTML = this.#render();
+    }
+    dispose() {
+        this.#cancel();
+        this.#element.remove();
+    }
+    #cancel() {
+        if (this.#pending === 0) {
+            return;
+        }
+        if (typeof cancelIdleCallback === "function") {
+            cancelIdleCallback(this.#pending);
+        }
+        else {
+            clearTimeout(this.#pending);
+        }
+        this.#pending = 0;
+    }
+}

package/dist/mod.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The canvist editor for the browser.
+ *
+ * canvist paints every pixel of the document on a canvas, measured by the
+ * browser itself, so the canvas wraps each line exactly where canvist's
+ * server-rendered HTML does and hydrating from that HTML moves nothing.
+ * Commands, queries, and plugins are typed from what you register: calling
+ * one you did not register is a type error.
+ *
+ * ```ts
+ * import { createEditor } from "@canvist/web";
+ *
+ * const editor = await createEditor(document.querySelector("#editor")!, {
+ * 	content: { format: "markdown", input: "Hello **world**" },
+ * });
+ * editor.select({ path: [0], offset: 0 }, { path: [0], offset: 5 });
+ * editor.commands.toggleItalic();
+ * ```
+ *
+ * @module
+ */
+export type { CanvistError, CommandName, CommandParams, Commands, Content, DocJson, ErrorCode, ExtensionDescriptor, Extensions, Format, Position, Queries, QueryName, QueryParams, QueryResult, Range, Registered, StarterKit, ThemeOptions, } from "@canvist/headless";
+export * from "@canvist/headless/extensions";
+export { borderScale, createEditor, detectBreaks, Editor, type EditorOptions, type EditorStats, type FrameReport, type Geometry, type InputLatency, type LineBreaks, pixelGrid, } from "./editor.ts";
+export { familyName, FontWatcher } from "./font-watcher.ts";
+export { type InputMode, usesEditContext } from "./input.ts";
+export { load, type WasmSource } from "./load.ts";
+export { CanvasMeasurer, type MeasureListener } from "./measure.ts";
+export { detectPlatform, type KeyPlatform } from "./platform.ts";
+export type { Plugin, PluginApis, PluginContext, Plugins } from "./plugin.ts";

package/dist/mod.js

@@ -0,0 +1,7 @@
+export * from "@canvist/headless/extensions";
+export { borderScale, createEditor, detectBreaks, Editor, pixelGrid, } from "./editor.js";
+export { familyName, FontWatcher } from "./font-watcher.js";
+export { usesEditContext } from "./input.js";
+export { load } from "./load.js";
+export { CanvasMeasurer } from "./measure.js";
+export { detectPlatform } from "./platform.js";

package/dist/placeholder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The placeholder: dimmed text shown where the first line starts while the
+ * document is empty.
+ *
+ * It is a DOM element over the canvas, set in the body text's font and
+ * line height, so it sits exactly where typed text will appear. Assistive
+ * technology reads it from the text field's `aria-placeholder` instead.
+ *
+ * @module
+ */
+/** Placeholder text over an empty document. */
+export declare class Placeholder {
+    #private;
+    /**
+     * A placeholder inside `parent` in the body text's CSS `font` and
+     * `color`.
+     */
+    constructor(parent: HTMLElement, font: string, color: string);
+    /** The text to show. An empty string shows nothing. */
+    set text(text: string);
+    /**
+     * Show the placeholder on the line `line` covers, in document
+     * coordinates, or hide it for `null`.
+     */
+    show(line: DOMRectReadOnly | null): void;
+    dispose(): void;
+}

package/dist/placeholder.js

@@ -0,0 +1,69 @@
+/**
+ * The placeholder: dimmed text shown where the first line starts while the
+ * document is empty.
+ *
+ * It is a DOM element over the canvas, set in the body text's font and
+ * line height, so it sits exactly where typed text will appear. Assistive
+ * technology reads it from the text field's `aria-placeholder` instead.
+ *
+ * @module
+ */
+/**
+ * How strongly the placeholder shows the body text's colour: enough for
+ * 4.5:1 contrast on the StarterKit's light and dark pages, as WCAG asks of
+ * placeholder text.
+ */
+const PLACEHOLDER_OPACITY = 0.62;
+/** Placeholder text over an empty document. */
+export class Placeholder {
+    #element;
+    /**
+     * A placeholder inside `parent` in the body text's CSS `font` and
+     * `color`.
+     */
+    constructor(parent, font, color) {
+        this.#element = parent.ownerDocument.createElement("div");
+        this.#element.className = "cv-placeholder";
+        this.#element.setAttribute("aria-hidden", "true");
+        Object.assign(this.#element.style, {
+            position: "absolute",
+            display: "none",
+            margin: "0",
+            font,
+            color,
+            opacity: String(PLACEHOLDER_OPACITY),
+            whiteSpace: "pre",
+            overflow: "hidden",
+            pointerEvents: "none",
+            userSelect: "none",
+        });
+        parent.append(this.#element);
+    }
+    /** The text to show. An empty string shows nothing. */
+    set text(text) {
+        this.#element.textContent = text;
+    }
+    /**
+     * Show the placeholder on the line `line` covers, in document
+     * coordinates, or hide it for `null`.
+     */
+    show(line) {
+        const style = this.#element.style;
+        if (line === null || this.#element.textContent === "") {
+            style.display = "none";
+            return;
+        }
+        // The caret is centred on where text starts.
+        const left = line.x + line.width / 2;
+        Object.assign(style, {
+            display: "block",
+            left: `${left}px`,
+            top: `${line.y}px`,
+            right: "0",
+            lineHeight: `${line.height}px`,
+        });
+    }
+    dispose() {
+        this.#element.remove();
+    }
+}

package/dist/platform.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Which modifier `Mod` means in key bindings.
+ *
+ * @module
+ */
+/** Which modifier `Mod` means in key bindings: Cmd on Apple platforms, Ctrl elsewhere. */
+export type KeyPlatform = "apple" | "other";
+/** Whether `navigator` belongs to an Apple platform, where `Mod` is Cmd. */
+export declare function detectPlatform(navigator: Navigator): KeyPlatform;

package/dist/platform.js

@@ -0,0 +1,12 @@
+/**
+ * Which modifier `Mod` means in key bindings.
+ *
+ * @module
+ */
+/** Whether `navigator` belongs to an Apple platform, where `Mod` is Cmd. */
+export function detectPlatform(navigator) {
+    const data = navigator.userAgentData;
+    return /Mac|iPhone|iPad|iPod/i.test(data?.platform ?? navigator.platform)
+        ? "apple"
+        : "other";
+}

package/dist/plugin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Plugins: optional features with their own typed API on the editor.
+ *
+ * A plugin is a name and a `setup` function. Whatever `setup` returns
+ * becomes `editor.plugins[name]`, typed from the plugin itself, so using a
+ * plugin's API without registering it is a type error, and code for an
+ * unregistered plugin is never loaded.
+ *
+ * @module
+ */
+import type { CanvasMeasurer } from "./measure.ts";
+/** What the editor offers a plugin while it sets up. */
+export interface PluginContext {
+    /** The element the editor renders into. */
+    readonly element: HTMLElement;
+    /** The measurer, to hear which fonts and text each relayout measured. */
+    readonly measurer: CanvasMeasurer;
+    /** Aborted when the editor is destroyed; release listeners and timers with it. */
+    readonly signal: AbortSignal;
+    /** Faces of `families` finished loading: re-measure only what uses them. */
+    fontsLoaded(families: readonly string[]): void;
+    /** Lay out text in `families` without drawing it, as during a `font-display` block period. */
+    hideFamilies(families: readonly string[]): void;
+    /** Paint again on the next frame. */
+    invalidate(): void;
+    /** Delay the editor's `ready()` until `work` settles. */
+    waitFor(work: Promise<unknown>): void;
+}
+/** A plugin named `Name` whose API is `Api`. */
+export interface Plugin<Name extends string = string, Api = unknown> {
+    readonly name: Name;
+    setup(context: PluginContext): Api;
+}
+/** A list of plugins. */
+export type Plugins = readonly Plugin[];
+/** Each registered plugin's API, by name. */
+export type PluginApis<P extends Plugins> = {
+    readonly [Entry in P[number] as Entry["name"]]: ReturnType<Entry["setup"]>;
+};

package/dist/plugin.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,87 @@
 {
-  "name": "@canvist/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@canvist/web",
+	"version": "0.2.0",
+	"description": "The canvist editor for the browser: a canvas that wraps text exactly like canvist's server-rendered HTML, with typed commands and a font plugin.",
+	"license": "Unlicense",
+	"homepage": "https://github.com/canvist/canvist/tree/main/packages/canvist-web#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/canvist/canvist.git",
+		"directory": "packages/canvist-web"
+	},
+	"bugs": {
+		"url": "https://github.com/canvist/canvist/issues",
+		"email": "support@canvist.dev"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"default": "./dist/mod.js"
+		},
+		"./fonts": {
+			"types": "./dist/fonts.d.ts",
+			"default": "./dist/fonts.js"
+		},
+		"./menus": {
+			"types": "./dist/menus.d.ts",
+			"default": "./dist/menus.js"
+		},
+		"./collab": {
+			"types": "./dist/collab.d.ts",
+			"default": "./dist/collab.js"
+		},
+		"./full": {
+			"types": "./dist/full.d.ts",
+			"default": "./dist/full.js"
+		},
+		"./wasm/canvist_web_bg.wasm": "./wasm/canvist_web_bg.wasm",
+		"./wasm-collab/canvist_web_bg.wasm": "./wasm-collab/canvist_web_bg.wasm",
+		"./wasm-full/canvist_web_bg.wasm": "./wasm-full/canvist_web_bg.wasm"
+	},
+	"files": [
+		"dist",
+		"wasm/*.js",
+		"wasm/*.d.ts",
+		"wasm/*.wasm",
+		"wasm-collab/*.js",
+		"wasm-collab/*.d.ts",
+		"wasm-collab/*.wasm",
+		"wasm-full/*.js",
+		"wasm-full/*.d.ts",
+		"wasm-full/*.wasm"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build:wasm": "npm run build:wasm:core && npm run build:wasm:collab && npm run build:wasm:full",
+		"build:wasm:core": "cd ../.. && RUSTFLAGS=\"--cfg canvist_omit_docs\" wasm-pack build crates/canvist_web --target web --profile wasm-web --no-opt --out-dir ../../packages/canvist-web/wasm --no-pack && rm packages/canvist-web/wasm/.gitignore && cd packages/canvist-web && node scripts/optimize-wasm.ts wasm/canvist_web_bg.wasm",
+		"build:wasm:collab": "cd ../.. && RUSTFLAGS=\"--cfg canvist_omit_docs\" wasm-pack build crates/canvist_web --target web --profile wasm-web --no-opt --out-dir ../../packages/canvist-web/wasm-collab --no-pack -- --features collab && rm packages/canvist-web/wasm-collab/.gitignore && cd packages/canvist-web && node scripts/optimize-wasm.ts wasm-collab/canvist_web_bg.wasm",
+		"build:wasm:full": "cd ../.. && RUSTFLAGS=\"--cfg canvist_omit_docs\" wasm-pack build crates/canvist_web --target web --profile wasm-web --no-opt --out-dir ../../packages/canvist-web/wasm-full --no-pack -- --features full && rm packages/canvist-web/wasm-full/.gitignore && cd packages/canvist-web && node scripts/optimize-wasm.ts wasm-full/canvist_web_bg.wasm",
+		"check:types": "tsc --noEmit",
+		"test": "node --test tests/*.test.ts",
+		"test:browser": "playwright test",
+		"dev": "vite --config tests/vite.config.ts",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build",
+		"size": "vite build --config tests/bundle/vite.config.ts --logLevel error && node scripts/bundle-size.ts --budget 359000"
+	},
+	"dependencies": {
+		"@canvist/headless": "^0.2.0"
+	},
+	"devDependencies": {
+		"@axe-core/playwright": "^4.14.0",
+		"@guidepup/virtual-screen-reader": "^0.33.0",
+		"@playwright/test": "^1.58.0",
+		"@types/node": "^24.0.0",
+		"@types/pngjs": "^6.0.5",
+		"binaryen": "^132.0.0",
+		"pixelmatch": "^7.2.0",
+		"pngjs": "^7.0.0",
+		"ssim.js": "^3.5.0",
+		"subset-font": "^2.9.0",
+		"typescript": "^7.0.2",
+		"vite": "^8.0.0",
+		"y-websocket": "^2.1.0",
+		"yjs": "^13.6.33"
+	}
+}

package/readme.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <a href="https://github.com/canvist/canvist">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup-dark.svg">
+      <img width="220" src="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup.svg" alt="canvist" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/quick-start/web.md"><strong>Quick start</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/readme.md"><strong>Docs</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/reference/contributing.md"><strong>Contributing</strong></a> ·
+  <a href="https://github.com/canvist/canvist"><strong>canvist</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@canvist/web"><img src="https://img.shields.io/npm/v/%40canvist%2Fweb?color=3B2CF5" alt="npm version" /></a>
+  <a href="https://github.com/canvist/canvist/actions/workflows/web.yml"><img src="https://github.com/canvist/canvist/actions/workflows/web.yml/badge.svg?branch=main" alt="web status" /></a>
+  <a href="https://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-3B2CF5" alt="Unlicense" /></a>
+</p>
+
+# @canvist/web
+
+The canvist editor for the browser. Every pixel of the document is painted on a canvas, but the browser measures the text, so the canvas wraps each line exactly where canvist's server-rendered HTML does and hydrating moves nothing.
+
+```sh
+npm install @canvist/web
+```
+
+```ts
+import { createEditor } from "@canvist/web";
+
+const editor = await createEditor(document.querySelector("#editor")!, {
+	content: { format: "markdown", input: "Hello **world**" },
+});
+
+editor.select({ path: [0], offset: 0 }, { path: [0], offset: 5 });
+editor.commands.toggleItalic();
+editor.toHtml(); // what a server would send: { html, css }
+```
+
+Using React or Vue? See [`@canvist/react`](../canvist-react) and [`@canvist/vue`](../canvist-vue). Rendering on a server? See [`@canvist/headless/ssr`](../../docs/src/quick-start/ssr.md).
+
+## What it does
+
+- **Editing like TipTap:** typed commands and queries, `editable: false` for read-only, a `placeholder`, and menus that follow the selection from `@canvist/web/menus` (`bubbleMenu`, `floatingMenu`).
+- **Collaboration:** `@canvist/web/collab` joins a room on any y-websocket server with `connect(editor, { url, room })`, with per-person undo. Its Yjs build is a separate module, so editors that don't collaborate never download it. `editor.caretRectAt(position)` places other people's carets.
+- **Every extension:** `createEditor` from `@canvist/web/full` takes every extension canvist ships, from tables to math, in a larger module that StarterKit editors never download.
+- **Server rendering:** an element holding canvist's server-rendered HTML hydrates without a layout shift.
+- **Small:** 349.6 KB gzipped for the editor and the StarterKit, with a 350 KB budget CI enforces.
+
+## Types follow what you register
+
+Commands, queries, and document JSON are typed from the extensions you pass, TipTap's StarterKit by default. Plugins add their own API under `editor.plugins`:
+
+```ts
+import { bold, createEditor, heading } from "@canvist/web";
+import { fonts } from "@canvist/web/fonts";
+
+const editor = await createEditor(element, {
+	extensions: [bold, heading],
+	plugins: [fonts()],
+});
+
+editor.commands.setHeading({ level: 2 });
+editor.commands.toggleItalic(); // type error: italic is not registered
+await editor.plugins.fonts.local(); // installed fonts, where the browser allows it
+```
+
+## Built for real typing
+
+- **Fonts:** installed fonts and the page's web fonts work with no setup. `@canvist/web/fonts` loads faces the way `@font-face` does and adds metric-compatible fallbacks, so a font swap barely moves anything. See [Fonts and text rendering](../../docs/src/guides/fonts.md).
+- **Input:** `EditContext` in Chromium and a hidden textarea elsewhere, so input methods, dictation, and autocorrect work as they do in a text field. See [Text input on the web](../../docs/src/guides/web-input.md).
+- **Accessibility:** a visually hidden copy of the document lets screen readers read it, and every change runs an axe audit and screen reader smoke tests.
+- **Latency:** every input event is painted in its own task, and `editor.inputLatency()` reports how long that took.
+
+<details>
+<summary><strong>Development</strong></summary>
+
+```sh
+npm ci
+npm run build:wasm     # builds crates/canvist_web into wasm/
+npx tsc --noEmit
+npm test               # unit tests in Node
+npx playwright test    # parity with server-rendered HTML, editing, and input latency in Chromium, Firefox, and WebKit
+node scripts/parity-report.ts
+```
+
+The parity tests and their thresholds are described in [Rendering parity](../../docs/src/guides/rendering-parity.md).
+
+</details>