@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/AGENTSAM.md

@@ -8,6 +8,35 @@ conventional client variable for that machinery, never a human identity. Prefer
 “AgentSam executes through SAM…” over anthropomorphic phrasing. Architecture SSOT:
 `docs/architecture/SAM_KERNEL.md`.
 
+## AgentSam system model: deterministic machinery + LLM augmentation
+
+AgentSam is deliberately **not** “an LLM with tools.” It is a layered system:
+
+- **Old-school AgentSam / SAM** owns deterministic perception and execution: repository discovery, manifests, Git/Merkle evidence, AST/indexes, capability probes, provider/runtime discovery, schemas/migrations, routing constraints, typed operations, receipts, and verification.
+- **LLM AgentSam** augments that machinery where language-model reasoning is valuable: interpreting intent, resolving ambiguity, planning across valid options, composing/translating content or code, explaining evidence, and proposing transformations.
+- Deterministic evidence is authoritative when it can answer a question reliably. Do not ask an LLM to rediscover or guess facts that SAM can inspect, derive, or prove.
+- LLM output never overrides authorization, runtime capability evidence, manifests, migrations, provider state, product contracts, or verification receipts.
+- Core product workflows should remain inspectable and recoverable without hidden model reasoning. Emit typed/versioned receipts and explicit state transitions instead of treating a transcript as system state.
+- A model may recommend an action; trusted machinery decides whether the action is available, authorized, correctly scoped, and verifiably complete.
+
+This division is a product requirement: **LLMs supercharge AgentSam; they do not become the source of truth that holds AgentSam together.**
+
+## Portability, resale, and repurposability law
+
+AgentSam machinery is only reusable when an unrelated user can install or instantiate it without inheriting the operator's machine, identity, credentials, infrastructure, or monorepo.
+
+- A reusable package, app, template, or pipeline must not require Sam/operator-specific usernames, device names, absolute paths, domains, account IDs, database IDs, repository names, credentials, customer content, or private infrastructure assumptions.
+- Customer differences belong primarily in manifests, portable schema/data, company/brand rows, themes, provider grants, capability configuration, and content — **not source-code forks**.
+- Product apps under `apps/` are independently extractable. Advertised CLI/app capabilities must work from the published/packed artifact outside this monorepo; repo-local `file:` escape dependencies are not a valid release mechanism.
+- If the SDK advertises a datastore, provider, runtime, or backend as supported, the corresponding contract and implementation must ship together. Do not mark placeholders or “follow-up” adapters as supported production paths.
+- Generic packages stay generic. Product/customer seeds, deployment bindings, brand values, and app-specific migrations belong with the consuming app or installation.
+- Authorization and resource visibility are always principal/installation scoped. **No authorized resource must never fall back to a platform-owner resource.**
+- Product readiness is proven, not asserted. Use current manifests, machine inspection, clean-room packaging/install tests, migrations, doctors, and receipts. If a product cannot pass its declared contract, mark it non-graduated/unavailable rather than advertising readiness.
+- Extend existing authorities and adapters instead of creating parallel copies of Identity, Database Studio, Settings, themes, registries, or runtime state.
+
+Product graduation and resale enforcement are defined in
+[`docs/PRODUCT_LIFECYCLE.md`](docs/PRODUCT_LIFECYCLE.md).
+
 ## Execution
 
 - Infer routine implementation details when repository evidence makes the answer clear; do not block on unnecessary questions.
@@ -76,6 +105,17 @@ conventional client variable for that machinery, never a human identity. Prefer
 See [Storage architecture](docs/architecture/STORAGE.md) for enforcement and
 the current compatibility boundary.
 
+## Application contract (APP identity)
+
+Portable product apps follow [`docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md`](docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md).
+
+- **APP** = installable product (`agentsam.app.json`, immutable kebab-case `APP.id`).
+- **Not** an APP merely because it is under `apps/`, deployable, or an npm package.
+- Runtime identity: `import APP from "./agentsam.app.json"` — never `const APP = "agentsam-…"`.
+- `.agentsam/app.json` is host/install state (`app_id`), not a second product definition.
+- Package, Worker, route, desktop, and service names are separate namespaces with explicit pointers.
+- Gate: `agentsam app validate` / `npm run guard:apps`.
+
 ## Model and run policy
 
 - Model, reasoning effort, service tier, budget, and permissions are runtime configuration, not hidden prompt instructions.

package/README.md

@@ -76,19 +76,24 @@ Without a global install, use `npx @inneranimalmedia/agentsam-sdk create my-agen
 
 ## MCP setup
 
-Cloudflare's API MCP server uses `https://mcp.cloudflare.com/mcp`. Add that URL
-to the agent client you use, then complete its Cloudflare OAuth flow. For Codex:
+Register MCP servers into `~/.agentsam/mcp/` and sync IDE adapters:
 
 ```sh
-codex mcp add cloudflare-api --url https://mcp.cloudflare.com/mcp
-codex mcp login cloudflare-api
+agentsam mcp add inneranimalmedia --client cursor
+agentsam mcp add cloudflare-api --client cursor
+agentsam mcp list --bundles          # Cloudflare portal bundles + pack scopes
+agentsam mcp scopes cloudflare-bindings
+agentsam mcp doctor cloudflare-api
 ```
 
-`agentsam mcp add cloudflare-api --url https://mcp.cloudflare.com/mcp` is not
-currently an AgentSam CLI command. The repo's `.agentsam/config.json` is a
-portable project manifest, not an MCP client configuration; it cannot register
-this server for every agent tool on clone. Keep OAuth tokens in each client's
-credential store rather than committing them to the repository.
+Cloudflare MCP portals (bindings, builds, browser, …) are **server bundles**, not
+OAuth clients. AgentSam Cloudflare OAuth stays pack-scoped (`agentsam` pack includes
+`mcp-portals.read` / `mcp-portals.write`). Never request the full ~315-scope catalog
+at connect time — upgrade with `agentsam cloudflare permissions authorize --packs …`.
+
+Portal-hosted OAuth (Cloudflare’s own consent on `*.mcp.cloudflare.com`) is separate
+from AgentSam’s CF connection token. Keep tokens in each client’s credential store;
+do not commit them.
 
 ## Index an existing repository
 
@@ -126,6 +131,7 @@ read-only `repository.snapshot` composition primitive. See [Capabilities and pre
 | File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
 | Security, trust-boundary scan, and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
 | Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
+| Machine Intelligence (MINI/APP/WORLD ladder) | world-state / maturity (in progress) | [Machine Intelligence](docs/MACHINE_INTELLIGENCE.md) · [Tomorrow briefing](docs/plans/TOMORROW-MACHINE-FIRST-BRIEFING.md) |
 | Recon bounded-worker packets | `agentsam recon pack\|validate` | [Recon](docs/RECON.md) |
 | Local containers | `agentsam dockerize`; `/dockerize` | [Dockerize](docs/DOCKERIZE.md) |
 | Background indexing service | Docker `knowledge_service`; `/knowledge-service-client` | [Knowledge service](docs/knowledge-service.md) |

package/apps/README.md

@@ -2,6 +2,11 @@
 
 `apps/` is the development/authoring source of truth for runnable AgentSam product surfaces. Product apps are independently extractable and are intentionally **not** members of the SDK root npm workspace graph.
 
+**Lifecycle SSOT (validate → machine → prove → graduate → install):** [`docs/PRODUCT_LIFECYCLE.md`](../docs/PRODUCT_LIFECYCLE.md).  
+Use that doc for product map, graduation gates, scaffold vocabulary, old-school SAM + LLM layering, and how Identity/Desktop/Database lanes must stay extractable for resale.
+
+**Global agent/runtime law:** [`AGENTSAM.md`](../AGENTSAM.md). Product apps may specialize behavior through app-owned manifests/data, but they must not weaken the portability, principal-isolation, deterministic-evidence, or receipt-backed completion rules.
+
 ## Product app law
 
 Every deployable product app follows the same ownership boundary:

package/apps/cad-creator/README.md

@@ -462,7 +462,7 @@ If you want, I can also **put this directly into `SamPrimeaux/AgentSamCadCreatio
 CAD Creator is packaged independently from the core SDK as:
 
 ```text
-@inneranimalmedia/agentsam-sdk-cad-creator
+@inneranimalmedia/agentsam-cad-creator
 ```
 
 The package deliberately contains both:
@@ -477,13 +477,13 @@ It deliberately does **not** publish `reference/`, donor ZIPs/snapshots, `node_m
 Once published:
 
 ```bash
-npx @inneranimalmedia/agentsam-sdk-cad-creator
+npx @inneranimalmedia/agentsam-cad-creator
 ```
 
 or after installing it:
 
 ```bash
-npm install @inneranimalmedia/agentsam-sdk-cad-creator
+npm install @inneranimalmedia/agentsam-cad-creator
 npx agentsam-cad-creator --port 3000
 ```
 
@@ -500,7 +500,7 @@ The normal Design Studio shell loads first. The MuJoCo/robotics workspace remain
 ### Materialize an editable project
 
 ```bash
-npx @inneranimalmedia/agentsam-sdk-cad-creator scaffold ./my-cad-app
+npx @inneranimalmedia/agentsam-cad-creator scaffold ./my-cad-app
 cd ./my-cad-app
 npm install
 npm run dev

package/apps/cad-creator/shared/cad/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-cad-shared",
-  "version": "0.0.0",
+  "version": "2.6.7",
   "private": true,
   "type": "module",
   "exports": {

package/apps/client-cms-editor/AGENTS.md

@@ -0,0 +1,17 @@
+# Client CMS Editor workspace law
+
+- Product authority is the installable npm package `@inneranimalmedia/client-cms-editor`, not registry rows and not host-app vite aliases.
+- Donor behavioral authority: `studio-cms-editor` + `reference/harvest/plans/CMS-EDITOR-HARVEST.md`. Encode requirements in `acceptance/cms-parity.v1.json`.
+- This app is an independent workspace root. Keep one active lockfile at `apps/client-cms-editor/package-lock.json`.
+- Do not add its frontend/backend/shared packages to the SDK root workspace list.
+- Do not import from sibling host apps for runtime authority.
+- `shared/cms` owns pure CMS editor/publication/adapter/config contracts only; no React and no vendor runtime SDKs.
+- Persistence adapters implement `CmsEditorAdapter` (`shared/cms/src/adapter.ts`). Never treat localStorage as an authority or scaffold persistence choice.
+- `backend/` is a portable host bridge. Consumer `/api/cms/*` routes are one implementation of the adapter contract — not the product architecture.
+- Do not invent product resources (Worker binding labels, fixed account/database IDs, or deployment hostnames) inside this package.
+- Public CMS runtime must remain smaller than the authoring app. Do not ship Monaco, terminal, browser automation, auth-admin, or a full agent workbench to anonymous visitors.
+- Session caches and containers are never auth/identity authority.
+- CMS agent context must be explicit. Never scrape editor/site state silently.
+- Prefer structured/versioned section data for publication. Arbitrary executable editor HTML is not a public-content authority.
+- Heuristic is a stock starter pack (`starter-packs/heuristic`), not fake demo mode. Fake write short-circuits are forbidden.
+- Before calling a release good: `npm run verify:cms` must pass, then a fresh empty-folder install of the packed/published tarball must boot the editor.

package/apps/client-cms-editor/IMPORT_PROVENANCE.json

@@ -0,0 +1,8 @@
+{
+  "source_repository": "SamPrimeaux/inneranimalmedia",
+  "source_path": "packages/client-cms-editor",
+  "source_commit": "5957af19dfb67e1551d0174b72141dd65acc4972",
+  "source_ref": "origin/main",
+  "imported_as": "apps/client-cms-editor",
+  "note": "Imported as real files, then normalized into an independent npm workspace root. Canonical platform CMS server/domain code remains in inneranimalmedia src/core/agentsam/cms until a dedicated agentsam-cms package extraction."
+}

package/apps/client-cms-editor/README.md

@@ -0,0 +1,100 @@
+# AgentSam Client CMS
+
+Reusable, white-label **website + CMS application kit** published as `@inneranimalmedia/client-cms-editor`.
+
+A developer can scaffold a customer website, run it completely locally, browse the public pages and CMS, customize or import a theme, edit and publish through real local persistence, then connect identity/cloud/deployment providers without replacing the CMS or content model.
+
+**Authority order:** donor behavior → this npm package → adapters under the UX → registry receipts last.  
+See [`ALPHA.md`](./ALPHA.md) and [`acceptance/cms-parity.v1.json`](./acceptance/cms-parity.v1.json).
+
+```text
+scaffold
+  ↓
+customer project
+  ├── public multi-page site (header / pages / footer)
+  └── protected CMS (pages · sections · blocks · media · theme · draft/preview/publish)
+        ↓
+same CmsEditorAdapter authority
+```
+
+## First-run (local before cloud)
+
+```bash
+npx agentsam-cms create my-site --starter heuristic   # or blank | import --theme ./old-theme.zip
+cd my-site
+npx agentsam-cms dev
+```
+
+Then browse:
+
+| URL | Surface |
+|-----|---------|
+| `http://localhost:4317/` | Published public home |
+| `http://localhost:4317/about` | Published interior page |
+| `http://localhost:4317/cms` | Protected CMS (local-dev principal by default) |
+
+No GitHub / Cloudflare / Supabase account is required to inspect or use the local product.
+
+### Starters
+
+| Starter | Meaning |
+|---------|---------|
+| **Heuristic** | Built-in multipage starter pack |
+| **Blank** | Empty durable site shell |
+| **IASF** | Stock Inner Animal Storefront (`--starter iasf`) |
+| **Import existing theme** | Directory or `.zip` → safe intake → ThemePack → `installStarterPack` |
+
+Imported themes are normalized into the **same** `CmsStarterPack` contract Heuristic uses. The editor never parses ZIP/Liquid itself — import/refinery tooling does.
+
+## Architecture
+
+```text
+CmsEditor / public renderer
+        ↓
+CmsEditorAdapter
+
+LOCAL     →  ./sqlite-adapter  (Node / node:sqlite)
+CLOUD     →  D1 + R2 adapter
+OTHER     →  HTTP / custom
+```
+
+- Browser CMS UI does **not** import `node:sqlite`.
+- `./sqlite-adapter`, `./import`, and `./local` are Node/local-runtime surfaces.
+- Root package `engines` stay cross-runtime (`node >= 20`); only `./sqlite-adapter` documents the `node:sqlite` requirement.
+
+## Auth boundary
+
+`/cms` is protected through a portable `CmsAuthHost` contract. Local scaffolds use an explicit local-development principal. Stock sign-in options for OAuth / CMS prebuild:
+
+- **Cloudflare** — `createStockCmsAuthHost('cloudflare')`
+- **Google** — `createStockCmsAuthHost('google')`
+- **Inner Animal Media** — `createStockCmsAuthHost('inneranimalmedia')`
+- **ChatGPT** — `createStockCmsAuthHost('chatgpt')` (Apps SDK hosted headers)
+
+Consumers wire OAuth/OIDC/their identity service without rebuilding route protection.
+
+## Persistence
+
+| Adapter | Role |
+|---------|------|
+| SQLite | desktop/offline authority via `./sqlite-adapter` |
+| D1 + R2 | cloud authority from **proven** OAuth resources |
+| HTTP / custom | consumer backend |
+| localStorage | UI chrome cache only — never scaffolded as authority |
+
+## Development / gates
+
+```bash
+cd apps/client-cms-editor
+npm ci
+npm run build
+npm run verify:cms
+# package + memory + sqlite durability + theme import + browser isolation + pack/bin
+```
+
+Release (`private:false` required):
+
+```bash
+npm run verify:cms-release
+npm publish --tag alpha --access public
+```

package/apps/client-cms-editor/agentsam.app.json

@@ -0,0 +1,74 @@
+{
+  "schema": "agentsam.app.v1",
+  "id": "client-cms-editor",
+  "product_id": "cms",
+  "name": "AgentSam Website + CMS Kit",
+  "kind": "app",
+  "package": "@inneranimalmedia/client-cms-editor",
+  "version": "0.1.0-alpha.0",
+  "description": "Reusable white-label website + CMS kit: multipage public site, protected authoring dashboard, local SQLite, Heuristic/Blank/Import Theme starters, pluggable auth and deployment adapters.",
+  "entrypoints": {
+    "frontend": "./frontend",
+    "backend": "./backend",
+    "cli": "./bin/agentsam-cms.js",
+    "public_renderer": "./local/public-renderer.ts",
+    "import_refinery": "./import/index.ts"
+  },
+  "capabilities": [
+    "cms",
+    "media",
+    "templates",
+    "admin_content",
+    "theme_import",
+    "local_storefront",
+    "auth_boundary"
+  ],
+  "provides": [
+    "cms.editor",
+    "cms.public_renderer",
+    "cms.templates",
+    "cms.media.library",
+    "cms.theme_import",
+    "workspace.panel"
+  ],
+  "surfaces": [
+    "public-site",
+    "store",
+    "theme-editor",
+    "cms-editor",
+    "templates",
+    "media-library",
+    "agentsam"
+  ],
+  "starters": [
+    "heuristic",
+    "blank",
+    "import-existing-theme"
+  ],
+  "runtime": {
+    "local_preview": "ready",
+    "source_scaffold": "ready",
+    "local_sqlite": "ready",
+    "theme_import": "ready",
+    "cloudflare": "adapter-ready",
+    "github": "source-ready",
+    "browser": true,
+    "local": true
+  },
+  "commands": {
+    "create": "agentsam-cms create <directory> --starter heuristic|blank|import",
+    "dev": "agentsam-cms dev",
+    "import_theme": "agentsam-cms import-theme <source> --out <dir>",
+    "doctor": "agentsam-cms doctor",
+    "info": "agentsam-cms info"
+  },
+  "bin": "bin/agentsam-cms.js",
+  "install": {
+    "command": "agentsam-cms create",
+    "selector": "client-cms-editor",
+    "paths": [
+      "/install/cms",
+      "/install/client-cms-editor"
+    ]
+  }
+}

package/apps/client-cms-editor/backend/README.md

@@ -0,0 +1,5 @@
+# CMS backend bridge
+
+This workspace package is the portable CMS client/backend boundary: HTTP API calls, model mapping, routing, preview messages and storefront URL helpers. It does not own the platform CMS server implementation or identity authority.
+
+The current platform implementation remains `inneranimalmedia/src/core/agentsam/cms/` until it is extracted into reusable `agentsam-cms-*` packages.

package/apps/client-cms-editor/backend/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@inneranimalmedia/agentsam-cms-backend",
+  "version": "2.6.7",
+  "description": "Internal CMS backend bridge (bundled into @inneranimalmedia/client-cms-editor \u2014 not published separately).",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api": "./src/api/client.ts",
+    "./model": "./src/model.ts",
+    "./preview": "./src/preview/bridge.ts",
+    "./routing": "./src/routing/index.js"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@inneranimalmedia/agentsam-cms-shared": "2.6.7"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "apps/client-cms-editor/backend"
+  },
+  "files": [
+    "src"
+  ],
+  "agentsam": {
+    "releaseIgnore": [
+      "worker",
+      "wrangler.jsonc"
+    ]
+  }
+}

package/apps/client-cms-editor/backend/src/api/client.ts

@@ -0,0 +1,233 @@
+/**
+ * HTTP CMS API client — real fetch only.
+ * Never fabricates success, never falls back to demo fixtures on localhost.
+ */
+import { mapCmsEditorBlock, mapCmsEditorBootstrap, mapCmsEditorPage, mapCmsEditorSection } from '../../../shared/cms/src/map';
+import type { CmsEditorBlock, CmsEditorPage, CmsEditorSection } from '../../../shared/cms/src/editor-types';
+
+type Json = Record<string, any>;
+type ApiInit = Omit<RequestInit, 'body'> & { body?: any };
+
+async function api<T extends Json = Json>(path: string, init: ApiInit = {}): Promise<T> {
+  const headers = new Headers(init.headers);
+  let body = init.body;
+  if (body != null && !(body instanceof FormData) && typeof body !== 'string') {
+    headers.set('Content-Type', 'application/json');
+    body = JSON.stringify(body);
+  }
+  const response = await fetch(path, { ...init, body, headers, credentials: 'include', cache: 'no-store' });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message = payload?.message || payload?.error || response.statusText || 'Request failed';
+    throw Object.assign(new Error(String(message)), { status: response.status, payload });
+  }
+  return payload as T;
+}
+
+export async function getCmsEditorBootstrap(projectSlug: string, focusPageId?: string | null) {
+  if (!String(projectSlug || '').trim()) {
+    throw new Error('project_slug_required');
+  }
+  const params = new URLSearchParams({ project_slug: projectSlug, site: projectSlug });
+  if (focusPageId) params.set('page_id', focusPageId);
+  return mapCmsEditorBootstrap(await api<Json>(`/api/cms/bootstrap?${params}`), projectSlug);
+}
+
+export async function getCmsEditorPagePreview(pageId: string, mode: 'draft' | 'published' = 'draft') {
+  return api<Json>(`/api/cms/pages/${encodeURIComponent(pageId)}?preview=${encodeURIComponent(mode)}`);
+}
+
+export const saveCmsEditorSection = (sectionId: string, fields: Record<string, any>, css?: Record<string, any>) =>
+  api(`/api/cms/sections/${encodeURIComponent(sectionId)}`, {
+    method: 'PUT',
+    body: { section_data: { ...fields, ...(css && Object.keys(css).length ? { css_override: css } : {}) } },
+  });
+
+export const renameCmsEditorSection = (sectionId: string, sectionName: string) =>
+  api(`/api/cms/sections/${encodeURIComponent(sectionId)}`, { method: 'PUT', body: { section_name: sectionName } });
+
+export const reorderCmsEditorSections = (pageId: string, sections: CmsEditorSection[]) =>
+  api('/api/cms/sections/reorder', {
+    method: 'POST',
+    body: { page_id: pageId, order: sections.map((section, index) => ({ id: section.id, sort_order: (index + 1) * 10 })) },
+  });
+
+export const setCmsEditorSectionVisibility = (sectionId: string, visible: boolean) =>
+  api(`/api/cms/sections/${encodeURIComponent(sectionId)}/visibility`, {
+    method: 'POST',
+    body: { is_visible: visible ? 1 : 0 },
+  });
+
+export async function createCmsEditorSection(pageId: string, name: string, fields: Record<string, any>, sortOrder: number) {
+  const result = await api<Json>('/api/cms/sections', {
+    method: 'POST',
+    body: {
+      page_id: pageId,
+      section_type: name.toLowerCase().replace(/\s+/g, '-'),
+      section_name: name,
+      section_data: fields,
+      sort_order: sortOrder,
+    },
+  });
+  return mapCmsEditorSection(result.section || { id: result.id, section_name: name, section_type: name, section_data: fields, is_visible: 1 });
+}
+
+export async function deleteCmsEditorSection(sectionId: string) {
+  return api(`/api/cms/sections/${encodeURIComponent(sectionId)}`, { method: 'DELETE' });
+}
+
+export async function listCmsEditorBlocks(sectionId: string) {
+  const result = await api<Json>(`/api/cms/blocks?section_id=${encodeURIComponent(sectionId)}`);
+  return (result.blocks || result.components || []).map((row: Json) => mapCmsEditorBlock(row, sectionId));
+}
+
+export async function createCmsEditorBlock(sectionId: string, type: string, data: Record<string, any>, sortOrder = 10) {
+  const blockType = String(type || 'text').trim() || 'text';
+  const result = await api<Json>('/api/cms/blocks', {
+    method: 'POST',
+    body: {
+      section_id: sectionId,
+      type: blockType,
+      block_type: blockType,
+      component_type: blockType,
+      data,
+      sort_order: sortOrder,
+    },
+  });
+  return mapCmsEditorBlock(result.block || result.component || { id: result.id, section_id: sectionId, type: blockType, data }, sectionId);
+}
+
+export const saveCmsEditorBlock = (block: CmsEditorBlock) =>
+  api(`/api/cms/blocks/${encodeURIComponent(block.id)}`, {
+    method: 'PUT',
+    body: { block_data: block.data, block_type: block.type, type: block.type, component_type: block.type },
+  });
+
+export const setCmsEditorBlockVisibility = (blockId: string, visible: boolean) =>
+  api(`/api/cms/blocks/${encodeURIComponent(blockId)}/visibility`, {
+    method: 'POST',
+    body: { is_visible: visible ? 1 : 0 },
+  });
+
+export const reorderCmsEditorBlocks = (blocks: CmsEditorBlock[]) =>
+  api('/api/cms/blocks/reorder', {
+    method: 'POST',
+    body: { order: blocks.map((block, index) => ({ id: block.id, sort_order: (index + 1) * 10 })) },
+  });
+
+export async function deleteCmsEditorBlock(blockId: string) {
+  return api(`/api/cms/blocks/${encodeURIComponent(blockId)}`, { method: 'DELETE' });
+}
+
+export async function createCmsEditorPage(projectSlug: string, input: { title: string; slug: string; type: string }) {
+  const slug = input.slug.replace(/^\/+/, '') || 'untitled';
+  const result = await api<Json>('/api/cms/pages', {
+    method: 'POST',
+    body: {
+      project_id: projectSlug,
+      title: input.title || 'Untitled',
+      slug,
+      route_path: `/${slug}`,
+      page_type: input.type,
+      status: 'draft',
+      content: '',
+    },
+  });
+  return mapCmsEditorPage({
+    ...result,
+    id: result.id,
+    title: input.title,
+    slug,
+    route_path: result.route_path || `/${slug}`,
+    page_type: input.type,
+    status: 'draft',
+  });
+}
+
+export async function deleteCmsEditorPage(pageId: string) {
+  return api(`/api/cms/pages/${encodeURIComponent(pageId)}`, { method: 'DELETE' });
+}
+
+export const saveCmsEditorPageMeta = (page: CmsEditorPage) => {
+  const route = page.slug.startsWith('/') ? page.slug : `/${String(page.slug || '').replace(/^\/+/, '')}`;
+  const normalizedRoute = route.length > 1 ? route.replace(/\/+$/, '') : route || '/';
+  const slug = normalizedRoute === '/' ? 'home' : normalizedRoute.replace(/^\/+/, '') || 'untitled';
+  return api(`/api/cms/pages/${encodeURIComponent(page.id)}`, {
+    method: 'PUT',
+    body: {
+      title: page.title,
+      route_path: normalizedRoute,
+      slug,
+      page_type: page.type,
+      seo_title: page.metaTitle,
+      meta_description: page.metaDescription,
+    },
+  });
+};
+
+export const publishCmsEditorPage = (pageId: string) =>
+  api(`/api/cms/pages/${encodeURIComponent(pageId)}/publish`, { method: 'POST', body: {} });
+
+export const saveCmsEditorThemeVars = (projectSlug: string, vars: Record<string, string>) =>
+  api('/api/cms/theme-vars', { method: 'PATCH', body: { project_slug: projectSlug, vars } });
+
+export async function getCmsEditorAssets() {
+  const result = await api<Json>('/api/cms/assets');
+  return (result.assets || []).map((asset: Json, index: number) => ({
+    id: asset.id || index,
+    name: asset.original_filename || asset.filename || asset.label || 'Asset',
+    type: String(asset.mime_type || '').startsWith('video/')
+      ? 'Video'
+      : String(asset.mime_type || '').includes('font')
+        ? 'Font'
+        : String(asset.mime_type || '').includes('pdf')
+          ? 'Document'
+          : 'Image',
+    size: asset.content_size_bytes ? `${(Number(asset.content_size_bytes) / 1e6).toFixed(1)} MB` : '—',
+    color: ['#5346db', '#d2e9df', '#ebc59d', '#25302b', '#705cf0', '#e6e0d3'][index % 6],
+    previewUrl: asset.thumbnail_url || asset.cdn_url || asset.public_url || null,
+  }));
+}
+
+export async function getCmsEditorTemplates() {
+  const result = await api<Json>('/api/cms/templates');
+  return (result.templates || [])
+    .map((row: Json) => ({
+      id: String(row.id || ''),
+      name: String(row.template_name || row.iam_label || row.slug || 'Template'),
+      type: String(row.template_type || 'section'),
+      category: String(row.category || 'General'),
+      slug: row.slug ? String(row.slug) : null,
+      previewImageUrl: row.preview_image_url ? String(row.preview_image_url) : null,
+      hasHtml: Boolean(row.source_html_r2_key),
+    }))
+    .filter((row: { id: string }) => row.id);
+}
+
+export async function applyCmsEditorTemplate(
+  templateId: string,
+  input: { pageId?: string | null; projectSlug?: string | null } = {},
+) {
+  return api<Json>(`/api/cms/templates/${encodeURIComponent(templateId)}/apply`, {
+    method: 'POST',
+    body: {
+      page_id: input.pageId || undefined,
+      project_slug: input.projectSlug || undefined,
+    },
+  });
+}
+
+export async function getCmsEditorContacts() {
+  const result = await api<Json>('/api/user/contacts');
+  return (result.contacts || []).map((row: Json, index: number) => ({
+    id: index,
+    name: String(row.name || row.display_name || row.email || 'Contact'),
+    email: String(row.email || ''),
+    source: String(row.source || 'Contact form'),
+    date: String(row.updated_at || row.created_at || 'Recently'),
+    tag: Array.isArray(row.tags) ? row.tags[0] || 'Lead' : row.tag || 'Lead',
+  }));
+}
+
+export const activateCmsEditorTheme = (themeSlug: string, accent?: string) =>
+  api('/api/cms/themes/activate', { method: 'POST', body: { slug: themeSlug, accent } });

package/apps/client-cms-editor/backend/src/index.ts

@@ -0,0 +1,6 @@
+export * from './api/client';
+export * from '../../shared/cms/src/index';
+export * from './model';
+export * from './preview/bridge';
+export * from './preview/urls';
+export * from './storefront';

package/apps/client-cms-editor/backend/src/model.ts

@@ -0,0 +1,11 @@
+/** @deprecated Prefer shared/cms map helpers — kept as re-export for transitional imports. */
+export {
+  parseCmsEditorObject,
+  cmsEditorInitials,
+  mapCmsEditorBlock,
+  mapCmsEditorSection,
+  mapCmsEditorPage,
+  mapCmsEditorBootstrap,
+  selectCmsEditorTarget,
+} from '../../shared/cms/src/map';
+export { emptyCmsEditorSelection } from '../../shared/cms/src/editor-types';