@hachej/boring-ui-kit 0.4.2 → 0.4.4

package/README.md

@@ -68,8 +68,50 @@ The default schema includes headings, lists, task lists, quotes, code and text m
 
 `test/packages/ui-markdown-editor.test.mjs`, `test/packages/ui-markdown-navigation.test.mjs` and `test/packages/ui-markdown-mounted.test.mjs` and `test/packages/ui-markdown-proposals.test.mjs` drive the real React/Tiptap renderer, DOM selections and SQLite provider. `npm run test:editor-consumer` requires `npm_config_cache` pointing to a writable cache with the pinned archives; it installs actual package tarballs, checks declarations with `skipLibCheck: false`, drives the controls and bundles for browsers without Pi or server filesystem imports. These checks do not establish browser layout, caret, IME or accessibility qualification. Chromium journeys remain pending.
 
+## Document marks
+
+`@hachej/boring-ui-kit/markdown-quote` exports `captureMarkdownQuote` and
+`markdownQuoteResolution`: pure exact-only anchors over canonical Markdown source.
+`@hachej/boring-ui-kit/mark-store` exports the kit's sidecar store, independently of
+React, Tiptap and Pi execution:
+
+```ts
+import { createMarkStore } from '@hachej/boring-ui-kit/mark-store';
+import { captureMarkdownQuote } from '@hachej/boring-ui-kit/markdown-quote';
+
+const store = await createMarkStore({ client, identity }, locator);
+const capture = captureMarkdownQuote(source, { start: 0, end: 12 });
+if (capture.kind === 'captured') {
+  await store.add({ id: 'mark-1', anchor: capture.anchor, colour: 'accent',
+    note: 'A fictional comment.', author: identity.principalId, time: new Date().toISOString() });
+}
+await store.edit('mark-1', { note: 'Revised fictional comment.' });
+await store.remove('mark-1');
+store.dispose(); // Does not close the borrowed resource client/provider.
+```
+
+Use the same workspace `client` as the document. `identity` is expected receipt
+metadata, never browser authentication. The store reads `<doc>.marks.json` in the
+same view and writes it only through the existing conditional publication path.
+`getSnapshot`/`subscribe` provide immutable marks, dirty/lifecycle and save state;
+mutations return the exact existing `SaveResult`. A stale tab retains its local
+marks and returns conflict; `reload()` explicitly discards them. Lost replies
+require `reconcile()` on the original operation. No auto-merge or blind retry is
+performed. The host owns policy, attribution and recovery after missing receipts.
+The [owner](../../docs/architecture/FEEDBACK.md#markdown-quotes-and-document-marks)
+defines quote/context matching and conservative rich-projection limits.
+
+The existing `MarkdownEditor` accepts `highlights`, `onQuoteSelection` and
+`onHighlightActivate`. Native decorations leave the document buffer clean. Rich
+capture refuses anything outside one proven literal text leaf; source selection
+remains available for syntax, escapes or normalization. The `highlights` registry
+block supplies context actions, comments and an unplaced-mark tray, creating a
+store by default or borrowing the same `MarkStore` interface from an app.
+
 ## Optional native chat
 
+The `/native-chat` entry also owns the neutral `ChatController`/`ChatSnapshot` renderer types. Concrete native controllers retain their full APIs. Optional multi-party data (`ChannelSource`, `createSharedChat`, socket/fake sources and state types) stays exclusively at `/shared-chat`, not the headless root. Its presentation is the optional [`shared-chat` registry item](../../registry/README.md#regular-chat-or-shared-chat); regular `pi-chat` has no imports from it.
+
 `createNativeChatController` from `@hachej/boring-ui-kit/native-chat` borrows an actual native `Conversation` and host-bound `Context`. Supply explicit runtime, scope and principal identity. These labels select a presentation instance and grant no permission. The concrete `controller.conversation` keeps the full native API available. `connect()` owns one native watch, and `dispose()` asynchronously closes that watch without aborting tasks or closing the borrowed Harness.
 
 `setText`, `setAttachments` and `send` retain an immutable selected draft. `beforeSubmit` validates that selection before the first submission and every retry. A refused retry retains the original unknown attempt. Native authorization remains the host boundary's responsibility. A thrown admission stays unknown unless the host can prove it was not admitted. `reconcile()` looks up the original native request. `retrySameRequest()` uses its original request ID and content, including when the user has since edited the composer. `send()` empties the composer at once, like any chat app: the sent text is held by the controller as the pending submission, so text typed before the host confirms is a new draft, never appended to the sent one, and an acknowledgement never clears it. Sending again while a submission is still being confirmed queues the new message in `outbox` and submits it, in order and with its own request ID, once the previous one is admitted. A refused message (validation, or a submission the host proves was not admitted) and any messages waiting behind it go back into the composer, one per line, ahead of the text typed since. A submission whose outcome is unknown stays held for `reconcile()`/`retrySameRequest()`, and further sends are refused until it is resolved. `send(whenBusy, { text, attachments, restore })` sends explicit content without touching the composer (`restore` is what comes back on refusal). This controller retains uncertainty in memory; durable reload of an unacknowledged local draft is not implemented.
@@ -80,6 +122,8 @@ A submit the host refused before admission (status 402 `submission-refused`, for
 
 `@hachej/boring-ui-kit/remote-chat` releases its watch stream while the page is hidden (`document.visibilityState`) and reopens it when the page is visible again, because browsers cap concurrent HTTP/1.1 connections per host and one idle stream per background tab starves every other request. The reopened watch starts with a complete view, so the controller keeps reading `connected`; submissions, answers and running turns are separate requests and are unaffected. The watch also survives the network: a stream that ends without an end frame (a proxy or load balancer closed it), or stays silent for 2.5 of the server's announced heartbeat intervals, is reopened with exponential backoff (`reconnect: { baseDelayMs: 1000, maxDelayMs: 30000 }`, with jitter) until the controller stops it. Meanwhile `remote.link` reports reconnecting and a controller given it (spreading the `RemoteChat` into its options does) reads `connection.kind === 'reconnecting'`; the reopened stream starts with a complete view, so nothing is duplicated. A refusal (4xx) or a final end (`retired`, `stopped`, revoked) ends the watch instead. Pass `pauseWhenHidden: false` to keep the stream open, and always call `close()` on a `RemoteChat` the controller never claimed. Node and workers have no `document` and are unaffected.
 
+`submissionStatus(submission)` reads that exact native handle using the controller's host-bound Context, verifies its conversation and rejects after disposal. It adds no lifecycle or retry: use native `done.answer` to attribute a response, rather than matching text or assuming the next assistant row belongs to a send. The optional [point-and-dictate block](../../docs/guides/agent-target.md) uses it while chat stays closed.
+
 `test/packages/ui-native-chat.test.mjs` uses a real native Harness and a fictional local streaming provider.
 
 ### Native conversation history
@@ -126,7 +170,9 @@ Native document author records are preserved. They do not grant access or select
 
 ## Optional React canvas editor
 
-Import `CanvasEditor` and `CanvasAssetUrls` from `@hachej/boring-ui-kit/canvas-editor`. Install the pinned `tldraw` peer in addition to the canvas controller peers. Supply `controller`, a complete host-owned `assetUrls` map, and optionally `title`, `height`, `className`, `licenseKey` and the native `onMount` callback. Load `tldraw/tldraw.css` when selecting the canvas route; the native JavaScript loads lazily. Asset URLs must cover all pinned fonts, icons, translations and embed icons, so omitted values cannot silently select default CDN assets.
+Import `CanvasEditor` and `CanvasAssetUrls` from `@hachej/boring-ui-kit/canvas-editor`. Install the pinned `tldraw` peer in addition to the canvas controller peers. Supply `controller`, a complete host-owned `assetUrls` map, and optionally `title`, `height`, `className`, `licenseKey` and the native `onMount` callback. The native JavaScript and `tldraw/tldraw.css` load lazily, only when a canvas mounts, so the host does not import the stylesheet itself. Asset URLs must cover all pinned fonts, icons, translations and embed icons, so omitted values cannot silently select default CDN assets.
+
+**Self-hosted assets (host recipe).** Install `@tldraw/assets` at the same pin as `tldraw`, serve its package directory at one origin path (for example `/tldraw-assets`), and build `assetUrls` from `tldraw`'s own defaults with that origin in place of `https://cdn.tldraw.com/<version>`. The working example is [`examples/canvas-assets`](../../examples/canvas-assets): `self-hosted.mjs` is the map, `route.mjs` the route, and `journey.mjs` drives Chromium to prove that the canvas makes no request off the host origin and records no Content-Security-Policy violation (`npm run canvas-assets:journey`). Pass `licenseKey` from the host's own configuration, never a literal in source.
 
 The native toolbar and Save/Check saved version controls use the concrete controller. Lost acknowledgements expose Check save outcome; conflicts preserve local edits and expose explicit discard. Paste/import/upload handlers are disabled until asset/content policy is qualified. Mounting may create native author metadata, but never publishes. Unmount preserves the controller and the native session read-only flag. The host explicitly resets or derives that flag when selecting a later writable session. Use one native editor per store; existing host read-only state remains effective.
 
@@ -350,3 +396,7 @@ publication and retained history without separate file callbacks. Its built-in
 text editor navigation asks before discarding unsaved content. The legacy
 `resources` binding remains available for existing hosts; use one binding at a
 time. History previews never replace the editable document.
+
+## Staged answers in native chat
+
+The [fictional triage-note recipe](../../examples/staged-chat/README.md) composes three sequential native Pi tasks with validation and inline stage entries, two independent chat controllers, error restoration, historical offers, host-owned unread indicators and a 24-row initial display window. It owns the exact API semantics and limitations for `hideLine`, `historicalMessageActions`, `unread`, `replyError`, `displayLimit`, stage-card `status` and `createNativeChatController({ restoreOnError: true })`. These are optional presentation/draft seams, not a kit workflow, retention service or additional transcript store.

package/bin/boring-ui-blocks.mjs

@@ -234,10 +234,39 @@ function parse(command, rest) {
   return flags;
 }
 
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const readJson = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return undefined; } };
+
+/** The version specifiers of an app's package.json (and the root entry of its npm lockfile), as written before the CLI runs. */
+function specifiers(app) {
+  const read = name => { const path = join(app, name), text = existsSync(path) ? readFileSync(path, 'utf8') : undefined; return { path, text, json: text === undefined ? undefined : readJson(path) }; };
+  return [read('package.json'), read('package-lock.json')].map((file, index) => ({ ...file, root: index === 0 ? file.json : file.json?.packages?.[''] }));
+}
+
+/**
+ * The shadcn CLI installs a block's dependencies by name (`npm install <name>`), and npm then saves `^<version>` over an exact pin the app
+ * already holds. The app owns its specifiers (AGENTS.md: pin dependencies), so after the CLI ran every dependency that was there before
+ * gets its old specifier back, in package.json and in the lockfile's root entry; dependencies the CLI added keep what it wrote.
+ */
+function restoreSpecifiers(before, app, log) {
+  const restored = new Set();
+  for (const [index, name] of ['package.json', 'package-lock.json'].entries()) {
+    const old = before[index], now = specifiers(app)[index];
+    if (!old.root || !now.root) continue;
+    for (const field of DEPENDENCY_FIELDS) for (const [dependency, range] of Object.entries(old.root[field] ?? {})) {
+      if (now.root[field]?.[dependency] !== undefined && now.root[field][dependency] !== range) { now.root[field][dependency] = range; restored.add(dependency); now.changed = true; }
+    }
+    if (now.changed) writeFileSync(now.path, `${JSON.stringify(now.json, null, /^\{\n([ \t]+)"/.exec(now.text)?.[1] ?? 2)}${now.text.endsWith('\n') ? '\n' : ''}`);
+  }
+  if (restored.size) log(`kept the version specifiers of ${[...restored].sort().join(', ')} (the CLI had rewritten them)`);
+}
+
 function shadcnAdd(app, args, log) {
   const argv = ['-y', SHADCN, 'add', ...args];
   log(`npx ${argv.join(' ')}`);
+  const before = specifiers(app);
   const result = spawnSync('npx', argv, { cwd: app, stdio: 'inherit', shell: process.platform === 'win32' });
+  restoreSpecifiers(before, app, log);
   return result.status ?? 1;
 }
 

package/dist/canvas-editor-native.d.ts

@@ -1,6 +1,7 @@
+import 'tldraw/tldraw.css';
 import type { CSSProperties } from 'react';
 import type { TLOnMountHandler } from '@tldraw/editor';
-import type { TLDefaultFonts, TLUiAssetUrls } from 'tldraw';
+import type { TLDefaultFonts, TLUiAssetUrls, TldrawProps } from 'tldraw';
 import type { CanvasController } from './canvas.js';
 import type { CanvasMountedTools } from './canvas-mounted.js';
 import type { ViewerComponents } from './viewer-components.js';
@@ -21,5 +22,11 @@ export interface CanvasEditorProps {
     /** Host presentation for the canvas controls; without it the package renders unstyled native buttons. */
     readonly components?: ViewerComponents;
 }
+/** A borrowed native renderer for a host-owned document projection. It never saves the native store. */
+export type CanvasProjectionProps = Pick<TldrawProps, 'store' | 'shapeUtils' | 'hideUi' | 'children' | 'onMount' | 'onUiEvent'> & {
+    readonly assetUrls: CanvasAssetUrls;
+    readonly licenseKey?: string | undefined;
+};
+export declare function NativeCanvasProjection({ assetUrls, licenseKey, onMount, ...props }: CanvasProjectionProps): import("react").JSX.Element;
 export default function NativeCanvas({ controller, assetUrls, title, className, height, licenseKey, onMount, onMountedTools, components }: CanvasEditorProps): import("react").JSX.Element;
 //# sourceMappingURL=canvas-editor-native.d.ts.map

package/dist/canvas-editor-native.js

@@ -1,10 +1,22 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import 'tldraw/tldraw.css';
 import { useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { useEditor, useValue, GeoShapeGeoStyle, LANGUAGES } from '@tldraw/editor';
 import { Tldraw, iconTypes, DEFAULT_EMBED_DEFINITIONS } from 'tldraw';
 import { createMountedCanvasTools } from './canvas-mounted.js';
 import { CanvasProposals } from './canvas-proposals.js';
+export function NativeCanvasProjection({ assetUrls, licenseKey, onMount, ...props }) {
+    const signature = useMemo(() => assetSignature(assetUrls), [assetUrls]);
+    const assets = useMemo(() => ({ fonts: { ...assetUrls.fonts }, icons: { ...assetUrls.icons }, translations: { ...assetUrls.translations }, embedIcons: { ...assetUrls.embedIcons } }), [signature]);
+    return _jsx(Tldraw, { ...props, autoFocus: false, locale: "en", assetUrls: assets, ...(licenseKey === undefined ? {} : { licenseKey }), onMount: editor => {
+            editor.registerExternalAssetHandler('file', null);
+            editor.registerExternalAssetHandler('url', null);
+            for (const type of externalContentTypes)
+                editor.registerExternalContentHandler(type, null);
+            return onMount?.(editor);
+        } });
+}
 const fontKeys = [
     'tldraw_draw', 'tldraw_draw_italic', 'tldraw_draw_bold', 'tldraw_draw_italic_bold',
     'tldraw_sans', 'tldraw_sans_italic', 'tldraw_sans_bold', 'tldraw_sans_italic_bold',
@@ -32,8 +44,6 @@ export default function NativeCanvas({ controller, assetUrls, title = 'Canvas',
     const mounted = useRef(true);
     const revokeTools = useRef(null);
     useLayoutEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
-    const signature = useMemo(() => assetSignature(assetUrls), [assetUrls]);
-    const assets = useMemo(() => ({ fonts: { ...assetUrls.fonts }, icons: { ...assetUrls.icons }, translations: { ...assetUrls.translations }, embedIcons: { ...assetUrls.embedIcons } }), [signature]);
     const outcome = state.save.kind === 'settled' ? state.save.result : undefined;
     const pending = state.save.kind === 'pending';
     const uncertain = outcome?.kind === 'unknown';
@@ -62,10 +72,6 @@ export default function NativeCanvas({ controller, assetUrls, title = 'Canvas',
     const attach = (editor) => {
         if (controller.getSnapshot().readOnly || controller.getSnapshot().lifecycle === 'disposed')
             editor.updateInstanceState({ isReadonly: true });
-        editor.registerExternalAssetHandler('file', null);
-        editor.registerExternalAssetHandler('url', null);
-        for (const type of externalContentTypes)
-            editor.registerExternalContentHandler(type, null);
         const cleanup = onMount?.(editor);
         setNativeEditor(editor);
         return () => { revokeTools.current?.(); setNativeEditor(current => current === editor ? null : current); cleanup?.(); };
@@ -78,7 +84,7 @@ export default function NativeCanvas({ controller, assetUrls, title = 'Canvas',
             }
         }, children: [_jsxs("header", { children: [_jsx("strong", { children: title }), state.readOnly && _jsx("span", { children: "Read only" }), _jsx("span", { role: "status", children: state.lifecycle === 'disposed' ? 'Closed' : pending ? 'Saving' : uncertain ? 'Save unconfirmed' : conflict ? 'Changed elsewhere' : state.dirty ? 'Unsaved changes' : 'Saved' }), _jsx(Control, { type: "button", disabled: unavailable || !state.dirty || pending || uncertain || busy || state.problem !== null, onClick: () => void save(), children: "Save" }), _jsx(Control, { type: "button", disabled: state.lifecycle === 'disposed' || pending || uncertain || busy, onClick: () => void run(controller.actions.refresh), children: "Check saved version" })] }), uncertain && _jsxs("div", { role: "alert", children: ["Save acknowledgement was lost. Your current canvas is retained.", _jsx(Control, { type: "button", disabled: busy, onClick: () => void run(controller.actions.reconcile), children: "Check save outcome" }), _jsx(Control, { type: "button", disabled: busy || state.lifecycle === 'disposed', onClick: () => void run(controller.actions.abandon), children: "Keep draft and refresh" })] }), conflict && _jsxs("div", { role: "alert", children: ["The saved canvas changed. Your local edits have been kept.", _jsx(Control, { type: "button", disabled: pending || uncertain || busy, onClick: () => void run(controller.actions.discardToRemote), children: "Discard local changes and reload" })] }), state.problem && _jsx("p", { role: "alert", children: state.problem }), (outcome?.kind === 'denied' || outcome?.kind === 'unavailable' || outcome?.kind === 'file_too_large') && _jsx("p", { role: "alert", children: outcome.reason }), error && _jsx("p", { role: "alert", children: error }), _jsx(CanvasProposals, { components: components, controller: controller, state: state, editor: nativeEditor, busy: busy, run: run }), state.lifecycle === 'active' && _jsx("div", { "data-boring": "canvas-stage", style: { position: 'relative', height }, onClickCapture: event => { if (event.target instanceof Element && event.target.closest('a'))
                     event.preventDefault(); }, onAuxClickCapture: event => { if (event.target instanceof Element && event.target.closest('a'))
-                    event.preventDefault(); }, children: _jsxs(Tldraw, { store: controller.store, hideUi: true, locale: "en", autoFocus: false, assetUrls: assets, ...(licenseKey === undefined ? {} : { licenseKey }), onMount: attach, children: [_jsx(CanvasTools, { components: components, controller: controller }), _jsx(MountedCommands, { controller: controller, revokeTools: revokeTools, ...(onMountedTools ? { onMountedTools } : {}) })] }) })] });
+                    event.preventDefault(); }, children: _jsxs(NativeCanvasProjection, { store: controller.store, hideUi: true, assetUrls: assetUrls, licenseKey: licenseKey, onMount: attach, children: [_jsx(CanvasTools, { components: components, controller: controller }), _jsx(MountedCommands, { controller: controller, revokeTools: revokeTools, ...(onMountedTools ? { onMountedTools } : {}) })] }) })] });
 }
 const externalContentTypes = ['text', 'files', 'file-replace', 'embed', 'svg-text', 'url', 'tldraw', 'excalidraw'];
 const choices = [

package/dist/canvas-editor.d.ts

@@ -1,6 +1,8 @@
 export type { CanvasMountedSubject, CanvasMountedInspection, CanvasMountedTools } from './canvas-mounted.js';
-import type { CanvasEditorProps } from './canvas-editor-native.js';
-export type { CanvasAssetUrls, CanvasEditorProps, CanvasFontUrls } from './canvas-editor-native.js';
+import type { CanvasEditorProps, CanvasProjectionProps } from './canvas-editor-native.js';
+export type { CanvasAssetUrls, CanvasEditorProps, CanvasFontUrls, CanvasProjectionProps } from './canvas-editor-native.js';
+/** Native tldraw presentation for a host format such as board@1. No document controller or native persistence. */
+export declare function CanvasProjection(props: CanvasProjectionProps): import("react").JSX.Element;
 /** Borrows one controller/store. The host supplies native CSS, fonts and any production license. */
 export declare function CanvasEditor(props: CanvasEditorProps): import("react").JSX.Element;
 //# sourceMappingURL=canvas-editor.d.ts.map

package/dist/canvas-editor.js

@@ -3,6 +3,11 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { lazy, Suspense, useState, useSyncExternalStore } from 'react';
 import { TextDraftControls } from './text-draft-controls.js';
 const NativeCanvas = lazy(() => import('./canvas-editor-native.js'));
+const NativeProjection = lazy(() => import('./canvas-editor-native.js').then(module => ({ default: module.NativeCanvasProjection })));
+/** Native tldraw presentation for a host format such as board@1. No document controller or native persistence. */
+export function CanvasProjection(props) {
+    return _jsx(Suspense, { fallback: _jsx("p", { role: "status", children: "Loading canvas" }), children: _jsx(NativeProjection, { ...props }) });
+}
 /** Borrows one controller/store. The host supplies native CSS, fonts and any production license. */
 export function CanvasEditor(props) {
     const state = useSyncExternalStore(props.controller.subscribe, props.controller.getSnapshot, props.controller.getSnapshot);

package/dist/chat-outbox.d.ts

@@ -0,0 +1,18 @@
+/** Unanswered transport calls retain their identity and payload across reconnects. The host must deduplicate mutating calls. */
+export declare function createChatOutbox<Input, Output>(): {
+    enqueue: (id: string, input: Input) => Promise<Output>;
+    get: (id: string) => {
+        readonly input: Input;
+        readonly resolve: (output: Output) => void;
+        readonly reject: (error: unknown) => void;
+    } | undefined;
+    values: () => {
+        readonly input: Input;
+        readonly resolve: (output: Output) => void;
+        readonly reject: (error: unknown) => void;
+    }[];
+    resolve: (id: string, output: Output) => void;
+    reject: (id: string, error: unknown) => void;
+    clear: () => void;
+};
+//# sourceMappingURL=chat-outbox.d.ts.map

package/dist/chat-outbox.js

@@ -0,0 +1,12 @@
+/** Unanswered transport calls retain their identity and payload across reconnects. The host must deduplicate mutating calls. */
+export function createChatOutbox() {
+    const pending = new Map();
+    return {
+        enqueue: (id, input) => new Promise((resolve, reject) => { pending.set(id, { input, resolve, reject }); }),
+        get: (id) => pending.get(id),
+        values: () => [...pending.values()],
+        resolve: (id, output) => { const call = pending.get(id); pending.delete(id); call?.resolve(output); },
+        reject: (id, error) => { const call = pending.get(id); pending.delete(id); call?.reject(error); },
+        clear: () => pending.clear(),
+    };
+}

package/dist/file-tree-view.d.ts

@@ -47,6 +47,9 @@ export declare const defaultFileTreeLabels: {
     checkUpload: string;
     uploadStatusUnavailable: string;
     uploadFailed: (name: string) => string;
+    tooLarge: string;
+    uploadProgress: (name: string) => string;
+    cancelUpload: (name: string) => string;
 };
 export type FileTreeLabels = typeof defaultFileTreeLabels;
 /** The tree's words in French (`locale="fr"`). */
@@ -100,7 +103,26 @@ export interface FileTreeComponents {
         readonly className?: string;
         readonly children?: ReactNode;
     }) => ReactNode;
+    /** The host's shadcn `Progress` (`value` 0–100, `null` while the total is unknown), for uploads through `uploadBlob`. */
+    readonly Progress?: (props: {
+        readonly value: number | null;
+        readonly 'aria-label': string;
+    }) => ReactNode;
+}
+/** How far an upload through `uploadBlob` is. */
+export interface UploadProgress {
+    readonly loaded: number;
+    readonly total: number;
 }
+/**
+ * The host's upload of a large file: it stores the bytes and writes the workspace's pointer file itself, then resolves (with the
+ * pointer it wrote). The tree never writes anything for it; it reloads its listing. `signal` aborts it (the row's cancel button);
+ * a refusal rejects with `{ error: { code, message } }`, whose `message` the tree shows.
+ */
+export type UploadBlob = (file: globalThis.File, options: {
+    readonly signal: AbortSignal;
+    readonly onProgress: (progress: UploadProgress) => void;
+}) => Promise<unknown>;
 export interface FileTreeProps {
     readonly components: FileTreeComponents;
     readonly revisionProvider: RevisionProvider;
@@ -128,6 +150,12 @@ export interface FileTreeProps {
     readonly refreshKey?: unknown;
     /** Reload the open history panel whenever this value changes (for example the seq of the workspace's latest change event). */
     readonly historyKey?: unknown;
+    /** The inline cap in bytes: a larger upload goes to `uploadBlob`, or is refused with `tooLarge` without it. No cap when omitted. */
+    readonly maxBytes?: number;
+    /** The refusal shown for a file above `maxBytes` when there is no `uploadBlob`. */
+    readonly tooLarge?: string;
+    /** The host's large-file upload (see `UploadBlob`), used above `maxBytes`. */
+    readonly uploadBlob?: UploadBlob;
 }
 /** One borrowed binding powers browsing, search, upload and history. Historical previews never replace an editor's draft. */
 export declare function FileTree(props: FileTreeProps): import("react").JSX.Element;
@@ -135,5 +163,5 @@ export interface FileTreeViewProps extends Omit<FileTreeProps, 'revisionProvider
     readonly controller: FileTreeController;
 }
 /** Renders a borrowed controller, for a workspace whose chat and tree share upload state. */
-export declare function FileTreeView({ components, controller, onOpen, selectedPath, className, uploadDirectory, locale, labels: given, upload, history, refresh, variant, title, onClose, refreshKey, historyKey }: FileTreeViewProps): import("react").JSX.Element;
+export declare function FileTreeView({ components, controller, onOpen, selectedPath, className, uploadDirectory, locale, labels: given, upload, history, refresh, variant, title, onClose, refreshKey, historyKey, maxBytes, tooLarge, uploadBlob }: FileTreeViewProps): import("react").JSX.Element;
 //# sourceMappingURL=file-tree-view.d.ts.map

package/dist/file-tree-view.js

@@ -48,6 +48,9 @@ export const defaultFileTreeLabels = {
     checkUpload: 'Check upload status',
     uploadStatusUnavailable: 'Upload status unavailable',
     uploadFailed: (name) => `${name}: upload failed`,
+    tooLarge: 'The file is too large to upload.',
+    uploadProgress: (name) => `Uploading ${name}`,
+    cancelUpload: (name) => `Cancel uploading ${name}`,
 };
 /** The tree's words in French (`locale="fr"`). */
 export const frenchFileTreeLabels = {
@@ -94,6 +97,9 @@ export const frenchFileTreeLabels = {
     checkUpload: 'Vérifier l’import',
     uploadStatusUnavailable: 'État de l’import indisponible',
     uploadFailed: name => `${name} : échec de l’import`,
+    tooLarge: 'Le fichier est trop volumineux pour être importé.',
+    uploadProgress: name => `Import de ${name}`,
+    cancelUpload: name => `Annuler l’import de ${name}`,
 };
 const LOCALES = { en: defaultFileTreeLabels, fr: frenchFileTreeLabels };
 function fileKind(path, labels) {
@@ -129,8 +135,8 @@ function BoundFileTree(props) {
     return owned?.provider === props.revisionProvider ? _jsx(FileTreeView, { ...props, controller: owned.controller }) : _jsx("p", { role: "status", children: props.labels?.loading ?? LOCALES[props.locale ?? 'en'].loading });
 }
 /** Renders a borrowed controller, for a workspace whose chat and tree share upload state. */
-export function FileTreeView({ components, controller, onOpen, selectedPath, className, uploadDirectory = 'uploads', locale = 'en', labels: given, upload = true, history = true, refresh = true, variant = 'list', title, onClose, refreshKey, historyKey }) {
-    const { Button, Actions, Menu: SidebarMenu, MenuItem: SidebarMenuItem, MenuSub: SidebarMenuSub, Input, Collapsible: CollapsibleRoot, CollapsibleTrigger, CollapsibleContent, Empty } = components;
+export function FileTreeView({ components, controller, onOpen, selectedPath, className, uploadDirectory = 'uploads', locale = 'en', labels: given, upload = true, history = true, refresh = true, variant = 'list', title, onClose, refreshKey, historyKey, maxBytes, tooLarge, uploadBlob }) {
+    const { Button, Actions, Menu: SidebarMenu, MenuItem: SidebarMenuItem, MenuSub: SidebarMenuSub, Input, Collapsible: CollapsibleRoot, CollapsibleTrigger, CollapsibleContent, Empty, Progress } = components;
     const list = variant === 'list';
     const labels = { ...LOCALES[locale], ...given };
     const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
@@ -154,9 +160,49 @@ export function FileTreeView({ components, controller, onOpen, selectedPath, cla
     const [uploadError, setUploadError] = useState('');
     const [historyPath, setHistoryPath] = useState();
     const [localFailures, setLocalFailures] = useState(new Map());
+    // Uploads through the host's `uploadBlob`, by a key of their own: the name, the progress and the abort behind the cancel button.
+    const [blobUploads, setBlobUploads] = useState(new Map());
+    const blobAborts = useRef(new Set());
+    useEffect(() => () => { for (const abort of blobAborts.current)
+        abort.abort(); }, []);
+    const uploadLarge = async (file, send) => {
+        const key = `${file.name}:${Math.random()}`, abort = new AbortController();
+        const set = (progress) => setBlobUploads(previous => new Map(previous).set(key, { name: file.name, progress, abort }));
+        blobAborts.current.add(abort);
+        set(undefined);
+        try {
+            await send(file, { signal: abort.signal, onProgress: progress => { if (!abort.signal.aborted)
+                    set(progress); } });
+            if (abort.signal.aborted)
+                return;
+            // The host wrote the pointer file: the listing is read again, never written.
+            const { query, expanded } = controller.getSnapshot();
+            if (query)
+                void controller.search(query);
+            else
+                for (const directory of ['', ...expanded])
+                    void controller.refresh(directory);
+        }
+        catch (error) {
+            if (!abort.signal.aborted)
+                setUploadError(refusalOf(error) ?? labels.uploadFailed(file.name));
+        }
+        finally {
+            blobAborts.current.delete(abort);
+            setBlobUploads(previous => { const next = new Map(previous); next.delete(key); return next; });
+        }
+    };
     const uploadFiles = async (files) => {
+        setUploadError('');
         for (const file of files) {
             const path = uploadDirectory ? `${uploadDirectory}/${file.name}` : file.name;
+            if (maxBytes !== undefined && file.size > maxBytes) {
+                if (uploadBlob)
+                    void uploadLarge(file, uploadBlob);
+                else
+                    setLocalFailures(previous => new Map(previous).set(path, { file, reason: tooLarge ?? labels.tooLarge }));
+                continue;
+            }
             setLocalFailures(previous => { const next = new Map(previous); next.delete(path); return next; });
             try {
                 await controller.upload({ path, bytes: new Uint8Array(await file.arrayBuffer()), mediaType: file.type || 'application/octet-stream' });
@@ -269,15 +315,17 @@ export function FileTreeView({ components, controller, onOpen, selectedPath, cla
         const folder = entry.kind === 'directory';
         const temporary = temporaryPaths.has(entry.path);
         const status = uploadRows.get(entry.path);
-        const name = entry.path.split('/').at(-1);
+        // A pointer file shows the file it stands for: its name, kind and size (`withBlobPointers` resolved it where the listing was read).
+        const blob = entry.blob && 'url' in entry.blob ? entry.blob : undefined;
+        const name = blob?.name ?? entry.path.split('/').at(-1);
         const parent = (state.query || temporary) && entry.path.includes('/') ? entry.path.slice(0, entry.path.lastIndexOf('/')) : '';
         const children = folder ? state.directories.get(entry.path) : undefined;
         const childCount = children?.kind === 'ready' && children.cursor === undefined ? labels.childCount(children.entries.length) : undefined;
-        const kind = folder ? { icon: Folder, label: labels.folder } : fileKind(entry.path, labels);
+        const kind = folder ? { icon: Folder, label: labels.folder } : fileKind(blob?.name ?? entry.path, labels);
         const Icon = kind.icon;
         const button = _jsxs(Button, { type: "button", variant: selectedPath === entry.path ? 'secondary' : 'ghost', "data-active": selectedPath === entry.path, tabIndex: -1, title: entry.path, disabled: temporary, className: "file-tree-row-button", onClick: () => { focus(entry.path); if (!folder)
-                onOpen?.(entry.path); }, children: [folder ? _jsx(ChevronRight, { "aria-hidden": "true" }) : list && _jsx("span", { className: "file-tree-chevron-space", "aria-hidden": "true" }), _jsx(Icon, { "aria-hidden": "true" }), _jsxs("span", { className: "file-tree-copy", children: [_jsx("span", { className: "file-tree-name", children: name }), list ? folder ? childCount !== undefined && _jsx("span", { "data-file-meta": true, children: childCount }) : _jsxs("span", { "data-file-meta": true, children: [kind.label, " \u00B7 ", fileSize(entry.size, locale), parent && ` · ${parent}`] }) : parent && _jsx("span", { className: "file-tree-parent", "data-file-meta": true, children: parent })] })] });
-        const item = _jsxs(SidebarMenuItem, { role: "treeitem", "data-path": entry.path, "data-upload-state": status?.kind, "aria-busy": status?.kind === 'pending' || undefined, "aria-level": level, "aria-selected": selectedPath === entry.path, "aria-expanded": folder ? state.expanded.has(entry.path) : undefined, tabIndex: focusPath === entry.path ? 0 : -1, onFocus: event => { if (event.target === event.currentTarget)
+                onOpen?.(entry.path); }, children: [folder ? _jsx(ChevronRight, { "aria-hidden": "true" }) : list && _jsx("span", { className: "file-tree-chevron-space", "aria-hidden": "true" }), _jsx(Icon, { "aria-hidden": "true" }), _jsxs("span", { className: "file-tree-copy", children: [_jsx("span", { className: "file-tree-name", children: name }), list ? folder ? childCount !== undefined && _jsx("span", { "data-file-meta": true, children: childCount }) : _jsxs("span", { "data-file-meta": true, children: [kind.label, " \u00B7 ", fileSize(blob?.size ?? entry.size, locale), parent && ` · ${parent}`] }) : parent && _jsx("span", { className: "file-tree-parent", "data-file-meta": true, children: parent })] })] });
+        const item = _jsxs(SidebarMenuItem, { role: "treeitem", "data-path": entry.path, "data-blob-type": blob?.type, "data-upload-state": status?.kind, "aria-busy": status?.kind === 'pending' || undefined, "aria-level": level, "aria-selected": selectedPath === entry.path, "aria-expanded": folder ? state.expanded.has(entry.path) : undefined, tabIndex: focusPath === entry.path ? 0 : -1, onFocus: event => { if (event.target === event.currentTarget)
                 setFocused(entry.path); }, onKeyDown: event => { if (event.target === event.currentTarget)
                 keyboard(event, entry); }, className: "file-tree-item", children: [_jsxs("div", { className: "flex items-center gap-1", children: [folder ? _jsx(CollapsibleTrigger, { render: button }) : button, status?.kind === 'pending' && _jsx(LoaderCircle, { "data-upload-spinner": true, className: "animate-spin motion-reduce:animate-none", "aria-hidden": "true" }), status?.kind === 'failed' && _jsx(Button, { type: "button", variant: "ghost", "data-upload-retry": true, "aria-label": status.retryLabel, onClick: status.retry, children: status.retryLabel }), !folder && !temporary && !status && _jsx(FileActions, { Actions: Actions, controller: controller, entry: entry, labels: labels, onOpen: onOpen ? () => onOpen(entry.path) : undefined, onHistory: history ? () => setHistoryPath(entry.path) : undefined, onError: setUploadError })] }), status?.kind === 'failed' && _jsx("span", { "data-upload-error": true, children: status.reason }), folder && !state.query && _jsx(CollapsibleContent, { render: _jsx(SidebarMenuSub, { role: "group" }), children: renderEntries(entry.path, level + 1) })] }, entry.path);
         return folder ? _jsx(CollapsibleRoot, { render: item, open: state.expanded.has(entry.path), onOpenChange: () => { void controller.toggle(entry.path); } }, entry.path) : item;
@@ -304,13 +352,32 @@ export function FileTreeView({ components, controller, onOpen, selectedPath, cla
                     const files = Array.from(event.currentTarget.files ?? []);
                     event.currentTarget.value = '';
                     void uploadFiles(files);
-                } }), dropping && _jsx("div", { className: "file-tree-drop", role: "status", children: _jsx(Empty, { icon: _jsx(Upload, { "aria-hidden": "true" }), title: labels.dropFiles }) }), uploadError && _jsx("p", { role: "alert", children: uploadError }), _jsxs(SidebarMenu, { ref: tree, role: "tree", "aria-label": labels.tree, className: "file-tree-menu", children: [state.query ? _jsxs(_Fragment, { children: [state.search.entries.map(entry => renderEntry(entry, 1)), listingStatus(state.search, '', true)] }) : renderEntries('', 1), temporaryEntries.map(entry => renderEntry(entry, 1))] }), _jsxs("ul", { "aria-label": labels.uploads, "aria-live": "polite", "aria-relevant": "additions text", className: "file-tree-announcements", children: [state.uploads.map(upload => _jsxs("li", { "data-operation": upload.operationId, children: [upload.path, ": ", upload.state.kind === 'pending' ? labels.uploading : upload.state.result.kind === 'committed' ? labels.saved : upload.state.result.kind === 'partial' ? labels.unconfirmed : upload.state.result.reason] }, upload.operationId)), [...localFailures].map(([path, failure]) => _jsxs("li", { children: [path, ": ", failure.reason] }, path))] }), history && historyPath !== undefined && _jsx(FileHistory, { components: components, locale: locale, controller: controller, path: historyPath, labels: labels, reload: historyKey, onClose: () => setHistoryPath(undefined) }, historyPath)] });
+                } }), dropping && _jsx("div", { className: "file-tree-drop", role: "status", children: _jsx(Empty, { icon: _jsx(Upload, { "aria-hidden": "true" }), title: labels.dropFiles }) }), uploadError && _jsx("p", { role: "alert", children: uploadError }), blobUploads.size > 0 && _jsx("ul", { "aria-label": labels.uploads, className: "file-tree-blob-uploads", children: [...blobUploads].map(([key, item]) => {
+                    const percent = item.progress && item.progress.total > 0 ? Math.min(100, Math.round(item.progress.loaded / item.progress.total * 100)) : null;
+                    return _jsxs("li", { "data-blob-upload": item.name, "data-progress": percent ?? undefined, className: "flex items-center gap-2", children: [_jsx("span", { className: "min-w-0 flex-1 truncate", children: item.name }), Progress ? _jsx("span", { className: "w-24 shrink-0", children: _jsx(Progress, { value: percent, "aria-label": labels.uploadProgress(item.name) }) }) : _jsx("span", { role: "status", children: percent === null ? labels.uploading : `${percent}%` }), _jsx(Button, { type: "button", variant: "ghost", size: "icon", "data-blob-upload-cancel": true, "aria-label": labels.cancelUpload(item.name), title: labels.cancelUpload(item.name), onClick: () => item.abort.abort(), children: _jsx(X, { "aria-hidden": "true" }) })] }, key);
+                }) }), _jsxs(SidebarMenu, { ref: tree, role: "tree", "aria-label": labels.tree, className: "file-tree-menu", children: [state.query ? _jsxs(_Fragment, { children: [state.search.entries.map(entry => renderEntry(entry, 1)), listingStatus(state.search, '', true)] }) : renderEntries('', 1), temporaryEntries.map(entry => renderEntry(entry, 1))] }), _jsxs("ul", { "aria-label": labels.uploads, "aria-live": "polite", "aria-relevant": "additions text", className: "file-tree-announcements", children: [state.uploads.map(upload => _jsxs("li", { "data-operation": upload.operationId, children: [upload.path, ": ", upload.state.kind === 'pending' ? labels.uploading : upload.state.result.kind === 'committed' ? labels.saved : upload.state.result.kind === 'partial' ? labels.unconfirmed : upload.state.result.reason] }, upload.operationId)), [...localFailures].map(([path, failure]) => _jsxs("li", { children: [path, ": ", failure.reason] }, path))] }), history && historyPath !== undefined && _jsx(FileHistory, { components: components, locale: locale, controller: controller, path: historyPath, labels: labels, reload: historyKey, onClose: () => setHistoryPath(undefined) }, historyPath)] });
+}
+/** The message of a host refusal `{ error: { code, message } }` (or an Error's), if any. */
+function refusalOf(error) {
+    const message = typeof error === 'object' && error !== null && 'error' in error && typeof error.error === 'object' && error.error !== null && 'message' in error.error ? error.error.message : error instanceof Error ? error.message : undefined;
+    return typeof message === 'string' && message ? message : undefined;
 }
 function FileActions({ Actions, controller, entry, labels, onOpen, onHistory, onError }) {
     const lifetime = useRef(undefined);
     useEffect(() => () => lifetime.current?.abort(), []);
+    const blob = entry.blob && 'url' in entry.blob ? entry.blob : undefined;
     const download = async () => {
         onError('');
+        if (blob) {
+            // The host serves a blob's bytes at its URL, with its own disposition; nothing is read into the page.
+            const link = document.createElement('a');
+            link.href = blob.url;
+            link.download = blob.name;
+            document.body.append(link);
+            link.click();
+            link.remove();
+            return;
+        }
         lifetime.current?.abort();
         const abort = new AbortController();
         lifetime.current = abort;

package/dist/mark-store.d.ts

@@ -0,0 +1,38 @@
+import type { ResourceAccess, ResourceClient, ResourceLocator } from '@hachej/boring-files';
+import type { TextBufferState } from './text-buffer-state.js';
+import type { SaveResult } from './resources.js';
+import { type MarkdownQuoteAnchor } from './markdown-quote.js';
+export type MarkColour = 'accent' | 'primary' | 'muted';
+export interface DocumentMark {
+    readonly id: string;
+    readonly anchor: MarkdownQuoteAnchor;
+    readonly colour: MarkColour;
+    readonly note: string;
+    readonly author: string;
+    readonly time: string;
+}
+export interface MarkStoreSnapshot {
+    readonly marks: readonly DocumentMark[];
+    readonly save: TextBufferState['save'];
+    readonly dirty: boolean;
+    readonly lifecycle: 'active' | 'disposed';
+}
+export interface MarkStore {
+    readonly getSnapshot: () => MarkStoreSnapshot;
+    readonly subscribe: (notify: () => void) => () => void;
+    readonly add: (mark: DocumentMark) => Promise<SaveResult>;
+    readonly edit: (id: string, change: Partial<Pick<DocumentMark, 'anchor' | 'colour' | 'note'>>) => Promise<SaveResult>;
+    readonly remove: (id: string) => Promise<SaveResult>;
+    readonly reconcile: () => Promise<SaveResult>;
+    /** Explicitly discard a refused local change and load current marks. Unknown writes must be reconciled first. */
+    readonly reload: () => Promise<void>;
+    readonly dispose: () => void;
+}
+export interface MarkResource {
+    readonly client: ResourceClient;
+    /** Expected receipt identity, never authentication authority. */
+    readonly identity: Pick<ResourceAccess, 'scopeId' | 'principalId' | 'initiatorId'>;
+}
+/** Host data/presentation concern; uses the workspace's existing resource publication seam, not Pi execution state. */
+export declare function createMarkStore(resource: MarkResource, locator: ResourceLocator): Promise<MarkStore>;
+//# sourceMappingURL=mark-store.d.ts.map

package/dist/mark-store.js

@@ -0,0 +1,84 @@
+import { randomUUID } from '@hachej/boring-files/platform';
+import { createTextBuffer, freeze } from './text-buffer.js';
+import { markdownQuoteResolution } from './markdown-quote.js';
+function mark(value) {
+    if (!value || typeof value !== 'object')
+        throw new TypeError('Invalid document mark');
+    const m = value;
+    if (typeof m['id'] !== 'string' || !m['id'] || !['accent', 'primary', 'muted'].includes(String(m['colour']))
+        || typeof m['note'] !== 'string' || typeof m['author'] !== 'string' || !m['author'] || typeof m['time'] !== 'string' || !Number.isFinite(Date.parse(m['time'])))
+        throw new TypeError('Invalid document mark');
+    return { id: m['id'], anchor: markdownQuoteResolution.schema.parse(m['anchor']), colour: m['colour'], note: m['note'], author: m['author'], time: m['time'] };
+}
+function decode(text) {
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object' || !('format' in data) || data.format !== 'document.marks@1' || !('marks' in data) || !Array.isArray(data.marks))
+        throw new TypeError('Unsupported marks file');
+    const marks = data.marks.map(mark);
+    if (new Set(marks.map(m => m.id)).size !== marks.length)
+        throw new TypeError('Duplicate mark id');
+    return marks;
+}
+const encode = (marks) => JSON.stringify({ format: 'document.marks@1', marks }, null, 2) + '\n';
+const readText = (snapshot) => {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(snapshot.bytes);
+    decode(text);
+    return text;
+};
+/** Host data/presentation concern; uses the workspace's existing resource publication seam, not Pi execution state. */
+export async function createMarkStore(resource, locator) {
+    const client = resource.client;
+    const identity = structuredClone(resource.identity);
+    const target = { resource: { ...locator.resource, path: `${locator.resource.path}.marks.json` }, view: structuredClone(locator.view) };
+    const read = await client.read({ target, revision: { kind: 'latest' } });
+    if (read.kind !== 'available' && read.kind !== 'missing')
+        throw new Error('Marks are unavailable');
+    if (read.kind === 'available' && (read.snapshot.ref.resource.providerId !== target.resource.providerId || read.snapshot.ref.resource.path !== target.resource.path
+        || JSON.stringify(read.snapshot.ref.view) !== JSON.stringify(target.view)))
+        throw new Error('Marks read returned another resource');
+    const buffer = createTextBuffer({ client, identity, instanceId: randomUUID(), epoch: randomUUID(),
+        source: read.kind === 'available' ? { kind: 'saved', snapshot: read.snapshot } : { kind: 'new', target, text: encode([]) },
+        mediaType: 'application/json', emptyText: encode([]), readText });
+    let snapshot;
+    const update = () => { const s = buffer.getSnapshot(); snapshot = freeze({ marks: decode(s.text), save: s.save, dirty: s.dirty, lifecycle: s.lifecycle }); };
+    update();
+    const listeners = new Set();
+    const unsubscribe = buffer.subscribe(() => { update(); for (const notify of [...listeners])
+        notify(); });
+    let preparing = false;
+    const mutate = (transform) => {
+        const s = buffer.getSnapshot();
+        if (s.lifecycle === 'disposed')
+            return Promise.resolve({ kind: 'unavailable', reason: 'Marks store is disposed' });
+        if (preparing || s.save.kind === 'pending' || s.save.kind === 'settled' && s.save.result.kind !== 'saved')
+            return Promise.resolve({ kind: 'unavailable', reason: 'Reconcile or reload marks before another change' });
+        preparing = true;
+        try {
+            buffer.edit(encode(transform(snapshot.marks)));
+            return buffer.flush(buffer.selection());
+        }
+        finally {
+            preparing = false;
+        }
+    };
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: notify => { listeners.add(notify); return () => { listeners.delete(notify); }; },
+        add: input => { const captured = mark(input); return mutate(marks => { if (marks.some(m => m.id === captured.id))
+            throw new TypeError('Duplicate mark id'); return [...marks, captured]; }); },
+        edit: (id, change) => { const captured = structuredClone(change); return mutate(marks => { if (!marks.some(m => m.id === id))
+            throw new TypeError('Unknown mark id'); return marks.map(m => m.id === id ? mark({ ...m, ...captured }) : m); }); },
+        remove: id => mutate(marks => { if (!marks.some(m => m.id === id))
+            throw new TypeError('Unknown mark id'); return marks.filter(m => m.id !== id); }),
+        reconcile: buffer.reconcile,
+        reload: async () => {
+            const s = buffer.getSnapshot();
+            if (s.save.kind === 'pending' || s.save.kind === 'settled' && s.save.result.kind === 'unknown')
+                throw new Error('Reconcile the unconfirmed save first');
+            const result = await buffer.refresh(true);
+            if (result.kind !== 'available' && result.kind !== 'missing')
+                throw new Error('Marks reload failed');
+        },
+        dispose: () => { buffer.dispose(); unsubscribe(); listeners.clear(); },
+    };
+}

package/dist/markdown-editor.d.ts

@@ -1,3 +1,6 @@
+import { type MarkdownDecoration, type MarkdownQuoteCapture } from './markdown-highlight-layer.js';
+export type { MarkdownDecoration, MarkdownQuoteCapture } from './markdown-highlight-layer.js';
+export { markdownMarkerBackground } from './markdown-highlight-layer.js';
 import type { ViewerComponents } from './viewer-components.js';
 export type { ViewerComponents } from './viewer-components.js';
 import type { MarkdownAutosave, MarkdownFlush } from './markdown-autosave.js';
@@ -12,6 +15,9 @@ export type { MarkdownRichSafety } from './markdown-safety.js';
 export type { MarkdownImageResolver } from './markdown-extensions.js';
 export type { MarkdownMountedTools, MarkdownMountedSubject, MarkdownMountedSelection, MarkdownMountedInspection } from './markdown-mounted.js';
 export interface MarkdownEditorProps {
+    readonly highlights?: readonly MarkdownDecoration[];
+    readonly onQuoteSelection?: (capture: MarkdownQuoteCapture) => void;
+    readonly onHighlightActivate?: (id: string) => void;
     /** Installed recipes supply the host's shadcn controls. Omit only for unstyled native HTML rendering. */
     readonly components?: ViewerComponents;
     readonly controller: MarkdownController;