@hachej/boring-ui-kit 0.4.3 → 0.4.5

package/README.md

@@ -68,8 +68,58 @@ 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.
 
+## Optional microphone capture
+
+`createVoiceCapture` from `@hachej/boring-ui-kit/voice-capture` records browser audio without React, files or Pi. Call `start()` from a person's gesture. It feature-detects microphone access and returns a recording or a typed refusal. `stop()` returns the Blob, recorded MIME type, page-clock sample times and `truncated`; `cancel()` discards audio and releases only this capture's microphone tracks, including a permission request that finishes late.
+
+`maxMs` caps capture at five minutes by default. Reaching the cap stops the microphone; callers still choose when to consume the recording through `stop()`. Transcription and persistence remain host capabilities. The existing `@hachej/boring-feedback/page` capture API re-exports this implementation unchanged. The headless root imports neither entry.
+
+The [registry voice-message guide](../../registry/README.md#voice-messages-in-pi-chat) describes PiChat's optional hold-to-send composition. Public capture behavior runs in `test/packages/ui.test.mjs`, compatibility in `test/packages/feedback-voice.test.mjs`, and dependency-free installation in `test/scaffold/isolated-ui.test.mjs`.
+
+## 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 +130,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
@@ -352,3 +404,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/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/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;

package/dist/markdown-editor.js

@@ -1,5 +1,8 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { captureMarkdownQuote } from './markdown-quote.js';
+import { captureRichMarkdownQuote, installMarkdownHighlights } from './markdown-highlight-layer.js';
+export { markdownMarkerBackground } from './markdown-highlight-layer.js';
 import { TextDraftControls } from './text-draft-controls.js';
 import { useMarkdownAutosave } from './markdown-autosave.js';
 import { Fragment, useDeferredValue, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
@@ -61,7 +64,7 @@ function useKeyboardInset(active) {
     }, [active]);
     return inset;
 }
-function MarkdownEditorSession({ components, controller, title = 'Document', initialMode = 'rich', placeholder = 'Start writing', className, onMountedTools, header = true, showOutline = header, mode: controlledMode, onModeChange, onRichSafety, resolveImage, formattingToolbar = 'pinned', autosave = true, onAutosaveChange, onSaveResult, activeController: active }) {
+function MarkdownEditorSession({ highlights, onQuoteSelection, onHighlightActivate, components, controller, title = 'Document', initialMode = 'rich', placeholder = 'Start writing', className, onMountedTools, header = true, showOutline = header, mode: controlledMode, onModeChange, onRichSafety, resolveImage, formattingToolbar = 'pinned', autosave = true, onAutosaveChange, onSaveResult, activeController: active }) {
     const Control = components?.button ?? 'button';
     const Bubble = components?.bubble ?? Fragment;
     const Source = components?.textarea ?? 'textarea';
@@ -150,6 +153,18 @@ function MarkdownEditorSession({ components, controller, title = 'Document', ini
             quote: current.isActive('blockquote'), codeBlock: current.isActive('codeBlock'), link: current.isActive('link'), table: current.isActive('table'),
             href: current.isActive('link') ? String(current.getAttributes('link')['href'] ?? '') : '',
         } : null });
+    useEffect(() => {
+        if (!editor || editor.isDestroyed || mode !== 'rich' || !highlights)
+            return;
+        return installMarkdownHighlights(editor, state.text, highlights, onHighlightActivate);
+    }, [editor, state.text, mode, highlights, onHighlightActivate]);
+    useEffect(() => {
+        if (!editor || editor.isDestroyed || mode !== 'rich' || !onQuoteSelection)
+            return;
+        const selected = () => onQuoteSelection(captureRichMarkdownQuote(editor, controller.getSnapshot().text));
+        editor.on('selectionUpdate', selected);
+        return () => { editor.off('selectionUpdate', selected); };
+    }, [editor, controller, mode, onQuoteSelection]);
     const outline = useEditorState({ editor, selector: ({ editor: current }) => {
             if (!current)
                 return null;
@@ -285,7 +300,7 @@ function MarkdownEditorSession({ components, controller, title = 'Document', ini
                                     }).catch(() => { if (active.current === controller)
                                         setError('The heading could not be selected'); });
                             }, children: heading.text || 'Untitled heading' }) }, heading.position)) }) }), uncertain && _jsxs("div", { role: "alert", className: "boring-markdown-alert", children: ["Save acknowledgement was lost. Keep editing while its outcome is checked.", _jsx(Control, { type: "button", onClick: () => run(controller.actions.reconcile), children: "Check save outcome" }), _jsx(Control, { type: "button", onClick: () => run(controller.actions.abandon), children: "Stop checking and refresh, keeping my draft" })] }), conflict && _jsxs("div", { role: "alert", className: "boring-markdown-alert", children: ["The saved document changed. Your local text has been kept.", _jsx(Control, { type: "button", disabled: pending || uncertain, onClick: () => run(controller.actions.refresh), children: "Check saved version" }), _jsx(Control, { type: "button", disabled: pending || uncertain, onClick: () => run(controller.actions.discardToRemote), children: "Discard local changes and reload" })] }), (outcome?.kind === 'denied' || outcome?.kind === 'unavailable' || outcome?.kind === 'file_too_large') && _jsx("p", { role: "alert", className: "boring-markdown-alert", children: outcome.reason }), error && _jsx("p", { role: "alert", className: "boring-markdown-alert", children: error }), state.proposals.map(proposal => _jsxs("article", { "data-boring": "proposal", className: "boring-markdown-proposal", children: [_jsx("h3", { children: proposal.summary || 'Proposed edit' }), _jsxs("details", { children: [_jsx("summary", { children: "Review text changes" }), _jsx(MarkdownProposalDiff, { components: components, proposal: proposal }), _jsxs("details", { children: [_jsx("summary", { children: "Exact before and after" }), _jsx("h4", { children: "Before" }), _jsx("pre", { children: proposal.before }), _jsx("h4", { children: "After" }), _jsx("pre", { children: proposal.after })] })] }), _jsx(Control, { type: "button", disabled: unavailable || pending || uncertain || proposal.adopted, onClick: () => run(() => controller.actions.accept(proposal.id)), children: proposal.adopted ? 'Adopted' : 'Accept and save' }), _jsx(Control, { type: "button", onClick: () => controller.actions.reject(proposal.id), children: "Dismiss proposal" })] }, proposal.id)), mode === 'source'
-                ? _jsx(Source, { ref: sourceInput, className: "boring-markdown-source", "aria-label": `${title} Markdown source`, value: state.text, readOnly: unavailable, spellCheck: false, onChange: event => controller.actions.edit(event.currentTarget.value) })
+                ? _jsx(Source, { ref: sourceInput, className: "boring-markdown-source", "aria-label": `${title} Markdown source`, value: state.text, readOnly: unavailable, spellCheck: false, onSelect: event => onQuoteSelection?.(captureMarkdownQuote(state.text, { start: event.currentTarget.selectionStart, end: event.currentTarget.selectionEnd })), onChange: event => controller.actions.edit(event.currentTarget.value) })
                 : _jsx("div", { className: "boring-markdown-surface", onKeyDownCapture: markInteraction, onBeforeInputCapture: markInteraction, onInputCapture: markInteraction, onPasteCapture: markInteraction, onDropCapture: markInteraction, onChangeCapture: markInteraction, onClickCapture: event => { markInteraction(); 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: _jsx(EditorContent, { editor: editor }) })] });

package/dist/markdown-highlight-layer.d.ts

@@ -0,0 +1,26 @@
+import type { Editor } from '@tiptap/core';
+import { captureMarkdownQuote, type MarkdownQuoteAnchor, type MarkdownQuoteRange } from './markdown-quote.js';
+import type { MarkColour } from './mark-store.js';
+export interface MarkdownDecoration {
+    readonly id: string;
+    readonly anchor: MarkdownQuoteAnchor;
+    readonly colour: MarkColour;
+    readonly active?: boolean;
+    readonly commented?: boolean;
+    readonly commentLabel?: string;
+    readonly confirmed?: {
+        readonly source: string;
+        readonly range: MarkdownQuoteRange;
+    };
+}
+export type MarkdownQuoteCapture = ReturnType<typeof captureMarkdownQuote>;
+export declare function markdownMarkerBackground(colour: MarkColour): string;
+/** The native serializer proves the complete source unchanged after removing two sentinels.
+ * If syntax/escaping/normalization changes, there is no source projection. */
+export declare function markdownTextProjection(editor: Editor, source: string): readonly {
+    readonly rich: number;
+    readonly source: MarkdownQuoteRange;
+}[];
+export declare function captureRichMarkdownQuote(editor: Editor, source: string): MarkdownQuoteCapture;
+export declare function installMarkdownHighlights(editor: Editor, source: string, marks: readonly MarkdownDecoration[], activate?: (id: string) => void): () => void;
+//# sourceMappingURL=markdown-highlight-layer.d.ts.map

package/dist/markdown-highlight-layer.js

@@ -0,0 +1,107 @@
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+import { finishRichMarkdown } from './markdown-safety.js';
+import { captureMarkdownQuote, markdownQuoteResolution } from './markdown-quote.js';
+const key = new PluginKey('boring-markdown-highlights');
+const left = 'BORINGQUOTELEFTBOUNDARY', right = 'BORINGQUOTERIGHTBOUNDARY';
+export function markdownMarkerBackground(colour) {
+    return `color-mix(in oklab,var(--${colour}) 12%,color-mix(in oklab,var(--chart-4,var(--accent)) 24%,var(--background)))`;
+}
+/** The native serializer proves the complete source unchanged after removing two sentinels.
+ * If syntax/escaping/normalization changes, there is no source projection. */
+export function markdownTextProjection(editor, source) {
+    if (!editor.markdown || source.includes(left) || source.includes(right) || finishRichMarkdown(editor.getMarkdown(), source) !== source)
+        return [];
+    const leaves = [];
+    editor.state.doc.descendants((node, position) => { if (node.isText && node.text)
+        leaves.push({ position, text: node.text }); });
+    return leaves.flatMap((leaf, index) => {
+        const json = editor.state.doc.toJSON();
+        let count = 0;
+        const insert = (node) => { if (node.type === 'text') {
+            if (count === index)
+                node.text = left + node.text + right;
+            count++;
+        } node.content?.forEach(insert); };
+        insert(json);
+        const marked = finishRichMarkdown(editor.markdown.serialize(json), source);
+        const start = marked.indexOf(left), end = marked.indexOf(right);
+        if (start < 0 || end < start || marked.indexOf(left, start + left.length) !== -1 || marked.indexOf(right, end + right.length) !== -1)
+            return [];
+        if (marked.slice(0, start) + marked.slice(start + left.length, end) + marked.slice(end + right.length) !== source
+            || marked.slice(start + left.length, end) !== leaf.text)
+            return [];
+        return [{ rich: leaf.position, source: { start, end: end - left.length } }];
+    });
+}
+export function captureRichMarkdownQuote(editor, source) {
+    const selection = editor.state.selection;
+    if (selection.empty)
+        return captureMarkdownQuote(source, { start: 0, end: 0 });
+    const mapped = markdownTextProjection(editor, source).find(p => selection.from >= p.rich && selection.to <= p.rich + p.source.end - p.source.start);
+    return mapped ? captureMarkdownQuote(source, { start: mapped.source.start + selection.from - mapped.rich, end: mapped.source.start + selection.to - mapped.rich })
+        : { kind: 'refused', reason: 'This rich selection has no exact source projection. Select the Markdown source instead.' };
+}
+export function installMarkdownHighlights(editor, source, marks, activate) {
+    const doc = editor.state.doc, projection = markdownTextProjection(editor, source), decorations = [];
+    for (const mark of marks) {
+        if (!['accent', 'primary', 'muted'].includes(mark.colour))
+            continue;
+        const placed = markdownQuoteResolution.resolve(mark.anchor, source, source);
+        const confirmed = mark.confirmed;
+        const range = confirmed?.source === source && placed.kind === 'ambiguous'
+            && placed.candidates.some(candidate => candidate.start === confirmed.range.start && candidate.end === confirmed.range.end)
+            ? confirmed.range : placed.kind === 'exact' || placed.kind === 'moved' ? placed.range : null;
+        if (!range)
+            continue;
+        let indicatorPosition;
+        for (const leaf of projection) {
+            const from = Math.max(leaf.source.start, range.start), to = Math.min(leaf.source.end, range.end);
+            if (from < to) {
+                indicatorPosition = leaf.rich + to - leaf.source.start;
+                decorations.push(Decoration.inline(leaf.rich + from - leaf.source.start, indicatorPosition, { 'data-mark-id': mark.id, 'data-mark-colour': mark.colour, 'data-mark-active': String(mark.active === true), role: 'button', tabindex: '0', 'aria-label': mark.anchor.fallback,
+                    style: `background-color:${markdownMarkerBackground(mark.colour)};color:var(--foreground);${mark.active ? 'outline:var(--border-width, 1px) solid var(--ring);' : ''}` }));
+            }
+        }
+        if (mark.commented && indicatorPosition !== undefined)
+            decorations.push(Decoration.widget(indicatorPosition, () => {
+                const document = editor.view.dom.ownerDocument, indicator = document.createElement('span');
+                indicator.dataset['markComment'] = mark.id;
+                indicator.setAttribute('role', 'img');
+                indicator.setAttribute('aria-label', mark.commentLabel ?? 'Has a comment');
+                indicator.style.cssText = 'display:inline-flex;vertical-align:super;margin-inline-start:0.15em;color:var(--muted-foreground)';
+                const icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+                icon.setAttribute('viewBox', '0 0 16 16');
+                icon.setAttribute('width', '0.75em');
+                icon.setAttribute('height', '0.75em');
+                icon.setAttribute('aria-hidden', 'true');
+                const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+                path.setAttribute('d', 'M3 2.5h10v8H7l-4 3v-11Z');
+                path.setAttribute('fill', 'none');
+                path.setAttribute('stroke', 'currentColor');
+                icon.append(path);
+                indicator.append(icon);
+                return indicator;
+            }, { side: -1, key: `comment-${mark.id}` }));
+    }
+    const activateElement = (event) => {
+        const element = event.target;
+        const target = element?.closest?.('[data-mark-id], [data-mark-comment]');
+        const id = target?.getAttribute('data-mark-id') ?? target?.getAttribute('data-mark-comment');
+        if (!id)
+            return false;
+        activate?.(id);
+        return true;
+    };
+    const decorationSet = DecorationSet.create(doc, decorations);
+    editor.registerPlugin(new Plugin({ key, props: {
+            decorations: state => state.doc === doc ? decorationSet : DecorationSet.empty,
+            handleDOMEvents: { click: (_view, event) => activateElement(event), contextmenu: (_view, event) => { if (!activateElement(event))
+                    return false; event.preventDefault(); return true; },
+                keydown: (_view, event) => { if (event.key !== 'Enter' && event.key !== ' ')
+                    return false; if (!activateElement(event))
+                    return false; event.preventDefault(); return true; } },
+        } }));
+    return () => { if (!editor.isDestroyed)
+        editor.unregisterPlugin(key); };
+}

package/dist/markdown-quote.d.ts

@@ -0,0 +1,23 @@
+import type { Anchor, AnchorResolution } from './contracts.js';
+/** Offsets address the canonical Markdown string in UTF-16, never rendered text. */
+export interface MarkdownQuoteRange {
+    readonly start: number;
+    readonly end: number;
+}
+export interface MarkdownQuoteAnchor extends Anchor {
+    readonly kind: 'markdown.quote@1';
+    readonly exact: string;
+    readonly prefix: string;
+    readonly suffix: string;
+    readonly start: number;
+    readonly fallback: string;
+}
+export declare function captureMarkdownQuote(source: string, range: MarkdownQuoteRange): {
+    readonly kind: 'captured';
+    readonly anchor: MarkdownQuoteAnchor;
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+export declare const markdownQuoteResolution: AnchorResolution<MarkdownQuoteAnchor, string, MarkdownQuoteRange>;
+//# sourceMappingURL=markdown-quote.d.ts.map

package/dist/markdown-quote.js

@@ -0,0 +1,39 @@
+const boundary = (text, at) => !(at > 0 && at < text.length && /[\uD800-\uDBFF]/.test(text[at - 1]) && /[\uDC00-\uDFFF]/.test(text[at]));
+const offset = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+function parse(value) {
+    if (!value || typeof value !== 'object')
+        throw new TypeError('Expected Markdown quote anchor');
+    const a = value;
+    if (a['kind'] !== 'markdown.quote@1' || typeof a['exact'] !== 'string' || !a['exact'] || typeof a['prefix'] !== 'string'
+        || typeof a['suffix'] !== 'string' || !offset(a['start']) || typeof a['fallback'] !== 'string' || !a['fallback'].trim())
+        throw new TypeError('Invalid Markdown quote anchor');
+    return { kind: 'markdown.quote@1', exact: a['exact'], prefix: a['prefix'], suffix: a['suffix'], start: a['start'], fallback: a['fallback'] };
+}
+export function captureMarkdownQuote(source, range) {
+    if (!offset(range.start) || !offset(range.end) || range.end <= range.start || range.end > source.length || !boundary(source, range.start) || !boundary(source, range.end))
+        return { kind: 'refused', reason: 'Select a nonempty canonical source range' };
+    const exact = source.slice(range.start, range.end);
+    return { kind: 'captured', anchor: { kind: 'markdown.quote@1', exact, prefix: source.slice(Math.max(0, range.start - 32), range.start), suffix: source.slice(range.end, range.end + 32), start: range.start, fallback: exact } };
+}
+export const markdownQuoteResolution = {
+    kind: 'markdown.quote@1',
+    schema: { jsonSchema: { type: 'object', properties: { kind: { const: 'markdown.quote@1' }, exact: { type: 'string', minLength: 1 }, prefix: { type: 'string' }, suffix: { type: 'string' }, start: { type: 'integer', minimum: 0 }, fallback: { type: 'string', minLength: 1 } }, required: ['kind', 'exact', 'prefix', 'suffix', 'start', 'fallback'], additionalProperties: false }, parse },
+    fallback: anchor => anchor.fallback,
+    resolve: (anchor, source, evaluated) => {
+        if (anchor.kind !== 'markdown.quote@1')
+            return { kind: 'unsupported', evaluated };
+        const a = parse(anchor), matches = [];
+        for (let at = source.indexOf(a.exact); at !== -1; at = source.indexOf(a.exact, at + 1)) {
+            if (boundary(source, at) && boundary(source, at + a.exact.length))
+                matches.push({ start: at, end: at + a.exact.length });
+        }
+        if (!matches.length)
+            return { kind: 'missing', evaluated };
+        const contextual = matches.filter(r => source.slice(Math.max(0, r.start - a.prefix.length), r.start) === a.prefix && source.slice(r.end, r.end + a.suffix.length) === a.suffix);
+        const candidates = contextual.length ? contextual : matches;
+        if (candidates.length !== 1)
+            return { kind: 'ambiguous', candidates, evaluated };
+        const range = candidates[0];
+        return { kind: range.start === a.start ? 'exact' : 'moved', range, evaluated };
+    },
+};

package/dist/native-chat.d.ts

@@ -111,6 +111,23 @@ export interface NativeChatSnapshot {
     readonly stop: 'idle' | 'requested' | 'confirmed' | 'unconfirmed';
     readonly disposed: boolean;
 }
+/** Structural presentation seam. Native controllers retain their concrete IDs, methods and recovery return values. */
+export type ChatSnapshot = Omit<NativeChatSnapshot, 'conversationId' | 'send'> & {
+    readonly conversationId: NativeChatSnapshot['conversationId'] | string;
+    readonly send: ChatSendState | {
+        readonly kind: 'idle' | 'submitting' | 'admitted';
+    } | {
+        readonly kind: 'unknown';
+        readonly reason: string;
+        readonly retryable: boolean;
+    };
+};
+export type ChatController = Pick<NativeChatController, 'subscribe' | 'setText' | 'setAttachments' | 'clearHistory' | 'loadEarlier' | 'connect' | 'stop' | 'dispose'> & {
+    readonly getSnapshot: () => ChatSnapshot;
+    readonly send: (whenBusy?: ChatAttempt['whenBusy'], input?: ChatSendInput) => Promise<unknown>;
+    readonly reconcile: () => Promise<unknown>;
+    readonly retrySameRequest: () => Promise<unknown>;
+};
 export interface NativeChatOptions {
     readonly identity: ChatIdentity;
     readonly conversation: ChatConversation;
@@ -120,6 +137,8 @@ export interface NativeChatOptions {
     readonly history?: NativeChatHistorySource | false;
     /** Validate the exact selected draft before any native admission. */
     readonly beforeSubmit?: (draft: ChatDraft) => Promise<string | undefined>;
+    /** Restore a question after a native model/run error with no answer text. Opt-in, local to this controller; never replays work. */
+    readonly restoreOnError?: boolean;
     /** Only a qualified host boundary can prove a thrown submission was not admitted. */
     readonly definitelyNotAdmitted?: (error: unknown) => boolean;
     readonly onListenerError?: (error: unknown) => void;
@@ -128,6 +147,8 @@ export interface NativeChatOptions {
 export declare function createNativeChatController(options: NativeChatOptions): {
     conversation: ChatConversation;
     getSnapshot: () => NativeChatSnapshot;
+    /** Reads the exact native submission with this controller's Context; observing never aborts or owns its execution. */
+    submissionStatus: (submission: Submission) => Promise<SubmissionRecord>;
     subscribe: (listener: () => void) => (() => void);
     setText: (text: string) => void;
     setAttachments: (attachments: readonly ChatAttachment[]) => void;