@hachej/boring-ui-kit 0.1.111 → 0.2.0

package/dist/markdown-safety.js

@@ -0,0 +1,135 @@
+import { Editor } from '@tiptap/core';
+import { marked } from 'marked';
+import { createMarkdownExtensions } from './markdown-extensions.js';
+const FENCE = /^ {0,3}(```|~~~)/;
+/** Blank-line runs outside fenced code collapse to one blank line, and the ends are trimmed: the only whitespace the rich editor may normalise. */
+export function normalizeMarkdownWhitespace(text) {
+    const lines = text.split('\n');
+    const out = [];
+    let fence;
+    for (const line of lines) {
+        const opened = FENCE.exec(line);
+        if (opened && (!fence || opened[1] === fence))
+            fence = fence ? undefined : opened[1];
+        if (!fence && !opened && line.trim() === '' && out.length > 0 && out[out.length - 1].trim() === '')
+            continue;
+        out.push(line);
+    }
+    return out.join('\n').replace(/^\s+/, '').trimEnd();
+}
+const HEADING = /^ {0,3}#{1,6}(\s|$)/;
+const LIST_ITEM = /^\s*([-*+]|\d{1,9}[.)])(\s|$)/;
+/** A line that starts its own block instead of continuing the paragraph above it. */
+const BLOCK_START = /^\s*([-*+]\s|\d{1,9}[.)]\s|#{1,6}(\s|$)|>|\||```|~~~|(\*\s*){3,}$|(-\s*){3,}$|(_\s*){3,}$)/;
+/**
+ * The comparison form for the round trip: whitespace normalised, and blank lines beside an ATX heading dropped (the serialiser always
+ * puts one there, and "# Title" directly above a paragraph means the same document). Blank lines inside fenced code are kept. The
+ * indentation of a wrapped line that continues a list item's paragraph is dropped too: it is a lazy continuation line, the same
+ * paragraph however far it is indented, and the serialiser writes it unindented. A line that starts a block keeps its indentation, so
+ * a change of nesting is still a rewrite. A list may interrupt a paragraph, so the blank line the serialiser puts between a top-level
+ * paragraph and the list right under it is dropped; between list items it stays, since it makes the list loose.
+ */
+function comparableMarkdown(text) {
+    const lines = normalizeMarkdownWhitespace(text).split('\n');
+    const out = [];
+    let fence;
+    let itemParagraph = false, topParagraph = false;
+    lines.forEach((line, index) => {
+        const opened = FENCE.exec(line);
+        if (opened && (!fence || opened[1] === fence))
+            fence = fence ? undefined : opened[1];
+        const blank = line.trim() === '' && !fence && !opened;
+        const afterParagraph = topParagraph;
+        topParagraph = false;
+        if (fence || opened || blank)
+            itemParagraph = false;
+        else if (LIST_ITEM.test(line))
+            itemParagraph = true;
+        else if (itemParagraph && !BLOCK_START.test(line))
+            line = line.trimStart();
+        else {
+            itemParagraph = false;
+            topParagraph = !/^\s/.test(line) && !BLOCK_START.test(line);
+        }
+        if (blank && (HEADING.test(lines[index - 1] ?? '') || HEADING.test(lines[index + 1] ?? '')))
+            return;
+        if (blank && afterParagraph && LIST_ITEM.test(lines[index + 1] ?? '') && !/^\s/.test(lines[index + 1] ?? ''))
+            return;
+        out.push(line);
+    });
+    return out.join('\n');
+}
+/** What follows the last visible character, so a rich edit keeps the document's own final newline. */
+export function trailingWhitespace(text) { return /\s*$/.exec(text)?.[0] ?? ''; }
+/** The text a rich edit publishes: the serialised document, whitespace normalised, with the original's trailing newline. */
+export function finishRichMarkdown(serialized, previous) {
+    const body = normalizeMarkdownWhitespace(serialized);
+    return body === '' ? '' : body + (trailingWhitespace(previous) || '');
+}
+const stripCode = (text) => text.replace(/^ {0,3}(```|~~~)[\s\S]*?(?:^ {0,3}\1.*$|(?![\s\S]))/gm, '').replace(/`[^`\n]*`/g, '');
+function hasToken(tokens, type, accept = () => true) {
+    return tokens.some(token => token.type === type && accept(token)
+        || ('tokens' in token && Array.isArray(token.tokens) && hasToken(token.tokens, type, accept))
+        || ('items' in token && Array.isArray(token.items) && hasToken(token.items, type, accept)));
+}
+/** Constructs that name themselves, for a short explanation. The round trip below is the authority. */
+function namedReasons(text) {
+    const reasons = [];
+    if (/^?---[ \t]*\r?\n[\s\S]*?\r?\n(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/.test(text))
+        reasons.push('front matter');
+    let tokens = [];
+    try {
+        tokens = marked.lexer(text);
+    }
+    catch { /* the round trip still decides */ }
+    if (hasToken(tokens, 'html'))
+        reasons.push('raw HTML');
+    const prose = stripCode(text);
+    if (/\[\^[^\]\s]+\]/.test(prose))
+        reasons.push('footnotes');
+    if (hasToken(tokens, 'def', token => !('tag' in token) || !String(token.tag).startsWith('^')))
+        reasons.push('reference-style links');
+    if (text.includes('\r'))
+        reasons.push('Windows line endings');
+    return reasons;
+}
+const cache = new Map();
+/**
+ * Decides whether the rich editor can open and edit `text` without changing anything but what the person edits: the text is
+ * parsed into the editor's document and serialised back without any edit, and must equal the original apart from blank-line runs and
+ * the ends. Named constructs the editor cannot hold (front matter, raw HTML, footnotes, reference links, CRLF) are reported as the
+ * reason. Without a DOM only the named constructs can be checked.
+ */
+export function checkMarkdownRichSafety(text) {
+    if (text === '')
+        return { safe: true };
+    const known = cache.get(text);
+    if (known)
+        return known;
+    const reasons = namedReasons(text);
+    if (reasons.length === 0 && typeof document !== 'undefined') {
+        let editor;
+        try {
+            editor = new Editor({ element: document.createElement('div'), extensions: createMarkdownExtensions(), content: '' });
+            editor.commands.setContent(text, { contentType: 'markdown', emitUpdate: false });
+            if (comparableMarkdown(editor.getMarkdown()) !== comparableMarkdown(text))
+                reasons.push('formatting the rich editor would rewrite');
+        }
+        catch {
+            reasons.push('content the rich editor cannot read');
+        }
+        finally {
+            editor?.destroy();
+        }
+    }
+    const result = reasons.length ? { safe: false, reasons } : { safe: true };
+    if (cache.size > 32)
+        cache.delete(cache.keys().next().value);
+    cache.set(text, result);
+    return result;
+}
+export function describeUnsafe(safety) {
+    if (safety.safe)
+        return '';
+    return `Rich editing is off because this document contains ${safety.reasons.join(', ')}, which it could not keep exactly. You can still edit the Markdown source.`;
+}

package/dist/markdown.d.ts

@@ -0,0 +1,86 @@
+import type { ReadResult, ResourceAccess, ResourceClient, ResourceExpectation, ResourceLocator, ResourceSnapshot } from '@hachej/boring-files';
+import { type TextEdit } from '@hachej/boring-files/text';
+import type { PresentationCommand, PresentationResult } from './contracts.js';
+import type { EditableViewerController, SaveResult, SaveSelection } from './resources.js';
+import type { TextDraftActions, TextDraftOptions, TextDraftRecoveryState } from './text-draft-types.js';
+export type MarkdownSource = {
+    readonly kind: 'saved';
+    readonly snapshot: ResourceSnapshot;
+} | {
+    readonly kind: 'new';
+    readonly target: ResourceLocator;
+    readonly text?: string;
+};
+export interface MarkdownProposal {
+    readonly id: string;
+    readonly base: SaveSelection;
+    readonly before: string;
+    readonly after: string;
+    readonly edits: readonly TextEdit[];
+    readonly summary: string;
+    readonly adopted: boolean;
+}
+type MarkdownSubject = SaveSelection['target']['subject'];
+export interface MarkdownInspection {
+    readonly selection: SaveSelection;
+    readonly text: string;
+    readonly dirty: boolean;
+}
+export interface MarkdownTools {
+    readonly inspect: PresentationCommand<{
+        readonly expiresAt: number;
+    }, MarkdownInspection, MarkdownSubject>;
+    readonly propose: PresentationCommand<{
+        readonly expiresAt: number;
+        readonly edits: readonly TextEdit[];
+        readonly summary: string;
+    }, void, MarkdownSubject>;
+}
+export interface MarkdownState {
+    readonly recovery: TextDraftRecoveryState;
+    readonly identity: Pick<ResourceAccess, 'scopeId' | 'principalId' | 'initiatorId'>;
+    readonly text: string;
+    readonly base: ResourceExpectation;
+    readonly proposals: readonly MarkdownProposal[];
+    readonly readOnly: boolean;
+    readonly bufferVersion: number;
+    readonly dirty: boolean;
+    readonly lifecycle: 'active' | 'disposed';
+    readonly save: {
+        readonly kind: 'idle';
+    } | {
+        readonly kind: 'pending';
+        readonly operationId: string;
+    } | {
+        readonly kind: 'settled';
+        readonly result: SaveResult;
+    };
+    readonly remote: ResourceExpectation | null;
+}
+export interface MarkdownActions extends TextDraftActions {
+    readonly propose: (base: SaveSelection, edits: readonly TextEdit[], summary?: string) => PresentationResult<void, MarkdownSubject>;
+    readonly accept: (proposalId: string) => Promise<SaveResult>;
+    readonly reject: (proposalId: string) => void;
+    readonly edit: (text: string) => void;
+    readonly selection: () => SaveSelection;
+    readonly refresh: () => Promise<ReadResult>;
+    readonly reconcile: () => Promise<SaveResult>;
+    /** For an unconfirmed save: stop reconciling and refresh, keeping the draft. The save is never reported committed or replayed. */
+    readonly abandon: () => Promise<ReadResult>;
+    readonly discardToRemote: () => Promise<ReadResult>;
+}
+export interface MarkdownOptions {
+    readonly drafts?: TextDraftOptions;
+    /** Expected authenticated identity is comparison metadata, never a grant. */
+    readonly identity: Pick<ResourceAccess, 'scopeId' | 'principalId' | 'initiatorId'>;
+    readonly instanceId: string;
+    readonly epoch: string;
+    readonly source: MarkdownSource;
+    readonly client: ResourceClient;
+    readonly readOnly?: boolean;
+    readonly onListenerError?: (error: unknown) => void;
+}
+export type MarkdownController = EditableViewerController<MarkdownState, MarkdownActions, MarkdownTools>;
+export declare function createMarkdownController(options: MarkdownOptions): MarkdownController;
+export {};
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.js

@@ -0,0 +1,121 @@
+import { applyTextEdits, parseTextEdits } from '@hachej/boring-files/text';
+import { createTextBuffer, freeze, sameBase } from './text-buffer.js';
+import { randomUUID } from '@hachej/boring-files/platform';
+export function createMarkdownController(options) {
+    const { drafts, ...bufferOptions } = options;
+    const buffer = createTextBuffer({ ...bufferOptions, ...(drafts ? { drafts: { ...drafts, format: 'markdown/v1' } } : {}), mediaType: 'text/markdown', readText: snapshot => {
+            if (snapshot.mediaType !== 'text/markdown' && snapshot.mediaType !== 'text/plain')
+                throw new TypeError('Expected Markdown or plain text');
+            return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(snapshot.bytes);
+        } });
+    let state = freeze({ ...buffer.getSnapshot(), proposals: [] });
+    const listeners = new Set();
+    const update = (next) => {
+        state = freeze(next);
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                queueMicrotask(() => { if (options.onListenerError)
+                    options.onListenerError(error);
+                else
+                    throw error; });
+            }
+        }
+    };
+    const unsubscribe = buffer.subscribe(() => update({ ...buffer.getSnapshot(), proposals: state.proposals }));
+    const selection = buffer.selection;
+    const selected = (value) => {
+        const current = selection().target, supplied = value.target;
+        return current.instanceId === supplied.instanceId && current.epoch === supplied.epoch
+            && current.subject.scopeId === supplied.subject.scopeId && current.subject.bufferVersion === supplied.subject.bufferVersion
+            && sameBase(current.subject.base, supplied.subject.base);
+    };
+    function propose(base, input, summary = '') {
+        if (state.lifecycle === 'disposed')
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (state.readOnly)
+            return { kind: 'denied', reason: 'Viewer is read-only' };
+        if (!selected(base))
+            return { kind: 'stale', reason: 'Proposal target has changed' };
+        const edits = parseTextEdits(input);
+        if (typeof summary !== 'string')
+            throw new TypeError('Proposal summary must be text');
+        const result = applyTextEdits(state.text, edits);
+        if (result.kind === 'rejected')
+            return { kind: 'denied', reason: result.reason };
+        const proposal = { id: randomUUID(), base: structuredClone(base), before: state.text, after: result.text, edits, summary, adopted: false };
+        update({ ...state, proposals: [...state.proposals, proposal] });
+        return { kind: 'proposed', proposalId: proposal.id, base: proposal.base.target };
+    }
+    function accept(proposalId) {
+        if (state.lifecycle === 'disposed')
+            return Promise.resolve({ kind: 'unavailable', reason: 'Viewer is disposed' });
+        if (state.readOnly)
+            return Promise.resolve({ kind: 'denied', reason: 'Viewer is read-only' });
+        const unconfirmed = state.save.kind === 'pending' ? state.save.operationId
+            : state.save.kind === 'settled' && state.save.result.kind === 'unknown' ? state.save.result.operationId : undefined;
+        if (unconfirmed !== undefined)
+            return Promise.resolve({ kind: 'unknown', operationId: unconfirmed, reason: 'Reconcile or await the earlier save before accepting a proposal' });
+        const proposal = state.proposals.find(value => value.id === proposalId);
+        if (!proposal || proposal.adopted || !selected(proposal.base))
+            return Promise.resolve({ kind: 'conflict', current: state.base.kind === 'revision' ? [state.base.target] : [], reason: 'Proposal base has changed or was already adopted' });
+        const nextVersion = state.bufferVersion + 1;
+        const adoptedSelection = freeze({ target: { ...proposal.base.target, subject: { ...proposal.base.target.subject, bufferVersion: nextVersion } } });
+        state = freeze({ ...state, proposals: state.proposals.map(value => value.id === proposalId ? { ...value, adopted: true } : value) });
+        buffer.edit(proposal.after, true);
+        return buffer.flush(adoptedSelection);
+    }
+    function commandInput(value) {
+        if (!value || typeof value !== 'object' || !('expiresAt' in value) || typeof value.expiresAt !== 'number' || !Number.isSafeInteger(value.expiresAt))
+            throw new TypeError('Command expiry is required');
+        return { expiresAt: value.expiresAt };
+    }
+    const tools = {
+        inspect: {
+            name: 'inspect_buffer', input: { jsonSchema: { type: 'object', properties: { expiresAt: { type: 'integer' } }, required: ['expiresAt'] }, parse: commandInput },
+            invoke: async (target, input, signal) => {
+                if (state.lifecycle === 'disposed')
+                    return { kind: 'unavailable', reason: 'Viewer is disposed' };
+                if (signal?.aborted)
+                    return { kind: 'denied', reason: 'Command was cancelled' };
+                if (commandInput(input).expiresAt <= Date.now() || !selected({ target }))
+                    return { kind: 'stale', reason: 'Command expired or its target changed' };
+                return { kind: 'applied', value: { selection: selection(), text: state.text, dirty: state.dirty } };
+            },
+        },
+        propose: {
+            name: 'propose_patch', input: {
+                jsonSchema: { type: 'object', properties: { expiresAt: { type: 'integer' }, summary: { type: 'string' }, edits: { type: 'array', minItems: 1, items: { type: 'object', properties: { find: { type: 'string', minLength: 1 }, replace: { type: 'string' } }, required: ['find', 'replace'], additionalProperties: false } } }, required: ['expiresAt', 'summary', 'edits'] },
+                parse: value => {
+                    const expiry = commandInput(value);
+                    if (!value || typeof value !== 'object' || !('edits' in value) || !('summary' in value) || typeof value.summary !== 'string')
+                        throw new TypeError('Expected edits and summary');
+                    return { ...expiry, edits: parseTextEdits(value.edits), summary: value.summary };
+                },
+            },
+            invoke: async (target, input, signal) => {
+                if (signal?.aborted)
+                    return { kind: 'denied', reason: 'Command was cancelled' };
+                if (commandInput(input).expiresAt <= Date.now())
+                    return { kind: 'stale', reason: 'Command expired' };
+                return propose({ target }, input.edits, input.summary);
+            },
+        },
+    };
+    return {
+        getSnapshot: () => state,
+        subscribe: listener => { if (state.lifecycle === 'disposed')
+            return () => { }; listeners.add(listener); return () => { listeners.delete(listener); }; },
+        actions: {
+            edit: text => buffer.edit(text),
+            propose, accept, reject: proposalId => { if (state.lifecycle !== 'disposed')
+                update({ ...state, proposals: state.proposals.filter(value => value.id !== proposalId) }); },
+            checkDrafts: buffer.checkDrafts, checkpointDraft: buffer.checkpointDraft, restoreDraft: buffer.restoreDraft, discardDraft: buffer.discardDraft,
+            selection, refresh: () => buffer.refresh(false), discardToRemote: () => buffer.refresh(true), reconcile: buffer.reconcile, abandon: buffer.abandon,
+        },
+        tools: Object.freeze(tools), flush: buffer.flush,
+        dispose: () => { buffer.dispose(); unsubscribe(); listeners.clear(); },
+    };
+}

package/dist/native-chat.d.ts

@@ -0,0 +1,150 @@
+import type { Context } from '@earendil-works/chord';
+import type { Conversation, ConversationView, EntryRecord, InputSubmissionDraft, Submission, SubmissionRecord, Tx, WatchEnd } from '@earendil-works/pi-durable';
+import type { ImageContent } from '@earendil-works/pi-ai';
+import type { ChatSource } from './pi.js';
+export interface ChatIdentity {
+    readonly runtimeId: string;
+    readonly scopeId: string;
+    readonly principalId: string;
+}
+export interface ChatAttachment {
+    readonly id: string;
+    readonly name: string;
+    readonly content: ImageContent;
+}
+export interface ChatDraft {
+    readonly text: string;
+    readonly attachments: readonly ChatAttachment[];
+    readonly version: number;
+}
+export interface ChatAttempt {
+    readonly requestId: string;
+    readonly draft: ChatDraft;
+    readonly whenBusy: NonNullable<InputSubmissionDraft['whenBusy']>;
+}
+/**
+ * Explicit content for `send` instead of the composer draft (the composer is then left alone). `restore` is what goes back into the
+ * composer if the host refuses it (default: the content itself), for example the person's own text without a host-attached block.
+ */
+export interface ChatSendInput {
+    readonly text: string;
+    readonly attachments?: readonly ChatAttachment[];
+    readonly restore?: {
+        readonly text: string;
+        readonly attachments?: readonly ChatAttachment[];
+    };
+}
+export type ChatSendState = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'validating';
+    readonly draft: ChatDraft;
+} | {
+    readonly kind: 'blocked';
+    readonly reason: string;
+} | {
+    readonly kind: 'submitting' | 'unknown';
+    readonly attempt: ChatAttempt;
+} | {
+    readonly kind: 'admitted';
+    readonly attempt: ChatAttempt;
+    readonly submissionId: Submission['id'];
+    readonly record?: SubmissionRecord;
+};
+/** `reconnecting`: the watch is still owned but its remote stream was lost and is being reopened (see `ChatLink`). */
+export type ChatConnection = {
+    readonly kind: 'idle' | 'connecting' | 'connected' | 'reconnecting';
+} | {
+    readonly kind: 'closed';
+    readonly end?: WatchEnd;
+} | {
+    readonly kind: 'error';
+    readonly error: unknown;
+};
+/**
+ * The part of a conversation the controller uses. A native `Conversation` satisfies it, and so does the remote client of
+ * `@hachej/boring-ui-kit/remote-chat`, which implements exactly these members (everything else is unavailable over the wire).
+ */
+export interface ChatConversation {
+    readonly id: Conversation['id'];
+    readonly watch: Conversation['watch'];
+    readonly submit: (draft: InputSubmissionDraft, context: Context) => Promise<Submission>;
+    readonly abort: Conversation['abort'];
+    readonly entries: Conversation['entries'];
+    /** Only `tx.submissionByRequest` is used, to reconcile an unconfirmed send. */
+    readonly commit: <T>(change: (tx: Pick<Tx, 'submissionByRequest'>) => T | Promise<T>, context: Context) => Promise<T>;
+}
+/**
+ * A remote source's link to its host, for example `link` from `@hachej/boring-ui-kit/remote-chat`. While it reports reconnecting, the
+ * controller's watch stays open (it receives a complete view when the stream is back) and the connection reads `reconnecting`.
+ */
+export interface ChatLink {
+    readonly reconnecting: () => boolean;
+    readonly subscribe: (listener: () => void) => () => void;
+}
+export interface NativeChatHistorySource {
+    readonly id: Conversation['id'];
+    readonly entries: Conversation['entries'];
+}
+export type ChatHistoryState = {
+    readonly kind: 'disabled' | 'idle';
+} | {
+    readonly kind: 'loading' | 'ready';
+    readonly entries: readonly EntryRecord[];
+    readonly hasMore: boolean;
+} | {
+    readonly kind: 'error';
+    readonly entries: readonly EntryRecord[];
+    readonly hasMore: boolean;
+    readonly error: unknown;
+};
+export interface NativeChatSnapshot {
+    readonly identity: ChatIdentity;
+    readonly conversationId: Conversation['id'];
+    readonly connection: ChatConnection;
+    readonly view?: ConversationView;
+    readonly draft: ChatDraft;
+    /** Messages already taken from the composer that wait, in order, for the current send to be confirmed before they are submitted. */
+    readonly outbox: readonly ChatDraft[];
+    readonly history: ChatHistoryState;
+    readonly send: ChatSendState;
+    readonly stop: 'idle' | 'requested' | 'confirmed' | 'unconfirmed';
+    readonly disposed: boolean;
+}
+export interface NativeChatOptions {
+    readonly identity: ChatIdentity;
+    readonly conversation: ChatConversation;
+    readonly context: Context;
+    readonly source?: ChatSource;
+    readonly link?: ChatLink;
+    readonly history?: NativeChatHistorySource | false;
+    /** Validate the exact selected draft before any native admission. */
+    readonly beforeSubmit?: (draft: ChatDraft) => Promise<string | undefined>;
+    /** Only a qualified host boundary can prove a thrown submission was not admitted. */
+    readonly definitelyNotAdmitted?: (error: unknown) => boolean;
+    readonly onListenerError?: (error: unknown) => void;
+}
+/** Local presentation/draft state over a borrowed native conversation and one owned native watch. */
+export declare function createNativeChatController(options: NativeChatOptions): {
+    conversation: ChatConversation;
+    getSnapshot: () => NativeChatSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    setText: (text: string) => void;
+    setAttachments: (attachments: readonly ChatAttachment[]) => void;
+    clearHistory: () => void;
+    loadEarlier: () => Promise<void>;
+    connect: () => Promise<void>;
+    /**
+     * Sends the composer draft (or `input`) and empties the composer at once. While another send is still being confirmed the message
+     * waits in `outbox` and is submitted, in order, after it. A refused message, and any waiting behind it, go back into the composer
+     * ahead of what was typed since; nothing is dropped or merged into another message. Resolves with the native submission, or
+     * undefined when the message was not admitted (refused, unknown, or the controller was disposed).
+     */
+    send: (whenBusy?: ChatAttempt["whenBusy"], input?: ChatSendInput) => Promise<Submission | undefined>;
+    reconcile: () => Promise<SubmissionRecord | undefined>;
+    retrySameRequest: () => Promise<Submission | undefined>;
+    stop: () => Promise<void>;
+    dispose: () => Promise<WatchEnd | undefined>;
+};
+export type NativeChatController = ReturnType<typeof createNativeChatController>;
+//# sourceMappingURL=native-chat.d.ts.map