@hachej/boring-ui-kit 0.1.111 → 0.2.0

package/dist/remote-chat.js

@@ -0,0 +1,324 @@
+import { applyImmutable } from '@earendil-works/chord/delta';
+/** A watch request the host answered with an error status. */
+class WatchRefused extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The host refused a submitted input before it reached the conversation (status 402, `submission-refused`); `message` is the host's words. */
+export class SubmissionRefused extends Error {
+    code = 'submission-refused';
+    constructor(message) { super(message); this.name = 'SubmissionRefused'; }
+}
+async function reason(response) {
+    try {
+        const value = await response.json();
+        if (typeof value.reason === 'string')
+            return value.reason;
+    }
+    catch { /* fall through */ }
+    return `status ${response.status}`;
+}
+/**
+ * Connect a browser to one remote native conversation. Resolves after the first view so the conversation identity is the
+ * server's. A dropped or silent stream is reopened automatically with backoff (see `reconnect` and `link`); it never means the
+ * native task stopped.
+ */
+export async function createRemoteChat(options) {
+    const base = new URL(options.endpoint, globalThis.location?.href);
+    const send = options.fetch, pollMs = options.pollMs ?? 500;
+    const backoff = { base: options.reconnect?.baseDelayMs ?? 1000, max: options.reconnect?.maxDelayMs ?? 30_000 };
+    const url = (op, extra = {}) => {
+        const target = new URL(base);
+        target.searchParams.set('op', op);
+        for (const [key, value] of Object.entries(extra))
+            target.searchParams.set(key, value);
+        return target;
+    };
+    async function call(op, init = {}, extra = {}) {
+        const response = await send(new Request(url(op, extra), init));
+        if (response.status === 402 && op === 'submit') {
+            const refused = await response.json().catch(() => ({}));
+            if (refused.reason === 'submission-refused')
+                throw new SubmissionRefused(typeof refused.message === 'string' && refused.message ? refused.message : 'The host refused this message');
+        }
+        if (!response.ok)
+            throw new Error(`Remote chat ${op} failed: ${await reason(response)}`);
+        return await response.json();
+    }
+    const post = (op, value) => call(op, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(value) });
+    const lookup = async (requestId) => (await call('submission', {}, { requestId })).record ?? undefined;
+    async function watch() {
+        const stopped = new AbortController();
+        const response = await send(new Request(url('watch'), { signal: stopped.signal }));
+        if (!response.ok || !response.body)
+            throw new WatchRefused(`Remote chat watch failed: ${await reason(response)}`, response.status);
+        const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+        let pending = '', staleMs = 0, lost = false;
+        // Once the server has announced its heartbeat interval, a read waiting 2.5 intervals means the stream is dead even if the
+        // socket still looks open (a proxy that dropped it silently).
+        async function read() {
+            if (!staleMs)
+                return reader.read();
+            let timer;
+            try {
+                return await Promise.race([reader.read(), new Promise((_, reject) => {
+                        timer = setTimeout(() => { lost = true; stopped.abort(); reject(new Error('Remote chat stream went silent')); }, staleMs);
+                    })]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        async function next() {
+            for (;;) {
+                const end = pending.indexOf('\n');
+                if (end >= 0) {
+                    const line = pending.slice(0, end);
+                    pending = pending.slice(end + 1);
+                    const frame = JSON.parse(line);
+                    if (frame.kind === 'heartbeat') {
+                        if (typeof frame.intervalMs === 'number' && frame.intervalMs > 0)
+                            staleMs = frame.intervalMs * 2.5;
+                        continue;
+                    }
+                    return frame;
+                }
+                const chunk = await read();
+                if (chunk.done)
+                    return undefined;
+                pending += chunk.value;
+            }
+        }
+        const first = await next().catch(() => undefined);
+        if (first?.kind !== 'view') {
+            stopped.abort();
+            throw new Error('Remote chat watch ended before its first view');
+        }
+        let value = first.view, started = false, settle, ended;
+        const closed = new Promise(resolve => { settle = resolve; });
+        const finish = (end) => { if (!ended) {
+            ended = end;
+            stopped.abort();
+            settle(end);
+        } };
+        const handle = {
+            get value() { return value; },
+            closed,
+            lost: () => lost,
+            stop: async () => { finish({ reason: 'stopped' }); return closed; },
+            start: listener => {
+                if (started)
+                    throw new Error('Watch already started');
+                started = true;
+                void (async () => {
+                    try {
+                        for (;;) {
+                            const frame = await next();
+                            if (ended)
+                                return;
+                            // The stream ending without an end frame is a lost connection, not a native terminal state. A server-sent
+                            // `session_closed` (a host restart, for example) is reopened too; `retired`, `stopped` and `revoked` are final.
+                            if (!frame || frame.kind === 'end') {
+                                lost = !frame || frame.reason === 'session_closed';
+                                return finish({ reason: frame?.reason === 'retired' ? 'retired' : frame?.reason === 'stopped' ? 'stopped' : 'session_closed' });
+                            }
+                            // Native operation batches are replayed with the upstream delta implementation; a view frame resets the replica.
+                            value = frame.kind === 'view' ? frame.view : applyImmutable(value, frame.ops);
+                            try {
+                                await listener(value, [], context);
+                            }
+                            catch (error) {
+                                return finish({ reason: 'listener_error', error: error instanceof Error ? error : new Error(String(error)) });
+                            }
+                        }
+                    }
+                    catch (error) {
+                        if (ended)
+                            return;
+                        // A failed read (network error, silence) is a lost connection; a line the client cannot parse is not.
+                        if (error instanceof SyntaxError)
+                            return finish({ reason: 'listener_error', error });
+                        lost = true;
+                        finish({ reason: 'session_closed' });
+                    }
+                })();
+            },
+        };
+        return handle;
+    }
+    const page = options.pauseWhenHidden === false ? undefined : globalThis.document;
+    const hidden = () => page?.visibilityState === 'hidden';
+    const linkListeners = new Set();
+    let reconnecting = false;
+    const setReconnecting = (next) => {
+        if (reconnecting === next)
+            return;
+        reconnecting = next;
+        for (const listener of [...linkListeners]) {
+            try {
+                listener();
+            }
+            catch { /* a viewer's listener never breaks the link */ }
+        }
+    };
+    const link = { reconnecting: () => reconnecting, subscribe: listener => { linkListeners.add(listener); return () => { linkListeners.delete(listener); }; } };
+    /**
+     * Wrap a watch so its stream can be lost and reopened, and (with `pauseWhenHidden`) released while the page is hidden. The
+     * wrapper stays open for the controller: every reopened stream begins with a complete view, which replaces the replica, so
+     * nothing is lost or duplicated. While a lost stream is being reopened (capped exponential backoff with jitter) `link` reports
+     * reconnecting. The wrapper ends only when stopped, when the server ends the stream for good, or when it refuses to reopen it.
+     */
+    function supervise(first) {
+        let current, last = first.value, listener;
+        let ended, settle, opening = false, attempt = 0, retry;
+        const closed = new Promise(resolve => { settle = resolve; });
+        const wanted = () => listener !== undefined && !ended && !hidden();
+        const cancelRetry = () => { clearTimeout(retry); retry = undefined; };
+        const finish = (end) => {
+            if (ended)
+                return;
+            ended = end;
+            page?.removeEventListener('visibilitychange', onVisibility);
+            cancelRetry();
+            setReconnecting(false);
+            settle(end);
+            const live = current;
+            current = undefined;
+            void live?.stop();
+        };
+        const fail = (error) => finish({ reason: 'listener_error', error: error instanceof Error ? error : new Error(String(error)) });
+        const forward = async (view) => { last = view; await listener(view, [], context); };
+        const schedule = () => {
+            cancelRetry();
+            const delay = Math.min(backoff.max, backoff.base * 2 ** attempt++) * (0.5 + Math.random() / 2);
+            retry = setTimeout(() => { retry = undefined; void open(); }, delay);
+        };
+        function attach(watch) {
+            current = watch;
+            void watch.closed.then(end => {
+                if (current !== watch)
+                    return;
+                current = undefined;
+                last = watch.value;
+                if (ended)
+                    return;
+                if (watch.lost()) {
+                    setReconnecting(true);
+                    schedule();
+                }
+                else
+                    finish(end);
+            });
+            watch.start(async (view) => { if (current === watch)
+                await forward(view); });
+        }
+        async function open() {
+            if (opening || current || !wanted())
+                return;
+            opening = true;
+            try {
+                const reopened = await watch();
+                if (!wanted() || current) {
+                    await reopened.stop();
+                    return;
+                }
+                try {
+                    await forward(reopened.value);
+                }
+                catch (error) {
+                    await reopened.stop();
+                    return fail(error);
+                }
+                if (!wanted() || current) {
+                    await reopened.stop();
+                    return;
+                }
+                attempt = 0;
+                setReconnecting(false);
+                attach(reopened);
+            }
+            catch (error) {
+                if (ended)
+                    return;
+                // The host refused (signed out, revoked, gone): reopening cannot help. A network failure or a 5xx is retried.
+                const status = error instanceof WatchRefused ? error.status : 0;
+                if (status >= 400 && status < 500 && status !== 408 && status !== 429)
+                    return finish({ reason: 'session_closed' });
+                setReconnecting(true);
+                schedule();
+            }
+            finally {
+                opening = false;
+            }
+        }
+        async function pause() {
+            cancelRetry();
+            const live = current;
+            if (!live)
+                return;
+            last = live.value;
+            current = undefined;
+            await live.stop();
+        }
+        function onVisibility() { if (hidden())
+            void pause();
+        else {
+            cancelRetry();
+            void open();
+        } }
+        page?.addEventListener('visibilitychange', onVisibility);
+        return {
+            get value() { return current?.value ?? last; },
+            closed,
+            stop: async () => { finish({ reason: 'stopped' }); return closed; },
+            start: next => {
+                if (listener)
+                    throw new Error('Watch already started');
+                listener = next;
+                if (hidden())
+                    void first.stop();
+                else
+                    attach(first);
+            },
+        };
+    }
+    // The first watch tells us the conversation identity. The controller's first `watch()` takes it over instead of opening a second one.
+    let unclaimed = await watch();
+    const id = unclaimed.value.conversation.id;
+    const requests = new Map();
+    const withdraw = async (submissionId, requestId = requests.get(submissionId)) => (await post('withdraw', { submissionId, ...(requestId === undefined ? {} : { requestId }) })).result;
+    const conversation = {
+        id,
+        watch: async () => { const first = unclaimed; unclaimed = undefined; return supervise(first ?? await watch()); },
+        submit: async (draft) => {
+            if (draft.type !== 'input' || !draft.requestId)
+                throw new Error('Remote chat submits input drafts with a request ID');
+            const requestId = draft.requestId;
+            const { submissionId } = await post('submit', { requestId, content: draft.content, whenBusy: draft.whenBusy });
+            requests.set(submissionId, requestId);
+            const status = async () => { const record = await lookup(requestId); if (!record)
+                throw new Error('Submission is unknown to the remote host'); return record; };
+            return {
+                id: submissionId, status,
+                wait: async () => { for (;;) {
+                    const record = await status();
+                    if (record.status === 'done' || record.status === 'unanswered')
+                        return record;
+                    await new Promise(resolve => setTimeout(resolve, pollMs));
+                } },
+                abort: () => withdraw(submissionId, requestId),
+            };
+        },
+        // The controller only reconciles a submission by request ID; no other transaction work crosses the wire.
+        commit: async (change, _context) => change({ submissionByRequest: (_conversationId, requestId) => lookup(requestId) }),
+        abort: async () => { await post('abort', {}); },
+        entries: async (_query, limit, cursor) => (await call('entries', {}, { limit: String(limit), ...(cursor === undefined ? {} : { cursor: JSON.stringify(cursor) }) })).page,
+    };
+    const context = Object.freeze({});
+    const close = async () => { const first = unclaimed; unclaimed = undefined; await first?.stop(); };
+    return { conversation, context, close, link, withdraw: id => withdraw(id), definitelyNotAdmitted: error => error instanceof SubmissionRefused,
+        answer: (callId, answer) => post('answer', { callId, answer }), configure: change => post('configure', change) };
+}

package/dist/resources.d.ts

@@ -0,0 +1,34 @@
+/** Optional document adapter contracts. Importing the headless UI root does
+ * not require this file or @hachej/boring-files. No native Pi type dependency here.
+ */
+import type { ResourceRead, ResourceExpectation, ResourceRef, PublicationReceipt, PublicationResult } from '@hachej/boring-files';
+import type { ViewerController, ViewerDescriptor, ViewerTarget } from './contracts.js';
+export interface ResourceViewerDescriptor extends ViewerDescriptor {
+    readonly source: ResourceRead;
+}
+/** An acknowledged selection includes editor incarnation and buffer version.
+ * An absent target represents create-if-absent: no fabricated saved revision.
+ */
+export interface SaveSelection {
+    readonly target: ViewerTarget<{
+        readonly scopeId: string;
+        readonly base: ResourceExpectation;
+        readonly bufferVersion: number;
+    }>;
+}
+export type SaveResult = {
+    readonly kind: 'saved';
+    readonly selection: SaveSelection;
+    /** Actual resulting revision, also present in the checked receipt. */
+    readonly ref: ResourceRef;
+    readonly receipt: PublicationReceipt;
+} | Exclude<PublicationResult, {
+    readonly kind: 'committed';
+}>;
+export interface EditableViewerController<State, Actions, Tools = unknown> extends ViewerController<State, Actions, Tools> {
+    /** Acknowledge only this selection or fail; prior/partial/unknown effects
+     * remain explicit. Merely loading or rendering a document never saves it.
+     */
+    readonly flush: (selection: SaveSelection, signal?: AbortSignal) => Promise<SaveResult>;
+}
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.js

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

package/dist/text-buffer-state.d.ts

@@ -0,0 +1,24 @@
+import type { ResourceAccess, ResourceExpectation } from '@hachej/boring-files';
+import type { SaveResult } from './resources.js';
+import type { TextDraftRecoveryState } from './text-draft-types.js';
+export interface TextBufferState {
+    readonly identity: Pick<ResourceAccess, 'scopeId' | 'principalId' | 'initiatorId'>;
+    readonly text: string;
+    readonly base: ResourceExpectation;
+    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;
+    readonly recovery: TextDraftRecoveryState;
+}
+//# sourceMappingURL=text-buffer-state.d.ts.map

package/dist/text-buffer-state.js

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

package/dist/text-buffer.d.ts

@@ -0,0 +1,52 @@
+import type { ReadResult, ResourceClient, ResourceExpectation, ResourceLocator, ResourceSnapshot } from '@hachej/boring-files';
+import type { SaveResult, SaveSelection } from './resources.js';
+import type { TextDraftBinding } from './text-draft-types.js';
+import type { TextBufferState } from './text-buffer-state.js';
+export type { TextBufferState } from './text-buffer-state.js';
+export type TextBufferSource = {
+    readonly kind: 'saved';
+    readonly snapshot: ResourceSnapshot;
+} | {
+    readonly kind: 'new';
+    readonly target: ResourceLocator;
+    readonly text?: string;
+};
+export interface TextBufferOptions {
+    readonly identity: TextBufferState['identity'];
+    readonly instanceId: string;
+    readonly epoch: string;
+    readonly source: TextBufferSource;
+    readonly client: ResourceClient;
+    readonly readOnly?: boolean;
+    readonly onListenerError?: (error: unknown) => void;
+    readonly mediaType: string;
+    readonly emptyText?: string;
+    readonly drafts?: TextDraftBinding;
+    readonly replaceText?: (text: string) => void;
+    readonly sync?: () => void;
+    readonly readText: (snapshot: ResourceSnapshot) => string;
+}
+export declare function freeze<Value>(value: Value): Value;
+export declare function sameBase(left: ResourceExpectation, right: ResourceExpectation): boolean;
+export declare function createTextBuffer(options: TextBufferOptions): {
+    getSnapshot: () => TextBufferState;
+    subscribe: (listener: () => void) => (() => void);
+    edit: (text: string, force?: boolean) => void;
+    observe: (text: string, force?: boolean) => void;
+    selection: () => SaveSelection;
+    refresh: (discard: boolean) => Promise<ReadResult>;
+    abandon: () => Promise<ReadResult>;
+    reconcile: () => Promise<SaveResult>;
+    flush: (value: SaveSelection, signal?: AbortSignal) => Promise<SaveResult>;
+    dispose: () => void;
+    checkDrafts: () => Promise<import("./text-draft-types.js").TextDraftDiscovery>;
+    checkpointDraft: () => Promise<import("./text-draft-types.js").TextDraftCheckpointResult>;
+    restoreDraft: (choice: import("./text-draft-types.js").TextDraftChoiceSelection) => Promise<{
+        readonly kind: "restored";
+        readonly selection: SaveSelection;
+    } | import("./text-draft-types.js").TextDraftChoiceFailure>;
+    discardDraft: (choice: import("./text-draft-types.js").TextDraftChoiceSelection) => Promise<{
+        readonly kind: "discarded";
+    } | import("./text-draft-types.js").TextDraftChoiceFailure>;
+};
+//# sourceMappingURL=text-buffer.d.ts.map