mapples 0.2.0-beta.0 → 0.2.0-beta.3

package/README.md

@@ -1,42 +1,90 @@
 # mapples
 
 Two-way code sync between **Mapples Creator** and your Expo project (RFC-0002, over the JPATCH/1
-protocol from RFC-0001). Screens live as generated, editable TSX in your repo — `$sid`-tagged JSX
-is the code-side truth, extracted back into RenderDom and merged 3-way against the canvas.
+protocol from RFC-0001). Screens and components live as generated, editable TSX in your repo —
+`$sid`-tagged JSX is the code-side truth, extracted back into RenderDom and merged 3-way against
+the canvas.
 
 ```bash
-npx mapples create my-app --project <projectId>   # scaffold a connected Expo app
-npx mapples init --project <projectId>            # link an existing Expo app
-npx mapples sync                                  # pull + push in one run
-npx mapples adopt app/settings.tsx                # force-adopt a plain RN screen
-npx mapples doctor                                # $sid lint + drift check
+npx mapples create my-app --secret <project API secret>   # scaffold a connected Expo app
+npx mapples init --secret <project API secret>            # link an existing Expo app
+npx mapples sync                                          # pull + push in one run
+npx mapples sync --yes                                    # …accepting every adoption proposal
+npx mapples adopt app/settings.tsx                        # adopt a plain RN screen, no prompt
+npx mapples doctor                                        # $sid lint + drift check
+```
+
+The project API secret comes from Creator (Project → Settings). It identifies the project and
+authenticates the CLI; it is stored in `.mapples/secret` (git-ignored) or read from
+`MAPPLES_SECRET`. A read-scoped secret pulls only; pushes need a write-scoped one.
+
+## Where code lives
+
+| In Creator                     | In your repo                                                        |
+| ------------------------------ | ------------------------------------------------------------------- |
+| A screen inside a navigator    | Its expo-router route file: `app/<segment>.tsx`                     |
+| A screen outside any section   | `mapples/pages/<Name>.tsx` — moves into `app/` once it is placed    |
+| Navigators (stack/tabs/drawer) | CLI-owned `app/**/_layout.tsx`, regenerated every sync              |
+| A saved component              | `mapples/components/<Name>.tsx`                                     |
+| A component placed on a screen | `import Card from '../mapples/components/Card'` + `<Card $sid … />` |
+| Theme                          | `mapples/theme.ts`                                                  |
+| Assets                         | `mapples/assets/` + generated `assetMap.ts`                         |
+
+A routed file opens with a `// mapples-route: <id>` marker: renaming the file renames the route
+in Creator, and a Creator rename moves the file. Apps born from `mapples create` own `app/`
+from the root `_layout.tsx`; apps linked with `mapples init` keep the `app/(mapples)` group.
+
+Generated files keep their styles in a dictionary below the component, the way hand-written
+Mapples code does — never inline:
+
+```tsx
+export default function Login() {
+  return <Text $sid="nd_…" text="Sign In" styled={{ style: styles.signInText }} />;
+}
+
+const styles = Styler.create({
+  signInText: { fontSize: 24, fontWeight: 'bold' },
+});
 ```
 
 ## What sync does
 
-1. Extracts every `*Mapplet.tsx` (`$sid` JSX → RenderDom; hooks/handlers/wrappers are invisible).
-2. Pulls the delta since the last synced HEAD (`GET ?since`, cold bootstrap when too far behind).
-3. 3-way merges per `$sid` node, per prop key: disjoint edits auto-merge; same-prop or
+1. Adopts new files you wrote (`app/*.tsx`, `mapples/pages/*.tsx`, `mapples/components/*.tsx`)
+   after a prompt (`--yes` to accept, `--no-adopt` to skip): react-native primitives become the
+   matching `@mapples/ui` components with `styled` props, anything else is wrapped as an opaque
+   `Custom` node; a component file becomes a Creator component, and a page that uses it links
+   to it in the same run.
+2. Extracts every managed file (`$sid` JSX → RenderDom; hooks, handlers and wrappers are
+   invisible). An element you added without a `$sid` is tagged the same way adoption would tag
+   it — it never stays invisible. A `styled={{ style: styles.card }}` reference is read through
+   your `StyleSheet.create` / `Styler.create` / plain-object dictionary.
+3. Pulls the delta since the last synced HEAD (cold bootstrap when too far behind).
+4. 3-way merges per `$sid` node, per prop key: disjoint edits auto-merge; same-prop or
    delete-vs-edit conflicts **deprecate** the file (`_depr_<ts>_<name>.tsx.old` — your version is
    never overwritten or deleted) and regenerate it from Creator.
-4. Writes remote changes into your files **surgically** — user code is preserved byte-for-byte.
-5. Pushes your edits as one JPATCH transaction; 409s rebase and retry with the same txId; going
+5. Writes remote changes into your files **surgically** — user code is preserved byte-for-byte.
+   A Creator style edit lands in the dictionary entry the tag references when that element is
+   its only reader, and inline (with a warning) when the entry is shared.
+6. Pushes your edits as JPATCH transactions of at most 200 ops; 409s rebase and retry; going
    offline parks ops in `.mapples/outbox/` and drains them next run.
-6. Rewrites client-minted `c_` ids to server ids from the response `idMap`.
+7. Rewrites client-minted `c_` ids to server ids from the response `idMap`.
 
-Also synced: navigation ↔ `app/(mapples)/` route tree (layouts CLI-owned, wrappers create-once —
-rename a wrapper file to rename the route), style ↔ `mapples/theme.ts`, and assets ↔
-`mapples/assets/` + generated `assetMap.ts`.
+Every lossy step is reported: expression props keep their last-known canvas value
+(`NON_LITERAL_PROP`), props a component instance cannot carry stay in code only, and so on.
+Nothing is dropped silently.
 
 ## Project state
 
 ```
 .mapples/
-  config.json    # projectId, apiUrl, appDir, routesDir
-  head           # last synced HEAD + seq
-  pages.json     # pageId <-> file mapping
-  base/          # canonical JSON per entity at the last synced HEAD
-  outbox/        # parked transactions (offline)
+  config.json      # projectId, apiUrl, pagesDir, routesDir, componentsDir, schema — committable
+  secret           # project API secret — git-ignored (or MAPPLES_SECRET)
+  head             # last synced HEAD + seq
+  pages.json       # pageId <-> file mapping (+ route)
+  components.json  # componentId <-> file mapping
+  base/            # canonical JSON per entity at the last synced HEAD
+  outbox/          # parked transactions (offline)
 ```
 
-Auth: set `MAPPLES_TOKEN` in the environment.
+`mapples/sid.d.ts` declares the transient JSX attributes (`$sid`, `$refs`, `$data`, `$actions`,
+`$fallback`); `babel-plugin-mapples-sid` strips them from production bundles.

package/dist/adopt/scan.d.ts

@@ -1,4 +1,10 @@
-import type { PagesMap } from '../project/pagesMap.js';
 import type { AdoptCandidate } from '../types.js';
-export declare function scanForCandidates(root: string, pagesMap: PagesMap): AdoptCandidate[];
+export interface ScanDirs {
+    routesDir: string;
+    pagesDir: string;
+}
+export declare function isUnder(file: string, dir: string): boolean;
+/** Files pages.json and components.json already own. */
+export declare function managedFiles(root: string): Set<string>;
+export declare function scanForCandidates(root: string, managed: Set<string>, dirs: ScanDirs): AdoptCandidate[];
 export declare function toRelative(root: string, file: string): string;

package/dist/adopt/scan.js

@@ -1,12 +1,32 @@
-// Adoption scan: exported React components under app/ + mapples/ with no $sid
-// and absent from the pages manifest. Unadopted files are never touched.
+// Adoption scan: exported React components under the route tree, the pages
+// directory and app/ + mapples/ with no $sid and absent from the pages and
+// components manifests. Unadopted files are never touched.
+//
+// Classification follows the file layout (RFC-0002 §5): a file under
+// routesDir is a ROUTED page (it joins the navigation at its position), one
+// under pagesDir — or elsewhere in app/ outside the managed tree — is a page
+// outside the navigation, anything else is a component.
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { isAbsolute, join, relative, sep } from 'node:path';
 import { scanComponents } from '@mapples/sid-ast';
-const SCAN_DIRS = ['app', 'mapples'];
-export function scanForCandidates(root, pagesMap) {
-    const managed = new Set(Object.values(pagesMap).map((m) => m.file));
+import { readComponentsMap } from '../project/componentsMap.js';
+import { readPagesMap } from '../project/pagesMap.js';
+export function isUnder(file, dir) {
+    const rel = relative(dir, file);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/** Files pages.json and components.json already own. */
+export function managedFiles(root) {
+    return new Set([
+        ...Object.values(readPagesMap(root)).map((m) => m.file),
+        ...Object.values(readComponentsMap(root)).map((m) => m.file),
+    ]);
+}
+export function scanForCandidates(root, managed, dirs) {
     const candidates = [];
+    const scanRoots = [
+        ...new Set(['app', 'mapples', dirs.routesDir.split(sep)[0], dirs.pagesDir.split(sep)[0]]),
+    ];
     const walk = (dir) => {
         const abs = join(root, dir);
         if (!existsSync(abs))
@@ -30,18 +50,16 @@ export function scanForCandidates(root, pagesMap) {
             if (info.hasSid || !info.hasJsx)
                 continue;
             if (info.markers.length > 0)
-                continue; // route wrappers / generated files
+                continue; // generated files / files already carrying a route
             const componentName = info.exportedComponents[0];
             if (!componentName)
                 continue;
-            candidates.push({
-                file: rel,
-                componentName,
-                kind: rel.split(sep)[0] === 'app' ? 'page' : 'component',
-            });
+            const routed = isUnder(rel, dirs.routesDir);
+            const page = routed || isUnder(rel, dirs.pagesDir) || rel.split(sep)[0] === 'app';
+            candidates.push({ file: rel, componentName, kind: page ? 'page' : 'component', routed });
         }
     };
-    for (const dir of SCAN_DIRS)
+    for (const dir of scanRoots)
         walk(dir);
     return candidates.sort((a, b) => (a.file < b.file ? -1 : 1));
 }

package/dist/adopt/scan.js.map

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

package/dist/api/auth.d.ts

@@ -2,4 +2,6 @@ export interface ResolvedProject {
     projectId: string;
     name?: string;
 }
+/** Decode the `project_uuid` claim from an API-key JWT. Null when the secret is not a JWT. */
+export declare function decodeKeyProject(secret: string): string | null;
 export declare function resolveProject(apiUrl: string, secret: string): Promise<ResolvedProject>;

package/dist/api/auth.js

@@ -1,18 +1,40 @@
-// Secret -> project resolution. The API secret (Creator: Project -> Settings)
-// both authenticates the CLI and identifies the project; the JPATCH paths
-// still need the pid, so we resolve it once and cache it in config.json.
+// Secret -> project resolution (RFC-0003). A Mapples API key is an HS256 JWT
+// whose payload carries `project_uuid` — the key both authenticates and
+// identifies the project, so resolution is a LOCAL decode of the payload (no
+// signature check client-side; the server verifies on every request). The
+// HTTP fallback exists only for opaque dev secrets (the mock server's sk_…).
 import axios from 'axios';
+/** Decode the `project_uuid` claim from an API-key JWT. Null when the secret is not a JWT. */
+export function decodeKeyProject(secret) {
+    const parts = secret.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return typeof payload.project_uuid === 'string' && payload.project_uuid.length > 0
+            ? payload.project_uuid
+            : null;
+    }
+    catch {
+        // Not a JWT payload we can read — fall through to the HTTP fallback.
+        return null;
+    }
+}
 export async function resolveProject(apiUrl, secret) {
+    const local = decodeKeyProject(secret);
+    if (local)
+        return { projectId: local };
+    // Opaque secret (mock server): resolve over HTTP with the real auth header.
     const res = await axios.get(`${apiUrl.replace(/\/+$/, '')}/auth/project`, {
-        headers: { Authorization: `Bearer ${secret}` },
+        headers: { 'X-API-Key': secret },
         validateStatus: () => true,
         timeout: 30_000,
     });
     if (res.status === 200 && typeof res.data.projectId === 'string') {
         return res.data;
     }
-    if (res.status === 401 || res.status === 403) {
-        throw new Error('the API secret was rejected — generate a fresh one in Creator (Project → Settings) and re-run with --secret');
+    if (res.status === 401 || res.status === 403 || res.status === 404) {
+        throw new Error('this does not look like a Mapples API key — generate one in Creator (Project → Settings) and re-run with --secret');
     }
     throw new Error(`could not resolve the project from the API secret (HTTP ${res.status})`);
 }

package/dist/api/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/api/auth.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0EAA0E;AAC1E,yEAAyE;AAEzE,OAAO,KAAK,MAAM,OAAO,CAAC;AAO1B,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc,EAAE,MAAc;IACjE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,EAAE;QACxE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;QAC9C,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI;QAC1B,OAAO,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,OAAQ,GAAG,CAAC,IAAgC,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC9F,OAAO,GAAG,CAAC,IAAuB,CAAC;IACrC,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,6GAA6G,CAC9G,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,2DAA2D,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5F,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/api/auth.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,wEAAwE;AACxE,6EAA6E;AAC7E,0EAA0E;AAC1E,6EAA6E;AAE7E,OAAO,KAAK,MAAM,OAAO,CAAC;AAO1B,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAE9E,CAAC;QACF,OAAO,OAAO,OAAO,CAAC,YAAY,KAAK,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;YAChF,CAAC,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc,EAAE,MAAc;IACjE,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,KAAK;QAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAEvC,4EAA4E;IAC5E,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,EAAE;QACxE,OAAO,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE;QAChC,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI;QAC1B,OAAO,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,OAAQ,GAAG,CAAC,IAAgC,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC9F,OAAO,GAAG,CAAC,IAAuB,CAAC;IACrC,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,mHAAmH,CACpH,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,2DAA2D,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5F,CAAC"}

package/dist/api/client.d.ts

@@ -3,9 +3,12 @@ import type { Bootstrap, CommitOk, Delta, Envelope } from '../types.js';
 export interface JpatchClientOptions {
     baseUrl: string;
     projectId: string;
+    /** Project API key (Creator → Project → Settings); sent as X-API-Key (RFC-0003). */
     token?: string;
     actor?: string;
     origin?: string;
+    /** Host serving asset bodies (per-stage assets host); defaults to baseUrl. */
+    assetsBaseUrl?: string;
 }
 /**
  * Thin, faithful JPATCH/1 transport (RFC-0001 §5–§8). No retry logic here —
@@ -16,14 +19,20 @@ export declare class JpatchClient {
     readonly projectId: string;
     readonly actor: string | undefined;
     readonly origin: string | undefined;
+    readonly assetsBaseUrl: string;
     constructor(opts: JpatchClientOptions);
     private path;
     commitRaw(envelope: Envelope): Promise<CommitOk>;
-    pullOnce(since: string): Promise<Delta>;
+    /** One delta page. The cursor is a SEQUENCE number (`since_seq`), not a head. */
+    pullOnce(sinceSeq: number): Promise<Delta>;
     bootstrap(): Promise<Bootstrap>;
     getObject(hash: string): Promise<unknown>;
     /** Binary blob fetch (asset bodies, addressed as `sha256:<hex>`). */
     getObjectBytes(hash: string): Promise<Uint8Array>;
+    /** Batched blob fetch: POST objects/get {hashes} -> {objects} (RFC-0001 §6, key-readable). */
+    objectsGet(hashes: string[]): Promise<Record<string, unknown>>;
+    /** Fetch raw bytes for an asset `link` (served from the assets host). */
+    getBytesAtPath(path: string): Promise<Uint8Array>;
     /** Which of these content hashes is the store missing? Returns hash -> signed PUT URL. */
     have(hashes: string[]): Promise<Record<string, string>>;
     history(limit?: number): Promise<{

package/dist/api/client.js

@@ -9,20 +9,23 @@ export class JpatchClient {
     projectId;
     actor;
     origin;
+    assetsBaseUrl;
     constructor(opts) {
         this.projectId = opts.projectId;
         this.actor = opts.actor;
         this.origin = opts.origin;
+        this.assetsBaseUrl = (opts.assetsBaseUrl ?? opts.baseUrl).replace(/\/+$/, '');
         this.http = axios.create({
             baseURL: opts.baseUrl.replace(/\/+$/, ''),
-            headers: opts.token ? { Authorization: `Bearer ${opts.token}` } : {},
+            headers: opts.token ? { 'X-API-Key': opts.token } : {},
             // We map error bodies ourselves; axios must hand them to us.
             validateStatus: () => true,
             timeout: 30_000,
         });
     }
     path(suffix = '') {
-        return `/${this.projectId}/canvas${suffix}`;
+        // Real backend shape (service--mapplesorg): plural `projects` prefix.
+        return `/projects/${this.projectId}/canvas${suffix}`;
     }
     async commitRaw(envelope) {
         const res = await this.http.post(this.path(), envelope);
@@ -30,8 +33,9 @@ export class JpatchClient {
             return res.data;
         throw errorFromBody(res.status, res.data);
     }
-    async pullOnce(since) {
-        const res = await this.http.get(this.path(), { params: { since } });
+    /** One delta page. The cursor is a SEQUENCE number (`since_seq`), not a head. */
+    async pullOnce(sinceSeq) {
+        const res = await this.http.get(this.path(), { params: { since_seq: sinceSeq } });
         if (res.status === 200)
             return res.data;
         throw errorFromBody(res.status, res.data);
@@ -57,6 +61,22 @@ export class JpatchClient {
             return new Uint8Array(res.data);
         throw errorFromBody(res.status, JSON.parse(Buffer.from(res.data).toString('utf8')));
     }
+    /** Batched blob fetch: POST objects/get {hashes} -> {objects} (RFC-0001 §6, key-readable). */
+    async objectsGet(hashes) {
+        const res = await this.http.post(this.path('/objects/get'), { hashes });
+        if (res.status === 200) {
+            return (res.data.objects ?? {});
+        }
+        throw errorFromBody(res.status, res.data);
+    }
+    /** Fetch raw bytes for an asset `link` (served from the assets host). */
+    async getBytesAtPath(path) {
+        const url = path.startsWith('http') ? path : `${this.assetsBaseUrl}${path}`;
+        const res = await this.http.get(url, { responseType: 'arraybuffer' });
+        if (res.status === 200)
+            return new Uint8Array(res.data);
+        throw errorFromBody(res.status, JSON.parse(Buffer.from(res.data).toString('utf8')));
+    }
     /** Which of these content hashes is the store missing? Returns hash -> signed PUT URL. */
     async have(hashes) {
         if (hashes.length > 500)

package/dist/api/client.js.map

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

package/dist/api/commit.d.ts

@@ -2,6 +2,15 @@ import type { CommitOk, Envelope, JpatchOp } from '../types.js';
 import type { JpatchClient } from './client.js';
 export declare function mintTxId(): string;
 export declare function mintCid(): string;
+/**
+ * Rewrite every cid that an earlier transaction already resolved (its `idMap`)
+ * to the server id, wherever it appears in `ops` — `id`, `data.parent`,
+ * children refs, props that point at sibling nodes. cids are transaction-scoped
+ * (RFC-0001 §5.2, invariant 5): once the create that minted one has committed,
+ * a later transaction must reference the DB id or the server answers
+ * CID_UNRESOLVED. Returns new objects; `ops` is left untouched.
+ */
+export declare function resolveCids(ops: JpatchOp[], idMap: Record<string, string>): JpatchOp[];
 export interface CommitParams {
     base: string;
     ops: JpatchOp[];

package/dist/api/commit.js

@@ -1,11 +1,39 @@
 import { ulid } from 'ulid';
 import { isNetworkError } from './client.js';
+import { JpatchError } from './errors.js';
 export function mintTxId() {
     return `tx_${ulid()}`;
 }
 export function mintCid() {
     return `c_${ulid()}`;
 }
+/**
+ * Rewrite every cid that an earlier transaction already resolved (its `idMap`)
+ * to the server id, wherever it appears in `ops` — `id`, `data.parent`,
+ * children refs, props that point at sibling nodes. cids are transaction-scoped
+ * (RFC-0001 §5.2, invariant 5): once the create that minted one has committed,
+ * a later transaction must reference the DB id or the server answers
+ * CID_UNRESOLVED. Returns new objects; `ops` is left untouched.
+ */
+export function resolveCids(ops, idMap) {
+    if (!Object.keys(idMap).some((k) => k.startsWith('c_')))
+        return ops;
+    const walk = (value) => {
+        if (typeof value === 'string') {
+            return value.startsWith('c_') && idMap[value] !== undefined ? idMap[value] : value;
+        }
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value !== null && typeof value === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(value))
+                out[k] = walk(v);
+            return out;
+        }
+        return value;
+    };
+    return ops.map((op) => walk(op));
+}
 export function buildEnvelope(client, params) {
     const envelope = {
         protocol: 'jpatch/1',
@@ -36,6 +64,13 @@ export async function commitWithTransportRetry(client, envelope, maxAttempts = 5
             return await client.commitRaw(envelope);
         }
         catch (err) {
+            if (err instanceof JpatchError && err.code === 'FORBIDDEN') {
+                // RFC-0003: read-scoped keys can pull but not push. Prefer the
+                // server's own guidance when it sends one.
+                const detail = err.message.replace(/^FORBIDDEN:\s*/, '');
+                throw new Error(`push rejected: ${detail ||
+                    'this API key is read-scoped — generate a read & write key in Creator (Project → Settings)'} (then re-run \`mapples init --secret <key>\`)`);
+            }
             if (!isNetworkError(err))
                 throw err;
             lastErr = err;

package/dist/api/commit.js.map

@@ -1 +1 @@
-{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../src/api/commit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,UAAU,QAAQ;IACtB,OAAO,MAAM,IAAI,EAAE,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,KAAK,IAAI,EAAE,EAAE,CAAC;AACvB,CAAC;AASD,MAAM,UAAU,aAAa,CAAC,MAAoB,EAAE,MAAoB;IACtE,MAAM,QAAQ,GAAa;QACzB,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,CAAC;QACT,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,QAAQ,EAAE;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,IAAI,EAAE;YACJ,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC7B;KACF,CAAC;IACF,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACvE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAoB,EACpB,QAAkB,EAClB,WAAW,GAAG,CAAC;IAEf,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAC;YACpC,OAAO,GAAG,GAAG,CAAC;YACd,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../src/api/commit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,UAAU,QAAQ;IACtB,OAAO,MAAM,IAAI,EAAE,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,KAAK,IAAI,EAAE,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAAe,EAAE,KAA6B;IACxE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IACpE,MAAM,IAAI,GAAG,CAAC,KAAc,EAAW,EAAE;QACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACrF,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;YACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAC7D,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAa,CAAC,CAAC;AAC/C,CAAC;AASD,MAAM,UAAU,aAAa,CAAC,MAAoB,EAAE,MAAoB;IACtE,MAAM,QAAQ,GAAa;QACzB,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,CAAC;QACT,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,QAAQ,EAAE;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,IAAI,EAAE;YACJ,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC7B;KACF,CAAC;IACF,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACvE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAoB,EACpB,QAAkB,EAClB,WAAW,GAAG,CAAC;IAEf,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC3D,+DAA+D;gBAC/D,2CAA2C;gBAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;gBACzD,MAAM,IAAI,KAAK,CACb,kBACE,MAAM;oBACN,2FACF,gDAAgD,CACjD,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAC;YACpC,OAAO,GAAG,GAAG,CAAC;YACd,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}

package/dist/api/errors.js

@@ -60,6 +60,14 @@ export class UnexpectedResponseError extends Error {
     }
 }
 export function errorFromBody(status, body) {
+    // The real backend's auth denials carry {detail} without a code field.
+    if (status === 403 &&
+        typeof body === 'object' &&
+        body !== null &&
+        !('code' in body) &&
+        typeof body.detail === 'string') {
+        return new JpatchError('FORBIDDEN', body.detail);
+    }
     if (isJpatchErrorBody(body)) {
         const { code, message, ...rest } = body;
         if (code === 'HEAD_MISMATCH') {

package/dist/api/errors.js.map

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

package/dist/api/objects.d.ts

@@ -1,19 +1,27 @@
-import type { Bootstrap, RenderDomNode } from '../types.js';
+import { type Bootstrap, type RenderDomNode } from '../types.js';
 import type { JpatchClient } from './client.js';
 export interface PageEntity {
     id: string;
     name: string;
     route: string;
     root: RenderDomNode;
+    /** Creator page uuid — navigator route targets reference pages by this. */
+    uuid?: string;
 }
 export interface ComponentEntity {
     id: string;
     name: string;
     root: RenderDomNode;
+    /** Creator component uuid — a page's `ComponentInstance` nodes link to it. */
+    uuid?: string;
 }
 export interface NavigationDocument {
-    routes: NavigationRoute[];
-    layouts: Record<string, unknown>;
+    /** Legacy/CLI route list. The real backend serves a navigator document
+     *  (`data.navigators`) without this field — then route-tree codegen is
+     *  skipped with a visible note; the raw doc is preserved in base. */
+    routes?: NavigationRoute[];
+    layouts?: Record<string, unknown>;
+    [k: string]: unknown;
 }
 export interface NavigationRoute {
     id: string;
@@ -28,11 +36,18 @@ export interface StyleConfig {
     sizing: Record<string, unknown>;
 }
 export type AssetIndex = Record<string, {
-    sha256: string;
-    mime: string;
+    sha256?: string;
+    mime?: string;
     w?: number;
     h?: number;
     name?: string;
+    /** Real backend fields (dev): server-relative body URL + file metadata. */
+    link?: string;
+    file_name?: string;
+    extension?: string;
+    type?: string;
+    uuid?: string;
+    [k: string]: unknown;
 }>;
 export interface ProjectState {
     head: string;
@@ -43,6 +58,8 @@ export interface ProjectState {
     style: StyleConfig;
     assets: AssetIndex;
 }
+/** Pages on the real backend carry no route; derive a stable one from the name. */
+export declare function deriveRoute(name: string): string;
 /** Cold bootstrap: walk the manifest and fetch every blob (RFC-0001 §6). */
 export declare function fetchProjectState(client: JpatchClient, boot: Bootstrap): Promise<ProjectState>;
 /**