@vcp-dev/contracts 0.3.14

package/README.md

@@ -0,0 +1,48 @@
+# `@vcp-dev/contracts`
+
+VCP 对外共享的 TypeScript 合同包，承载站点编辑、render document、patch
+plan、Agent / Workspace 相关 schema 与事件类型。
+
+## 环境要求
+
+- Node.js `>=24`
+
+## 安装
+
+```bash
+npm install @vcp-dev/contracts
+```
+
+## 适用场景
+
+- 校验 site edit operation / patch plan 输入输出
+- 复用 site edit runtime fallback 标签集合与能力 fallback helper
+- 复用 `site_id`、`snapshot_id`、`tenant_id` 等稳定边界字段
+- 在服务端、工具链或外部集成中共享 Zod schema 与推导类型
+
+## 示例
+
+```ts
+import {
+  SiteEditOperationRequestSchema,
+  type SiteEditOperationRequest,
+} from "@vcp-dev/contracts";
+
+const request: SiteEditOperationRequest = SiteEditOperationRequestSchema.parse({
+  id: "op_123",
+  siteId: "site_123",
+  baseSnapshotId: "snapshot_123",
+  kind: "update-text",
+  target: { kind: "object", key: "hero-title" },
+  payload: { text: "Hello VCP" },
+});
+```
+
+## 非目标
+
+`@vcp-dev/contracts` 只提供合同、schema 与共享类型，不负责：
+
+- 执行源码编辑
+- 管理 snapshot 持久化
+- 启动 preview / sandbox
+- 触发站点发布

package/dist/cms-collection-binding.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/**
+ * V1b binding-state 状态机（计划决策 2）：connect_dynamic_collection provision
+ * 是多步外部写（cms 建应用 → 建分类 → 灌数据 → 生成页面），run 间靠
+ * cms_collection_bindings 行防 orphan。合法推进：
+ * provisioning → cms_app_created → seeded → ready；任一步失败落 failed。
+ */
+export declare const BINDING_STATUSES: readonly ["provisioning", "cms_app_created", "seeded", "ready", "failed"];
+export type BindingStatus = (typeof BINDING_STATUSES)[number];
+/**
+ * apps/api `/internal/cms/bindings` 内网面与 agent client 之间交换的 binding
+ * 行契约，字段对齐 `cms_collection_bindings` 表（uuid 代理主键不进契约——
+ * binding 身份是 (tenant_id, site_id, collection_slug) 三元组）。
+ * created_at / updated_at 是服务端时间戳的 ISO 字符串形态。
+ */
+export declare const CmsCollectionBindingSchema: z.ZodObject<{
+    tenant_id: z.ZodString;
+    site_id: z.ZodString;
+    collection_slug: z.ZodString;
+    cms_collection_id: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        provisioning: "provisioning";
+        cms_app_created: "cms_app_created";
+        seeded: "seeded";
+        ready: "ready";
+        failed: "failed";
+    }>;
+    owned_by_vcp: z.ZodBoolean;
+    run_id: z.ZodNullable<z.ZodString>;
+    last_error: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type CmsCollectionBinding = z.infer<typeof CmsCollectionBindingSchema>;

package/dist/cms-public-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 将 CMS 侧站点 URL / 已配置公共 API base 归一为生成站点实际读取的
+ * vibe/v1 base。external-sync 写入的 site_url 可能是站点根域名，而
+ * generated site 的 CMS_PROXY_URL 必须指向 /vibe/v1。
+ */
+export declare function normalizeCmsPublicApiBase(input: string | null | undefined): string | null;

package/dist/colorway-distinctness.d.ts

@@ -0,0 +1,24 @@
+import { type DesignColorSeeds, type DesignSurfaceMode } from "./design-tokens.js";
+/**
+ * 视觉调性 3 张配色卡的"是否肉眼可分"度量，仅供 clarify C2 telemetry（不重生成、
+ * 不阻断）。关键：用户感知的"同背景"来自派生 `deriveDesignColors(...)["--background"]`，
+ * 而 light 分支把 background 钉成 `oklch(0.98, 0.01, hue)`（L/C 常量、只 hue 微变），
+ * 所以**不能比 raw `colorSeeds.primary`**（那量的是色块差异，不是背景差异）。这里对每个
+ * colorway 走共享派生后，在派生结果上判可分：surfaceMode 多样性 + 背景 ciede2000 deltaE +
+ * primary/accent 的**色相**间距（用色相而非整体 deltaE，避免同色系不同明度被误判可分）。
+ * 命名色（cream/amber/slate）经 deriveDesignColors 内部的 SEMANTIC_SEED_ALIASES + hash
+ * 一律可解析，无需自写颜色解析、无需跳过。
+ */
+export interface ColorwayInput {
+    colorSeeds?: DesignColorSeeds;
+    surfaceMode?: DesignSurfaceMode;
+}
+export interface ColorwayDistinctnessResult {
+    /** 派生卡片背景两两 ciede2000 deltaE 的最小值；insufficient 时为 null。 */
+    minBackgroundDeltaE: number | null;
+    /** true = 三张配色肉眼不可分（同色系微变体、同 surface、同色相）。 */
+    tooSimilar: boolean;
+    /** 可解析的 colorway < 2，无法判定。 */
+    insufficient: boolean;
+}
+export declare function measureColorwayDistinctness(colorways: ColorwayInput[]): ColorwayDistinctnessResult;

package/dist/colorway-distinctness.js

@@ -0,0 +1 @@
+import{converter as K,differenceCiede2000 as W}from"culori";import{converter as P,parse as k,wcagContrast as v}from"culori";var f=P("oklch"),M=4.5,$={paper:"oklch(0.92 0.008 250)",cream:"oklch(0.90 0.035 85)",sand:"oklch(0.75 0.05 78)",stone:"oklch(0.60 0.02 75)",ash:"oklch(0.60 0.012 250)",slate:"oklch(0.45 0.025 250)",charcoal:"oklch(0.30 0.015 255)",ink:"oklch(0.25 0.04 260)",sky:"oklch(0.72 0.12 230)",blue:"oklch(0.58 0.17 250)","medical blue":"oklch(0.58 0.12 235)",indigo:"oklch(0.50 0.18 280)",navy:"oklch(0.40 0.10 258)",ocean:"oklch(0.55 0.13 220)","slate blue":"oklch(0.46 0.06 245)",teal:"oklch(0.60 0.12 195)","soft aqua":"oklch(0.78 0.07 190)",mint:"oklch(0.78 0.10 165)",sage:"oklch(0.65 0.05 145)",green:"oklch(0.58 0.15 145)","clinical green":"oklch(0.62 0.12 155)",emerald:"oklch(0.60 0.16 155)",forest:"oklch(0.45 0.10 145)",olive:"oklch(0.58 0.08 115)",lime:"oklch(0.72 0.17 130)",yellow:"oklch(0.82 0.15 100)",gold:"oklch(0.72 0.14 85)",amber:"oklch(0.70 0.16 70)",orange:"oklch(0.66 0.18 55)",coral:"oklch(0.68 0.16 32)",terracotta:"oklch(0.55 0.12 42)",rust:"oklch(0.50 0.13 38)",brown:"oklch(0.45 0.07 55)",rose:"oklch(0.65 0.16 18)",red:"oklch(0.58 0.20 25)",crimson:"oklch(0.52 0.20 22)",wine:"oklch(0.42 0.13 18)",pink:"oklch(0.72 0.14 0)",magenta:"oklch(0.60 0.22 345)",lavender:"oklch(0.72 0.08 295)",violet:"oklch(0.58 0.19 295)",purple:"oklch(0.52 0.19 305)",plum:"oklch(0.45 0.13 325)",electric:"oklch(0.62 0.23 285)","clean white":"oklch(0.97 0.01 245)","cool gray":"oklch(0.62 0.02 245)",zinc:"oklch(0.60 0.012 250)",gray:"oklch(0.60 0.012 250)",grey:"oklch(0.60 0.012 250)",neutral:"oklch(0.60 0.005 250)",gunmetal:"oklch(0.30 0.015 255)"};function E(e){let o=e.colorSeeds??{primary:"slate",accent:"blue",neutral:"zinc"},c=e.surfaceMode,r=g(o.primary||"slate"),t=a(r),n=a(g(o.accent||"blue")),i=o.neutral?g(o.neutral):V(r),l=h(i.h),u,s,d,p,b,y;c==="dark"?(u=a({mode:"oklch",l:.14,c:.03,h:l}),s=a({mode:"oklch",l:.95,c:.02,h:l}),d=a({mode:"oklch",l:.2,c:.04,h:l}),p=a({mode:"oklch",l:.29,c:.05,h:l}),b=a({mode:"oklch",l:.78,c:.02,h:l}),y=a({mode:"oklch",l:.35,c:.06,h:l})):(u=a({mode:"oklch",l:.98,c:.01,h:l}),s=a({mode:"oklch",l:.2,c:.02,h:l}),d=a({mode:"oklch",l:.96,c:.015,h:l}),p=a({mode:"oklch",l:.92,c:.02,h:l}),b=a({mode:"oklch",l:.43,c:.02,h:l}),y=a({mode:"oklch",l:.84,c:.025,h:l}));let S=c!=="dark",D={"--background":u,"--foreground":s,"--card":d,"--card-foreground":s,"--muted":p,"--muted-foreground":b,"--border":y,"--input":y,"--ring":n,"--primary":t,"--primary-foreground":m(t),"--primary-hover":x(t,S),"--accent":n,"--accent-foreground":m(n),"--accent-ink":w(n,u),"--accent-subtle":j(n,S),"--accent-hover":x(n,S),"--overlay-on-dark":a({mode:"oklch",l:.96,c:.02,h:l}),"--overlay-on-light":a({mode:"oklch",l:.2,c:.02,h:l})},L=s,O=m(s),T=C(s,l),_=w(n,s),N=f(k(t)??t),B=h(N?.h),H=C(t,B),G=w(n,t);return R({...D,...{"--surface-inverse":L,"--surface-inverse-foreground":O,"--surface-inverse-muted":T,"--surface-inverse-accent-ink":_,"--surface-primary-muted":H,"--surface-primary-accent-ink":G}},o)}function R(e,o){let c=a({mode:"oklch",l:.58,c:.22,h:28}),r=a({mode:"oklch",l:.6,c:.14,h:150}),t=a({mode:"oklch",l:.75,c:.15,h:75}),n={...e,"--popover":"var(--card)","--popover-foreground":"var(--card-foreground)","--secondary":"var(--muted)","--secondary-foreground":"var(--foreground)","--destructive":c,"--destructive-foreground":m(c),"--success":r,"--success-foreground":m(r),"--warning":t,"--warning-foreground":m(t)},[i,l]=z(o,n);return n["--supporting-0"]=i,n["--supporting-1"]=l,q(n["--accent"]).forEach((s,d)=>{n[`--chart-${d+1}`]=s}),n}function z(e,o){let t=(e.supporting??[]).filter(i=>!!(i&&i.trim())).slice(0,2).map(i=>a(g(i))),n=[o["--primary"],o["--accent"]];for(;t.length<2;)t.push(n[t.length]);return[t[0],t[1]]}function g(e,o="paper"){let c=(e??"").trim();if(!c)return g(o);let r=$[c.toLowerCase()]??c,t=k(r);if(t){let n=f(t);if(n)return n}return U(c)}function U(e){let o=2166136261,c=e.toLowerCase();for(let i=0;i<c.length;i++)o^=c.charCodeAt(i),o=Math.imul(o,16777619)>>>0;let r=o%360,t=.08+(o>>>9)%9/100;return{mode:"oklch",l:.52+(o>>>18)%16/100,c:t,h:r}}function V(e){return{mode:"oklch",l:.6,c:.02,h:h(e.h)}}function x(e,o){let c=f(k(e)??e);if(!c)return e;let r=o?-.06:.06,t=Math.max(.06,Math.min(.97,h(c.l)+r));return a({mode:"oklch",l:t,c:h(c.c),h:h(c.h)})}function j(e,o){let c=f(k(e)??e),r=h(c?.h),t=Math.min(h(c?.c),o?.05:.06);return a({mode:"oklch",l:o?.95:.24,c:t,h:r})}function q(e){let o=f(k(e)??e),c=h(o?.h),r=Math.max(.12,Math.min(h(o?.c),.16));return[0,72,144,216,288].map(t=>a({mode:"oklch",l:.62,c:r,h:(c+t)%360}))}function m(e){let o=k(e),c=o?f(o):void 0,r=h(c?.h),t={mode:"oklch",l:.99,c:.01,h:r},n={mode:"oklch",l:.18,c:.02,h:r},i=v(o??e,t),l=v(o??e,n);return a(i>=l?t:n)}function w(e,o){let c=f(k(e)??e);if(!c)return e;let r=h(c.h),t=h(c.c),n=h(c.l),i=f(k(o)??o),u=(i?h(i.l)>=.5:!0)?-.02:.02;for(let s=0;s<=50;s++){let d=n+u*s;if(d<=0||d>=1)break;let p={mode:"oklch",l:d,c:t,h:r};if(v(p,o)>=M)return a(p)}return m(o)}function C(e,o){let c=f(k(e)??e),t=(c?h(c.l):.5)>=.5,n=t?.75:.35,i=t?-.02:.02;for(let l=0;l<=50;l++){let u=n+i*l;if(u<=0||u>=1)break;let s={mode:"oklch",l:u,c:.02,h:o};if(v(s,e)>=M)return a(s)}return m(e)}function h(e){return typeof e=="number"&&Number.isFinite(e)?e:0}function a(e){let o=h(e.l),c=h(e.c),r=h(e.h);return`oklch(${o.toFixed(2)} ${c.toFixed(2)} ${r.toFixed(2)})`}var X=10,I=25,J=K("oklch"),Q=W();function Y(e){return typeof e.colorSeeds?.primary=="string"&&e.colorSeeds.primary.trim().length>0}function F(e){let o=J(e);return o&&typeof o.h=="number"?o.h:void 0}function A(e){let o=0;for(let c=0;c<e.length;c+=1)for(let r=c+1;r<e.length;r+=1){let t=e[c],n=e[r];if(t===void 0||n===void 0)continue;let i=Math.abs(t-n)%360,l=i>180?360-i:i;l>o&&(o=l)}return o}function Z(e){let o=0,c=1/0;for(let r=0;r<e.length;r+=1)for(let t=r+1;t<e.length;t+=1){let n=Q(e[r],e[t]);n>o&&(o=n),n<c&&(c=n)}return{max:o,min:c===1/0?0:c}}function re(e){let o=e.filter(Y);if(o.length<2)return{minBackgroundDeltaE:null,tooSimilar:!1,insufficient:!0};let c=o.map(s=>s.surfaceMode??"light"),r=o.map((s,d)=>E({colorSeeds:s.colorSeeds,surfaceMode:c[d]})),t=Z(r.map(s=>s["--background"])),n=A(r.map(s=>F(s["--primary"]))),i=A(r.map(s=>F(s["--accent"]))),u=!(new Set(c).size===1)||t.max>=X||n>=I||i>=I;return{minBackgroundDeltaE:t.min,tooSimilar:!u,insufficient:!1}}export{re as measureColorwayDistinctness};

package/dist/connect-dynamic-collection.d.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+/** V1b provision 可定义的字段类型词表（非媒体、非分类；与 CMS 字段类型 1:1）。spec §5.3。 */
+export declare const FIELD_TYPES: readonly ["title", "text", "richtext", "number", "boolean", "date", "datetime", "url", "email", "color", "select", "multiselect", "tag"];
+export type FieldType = (typeof FIELD_TYPES)[number];
+export declare const FieldDeclSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        title: "title";
+        text: "text";
+        richtext: "richtext";
+        date: "date";
+        datetime: "datetime";
+        url: "url";
+        email: "email";
+        color: "color";
+        select: "select";
+        multiselect: "multiselect";
+        tag: "tag";
+    }>;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type FieldDecl = z.infer<typeof FieldDeclSchema>;
+/** 从 CMS schema 读回的落定字段（含 CMS 原生类型字符串）。 */
+export declare const ResolvedFieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    cms_type: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    value_shape: z.ZodOptional<z.ZodString>;
+    front_display: z.ZodOptional<z.ZodEnum<{
+        visible: "visible";
+        internal: "internal";
+        forbidden: "forbidden";
+    }>>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ResolvedField = z.infer<typeof ResolvedFieldSchema>;
+export declare const ConnectDynamicCollectionInputSchema: z.ZodObject<{
+    route_file_path: z.ZodString;
+    target_component_path: z.ZodString;
+    content_type_hint: z.ZodString;
+    required_fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            title: "title";
+            text: "text";
+            richtext: "richtext";
+            date: "date";
+            datetime: "datetime";
+            url: "url";
+            email: "email";
+            color: "color";
+            select: "select";
+            multiselect: "multiselect";
+            tag: "tag";
+        }>;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    mode: z.ZodEnum<{
+        bind_existing: "bind_existing";
+        provision: "provision";
+    }>;
+    list_mode: z.ZodOptional<z.ZodEnum<{
+        page: "page";
+        embedded: "embedded";
+    }>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            title: "title";
+            text: "text";
+            richtext: "richtext";
+            date: "date";
+            datetime: "datetime";
+            url: "url";
+            email: "email";
+            color: "color";
+            select: "select";
+            multiselect: "multiselect";
+            tag: "tag";
+        }>;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    seed_records: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type ConnectDynamicCollectionInput = z.infer<typeof ConnectDynamicCollectionInputSchema>;
+export type ConnectDynamicCollectionResult = {
+    status: "bound" | "provisioned";
+    collection_slug: string;
+    detail_prefix: string;
+    schema: ResolvedField[];
+    list_view: string;
+    detail_view: string;
+    /** 逐字段人话渲染契约（LLM 写 view 的零猜测依据），确定性派生。 */
+    view_contract: string;
+    /** 工具已写入 working set 的确定性产物路径——LLM 绝不可再 create/覆盖。 */
+    created_files: string[];
+    /** 自定义消费场景照抄片段（与 already_bound 同口径）；首次 bind 也回传，供 LLM 写额外自取数区块时照抄。 */
+    usage?: string;
+}
+/**
+ * 幂等命中：该 collection 的 scaffold 已存在于 base snapshot（此前 run 绑定过），
+ * 本次零写入。LLM 收到后下一步：按实时重算的 view_contract + usage 片段直接写
+ * 新区块/消费代码；绝不重建 existing_files、绝不手写数据层。
+ */
+ | {
+    status: "already_bound";
+    collection_slug: string;
+    /** 照常采样推断；采样失败回退空串（详情链接始终用 record.url，与 usage 同口径）。 */
+    detail_prefix: string;
+    schema: ResolvedField[];
+    /** 实时重算（与 bound 同源派生），不读旧产物。 */
+    view_contract: string;
+    /** 已存在的 scaffold 路径，绝不可重建（再 create 必撞 ALREADY_EXISTS）。 */
+    existing_files: string[];
+    /** 标准消费片段（嵌入区块/自定义消费场景照抄，杜绝凭记忆手写取数）。 */
+    usage: string;
+} | {
+    status: "not_found_collection";
+    /** 站点全部可用低代码应用（slug+名称）。从中选最匹配项以 slug 或精确 name 重调，勿猜名。 */
+    available_collections: {
+        slug: string;
+        name: string;
+    }[];
+} | {
+    status: "schema_incompatible";
+    missing_fields: string[];
+    schema: ResolvedField[];
+} | {
+    status: "unsupported_url_template";
+} | {
+    status: "cannot_infer_detail_prefix";
+}
+/** CMS 基础设施暂不可达（网络/5xx/530 瞬断），非「collection 不存在」——稍后重试，勿换名猜测。 */
+ | {
+    status: "cms_unreachable";
+}
+/**
+ * provision 编排失败专用结果态（V1b）：slug 归一失败 / 内网未配置 /
+ * CMS 写链路任一步失败 / seed 发布 fail-closed。reason 是给 LLM 的
+ * 人话（含可自纠指引），不复用 not_found_collection 等 bind 语义。
+ */
+ | {
+    status: "provision_failed";
+    reason: string;
+}
+/**
+ * scaffold 写入失败（applyPatchBatch 未 applied）：code 是真实失败码，
+ * 不再伪装成 not_found_collection/provision_failed（真实 run：伪装清单为空
+ * 骗 LLM 连环换名乱猜，最终绑错集合）。LLM 收到后下一步：文件已存在
+ * （PATCH_TARGET_ALREADY_EXISTS）≈ 已绑定过——原参重调本工具拿
+ * already_bound 契约；绝不换名重试或手写数据层。collection_slug 是
+ * 工具已解析落定的真实 slug（重调以它为锚，不回到 hint 猜测）。
+ */
+ | {
+    status: "scaffold_write_failed";
+    collection_slug: string;
+    code: string;
+    reason: string;
+};

package/dist/connect-form.d.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+/**
+ * connect_form provision 可声明的表单字段类型词表（非文件/媒体类）。
+ * 词表→CMS 表单字段类型映射在 agent 侧 `cms-forms/field-type-to-form.ts`，
+ * 与 connect-dynamic-collection 的 FIELD_TYPES/field-type-to-cms 同款分层。
+ */
+export declare const FORM_FIELD_TYPES: readonly ["text", "textarea", "email", "phone", "select", "radio", "multiselect", "boolean", "date", "number"];
+export type FormFieldType = (typeof FORM_FIELD_TYPES)[number];
+export declare const FormFieldDeclSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        date: "date";
+        email: "email";
+        select: "select";
+        multiselect: "multiselect";
+        textarea: "textarea";
+        phone: "phone";
+        radio: "radio";
+    }>;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type FormFieldDecl = z.infer<typeof FormFieldDeclSchema>;
+export declare const ConnectFormInputSchema: z.ZodObject<{
+    form_hint: z.ZodString;
+    mode: z.ZodEnum<{
+        bind_existing: "bind_existing";
+        provision: "provision";
+    }>;
+    component_slug: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            date: "date";
+            email: "email";
+            select: "select";
+            multiselect: "multiselect";
+            textarea: "textarea";
+            phone: "phone";
+            radio: "radio";
+        }>;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ConnectFormInput = z.infer<typeof ConnectFormInputSchema>;
+/** 从 GET forms/{code} 读回的落定字段（field_name/field_label/field_type/is_required → 本形态）。 */
+export declare const ResolvedFormFieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    cms_type: z.ZodString;
+    required: z.ZodBoolean;
+}, z.core.$strip>;
+export type ResolvedFormField = z.infer<typeof ResolvedFormFieldSchema>;
+export type ConnectFormResult = {
+    status: "bound" | "provisioned";
+    form_code: string;
+    form_name: string;
+    /** 读回落定的表单字段（提交 data 的键 = name）。 */
+    fields: ResolvedFormField[];
+    /** 表单来源页 id（提交必带；null=CMS 未回，提交会被 cms 以 unknown_source_page 拒）。 */
+    source_page_id: number | null;
+    /** LLM 要写的表单 view 组件路径（必须 "use client"）。 */
+    form_view: string;
+    /** 逐字段人话渲染契约 + 提交链路用法（LLM 写 form view 的零猜测依据），确定性派生。 */
+    form_contract: string;
+    /** 工具已写入 working set 的确定性产物路径——LLM 绝不可再 create/覆盖。 */
+    created_files: string[];
+} | {
+    status: "not_found_form";
+    /** 站点全部可用表单（code+名称）。从中选最匹配项以 form_code 或精确 name 重调，勿猜名。 */
+    available_forms: {
+        code: string;
+        name: string;
+    }[];
+}
+/**
+ * 幂等命中：该表单的 scaffold 已存在于 base snapshot（此前 run 绑定过），
+ * 本次零写入。LLM 收到后下一步：按实时重算的 form_contract 写 form view，
+ * 绝不重建 existing_files、绝不手写提交链路（与 connect_dynamic_collection
+ * 的 already_bound 同款）。
+ */
+ | {
+    status: "already_bound";
+    form_code: string;
+    form_name: string;
+    /** 实时读回落定的表单字段（提交 data 的键 = name）。 */
+    fields: ResolvedFormField[];
+    /** 表单来源页 id（提交必带；null=CMS 未回）。 */
+    source_page_id: number | null;
+    /** LLM 要写的表单 view 组件路径（必须 "use client"）。 */
+    form_view: string;
+    /** 实时重算（与 bound 同源派生），不读旧产物。 */
+    form_contract: string;
+    /** 已存在的 scaffold 路径（容器 + 站点级基建），绝不可重建（再 create 必撞 ALREADY_EXISTS）。 */
+    existing_files: string[];
+}
+/** CMS 基础设施暂不可达（网络/5xx/530 瞬断），非「表单不存在」——稍后重试，勿换名猜测。 */
+ | {
+    status: "cms_unreachable";
+}
+/**
+ * provision 编排失败专用结果态：fields 缺失/选择类缺 options / 内网未配置 /
+ * CMS 写失败 / 读回失败。reason 是给 LLM 的人话（含可自纠指引），
+ * 不复用 not_found_form 等 bind 语义。
+ */
+ | {
+    status: "provision_failed";
+    reason: string;
+}
+/**
+ * scaffold 写入失败（applyPatchBatch 未 applied）：code 是真实失败码，
+ * 不再伪装成 not_found_form 空清单（真实 run：伪装清单为空骗 LLM 连环换
+ * form_code 乱猜，或转去手写提交链路）。LLM 收到后下一步：文件已存在
+ * （PATCH_TARGET_ALREADY_EXISTS）≈ 已绑定过——原参重调本工具拿
+ * already_bound 契约；绝不换名重试或手写提交链路。form_code 是工具已解析
+ * 落定的真实 code（重调以它为锚，不回到 hint 猜测）。
+ */
+ | {
+    status: "scaffold_write_failed";
+    form_code: string;
+    code: string;
+    reason: string;
+};

package/dist/deployment-runtime.d.ts

@@ -0,0 +1,8 @@
+export declare const DEPLOYMENT_STATUSES: readonly ["queued", "preparing_source", "building", "artifact_ready", "deploying", "released", "lock_failed", "source_prepare_failed", "build_failed", "artifact_fetch_failed", "artifact_validation_failed", "deploy_failed", "cleanup_failed"];
+export interface RedisConnectionConfig {
+    url?: string;
+    host: string;
+    port: number;
+    password?: string;
+}
+export declare function resolveRedisConnectionConfig(env: Record<string, string | undefined>): RedisConnectionConfig;

package/dist/design-tokens.d.ts

@@ -0,0 +1,54 @@
+import { type Oklch } from "culori";
+export type DesignSurfaceMode = "light" | "dark";
+/** Brand color seeds. Only `primary` is conceptually required; the rest derive. */
+export interface DesignColorSeeds {
+    primary?: string;
+    accent?: string;
+    neutral?: string;
+    supporting?: string[];
+}
+export interface DeriveDesignColorsInput {
+    colorSeeds?: DesignColorSeeds;
+    surfaceMode: DesignSurfaceMode;
+}
+/**
+ * Preferred seed vocabulary ported from cms-builder's
+ * `color_tokens.SEMANTIC_SEED_ALIASES` (oklch anchors that set hue/chroma
+ * tendency; lightness for surfaces is derived per surface mode). The trailing
+ * Tailwind neutral aliases are a thin VCP extension so the default neutral seed
+ * "zinc" (and common synonyms) resolves to a clean low-chroma neutral hue
+ * instead of hitting the unknown-label hash fallback.
+ */
+export declare const SEMANTIC_SEED_ALIASES: Record<string, string>;
+/**
+ * Returns the full color token map (`--background` … `--supporting-1`) derived
+ * from the seeds + surface mode. Pure: no I/O, deterministic.
+ */
+export declare function deriveDesignColors(input: DeriveDesignColorsInput): Record<string, string>;
+/**
+ * Resolves a seed (alias name, CSS color, or hex) to an oklch color. Unknown
+ * domain words deterministically hash to a stable mid-tone color, mirroring
+ * cms-builder's `_color_from_unknown_label` intent.
+ */
+export declare function isResolvableDesignColorSeed(seed: string): boolean;
+/** Picks a near-white / near-black foreground with higher WCAG contrast. */
+export declare function bestForegroundFor(background: string): string;
+/**
+ * Readable accent *text* color for copy that sits directly on a page surface —
+ * eyebrow labels, emphasized words, prices, stat numbers, outline-button labels.
+ *
+ * `--accent` keeps the seed's own lightness so it works as a FILL: `bg-accent`
+ * paired with the adaptive `--accent-foreground`. That same value is usually too
+ * close to `--background` to read as TEXT (a light gold accent on a near-white
+ * surface lands around 2:1, well under WCAG AA). This derives a same-hue /
+ * same-chroma variant whose lightness is pushed toward the readable direction —
+ * darker on light surfaces, lighter on dark — until it clears 4.5:1 against the
+ * background, so `text-accent-ink` stays legible while remaining recognizably
+ * the brand accent. When the accent already clears 4.5:1 as-is (common on dark
+ * surfaces, or for an already-deep seed) its original lightness is kept.
+ */
+export declare function accentInkFor(accent: string, background: string): string;
+/** NaN-safe channel read (achromatic colors have undefined hue in culori). */
+export declare function channel(value: number | undefined): number;
+/** Formats an oklch color as `oklch(L C H)` with 2-decimal precision. */
+export declare function oklchString(color: Oklch): string;

package/dist/design-tokens.js

@@ -0,0 +1 @@
+import{converter as _,parse as k,wcagContrast as y}from"culori";var m=_("oklch"),F=4.5,M={paper:"oklch(0.92 0.008 250)",cream:"oklch(0.90 0.035 85)",sand:"oklch(0.75 0.05 78)",stone:"oklch(0.60 0.02 75)",ash:"oklch(0.60 0.012 250)",slate:"oklch(0.45 0.025 250)",charcoal:"oklch(0.30 0.015 255)",ink:"oklch(0.25 0.04 260)",sky:"oklch(0.72 0.12 230)",blue:"oklch(0.58 0.17 250)","medical blue":"oklch(0.58 0.12 235)",indigo:"oklch(0.50 0.18 280)",navy:"oklch(0.40 0.10 258)",ocean:"oklch(0.55 0.13 220)","slate blue":"oklch(0.46 0.06 245)",teal:"oklch(0.60 0.12 195)","soft aqua":"oklch(0.78 0.07 190)",mint:"oklch(0.78 0.10 165)",sage:"oklch(0.65 0.05 145)",green:"oklch(0.58 0.15 145)","clinical green":"oklch(0.62 0.12 155)",emerald:"oklch(0.60 0.16 155)",forest:"oklch(0.45 0.10 145)",olive:"oklch(0.58 0.08 115)",lime:"oklch(0.72 0.17 130)",yellow:"oklch(0.82 0.15 100)",gold:"oklch(0.72 0.14 85)",amber:"oklch(0.70 0.16 70)",orange:"oklch(0.66 0.18 55)",coral:"oklch(0.68 0.16 32)",terracotta:"oklch(0.55 0.12 42)",rust:"oklch(0.50 0.13 38)",brown:"oklch(0.45 0.07 55)",rose:"oklch(0.65 0.16 18)",red:"oklch(0.58 0.20 25)",crimson:"oklch(0.52 0.20 22)",wine:"oklch(0.42 0.13 18)",pink:"oklch(0.72 0.14 0)",magenta:"oklch(0.60 0.22 345)",lavender:"oklch(0.72 0.08 295)",violet:"oklch(0.58 0.19 295)",purple:"oklch(0.52 0.19 305)",plum:"oklch(0.45 0.13 325)",electric:"oklch(0.62 0.23 285)","clean white":"oklch(0.97 0.01 245)","cool gray":"oklch(0.62 0.02 245)",zinc:"oklch(0.60 0.012 250)",gray:"oklch(0.60 0.012 250)",grey:"oklch(0.60 0.012 250)",neutral:"oklch(0.60 0.005 250)",gunmetal:"oklch(0.30 0.015 255)"};function W(e){let o=e.colorSeeds??{primary:"slate",accent:"blue",neutral:"zinc"},c=e.surfaceMode,l=g(o.primary||"slate"),r=n(l),t=n(g(o.accent||"blue")),h=o.neutral?g(o.neutral):z(l),s=a(h.h),u,i,d,p,b,v;c==="dark"?(u=n({mode:"oklch",l:.14,c:.03,h:s}),i=n({mode:"oklch",l:.95,c:.02,h:s}),d=n({mode:"oklch",l:.2,c:.04,h:s}),p=n({mode:"oklch",l:.29,c:.05,h:s}),b=n({mode:"oklch",l:.78,c:.02,h:s}),v=n({mode:"oklch",l:.35,c:.06,h:s})):(u=n({mode:"oklch",l:.98,c:.01,h:s}),i=n({mode:"oklch",l:.2,c:.02,h:s}),d=n({mode:"oklch",l:.96,c:.015,h:s}),p=n({mode:"oklch",l:.92,c:.02,h:s}),b=n({mode:"oklch",l:.43,c:.02,h:s}),v=n({mode:"oklch",l:.84,c:.025,h:s}));let w=c!=="dark",I={"--background":u,"--foreground":i,"--card":d,"--card-foreground":i,"--muted":p,"--muted-foreground":b,"--border":v,"--input":v,"--ring":t,"--primary":r,"--primary-foreground":f(r),"--primary-hover":S(r,w),"--accent":t,"--accent-foreground":f(t),"--accent-ink":x(t,u),"--accent-subtle":H(t,w),"--accent-hover":S(t,w),"--overlay-on-dark":n({mode:"oklch",l:.96,c:.02,h:s}),"--overlay-on-light":n({mode:"oklch",l:.2,c:.02,h:s})},A=i,L=f(i),T=C(i,s),O=x(t,i),E=m(k(r)??r),$=a(E?.h),N=C(r,$),P=x(t,r);return B({...I,...{"--surface-inverse":A,"--surface-inverse-foreground":L,"--surface-inverse-muted":T,"--surface-inverse-accent-ink":O,"--surface-primary-muted":N,"--surface-primary-accent-ink":P}},o)}function B(e,o){let c=n({mode:"oklch",l:.58,c:.22,h:28}),l=n({mode:"oklch",l:.6,c:.14,h:150}),r=n({mode:"oklch",l:.75,c:.15,h:75}),t={...e,"--popover":"var(--card)","--popover-foreground":"var(--card-foreground)","--secondary":"var(--muted)","--secondary-foreground":"var(--foreground)","--destructive":c,"--destructive-foreground":f(c),"--success":l,"--success-foreground":f(l),"--warning":r,"--warning-foreground":f(r)},[h,s]=D(o,t);return t["--supporting-0"]=h,t["--supporting-1"]=s,R(t["--accent"]).forEach((i,d)=>{t[`--chart-${d+1}`]=i}),t}function D(e,o){let r=(e.supporting??[]).filter(h=>!!(h&&h.trim())).slice(0,2).map(h=>n(g(h))),t=[o["--primary"],o["--accent"]];for(;r.length<2;)r.push(t[r.length]);return[r[0],r[1]]}function X(e){let o=(e??"").trim();if(!o||o.startsWith("#")&&!/^#[0-9A-Fa-f]{3,8}$/.test(o))return!1;let c=M[o.toLowerCase()]??o;return!!k(c)}function g(e,o="paper"){let c=(e??"").trim();if(!c)return g(o);let l=M[c.toLowerCase()]??c,r=k(l);if(r){let t=m(r);if(t)return t}return V(c)}function V(e){let o=2166136261,c=e.toLowerCase();for(let h=0;h<c.length;h++)o^=c.charCodeAt(h),o=Math.imul(o,16777619)>>>0;let l=o%360,r=.08+(o>>>9)%9/100;return{mode:"oklch",l:.52+(o>>>18)%16/100,c:r,h:l}}function z(e){return{mode:"oklch",l:.6,c:.02,h:a(e.h)}}function S(e,o){let c=m(k(e)??e);if(!c)return e;let l=o?-.06:.06,r=Math.max(.06,Math.min(.97,a(c.l)+l));return n({mode:"oklch",l:r,c:a(c.c),h:a(c.h)})}function H(e,o){let c=m(k(e)??e),l=a(c?.h),r=Math.min(a(c?.c),o?.05:.06);return n({mode:"oklch",l:o?.95:.24,c:r,h:l})}function R(e){let o=m(k(e)??e),c=a(o?.h),l=Math.max(.12,Math.min(a(o?.c),.16));return[0,72,144,216,288].map(r=>n({mode:"oklch",l:.62,c:l,h:(c+r)%360}))}function f(e){let o=k(e),c=o?m(o):void 0,l=a(c?.h),r={mode:"oklch",l:.99,c:.01,h:l},t={mode:"oklch",l:.18,c:.02,h:l},h=y(o??e,r),s=y(o??e,t);return n(h>=s?r:t)}function x(e,o){let c=m(k(e)??e);if(!c)return e;let l=a(c.h),r=a(c.c),t=a(c.l),h=m(k(o)??o),u=(h?a(h.l)>=.5:!0)?-.02:.02;for(let i=0;i<=50;i++){let d=t+u*i;if(d<=0||d>=1)break;let p={mode:"oklch",l:d,c:r,h:l};if(y(p,o)>=F)return n(p)}return f(o)}function C(e,o){let c=m(k(e)??e),r=(c?a(c.l):.5)>=.5,t=r?.75:.35,h=r?-.02:.02;for(let s=0;s<=50;s++){let u=t+h*s;if(u<=0||u>=1)break;let i={mode:"oklch",l:u,c:.02,h:o};if(y(i,e)>=F)return n(i)}return f(e)}function a(e){return typeof e=="number"&&Number.isFinite(e)?e:0}function n(e){let o=a(e.l),c=a(e.c),l=a(e.h);return`oklch(${o.toFixed(2)} ${c.toFixed(2)} ${l.toFixed(2)})`}export{M as SEMANTIC_SEED_ALIASES,x as accentInkFor,f as bestForegroundFor,a as channel,W as deriveDesignColors,X as isResolvableDesignColorSeed,n as oklchString};

package/dist/font-catalog.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Curated registry of site fonts accepted by DesignPlan. The deterministic
+ * root layout composer (see `buildDeterministicRouteContent`) emits
+ * `next/font/google` imports only for entries whose download policy allows it:
+ * large CJK families remain valid font-stack names, but are not downloaded by
+ * default because full CJK webfont slices can add multiple MB to generated
+ * Next.js output.
+ *
+ * Every entry below was verified against Next.js 16's
+ * `@next/font/google/font-data.json`:
+ * - `import` is the exact `next/font/google` export name.
+ * - `weights` is set ONLY for non-variable fonts that REQUIRE an explicit
+ *   weight (i.e. fonts whose `font-data.json` weights do not include
+ *   `"variable"`). Variable fonts omit `weights` so the default axis applies.
+ *
+ * Display names (the map keys) are what the DesignPlan prompt advertises and
+ * what the model is expected to choose from.
+ */
+export interface NextFontEntry {
+    /** Exact `next/font/google` export name (e.g. "Bebas_Neue", "Inter"). */
+    import: string;
+    /**
+     * Explicit weights, required only for non-variable fonts. Omitted for
+     * variable fonts (default axis is used).
+     */
+    weights?: string[];
+    /**
+     * Whether deterministic layout should emit a `next/font/google` download.
+     * Defaults to true. Set false for CJK/system-stack families.
+     */
+    download?: boolean;
+}
+export declare const NEXT_FONT_REGISTRY: Record<string, NextFontEntry>;
+/** Safe default used whenever a requested font is not in the registry. */
+export declare const DEFAULT_FONTS: {
+    readonly heading: "Inter";
+    readonly body: "Inter";
+};
+/**
+ * Resolves a (possibly model-chosen) font name to a verified
+ * `next/font/google` entry. Matches by display name OR import name,
+ * case-insensitive and whitespace-normalized. Returns the safe Inter default
+ * when the name is unknown so we never emit an unverified font import.
+ */
+export declare function resolveFont(name: string): NextFontEntry;
+/**
+ * Resolves a possibly user/LLM-supplied font name to the registry's
+ * canonical display name (e.g. `"noto_sans_sc"` / `"Noto_Sans_SC"` /
+ * `"noto sans sc"` all → `"Noto Sans SC"`). Returns `"Inter"` (the safe
+ * default) when the name is unknown, so any downstream caller can write
+ * the resolved name into `DesignPlan.siteDesignContext.fonts` and trust
+ * it passes the schema's NEXT_FONT_DISPLAY_NAMES validation.
+ */
+export declare function resolveFontDisplayName(name: string): string;
+/** Display names advertised to the DesignPlan prompt (kept in registry order). */
+export declare const NEXT_FONT_DISPLAY_NAMES: readonly string[];
+export declare function fontStack(value: string | undefined, fallback: string): string;
+/**
+ * The two site font CSS variables consumed by generated globals.css. Shared by
+ * the server materializer (design-css-materializer) and the workspace try-on
+ * path so the fallback semantics (sans follows body; heading falls back to
+ * body) can never drift between preview and apply.
+ */
+export declare function siteFontVariables(fonts?: {
+    heading?: string;
+    body?: string;
+}): {
+    "--site-font-sans": string;
+    "--site-font-heading": string;
+};
+/** A curated heading/body pairing surfaced by the workspace design panel. */
+export interface FontPairing {
+    /** Stable kebab-case id persisted nowhere; used for UI selection state. */
+    id: string;
+    /** Display name key into NEXT_FONT_REGISTRY. */
+    heading: string;
+    /** Display name key into NEXT_FONT_REGISTRY. */
+    body: string;
+}
+/**
+ * Pairings shown in the workspace design panel. Keep every name a valid
+ * NEXT_FONT_REGISTRY display-name key (enforced by font-catalog.test.ts).
+ * CJK pairings stay system-stack only (`download: false` entries).
+ */
+export declare const FONT_PAIRINGS: readonly FontPairing[];