@book.dev/sdk 1.66.0 → 1.68.0

package/dist/import.js

@@ -0,0 +1,312 @@
+/**
+ * The **format-agnostic import core** — the spine every importer (Markdown,
+ * HTML, Notion, …) targets. A parser's only job is to turn its source format
+ * into an {@link ImportedDoc}; this module then writes that IR into the
+ * workspace through the *existing* data paths, so importers never touch the
+ * store, the CRDT, or the wire protocol directly.
+ *
+ * Two writers, picked by the document's size/shape (see {@link chooseStrategy}):
+ *
+ *  - **Strategy A — {@link writeViaCreateApis}** drives `savePage` /
+ *    `createDatabase` / `createRow` directly, exactly like the template gallery
+ *    (see `templates.ts`). Best for a single page / small tree: it streams
+ *    creates and resolves parent links as it goes, with no whole-bundle staging.
+ *
+ *  - **Strategy B — {@link writeViaBundle}** maps the whole IR into a backup
+ *    bundle (`{pages, databases}` native records) and hands it to
+ *    `importSpace(…, mode:'copy')`. That inherits — for free — the server's
+ *    id-remap, `@`-mention link-rewrite, name de-dup, and idempotent-replay
+ *    machinery (`remapBundle` / `importBundle`), plus the Restore dialog on the
+ *    UI side. Best for a multi-page / database tree.
+ *
+ * **Assets (v1 decision).** A real asset store is a separate epic; until then an
+ * image becomes a *placeholder* that preserves the original `ref` + `alt` rather
+ * than being silently dropped — {@link imagePlaceholderBlock} for body content,
+ * {@link imagePlaceholderCell} for a database cell. The "never silently drop
+ * content" guarantee that the inbound HTML/EditorJS converters follow (see
+ * `ui/blockeditor/model.ts`) holds end-to-end through import.
+ *
+ * **Why the SDK.** The writers speak `DataClient` and the backup bundle, both
+ * SDK-owned; the block payload is the editor's plain JSON projection, which the
+ * SDK already handles structurally (`content.ts`, `mtime.ts`). {@link
+ * ImportedBlock} is the structural mirror of `@book.dev/ui`'s `BlockJSON`: a
+ * parser's real `BlockJSON` (built with the UI's `htmlToBlocks` / `htmlToRuns`
+ * helpers) is assignable straight into this IR — without the SDK taking a UI
+ * dependency. The assignment is one-way *by design*: `ImportedBlock.id` is
+ * OPTIONAL (import omits ids; the editor mints them on load via its
+ * `jsonToNewBlock`), so the reverse — treating an `ImportedBlock` as a
+ * `BlockJSON` — intentionally does not hold.
+ */
+import { emptyPageSnapshot } from './types';
+import { ICON_PROPERTY_ID } from './pageProperties';
+import { contentHash } from './mtime';
+// ── Image-placeholder shim (v1 assets decision) ──────────────────────────────
+/**
+ * The `props.kind` marker on a placeholder block, and the `props` key the
+ * structured {@link ImportedAsset} is stashed under. A future real-asset epic
+ * can query for `props[IMAGE_PLACEHOLDER_PROP]` to find and rehydrate every
+ * placeholder a past import left behind.
+ */
+export const IMAGE_PLACEHOLDER_KIND = 'import-image-placeholder';
+export const IMAGE_PLACEHOLDER_PROP = 'importedAsset';
+/**
+ * Turn an image asset into a real, visible **callout** block that preserves the
+ * original ref (as a clickable link run) and the alt/title text — never a
+ * silent drop. The structured {@link ImportedAsset} is stashed in `props` so the
+ * asset can be rehydrated later. Mirrors the "honest visible marker" pattern the
+ * EditorJS migration uses for not-yet-supported blocks (`model.ts`). Pure: the
+ * id is derived from the asset, so the same image always yields the same block
+ * id (deterministic re-imports, no module-global counter).
+ */
+export function imagePlaceholderBlock(asset) {
+    const label = asset.alt?.trim() || asset.title?.trim() || asset.ref;
+    return {
+        id: `imp_img_${contentHash(`${asset.ref}|${asset.alt ?? ''}`)}`,
+        type: 'callout',
+        text: [{ t: '🖼 ' }, { t: label, a: { a: asset.ref } }],
+        props: {
+            variant: 'info',
+            [IMAGE_PLACEHOLDER_PROP]: {
+                kind: IMAGE_PLACEHOLDER_KIND,
+                assetKind: asset.kind,
+                ref: asset.ref,
+                ...(asset.alt ? { alt: asset.alt } : {}),
+                ...(asset.title ? { title: asset.title } : {}),
+            },
+        },
+    };
+}
+/**
+ * The placeholder *cell* value for a `files` / `url` database property: the
+ * original ref, so the cell still renders and resolves the image (`firstImageUrl`
+ * / `coverImageUrl` read it). Alt, when present, is preserved at block
+ * granularity via {@link imagePlaceholderBlock} on the row's body.
+ */
+export function imagePlaceholderCell(asset) {
+    return asset.ref;
+}
+// ── Snapshot construction ────────────────────────────────────────────────────
+/**
+ * Wrap a block list in a page snapshot the block editor reads — the same shape
+ * `templates.ts` ships (`editor:'blocks'`, blocks in `blockdoc.blocks`, NO CRDT
+ * `update`). The editor rebuilds the Y.Doc from the JSON projection on load
+ * (`decodeSnapshot` falls back to it), so importers never touch yjs.
+ */
+export function importedBlocksToSnapshot(blocks) {
+    return {
+        editorjs: { blocks: [] },
+        values: [],
+        names: [],
+        editor: 'blocks',
+        blockdoc: { blocks },
+    };
+}
+const rowSnapshot = (row) => row.blocks && row.blocks.length > 0 ? importedBlocksToSnapshot(row.blocks) : emptyPageSnapshot();
+const pageIsSimple = (page) => !page.database && !(page.children && page.children.length > 0);
+/**
+ * Pick a writer by the document's shape: a lone, childless, database-less page
+ * → **Strategy A** (stream creates); anything bigger — multiple pages, nested
+ * children, or a hosted database — → **Strategy B** (stage a bundle and let the
+ * server remap/rewrite/dedup the whole tree at once).
+ */
+export function chooseStrategy(doc) {
+    return doc.pages.length === 1 && pageIsSimple(doc.pages[0]) ? 'create' : 'bundle';
+}
+/**
+ * Does this block tree hold an image placeholder (a callout carrying
+ * {@link IMAGE_PLACEHOLDER_PROP})? Used by the writers to record which landed
+ * pages the post-import rehydration pass must revisit (see
+ * {@link ImportWriteResult.placeholderPageIds}). Recurses container children.
+ */
+export function blocksHaveImagePlaceholder(blocks) {
+    for (const b of blocks ?? []) {
+        if (b.props?.[IMAGE_PLACEHOLDER_PROP])
+            return true;
+        if (b.children && blocksHaveImagePlaceholder(b.children))
+            return true;
+    }
+    return false;
+}
+/** How many `(imported)`-suffixed names to try before falling back to untitled. */
+const NAME_SUFFIX_ATTEMPTS = 5;
+/**
+ * Run a name-bearing create (page or row) with a retry ladder so an import
+ * **never hard-fails on a single record**. Names are not unique (server
+ * migration 0015), so the plain title normally lands on the first attempt; the
+ * `"<title> (imported)"` / numbered candidates remain as a retry path for
+ * transient failures — consistent with the server's copy-mode ` (imported)`
+ * suffix so Strategy A and B stay convergent — with an untitled record as the
+ * last resort. A genuine persistent failure surfaces once the untitled
+ * fallback also throws.
+ */
+async function createDeduped(title, create) {
+    const candidates = [];
+    if (title) {
+        candidates.push(title, `${title} (imported)`);
+        for (let n = 2; n <= NAME_SUFFIX_ATTEMPTS; n += 1)
+            candidates.push(`${title} (imported) ${n}`);
+    }
+    for (const name of candidates) {
+        try {
+            return await create(name);
+        }
+        catch {
+            // Name taken (or transient) — step the suffix and retry the next candidate.
+        }
+    }
+    // Empty title, or every suffix exhausted: land it untitled rather than abort.
+    return create(null);
+}
+/**
+ * **Strategy A.** Write the tree by driving the create APIs directly, the way
+ * the template gallery does: each page is `savePage`d (parent resolved from the
+ * already-created ancestor), a hosted database is `createDatabase`d on it, and
+ * every row — including nested sub-items — is `createRow`d. Each create runs
+ * through the {@link createDeduped} retry ladder so one failing record degrades
+ * (suffixed, then untitled) instead of aborting the import. Returns the ids it
+ * minted, in creation order.
+ */
+export async function writeViaCreateApis(client, doc, opts = {}) {
+    const result = { strategy: 'create', pageIds: [], databaseIds: [], rowIds: [], placeholderPageIds: [] };
+    const writeRows = async (databaseId, rows, parentRowId) => {
+        for (const row of rows) {
+            const data = row.blocks && row.blocks.length > 0 ? importedBlocksToSnapshot(row.blocks) : undefined;
+            const stored = await createDeduped(row.title, (name) => client.createRow(databaseId, { name, properties: row.properties, data, parentId: parentRowId }));
+            result.rowIds.push(stored.id);
+            if (blocksHaveImagePlaceholder(row.blocks))
+                result.placeholderPageIds.push(stored.id);
+            if (row.children && row.children.length > 0)
+                await writeRows(databaseId, row.children, stored.id);
+        }
+    };
+    const writePage = async (page, parentId) => {
+        const stored = await createDeduped(page.title, (name) => client.savePage({ name, data: importedBlocksToSnapshot(page.blocks), parentId }));
+        result.pageIds.push(stored.id);
+        if (blocksHaveImagePlaceholder(page.blocks))
+            result.placeholderPageIds.push(stored.id);
+        if (page.icon)
+            await client.setPageProperties(stored.id, { [ICON_PROPERTY_ID]: page.icon });
+        if (page.database) {
+            const db = await client.createDatabase({
+                pageId: stored.id,
+                name: page.database.name ?? page.title ?? null,
+                schema: page.database.schema,
+            });
+            result.databaseIds.push(db.id);
+            await writeRows(db.id, page.database.rows, null);
+        }
+        for (const child of page.children ?? [])
+            await writePage(child, stored.id);
+    };
+    for (const page of doc.pages)
+        await writePage(page, opts.parentId ?? null);
+    return result;
+}
+/**
+ * Map an {@link ImportedDoc} to a copy-mode backup bundle: native `StoredPage` /
+ * `StoredDatabase` records with internally-consistent **synthetic** ids (the
+ * server re-keys every id on import). The host page's `hostedDatabaseId`, the
+ * database's `pageId`, each row's `databaseId`, and sub-item / child `parentId`
+ * links are all wired up so `remapBundle` can rewrite them as one graph. Pure —
+ * no client, no I/O — so it is directly unit-testable.
+ */
+export function buildImportBundle(doc, opts = {}) {
+    const now = opts.now ?? new Date().toISOString();
+    let counter = 0;
+    const newId = opts.newId ?? (() => `imp_${++counter}`);
+    const pages = [];
+    const databases = [];
+    const emitRows = (rows, databaseId, parentRowId) => {
+        for (const row of rows) {
+            // A parser may pin a stable id (so cross-page mentions resolve); else mint one.
+            const id = row.id ?? newId();
+            pages.push({
+                id,
+                name: row.title || null,
+                data: rowSnapshot(row),
+                hostedDatabaseId: null,
+                databaseId,
+                parentId: parentRowId,
+                properties: row.properties ?? {},
+                deletedAt: null,
+                createdAt: now,
+                updatedAt: now,
+            });
+            if (row.children && row.children.length > 0)
+                emitRows(row.children, databaseId, id);
+        }
+    };
+    const emitPage = (page, parentId) => {
+        // A parser may pin a stable id (so cross-page mentions resolve); else mint one.
+        const id = page.id ?? newId();
+        const hostedDatabaseId = page.database ? newId() : null;
+        pages.push({
+            id,
+            name: page.title || null,
+            data: importedBlocksToSnapshot(page.blocks),
+            hostedDatabaseId,
+            databaseId: null,
+            parentId,
+            properties: page.icon ? { [ICON_PROPERTY_ID]: page.icon } : {},
+            deletedAt: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+        if (page.database && hostedDatabaseId) {
+            databases.push({
+                id: hostedDatabaseId,
+                pageId: id,
+                name: page.database.name ?? page.title ?? null,
+                schema: page.database.schema,
+                createdAt: now,
+                updatedAt: now,
+            });
+            emitRows(page.database.rows, hostedDatabaseId, null);
+        }
+        for (const child of page.children ?? [])
+            emitPage(child, id);
+    };
+    // Bundle roots land at the top level: copy-mode remap nulls any parent not in
+    // the bundle, so an external `parentId` would be dropped anyway — don't set it.
+    for (const page of doc.pages)
+        emitPage(page, null);
+    return { pages, databases };
+}
+/**
+ * **Strategy B.** Build the copy-mode bundle ({@link buildImportBundle}) and
+ * hand it to `importSpace`, inheriting the server's id-remap, link-rewrite,
+ * name-dedup, and idempotent-replay handling. Surfaces the server's
+ * {@link ImportResult} (and its `idMap` as the new page ids).
+ */
+export async function writeViaBundle(client, doc, opts = {}) {
+    const { pages, databases } = buildImportBundle(doc, opts);
+    const req = { pages, databases, mode: 'copy' };
+    const importResult = await client.importSpace(req);
+    // Map the bundle pages that carry an image placeholder to their server-assigned
+    // ids (via the id-map) so the post-import rehydration pass revisits only those.
+    const placeholderPageIds = [];
+    for (const page of pages) {
+        const blocks = page.data.blockdoc?.blocks;
+        if (!blocksHaveImagePlaceholder(blocks))
+            continue;
+        const landed = importResult.idMap[page.id];
+        if (landed)
+            placeholderPageIds.push(landed);
+    }
+    return {
+        strategy: 'bundle',
+        pageIds: Object.values(importResult.idMap),
+        databaseIds: [],
+        rowIds: [],
+        importResult,
+        placeholderPageIds,
+    };
+}
+/**
+ * Import a document, picking the writer by {@link chooseStrategy}. The single
+ * entry point a parser calls once it has built its {@link ImportedDoc}.
+ */
+export function importDoc(client, doc, opts = {}) {
+    return chooseStrategy(doc) === 'create' ? writeViaCreateApis(client, doc, opts) : writeViaBundle(client, doc, opts);
+}
+//# sourceMappingURL=import.js.map

package/dist/import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.js","sourceRoot":"","sources":["../src/import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,EAAC,iBAAiB,EAAqC,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAgHpC,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAoB;IACxD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC;IACpE,OAAO;QACL,EAAE,EAAE,WAAW,WAAW,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,EAAE;QAC/D,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,CAAC,EAAC,CAAC,EAAE,KAAK,EAAC,EAAE,EAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAC,CAAC,EAAE,KAAK,CAAC,GAAG,EAAC,EAAC,CAAC;QACjD,KAAK,EAAE;YACL,OAAO,EAAE,MAAM;YACf,CAAC,sBAAsB,CAAC,EAAE;gBACxB,IAAI,EAAE,sBAAsB;gBAC5B,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAC,GAAG,EAAE,KAAK,CAAC,GAAG,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7C;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAoB;IACvD,OAAO,KAAK,CAAC,GAAG,CAAC;AACnB,CAAC;AAED,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAuB;IAC9D,OAAO;QACL,QAAQ,EAAE,EAAC,MAAM,EAAE,EAAE,EAAC;QACtB,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,QAAQ;QAChB,QAAQ,EAAE,EAAC,MAAM,EAAC;KACnB,CAAC;AACJ,CAAC;AAED,MAAM,WAAW,GAAG,CAAC,GAAgB,EAAgB,EAAE,CACrD,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;AAMnG,MAAM,YAAY,GAAG,CAAC,IAAkB,EAAW,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAErH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpF,CAAC;AAoDD;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAmC;IAC5E,KAAK,MAAM,CAAC,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,sBAAsB,CAAC;YAAE,OAAO,IAAI,CAAC;QACnD,IAAI,CAAC,CAAC,QAAQ,IAAI,0BAA0B,CAAC,CAAC,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mFAAmF;AACnF,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B;;;;;;;;;GASG;AACH,KAAK,UAAU,aAAa,CAAI,KAAa,EAAE,MAA2C;IACxF,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,KAAK,EAAE,CAAC;QACV,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,KAAK,aAAa,CAAC,CAAC;QAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,oBAAoB,EAAE,CAAC,IAAI,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,eAAe,CAAC,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;QAC9E,CAAC;IACH,CAAC;IACD,8EAA8E;IAC9E,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAyB,EACzB,GAAgB,EAChB,OAAsB,EAAE;IAExB,MAAM,MAAM,GAAsB,EAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAC,CAAC;IAEzH,MAAM,SAAS,GAAG,KAAK,EAAE,UAAkB,EAAE,IAAmB,EAAE,WAA0B,EAAiB,EAAE;QAC7G,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACpG,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACrD,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,EAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAC,CAAC,CAC9F,CAAC;YACF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,0BAA0B,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtF,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,KAAK,EAAE,IAAkB,EAAE,QAAuB,EAAiB,EAAE;QACrF,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACtD,MAAM,CAAC,QAAQ,CAAC,EAAC,IAAI,EAAE,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAC,CAAC,CAC/E,CAAC;QACF,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACvF,IAAI,IAAI,CAAC,IAAI;YAAE,MAAM,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,EAAE,EAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC,IAAI,EAAC,CAAC,CAAC;QAC1F,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC;gBACrC,MAAM,EAAE,MAAM,CAAC,EAAE;gBACjB,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;gBAC9C,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;aAC7B,CAAC,CAAC;YACH,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC/B,MAAM,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACnD,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK;QAAE,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAgB,EAChB,OAAsB,EAAE;IAExB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAEvD,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAqB,EAAE,CAAC;IAEvC,MAAM,QAAQ,GAAG,CAAC,IAAmB,EAAE,UAAkB,EAAE,WAA0B,EAAQ,EAAE;QAC7F,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,gFAAgF;YAChF,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,IAAI,KAAK,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE;gBACF,IAAI,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;gBACvB,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC;gBACtB,gBAAgB,EAAE,IAAI;gBACtB,UAAU;gBACV,QAAQ,EAAE,WAAW;gBACrB,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,EAAE;gBAChC,SAAS,EAAE,IAAI;gBACf,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,GAAG;aACf,CAAC,CAAC;YACH,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,IAAkB,EAAE,QAAuB,EAAQ,EAAE;QACrE,gFAAgF;QAChF,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC;YACT,EAAE;YACF,IAAI,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;YACxB,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC;YAC3C,gBAAgB;YAChB,UAAU,EAAE,IAAI;YAChB,QAAQ;YACR,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC,IAAI,EAAC,CAAC,CAAC,CAAC,EAAE;YAC5D,SAAS,EAAE,IAAI;YACf,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;SACf,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,QAAQ,IAAI,gBAAgB,EAAE,CAAC;YACtC,SAAS,CAAC,IAAI,CAAC;gBACb,EAAE,EAAE,gBAAgB;gBACpB,MAAM,EAAE,EAAE;gBACV,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;gBAC9C,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;gBAC5B,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,GAAG;aACf,CAAC,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC;IAEF,8EAA8E;IAC9E,gFAAgF;IAChF,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK;QAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO,EAAC,KAAK,EAAE,SAAS,EAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAyB,EACzB,GAAgB,EAChB,OAAsB,EAAE;IAExB,MAAM,EAAC,KAAK,EAAE,SAAS,EAAC,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,GAAG,GAAkB,EAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAC,CAAC;IAC5D,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnD,gFAAgF;IAChF,gFAAgF;IAChF,MAAM,kBAAkB,GAAa,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAI,IAAI,CAAC,IAAI,CAAC,QAAmD,EAAE,MAAM,CAAC;QACtF,IAAI,CAAC,0BAA0B,CAAC,MAAM,CAAC;YAAE,SAAS;QAClD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,MAAM;YAAE,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC;QAC1C,WAAW,EAAE,EAAE;QACf,MAAM,EAAE,EAAE;QACV,YAAY;QACZ,kBAAkB;KACnB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,MAAyB,EACzB,GAAgB,EAChB,OAAsB,EAAE;IAExB,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AACtH,CAAC"}

package/dist/importAssets.d.ts

@@ -0,0 +1,167 @@
+/**
+ * **Import asset rehydration (Assets A4).** Turns the image *placeholders* the
+ * importers emit (see `import.ts` {@link imagePlaceholderBlock}) into real,
+ * rendering `image` blocks — the payoff of OB-ASSETS: an imported picture comes
+ * through for real, not as a callout.
+ *
+ * Two seams, because the bytes arrive two very different ways:
+ *
+ *  - **URL / `data:` images (Markdown · HTML).** These already carry a loadable
+ *    source, so no upload is needed — {@link rehydrateImageUrls} rewrites the
+ *    placeholder to an `image` block whose `src` is the original URL (kept as a
+ *    link) or the inline `data:` URL (which the editor's A2 on-load migration
+ *    then stores). Pure, DOM-free, no client — runnable *before* the doc is
+ *    landed, so the page lands already-correct.
+ *
+ *  - **Embedded bytes (Notion zip · opt-in URL download).** A Notion export holds
+ *    every image's bytes inside the zip; there is no URL to render. So — *after*
+ *    the page is created (we need its id to ref the asset's read-gate) —
+ *    {@link rehydrateStoredImages} resolves each placeholder's `ref` to bytes,
+ *    `putAsset`s them, and rewrites the placeholder to an `image` block holding
+ *    the returned `assetId`. Content-addressed dedup makes a re-import idempotent.
+ *
+ * **Never lose the reference.** If the bytes are missing, over the 10 MiB cap, or
+ * the upload fails, the block degrades rather than dropping: a loadable URL is
+ * preserved as a URL `image` block; anything else keeps its original placeholder
+ * (ref + alt intact). A big import's uploads are processed with bounded
+ * concurrency so the UI is never blocked, and only pages that actually contain a
+ * placeholder are re-read/re-saved (the writers report them in
+ * `ImportWriteResult.placeholderPageIds`).
+ */
+import { type ImportedBlock, type ImportedDoc } from './import';
+import type { PageInput, StoredPage } from './types';
+/** The `image` block type — the native picture block the editor ships (A0/A2). */
+export declare const IMAGE_BLOCK_TYPE = "image";
+/**
+ * Hard cap on an uploaded asset (10 MiB) — matches the server's asset bodyLimit
+ * (`app.ts` `ASSET_MAX_BYTES`). An import image over this stays a placeholder
+ * rather than failing the whole import.
+ */
+export declare const DEFAULT_MAX_ASSET_BYTES: number;
+/** Is this an `http(s)` URL — a picture the `image` block can render from `src`? */
+export declare const isHttpUrl: (s: string) => boolean;
+/** Is this a `data:` URL — inline bytes the editor can render (and A2 migrates)? */
+export declare const isDataUrlRef: (s: string) => boolean;
+/** Guess an image mime from a ref's file extension (defaults to octet-stream). */
+export declare function mimeFromRef(ref: string): string;
+/** The structured asset preserved on a placeholder block (see `imagePlaceholderBlock`). */
+interface PlaceholderMeta {
+    ref?: string;
+    alt?: string;
+    title?: string;
+}
+/** Read the {@link PlaceholderMeta} off a block, or `undefined` if it isn't a placeholder. */
+export declare function imagePlaceholderMeta(block: ImportedBlock): PlaceholderMeta | undefined;
+/**
+ * Rewrite an image *placeholder* into a real `image` block, carrying either the
+ * uploaded `assetId` or a renderable `src`. The placeholder's `alt` becomes the
+ * image alt, its `title` the caption; the deterministic block id is kept so the
+ * rewrite is stable across re-imports.
+ */
+export declare function importedImageBlock(placeholder: ImportedBlock, target: {
+    assetId: string;
+} | {
+    src: string;
+}): ImportedBlock;
+/** Options for {@link rehydrateImageUrls}. */
+export interface RehydrateUrlOptions {
+    /**
+     * Rewrite an `http(s)` image placeholder into a URL `image` block (default
+     * `true`). Set `false` to *keep* it a placeholder so a later
+     * {@link rehydrateStoredImages} pass can download the bytes into the store
+     * (the opt-in "download into workspace" flow).
+     */
+    preserveHttpUrls?: boolean;
+    /**
+     * Rewrite a `data:` placeholder into an inline `image` block when its decoded
+     * size is within this many bytes (default 10 MiB). An over-cap `data:` image
+     * stays a placeholder so the CRDT never carries a huge base64 blob.
+     */
+    maxDataBytes?: number;
+}
+/**
+ * **Pass 1 (pure).** Rewrite every image placeholder whose ref is a directly
+ * loadable source — an `http(s)` URL (preserved as a link) or an in-cap `data:`
+ * URL — into a real `image` block, throughout the doc (pages, children, database
+ * rows). No client, no I/O: run this on the IR *before* landing it so the page
+ * arrives already carrying real images. Idempotent (an `image` block isn't a
+ * placeholder, so a re-run is a no-op).
+ */
+export declare function rehydrateImageUrls(doc: ImportedDoc, opts?: RehydrateUrlOptions): ImportedDoc;
+/** An asset's raw bytes plus its mime, as resolved for upload. */
+export interface AssetBytes {
+    bytes: Uint8Array;
+    mime: string;
+}
+/**
+ * Resolve a placeholder's `ref` to its bytes for upload, or `null` when the
+ * bytes are unavailable (missing / not fetchable). May be async (a network
+ * fetch). {@link notionAssetResolver} and {@link urlAssetResolver} build one.
+ */
+export type ImportAssetResolver = (ref: string) => AssetBytes | null | Promise<AssetBytes | null>;
+/** The slice of the data client {@link rehydrateStoredImages} drives. */
+export interface RehydrateStoredClient {
+    getPage(id: string): Promise<StoredPage | null>;
+    savePage(input: PageInput): Promise<StoredPage>;
+    putAsset(bytes: Uint8Array, mime: string, pageId: string): Promise<{
+        id: string;
+    }>;
+}
+/** Options for {@link rehydrateStoredImages}. */
+export interface RehydrateStoredOptions {
+    /** Skip (keep as placeholder) any image whose bytes exceed this (default 10 MiB). */
+    maxAssetBytes?: number;
+    /**
+     * Max total in-flight uploads at once (default 4) — a single shared budget
+     * across every page, so an image-dense page can't fan out N uploads and flood
+     * the socket. Also caps how many pages are walked concurrently.
+     */
+    concurrency?: number;
+    /** Progress callback: pages processed / total (so the UI can show a live count). */
+    onProgress?: (done: number, total: number) => void;
+}
+/** What a stored-image pass did, for honest reporting. */
+export interface RehydrateStoredResult {
+    /** Placeholders uploaded to the store and rewritten to an `assetId` image block. */
+    uploaded: number;
+    /** Placeholders degraded to a URL `image` block (bytes unavailable but ref loadable). */
+    preservedUrls: number;
+    /** Placeholders left untouched (over-cap / no bytes / not loadable) — ref never lost. */
+    keptPlaceholders: number;
+}
+/**
+ * **Pass 2 (post-import).** For each page id carrying an image placeholder (the
+ * writers report these in `ImportWriteResult.placeholderPageIds`), resolve every
+ * placeholder's bytes and — within the size cap — `putAsset` + rewrite it to an
+ * `assetId` `image` block, then re-save the page. A single shared limiter caps
+ * total in-flight uploads (across all pages and all images) so a large,
+ * image-dense import streams rather than flooding the socket. Degrades safely
+ * (never loses a ref); idempotent (a re-run finds real images, not placeholders,
+ * and content-addressed dedup returns the same `assetId`).
+ */
+export declare function rehydrateStoredImages(client: RehydrateStoredClient, pageIds: string[], resolve: ImportAssetResolver, opts?: RehydrateStoredOptions): Promise<RehydrateStoredResult>;
+/**
+ * Build a resolver over a Notion export zip: a placeholder `ref` (rewritten by
+ * {@link notionExportToImportedDoc} to the absolute in-zip path) → its bytes +
+ * a mime guessed from the extension. Unzips lazily on first use (the import may
+ * land no images), and answers `null` for a ref with no matching entry.
+ */
+export declare function notionAssetResolver(zipBytes: Uint8Array): ImportAssetResolver;
+/** The `fetch`-shaped surface {@link urlAssetResolver} needs (so it's testable with a fake). */
+export type FetchLike = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    headers: {
+        get(name: string): string | null;
+    };
+}>;
+/**
+ * Build a resolver that downloads an `http(s)` image `ref` into bytes — the
+ * opt-in "store a copy of each linked image" path. Uses the ambient `fetch` when
+ * no impl is passed. Answers `null` (→ the URL is preserved as a link) for a
+ * non-http ref, a non-OK response, an empty body, or any fetch error — a slow /
+ * failing / cross-origin link degrades rather than breaking the import.
+ */
+export declare function urlAssetResolver(fetchImpl?: FetchLike): ImportAssetResolver;
+export {};