@superdoc/sdk 2.27.0 → 2.28.0

package/dist/agent/lead-in-label.d.ts

@@ -0,0 +1,29 @@
+export declare const LEAD_IN_DELIMITERS: readonly [":", " — ", " – ", " - ", "—", "–"];
+export declare const LEAD_IN_MAX_CHARS = 90;
+export declare const LEAD_IN_BODY_SAMPLE_CHARS = 40;
+export declare const LEAD_IN_QUOTES: readonly ["\"", "“", "‘", "'"];
+export type LabelBeforeDelimiter = {
+    kind: 'before';
+    delimiter: string | null;
+};
+export type LabelIncludingDelimiter = {
+    kind: 'inside';
+    delimiter: string;
+    occurrence: number;
+};
+export type QuotedDefinedTerm = {
+    kind: 'quoted';
+    quote: string;
+};
+export type EmphasisedOpeningWord = {
+    kind: 'word';
+    label: string;
+};
+export type LabelLeadInShape = LabelBeforeDelimiter | LabelIncludingDelimiter | QuotedDefinedTerm | EmphasisedOpeningWord;
+export type LeadInSpan = {
+    start: number;
+    end: number;
+};
+export declare function leadInEndOf(text: string, siblingDelimiter?: string | null): number | null;
+export declare function leadInShapeOf(blockText: string, labelText: string, quote?: string): LabelLeadInShape | null;
+export declare function labelLeadInSpanOf(text: string, shape: LabelLeadInShape): LeadInSpan | null;

package/dist/agent/lead-in-label.js

@@ -0,0 +1,90 @@
+const SPACED_DASH_DELIMITERS = [' — ', ' – ', ' - '];
+const BARE_DASH_DELIMITERS = ['—', '–'];
+export const LEAD_IN_DELIMITERS = [':', ...SPACED_DASH_DELIMITERS, ...BARE_DASH_DELIMITERS];
+const DELIMITERS_A_LABEL_RUN_MAY_END_WITH = ['. ', ': ', ...LEAD_IN_DELIMITERS];
+export const LEAD_IN_MAX_CHARS = 90;
+export const LEAD_IN_BODY_SAMPLE_CHARS = 40;
+export const LEAD_IN_QUOTES = ['"', '“', '‘', "'"];
+const QUOTED_TERM_OPENER_WINDOW = 2;
+const SINGLE_WORD_THEN_SPACE = /^\S+\s$/;
+function labelEndAt(text, delimiter) {
+    const index = text.indexOf(delimiter);
+    return index > 0 && index <= LEAD_IN_MAX_CHARS ? index : null;
+}
+function earliestLeadInEnd(text) {
+    const found = LEAD_IN_DELIMITERS.map((delimiter) => labelEndAt(text, delimiter)).filter((index) => index != null);
+    return found.length > 0 ? Math.min(...found) : null;
+}
+export function leadInEndOf(text, siblingDelimiter) {
+    const siblingEnd = siblingDelimiter ? labelEndAt(text, siblingDelimiter) : null;
+    return siblingEnd ?? earliestLeadInEnd(text);
+}
+function labelRunTailShapeOf(labelText) {
+    const trimmed = labelText.trimEnd();
+    const delimiter = DELIMITERS_A_LABEL_RUN_MAY_END_WITH.find((d) => trimmed.endsWith(d.trimEnd()) && trimmed.length > d.trimEnd().length);
+    if (!delimiter)
+        return null;
+    const occurrence = labelText.split(delimiter).length - 1;
+    return occurrence > 0 ? { kind: 'inside', delimiter, occurrence } : null;
+}
+function emphasisedOpeningWordOf(blockText, labelText) {
+    const opensWithSingleWord = SINGLE_WORD_THEN_SPACE.test(labelText) && blockText.length > labelText.length && blockText.startsWith(labelText);
+    return opensWithSingleWord ? { kind: 'word', label: labelText.trimEnd() } : null;
+}
+export function leadInShapeOf(blockText, labelText, quote) {
+    if (quote)
+        return { kind: 'quoted', quote };
+    const delimiterAfterLabel = LEAD_IN_DELIMITERS.find((d) => blockText.startsWith(d, labelText.length));
+    if (delimiterAfterLabel)
+        return { kind: 'before', delimiter: delimiterAfterLabel };
+    return labelRunTailShapeOf(labelText) ?? emphasisedOpeningWordOf(blockText, labelText);
+}
+function isWordBoundary(character) {
+    return character === '' || /\s/.test(character);
+}
+function openingWordSpanOf(text, shape) {
+    const opensWithSameWord = text.startsWith(shape.label) && isWordBoundary(text.charAt(shape.label.length));
+    return opensWithSameWord ? { start: 0, end: shape.label.length } : null;
+}
+function quotedTermSpanOf(text, shape) {
+    const opener = text.slice(0, QUOTED_TERM_OPENER_WINDOW).indexOf(shape.quote);
+    if (opener < 0)
+        return null;
+    const termStart = opener + 1;
+    const close = text.indexOf(shape.quote, termStart);
+    const closesAfterNonEmptyTerm = close > termStart;
+    if (!closesAfterNonEmptyTerm || close > LEAD_IN_MAX_CHARS)
+        return null;
+    return { start: termStart, end: close };
+}
+function nthIndexOf(text, search, occurrence) {
+    let at = -1;
+    for (let seen = 0; seen < occurrence; seen += 1) {
+        at = text.indexOf(search, at + 1);
+        if (at < 0)
+            return -1;
+    }
+    return at;
+}
+function spanThroughSameDelimiterCountOf(text, shape) {
+    const at = nthIndexOf(text, shape.delimiter, shape.occurrence);
+    if (at <= 0 || at > LEAD_IN_MAX_CHARS)
+        return null;
+    return { start: 0, end: at + shape.delimiter.length };
+}
+function spanBeforeDelimiterOf(text, shape) {
+    const end = leadInEndOf(text, shape.delimiter);
+    return end == null ? null : { start: 0, end };
+}
+export function labelLeadInSpanOf(text, shape) {
+    switch (shape.kind) {
+        case 'word':
+            return openingWordSpanOf(text, shape);
+        case 'quoted':
+            return quotedTermSpanOf(text, shape);
+        case 'inside':
+            return spanThroughSameDelimiterCountOf(text, shape);
+        case 'before':
+            return spanBeforeDelimiterOf(text, shape);
+    }
+}

package/dist/collaboration/write-admission.cjs

@@ -0,0 +1,185 @@
+'use strict';
+
+const WRITE_ADMISSION_PROTOCOL = 'superdoc.write-admission.v1';
+const DEFAULT_LEASE_TIMEOUT_MS = 10_000;
+const SYNC_MESSAGE_TYPE = 0;
+function readVarUint(bytes, start) {
+    let value = 0;
+    let shift = 0;
+    for (let index = start; index < bytes.length && shift < 35; index += 1) {
+        const byte = bytes[index] ?? 0;
+        value += (byte & 0x7f) * 2 ** shift;
+        if (byte < 0x80)
+            return { value, next: index + 1 };
+        shift += 7;
+    }
+    return null;
+}
+function isDocumentSyncMessage(update) {
+    const nameLength = readVarUint(update, 0);
+    if (!nameLength)
+        return false;
+    return readVarUint(update, nameLength.next + nameLength.value)?.value === SYNC_MESSAGE_TYPE;
+}
+function parseClientRequest(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const protocol = Reflect.get(parsed, 'protocol');
+    const type = Reflect.get(parsed, 'type');
+    const leaseId = Reflect.get(parsed, 'leaseId');
+    if (protocol !== WRITE_ADMISSION_PROTOCOL || typeof leaseId !== 'string' || leaseId.length === 0)
+        return null;
+    if (type !== 'begin' && type !== 'release')
+        return null;
+    return { type, leaseId };
+}
+function reply(connection, type, leaseId, reason) {
+    try {
+        connection.sendStateless(JSON.stringify({ protocol: WRITE_ADMISSION_PROTOCOL, type, leaseId, ...(reason ? { reason } : {}) }));
+    }
+    catch {
+        return;
+    }
+}
+function nextMacrotask() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function sameRequest(request, leaseId, socketId) {
+    return request.leaseId === leaseId && request.connection.socketId === socketId;
+}
+function createWriteAdmissionExtension(options = {}) {
+    const leaseTimeoutMs = options.leaseTimeoutMs ?? DEFAULT_LEASE_TIMEOUT_MS;
+    if (!Number.isFinite(leaseTimeoutMs) || leaseTimeoutMs <= 0) {
+        throw new RangeError('leaseTimeoutMs must be a positive number.');
+    }
+    const rooms = new Map();
+    const roomFor = (documentName) => {
+        const existing = rooms.get(documentName);
+        if (existing)
+            return existing;
+        const room = { holder: null, scheduled: null, waiting: [], heldWrites: [] };
+        rooms.set(documentName, room);
+        return room;
+    };
+    const forgetIdleRoom = (documentName, room) => {
+        if (room.holder || room.scheduled || room.waiting.length > 0 || room.heldWrites.length > 0)
+            return;
+        rooms.delete(documentName);
+    };
+    const isBusy = (room) => room.holder !== null || room.scheduled !== null || room.waiting.length > 0;
+    const grant = async (documentName, room, request) => {
+        const lease = { ...request, timer: null };
+        room.holder = lease;
+        await nextMacrotask();
+        if (room.holder !== lease)
+            return;
+        request.document.flush?.();
+        reply(request.connection, 'granted', request.leaseId);
+        lease.timer = setTimeout(() => {
+            if (room.holder !== lease)
+                return;
+            reply(request.connection, 'expired', request.leaseId);
+            endLease(documentName, room);
+        }, leaseTimeoutMs);
+    };
+    const scheduleNextGrant = (documentName, room) => {
+        const next = room.waiting.shift();
+        if (!next) {
+            forgetIdleRoom(documentName, room);
+            return;
+        }
+        room.scheduled = next;
+        void nextMacrotask().then(async () => {
+            const request = room.scheduled;
+            room.scheduled = null;
+            if (request)
+                await grant(documentName, room, request);
+            else
+                scheduleNextGrant(documentName, room);
+        });
+    };
+    const endLease = (documentName, room) => {
+        if (room.holder?.timer)
+            clearTimeout(room.holder.timer);
+        room.holder = null;
+        for (const resume of room.heldWrites.splice(0))
+            resume();
+        scheduleNextGrant(documentName, room);
+    };
+    return {
+        async beforeHandleMessage({ documentName, socketId, update }) {
+            const room = rooms.get(documentName);
+            if (!room || !isDocumentSyncMessage(update))
+                return;
+            while (room.holder && room.holder.connection.socketId !== socketId) {
+                await new Promise((resume) => room.heldWrites.push(resume));
+            }
+        },
+        async onStateless({ documentName, connection, document, payload }) {
+            const request = parseClientRequest(payload);
+            if (!request)
+                return;
+            const room = roomFor(documentName);
+            if (request.type === 'begin') {
+                if (connection.readOnly) {
+                    reply(connection, 'denied', request.leaseId, 'read-only connection');
+                    forgetIdleRoom(documentName, room);
+                    return;
+                }
+                const lease = { leaseId: request.leaseId, connection, document };
+                if (isBusy(room)) {
+                    room.waiting.push(lease);
+                    reply(connection, 'queued', request.leaseId);
+                    return;
+                }
+                await grant(documentName, room, lease);
+                return;
+            }
+            if (room.holder && sameRequest(room.holder, request.leaseId, connection.socketId)) {
+                reply(connection, 'released', request.leaseId);
+                endLease(documentName, room);
+                return;
+            }
+            if (room.scheduled && sameRequest(room.scheduled, request.leaseId, connection.socketId)) {
+                room.scheduled = null;
+                reply(connection, 'released', request.leaseId);
+                return;
+            }
+            const waitingIndex = room.waiting.findIndex((entry) => sameRequest(entry, request.leaseId, connection.socketId));
+            if (waitingIndex >= 0) {
+                room.waiting.splice(waitingIndex, 1);
+                reply(connection, 'released', request.leaseId);
+                forgetIdleRoom(documentName, room);
+                return;
+            }
+            reply(connection, 'expired', request.leaseId);
+            forgetIdleRoom(documentName, room);
+        },
+        async onDisconnect({ documentName, socketId }) {
+            const room = rooms.get(documentName);
+            if (!room)
+                return;
+            for (let index = room.waiting.length - 1; index >= 0; index -= 1) {
+                if (room.waiting[index]?.connection.socketId === socketId)
+                    room.waiting.splice(index, 1);
+            }
+            if (room.scheduled?.connection.socketId === socketId)
+                room.scheduled = null;
+            if (room.holder?.connection.socketId === socketId) {
+                endLease(documentName, room);
+                return;
+            }
+            forgetIdleRoom(documentName, room);
+        },
+    };
+}
+
+exports.WRITE_ADMISSION_PROTOCOL = WRITE_ADMISSION_PROTOCOL;
+exports.createWriteAdmissionExtension = createWriteAdmissionExtension;

package/dist/collaboration/write-admission.d.ts

@@ -0,0 +1,33 @@
+export declare const WRITE_ADMISSION_PROTOCOL = "superdoc.write-admission.v1";
+export interface WriteAdmissionConnection {
+    readonly socketId: string;
+    readonly readOnly?: boolean;
+    sendStateless(payload: string): void;
+}
+export interface WriteAdmissionDocument {
+    flush?(): void;
+}
+export interface WriteAdmissionMessagePayload {
+    readonly documentName: string;
+    readonly socketId: string;
+    readonly update: Uint8Array;
+}
+export interface WriteAdmissionStatelessPayload {
+    readonly documentName: string;
+    readonly connection: WriteAdmissionConnection;
+    readonly document: WriteAdmissionDocument;
+    readonly payload: string;
+}
+export interface WriteAdmissionDisconnectPayload {
+    readonly documentName: string;
+    readonly socketId: string;
+}
+export interface WriteAdmissionExtension {
+    beforeHandleMessage(payload: WriteAdmissionMessagePayload): Promise<void>;
+    onStateless(payload: WriteAdmissionStatelessPayload): Promise<void>;
+    onDisconnect(payload: WriteAdmissionDisconnectPayload): Promise<void>;
+}
+export interface WriteAdmissionOptions {
+    readonly leaseTimeoutMs?: number;
+}
+export declare function createWriteAdmissionExtension(options?: WriteAdmissionOptions): WriteAdmissionExtension;

package/dist/collaboration/write-admission.js

@@ -0,0 +1,180 @@
+export const WRITE_ADMISSION_PROTOCOL = 'superdoc.write-admission.v1';
+const DEFAULT_LEASE_TIMEOUT_MS = 10_000;
+const SYNC_MESSAGE_TYPE = 0;
+function readVarUint(bytes, start) {
+    let value = 0;
+    let shift = 0;
+    for (let index = start; index < bytes.length && shift < 35; index += 1) {
+        const byte = bytes[index] ?? 0;
+        value += (byte & 0x7f) * 2 ** shift;
+        if (byte < 0x80)
+            return { value, next: index + 1 };
+        shift += 7;
+    }
+    return null;
+}
+function isDocumentSyncMessage(update) {
+    const nameLength = readVarUint(update, 0);
+    if (!nameLength)
+        return false;
+    return readVarUint(update, nameLength.next + nameLength.value)?.value === SYNC_MESSAGE_TYPE;
+}
+function parseClientRequest(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const protocol = Reflect.get(parsed, 'protocol');
+    const type = Reflect.get(parsed, 'type');
+    const leaseId = Reflect.get(parsed, 'leaseId');
+    if (protocol !== WRITE_ADMISSION_PROTOCOL || typeof leaseId !== 'string' || leaseId.length === 0)
+        return null;
+    if (type !== 'begin' && type !== 'release')
+        return null;
+    return { type, leaseId };
+}
+function reply(connection, type, leaseId, reason) {
+    try {
+        connection.sendStateless(JSON.stringify({ protocol: WRITE_ADMISSION_PROTOCOL, type, leaseId, ...(reason ? { reason } : {}) }));
+    }
+    catch {
+        return;
+    }
+}
+function nextMacrotask() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function sameRequest(request, leaseId, socketId) {
+    return request.leaseId === leaseId && request.connection.socketId === socketId;
+}
+export function createWriteAdmissionExtension(options = {}) {
+    const leaseTimeoutMs = options.leaseTimeoutMs ?? DEFAULT_LEASE_TIMEOUT_MS;
+    if (!Number.isFinite(leaseTimeoutMs) || leaseTimeoutMs <= 0) {
+        throw new RangeError('leaseTimeoutMs must be a positive number.');
+    }
+    const rooms = new Map();
+    const roomFor = (documentName) => {
+        const existing = rooms.get(documentName);
+        if (existing)
+            return existing;
+        const room = { holder: null, scheduled: null, waiting: [], heldWrites: [] };
+        rooms.set(documentName, room);
+        return room;
+    };
+    const forgetIdleRoom = (documentName, room) => {
+        if (room.holder || room.scheduled || room.waiting.length > 0 || room.heldWrites.length > 0)
+            return;
+        rooms.delete(documentName);
+    };
+    const isBusy = (room) => room.holder !== null || room.scheduled !== null || room.waiting.length > 0;
+    const grant = async (documentName, room, request) => {
+        const lease = { ...request, timer: null };
+        room.holder = lease;
+        await nextMacrotask();
+        if (room.holder !== lease)
+            return;
+        request.document.flush?.();
+        reply(request.connection, 'granted', request.leaseId);
+        lease.timer = setTimeout(() => {
+            if (room.holder !== lease)
+                return;
+            reply(request.connection, 'expired', request.leaseId);
+            endLease(documentName, room);
+        }, leaseTimeoutMs);
+    };
+    const scheduleNextGrant = (documentName, room) => {
+        const next = room.waiting.shift();
+        if (!next) {
+            forgetIdleRoom(documentName, room);
+            return;
+        }
+        room.scheduled = next;
+        void nextMacrotask().then(async () => {
+            const request = room.scheduled;
+            room.scheduled = null;
+            if (request)
+                await grant(documentName, room, request);
+            else
+                scheduleNextGrant(documentName, room);
+        });
+    };
+    const endLease = (documentName, room) => {
+        if (room.holder?.timer)
+            clearTimeout(room.holder.timer);
+        room.holder = null;
+        for (const resume of room.heldWrites.splice(0))
+            resume();
+        scheduleNextGrant(documentName, room);
+    };
+    return {
+        async beforeHandleMessage({ documentName, socketId, update }) {
+            const room = rooms.get(documentName);
+            if (!room || !isDocumentSyncMessage(update))
+                return;
+            while (room.holder && room.holder.connection.socketId !== socketId) {
+                await new Promise((resume) => room.heldWrites.push(resume));
+            }
+        },
+        async onStateless({ documentName, connection, document, payload }) {
+            const request = parseClientRequest(payload);
+            if (!request)
+                return;
+            const room = roomFor(documentName);
+            if (request.type === 'begin') {
+                if (connection.readOnly) {
+                    reply(connection, 'denied', request.leaseId, 'read-only connection');
+                    forgetIdleRoom(documentName, room);
+                    return;
+                }
+                const lease = { leaseId: request.leaseId, connection, document };
+                if (isBusy(room)) {
+                    room.waiting.push(lease);
+                    reply(connection, 'queued', request.leaseId);
+                    return;
+                }
+                await grant(documentName, room, lease);
+                return;
+            }
+            if (room.holder && sameRequest(room.holder, request.leaseId, connection.socketId)) {
+                reply(connection, 'released', request.leaseId);
+                endLease(documentName, room);
+                return;
+            }
+            if (room.scheduled && sameRequest(room.scheduled, request.leaseId, connection.socketId)) {
+                room.scheduled = null;
+                reply(connection, 'released', request.leaseId);
+                return;
+            }
+            const waitingIndex = room.waiting.findIndex((entry) => sameRequest(entry, request.leaseId, connection.socketId));
+            if (waitingIndex >= 0) {
+                room.waiting.splice(waitingIndex, 1);
+                reply(connection, 'released', request.leaseId);
+                forgetIdleRoom(documentName, room);
+                return;
+            }
+            reply(connection, 'expired', request.leaseId);
+            forgetIdleRoom(documentName, room);
+        },
+        async onDisconnect({ documentName, socketId }) {
+            const room = rooms.get(documentName);
+            if (!room)
+                return;
+            for (let index = room.waiting.length - 1; index >= 0; index -= 1) {
+                if (room.waiting[index]?.connection.socketId === socketId)
+                    room.waiting.splice(index, 1);
+            }
+            if (room.scheduled?.connection.socketId === socketId)
+                room.scheduled = null;
+            if (room.holder?.connection.socketId === socketId) {
+                endLease(documentName, room);
+                return;
+            }
+            forgetIdleRoom(documentName, room);
+        },
+    };
+}