mapples 0.2.0-beta.0 → 0.2.0-beta.10

package/README.md

@@ -1,42 +1,153 @@
 # 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
+npx mapples create my-app --secret <secret> --agent claude # …plus an agent bundle (claude | cursor | codex)
+npx mapples agent install                                 # add the bundle to a linked app
+```
+
+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`.
+
+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.
+
+## Run in agent (Claude Code, Cursor, Codex)
+
+`--agent <name>` on `create`/`init` (or `mapples agent install --agent <name>` in a linked app)
+sets the app up for your local coding agent. Three skills — `mapples-design` builds the app
+from a product brief the way the Creator's AI does (style guides → design tokens in
+`mapples/theme.ts` → implementation plan → one screen per phase from the design playbooks →
+wiring → review), `mapples-conventions` teaches how Mapples files are written and
+`mapples-sync` how to run and read a sync — plus a conventions file, a pointer in the agent's
+instructions file and a read-only `mapples` MCP entry, each where that agent reads it:
+
+| `--agent`           | Skills            | Conventions          | Instructions | MCP entry            | Run the skill     |
+| ------------------- | ----------------- | -------------------- | ------------ | -------------------- | ----------------- |
+| `claude`            | `.claude/skills/` | `.claude/mapples.md` | `CLAUDE.md`  | `.mcp.json`          | `/mapples-design` |
+| `cursor`            | `.cursor/skills/` | `.cursor/mapples.md` | `AGENTS.md`  | `.cursor/mcp.json`   | `/mapples-design` |
+| `codex` (`chatgpt`) | `.agents/skills/` | `.agents/mapples.md` | `AGENTS.md`  | `.codex/config.toml` | `$mapples-design` |
+
+Start the agent with the key in its environment (the MCP entry reads `MAPPLES_SECRET`; the CLI
+itself reads `.mapples/secret`), then run the skill and describe your app:
+
+```bash
+cd my-app && MAPPLES_SECRET=$(cat .mapples/secret) claude    # or: cursor .  ·  codex
+```
+
+Codex loads `.codex/config.toml` only once you trust the project. An existing instructions
+file or MCP config is never rewritten: the pointer line is appended once and the MCP entry is
+printed for you to add.
+
+Every write still goes through `mapples sync`; the MCP server only reads. Generated bundle
+files carry a `<!-- GENERATED by Mapples … -->` header and are refreshed by
+`mapples agent install`; a file you edited is left alone (`--force` keeps it as `_depr_…old`
+and regenerates).
+
+While a run is in progress the CLI holds the project's **agent-session lease** so Creator shows
+"<agent> is working on this project", a step log, and locks its own chat:
+
+```bash
+mapples agent start --agent cursor --steps "Brief,Style guides,…"         # take the lease (exit 4 if busy; --takeover)
+mapples agent step --index 5 --title "Build the Home screen" --status running   # report progress (exit 3 if the lease is gone)
+mapples agent status --json                                                  # live session + local state
+mapples agent stop --status done                                             # release (or --status failed --error "…")
+```
+
+The bundle also installs **lease hooks** (`.claude/settings.json`, `.cursor/hooks.json` or
+`.codex/hooks.json`): every prompt runs `mapples agent hook prompt`, which takes the lease, and
+the end of the agent's reply runs `mapples agent hook stop`, which releases it. So Creator shows
+the agent working for every request, even one that changes nothing. A lease a skill starts
+explicitly (`/mapples-design`) is pinned: the stop hook leaves it held between turns, so the
+chat stays locked while the skill asks questions, until the skill's own `agent stop`. When
+another agent holds the project the hook tells the agent instead of failing the prompt. Codex
+runs project hooks only after you trust the project and approve them with `/hooks`.
+
+`start` writes `.mapples/agent.json` (git-ignored) and spawns a detached heartbeat daemon
+(`mapples agent heartbeat --loop`, every `heartbeatSeconds` from the session; `--no-daemon`
+to skip it) because the lease expires 90 s after the last heartbeat. Every `mapples sync` and
+`mapples adopt` inside a session heartbeats too, and their commits are labelled
+`<agent label>: <current step>` in Creator's history (`Claude Code`, `Cursor`, `Codex`). Disconnecting the agent in Creator makes
+the next heartbeat/step exit 3. macOS/Linux daemon semantics in this version.
 
-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`.
+Exit codes: `0` ok · `1` error · `2` sync conflicts · `3` agent lease gone · `4` project busy.
 
 ## 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)
+  agent.json       # agent-session lease held by this checkout — git-ignored, present during a run
 ```
 
-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/agent.d.ts

@@ -0,0 +1,85 @@
+import { type AxiosInstance } from 'axios';
+export type AgentSessionStatus = 'active' | 'done' | 'failed' | 'expired' | 'disconnected';
+export type AgentStepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+export interface AgentSessionStep {
+    index: number;
+    title: string;
+    status: AgentStepStatus;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    detail?: string | null;
+}
+/** The session object every route returns (camelCase, as the backend serializes it). */
+export interface AgentSession {
+    uuid: string;
+    project: string;
+    agent: string;
+    label: string | null;
+    status: AgentSessionStatus;
+    apiKey: {
+        uuid: string;
+        name: string | null;
+    } | null;
+    startedAt: string;
+    lastHeartbeatAt: string;
+    expiresAt: string;
+    endedAt: string | null;
+    currentStep: string | null;
+    steps: AgentSessionStep[];
+    error: string | null;
+    rev: number;
+    heartbeatSeconds: number;
+}
+export interface AgentStartBody {
+    /** `claude-code` | `cursor` | `codex` — Creator names the session after it. */
+    agent: string;
+    label?: string;
+    steps?: {
+        title: string;
+    }[];
+    force?: boolean;
+}
+export interface AgentHeartbeatBody {
+    step?: {
+        index: number;
+        title?: string;
+        status: AgentStepStatus;
+        detail?: string;
+    };
+    currentStep?: string;
+}
+export interface AgentReleaseBody {
+    status: 'done' | 'failed';
+    error?: string;
+}
+export type AgentSessionErrorCode = 'SESSION_ACTIVE' | 'SESSION_GONE' | 'NOT_OWNER' | 'FORBIDDEN' | 'UNEXPECTED';
+export declare class AgentSessionError extends Error {
+    readonly code: AgentSessionErrorCode;
+    readonly http: number;
+    readonly body: unknown;
+    /** The live session that refused a start (409 AGENT_SESSION_ACTIVE). */
+    readonly session: AgentSession | null;
+    constructor(code: AgentSessionErrorCode, http: number, message: string, body: unknown);
+}
+/** Maps a non-success response to the typed error (never returns for 2xx). */
+export declare function agentErrorFromResponse(status: number, body: unknown): AgentSessionError;
+export interface AgentSessionClientOptions {
+    baseUrl: string;
+    projectId: string;
+    /** Project API key (write-scoped for start/heartbeat/release). */
+    token?: string;
+}
+export declare class AgentSessionClient {
+    readonly http: AxiosInstance;
+    readonly projectId: string;
+    constructor(opts: AgentSessionClientOptions);
+    private path;
+    /** POST …/agent-session → 201 session, 409 AGENT_SESSION_ACTIVE (SESSION_ACTIVE carries the live one). */
+    start(body: AgentStartBody): Promise<AgentSession>;
+    /** POST …/agent-session/{uuid}/heartbeat → 200 session, 409 SESSION_NOT_ACTIVE, 403, 404. */
+    heartbeat(uuid: string, body?: AgentHeartbeatBody): Promise<AgentSession>;
+    /** POST …/agent-session/{uuid}/release → 200 session (idempotent on terminal sessions). */
+    release(uuid: string, body: AgentReleaseBody): Promise<AgentSession>;
+    /** GET …/agent-session → {session: live | recently ended | null}. */
+    current(): Promise<AgentSession | null>;
+}

package/dist/api/agent.js

@@ -0,0 +1,92 @@
+// Agent-session lease client (service--mapplesorg `api/agent`): one live
+// lease per project, kept alive by heartbeats, with a step log the Creator
+// renders while the agent works. Same transport discipline as JpatchClient:
+// X-API-Key auth, statuses mapped here, nothing retried at this layer.
+import axios from 'axios';
+export class AgentSessionError extends Error {
+    code;
+    http;
+    body;
+    /** The live session that refused a start (409 AGENT_SESSION_ACTIVE). */
+    session;
+    constructor(code, http, message, body) {
+        super(message);
+        this.name = 'AgentSessionError';
+        this.code = code;
+        this.http = http;
+        this.body = body;
+        const session = typeof body === 'object' && body !== null
+            ? body.session
+            : undefined;
+        this.session = code === 'SESSION_ACTIVE' && session ? session : null;
+    }
+}
+function bodyField(body, key) {
+    return typeof body === 'object' && body !== null
+        ? body[key]
+        : undefined;
+}
+/** Maps a non-success response to the typed error (never returns for 2xx). */
+export function agentErrorFromResponse(status, body) {
+    const code = bodyField(body, 'code');
+    const detail = bodyField(body, 'detail');
+    const message = typeof detail === 'string' ? detail : typeof code === 'string' ? code : `HTTP ${status}`;
+    if (status === 409 && code === 'AGENT_SESSION_ACTIVE') {
+        return new AgentSessionError('SESSION_ACTIVE', status, message, body);
+    }
+    if ((status === 409 && code === 'SESSION_NOT_ACTIVE') || status === 404) {
+        return new AgentSessionError('SESSION_GONE', status, message, body);
+    }
+    if (status === 403 && code === 'NOT_SESSION_OWNER') {
+        return new AgentSessionError('NOT_OWNER', status, message, body);
+    }
+    if (status === 403 || status === 401) {
+        return new AgentSessionError('FORBIDDEN', status, message, body);
+    }
+    return new AgentSessionError('UNEXPECTED', status, `unexpected response (HTTP ${status}): ${JSON.stringify(body)}`, body);
+}
+export class AgentSessionClient {
+    http;
+    projectId;
+    constructor(opts) {
+        this.projectId = opts.projectId;
+        this.http = axios.create({
+            baseURL: opts.baseUrl.replace(/\/+$/, ''),
+            headers: opts.token ? { 'X-API-Key': opts.token } : {},
+            validateStatus: () => true,
+            timeout: 15_000,
+        });
+    }
+    path(suffix = '') {
+        return `/projects/${this.projectId}/agent-session${suffix}`;
+    }
+    /** POST …/agent-session → 201 session, 409 AGENT_SESSION_ACTIVE (SESSION_ACTIVE carries the live one). */
+    async start(body) {
+        const res = await this.http.post(this.path(), body);
+        if (res.status === 201 || res.status === 200)
+            return res.data;
+        throw agentErrorFromResponse(res.status, res.data);
+    }
+    /** POST …/agent-session/{uuid}/heartbeat → 200 session, 409 SESSION_NOT_ACTIVE, 403, 404. */
+    async heartbeat(uuid, body = {}) {
+        const res = await this.http.post(this.path(`/${encodeURIComponent(uuid)}/heartbeat`), body);
+        if (res.status === 200)
+            return res.data;
+        throw agentErrorFromResponse(res.status, res.data);
+    }
+    /** POST …/agent-session/{uuid}/release → 200 session (idempotent on terminal sessions). */
+    async release(uuid, body) {
+        const res = await this.http.post(this.path(`/${encodeURIComponent(uuid)}/release`), body);
+        if (res.status === 200)
+            return res.data;
+        throw agentErrorFromResponse(res.status, res.data);
+    }
+    /** GET …/agent-session → {session: live | recently ended | null}. */
+    async current() {
+        const res = await this.http.get(this.path());
+        if (res.status === 200)
+            return res.data.session;
+        throw agentErrorFromResponse(res.status, res.data);
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/api/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/api/agent.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,14 @@ 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;
+    /** Commit summary for every envelope this client sends (`meta.summary`), e.g. the agent step. */
+    summary?: string;
 }
 /**
  * Thin, faithful JPATCH/1 transport (RFC-0001 §5–§8). No retry logic here —
@@ -16,14 +21,21 @@ export declare class JpatchClient {
     readonly projectId: string;
     readonly actor: string | undefined;
     readonly origin: string | undefined;
+    readonly summary: 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,25 @@ export class JpatchClient {
     projectId;
     actor;
     origin;
+    summary;
+    assetsBaseUrl;
     constructor(opts) {
         this.projectId = opts.projectId;
         this.actor = opts.actor;
         this.origin = opts.origin;
+        this.summary = opts.summary;
+        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 +35,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 +63,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)