@consciousclouds/canvas-sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog — @consciousclouds/canvas-sdk
+
+Versioned on the independent frontend-SDK lifecycle (NOT `contract_version`).
+
+## [0.1.0] — 2026-06-09
+
+### Added
+
+- `CanvasDefinition` types (discriminated union: `stat-card`, `data-table`,
+  `service-health`), derived from `platform/contracts/canvas/v1/`.
+- Component Registry allowlist (`stat-card`, `data-table`, `service-health`)
+  with `active | deprecated | removed` lifecycle.
+- `IExperienceProvider` adapter contract + `ExperienceAdapterRegistry`
+  (explicit registration, fail-closed on unknown product).
+- `validateCanvasDefinition()` (zod) and a thin `createCanvasClient()`.
+
+### Notes
+
+- Authoritative contract is the JSON Schema under
+  `platform/contracts/canvas/v1/`. These TypeScript types mirror it; the
+  conformance test guards drift. Full schema→TS codegen is a follow-up.
+- Phase 1 slice: deterministic selection only, no LLM, no persistence.

package/README.md

@@ -0,0 +1,29 @@
+# @consciousclouds/canvas-sdk
+
+Types + contracts for the Intelligence Runtime **Canvas** layer. The server
+emits a `CanvasDefinition`; a consumer renders it from an **approved
+component allowlist** (`@consciousclouds/canvas-runtime` is the React
+renderer). The model may *select* components; it may never *invent* UI.
+
+Framework-agnostic and domain-agnostic — no product nouns, no React. The
+authoritative contract is the JSON Schema under
+`platform/contracts/canvas/v1/`; these types derive from it.
+
+## Exports
+
+| Subpath | What |
+|---|---|
+| `.` | everything below |
+| `./types` | `CanvasDefinition`, `CanvasNode`, node + prop types |
+| `./registry` | `ComponentRegistry`, `COMPONENT_REGISTRY`, `isApprovedComponent()` |
+| `./contracts` | `IExperienceProvider`, `ExperienceAdapterRegistry`, scoping types |
+| `./validate` | `validateCanvasDefinition()`, `NODE_TYPES` |
+| `./client` | `createCanvasClient()` — thin HTTP wrapper |
+
+## Adapter authors (e.g. ENO)
+
+Implement `IExperienceProvider` (domain methods like `getWine()` live in your
+concrete adapter, never in this SDK), register it explicitly at your
+composition root, and let the runtime call it. The runtime authorizes every
+request against the *caller's* identity (see the design lock's four-gate
+model) — your adapter never decides authorization.

package/dist/client/canvas-client.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Thin canvas client — types + HTTP wrapper only (the locked SDK rule).
+ * No business logic, no caching, no orchestration.
+ *
+ * @packageDocumentation
+ */
+import type { CanvasDefinition } from '../types/canvas.js';
+export interface CanvasClientOptions {
+    /** Base URL of the gateway, e.g. https://gateway.example.com */
+    baseUrl: string;
+    /** Optional fetch implementation (defaults to global fetch). */
+    fetchImpl?: typeof fetch;
+    /** Optional per-request headers (auth, correlation, tenant). */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Validate the response against the schema (default true). */
+    validate?: boolean;
+}
+export interface CanvasClient {
+    /** GET /api/v1/canvas/:product/:resource → CanvasDefinition */
+    getCanvas(product: string, resource: string, params?: Record<string, string>): Promise<CanvasDefinition>;
+}
+export declare class CanvasClientError extends Error {
+    readonly status?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, details?: unknown | undefined);
+}
+export declare function createCanvasClient(options: CanvasClientOptions): CanvasClient;
+//# sourceMappingURL=canvas-client.d.ts.map

package/dist/client/canvas-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-client.d.ts","sourceRoot":"","sources":["../../src/client/canvas-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,SAAS,CACP,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,MAAM,CAAC,EAAE,MAAM;aACf,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAoC7E"}

package/dist/client/canvas-client.js

@@ -0,0 +1,50 @@
+/**
+ * Thin canvas client — types + HTTP wrapper only (the locked SDK rule).
+ * No business logic, no caching, no orchestration.
+ *
+ * @packageDocumentation
+ */
+import { validateCanvasDefinition } from '../validate/canvas.js';
+export class CanvasClientError extends Error {
+    constructor(message, status, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.name = 'CanvasClientError';
+    }
+}
+export function createCanvasClient(options) {
+    const base = options.baseUrl.replace(/\/$/, '');
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    const validate = options.validate ?? true;
+    return {
+        async getCanvas(product, resource, params) {
+            const qs = params ? `?${new URLSearchParams(params).toString()}` : '';
+            const url = `${base}/api/v1/canvas/${encodeURIComponent(product)}/${encodeURIComponent(resource)}${qs}`;
+            const headers = options.headers ? await options.headers() : {};
+            const res = await doFetch(url, {
+                method: 'GET',
+                headers: { Accept: 'application/json', ...headers },
+            });
+            if (!res.ok) {
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    body = undefined;
+                }
+                throw new CanvasClientError(`Canvas request failed (${res.status})`, res.status, body);
+            }
+            const json = (await res.json());
+            if (!validate)
+                return json;
+            const result = validateCanvasDefinition(json);
+            if (!result.ok || !result.data) {
+                throw new CanvasClientError('Canvas response failed validation', res.status, result.errors);
+            }
+            return result.data;
+        },
+    };
+}
+//# sourceMappingURL=canvas-client.js.map

package/dist/client/canvas-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-client.js","sourceRoot":"","sources":["../../src/client/canvas-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAsBjE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YACE,OAAe,EACC,MAAe,EACf,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAS;QACf,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAE1C,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM;YACvC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,MAAM,GAAG,GAAG,GAAG,IAAI,kBAAkB,kBAAkB,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC;YACxG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAE/D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE;gBAC7B,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE;aACpD,CAAC,CAAC;YAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,IAAI,IAAa,CAAC;gBAClB,IAAI,CAAC;oBACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;gBAC1B,CAAC;gBAAC,MAAM,CAAC;oBACP,IAAI,GAAG,SAAS,CAAC;gBACnB,CAAC;gBACD,MAAM,IAAI,iBAAiB,CAAC,0BAA0B,GAAG,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACzF,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAY,CAAC;YAC3C,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAwB,CAAC;YAE/C,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC/B,MAAM,IAAI,iBAAiB,CAAC,mCAAmC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAC9F,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/contracts/experience-adapter.d.ts

@@ -0,0 +1,83 @@
+/**
+ * IExperienceProvider — the per-product adapter contract.
+ *
+ * Modeled 1:1 on runtime-orchestrator's IRuntimeAdapter (strategy pattern,
+ * idempotent by correlationId, explicit registration). Domain-agnostic: no
+ * product nouns appear here — getWine()/getEnvironment() live ONLY in the
+ * concrete adapter a product ships. The runtime calls adapters, never an app
+ * database.
+ *
+ * Terminology lock: `provider` = this interface; `adapter` = a concrete impl.
+ *
+ * @packageDocumentation
+ */
+/** Registry key for a registered product (closed at registration, not in the contract). */
+export type ProductId = string;
+/**
+ * Scope binding declared at registration. Maps to consul scope_type
+ * (only `global | tenant` exist) plus the project_id boundary.
+ */
+export interface AdapterScopeBinding {
+    /** consul RBAC scope. There is no `platform` scope_type in the platform. */
+    scopeType: 'global' | 'tenant';
+    /** When true, the request MUST carry projectId and passes the project-access gate. */
+    projectBound?: boolean;
+}
+/**
+ * Per-request context. Extends node-sdk RequestContext fields; the runtime
+ * fills it from the *caller's* identity (never the runtime's own). Idempotent
+ * by correlationId.
+ */
+export interface ExperienceContext {
+    correlationId: string;
+    tenantId: string;
+    userId: string;
+    projectId?: string;
+    /** Requested view/resource key (allowlisted by the runtime). */
+    resource: string;
+    params?: Record<string, unknown>;
+}
+/** Product-neutral data the runtime reads to assemble a context package. */
+export interface ExperienceResult {
+    data: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/** The registered-adapter interface (parallels IRuntimeAdapter). */
+export interface IExperienceProvider {
+    /** Registry key + log routing (cf. IRuntimeAdapter.name). */
+    readonly productId: ProductId;
+    /** Bound at registration, immutable. */
+    readonly scope: AdapterScopeBinding;
+    /** Read product data. IDEMPOTENT by correlationId. */
+    fetch(ctx: ExperienceContext): Promise<ExperienceResult>;
+    /** Optional mutating action (requires adapter.invoke + non-read project role). */
+    action?(ctx: ExperienceContext): Promise<ExperienceResult>;
+    /** Clear idempotency cache for a correlation id (same hook as IRuntimeAdapter). */
+    clearCache?(correlationId: string): void;
+}
+export interface IExperienceAdapterRegistry {
+    set(productId: ProductId, adapter: IExperienceProvider): void;
+    /** Throws ProductNotRegisteredError if absent — fail closed, no default. */
+    get(productId: ProductId): IExperienceProvider;
+    has(productId: ProductId): boolean;
+    list(): ProductId[];
+}
+export declare class ProductNotRegisteredError extends Error {
+    readonly productId: ProductId;
+    readonly code = "PRODUCT_NOT_REGISTERED";
+    constructor(productId: ProductId);
+}
+/**
+ * Closed-allowlist adapter registry. Unlike the runtime-orchestrator factory
+ * there is NO lazy-create fallback — every product adapter requires external
+ * config, so an unregistered product fails closed.
+ */
+export declare class ExperienceAdapterRegistry implements IExperienceAdapterRegistry {
+    private readonly adapters;
+    set(productId: ProductId, adapter: IExperienceProvider): void;
+    get(productId: ProductId): IExperienceProvider;
+    has(productId: ProductId): boolean;
+    list(): ProductId[];
+}
+export declare function createExperienceAdapterRegistry(): ExperienceAdapterRegistry;
+//# sourceMappingURL=experience-adapter.d.ts.map

package/dist/contracts/experience-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experience-adapter.d.ts","sourceRoot":"","sources":["../../src/contracts/experience-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,sFAAsF;IACtF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,sDAAsD;IACtD,KAAK,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzD,kFAAkF;IAClF,MAAM,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3D,mFAAmF;IACnF,UAAU,CAAC,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC9D,4EAA4E;IAC5E,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAAC;IAC/C,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC;IACnC,IAAI,IAAI,SAAS,EAAE,CAAC;CACrB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;aAEtB,SAAS,EAAE,SAAS;IADhD,QAAQ,CAAC,IAAI,4BAA4B;gBACb,SAAS,EAAE,SAAS;CAIjD;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,0BAA0B;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IAEtE,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAI7D,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB;IAM9C,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO;IAIlC,IAAI,IAAI,SAAS,EAAE;CAGpB;AAED,wBAAgB,+BAA+B,IAAI,yBAAyB,CAE3E"}

package/dist/contracts/experience-adapter.js

@@ -0,0 +1,50 @@
+/**
+ * IExperienceProvider — the per-product adapter contract.
+ *
+ * Modeled 1:1 on runtime-orchestrator's IRuntimeAdapter (strategy pattern,
+ * idempotent by correlationId, explicit registration). Domain-agnostic: no
+ * product nouns appear here — getWine()/getEnvironment() live ONLY in the
+ * concrete adapter a product ships. The runtime calls adapters, never an app
+ * database.
+ *
+ * Terminology lock: `provider` = this interface; `adapter` = a concrete impl.
+ *
+ * @packageDocumentation
+ */
+export class ProductNotRegisteredError extends Error {
+    constructor(productId) {
+        super(`No experience adapter registered for product '${productId}'`);
+        this.productId = productId;
+        this.code = 'PRODUCT_NOT_REGISTERED';
+        this.name = 'ProductNotRegisteredError';
+    }
+}
+/**
+ * Closed-allowlist adapter registry. Unlike the runtime-orchestrator factory
+ * there is NO lazy-create fallback — every product adapter requires external
+ * config, so an unregistered product fails closed.
+ */
+export class ExperienceAdapterRegistry {
+    constructor() {
+        this.adapters = new Map();
+    }
+    set(productId, adapter) {
+        this.adapters.set(productId, adapter);
+    }
+    get(productId) {
+        const adapter = this.adapters.get(productId);
+        if (!adapter)
+            throw new ProductNotRegisteredError(productId);
+        return adapter;
+    }
+    has(productId) {
+        return this.adapters.has(productId);
+    }
+    list() {
+        return [...this.adapters.keys()];
+    }
+}
+export function createExperienceAdapterRegistry() {
+    return new ExperienceAdapterRegistry();
+}
+//# sourceMappingURL=experience-adapter.js.map

package/dist/contracts/experience-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experience-adapter.js","sourceRoot":"","sources":["../../src/contracts/experience-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2DH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAElD,YAA4B,SAAoB;QAC9C,KAAK,CAAC,iDAAiD,SAAS,GAAG,CAAC,CAAC;QAD3C,cAAS,GAAT,SAAS,CAAW;QADvC,SAAI,GAAG,wBAAwB,CAAC;QAGvC,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAAyB;IAAtC;QACmB,aAAQ,GAAG,IAAI,GAAG,EAAkC,CAAC;IAmBxE,CAAC;IAjBC,GAAG,CAAC,SAAoB,EAAE,OAA4B;QACpD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,GAAG,CAAC,SAAoB;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,yBAAyB,CAAC,SAAS,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,SAAoB;QACtB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;CACF;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO,IAAI,yBAAyB,EAAE,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { CanvasVersion, Binding, ActionDef, CanvasNodeBase, StatCardProps, StatCardNode, DataTableColumn, DataTableProps, DataTableNode, ServiceHealthItem, ServiceHealthProps, ServiceHealthNode, CanvasNode, CanvasNodeType, CanvasLayout, CanvasDefinition, } from './types/canvas.js';
+export type { ComponentStatus, ComponentRegistryEntry, ComponentRegistry, } from './registry/component-registry.js';
+export { COMPONENT_REGISTRY, getComponentEntry, isApprovedComponent, isDeprecatedComponent, } from './registry/component-registry.js';
+export type { ProductId, AdapterScopeBinding, ExperienceContext, ExperienceResult, IExperienceProvider, IExperienceAdapterRegistry, } from './contracts/experience-adapter.js';
+export { ProductNotRegisteredError, ExperienceAdapterRegistry, createExperienceAdapterRegistry, } from './contracts/experience-adapter.js';
+export type { ValidationResult } from './validate/canvas.js';
+export { NODE_TYPES, ZOD_NODE_TYPES, canvasNodeSchema, canvasDefinitionSchema, validateCanvasDefinition, } from './validate/canvas.js';
+export type { CanvasClient, CanvasClientOptions } from './client/canvas-client.js';
+export { createCanvasClient, CanvasClientError } from './client/canvas-client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,aAAa,EACb,OAAO,EACP,SAAS,EACT,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,mCAAmC,CAAC;AAG3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { COMPONENT_REGISTRY, getComponentEntry, isApprovedComponent, isDeprecatedComponent, } from './registry/component-registry.js';
+export { ProductNotRegisteredError, ExperienceAdapterRegistry, createExperienceAdapterRegistry, } from './contracts/experience-adapter.js';
+export { NODE_TYPES, ZOD_NODE_TYPES, canvasNodeSchema, canvasDefinitionSchema, validateCanvasDefinition, } from './validate/canvas.js';
+export { createCanvasClient, CanvasClientError } from './client/canvas-client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kCAAkC,CAAC;AAW1C,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,mCAAmC,CAAC;AAI3C,OAAO,EACL,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/registry/component-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Component Registry — the approved-component allowlist (GOVERNANCE).
+ *
+ * The model SELECTS from this; it cannot invent UI. The authoritative copy
+ * lives at platform/contracts/canvas/v1/component-registry.json; this is the
+ * SDK's typed, embedded copy (the contract JSON is not shipped in the
+ * published npm package). The conformance test asserts the two agree.
+ *
+ * @packageDocumentation
+ */
+import type { CanvasNodeType } from '../types/canvas.js';
+export type ComponentStatus = 'active' | 'deprecated' | 'removed';
+export interface ComponentRegistryEntry {
+    status: ComponentStatus;
+    since: string;
+    required_permission?: string | null;
+    props_schema?: string;
+    deprecated_since?: string;
+    replaced_by?: string;
+    removal_after?: string;
+    _note?: string;
+}
+export interface ComponentRegistry {
+    registry_version: string;
+    updated_at: string;
+    components: Record<string, ComponentRegistryEntry>;
+}
+/** Embedded allowlist — keep in sync with the contracts manifest (test-guarded). */
+export declare const COMPONENT_REGISTRY: ComponentRegistry;
+/** Look up an entry by component id (returns undefined if absent). */
+export declare function getComponentEntry(id: string, registry?: ComponentRegistry): ComponentRegistryEntry | undefined;
+/**
+ * True if a component id may be selected (emitter) or rendered (renderer):
+ * it must exist and be `active` or `deprecated`. `removed` and unknown ids
+ * fail closed.
+ */
+export declare function isApprovedComponent(id: string, registry?: ComponentRegistry): id is CanvasNodeType;
+/** True if an approved component is deprecated (still renders, with a warning). */
+export declare function isDeprecatedComponent(id: string, registry?: ComponentRegistry): boolean;
+//# sourceMappingURL=component-registry.d.ts.map

package/dist/registry/component-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-registry.d.ts","sourceRoot":"","sources":["../../src/registry/component-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACpD;AAED,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,EAAE,iBA6BhC,CAAC;AAEF,sEAAsE;AACtE,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,EACV,QAAQ,GAAE,iBAAsC,GAC/C,sBAAsB,GAAG,SAAS,CAEpC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,EACV,QAAQ,GAAE,iBAAsC,GAC/C,EAAE,IAAI,cAAc,CAGtB;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,QAAQ,GAAE,iBAAsC,GAC/C,OAAO,CAET"}

package/dist/registry/component-registry.js

@@ -0,0 +1,59 @@
+/**
+ * Component Registry — the approved-component allowlist (GOVERNANCE).
+ *
+ * The model SELECTS from this; it cannot invent UI. The authoritative copy
+ * lives at platform/contracts/canvas/v1/component-registry.json; this is the
+ * SDK's typed, embedded copy (the contract JSON is not shipped in the
+ * published npm package). The conformance test asserts the two agree.
+ *
+ * @packageDocumentation
+ */
+/** Embedded allowlist — keep in sync with the contracts manifest (test-guarded). */
+export const COMPONENT_REGISTRY = {
+    registry_version: '0.2.0',
+    updated_at: '2026-06-15T00:00:00Z',
+    components: {
+        'stat-card': {
+            status: 'active',
+            since: '0.1.0',
+            required_permission: null,
+            props_schema: 'nodes/stat-card.schema.json',
+        },
+        'data-table': {
+            status: 'active',
+            since: '0.1.0',
+            required_permission: null,
+            props_schema: 'nodes/data-table.schema.json',
+        },
+        'service-health': {
+            status: 'active',
+            since: '0.1.0',
+            required_permission: null,
+            props_schema: 'nodes/service-health.schema.json',
+        },
+        'text-block': {
+            status: 'active',
+            since: '0.2.0',
+            required_permission: null,
+            props_schema: 'nodes/text-block.schema.json',
+        },
+    },
+};
+/** Look up an entry by component id (returns undefined if absent). */
+export function getComponentEntry(id, registry = COMPONENT_REGISTRY) {
+    return registry.components[id];
+}
+/**
+ * True if a component id may be selected (emitter) or rendered (renderer):
+ * it must exist and be `active` or `deprecated`. `removed` and unknown ids
+ * fail closed.
+ */
+export function isApprovedComponent(id, registry = COMPONENT_REGISTRY) {
+    const entry = registry.components[id];
+    return !!entry && (entry.status === 'active' || entry.status === 'deprecated');
+}
+/** True if an approved component is deprecated (still renders, with a warning). */
+export function isDeprecatedComponent(id, registry = COMPONENT_REGISTRY) {
+    return registry.components[id]?.status === 'deprecated';
+}
+//# sourceMappingURL=component-registry.js.map

package/dist/registry/component-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-registry.js","sourceRoot":"","sources":["../../src/registry/component-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAuBH,oFAAoF;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,gBAAgB,EAAE,OAAO;IACzB,UAAU,EAAE,sBAAsB;IAClC,UAAU,EAAE;QACV,WAAW,EAAE;YACX,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,OAAO;YACd,mBAAmB,EAAE,IAAI;YACzB,YAAY,EAAE,6BAA6B;SAC5C;QACD,YAAY,EAAE;YACZ,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,OAAO;YACd,mBAAmB,EAAE,IAAI;YACzB,YAAY,EAAE,8BAA8B;SAC7C;QACD,gBAAgB,EAAE;YAChB,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,OAAO;YACd,mBAAmB,EAAE,IAAI;YACzB,YAAY,EAAE,kCAAkC;SACjD;QACD,YAAY,EAAE;YACZ,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,OAAO;YACd,mBAAmB,EAAE,IAAI;YACzB,YAAY,EAAE,8BAA8B;SAC7C;KACF;CACF,CAAC;AAEF,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAC/B,EAAU,EACV,WAA8B,kBAAkB;IAEhD,OAAO,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,EAAU,EACV,WAA8B,kBAAkB;IAEhD,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC;AACjF,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CACnC,EAAU,EACV,WAA8B,kBAAkB;IAEhD,OAAO,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC;AAC1D,CAAC"}

package/dist/storage/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * CanvasStorageClient — the thin write client over canvas-service's record/Parts/lifecycle API.
+ *
+ * Types + HTTP wrapper ONLY (the locked SDK rule): no rendering, no business logic, no lifecycle
+ * enforcement, no caching, no auth minting. canvas-service owns persistence, the lifecycle state machine,
+ * and two-gate auth; this client only TRANSPORTS the write, forwarding the verified caller's bearer (+
+ * tenant/correlation) via `headers()` — it never mints a token. A stale-revision write surfaces as a typed
+ * conflict. This is the browser/edge transport of the one wire contract (the Go Conductor write-back is the
+ * other transport; see docs/design/canvas-storage-sdk.md). Append-only (v1): no in-place part Update.
+ *
+ * @packageDocumentation
+ */
+import type { CanvasRecord, CanvasPart, CanvasAggregate, CanvasHome, PartInput, BatchAppendRequest, BatchAppendResult } from './types.js';
+export interface CanvasStorageClientOptions {
+    /** Base URL the canvas-service record API is reached at (record routes live under /api/v1/canvases). */
+    baseUrl: string;
+    /** Optional fetch implementation (defaults to global fetch). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Per-request headers the caller supplies — the verified-actor bearer (Authorization), the claimed
+     * tenant (X-Tenant-ID), and a correlation id (X-Correlation-ID). The client FORWARDS these; it never
+     * mints, refreshes, or inspects a token. canvas-service re-proves Gate-1 + Gate-2 from them.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+}
+/** A non-2xx response from canvas-service (404 = the owner/tenant collapse; 401 = auth). */
+export declare class CanvasStorageError extends Error {
+    readonly status?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, details?: unknown | undefined);
+}
+/** A stale-write conflict (HTTP 409): the canvas `revision` changed since it was observed. */
+export declare class CanvasStorageConflictError extends CanvasStorageError {
+    readonly currentRevision?: number | undefined;
+    constructor(message: string, currentRevision?: number | undefined, details?: unknown);
+}
+export declare class CanvasStorageClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly headers?;
+    constructor(opts: CanvasStorageClientOptions);
+    /** POST /api/v1/canvases — create a DRAFT (or resume the owner's open draft). */
+    create(): Promise<CanvasRecord>;
+    /** POST /api/v1/canvases/:id/name — DRAFT→ACTIVE birth, or rename an ACTIVE canvas. */
+    name(id: string, name: string): Promise<CanvasRecord>;
+    /** GET /api/v1/canvases/:id — open/read a canvas with its ordered parts. */
+    open(id: string): Promise<CanvasAggregate>;
+    /** GET /api/v1/canvases — the caller's ACTIVE canvases, recency-ordered. */
+    list(): Promise<CanvasRecord[]>;
+    /** GET /api/v1/canvases/home — the Workspace-Home read model in one read. */
+    home(): Promise<CanvasHome>;
+    /** POST /api/v1/canvases/:id/archive — ACTIVE→ARCHIVED (idempotent). */
+    archive(id: string): Promise<CanvasRecord>;
+    /** POST /api/v1/canvases/:id/restore — ARCHIVED→ACTIVE (idempotent). */
+    restore(id: string): Promise<CanvasRecord>;
+    /** POST /api/v1/canvases/:id/parts — append one authored part. */
+    addPart(id: string, part: PartInput): Promise<CanvasPart>;
+    /** DELETE /api/v1/canvases/:id/parts/:partId — hard-delete a part (append-only model; no Update). */
+    removePart(id: string, partId: string): Promise<void>;
+    /** POST /api/v1/canvases/:id/parts/reorder — rewrite the part order to the supplied id list. */
+    reorderParts(id: string, partIds: string[]): Promise<CanvasPart[]>;
+    /**
+     * POST /api/v1/canvases/:id/parts/apply — the Phase-5 write-back batch: append a batch of parts
+     * atomically, idempotent under the key, optimistic against `expectedRevision`. The SDK banks this
+     * contract now; the canvas-service route + durable dedup + revision check land in Phase 5.
+     */
+    apply(id: string, batch: BatchAppendRequest): Promise<BatchAppendResult>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/storage/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/storage/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,wGAAwG;IACxG,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1E;AAED,4FAA4F;AAC5F,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,MAAM,CAAC,EAAE,MAAM;aACf,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,8FAA8F;AAC9F,qBAAa,0BAA2B,SAAQ,kBAAkB;aAG9C,eAAe,CAAC,EAAE,MAAM;gBADxC,OAAO,EAAE,MAAM,EACC,eAAe,CAAC,EAAE,MAAM,YAAA,EACxC,OAAO,CAAC,EAAE,OAAO;CAKpB;AAID,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAwC;gBAErD,IAAI,EAAE,0BAA0B;IAM5C,iFAAiF;IACjF,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAI/B,uFAAuF;IACvF,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIrD,4EAA4E;IAC5E,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAI1C,4EAA4E;IAC5E,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAI/B,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAI3B,wEAAwE;IACxE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI1C,wEAAwE;IACxE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI1C,kEAAkE;IAClE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAIzD,qGAAqG;IACrG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,gGAAgG;IAChG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMlE;;;;OAIG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAW1D,OAAO;CA4BtB"}

package/dist/storage/client.js

@@ -0,0 +1,146 @@
+/**
+ * CanvasStorageClient — the thin write client over canvas-service's record/Parts/lifecycle API.
+ *
+ * Types + HTTP wrapper ONLY (the locked SDK rule): no rendering, no business logic, no lifecycle
+ * enforcement, no caching, no auth minting. canvas-service owns persistence, the lifecycle state machine,
+ * and two-gate auth; this client only TRANSPORTS the write, forwarding the verified caller's bearer (+
+ * tenant/correlation) via `headers()` — it never mints a token. A stale-revision write surfaces as a typed
+ * conflict. This is the browser/edge transport of the one wire contract (the Go Conductor write-back is the
+ * other transport; see docs/design/canvas-storage-sdk.md). Append-only (v1): no in-place part Update.
+ *
+ * @packageDocumentation
+ */
+/** A non-2xx response from canvas-service (404 = the owner/tenant collapse; 401 = auth). */
+export class CanvasStorageError extends Error {
+    constructor(message, status, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.name = 'CanvasStorageError';
+    }
+}
+/** A stale-write conflict (HTTP 409): the canvas `revision` changed since it was observed. */
+export class CanvasStorageConflictError extends CanvasStorageError {
+    constructor(message, currentRevision, details) {
+        super(message, 409, details);
+        this.currentRevision = currentRevision;
+        this.name = 'CanvasStorageConflictError';
+    }
+}
+const RECORD_BASE = '/api/v1/canvases';
+export class CanvasStorageClient {
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.headers = opts.headers;
+    }
+    /** POST /api/v1/canvases — create a DRAFT (or resume the owner's open draft). */
+    create() {
+        return this.request('POST', '').then((d) => d.canvas);
+    }
+    /** POST /api/v1/canvases/:id/name — DRAFT→ACTIVE birth, or rename an ACTIVE canvas. */
+    name(id, name) {
+        return this.request('POST', `/${enc(id)}/name`, { name }).then((d) => d.canvas);
+    }
+    /** GET /api/v1/canvases/:id — open/read a canvas with its ordered parts. */
+    open(id) {
+        return this.request('GET', `/${enc(id)}`);
+    }
+    /** GET /api/v1/canvases — the caller's ACTIVE canvases, recency-ordered. */
+    list() {
+        return this.request('GET', '').then((d) => d.canvases);
+    }
+    /** GET /api/v1/canvases/home — the Workspace-Home read model in one read. */
+    home() {
+        return this.request('GET', '/home');
+    }
+    /** POST /api/v1/canvases/:id/archive — ACTIVE→ARCHIVED (idempotent). */
+    archive(id) {
+        return this.request('POST', `/${enc(id)}/archive`).then((d) => d.canvas);
+    }
+    /** POST /api/v1/canvases/:id/restore — ARCHIVED→ACTIVE (idempotent). */
+    restore(id) {
+        return this.request('POST', `/${enc(id)}/restore`).then((d) => d.canvas);
+    }
+    /** POST /api/v1/canvases/:id/parts — append one authored part. */
+    addPart(id, part) {
+        return this.request('POST', `/${enc(id)}/parts`, toPartBody(part)).then((d) => d.part);
+    }
+    /** DELETE /api/v1/canvases/:id/parts/:partId — hard-delete a part (append-only model; no Update). */
+    removePart(id, partId) {
+        return this.request('DELETE', `/${enc(id)}/parts/${enc(partId)}`);
+    }
+    /** POST /api/v1/canvases/:id/parts/reorder — rewrite the part order to the supplied id list. */
+    reorderParts(id, partIds) {
+        return this.request('POST', `/${enc(id)}/parts/reorder`, { part_ids: partIds }).then((d) => d.parts);
+    }
+    /**
+     * POST /api/v1/canvases/:id/parts/apply — the Phase-5 write-back batch: append a batch of parts
+     * atomically, idempotent under the key, optimistic against `expectedRevision`. The SDK banks this
+     * contract now; the canvas-service route + durable dedup + revision check land in Phase 5.
+     */
+    apply(id, batch) {
+        const body = {
+            idempotency_key: { turn_id: batch.idempotencyKey.turn_id, tool_call_id: batch.idempotencyKey.tool_call_id },
+            parts: batch.parts.map(toPartBody),
+        };
+        if (batch.expectedRevision !== undefined)
+            body.expected_revision = batch.expectedRevision;
+        return this.request('POST', `/${enc(id)}/parts/apply`, body);
+    }
+    // --- transport ---
+    async request(method, path, body) {
+        const provided = this.headers ? await this.headers() : {};
+        const headers = { ...provided };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const res = await this.fetchImpl(`${this.baseUrl}${RECORD_BASE}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 204)
+            return undefined;
+        if (!res.ok) {
+            const detail = await safeJson(res);
+            if (res.status === 409) {
+                throw new CanvasStorageConflictError(`canvas-storage: stale-write conflict on ${method} ${path}`, revisionOf(detail), detail);
+            }
+            throw new CanvasStorageError(`canvas-storage: ${method} ${path} returned ${res.status}`, res.status, detail);
+        }
+        const envelope = (await res.json());
+        return envelope.data;
+    }
+}
+/** Encode a path segment (the ids are UUIDs, but encode defensively). */
+function enc(seg) {
+    return encodeURIComponent(seg);
+}
+/** Map a PartInput to the canvas-service wire body (snake_case, nulls preserved). */
+function toPartBody(p) {
+    return {
+        part_type: p.part_type,
+        text_content: p.text_content ?? null,
+        layout: p.layout ?? {},
+        metadata: p.metadata ?? {},
+    };
+}
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pull a `revision` (or `current_revision`) out of an error body, if present. */
+function revisionOf(detail) {
+    if (detail && typeof detail === 'object') {
+        const d = detail;
+        const r = d.current_revision ?? d.revision;
+        if (typeof r === 'number')
+            return r;
+    }
+    return undefined;
+}
+//# sourceMappingURL=client.js.map