mapples 0.2.0-beta.1 → 0.2.0-beta.12

package/dist/services/syncEngine.js

@@ -1,32 +1,60 @@
 // `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 { adoptPropConditions } from '@mapples/codegen';
+import { codemodAdopt, extract, patch, propOfCondition, 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 { planTransactions } from '../api/txPlan.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, ROUTE_MARKER, withoutRouteMarker } from '../codegen/emit.js';
+import { importNeedsFor, importNeedsUsedIn } from '../codegen/imports.js';
+import { instanceLinker } from '../codegen/instances.js';
+import { makeHunks, merge3, textHash } from '@mapples/textpatch';
 import { deprecateFile } from '../merge/deprecate.js';
-import { diffTree } from '../merge/diff.js';
-import { applyMergePatch, deepEqual } from '../merge/mergePatch.js';
+import { diffTree, diffTreeStaged } from '../merge/diff.js';
+import { buildMergePatch, 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';
+import { sourceIdFor, } from '../types.js';
 const MAX_REBASE_RETRIES = 5;
-const MAX_OPS_PER_TX = 200;
+/** A Source create carries a whole file (≤256 KiB); updates are hunks (A13). Fewer per transaction than node ops. */
+const SOURCE_OPS_PER_TX = 10;
+// 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 +63,33 @@ 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);
+        const entryTxs = planTransactions(entry.ops);
         try {
-            const result = await commitLoop(client, currentHead, entry.ops, entry.txId, report);
-            currentHead = result.head;
+            await pushChunked(client, entryTxs, 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(entryTxs.flat().slice(progress.committedOps), progress.idMap),
+                        parkedAt: entry.parkedAt,
+                    });
+                }
                 report.offline = true;
                 report.notes.push('still offline — outbox kept');
                 return report;
@@ -57,6 +99,15 @@ export async function runSyncEngine({ root, client }) {
                 report.notes.push(`outbox tx ${entry.txId} dropped: ${err.message} (target changed under it — this is the one user-visible conflict class, RFC-0001 §7.1)`);
                 continue;
             }
+            if (err instanceof JpatchError &&
+                (err.code === 'SOURCE_BASE_MISMATCH' || err.code === 'SOURCE_PATCH_INVALID')) {
+                // A parked code edit whose text Creator changed meanwhile (A13).
+                // Nothing is lost: the file still holds the local text, and the
+                // merge below re-derives the upload from base, file and remote.
+                outbox.clear(entry.txId);
+                report.notes.push(`outbox tx ${entry.txId} dropped: Creator changed this file meanwhile — your code edit is re-merged from the file on this sync`);
+                continue;
+            }
             throw err;
         }
     }
@@ -64,7 +115,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,41 +124,67 @@ 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);
-        if (pushOps.length === 0) {
-            finalize(root, baseStore, mergedBase, pagesMap, remote.head, remote.seq);
+        const merged = await mergeAndWrite(root, client, config, base, remote, report);
+        const { mergedBase, pagesMap, componentsMap, sourceUploads } = merged;
+        // Planned before anything is sent: a placement group that cannot fit one
+        // transaction stops the push here (RFC-0001 §5.2). `pushOps` is the send
+        // order, which is what `progress.committedOps` counts against.
+        const pushTxs = [...planTransactions(merged.pushOps), ...planTransactions(merged.deferredOps)];
+        const pushOps = pushTxs.flat();
+        // Source text goes out AFTER the node ops (its `$sid`s must be server
+        // ids, which the node push mints), as its own transaction(s).
+        let sourceOps = [];
+        if (pushOps.length === 0 && sourceUploads.size === 0) {
+            finalize(root, baseStore, mergedBase, pagesMap, componentsMap, remote.head, remote.seq);
             report.head = remote.head;
             return report;
         }
-        if (pushOps.length > MAX_OPS_PER_TX) {
+        if (pushTxs.length > 1) {
             // 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`);
+            report.notes.push(`push split into ${pushTxs.length} 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}`);
+            if (pushOps.length > 0) {
+                await pushChunked(client, pushTxs, 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;
+            }
+            sourceOps = sourceOpsFor(mergedBase, remote, sourceUploads, progress.idMap);
+            try {
+                for (let i = 0; i < sourceOps.length; i += SOURCE_OPS_PER_TX) {
+                    await pushChunked(client, [sourceOps.slice(i, i + SOURCE_OPS_PER_TX)], pushOps.length === 0 && i === 0 ? txId : mintTxId(), progress, { rebaseInPlace: false, report });
+                }
+                if (sourceOps.length > 0) {
+                    report.pushedOps += sourceOps.length;
+                    report.notes.push(`uploaded the source text of ${sourceOps.length} file(s) to Creator`);
                 }
             }
-            report.pushedOps += pushOps.length;
-            rewriteIds(root, mergedBase, pagesMap, idMap, report);
-            finalize(root, baseStore, mergedBase, pagesMap, resultHead, resultSeq);
-            report.head = resultHead;
+            catch (err) {
+                if (!(err instanceof JpatchError && err.code === 'UNKNOWN_ENTITY'))
+                    throw err;
+                // A Creator server from before A12 rejects the entity. The node ops
+                // already landed; the code stays local and is offered again once the
+                // server stores source text — never silently.
+                for (const id of sourceUploads) {
+                    const entry = mergedBase.sources.get(progress.idMap[id] ?? id);
+                    if (entry)
+                        entry.onServer = false;
+                }
+                sourceOps = [];
+                report.notes.push('this Creator server does not store source text yet — the code around your elements stays local until it does');
+            }
+            finalize(root, baseStore, mergedBase, pagesMap, componentsMap, progress.head, progress.seq);
+            report.head = progress.head;
             return report;
         }
         catch (err) {
@@ -116,18 +193,31 @@ 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() });
-                report.pushedOps = pushOps.length;
+                // 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.
+                // Source ops not yet computed (offline during the node push) are
+                // simply recomputed next time: the files still differ from the base.
+                const allOps = [...pushOps, ...sourceOps];
+                outbox.park({
+                    txId: progress.committedOps > 0 ? mintTxId() : txId,
+                    ops: resolveCids(allOps.slice(progress.committedOps), progress.idMap),
+                    parkedAt: new Date().toISOString(),
+                });
+                report.pushedOps = allOps.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 +225,70 @@ 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);
+    // A container with stored source text (A12) materializes from that text —
+    // hooks and handlers written in the Creator's editor included — patched to
+    // its current tree; the rest is generated.
+    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`);
+        const tree = linker.unlink(page.root, mapping.file, warnInto(report, mapping.file));
+        targets.push({
+            id: page.id,
+            file: mapping.file,
+            emit: async () => renderFromSource(state.sources.get(page.id) ?? null, tree, mapping.file, report, page.state) ?? emitPage(emitInput(page.name, tree, mapping, page.state), join(root, mapping.file)),
+        });
+    }
+    for (const component of state.components.values()) {
+        const mapping = componentsMap[component.id];
+        const tree = linker.unlink(component.root, mapping.file, warnInto(report, mapping.file));
+        targets.push({
+            id: component.id,
+            file: mapping.file,
+            emit: async () => renderFromSource(state.sources.get(component.id) ?? null, tree, mapping.file, report, component.state) ??
+                emitComponent({ name: component.name, root: tree, states: component.state }, join(root, mapping.file)),
+        });
+    }
+    const baseSources = new Map();
+    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' });
+        else {
+            mkdirSync(dirname(filePath), { recursive: true });
+            writeFileSync(filePath, await target.emit());
+            report.files.push({ file: target.file, action: 'created' });
+        }
+        // The text 3-way's base: the server's text where it has one, else the
+        // file as it stands (an untouched pre-existing file included — its own
+        // code then reads as a local change and uploads on the next sync).
+        const remoteSource = state.sources.get(target.id) ?? null;
+        baseSources.set(target.id, {
+            id: remoteSource?.id ?? sourceIdFor(target.id),
+            of: target.id,
+            lang: remoteSource?.lang ?? 'tsx',
+            text: remoteSource?.text ?? readFileSync(filePath, 'utf8'),
+            onServer: remoteSource !== null,
+        });
     }
-    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');
@@ -179,211 +299,301 @@ async function bootstrap(root, client, appDir, report) {
         navigation: navResult.mergedNavigation,
         style: styleResult.mergedStyle,
         assets: state.assets,
+        sources: baseSources,
     });
+    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 };
+    }
+}
+/** The route marker for a routed page's (re)generated file. */
+function emitInput(name, root, mapping, states) {
+    const input = { name, root, ...(states ? { states } : {}) };
+    return mapping.routeId ? { ...input, route: { id: mapping.routeId, name } } : input;
+}
+/**
+ * A container's states after a file is merged in: the Creator's own states
+ * as the server has them, and the prop states the file's code declares
+ * (`isActive && …`) in place of the prop states the server held.
+ */
+function withFileStates(remote, file) {
+    const out = {};
+    for (const [key, state] of Object.entries(remote)) {
+        if (propOfCondition(state.condition) === null)
+            out[key] = state;
     }
-    return file;
+    for (const [key, state] of Object.entries(file))
+        out[key] = { id: key, ...state };
+    return out;
 }
 // ------------------------------------------------------------- remote model
-async function buildRemoteModel(client, base, sinceHead, report) {
+/** The base's Source texts the server holds, keyed by container — a fetch skip-list. */
+function knownSources(base) {
+    return new Map([...base.sources]
+        .filter(([, source]) => source.onServer)
+        .map(([id, { onServer: _onServer, ...source }]) => [id, source]));
+}
+async function buildRemoteModel(client, base, sinceSeq, report) {
+    // The delta is used only to detect change and report op counts. The remote
+    // MODEL comes from the manifest: blobs are content-addressed, so the walk
+    // costs only what changed (a Source whose base text still hashes to the
+    // index entry is not fetched again).
+    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,
+            sources: new Map([...base.sources]
+                .filter(([, source]) => source.onServer)
+                .map(([id, { onServer: _onServer, ...source }]) => [id, source])),
+            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, knownSources(base));
+    return {
+        pages: state.pages,
+        components: state.components,
+        navigation: state.navigation,
+        style: state.style,
+        assets: state.assets,
+        sources: state.sources,
+        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 deferredOps = [];
+    const sourceUploads = new Set();
     const mergedBase = {
         pages: new Map(),
-        components: base.components,
+        components: new Map(),
         navigation: remote.navigation,
         style: remote.style,
         assets: remote.assets,
+        sources: new Map(),
     };
     // Reset per-attempt report fields (the rebase loop re-runs this).
     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, entity.state), filePath),
+        mergedOut: mergedBase.pages,
+        baseSources: base.sources,
+        remoteSources: remote.sources,
+        sourcesOut: mergedBase.sources,
+        sourceUploads,
+        pushOps,
+        deferredOps,
+        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, states: entity.state }, filePath),
+        mergedOut: mergedBase.components,
+        baseSources: base.sources,
+        remoteSources: remote.sources,
+        sourcesOut: mergedBase.sources,
+        sourceUploads,
+        pushOps,
+        deferredOps,
+        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, deferredOps, mergedBase, pagesMap, componentsMap, sourceUploads };
+}
+/**
+ * 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, baseSources, remoteSources, sourcesOut, sourceUploads, pushOps, deferredOps, report, } = args;
+    /**
+     * The file's text after this sync becomes the next base. It goes to the
+     * server when a stored text exists and differs from the file (the file
+     * always wins: the merge above already folded the Creator's side in), or
+     * when the developer changed the code of a file the server has no text for.
+     */
+    const recordSource = (id, remoteSource, text, codeChanged) => {
+        const upload = remoteSource !== null ? remoteSource.text !== text : codeChanged;
+        if (upload)
+            sourceUploads.add(id);
+        sourcesOut.set(id, {
+            id: remoteSource?.id ?? sourceIdFor(id),
+            of: id,
+            lang: remoteSource?.lang ?? 'tsx',
+            text,
+            onServer: remoteSource !== null || upload,
+        });
+    };
+    /** A container's file text: its stored source patched to `tree`, else generated. */
+    const fileTextFor = async (entity, mapping, remoteSource, tree, filePath) => renderFromSource(remoteSource, tree, mapping.file, report, entity.state) ??
+        (await emit(entity, mapping, tree, filePath));
+    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);
+        const baseSource = baseSources.get(id) ?? null;
+        const remoteSource = remoteSources.get(id) ?? null;
         // 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;
+        /** The prop states the file's code declares (null: no file was read). */
+        let fileStates = null;
+        /**
+         * The file as the developer left it, after import healing (a stripped
+         * import is an interrupted sync's damage, not a code edit) and before
+         * tagging (an element added without a `$sid` IS one).
+         */
+        let originalSource = 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 — and names elements the developer has
+            // since deleted, whose imports must stay gone.
+            if (baseEntity) {
+                const healed = upsertImports(fileSource, importNeedsUsedIn(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`);
+                }
+            }
+            originalSource = fileSource;
+            // 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);
+            fileStates = extracted.states;
+            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,89 +601,251 @@ 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));
+                const regenerated = await fileTextFor(remoteEntity, mapping, remoteSource, linker.unlink(remoteEntity.root, mapping.file, warnInto(report, mapping.file)), filePath);
+                writeFileSync(filePath, regenerated);
+                recordSource(id, remoteSource, regenerated, false);
                 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);
-                for (const w of warnings)
-                    report.warnings.push({ ...w, file: mapping.file });
-                writeFileSync(filePath, patched);
-                report.files.push({ file: mapping.file, action: 'updated' });
+        // The file owns the states its prop tests declare; the Creator the rest.
+        const remoteStates = remoteEntity.state ?? {};
+        const mergedStates = fileStates === null ? remoteStates : withFileStates(remoteStates, fileStates);
+        const mergedEntity = { ...remoteEntity, state: mergedStates };
+        // Write the merged view into the file — in the file's language.
+        const mergedFile = linker.unlink(merged, mapping.file, warnInto(report, mapping.file));
+        /** The file's text after this sync. */
+        let written;
+        /** The developer changed the file since the last sync (unknowable without a base). */
+        let localTextChanged = false;
+        if (fileExists && fileSource !== null && localFile !== null && originalSource !== null) {
+            // The text 3-way (A12): the code outside `$sid` elements. The
+            // document merge above already settled every element; here only the
+            // surrounding code is at stake. Remote wins when the developer left the
+            // file alone; both changed is a conflict, and P0 keeps the local file.
+            const remoteTextChanged = remoteSource !== null && baseSource !== null && remoteSource.text !== baseSource.text;
+            // Route markers are the CLI's own (placement rewrites them), never a code edit.
+            localTextChanged =
+                baseSource !== null &&
+                    withoutRouteMarker(originalSource) !== withoutRouteMarker(baseSource.text);
+            let fromRemote = null;
+            /** Both sides changed the code and the hunks did not overlap (A13). */
+            let mergedCode = false;
+            let conflictDetail = null;
+            if (remoteTextChanged && remoteSource !== null && baseSource !== null) {
+                let theirs = remoteSource.text;
+                if (localTextChanged) {
+                    // The text 3-way (A13): base = the text both sides started from,
+                    // ours = the file as the developer left it (tagged, so its `$sid`s
+                    // match the trees merged above), theirs = Creator's text now. The
+                    // route marker is the CLI's own: merged without it, put back after.
+                    const merged = merge3(withoutRouteMarker(baseSource.text), withoutRouteMarker(fileSource), withoutRouteMarker(remoteSource.text));
+                    if (merged.ok) {
+                        const marker = fileSource.split('\n').find((line) => ROUTE_MARKER.test(line));
+                        theirs = marker === undefined ? merged.text : `${marker}\n${merged.text}`;
+                        mergedCode = true;
+                    }
+                    else {
+                        conflictDetail = `${merged.conflicts} change(s) touch the same lines`;
+                    }
+                }
+                if (conflictDetail === null) {
+                    fromRemote = renderFromSource({ ...remoteSource, text: theirs }, mergedFile, mapping.file, report, mergedStates);
+                    if (fromRemote === null && mergedCode) {
+                        conflictDetail = 'the merged code has no $sid root';
+                    }
+                }
+                if (conflictDetail !== null) {
+                    mergedCode = false;
+                    fromRemote = renderFromSource(remoteSource, mergedFile, mapping.file, report, mergedStates);
+                }
+            }
+            if (fromRemote !== null) {
+                if (localTextChanged && !mergedCode) {
+                    const deprecatedTo = relative(root, deprecateFile(filePath));
+                    report.conflicts.push({
+                        sid: mergedFile.sid,
+                        reason: 'source-text',
+                        detail: `the code around the elements changed both here and in Creator${conflictDetail === null ? '' : ` — ${conflictDetail}`}`,
+                        file: mapping.file,
+                        deprecatedTo,
+                    });
+                    report.files.push({
+                        file: mapping.file,
+                        action: 'deprecated',
+                        detail: `code conflict — your version kept at ${deprecatedTo}; Creator's code applied`,
+                    });
+                }
+                else {
+                    report.files.push({
+                        file: mapping.file,
+                        action: 'updated',
+                        detail: mergedCode ? 'code merged with Creator' : 'code edited in Creator',
+                    });
+                }
+                mkdirSync(dirname(filePath), { recursive: true });
+                writeFileSync(filePath, fromRemote);
+                written = fromRemote;
             }
             else {
-                report.files.push({ file: mapping.file, action: 'unchanged' });
+                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, { states: mergedStates });
+                    for (const w of warnings)
+                        report.warnings.push({ ...w, file: mapping.file });
+                    writeFileSync(filePath, patched);
+                    report.files.push({ file: mapping.file, action: 'updated' });
+                    written = patched;
+                }
+                else {
+                    report.files.push({ file: mapping.file, action: 'unchanged' });
+                    written = fileSource;
+                }
             }
         }
         else {
             mkdirSync(dirname(filePath), { recursive: true });
-            writeFileSync(filePath, await emitPage({ name: remotePage.name, root: merged }, filePath));
+            written = await fileTextFor(mergedEntity, mapping, remoteSource, mergedFile, filePath);
+            writeFileSync(filePath, written);
             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;
+        recordSource(id, remoteSource, written, localTextChanged);
+        // Push = local changes rebased onto remote. Moves into containers created
+        // by this push go in a later transaction, once those have real ids.
+        const staged = diffTreeStaged(remoteRoot, merged);
+        pushOps.push(...staged.ops);
+        deferredOps.push(...staged.deferred);
+        const statePatch = buildMergePatch({ state: remoteStates }, { state: mergedStates });
+        if (statePatch !== null) {
+            pushOps.push({ op: 'update', entity: kind.entity, id, patch: statePatch });
+        }
+        const next = { ...mergedEntity, root: merged };
+        if (Object.keys(mergedStates).length === 0)
+            delete next.state;
+        mergedOut.set(id, next);
+        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 });
+    };
+}
+/**
+ * A container's stored source (A12) brought up to date with `tree` — the
+ * FILE-language tree the file must show: its `$sid` elements are re-patched
+ * from the document (which is the truth for them), everything around them is
+ * the text as stored. Null when the text holds no `$sid` root, which is
+ * reported and regenerated rather than silently guessed.
+ */
+function renderFromSource(source, tree, file, report, docStates) {
+    if (source === null)
+        return null;
+    const extracted = extract(source.text);
+    if (extracted.dom === null) {
+        report.notes.push(`${file}: the source stored in Creator has no $sid root — regenerated from the canvas instead`);
+        return null;
+    }
+    fillNonLiteralProps(extracted.dom, tree, extracted.warnings);
+    // What renders under a prop test is the text's to say: the document may
+    // predate it, and must not strip a guard or a prop-state style from code.
+    const adopted = adoptPropConditions(tree, extracted.dom, extracted.states, docStates);
+    const healed = upsertImports(source.text, importNeedsFor(tree));
+    const edits = treeToEdits(extracted.dom, adopted.tree);
+    if (edits.length === 0)
+        return healed;
+    const { source: patched, warnings } = patch(healed, edits, { states: adopted.states });
+    for (const w of warnings)
+        report.warnings.push({ ...w, file });
+    return patched;
+}
+/**
+ * Source ops for the containers the merge marked for upload: a create where
+ * the server has no Source yet, an update otherwise. `idMap` resolves
+ * containers created by the node push that just landed.
+ */
+function sourceOpsFor(mergedBase, remote, uploads, idMap) {
+    const ops = [];
+    for (const containerId of uploads) {
+        const serverId = idMap[containerId] ?? containerId;
+        if (serverId.startsWith('c_'))
+            continue; // its page never landed (offline): next sync
+        const source = mergedBase.sources.get(serverId);
+        if (!source)
+            throw new Error(`internal: no merged source for ${serverId}`);
+        const remoteSource = remote.sources.get(serverId) ?? null;
+        if (remoteSource === null) {
+            ops.push({
+                op: 'create',
+                entity: 'Source',
+                cid: mintCid(),
+                data: { of: serverId, lang: source.lang, text: source.text },
+            });
+        }
+        else if (remoteSource.text !== source.text) {
+            // A13: hunks against the server's text at the push base, never the file.
+            ops.push({
+                op: 'update',
+                entity: 'Source',
+                id: remoteSource.id,
+                text: {
+                    base: textHash(remoteSource.text),
+                    hunks: makeHunks(remoteSource.text, source.text),
+                },
+            });
+        }
+    }
+    return ops;
 }
 /** NON_LITERAL_PROP contract: expression props keep their last-known base value. */
 function fillNonLiteralProps(local, baseRoot, warnings) {
@@ -501,13 +873,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 +924,19 @@ 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);
+    // Source text mirrors the files: same rewrite, and a container minted by
+    // this push re-keys its entry under the server id.
+    const renamedSources = new Map();
+    for (const [containerId, source] of mergedBase.sources) {
+        let text = source.text;
+        for (const [cid, id] of entries)
+            text = text.split(`"${cid}"`).join(`"${id}"`);
+        const of = idMap[containerId] ?? containerId;
+        renamedSources.set(of, { ...source, id: sourceIdFor(of), of, text });
+    }
+    mergedBase.sources = renamedSources;
     if (mergedBase.assets) {
         mergedBase.assets = resolveAssetIds(mergedBase.assets, idMap);
         writeAssetMap(root, mergedBase.assets);
@@ -537,58 +944,95 @@ 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,
+        sources: new Map([...remote.sources].map(([id, source]) => [id, { ...source, onServer: true }])),
     };
 }
-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 `txs` (planned by planTransactions, RFC-0001 §5.1/§5.2) as sequential
+ * transactions. cids are transaction-scoped (§5.2, invariant 5): a later
+ * transaction may reference the nodes an earlier one created only by their
+ * server ids, so every transaction is rewritten through the idMaps collected
+ * so far before it is sent — otherwise the server answers CID_UNRESOLVED.
+ *
+ * `progress` advances after each committed transaction; when this throws, it
+ * tells the caller exactly what already landed (`committedOps` counts against
+ * `txs.flat()`). The first transaction reuses `firstTxId` (the caller's replay
+ * handle, RFC-0001 §7.3); later ones mint their own. `rebaseInPlace` retries a
+ * 409 on the same transaction 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. Every op the server dropped and every
+ * warning it raised lands in the report.
+ */
+async function pushChunked(client, txs, firstTxId, progress, opts) {
+    for (const [i, tx] of txs.entries()) {
+        const chunk = resolveCids(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;
+        for (const d of result.dropped ?? []) {
+            const op = chunk[d.index];
+            if (!op) {
+                throw new Error(`server dropped op ${d.index} of a ${chunk.length}-op transaction — server/CLI contract drift`);
+            }
+            opts.report.dropped.push({ ...d, op });
+        }
+        for (const w of result.warnings ?? []) {
+            if (!opts.report.serverWarnings.includes(w))
+                opts.report.serverWarnings.push(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 +1042,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;
 }