mapples 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/services/syncEngine.js

@@ -1,32 +1,55 @@
 // `mapples sync` end-to-end (RFC-0002 Phase 5): extract -> local ops vs base ->
-// pull -> 3-way merge -> surgical file writes (deprecation on conflict) ->
-// POST -> 409 rebase loop -> c_ -> nd_ rewrite -> base + head update.
+// pull -> place page files for the navigation -> 3-way merge -> surgical file
+// writes (deprecation on conflict) -> POST -> 409 rebase loop -> c_ -> nd_
+// rewrite -> base + head update.
+//
+// File layout (RFC-0002 §5): a page's code lives at its route file under
+// routesDir while it is in the navigation, and under pagesDir otherwise; the
+// navigation sync moves files between the two. Creator components live under
+// componentsDir. Pages and components go through the same merge loop.
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
-import { extract, patch } from '@mapples/sid-ast';
+import { codemodAdopt, extract, patch, upsertImports } from '@mapples/sid-ast';
 import { isNetworkError } from '../api/client.js';
-import { buildEnvelope, commitWithTransportRetry, mintTxId } from '../api/commit.js';
+import { buildEnvelope, commitWithTransportRetry, mintCid, mintTxId, resolveCids, } from '../api/commit.js';
 import { HeadMismatchError, JpatchError } from '../api/errors.js';
 import { pullDelta, SnapshotRequired } from '../api/poll.js';
 import { fetchProjectState, } from '../api/objects.js';
-import { emitPage, mappletName } from '../codegen/emit.js';
-import { applyNodeOps } from '../merge/applyOps.js';
+import { PRIMITIVE_MAPPING } from '../adopt/mappingTable.js';
+import { emitComponent, emitPage } from '../codegen/emit.js';
+import { importNeedsFor } from '../codegen/imports.js';
+import { instanceLinker } from '../codegen/instances.js';
 import { deprecateFile } from '../merge/deprecate.js';
 import { diffTree } from '../merge/diff.js';
-import { applyMergePatch, deepEqual } from '../merge/mergePatch.js';
+import { deepEqual } from '../merge/mergePatch.js';
 import { threeWayMerge } from '../merge/threeWay.js';
 import { treeToEdits } from '../merge/toEdits.js';
 import { BaseStore } from '../project/baseStore.js';
-import { readConfig } from '../project/config.js';
+import { DEFAULT_COMPONENTS_DIR, DEFAULT_ROUTES_DIR, readConfig, } from '../project/config.js';
+import { readComponentsMap, writeComponentsMap, } from '../project/componentsMap.js';
 import { readHead, writeHead } from '../project/head.js';
 import { Outbox } from '../project/outbox.js';
-import { readPagesMap, writePagesMap } from '../project/pagesMap.js';
+import { readPagesMap, writePagesMap, } from '../project/pagesMap.js';
 import { resolveAssetIds, syncAssets, writeAssetMap } from '../assets/assets.js';
+import { mintEntityFile } from '../nav/placement.js';
 import { syncNavigation } from '../nav/routeTree.js';
 import { syncStyleFile } from '../style/theme.js';
 import { emptyReport } from '../ui/report.js';
 const MAX_REBASE_RETRIES = 5;
 const MAX_OPS_PER_TX = 200;
+// buildRemoteModel needs the project root to read the stored head; carried as
+// a non-enumerable tag so BaseSnapshot's shape stays unchanged for callers.
+const ROOT_TAG = Symbol('projectRoot');
+function baseWithRoot(base, root) {
+    Object.defineProperty(base, ROOT_TAG, { value: root, configurable: true, enumerable: false });
+    return base;
+}
+function rootOf(base) {
+    const root = base[ROOT_TAG];
+    if (!root)
+        throw new Error('internal: base snapshot missing project root tag');
+    return root;
+}
 export async function runSyncEngine({ root, client }) {
     const report = emptyReport();
     const config = readConfig(root);
@@ -35,19 +58,32 @@ export async function runSyncEngine({ root, client }) {
     const head = readHead(root);
     // ---- Cold bootstrap ----
     if (!head || !baseStore.exists()) {
-        return bootstrap(root, client, config.appDir, report);
+        return bootstrap(root, client, config, report);
     }
     // ---- Drain outbox ----
     let currentHead = head.head;
+    let currentSeq = head.seq;
     for (const entry of outbox.list()) {
+        const progress = newProgress(currentHead, currentSeq);
         try {
-            const result = await commitLoop(client, currentHead, entry.ops, entry.txId, report);
-            currentHead = result.head;
+            await pushChunked(client, entry.ops, entry.txId, progress, { rebaseInPlace: true, report });
+            currentHead = progress.head;
+            currentSeq = progress.seq;
             outbox.clear(entry.txId);
             report.notes.push(`drained outbox tx ${entry.txId} (${entry.ops.length} ops)`);
         }
         catch (err) {
             if (isNetworkError(err)) {
+                if (progress.committedOps > 0) {
+                    // Part of a split entry landed. Keep only what is left, with the
+                    // committed cids resolved, under a fresh txId — the old one is spent.
+                    outbox.clear(entry.txId);
+                    outbox.park({
+                        txId: mintTxId(),
+                        ops: resolveCids(entry.ops.slice(progress.committedOps), progress.idMap),
+                        parkedAt: entry.parkedAt,
+                    });
+                }
                 report.offline = true;
                 report.notes.push('still offline — outbox kept');
                 return report;
@@ -64,7 +100,7 @@ export async function runSyncEngine({ root, client }) {
     const base = baseStore.readAll();
     let remote;
     try {
-        remote = await buildRemoteModel(client, base, currentHead, report);
+        remote = await buildRemoteModel(client, baseWithRoot(base, root), currentSeq, report);
     }
     catch (err) {
         if (isNetworkError(err)) {
@@ -73,12 +109,12 @@ export async function runSyncEngine({ root, client }) {
         throw err;
     }
     // ---- Merge + write + push (with 409 rebase loop) ----
-    const txId = mintTxId();
+    let txId = mintTxId();
     let attempt = 0;
     for (;;) {
-        const { pushOps, mergedBase, pagesMap } = await mergeAndWrite(root, client, config, base, remote, report);
+        const { pushOps, mergedBase, pagesMap, componentsMap } = await mergeAndWrite(root, client, config, base, remote, report);
         if (pushOps.length === 0) {
-            finalize(root, baseStore, mergedBase, pagesMap, remote.head, remote.seq);
+            finalize(root, baseStore, mergedBase, pagesMap, componentsMap, remote.head, remote.seq);
             report.head = remote.head;
             return report;
         }
@@ -86,28 +122,19 @@ export async function runSyncEngine({ root, client }) {
             // Split into sequential transactions (RFC-0001 §5.1 TX_TOO_LARGE discipline).
             report.notes.push(`push split into ${Math.ceil(pushOps.length / MAX_OPS_PER_TX)} transactions`);
         }
+        const progress = newProgress(remote.head, remote.seq);
         try {
-            let resultHead = remote.head;
-            let resultSeq = remote.seq;
-            let idMap = {};
-            let cursorBase = remote.head;
-            for (let i = 0; i < pushOps.length; i += MAX_OPS_PER_TX) {
-                const chunk = pushOps.slice(i, i + MAX_OPS_PER_TX);
-                const chunkTx = i === 0 ? txId : mintTxId();
-                const result = await commitWithTransportRetry(client, buildEnvelope(client, { base: cursorBase, ops: chunk, txId: chunkTx }));
-                resultHead = result.head;
-                resultSeq = result.seq;
-                cursorBase = result.head;
-                idMap = { ...idMap, ...result.idMap };
-                if (result.warnings?.length) {
-                    for (const w of result.warnings)
-                        report.notes.push(`server warning: ${w}`);
-                }
-            }
+            await pushChunked(client, pushOps, txId, progress, {
+                rebaseInPlace: false,
+                report,
+                // Rewrite as each chunk lands, so files and base never hold a cid the
+                // server has already resolved: a re-merge or a park after a later
+                // chunk fails then sees the committed nodes by their real ids.
+                onChunk: (idMap) => rewriteIds(root, mergedBase, [pagesMap, componentsMap], idMap, report),
+            });
             report.pushedOps += pushOps.length;
-            rewriteIds(root, mergedBase, pagesMap, idMap, report);
-            finalize(root, baseStore, mergedBase, pagesMap, resultHead, resultSeq);
-            report.head = resultHead;
+            finalize(root, baseStore, mergedBase, pagesMap, componentsMap, progress.head, progress.seq);
+            report.head = progress.head;
             return report;
         }
         catch (err) {
@@ -116,18 +143,28 @@ export async function runSyncEngine({ root, client }) {
                 if (attempt >= MAX_REBASE_RETRIES) {
                     throw new Error(`sync gave up after ${MAX_REBASE_RETRIES} rebase attempts — the project is changing faster than we can rebase; re-run \`mapples sync\``);
                 }
-                report.notes.push(`rebase ${attempt}: HEAD moved to ${err.head} (${err.delta.ops.length} new ops)`);
-                applyDeltaToRemote(remote, err.delta.ops, err.head, err.delta.seq, base, report);
-                continue; // re-merge against the advanced remote, retry SAME txId
+                if (progress.committedOps > 0) {
+                    // Earlier chunks landed under `txId`; replaying it would hand back
+                    // their result instead of committing the re-merged ops.
+                    report.pushedOps += progress.committedOps;
+                    txId = mintTxId();
+                }
+                report.notes.push(`rebase ${attempt}: HEAD moved to ${err.head} — refetching state`);
+                remote = await buildRemoteModel(client, baseWithRoot(base, root), currentSeq, report);
+                continue; // re-merge against the advanced remote, retry the same txId unless it is spent
             }
             if (isNetworkError(err)) {
-                // Files already show the merged view; park the ops, adopt the remote
-                // head so the drain pushes exactly these ops next time.
-                outbox.park({ txId, ops: pushOps, parkedAt: new Date().toISOString() });
+                // Files already show the merged view; park what did not land (with
+                // the committed chunks' cids resolved) and adopt the remote head so
+                // the drain pushes exactly these ops next time.
+                outbox.park({
+                    txId: progress.committedOps > 0 ? mintTxId() : txId,
+                    ops: resolveCids(pushOps.slice(progress.committedOps), progress.idMap),
+                    parkedAt: new Date().toISOString(),
+                });
                 report.pushedOps = pushOps.length;
                 report.offline = true;
-                const { mergedBase: remoteOnlyBase, pagesMap } = remoteAsBase(base, remote);
-                finalize(root, baseStore, remoteOnlyBase, { ...readPagesMap(root), ...pagesMap }, remote.head, remote.seq);
+                finalize(root, baseStore, remoteAsBase(remote), readPagesMap(root), readComponentsMap(root), remote.head, remote.seq);
                 return report;
             }
             throw err;
@@ -135,40 +172,52 @@ export async function runSyncEngine({ root, client }) {
     }
 }
 // ---------------------------------------------------------------- bootstrap
-async function bootstrap(root, client, appDir, report) {
+async function bootstrap(root, client, config, report) {
     const boot = await client.bootstrap();
     const state = await fetchProjectState(client, boot);
     const baseStore = new BaseStore(root);
     const pagesMap = readPagesMap(root);
-    const usedFiles = new Set(Object.values(pagesMap).map((m) => m.file));
+    // Placement first: every page gets its file position from the navigation.
+    const navResult = syncNavigation(root, config.routesDir ?? DEFAULT_ROUTES_DIR, config.pagesDir, state.pages, pagesMap, state.navigation, state.navigation, report);
+    const componentsMap = readComponentsMap(root);
+    placeComponents(config.componentsDir ?? DEFAULT_COMPONENTS_DIR, state.components, componentsMap);
+    const linker = instanceLinker(componentsMap, state.components);
+    const targets = [];
     for (const page of state.pages.values()) {
-        let mapping = pagesMap[page.id];
-        if (!mapping) {
-            mapping = {
-                file: mintFilePath(appDir, page.name, usedFiles),
-                name: page.name,
-                route: page.route,
-            };
-            pagesMap[page.id] = mapping;
-            usedFiles.add(mapping.file);
-        }
-        const filePath = join(root, mapping.file);
+        const mapping = pagesMap[page.id];
+        if (!mapping)
+            throw new Error(`internal: page ${page.id} was not placed`);
+        targets.push({
+            file: mapping.file,
+            emit: () => emitPage(emitInput(page.name, linker.unlink(page.root, mapping.file, warnInto(report, mapping.file)), mapping), join(root, mapping.file)),
+        });
+    }
+    for (const component of state.components.values()) {
+        const mapping = componentsMap[component.id];
+        targets.push({
+            file: mapping.file,
+            emit: () => emitComponent({
+                name: component.name,
+                root: linker.unlink(component.root, mapping.file, warnInto(report, mapping.file)),
+            }, join(root, mapping.file)),
+        });
+    }
+    for (const target of targets) {
+        const filePath = join(root, target.file);
         if (existsSync(filePath)) {
             // P0: never overwrite. The file's content will be merged on the next sync.
             report.files.push({
-                file: mapping.file,
+                file: target.file,
                 action: 'unchanged',
                 detail: 'exists — left untouched',
             });
             continue;
         }
         mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, await emitPage({ name: page.name, root: page.root }, filePath));
-        report.files.push({ file: mapping.file, action: 'created' });
+        writeFileSync(filePath, await target.emit());
+        report.files.push({ file: target.file, action: 'created' });
     }
-    const config = readConfig(root);
     const styleResult = syncStyleFile(root, state.style, state.style, report);
-    const navResult = syncNavigation(root, config.routesDir ?? 'app/(mapples)', pagesMap, state.navigation, state.navigation, report);
     const assetsResult = await syncAssets(root, client, state.assets, report);
     if (assetsResult.pushOps.length > 0) {
         report.notes.push('local assets found — run `mapples sync` again to upload them');
@@ -180,165 +229,89 @@ async function bootstrap(root, client, appDir, report) {
         style: styleResult.mergedStyle,
         assets: state.assets,
     });
+    baseStore.writeStamp(state.head);
     writePagesMap(root, pagesMap);
+    writeComponentsMap(root, componentsMap);
     writeHead(root, { head: state.head, seq: state.seq });
     report.head = state.head;
-    report.notes.push(`bootstrapped ${state.pages.size} page(s) @ ${state.head}`);
+    report.notes.push(`bootstrapped ${state.pages.size} page(s), ${state.components.size} component(s) @ ${state.head}`);
     return report;
 }
-function mintFilePath(appDir, pageName, used) {
-    const baseName = mappletName(pageName);
-    let file = join(appDir, `${baseName}.tsx`);
-    let counter = 2;
-    while (used.has(file)) {
-        file = join(appDir, `${baseName}${counter}.tsx`);
-        counter += 1;
+/** Every Creator component gets a file under componentsDir; existing mappings are kept. */
+function placeComponents(componentsDir, components, componentsMap) {
+    const used = new Set(Object.values(componentsMap).map((m) => m.file));
+    for (const [id, component] of components) {
+        if (componentsMap[id])
+            continue;
+        const file = mintEntityFile(componentsDir, component.name, used);
+        used.add(file);
+        componentsMap[id] = { file, name: component.name };
     }
-    return file;
+}
+/** The route marker for a routed page's (re)generated file. */
+function emitInput(name, root, mapping) {
+    return mapping.routeId ? { name, root, route: { id: mapping.routeId, name } } : { name, root };
 }
 // ------------------------------------------------------------- remote model
-async function buildRemoteModel(client, base, sinceHead, report) {
+async function buildRemoteModel(client, base, sinceSeq, report) {
+    // The delta is used only to detect change and report op counts. The remote
+    // MODEL always comes from a full snapshot fetch: the real backend currently
+    // moves HEAD through legacy-write mirroring without emitting the matching
+    // ops (navigation saves, page creation — RFC-0001 invariant 10 violation),
+    // so op-replay would silently reconstruct a stale tree. Revisit when the
+    // backend guarantees every HEAD move carries its ops.
+    let head;
     try {
-        const delta = await pullDelta(client, sinceHead);
+        const delta = await pullDelta(client, sinceSeq);
         report.pulledOps = delta.ops.length;
-        const model = {
+        head = delta.head;
+    }
+    catch (err) {
+        if (!(err instanceof SnapshotRequired))
+            throw err;
+        report.notes.push('too far behind — cold re-bootstrap of remote state');
+        head = '';
+    }
+    const storedHead = readHead(rootOf(base)) ?? null;
+    const stamped = new BaseStore(rootOf(base)).readStamp();
+    if (head !== '' &&
+        storedHead &&
+        head === storedHead.head &&
+        stamped === storedHead.head &&
+        report.pulledOps === 0) {
+        // Nothing changed server-side and the base was written at this very
+        // head: the base IS the remote state.
+        return {
             pages: structuredClone(base.pages),
+            components: structuredClone(base.components),
             navigation: structuredClone(base.navigation),
             style: structuredClone(base.style),
             assets: structuredClone(base.assets),
-            head: delta.head,
-            seq: delta.seq,
+            head: storedHead.head,
+            seq: storedHead.seq,
         };
-        applyDeltaToRemote(model, delta.ops, delta.head, delta.seq, base, report);
-        return model;
-    }
-    catch (err) {
-        if (err instanceof SnapshotRequired) {
-            report.notes.push('too far behind — cold re-bootstrap of remote state');
-            const boot = await client.bootstrap();
-            const state = await fetchProjectState(client, boot);
-            return {
-                pages: state.pages,
-                navigation: state.navigation,
-                style: state.style,
-                assets: state.assets,
-                head: state.head,
-                seq: state.seq,
-            };
-        }
-        throw err;
-    }
-}
-function applyDeltaToRemote(model, ops, head, seq, base, report) {
-    model.head = head;
-    model.seq = seq;
-    const nodeOps = ops.filter((o) => o.entity === 'RenderNode');
-    for (const page of model.pages.values()) {
-        const { root } = applyNodeOps(page.root, nodeOps);
-        if (root)
-            page.root = root;
-        else
-            model.pages.delete(page.id);
-    }
-    for (const op of ops) {
-        switch (op.entity) {
-            case 'RenderNode':
-                break; // handled above
-            case 'Page': {
-                if (op.op === 'create') {
-                    const data = op.data;
-                    const id = op.id ?? op.cid;
-                    if (!id)
-                        throw new Error('Page create op without id');
-                    const tree = buildTreeFromOps(nodeOps, data.root);
-                    if (!tree) {
-                        report.notes.push(`pulled Page ${id} but its root ${data.root} is not in the delta — skipping`);
-                        break;
-                    }
-                    model.pages.set(id, { id, name: data.name, route: data.route, root: tree });
-                }
-                else if (op.op === 'update' && op.id) {
-                    const page = model.pages.get(op.id);
-                    if (page && op.patch) {
-                        const patched = applyMergePatch({ name: page.name, route: page.route }, op.patch);
-                        page.name = patched.name;
-                        page.route = patched.route;
-                    }
-                }
-                else if (op.op === 'delete' && op.id) {
-                    model.pages.delete(op.id);
-                }
-                break;
-            }
-            case 'NavigationRoute': {
-                const nav = model.navigation ?? { routes: [], layouts: {} };
-                if (op.op === 'create') {
-                    const id = op.id ?? op.cid;
-                    if (id)
-                        nav.routes.push({ id, ...op.data });
-                }
-                else if (op.op === 'update' && op.id && op.patch) {
-                    const idx = nav.routes.findIndex((r) => r.id === op.id);
-                    if (idx !== -1)
-                        nav.routes[idx] = applyMergePatch(nav.routes[idx], op.patch);
-                }
-                else if (op.op === 'delete' && op.id) {
-                    nav.routes = nav.routes.filter((r) => r.id !== op.id);
-                }
-                model.navigation = nav;
-                break;
-            }
-            case 'NavigationDocument':
-                if (op.patch)
-                    model.navigation = applyMergePatch(model.navigation ?? { routes: [], layouts: {} }, op.patch);
-                break;
-            case 'StyleConfig':
-                if (op.patch)
-                    model.style = applyMergePatch(model.style ?? { theme: {}, typography: {}, sizing: {} }, op.patch);
-                break;
-            case 'Theme':
-            case 'Typography':
-            case 'Sizing': {
-                const key = op.entity.toLowerCase();
-                const style = model.style ?? { theme: {}, typography: {}, sizing: {} };
-                if (op.patch) {
-                    model.style = { ...style, [key]: applyMergePatch(style[key], op.patch) };
-                }
-                break;
-            }
-            case 'Asset': {
-                const assets = model.assets ?? {};
-                const id = op.id ?? op.cid;
-                if (op.op === 'delete' && op.id)
-                    delete assets[op.id];
-                else if (op.op === 'create' && id)
-                    assets[id] = op.data;
-                else if (op.op === 'update' && op.id && op.patch) {
-                    assets[op.id] = applyMergePatch(assets[op.id], op.patch);
-                }
-                model.assets = assets;
-                break;
-            }
-            default:
-                report.notes.push(`pulled op for unhandled entity ${op.entity} — recorded in base only`);
-        }
     }
-    void base;
-}
-function buildTreeFromOps(nodeOps, rootId) {
-    const { root, orphans } = applyNodeOps(null, nodeOps);
-    if (root && root.sid === rootId)
-        return root;
-    return orphans.get(rootId) ?? null;
+    const boot = await client.bootstrap();
+    const state = await fetchProjectState(client, boot);
+    return {
+        pages: state.pages,
+        components: state.components,
+        navigation: state.navigation,
+        style: state.style,
+        assets: state.assets,
+        head: state.head,
+        seq: state.seq,
+    };
 }
+const PAGE_KIND = { label: 'page', entity: 'Page' };
+const COMPONENT_KIND = { label: 'component', entity: 'Component' };
 async function mergeAndWrite(root, client, config, base, remote, report) {
-    const appDir = config.appDir;
     const pagesMap = readPagesMap(root);
-    const usedFiles = new Set(Object.values(pagesMap).map((m) => m.file));
+    const componentsMap = readComponentsMap(root);
     const pushOps = [];
     const mergedBase = {
         pages: new Map(),
-        components: base.components,
+        components: new Map(),
         navigation: remote.navigation,
         style: remote.style,
         assets: remote.assets,
@@ -347,43 +320,137 @@ async function mergeAndWrite(root, client, config, base, remote, report) {
     report.files = [];
     report.conflicts = [];
     report.warnings = [];
-    const pageIds = new Set([...base.pages.keys(), ...remote.pages.keys()]);
-    for (const pageId of pageIds) {
-        const basePage = base.pages.get(pageId) ?? null;
-        const remotePage = remote.pages.get(pageId) ?? null;
-        let mapping = pagesMap[pageId];
+    // ---- Navigation first: it decides where every page file lives ----
+    const navResult = syncNavigation(root, config.routesDir ?? DEFAULT_ROUTES_DIR, config.pagesDir, remote.pages, pagesMap, base.navigation, remote.navigation, report);
+    pushOps.push(...navResult.pushOps);
+    mergedBase.navigation = navResult.mergedNavigation;
+    placeComponents(config.componentsDir ?? DEFAULT_COMPONENTS_DIR, remote.components, componentsMap);
+    // Component uuids come from the remote model; a page's instances link to them.
+    const linker = instanceLinker(componentsMap, remote.components);
+    await mergeFiles({
+        root,
+        kind: PAGE_KIND,
+        base: base.pages,
+        remote: remote.pages,
+        mapping: pagesMap,
+        linker,
+        emit: (entity, mapping, tree, filePath) => emitPage(emitInput(entity.name, tree, mapping), filePath),
+        mergedOut: mergedBase.pages,
+        pushOps,
+        report,
+    });
+    await mergeFiles({
+        root,
+        kind: COMPONENT_KIND,
+        base: base.components,
+        remote: remote.components,
+        mapping: componentsMap,
+        linker,
+        emit: (entity, _mapping, tree, filePath) => emitComponent({ name: entity.name, root: tree }, filePath),
+        mergedOut: mergedBase.components,
+        pushOps,
+        report,
+    });
+    // ---- Non-page entities: style, assets ----
+    const styleResult = syncStyleFile(root, base.style, remote.style, report);
+    pushOps.push(...styleResult.pushOps);
+    mergedBase.style = styleResult.mergedStyle;
+    const assetsResult = await syncAssets(root, client, remote.assets, report);
+    pushOps.push(...assetsResult.pushOps);
+    mergedBase.assets = assetsResult.mergedAssets;
+    return { pushOps, mergedBase, pagesMap, componentsMap };
+}
+/**
+ * The 3-way file merge for one entity kind: extract the file, merge against
+ * base and remote, write the merged view (patch in place, or regenerate),
+ * deprecate on conflict, and collect the ops that push local changes.
+ */
+async function mergeFiles(args) {
+    const { root, kind, base, remote, mapping: mappings, linker, emit, mergedOut, pushOps, report, } = args;
+    const ids = new Set([...base.keys(), ...remote.keys()]);
+    for (const id of ids) {
+        const baseEntity = base.get(id) ?? null;
+        const remoteEntity = remote.get(id) ?? null;
+        const mapping = mappings[id];
         if (!mapping) {
-            const name = remotePage?.name ?? basePage?.name ?? pageId;
-            mapping = {
-                file: mintFilePath(appDir, name, usedFiles),
-                name,
-                route: remotePage?.route ?? basePage?.route ?? '/',
-            };
-            pagesMap[pageId] = mapping;
-            usedFiles.add(mapping.file);
+            // Known to the base only and never written to disk: nothing to reconcile.
+            if (remoteEntity)
+                throw new Error(`internal: ${kind.label} ${id} was not placed`);
+            continue;
         }
         const filePath = join(root, mapping.file);
         const fileExists = existsSync(filePath);
         // local = fresh extract, with NON_LITERAL props refilled from base.
         let local;
+        // The same tree as the file reads it (linked instances still Customs):
+        // what edits to the file are computed against.
+        let localFile = null;
         let fileSource = null;
         if (fileExists) {
             fileSource = readFileSync(filePath, 'utf8');
+            // Pre-extraction import healing: a file left behind by an interrupted
+            // sync may use elements its import block never gained. Without the
+            // import, extraction reads primitives as local Customs and the merge
+            // would push that misreading to the server. The BASE tree knows the true
+            // types for every existing sid.
+            if (baseEntity) {
+                const healed = upsertImports(fileSource, importNeedsFor(linker.unlink(baseEntity.root, mapping.file, () => undefined)));
+                if (healed !== fileSource) {
+                    fileSource = healed;
+                    writeFileSync(filePath, healed);
+                    report.notes.push(`${mapping.file}: restored missing imports before extraction`);
+                }
+            }
+            // An element the developer added without a `$sid` is invisible to
+            // extraction — and so to the Creator — for as long as it stays untagged.
+            // Tag it the way adoption did the file: react-native primitives swapped
+            // and their props translated, anything else an opaque Custom node.
+            const tagged = codemodAdopt(fileSource, {
+                mapping: PRIMITIVE_MAPPING,
+                mintSid: mintCid,
+                isLinked: (origin) => linker.isLinked(origin, mapping.file),
+            });
+            if (tagged.adopted.length > 0) {
+                fileSource = tagged.source;
+                writeFileSync(filePath, fileSource);
+                const names = tagged.adopted.map((a) => a.kind === 'custom' ? `${a.originalName} (Custom)` : a.originalName);
+                report.notes.push(`${mapping.file}: tagged ${tagged.adopted.length} new element(s) — ${names.join(', ')}`);
+                for (const skip of tagged.skipped) {
+                    report.warnings.push({
+                        kind: 'UNKNOWN_ELEMENT_WITH_SID',
+                        detail: `${mapping.file}: ${skip.reason}`,
+                    });
+                }
+            }
             const extracted = extract(fileSource);
             for (const w of extracted.warnings)
                 report.warnings.push({ ...w, file: mapping.file });
             local = extracted.dom;
-            if (local && basePage)
-                fillNonLiteralProps(local, basePage.root, extracted.warnings);
+            if (local) {
+                // A hand-written `$sid` that is neither a server id nor a ULID-shaped
+                // `c_` placeholder fails the server's envelope validation and takes
+                // the whole push down with it. Mint the placeholder here instead.
+                const renamed = normalizeClientIds(local);
+                if (renamed.size > 0) {
+                    for (const [from, to] of renamed)
+                        fileSource = fileSource.split(`"${from}"`).join(`"${to}"`);
+                    writeFileSync(filePath, fileSource);
+                    report.notes.push(`${mapping.file}: minted client id(s) for ${[...renamed.keys()].join(', ')} (a new element's $sid must be c_<ULID>)`);
+                }
+                localFile = structuredClone(local);
+                linker.link(local, mapping.file, warnInto(report, mapping.file));
+            }
+            if (local && baseEntity)
+                fillNonLiteralProps(local, baseEntity.root, extracted.warnings);
         }
         else {
-            local = basePage?.root ?? null; // no file -> treat as unchanged
-            if (basePage) {
+            local = baseEntity?.root ?? null; // no file -> treat as unchanged
+            if (baseEntity) {
                 report.notes.push(`${mapping.file} is missing — regenerating from the merged canvas state`);
             }
         }
-        const baseRoot = basePage?.root ?? null;
-        const remoteRoot = remotePage?.root ?? null;
+        const baseRoot = baseEntity?.root ?? null;
+        const remoteRoot = remoteEntity?.root ?? null;
         const { merged, conflicts } = threeWayMerge(baseRoot, local, remoteRoot);
         if (conflicts.length > 0) {
             let deprecatedTo;
@@ -391,58 +458,66 @@ async function mergeAndWrite(root, client, config, base, remote, report) {
                 deprecatedTo = relative(root, deprecateFile(filePath));
             for (const c of conflicts)
                 report.conflicts.push({ ...c, file: mapping.file, deprecatedTo });
-            if (remotePage) {
+            if (remoteEntity) {
                 mkdirSync(dirname(filePath), { recursive: true });
-                writeFileSync(filePath, await emitPage({ name: remotePage.name, root: remotePage.root }, filePath));
+                writeFileSync(filePath, await emit(remoteEntity, mapping, linker.unlink(remoteEntity.root, mapping.file, warnInto(report, mapping.file)), filePath));
                 report.files.push({
                     file: mapping.file,
                     action: 'deprecated',
                     detail: `conflict — your version kept at ${deprecatedTo ?? '(no file)'}; regenerated from Creator`,
                 });
-                mergedBase.pages.set(pageId, remotePage);
-                mapping.name = remotePage.name;
-                mapping.route = remotePage.route;
+                mergedOut.set(id, remoteEntity);
+                mapping.name = remoteEntity.name;
             }
             else {
                 report.files.push({
                     file: mapping.file,
                     action: 'deprecated',
-                    detail: 'page deleted in Creator; your local edits kept in the .old file',
+                    detail: `${kind.label} deleted in Creator; your local edits kept in the .old file`,
                 });
-                delete pagesMap[pageId];
+                delete mappings[id];
             }
             continue; // keepLocal ops for this file are DROPPED from the push
         }
-        if (remotePage === null) {
+        if (remoteEntity === null) {
             // Deleted remotely, no local edits (else it would have conflicted).
             if (fileExists) {
                 const deprecatedTo = relative(root, deprecateFile(filePath));
                 report.files.push({
                     file: mapping.file,
                     action: 'deprecated',
-                    detail: `page deleted in Creator — file kept at ${deprecatedTo}`,
+                    detail: `${kind.label} deleted in Creator — file kept at ${deprecatedTo}`,
                 });
             }
-            delete pagesMap[pageId];
+            delete mappings[id];
             continue;
         }
         if (merged === null) {
-            // Locally deleted page tree, remote unchanged: push the deletion.
-            pushOps.push({ op: 'delete', entity: 'RenderNode', id: remotePage.root.sid, cascade: true });
-            pushOps.push({ op: 'delete', entity: 'Page', id: pageId });
+            // Locally deleted tree, remote unchanged: push the deletion.
+            pushOps.push({
+                op: 'delete',
+                entity: 'RenderNode',
+                id: remoteEntity.root.sid,
+                cascade: true,
+            });
+            pushOps.push({ op: 'delete', entity: kind.entity, id });
             report.files.push({
                 file: mapping.file,
                 action: 'updated',
                 detail: 'local deletion pushed to Creator',
             });
-            delete pagesMap[pageId];
+            delete mappings[id];
             continue;
         }
-        // Write the merged view into the file.
-        if (fileExists && fileSource !== null && local !== null) {
-            const edits = treeToEdits(local, merged);
-            if (edits.length > 0) {
-                const { source: patched, warnings } = patch(fileSource, edits);
+        // Write the merged view into the file — in the file's language.
+        const mergedFile = linker.unlink(merged, mapping.file, warnInto(report, mapping.file));
+        if (fileExists && fileSource !== null && localFile !== null) {
+            const edits = treeToEdits(localFile, mergedFile);
+            // Import healing: patch-inserted elements must be importable, and files
+            // touched by an interrupted earlier sync may be missing imports already.
+            const healed = upsertImports(fileSource, importNeedsFor(mergedFile));
+            if (edits.length > 0 || healed !== fileSource) {
+                const { source: patched, warnings } = patch(healed, edits);
                 for (const w of warnings)
                     report.warnings.push({ ...w, file: mapping.file });
                 writeFileSync(filePath, patched);
@@ -454,26 +529,20 @@ async function mergeAndWrite(root, client, config, base, remote, report) {
         }
         else {
             mkdirSync(dirname(filePath), { recursive: true });
-            writeFileSync(filePath, await emitPage({ name: remotePage.name, root: merged }, filePath));
+            writeFileSync(filePath, await emit(remoteEntity, mapping, mergedFile, filePath));
             report.files.push({ file: mapping.file, action: fileExists ? 'regenerated' : 'created' });
         }
         // Push = local changes rebased onto remote.
         pushOps.push(...diffTree(remoteRoot, merged));
-        mergedBase.pages.set(pageId, { ...remotePage, root: merged });
-        mapping.name = remotePage.name;
-        mapping.route = remotePage.route;
+        mergedOut.set(id, { ...remoteEntity, root: merged });
+        mapping.name = remoteEntity.name;
     }
-    // ---- Non-page entities: style, navigation, assets ----
-    const styleResult = syncStyleFile(root, base.style, remote.style, report);
-    pushOps.push(...styleResult.pushOps);
-    mergedBase.style = styleResult.mergedStyle;
-    const navResult = syncNavigation(root, config.routesDir ?? 'app/(mapples)', pagesMap, base.navigation, remote.navigation, report);
-    pushOps.push(...navResult.pushOps);
-    mergedBase.navigation = navResult.mergedNavigation;
-    const assetsResult = await syncAssets(root, client, remote.assets, report);
-    pushOps.push(...assetsResult.pushOps);
-    mergedBase.assets = assetsResult.mergedAssets;
-    return { pushOps, mergedBase, pagesMap };
+}
+/** A warning sink that lands each warning in the report stamped with its file. */
+function warnInto(report, file) {
+    return (w) => {
+        report.warnings.push({ ...w, file });
+    };
 }
 /** NON_LITERAL_PROP contract: expression props keep their last-known base value. */
 function fillNonLiteralProps(local, baseRoot, warnings) {
@@ -501,13 +570,35 @@ function fillNonLiteralProps(local, baseRoot, warnings) {
         }
     }
 }
+// ------------------------------------------------------------ client ids
+/** Ids the server accepts as-is (RFC-0001 §5): a DB id, or a ULID-shaped `c_` placeholder. */
+const SERVER_ID_RE = /^(nd|pg|cmp|rt|st|th|ty|sz|as|nav)_\w+$/;
+const CLIENT_ID_RE = /^c_[0-9A-HJKMNP-TV-Z]{26}$/;
+/**
+ * Replace every sid the server would reject with a freshly minted `c_` id,
+ * in place. Returns old -> new so the caller can rewrite the file the same
+ * way `rewriteIds` does after a push.
+ */
+export function normalizeClientIds(root) {
+    const renamed = new Map();
+    const walk = (node) => {
+        if (!SERVER_ID_RE.test(node.sid) && !CLIENT_ID_RE.test(node.sid)) {
+            const fresh = mintCid();
+            renamed.set(node.sid, fresh);
+            node.sid = fresh;
+        }
+        node.children.forEach(walk);
+    };
+    walk(root);
+    return renamed;
+}
 // ------------------------------------------------------------ idMap rewrite
 /** After a successful push, rewrite client-minted c_ sids to server nd_ ids in files and base. */
-function rewriteIds(root, mergedBase, pagesMap, idMap, report) {
+function rewriteIds(root, mergedBase, fileMaps, idMap, report) {
     const entries = Object.entries(idMap).filter(([cid]) => cid.startsWith('c_'));
     if (entries.length === 0)
         return;
-    for (const mapping of Object.values(pagesMap)) {
+    for (const mapping of fileMaps.flatMap((m) => Object.values(m))) {
         const filePath = join(root, mapping.file);
         if (!existsSync(filePath))
             continue;
@@ -530,6 +621,8 @@ function rewriteIds(root, mergedBase, pagesMap, idMap, report) {
     };
     for (const page of mergedBase.pages.values())
         renameTree(page.root);
+    for (const component of mergedBase.components.values())
+        renameTree(component.root);
     if (mergedBase.assets) {
         mergedBase.assets = resolveAssetIds(mergedBase.assets, idMap);
         writeAssetMap(root, mergedBase.assets);
@@ -537,58 +630,85 @@ function rewriteIds(root, mergedBase, pagesMap, idMap, report) {
     report.notes.push(`resolved ${entries.length} new node id(s) from the server`);
 }
 // ----------------------------------------------------------------- finalize
-function remoteAsBase(base, remote) {
+function remoteAsBase(remote) {
     return {
-        mergedBase: {
-            pages: remote.pages,
-            components: base.components,
-            navigation: remote.navigation,
-            style: remote.style,
-            assets: remote.assets,
-        },
-        pagesMap: {},
+        pages: remote.pages,
+        components: remote.components,
+        navigation: remote.navigation,
+        style: remote.style,
+        assets: remote.assets,
     };
 }
-function finalize(root, baseStore, mergedBase, pagesMap, head, seq) {
+function finalize(root, baseStore, mergedBase, pagesMap, componentsMap, head, seq) {
     baseStore.writeAll(mergedBase);
+    baseStore.writeStamp(head);
     writePagesMap(root, pagesMap);
+    writeComponentsMap(root, componentsMap);
     writeHead(root, { head, seq });
 }
-async function commitLoop(client, base, ops, txId, report) {
-    let cursor = base;
-    for (let attempt = 0; attempt < MAX_REBASE_RETRIES; attempt++) {
-        try {
-            const result = await commitWithTransportRetry(client, buildEnvelope(client, { base: cursor, ops, txId }));
-            return { head: result.head, seq: result.seq };
-        }
-        catch (err) {
-            if (err instanceof HeadMismatchError) {
+function newProgress(head, seq) {
+    return { head, seq, idMap: {}, committedOps: 0 };
+}
+/**
+ * POST `ops` as sequential transactions of at most MAX_OPS_PER_TX (RFC-0001
+ * §5.1 TX_TOO_LARGE discipline). cids are transaction-scoped (§5.2, invariant
+ * 5): a later chunk may reference the nodes an earlier chunk created only by
+ * their server ids, so every chunk is rewritten through the idMaps collected
+ * so far before it is sent — otherwise the server answers CID_UNRESOLVED.
+ *
+ * `progress` advances after each committed chunk; when this throws, it tells
+ * the caller exactly what already landed. The first chunk reuses `firstTxId`
+ * (the caller's replay handle, RFC-0001 §7.3); later chunks mint their own.
+ * `rebaseInPlace` retries a 409 on the same chunk from the server's head (the
+ * outbox drain has nothing local to re-merge); otherwise the 409 propagates so
+ * the caller can re-merge against the advanced remote.
+ */
+async function pushChunked(client, ops, firstTxId, progress, opts) {
+    for (let i = 0; i < ops.length; i += MAX_OPS_PER_TX) {
+        const chunk = resolveCids(ops.slice(i, i + MAX_OPS_PER_TX), progress.idMap);
+        const txId = i === 0 ? firstTxId : mintTxId();
+        let cursor = progress.head;
+        let result;
+        for (let attempt = 0; result === undefined; attempt++) {
+            try {
+                result = await commitWithTransportRetry(client, buildEnvelope(client, { base: cursor, ops: chunk, txId }));
+            }
+            catch (err) {
+                if (!opts.rebaseInPlace || !(err instanceof HeadMismatchError))
+                    throw err;
+                if (attempt + 1 >= MAX_REBASE_RETRIES) {
+                    throw new Error(`outbox tx ${txId} could not be committed after ${MAX_REBASE_RETRIES} rebases`);
+                }
                 cursor = err.head;
-                report.notes.push(`outbox rebase: HEAD moved to ${err.head}`);
-                continue;
+                opts.report.notes.push(`outbox rebase: HEAD moved to ${err.head}`);
             }
-            throw err;
         }
+        progress.head = result.head;
+        progress.seq = result.seq;
+        progress.idMap = { ...progress.idMap, ...result.idMap };
+        progress.committedOps += chunk.length;
+        if (result.warnings?.length) {
+            for (const w of result.warnings)
+                opts.report.notes.push(`server warning: ${w}`);
+        }
+        opts.onChunk?.(result.idMap);
     }
-    throw new Error(`outbox tx ${txId} could not be committed after ${MAX_REBASE_RETRIES} rebases`);
 }
 function parkOffline(root, base, outbox, report) {
     // Offline before we could pull: compute local ops vs base and park them.
-    const pagesMap = readPagesMap(root);
     const ops = [];
-    for (const [pageId, mapping] of Object.entries(pagesMap)) {
-        const basePage = base.pages.get(pageId);
-        if (!basePage)
-            continue;
+    const linker = instanceLinker(readComponentsMap(root), base.components);
+    for (const [, mapping, baseEntity] of mappedEntities(root, base)) {
         const filePath = join(root, mapping.file);
         if (!existsSync(filePath))
             continue;
         const extracted = extract(readFileSync(filePath, 'utf8'));
         for (const w of extracted.warnings)
             report.warnings.push({ ...w, file: mapping.file });
-        if (extracted.dom && basePage) {
-            fillNonLiteralProps(extracted.dom, basePage.root, extracted.warnings);
-            ops.push(...diffTree(basePage.root, extracted.dom));
+        if (extracted.dom) {
+            linker.link(extracted.dom, mapping.file, warnInto(report, mapping.file));
+            fillNonLiteralProps(extracted.dom, baseEntity.root, extracted.warnings);
+            ops.push(...diffTree(baseEntity.root, extracted.dom));
         }
     }
     if (ops.length > 0) {
@@ -598,20 +718,36 @@ function parkOffline(root, base, outbox, report) {
     report.pushedOps = ops.length;
     return report;
 }
+/** Every mapped page and component that exists in the base, with its mapping. */
+function mappedEntities(root, base) {
+    const out = [];
+    for (const [id, mapping] of Object.entries(readPagesMap(root))) {
+        const page = base.pages.get(id);
+        if (page)
+            out.push([id, mapping, page]);
+    }
+    for (const [id, mapping] of Object.entries(readComponentsMap(root))) {
+        const component = base.components.get(id);
+        if (component)
+            out.push([id, mapping, component]);
+    }
+    return out;
+}
 export function verifyNoLocalDrift(root) {
     // Used by doctor (Phase 8): re-extract every mapped file and compare to base.
     const base = new BaseStore(root).readAll();
-    const pagesMap = readPagesMap(root);
+    const linker = instanceLinker(readComponentsMap(root), base.components);
     const results = [];
-    for (const [pageId, mapping] of Object.entries(pagesMap)) {
-        const basePage = base.pages.get(pageId);
+    for (const [, mapping, baseEntity] of mappedEntities(root, base)) {
         const filePath = join(root, mapping.file);
-        if (!basePage || !existsSync(filePath))
+        if (!existsSync(filePath))
             continue;
         const extracted = extract(readFileSync(filePath, 'utf8'));
-        if (extracted.dom && basePage)
-            fillNonLiteralProps(extracted.dom, basePage.root, extracted.warnings);
-        results.push({ file: mapping.file, drifted: !deepEqual(extracted.dom, basePage.root) });
+        if (extracted.dom) {
+            linker.link(extracted.dom, mapping.file, () => undefined);
+            fillNonLiteralProps(extracted.dom, baseEntity.root, extracted.warnings);
+        }
+        results.push({ file: mapping.file, drifted: !deepEqual(extracted.dom, baseEntity.root) });
     }
     return results;
 }