@book.dev/sdk 1.60.0

package/dist/forwarding/tunnelClient.js

@@ -0,0 +1,206 @@
+// The reusable tunnel client the desktop embeds (Tauri webview/sidecar, Node, or
+// any runtime with global `WebSocket` + `fetch`). It dials OUT to the relay,
+// completes the double-gated attach (signs the relay's nonce with the site key +
+// presents the account ticket), then serves inbound requests against the local
+// OpenBook data server, streaming responses — including SSE — back up the tunnel.
+//
+// No Node-only APIs, so it also runs inside the Tauri webview. On the desktop the
+// `fetchImpl` is the IPC transport, so forwarded traffic reaches the portless
+// local server without opening a TCP port.
+import { globalFetch } from '../client';
+import { buildRelayAttachMessage } from './challenge';
+import { signWithSiteKey } from './siteKey';
+import { decodeBody, decodeControl, encodeBody, encodeControl } from './tunnelProtocol';
+export class TunnelClient {
+    constructor(opts) {
+        this.opts = opts;
+        this.status = 'offline';
+        this.backoff = 500;
+        this.stopped = false;
+        this.inflight = new Map();
+        this.fetchImpl = opts.fetchImpl ?? globalFetch;
+        this.WS = opts.webSocketImpl ?? WebSocket;
+    }
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.setStatus('offline');
+        this.ws?.close();
+    }
+    get currentStatus() {
+        return this.status;
+    }
+    setStatus(next) {
+        if (next !== this.status) {
+            this.status = next;
+            this.opts.onStatus?.(next);
+        }
+    }
+    connect() {
+        this.setStatus(this.backoff > 500 ? 'reconnecting' : 'connecting');
+        void this.dial();
+    }
+    /** Mint a fresh ticket, then open the relay socket with it. Minting per dial is
+     *  what keeps reconnects working — a reused ticket expires and attach fails. */
+    async dial() {
+        let info;
+        try {
+            info = await this.opts.ticketProvider();
+        }
+        catch {
+            // Couldn't mint (account unreachable / token expired) — back off and retry.
+            this.scheduleReconnect();
+            return;
+        }
+        if (this.stopped)
+            return;
+        this.ticket = info.ticket;
+        const ws = new this.WS(info.relayWsUrl);
+        ws.binaryType = 'arraybuffer';
+        this.ws = ws;
+        ws.onmessage = (ev) => void this.onMessage(ev.data);
+        ws.onclose = () => this.onClose();
+        ws.onerror = () => ws.close();
+    }
+    onClose() {
+        for (const f of this.inflight.values())
+            f.controller.abort();
+        this.inflight.clear();
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.stopped) {
+            this.setStatus('offline');
+            return;
+        }
+        this.setStatus('reconnecting');
+        const delay = this.backoff;
+        this.backoff = Math.min(this.backoff * 2, this.opts.maxBackoffMs ?? 30000);
+        setTimeout(() => {
+            if (!this.stopped)
+                this.connect();
+        }, delay);
+    }
+    sendControl(frame) {
+        this.ws?.send(encodeControl(frame));
+    }
+    /** Pause while the socket's send buffer is backed up, so streaming a large
+     *  response to a slow viewer can't grow memory without bound. */
+    async drain() {
+        const ws = this.ws;
+        if (!ws)
+            return;
+        const HIGH_WATER = 4 * 1024 * 1024; // 4 MB
+        while (ws.readyState === ws.OPEN && ws.bufferedAmount > HIGH_WATER) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    async onMessage(data) {
+        if (typeof data === 'string') {
+            const frame = decodeControl(data);
+            if (frame)
+                await this.onControl(frame);
+            return;
+        }
+        const { id, chunk } = decodeBody(new Uint8Array(data));
+        this.inflight.get(id)?.bodyController?.enqueue(chunk);
+    }
+    async onControl(frame) {
+        switch (frame.t) {
+            case 'challenge': {
+                if (!this.ticket) {
+                    this.ws?.close();
+                    break;
+                }
+                const signature = await signWithSiteKey(this.opts.privateKey, buildRelayAttachMessage(frame.nonce));
+                this.sendControl({ t: 'attach', ticket: this.ticket, signature });
+                break;
+            }
+            case 'ready':
+                this.backoff = 500;
+                this.setStatus('online');
+                break;
+            case 'error':
+                this.ws?.close();
+                break;
+            case 'ping':
+                this.sendControl({ t: 'pong' });
+                break;
+            case 'req':
+                void this.handleRequest(frame);
+                break;
+            case 'end': {
+                const f = this.inflight.get(frame.id);
+                f?.bodyController?.close();
+                if (f)
+                    f.bodyController = undefined;
+                break;
+            }
+            case 'abort': {
+                this.inflight.get(frame.id)?.controller.abort();
+                this.inflight.delete(frame.id);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    async handleRequest(frame) {
+        const { id } = frame;
+        const controller = new AbortController();
+        const inflight = { controller };
+        this.inflight.set(id, inflight);
+        const hasBody = frame.method !== 'GET' && frame.method !== 'HEAD';
+        let body;
+        if (hasBody) {
+            body = new ReadableStream({
+                start: (c) => {
+                    inflight.bodyController = c;
+                },
+            });
+        }
+        const url = `${this.opts.localOrigin.replace(/\/$/, '')}${frame.path}`;
+        const headers = new Headers();
+        for (const [k, v] of frame.headers) {
+            const lk = k.toLowerCase();
+            if (lk === 'host' || lk === 'connection' || lk === 'content-length')
+                continue;
+            headers.append(k, v);
+        }
+        const init = { method: frame.method, headers, signal: controller.signal };
+        if (hasBody) {
+            init.body = body;
+            init.duplex = 'half';
+        }
+        try {
+            const res = await this.fetchImpl(url, init);
+            const resHeaders = [];
+            res.headers.forEach((value, key) => resHeaders.push([key, value]));
+            this.sendControl({ t: 'res', id, status: res.status, headers: resHeaders });
+            if (res.body) {
+                const reader = res.body.getReader();
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value && value.byteLength) {
+                        this.ws?.send(encodeBody(id, value));
+                        await this.drain(); // backpressure: don't outrun a slow consumer
+                    }
+                }
+            }
+            this.sendControl({ t: 'end', id });
+        }
+        catch {
+            if (!controller.signal.aborted)
+                this.sendControl({ t: 'abort', id, reason: 'local fetch failed' });
+        }
+        finally {
+            this.inflight.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=tunnelClient.js.map

package/dist/forwarding/tunnelClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnelClient.js","sourceRoot":"","sources":["../../src/forwarding/tunnelClient.ts"],"names":[],"mappings":"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"}

package/dist/forwarding/tunnelProtocol.d.ts

@@ -0,0 +1,45 @@
+export type ControlFrame = {
+    t: 'challenge';
+    nonce: string;
+} | {
+    t: 'attach';
+    ticket: string;
+    signature: string;
+    clientInfo?: string;
+} | {
+    t: 'ready';
+    siteId: string;
+} | {
+    t: 'error';
+    message: string;
+} | {
+    t: 'req';
+    id: number;
+    method: string;
+    path: string;
+    headers: [string, string][];
+} | {
+    t: 'res';
+    id: number;
+    status: number;
+    headers: [string, string][];
+} | {
+    t: 'end';
+    id: number;
+} | {
+    t: 'abort';
+    id: number;
+    reason?: string;
+} | {
+    t: 'ping';
+} | {
+    t: 'pong';
+};
+export declare function encodeControl(frame: ControlFrame): string;
+export declare function decodeControl(data: string): ControlFrame | null;
+/** Binary body frame: [id: uint32 BE][...bytes]. */
+export declare function encodeBody(id: number, chunk: Uint8Array): Uint8Array<ArrayBuffer>;
+export declare function decodeBody(buf: Uint8Array): {
+    id: number;
+    chunk: Uint8Array;
+};

package/dist/forwarding/tunnelProtocol.js

@@ -0,0 +1,29 @@
+// The wire protocol for the reverse tunnel between a desktop and its relay. One
+// WebSocket carries many concurrent HTTP exchanges, multiplexed by a numeric
+// request id. Control frames are JSON (WS text); body chunks are binary (WS
+// binary) prefixed with the id, so large payloads and SSE stream without base64
+// overhead. Shared by the relay (open.book.pub) and the tunnel client below.
+export function encodeControl(frame) {
+    return JSON.stringify(frame);
+}
+export function decodeControl(data) {
+    try {
+        const f = JSON.parse(data);
+        return f && typeof f.t === 'string' ? f : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Binary body frame: [id: uint32 BE][...bytes]. */
+export function encodeBody(id, chunk) {
+    const out = new Uint8Array(4 + chunk.byteLength);
+    new DataView(out.buffer).setUint32(0, id >>> 0, false);
+    out.set(chunk, 4);
+    return out;
+}
+export function decodeBody(buf) {
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    return { id: view.getUint32(0, false), chunk: buf.subarray(4) };
+}
+//# sourceMappingURL=tunnelProtocol.js.map

package/dist/forwarding/tunnelProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnelProtocol.js","sourceRoot":"","sources":["../../src/forwarding/tunnelProtocol.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,4EAA4E;AAC5E,gFAAgF;AAChF,6EAA6E;AAiB7E,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAiB,CAAC;QAC3C,OAAO,CAAC,IAAI,OAAQ,CAAmB,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,KAAiB;IACtD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IACvD,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAClB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACtE,OAAO,EAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAC,CAAC;AAChE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { PageSnapshot, PageMeta, StoredPage, PageInput, ServerInfo, ServerControls } from './types';
+export { emptyPageSnapshot } from './types';
+export { API, type ApiError } from './routes';
+export type { DataClient, PageSubscription, FetchLike, LiveSourceLike, HttpDataClientOptions } from './client';
+export { HttpDataClient } from './client';
+export { ForwardingClient, TunnelClient, MemoryKeyStore, mintSiteKeypair, signWithSiteKey, type KeyStore, type SiteIdentity, type ForwardingClientOptions, type TunnelStatus, } from './forwarding';
+export type { DatabasePropertyType, NumberFormat, NumberDisplay, StatusGroup, RollupFunction, RollupConfig, RelationCardinality, DatabaseSelectOption, DatabaseProperty, DateRange, LocationValue, PropertyGroup, RowTemplate, DatabaseViewType, ChartAggregate, SummaryType, FilterOperator, FilterConjunction, DatabaseFilter, DatabaseFilterGroup, FilterNode, SortDirection, DatabaseSort, DatabaseView, DatabaseMetric, ColorRule, DatabaseSchema, StoredDatabase, DatabaseInput, DatabaseUpdate, DatabaseRow, RowInput, RowUpdate, RowGroup, ChartDatum, ChartSeries, ChartSegment, ChartGroup, ChartMatrix, DateSpan, GraphNode, GraphEdge, DependencyGraph, InverseUpdate, RowTreeNode, } from './database';
+export { TITLE_PROPERTY_ID, SELECT_COLORS, NO_VALUE_GROUP, STATUS_GROUPS, RELATIVE_DATE_OPS, projectExports, rowValue, matchesFilter, rowMatchesCondition, applyView, viewFilterRoot, isFilterGroup, shortId, defaultDatabaseSchema, defaultView, defaultStatusOptions, removeProperty, formatNumber, formatUniqueId, numberProgress, groupRows, groupRowsBy, groupRowsByParent, PARENT_GROUP_ID, NO_PARENT_GROUP, aggregateRows, aggregateMatrix, CHART_TOTAL_SERIES, summarizeColumn, dateStart, dateEnd, parseDay, rowDateSpan, rowLocation, asLocation, dependencyGraph, syncInverseUpdates, relationSides, buildRowTree, flattenRowTree, isImageUrl, firstImageUrl, coverImageUrl, } from './database';
+export { evaluateFormula, formulaReferences, FormulaError, type FormulaValue, type FormulaResolver, } from './formula';
+export { OWNER_PROPERTY_ID, VERIFICATION_PROPERTY_ID, BACKLINKS_PROPERTY_ID, THEME_PROPERTY_ID, COVER_PROPERTY_ID, FONTS_PROPERTY_ID, ICON_PROPERTY_ID, FULLWIDTH_PROPERTY_ID, SYSTEM_PAGE_PROPERTIES, isVerified, verificationExpired, isVerificationActive, makeVerification, extractMentionIds, propertiesReferencePage, type VerificationValue, } from './pageProperties';
+export { getServerUrlOverride, setServerUrlOverride, getServerTokenOverride, setServerTokenOverride, isMixedContentBlocked } from './connection';
+export { AccountClient, AccountError, DEFAULT_ACCOUNT_URL, getAccountUrlOverride, setAccountUrlOverride, resolveAccountUrl, type AccountSettings, } from './account';
+export { snapshotText, paragraphBlocks, textSnapshot, appendTextToSnapshot, appendBlocksToSnapshot, type AppendBlock } from './content';
+export { snapshotBlocks, contentHash, computeBlockMtimes, stampSnapshotMtimes, latestBlockMtime, type BlockDigest, } from './mtime';
+export { pageToBookHtml, bookHtmlToPage, readBookHtmlMeta, slugify, type BookPageRecord, } from './bookfile';
+export { spaceToBookFiles, parseBookFolder, SPACE_BUNDLE_FILE, type BookFolderFile, type SpaceSnapshot, } from './bookFolder';
+export { canonicalDigest, generateRegistryKeys, signPlugin, verifyPlugin, validateManifest, OPENBOOK_REGISTRY, type PluginManifest, type PluginAgentTool, type PluginPackage, type PluginSignature, type StoredPlugin, } from './plugins';
+export { buildSampleDocument, seedSampleDocument, SAMPLE_DOCUMENT_NAME } from './sampleDocument';
+export type { CommentRun, SuggestionAuthorKind, SuggestionKind, SuggestionStatus, SuggestionTarget, StoredSuggestion, SuggestionInput, SuggestionUpdate, StoredComment, CommentInput, } from './suggestions';
+export { PAGE_TEMPLATES, instantiateTemplate, type PageTemplate } from './templates';
+export { BACKUP_VERSION, remapBundle, type SpaceBackup, type ImportMode, type ImportRequest, type ImportResult, } from './backup';
+export type { AgentChatEvent, AgentChatMessage, AgentChatOptions, AgentProposal, InterviewStep, AiProvider, AiConfig, AiProviderSettings, AiEffort, AiSkill, AiStatus, AiSearchResult, AiSearchResponse, AiTasksResponse, AiStreamEvent, } from './ai';
+export { providerSettings } from './ai';

package/dist/index.js

@@ -0,0 +1,19 @@
+export { emptyPageSnapshot } from './types';
+export { API } from './routes';
+export { HttpDataClient } from './client';
+export { ForwardingClient, TunnelClient, MemoryKeyStore, mintSiteKeypair, signWithSiteKey, } from './forwarding';
+export { TITLE_PROPERTY_ID, SELECT_COLORS, NO_VALUE_GROUP, STATUS_GROUPS, RELATIVE_DATE_OPS, projectExports, rowValue, matchesFilter, rowMatchesCondition, applyView, viewFilterRoot, isFilterGroup, shortId, defaultDatabaseSchema, defaultView, defaultStatusOptions, removeProperty, formatNumber, formatUniqueId, numberProgress, groupRows, groupRowsBy, groupRowsByParent, PARENT_GROUP_ID, NO_PARENT_GROUP, aggregateRows, aggregateMatrix, CHART_TOTAL_SERIES, summarizeColumn, dateStart, dateEnd, parseDay, rowDateSpan, rowLocation, asLocation, dependencyGraph, syncInverseUpdates, relationSides, buildRowTree, flattenRowTree, isImageUrl, firstImageUrl, coverImageUrl, } from './database';
+export { evaluateFormula, formulaReferences, FormulaError, } from './formula';
+export { OWNER_PROPERTY_ID, VERIFICATION_PROPERTY_ID, BACKLINKS_PROPERTY_ID, THEME_PROPERTY_ID, COVER_PROPERTY_ID, FONTS_PROPERTY_ID, ICON_PROPERTY_ID, FULLWIDTH_PROPERTY_ID, SYSTEM_PAGE_PROPERTIES, isVerified, verificationExpired, isVerificationActive, makeVerification, extractMentionIds, propertiesReferencePage, } from './pageProperties';
+export { getServerUrlOverride, setServerUrlOverride, getServerTokenOverride, setServerTokenOverride, isMixedContentBlocked } from './connection';
+export { AccountClient, AccountError, DEFAULT_ACCOUNT_URL, getAccountUrlOverride, setAccountUrlOverride, resolveAccountUrl, } from './account';
+export { snapshotText, paragraphBlocks, textSnapshot, appendTextToSnapshot, appendBlocksToSnapshot } from './content';
+export { snapshotBlocks, contentHash, computeBlockMtimes, stampSnapshotMtimes, latestBlockMtime, } from './mtime';
+export { pageToBookHtml, bookHtmlToPage, readBookHtmlMeta, slugify, } from './bookfile';
+export { spaceToBookFiles, parseBookFolder, SPACE_BUNDLE_FILE, } from './bookFolder';
+export { canonicalDigest, generateRegistryKeys, signPlugin, verifyPlugin, validateManifest, OPENBOOK_REGISTRY, } from './plugins';
+export { buildSampleDocument, seedSampleDocument, SAMPLE_DOCUMENT_NAME } from './sampleDocument';
+export { PAGE_TEMPLATES, instantiateTemplate } from './templates';
+export { BACKUP_VERSION, remapBundle, } from './backup';
+export { providerSettings } from './ai';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,iBAAiB,EAAC,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAC,GAAG,EAAgB,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAC,cAAc,EAAC,MAAM,UAAU,CAAC;AACxC,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,GAKhB,MAAM,cAAc,CAAC;AAgDtB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,aAAa,EACb,OAAO,EACP,qBAAqB,EACrB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,cAAc,EACd,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,UAAU,EACV,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,GAGb,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,GAExB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAC,oBAAoB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,qBAAqB,EAAC,MAAM,cAAc,CAAC;AAC/I,OAAO,EACL,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,GAElB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAmB,MAAM,WAAW,CAAC;AACtI,OAAO,EACL,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,GAEjB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,OAAO,GAER,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAGlB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,GAMlB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,mBAAmB,EAAE,kBAAkB,EAAE,oBAAoB,EAAC,MAAM,kBAAkB,CAAC;AAa/F,OAAO,EAAC,cAAc,EAAE,mBAAmB,EAAoB,MAAM,aAAa,CAAC;AACnF,OAAO,EACL,cAAc,EACd,WAAW,GAKZ,MAAM,UAAU,CAAC;AAkBlB,OAAO,EAAC,gBAAgB,EAAC,MAAM,MAAM,CAAC"}

package/dist/mtime.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-block modification tracking — the change/version signal the on-disk book
+ * mirror, the external-change watcher, and conflict detection all rely on
+ * (OB-133). A page snapshot can carry an `mtimes` array of `[blockId, ISO]`
+ * pairs; the server stamps it on every write so an unchanged block keeps its old
+ * timestamp while a changed or newly-inserted one is restamped to "now".
+ *
+ * Pure and isomorphic (no DOM, no Node): it reads whichever block projection a
+ * page uses — the CRDT block editor's JSON projection (`blockdoc.blocks`) or the
+ * legacy EditorJS blocks (`editorjs.blocks`) — so the same logic runs on the
+ * server write path and in unit tests.
+ */
+import type { PageSnapshot } from './types';
+/** A top-level block reduced to the bits that define its identity + content. */
+export interface BlockDigest {
+    /** Stable block id (used to match the same block across two snapshot versions). */
+    id: string;
+    /** Block type (`paragraph`, `heading`, …). */
+    type: string;
+    /** A short, deterministic hash of the block's full content (incl. children). */
+    hash: string;
+}
+/**
+ * FNV-1a (32-bit) over a string, returned as 8 hex chars. Fast, dependency-free,
+ * and stable across platforms — exactly what change-detection needs (a rare
+ * collision only means a missed restamp, never corruption).
+ */
+export declare function contentHash(input: string): string;
+/**
+ * The ordered list of a snapshot's top-level blocks, each as a {@link BlockDigest}.
+ * Reads the block-editor projection for `editor: 'blocks'` pages and the EditorJS
+ * blocks otherwise. A block with no explicit id falls back to a positional id so
+ * an unchanged document still matches itself across versions.
+ */
+export declare function snapshotBlocks(data: PageSnapshot | null | undefined): BlockDigest[];
+/**
+ * Compute the `[blockId, ISO]` mtimes for `next`, carrying forward each block's
+ * timestamp from `prev` when its content is unchanged and stamping `nowIso` for
+ * new or changed blocks. The result preserves `next`'s block order. Pages with
+ * no `prev` (a fresh insert) get every block stamped `nowIso`.
+ */
+export declare function computeBlockMtimes(prev: PageSnapshot | null | undefined, next: PageSnapshot, nowIso: string): Array<[string, string]>;
+/**
+ * Return `next` with its `mtimes` stamped relative to `prev`. The server calls
+ * this on every content write so a page snapshot always describes when each of
+ * its blocks last changed. Idempotent when the document is unchanged: re-stamping
+ * an identical snapshot keeps every timestamp.
+ */
+export declare function stampSnapshotMtimes(prev: PageSnapshot | null | undefined, next: PageSnapshot, nowIso?: string): PageSnapshot;
+/** The most recent block mtime in a snapshot, or `null` if none are stamped. */
+export declare function latestBlockMtime(data: PageSnapshot | null | undefined): string | null;

package/dist/mtime.js

@@ -0,0 +1,84 @@
+/**
+ * FNV-1a (32-bit) over a string, returned as 8 hex chars. Fast, dependency-free,
+ * and stable across platforms — exactly what change-detection needs (a rare
+ * collision only means a missed restamp, never corruption).
+ */
+export function contentHash(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        h ^= input.charCodeAt(i);
+        // h *= 16777619, kept in 32-bit range via the >>> 0 below.
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/** Stable JSON: object keys sorted so `{a,b}` and `{b,a}` hash identically. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+/**
+ * The ordered list of a snapshot's top-level blocks, each as a {@link BlockDigest}.
+ * Reads the block-editor projection for `editor: 'blocks'` pages and the EditorJS
+ * blocks otherwise. A block with no explicit id falls back to a positional id so
+ * an unchanged document still matches itself across versions.
+ */
+export function snapshotBlocks(data) {
+    if (!data)
+        return [];
+    const blockdoc = data.blockdoc;
+    if (data.editor === 'blocks' && Array.isArray(blockdoc?.blocks)) {
+        return blockdoc.blocks.map((b, i) => ({
+            id: typeof b.id === 'string' && b.id ? b.id : `b${i}`,
+            type: typeof b.type === 'string' ? b.type : 'unknown',
+            hash: contentHash(stableStringify({ type: b.type, text: b.text, props: b.props, children: b.children })),
+        }));
+    }
+    const blocks = data.editorjs?.blocks ?? [];
+    return blocks.map((b, i) => ({
+        id: typeof b.id === 'string' && b.id ? b.id : `b${i}`,
+        type: typeof b.type === 'string' ? b.type : 'unknown',
+        hash: contentHash(stableStringify({ type: b.type, data: b.data })),
+    }));
+}
+/**
+ * Compute the `[blockId, ISO]` mtimes for `next`, carrying forward each block's
+ * timestamp from `prev` when its content is unchanged and stamping `nowIso` for
+ * new or changed blocks. The result preserves `next`'s block order. Pages with
+ * no `prev` (a fresh insert) get every block stamped `nowIso`.
+ */
+export function computeBlockMtimes(prev, next, nowIso) {
+    const prevBlocks = snapshotBlocks(prev);
+    const prevHash = new Map();
+    for (const b of prevBlocks)
+        prevHash.set(b.id, b.hash);
+    const prevMtime = new Map(prev?.mtimes ?? []);
+    return snapshotBlocks(next).map((b) => {
+        const unchanged = prevHash.get(b.id) === b.hash && prevMtime.has(b.id);
+        return [b.id, unchanged ? prevMtime.get(b.id) : nowIso];
+    });
+}
+/**
+ * Return `next` with its `mtimes` stamped relative to `prev`. The server calls
+ * this on every content write so a page snapshot always describes when each of
+ * its blocks last changed. Idempotent when the document is unchanged: re-stamping
+ * an identical snapshot keeps every timestamp.
+ */
+export function stampSnapshotMtimes(prev, next, nowIso = new Date().toISOString()) {
+    return { ...next, mtimes: computeBlockMtimes(prev, next, nowIso) };
+}
+/** The most recent block mtime in a snapshot, or `null` if none are stamped. */
+export function latestBlockMtime(data) {
+    let latest = null;
+    for (const [, iso] of data?.mtimes ?? []) {
+        if (latest === null || iso > latest)
+            latest = iso;
+    }
+    return latest;
+}
+//# sourceMappingURL=mtime.js.map

package/dist/mtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtime.js","sourceRoot":"","sources":["../src/mtime.ts"],"names":[],"mappings":"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"}

package/dist/pageProperties.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Built-in **page properties** — structured metadata every page carries,
+ * modelled with the same {@link DatabaseProperty} vocabulary as databases so
+ * the two presentations are duals:
+ *
+ *  - A standalone page shows them in a wiki-style *properties panel* under its
+ *    title (Owner, Verification, Backlinks).
+ *  - A collection of pages gathered into a database shows the very same values
+ *    as *columns*, because the property ids below are stable and reserved — a
+ *    column whose id is {@link OWNER_PROPERTY_ID} reads the identical
+ *    `page.properties[OWNER_PROPERTY_ID]` the panel edits.
+ *
+ * Owner and Verification are stored on the page (`page.properties`). Backlinks
+ * are *computed* from the link graph (which pages mention this one), so they
+ * are never stored — see {@link extractMentionIds}.
+ */
+import type { PageSnapshot } from './types';
+import type { DatabaseProperty } from './database';
+/** Reserved, stable id for the Owner (person) property. */
+export declare const OWNER_PROPERTY_ID = "sys_owner";
+/** Reserved, stable id for the Verification property. */
+export declare const VERIFICATION_PROPERTY_ID = "sys_verification";
+/** Reserved, stable id for the Backlinks (computed) property. */
+export declare const BACKLINKS_PROPERTY_ID = "sys_backlinks";
+/**
+ * Reserved ids for a page's **appearance**, stored on `page.properties` so a
+ * page's theme / cover / typefaces travel with the document (sync across
+ * devices) rather than living only in the local browser. They are appearance
+ * metadata — not panel/column properties — so they are intentionally NOT part
+ * of {@link SYSTEM_PAGE_PROPERTIES}.
+ */
+export declare const THEME_PROPERTY_ID = "sys_theme";
+export declare const COVER_PROPERTY_ID = "sys_cover";
+export declare const FONTS_PROPERTY_ID = "sys_fonts";
+/** The page's emoji icon (a string). Projected into {@link PageMeta} so the
+ *  sidebar/tabs/mentions resolve it from the page list, not a per-page fetch. */
+export declare const ICON_PROPERTY_ID = "sys_icon";
+/** The page's full-width layout flag (a boolean; absent = centered column). */
+export declare const FULLWIDTH_PROPERTY_ID = "sys_fullwidth";
+/** The stored shape of a Verification property value. */
+export interface VerificationValue {
+    verified: boolean;
+    /** Display name of who verified it; `null` when unknown. */
+    by?: string | null;
+    /** ISO timestamp the page was verified. */
+    at?: string | null;
+    /** ISO timestamp the verification lapses; absent/`null` = never expires. */
+    expiresAt?: string | null;
+}
+/** The built-in properties every page carries, in panel order. */
+export declare const SYSTEM_PAGE_PROPERTIES: DatabaseProperty[];
+/** True when a stored value represents a verified page (ignoring expiry). */
+export declare function isVerified(value: unknown): boolean;
+/** True when a verified page's verification has lapsed (expiry is in the past). */
+export declare function verificationExpired(value: unknown, nowMs?: number): boolean;
+/** True when a page is verified AND its verification has not lapsed. */
+export declare function isVerificationActive(value: unknown, nowMs?: number): boolean;
+/**
+ * A verification value stamped as verified now (the caller supplies the time).
+ * `expiresAtIso` sets an expiry; omit/`null` for a verification that never
+ * lapses.
+ */
+export declare function makeVerification(by: string | null, atIso: string, expiresAtIso?: string | null): VerificationValue;
+/**
+ * Pure: the set of page ids this snapshot links to, by scanning the EditorJS
+ * blocks for inline mention anchors (`<a … data-page-id="…">`). Order-preserving
+ * and de-duplicated — the out-edges of one page in the backlink graph.
+ *
+ * Works on both the raw HTML form (`data-page-id="id"`) and the JSON-escaped
+ * form (`data-page-id=\"id\"`) that appears once the document is serialised, so
+ * it can run over a parsed snapshot or a stringified one alike.
+ */
+/**
+ * Pure: does a page's stored `properties` reference `id`? True when any property
+ * value equals `id`, or `id` is an element of an array-valued property (a
+ * `relation`). This lets the backlink graph count relation links — set on a
+ * row's properties — alongside inline `@`-mentions in the document.
+ */
+export declare function propertiesReferencePage(properties: Record<string, unknown> | null | undefined, id: string): boolean;
+export declare function extractMentionIds(snapshot: Pick<PageSnapshot, 'editorjs'>): string[];