@book.dev/sdk 1.60.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Eliot Lim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @book.dev/sdk
+
+The shared contract for OpenBook — imported by the server, the desktop app, and
+the web shell so types and the HTTP API can never drift between them.
+
+Exports:
+
+- **Types** — `Page`/`StoredPage`, `PageMeta`, `PageInput`, `PageSnapshot`,
+  `ServerInfo`, plus `emptyPageSnapshot()`.
+- **`API`** — the route paths (`/api/pages`, `/api/pages/:id`, `/health`). The
+  server's router and the client both build URLs from these.
+- **`DataClient`** — the storage-agnostic interface the document UI depends on.
+- **`HttpDataClient`** — an isomorphic `fetch`-based implementation. The desktop
+  points it at its bundled local server; the web shell at a remote one.
+
+No React or Node dependencies — safe to import from any layer.
+
+```ts
+import {HttpDataClient, type PageInput} from '@book.dev/sdk';
+
+const client = new HttpDataClient('http://127.0.0.1:4319');
+const page = await client.savePage({data: {editorjs: {blocks: []}, values: [], names: []}});
+```

package/dist/account.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Client for the OpenBook account service (account.book.pub): the deep-link
+ * sign-in URL plus the settings-sync API. Identity + settings sync live in a
+ * service separate from the (single-tenant) data server, so this is its own
+ * small client — independent of {@link HttpDataClient}, authed by a bearer
+ * "device token" rather than the cookieless data API.
+ */
+/** Where the account service lives when nothing overrides it. */
+export declare const DEFAULT_ACCOUNT_URL = "https://account.book.pub";
+/** A dev/self-host override for the account base URL (localStorage), or null. */
+export declare function getAccountUrlOverride(): string | null;
+/** Set (or clear, with `null`) the account base URL override. */
+export declare function setAccountUrlOverride(url: string | null): void;
+/** The effective account base URL (override, else the production default). */
+export declare function resolveAccountUrl(): string;
+/** The user's synced blob plus the server's last-write timestamp. */
+export interface AccountSettings {
+    /** Whatever the app stored, or `{}` when nothing is synced yet. */
+    settings: Record<string, unknown>;
+    /** ISO timestamp of the last server write, or null if never written. */
+    updatedAt: string | null;
+}
+/** Thrown on a non-OK account response, so callers can branch on `status` (401). */
+export declare class AccountError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Talks to the account service's `/api/connect` (deep-link sign-in) and
+ * `/api/settings` (bearer-authed settings sync). Stateless: the caller holds the
+ * device token and passes it per request.
+ */
+export declare class AccountClient {
+    private readonly baseUrl;
+    constructor(baseUrl?: string);
+    /** The base URL this client targets (already trimmed). */
+    get origin(): string;
+    /**
+     * The browser URL that starts deep-link sign-in: it runs OAuth (if needed),
+     * mints a one-shot device token, and redirects to
+     * `redirectUri#token=<token>&state=<state>`. Open it in the system browser.
+     */
+    connectUrl(opts: {
+        redirectUri: string;
+        state: string;
+        name?: string;
+    }): string;
+    /** Pull the synced settings blob. Throws `AccountError(401)` if the token is
+     *  invalid or revoked. */
+    getSettings(token: string): Promise<AccountSettings>;
+    /** Push the settings blob; returns the new server timestamp for reconciliation. */
+    putSettings(token: string, settings: Record<string, unknown>): Promise<{
+        updatedAt: string;
+    }>;
+    /** Cheap token check (a settings GET): true if accepted, false on 401. */
+    validate(token: string): Promise<boolean>;
+}

package/dist/account.js

@@ -0,0 +1,104 @@
+/**
+ * Client for the OpenBook account service (account.book.pub): the deep-link
+ * sign-in URL plus the settings-sync API. Identity + settings sync live in a
+ * service separate from the (single-tenant) data server, so this is its own
+ * small client — independent of {@link HttpDataClient}, authed by a bearer
+ * "device token" rather than the cookieless data API.
+ */
+/** Where the account service lives when nothing overrides it. */
+export const DEFAULT_ACCOUNT_URL = 'https://account.book.pub';
+const ACCOUNT_URL_KEY = 'openbook.accountUrl';
+const trimUrl = (u) => u.trim().replace(/\/+$/, '');
+/** A dev/self-host override for the account base URL (localStorage), or null. */
+export function getAccountUrlOverride() {
+    if (typeof localStorage === 'undefined')
+        return null;
+    const v = localStorage.getItem(ACCOUNT_URL_KEY);
+    return v && v.trim() ? trimUrl(v) : null;
+}
+/** Set (or clear, with `null`) the account base URL override. */
+export function setAccountUrlOverride(url) {
+    if (typeof localStorage === 'undefined')
+        return;
+    if (url && url.trim())
+        localStorage.setItem(ACCOUNT_URL_KEY, trimUrl(url));
+    else
+        localStorage.removeItem(ACCOUNT_URL_KEY);
+}
+/** The effective account base URL (override, else the production default). */
+export function resolveAccountUrl() {
+    return getAccountUrlOverride() ?? DEFAULT_ACCOUNT_URL;
+}
+/** Thrown on a non-OK account response, so callers can branch on `status` (401). */
+export class AccountError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'AccountError';
+    }
+}
+/**
+ * Talks to the account service's `/api/connect` (deep-link sign-in) and
+ * `/api/settings` (bearer-authed settings sync). Stateless: the caller holds the
+ * device token and passes it per request.
+ */
+export class AccountClient {
+    constructor(baseUrl = resolveAccountUrl()) {
+        this.baseUrl = trimUrl(baseUrl);
+    }
+    /** The base URL this client targets (already trimmed). */
+    get origin() {
+        return this.baseUrl;
+    }
+    /**
+     * The browser URL that starts deep-link sign-in: it runs OAuth (if needed),
+     * mints a one-shot device token, and redirects to
+     * `redirectUri#token=<token>&state=<state>`. Open it in the system browser.
+     */
+    connectUrl(opts) {
+        const u = new URL('/api/connect', this.baseUrl + '/');
+        u.searchParams.set('redirect_uri', opts.redirectUri);
+        u.searchParams.set('state', opts.state);
+        if (opts.name)
+            u.searchParams.set('name', opts.name);
+        return u.toString();
+    }
+    /** Pull the synced settings blob. Throws `AccountError(401)` if the token is
+     *  invalid or revoked. */
+    async getSettings(token) {
+        const res = await fetch(new URL('/api/settings', this.baseUrl + '/'), {
+            headers: { authorization: `Bearer ${token}` },
+            cache: 'no-store',
+        });
+        if (!res.ok)
+            throw new AccountError(res.status, `account settings GET failed (${res.status})`);
+        const body = (await res.json());
+        return { settings: body.settings ?? {}, updatedAt: body.updatedAt ?? null };
+    }
+    /** Push the settings blob; returns the new server timestamp for reconciliation. */
+    async putSettings(token, settings) {
+        const res = await fetch(new URL('/api/settings', this.baseUrl + '/'), {
+            method: 'PUT',
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ settings }),
+            cache: 'no-store',
+        });
+        if (!res.ok)
+            throw new AccountError(res.status, `account settings PUT failed (${res.status})`);
+        const body = (await res.json());
+        return { updatedAt: body.updatedAt };
+    }
+    /** Cheap token check (a settings GET): true if accepted, false on 401. */
+    async validate(token) {
+        try {
+            await this.getSettings(token);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof AccountError && err.status === 401)
+                return false;
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=account.js.map

package/dist/account.js.map

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

package/dist/ai.d.ts

@@ -0,0 +1,264 @@
+/**
+ * The optional local-AI subsystem's shared contract. The server hosts a
+ * pluggable inference engine; these types describe its configuration,
+ * status, and request/response shapes. Everything degrades gracefully:
+ * with the engine off, lexical (BM25) note search still works and the AI
+ * editor affordances simply hide.
+ *
+ * Providers:
+ *  - `off`    — disabled (default).
+ *  - `mock`   — deterministic in-process engine (tests, demos).
+ *  - `llama`  — llama.cpp in-process via node-llama-cpp (GGUF models,
+ *               cross-platform: Metal/CUDA/Vulkan/CPU). The model file is
+ *               downloaded on demand into the server's models directory.
+ *  - `mlx`    — Apple-Silicon MLX through `mlx_lm.server`'s OpenAI-compatible
+ *               API (optionally auto-started by the server).
+ *  - `openai` — any OpenAI-compatible local endpoint (Ollama, LM Studio,
+ *               llama-server, vLLM…).
+ *  - `claude` — Anthropic's hosted Claude API (cloud; needs an API key). The
+ *               only provider that sends content off the machine.
+ */
+import type { StoredSuggestion } from './suggestions';
+export type AiProvider = 'off' | 'mock' | 'llama' | 'mlx' | 'openai' | 'claude';
+/**
+ * How hard the agent works on a turn. One knob maps (server-side, in one
+ * place — `ai/effort.ts`) to a thinking-token budget, sampling temperature,
+ * answer-token cap, and the agent's max tool-call steps.
+ */
+export type AiEffort = 'low' | 'med' | 'high';
+/** Per-provider connection settings. Every provider is configured independently
+ *  (in `AiConfig.providers`), so a workspace can have llama, mlx, openai and
+ *  claude all set up at once and switch between them per agent run. */
+export interface AiProviderSettings {
+    /** Model identifier: a GGUF filename (llama), an MLX model id (mlx), a served
+     *  model name (openai), or a Claude model id (e.g. `claude-sonnet-4-6`). */
+    model?: string;
+    /** Base URL for `mlx` / `openai` / `claude`. Defaults: mlx
+     *  http://127.0.0.1:8080, openai http://127.0.0.1:11434, claude
+     *  https://api.anthropic.com (override for a proxy/gateway). */
+    baseUrl?: string;
+    /** `claude` only: the Anthropic API key. */
+    apiKey?: string;
+    /** `mlx` only: spawn `mlx_lm.server` automatically when possible. */
+    autoStart?: boolean;
+}
+export interface AiConfig {
+    /** The default provider — used unless an agent run overrides it. */
+    provider: AiProvider;
+    /** Per-provider settings, so every provider can be configured at once. */
+    providers?: Partial<Record<AiProvider, AiProviderSettings>>;
+    /** Default agent effort (low/med/high). Falls back to 'med'. */
+    effort?: AiEffort;
+    /** Whether the agent surfaces its reasoning (collapsible). Default true. */
+    thinking?: boolean;
+    /** @deprecated use `providers[provider].model` */ model?: string;
+    /** @deprecated use `providers[provider].baseUrl` */ baseUrl?: string;
+    /** @deprecated use `providers[provider].apiKey` */ apiKey?: string;
+    /** @deprecated use `providers[provider].autoStart` */ autoStart?: boolean;
+}
+/**
+ * The effective settings for one provider: its `providers` entry, or — for a
+ * legacy config saved before per-provider settings existed — the flat top-level
+ * fields (which belonged to the then-active provider). Server engine creation
+ * and both UIs read settings through this, so old configs keep working.
+ */
+export declare function providerSettings(config: AiConfig, provider: AiProvider): AiProviderSettings;
+export interface AiStatus {
+    config: AiConfig;
+    /** The engine can generate text right now. */
+    ready: boolean;
+    /** The engine can embed text (semantic search reranking). */
+    embeddings: boolean;
+    /** Human-readable detail when not ready (missing model, endpoint down…). */
+    detail?: string;
+    /** Lexical search index state (always available, even with AI off). */
+    index: {
+        pages: number;
+        builtAt: string | null;
+    };
+    /** In-flight model download, when one is running. */
+    download?: {
+        url: string;
+        received: number;
+        total: number | null;
+        done: boolean;
+        error?: string;
+    };
+}
+export interface AiSearchResult {
+    pageId: string;
+    title: string;
+    /** Best-matching snippet of the page's text. */
+    snippet: string;
+    score: number;
+}
+export interface AiSearchResponse {
+    results: AiSearchResult[];
+    /** 'lexical' (BM25 only) or 'hybrid' (BM25 + embedding rerank). */
+    mode: 'lexical' | 'hybrid';
+}
+export interface AiTasksResponse {
+    tasks: string[];
+}
+/**
+ * Server-sent chunk of a streaming generation. `token` carries answer text;
+ * `reasoning` carries a model's thinking (from `<think>…</think>` or a
+ * scratchpad) routed to a separate channel so the UI renders it as a
+ * collapsible block and never as document content.
+ */
+export interface AiStreamEvent {
+    token?: string;
+    /** A reasoning/thinking token (kept out of the document). */
+    reasoning?: string;
+    done?: boolean;
+    error?: string;
+}
+export interface AgentChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * A single change the agent's write tools describe. Internal to the agent
+ * harness: a write tool builds one of these, the runner persists it as a
+ * {@link StoredSuggestion} (see `./suggestions`), and the suggestion — not this
+ * proposal — is what reaches the UI. Retained because the persisted
+ * suggestion's `payload` carries this `kind` (as `applyKind`), which the editor
+ * bridge replays to apply the change when a human accepts it.
+ */
+export interface AgentProposal {
+    /** Stable id within the turn's change set. */
+    id: string;
+    /** Which write tool produced it (drives how the bridge applies it). */
+    kind: 'set_kit_value' | 'set_db_cell' | 'update_block' | 'append_blocks' | 'set_page_theme' | 'delete_block' | 'set_block_props';
+    /** One-line human summary, e.g. `Set "budget" = 1200`. */
+    summary: string;
+    /** The page this change targets (for block/kit writes). */
+    pageId?: string;
+    /** Prior value, rendered for the diff card (optional). */
+    before?: string;
+    /** New value, rendered for the diff card. */
+    after?: string;
+    /** Structured payload the client bridge replays to mutate the CRDT/DB. */
+    payload: Record<string, unknown>;
+}
+/**
+ * One step of a multi-step interview the agent asks the user (the `ask_user`
+ * tool). Each step is one question; the user answers all steps, and the answers
+ * return to the agent as their next message.
+ */
+export interface InterviewStep {
+    id: string;
+    /** The question text. */
+    question: string;
+    /** Choices to pick from. Omit (or set `freeText`) for a typed answer. */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Allow selecting more than one option. */
+    multiple?: boolean;
+    /** Allow a typed answer (on its own, or in addition to the options). */
+    freeText?: boolean;
+}
+/** One streamed step of an agent run. */
+export type AgentChatEvent = {
+    type: 'tool';
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    name: string;
+    result: string;
+}
+/**
+ * The agent is asking to apply its edits DIRECTLY (without the review pane).
+ * The UI shows an allow/keep-reviewing prompt; granting it makes subsequent
+ * edits in this conversation apply immediately (see {@link apply}).
+ */
+ | {
+    type: 'permission_request';
+    summary: string;
+}
+/** The agent is asking the user a multi-step interview; answers return as the
+ *  user's next message. */
+ | {
+    type: 'interview';
+    title?: string;
+    steps: InterviewStep[];
+}
+/**
+ * Edits the agent applied DIRECTLY (the user granted edit access). The UI
+ * replays them through the editor bridge — the same path an accepted
+ * suggestion takes — and shows a short "applied" summary instead of a review
+ * card.
+ */
+ | {
+    type: 'apply';
+    proposals: AgentProposal[];
+}
+/**
+ * A chunk of the assistant's answer, streamed live as the model writes it
+ * (engines that support native tool-calling only; the JSON-protocol fallback
+ * surfaces the answer once, via {@link final}). The UI appends these to the
+ * in-progress answer bubble; the matching {@link final} carries the complete,
+ * authoritative text.
+ */
+ | {
+    type: 'token';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+}
+/**
+ * The agent's write tools persisted these suggestions for review (NOT
+ * applied). The UI shows a "proposed N suggestions — Review" card linking to
+ * the Review side pane; a human accepts/rejects each there.
+ */
+ | {
+    type: 'suggestions';
+    suggestions: StoredSuggestion[];
+} | {
+    type: 'final';
+    text: string;
+} | {
+    type: 'error';
+    error: string;
+};
+/** Options for one agent run. */
+export interface AgentChatOptions {
+    signal?: AbortSignal;
+    /** Override the default provider for this run (else the configured default). */
+    provider?: AiProvider;
+    /** Override the model for this run (else the provider's configured model). */
+    model?: string;
+    /** Override the configured default effort for this run. */
+    effort?: AiEffort;
+    /** Override whether reasoning is surfaced for this run. */
+    thinking?: boolean;
+    /** Names of prompt/recipe skills to inline into the system prompt. */
+    skills?: string[];
+    /** The page the user is currently viewing — its content is added as context. */
+    pageId?: string;
+    /** The user's current text selection — added as context on top of the message. */
+    selection?: string;
+    /** When true (the user granted edit access), the agent's edits apply directly
+     *  via an {@link AgentChatEvent.apply} event instead of becoming review
+     *  suggestions. Sticky for the conversation once granted. */
+    allowDirectEdits?: boolean;
+}
+/**
+ * A user-authored prompt/recipe skill: markdown instructions the agent can
+ * inline into its system prompt. No code — pure prompt engineering, editable
+ * by the user. Stored per-workspace (in the `settings` table under `ai.skills`;
+ * see `ai/skills.ts`).
+ */
+export interface AiSkill {
+    /** Stable slug (lowercase, hyphenated), unique per workspace. */
+    name: string;
+    /** Short one-line description shown in the catalogue. */
+    description: string;
+    /** The instructions inlined when the skill is invoked (markdown). */
+    instructions: string;
+    updatedAt?: string;
+}

package/dist/ai.js

@@ -0,0 +1,36 @@
+/**
+ * The optional local-AI subsystem's shared contract. The server hosts a
+ * pluggable inference engine; these types describe its configuration,
+ * status, and request/response shapes. Everything degrades gracefully:
+ * with the engine off, lexical (BM25) note search still works and the AI
+ * editor affordances simply hide.
+ *
+ * Providers:
+ *  - `off`    — disabled (default).
+ *  - `mock`   — deterministic in-process engine (tests, demos).
+ *  - `llama`  — llama.cpp in-process via node-llama-cpp (GGUF models,
+ *               cross-platform: Metal/CUDA/Vulkan/CPU). The model file is
+ *               downloaded on demand into the server's models directory.
+ *  - `mlx`    — Apple-Silicon MLX through `mlx_lm.server`'s OpenAI-compatible
+ *               API (optionally auto-started by the server).
+ *  - `openai` — any OpenAI-compatible local endpoint (Ollama, LM Studio,
+ *               llama-server, vLLM…).
+ *  - `claude` — Anthropic's hosted Claude API (cloud; needs an API key). The
+ *               only provider that sends content off the machine.
+ */
+/**
+ * The effective settings for one provider: its `providers` entry, or — for a
+ * legacy config saved before per-provider settings existed — the flat top-level
+ * fields (which belonged to the then-active provider). Server engine creation
+ * and both UIs read settings through this, so old configs keep working.
+ */
+export function providerSettings(config, provider) {
+    const entry = config.providers?.[provider];
+    if (entry)
+        return entry;
+    if (provider === config.provider) {
+        return { model: config.model, baseUrl: config.baseUrl, apiKey: config.apiKey, autoStart: config.autoStart };
+    }
+    return {};
+}
+//# sourceMappingURL=ai.js.map

package/dist/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgDH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAgB,EAAE,QAAoB;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,QAAQ,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,EAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAC,CAAC;IAC5G,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/backup.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Whole-space backup & restore contract. A backup is one JSON bundle of every
+ * live page (full data, nesting, database membership, properties) plus every
+ * database; emoji `icons` are added client-side (they live in localStorage).
+ *
+ * Restore has two modes:
+ *  - `copy` (default): import as new pages (fresh ids); names that clash with an
+ *    existing live page get a `" (imported)"` suffix. Never clobbers.
+ *  - `overwrite`: restore in place by id, replacing existing pages/databases. The
+ *    UI double-confirms, quoting how many existing pages will be replaced.
+ */
+import type { StoredPage } from './types';
+import type { StoredDatabase } from './database';
+export declare const BACKUP_VERSION = 1;
+export interface SpaceBackup {
+    version: number;
+    exportedAt: string;
+    pages: StoredPage[];
+    databases: StoredDatabase[];
+    /** pageId → emoji icon (added client-side; ignored by the server). */
+    icons?: Record<string, string>;
+}
+export type ImportMode = 'copy' | 'overwrite';
+/** What the client sends to restore: the (already-selected) pages/databases + mode. */
+export interface ImportRequest {
+    pages: StoredPage[];
+    databases: StoredDatabase[];
+    mode: ImportMode;
+}
+export interface ImportResult {
+    /** New pages created (copy mode, or overwrite of a not-yet-existing id). */
+    created: number;
+    /** Existing pages replaced (overwrite mode). */
+    overwritten: number;
+    /** Pages whose name was suffixed to avoid a clash (copy mode). */
+    renamed: number;
+    /** old page id → new page id (copy mode; identity in overwrite). */
+    idMap: Record<string, string>;
+}
+/**
+ * Pure: re-key a bundle for copy-mode import. Mints a fresh id for every page and
+ * database, remaps every internal reference (`parentId`, `databaseId`,
+ * `hostedDatabaseId`, a database's `pageId`, and `@`-mention `data-page-id`s
+ * embedded in block HTML), and returns the rewritten pages/databases plus the
+ * `oldId → newId` map. References to pages outside the bundle are left as-is.
+ * Unit-tested; the store layer adds DB-aware name de-duplication on top.
+ */
+export declare function remapBundle(pages: StoredPage[], databases: StoredDatabase[], newId: () => string): {
+    pages: StoredPage[];
+    databases: StoredDatabase[];
+    idMap: Record<string, string>;
+};

package/dist/backup.js

@@ -0,0 +1,35 @@
+export const BACKUP_VERSION = 1;
+/**
+ * Pure: re-key a bundle for copy-mode import. Mints a fresh id for every page and
+ * database, remaps every internal reference (`parentId`, `databaseId`,
+ * `hostedDatabaseId`, a database's `pageId`, and `@`-mention `data-page-id`s
+ * embedded in block HTML), and returns the rewritten pages/databases plus the
+ * `oldId → newId` map. References to pages outside the bundle are left as-is.
+ * Unit-tested; the store layer adds DB-aware name de-duplication on top.
+ */
+export function remapBundle(pages, databases, newId) {
+    const idMap = {};
+    for (const p of pages)
+        idMap[p.id] = newId();
+    const dbMap = {};
+    for (const d of databases)
+        dbMap[d.id] = newId();
+    const remapMentions = (data) => {
+        let json = JSON.stringify(data);
+        for (const [oldId, nid] of Object.entries(idMap)) {
+            json = json.split(`data-page-id=\\"${oldId}\\"`).join(`data-page-id=\\"${nid}\\"`);
+        }
+        return JSON.parse(json);
+    };
+    const remappedPages = pages.map((p) => ({
+        ...p,
+        id: idMap[p.id],
+        parentId: p.parentId && idMap[p.parentId] ? idMap[p.parentId] : null,
+        databaseId: p.databaseId && dbMap[p.databaseId] ? dbMap[p.databaseId] : null,
+        hostedDatabaseId: p.hostedDatabaseId && dbMap[p.hostedDatabaseId] ? dbMap[p.hostedDatabaseId] : null,
+        data: remapMentions(p.data),
+    }));
+    const remappedDbs = databases.map((d) => ({ ...d, id: dbMap[d.id], pageId: idMap[d.pageId] ?? d.pageId }));
+    return { pages: remappedPages, databases: remappedDbs, idMap };
+}
+//# sourceMappingURL=backup.js.map

package/dist/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AA+BhC;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,KAAmB,EACnB,SAA2B,EAC3B,KAAmB;IAEnB,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;IAC7C,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;IAEjD,MAAM,aAAa,GAAG,CAAC,IAAwB,EAAsB,EAAE;QACrE,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC,CAAC;QACrF,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAChD,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtC,GAAG,CAAC;QACJ,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACpE,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;QAC5E,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,IAAI,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI;QACpG,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;KAC5B,CAAC,CAAC,CAAC;IACJ,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAC,CAAC,CAAC,CAAC;IACzG,OAAO,EAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAC,CAAC;AAC/D,CAAC"}

package/dist/bookFolder.d.ts

@@ -0,0 +1,44 @@
+import type { StoredPage } from './types';
+import type { StoredDatabase } from './database';
+/**
+ * Whole-space → folder-of-files serialisation, shared by every "dump my books
+ * to a folder" surface: the desktop's native folder export and the web app's
+ * File System Access export both call {@link spaceToBookFiles}, and the layout
+ * is byte-compatible with the server's on-disk {@link BookMirror} (OB-134) so a
+ * folder written by one can be re-imported by the other.
+ *
+ * The layout is exactly two levels deep — `<book-folder>/<page>.html` — where
+ * the book folder is named from the page's *root* ancestor. Each page renders to
+ * the human-readable `.book.html` format (`pageToBookHtml`); alongside them a
+ * single {@link SPACE_BUNDLE_FILE} carries the full structured bundle so an
+ * import is lossless (parent/position/properties and databases survive, which
+ * the flat HTML files alone don't capture).
+ */
+/** A relative file within the chosen folder (POSIX `/` separators). */
+export interface BookFolderFile {
+    path: string;
+    contents: string;
+}
+/** Everything in a space, as returned by `DataClient.exportSpace`. */
+export interface SpaceSnapshot {
+    pages: StoredPage[];
+    databases: StoredDatabase[];
+}
+/** Lossless structured sidecar, parsed back by {@link parseBookFolder}. */
+export declare const SPACE_BUNDLE_FILE = "openbook.space.json";
+/**
+ * Serialise a space to its on-disk files. By default includes the lossless
+ * {@link SPACE_BUNDLE_FILE}; pass `includeBundle: false` for the human-readable
+ * HTML files only.
+ */
+export declare function spaceToBookFiles(snapshot: SpaceSnapshot, opts?: {
+    includeBundle?: boolean;
+}): BookFolderFile[];
+/**
+ * Reconstruct a space from a folder's files. Prefers the lossless
+ * {@link SPACE_BUNDLE_FILE} when present; otherwise falls back to parsing the
+ * `.html` files into a flat list of pages (no databases, no nesting — the most
+ * a human-readable folder can recover). Returns `null` if nothing parseable was
+ * found, so the caller can surface "not an OpenBook folder".
+ */
+export declare function parseBookFolder(files: BookFolderFile[]): SpaceSnapshot | null;