@vcp-dev/contracts 0.3.14

package/dist/site-edit-repeat-instance-key.d.ts

@@ -0,0 +1,11 @@
+export interface SiteEditRepeatInstanceKeyPart {
+    repeatIndex: number;
+}
+export interface ParsedSiteEditRepeatInstanceKey {
+    baseKey: string;
+    parts: SiteEditRepeatInstanceKeyPart[];
+}
+export declare function makeSiteEditRepeatInstanceKey(baseKey: string, repeatIndex: number): string;
+export declare function composeSiteEditRepeatInstanceKey(baseKey: string, repeatIndexes: readonly number[]): string;
+export declare function parseSiteEditRepeatInstanceKey(key: string | null | undefined): ParsedSiteEditRepeatInstanceKey | null;
+export declare function stripSiteEditRepeatInstanceKeys(key: string | null | undefined): string | null;

package/dist/site-edit-runtime-capability.d.ts

@@ -0,0 +1,21 @@
+export declare const SITE_EDIT_RUNTIME_VOID_ELEMENT_TAGS: readonly ["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"];
+export declare const SITE_EDIT_RUNTIME_CONTAINER_TAGS: readonly ["article", "aside", "div", "footer", "form", "header", "li", "main", "nav", "ol", "section", "select", "table", "tbody", "tfoot", "thead", "tr", "ul"];
+export declare const SITE_EDIT_RUNTIME_TEXT_TAGS: readonly ["a", "button", "em", "h1", "h2", "h3", "h4", "h5", "h6", "label", "p", "small", "span", "strong"];
+export type SiteEditRuntimeVoidElementTag = (typeof SITE_EDIT_RUNTIME_VOID_ELEMENT_TAGS)[number];
+export type SiteEditRuntimeContainerTag = (typeof SITE_EDIT_RUNTIME_CONTAINER_TAGS)[number];
+export type SiteEditRuntimeTextTag = (typeof SITE_EDIT_RUNTIME_TEXT_TAGS)[number];
+export type SiteEditRuntimeFallbackMode = "preview" | "strict";
+export type SiteEditRuntimeOperationSummary = {
+    canUpdateText: boolean;
+    canInsertChild: boolean;
+    canMove: boolean;
+    canRemove: boolean;
+};
+export declare function isSiteEditRuntimeVoidElementTag(tagName?: string | null): boolean;
+export declare function isSiteEditRuntimeContainerTag(tagName?: string | null): boolean;
+export declare function isSiteEditRuntimeTextTag(tagName?: string | null): boolean;
+export declare function resolveSiteEditRuntimeOperationSummary(params: {
+    operationSummary?: SiteEditRuntimeOperationSummary | null;
+    tagName?: string | null;
+    fallbackMode?: SiteEditRuntimeFallbackMode;
+}): SiteEditRuntimeOperationSummary;

package/dist/site-edit-runtime-capability.js

@@ -0,0 +1 @@
+var a=["area","base","br","col","embed","hr","img","input","link","meta","param","source","track","wbr"],o=["article","aside","div","footer","form","header","li","main","nav","ol","section","select","table","tbody","tfoot","thead","tr","ul"],T=["a","button","em","h1","h2","h3","h4","h5","h6","label","p","small","span","strong"],r=new Set(a),i=new Set(o),E=new Set(T),c={canUpdateText:!1,canInsertChild:!1,canMove:!1,canRemove:!1};function I(e){return r.has(n(e))}function _(e){return i.has(n(e))}function s(e){return E.has(n(e))}function l(e){let{operationSummary:t}=e;return t?{canUpdateText:t.canUpdateText,canInsertChild:t.canInsertChild,canMove:t.canMove,canRemove:t.canRemove}:e.fallbackMode!=="preview"?{...c}:{canUpdateText:s(e.tagName),canInsertChild:_(e.tagName),canMove:!1,canRemove:!1}}function n(e){return e?.trim().toLowerCase()??""}export{o as SITE_EDIT_RUNTIME_CONTAINER_TAGS,T as SITE_EDIT_RUNTIME_TEXT_TAGS,a as SITE_EDIT_RUNTIME_VOID_ELEMENT_TAGS,_ as isSiteEditRuntimeContainerTag,s as isSiteEditRuntimeTextTag,I as isSiteEditRuntimeVoidElementTag,l as resolveSiteEditRuntimeOperationSummary};

package/dist/site-edit-version.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 当前 edit-engine 公开包统一版本号。
+ * 三个包（@vcp-dev/contracts / @vcp-dev/site-edit-engine / @vcp-dev/site-edit-bridge）
+ * 始终同号发布。
+ *
+ * 由 release-edit-engine-packages.ts 在 bump 版本时自动更新。
+ */
+export declare const CURRENT_EDIT_ENGINE_VERSION = "0.3.14";
+export declare const EDIT_ENGINE_VERSION_HEADER = "x-vcp-edit-engine-version";
+export declare const EDIT_ENGINE_VERSION_SOURCE_HEADER = "x-vcp-edit-engine-version-source";
+export type EditEngineVersionSource = "explicit" | "fallback_current" | "system_current";
+export interface ResolvedEditEngineVersion {
+    version: string;
+    source: EditEngineVersionSource;
+}
+export declare class EditEngineVersionParseError extends Error {
+    readonly code: "EDIT_ENGINE_VERSION_INVALID";
+    constructor(message?: string);
+}
+export declare function isExactEditEngineVersion(value: string): boolean;
+export declare function parseExactEditEngineVersion(value: unknown): string;
+export declare function resolveRequestedEditEngineVersion(value: unknown): ResolvedEditEngineVersion;
+export declare function resolveSystemCurrentEditEngineVersion(): ResolvedEditEngineVersion;

package/dist/site-locale.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+/**
+ * 白名单 BCP-47 code（与 {@link SUPPORTED_SITE_LOCALES} 同序同值）。
+ * 显式 literal tuple 以便 `z.enum` 推导出精确联合类型。
+ */
+export declare const SITE_LOCALE_CODES: readonly ["zh-CN", "en", "ja", "es", "fr", "de", "zh-TW", "ko", "pt", "pt-BR", "it", "ru", "ar", "hi", "id", "vi", "th", "tr", "nl", "pl", "uk", "sv", "da", "fi", "no", "cs", "el", "hu", "ro", "he", "ms", "fil", "bn", "ta", "ca", "sk", "hr", "bg", "lt", "lv", "et", "fa", "sw", "sr", "is"];
+export declare const SiteLocaleSchema: z.ZodEnum<{
+    "zh-CN": "zh-CN";
+    en: "en";
+    ja: "ja";
+    es: "es";
+    fr: "fr";
+    de: "de";
+    "zh-TW": "zh-TW";
+    ko: "ko";
+    pt: "pt";
+    "pt-BR": "pt-BR";
+    it: "it";
+    ru: "ru";
+    ar: "ar";
+    hi: "hi";
+    id: "id";
+    vi: "vi";
+    th: "th";
+    tr: "tr";
+    nl: "nl";
+    pl: "pl";
+    uk: "uk";
+    sv: "sv";
+    da: "da";
+    fi: "fi";
+    no: "no";
+    cs: "cs";
+    el: "el";
+    hu: "hu";
+    ro: "ro";
+    he: "he";
+    ms: "ms";
+    fil: "fil";
+    bn: "bn";
+    ta: "ta";
+    ca: "ca";
+    sk: "sk";
+    hr: "hr";
+    bg: "bg";
+    lt: "lt";
+    lv: "lv";
+    et: "et";
+    fa: "fa";
+    sw: "sw";
+    sr: "sr";
+    is: "is";
+}>;
+export type SiteLocale = z.infer<typeof SiteLocaleSchema>;
+/**
+ * 站点产出语种（访客看到的语言）的事实源白名单。
+ *
+ * - `code`：BCP-47 标签，持久化进 `SiteRecord.default_locale`，并直接用于
+ *   生成站点产物的 `<html lang>`。
+ * - `label`：语种自称（endonym，如 `日本語` / `Español`），**不随界面语言变**，
+ *   控件主显示。
+ * - `common`：是否常用，控件浮层默认置顶展示。
+ *
+ * 语种在当前界面语言下的释义（exonym，如「日语」/「Japanese」）**不放这里**——
+ * 它随界面语言变化，由前端 i18n（`clarify` 命名空间 `siteLanguage.names.<code>`）
+ * 提供，避免界面切到英文时右侧仍显示中文。
+ *
+ * `default_locale` 为 NOT NULL：Step 1 创建站点时由后端轻量语言检测写入
+ * （识别不出兜底 {@link DEFAULT_SITE_LOCALE}），用户可在 Step 2 覆盖。
+ */
+export interface SiteLocaleOption {
+    code: SiteLocale;
+    label: string;
+    common?: boolean;
+}
+/**
+ * 控件展示用元数据（前 6 项为常用，控件默认置顶）。code 必须落在白名单内。
+ * `label` 是语种自称（endonym），不随界面语言变；释义（exonym）走前端 i18n。
+ */
+export declare const SUPPORTED_SITE_LOCALES: readonly SiteLocaleOption[];
+/**
+ * 识别不确定 / 失败时的兜底语种。`default_locale` 不可为空，故必须有终极兜底。
+ */
+export declare const DEFAULT_SITE_LOCALE: SiteLocale;
+/**
+ * 轻量语言检测库（franc 系）输出的 ISO 639-3 → 白名单 BCP-47。
+ * 映射未命中时由调用方兜底为 {@link DEFAULT_SITE_LOCALE}。
+ * 注：franc 不区分简繁，`cmn` 统一归 `zh-CN`，繁体靠用户在 Step 2 手选。
+ */
+export declare const ISO_639_3_TO_SITE_LOCALE: Readonly<Record<string, SiteLocale>>;
+/**
+ * 把检测库输出的 ISO 639-3 归一到白名单 BCP-47；未命中返回 {@link DEFAULT_SITE_LOCALE}。
+ */
+export declare function resolveSiteLocaleFromIso6393(iso6393: string): SiteLocale;

package/dist/theme-presets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Platform-curated theme presets for the workspace design panel. Each preset
+ * carries ONLY brand/accent anchor seeds — the full token set derives via
+ * deriveDesignColors, so contrast safety is computed, not authored.
+ * zh-CN labels are end-user facing (generated sites are zh-CN-first).
+ */
+export interface ThemePreset {
+    id: string;
+    /** End-user facing label (zh-CN). */
+    label: string;
+    colorSeeds: {
+        primary: string;
+        accent: string;
+    };
+}
+export declare const THEME_PRESETS: readonly ThemePreset[];

package/dist/user-facing-copy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Workspace iteration 用户面文案 single source of truth（详见 Plan Task 11）。
+ *
+ * 凡是会被用户看到的字符串（错误 banner、拒绝模板、澄清卡片标签、聊天提示）
+ * 必须从这里导出，前后端共用。禁止在 app 代码里硬编码 user-facing 英文/中文文案。
+ *
+ * - `ERROR_COPY`：用户面错误兜底；任何 agent `run.failed` 的 `error_code` 必须能
+ *   映射到这里的一个 key，找不到时由前端回退到 `GENERIC`。
+ * - `REFUSAL_COPY`：模型拒绝越界请求时的统一英文模板（system prompt 注入）。
+ * - `CLARIFICATION_COPY`：澄清卡片 UI 文案。
+ * - `CHAT_COPY`：聊天面板小型提示文案。
+ */
+export declare const ERROR_COPY: {
+    readonly PATCH_VALIDATION_FAILED: "The code didn't pass validation. Try describing the change more specifically.";
+    readonly PATCH_BATCH_FAILED: "The site code couldn't be generated. Please regenerate the site.";
+    readonly PATCH_BATCH_INVALID: "The change couldn't be applied. Try simpler instructions.";
+    readonly VALIDATION_FAILED: "Your message couldn't be sent as written. Please edit it and try again.";
+    readonly WORKSPACE_MESSAGE_CONTAINS_SECRET: "Your message looks like it contains a secret or token, so it wasn't sent. Remove it and try again.";
+    readonly WORKSPACE_TOOL_RESULT_INVALID: "This change couldn't be completed and was rolled back. Please try again.";
+    readonly WORKSPACE_TOOL_FAILED: "A tool step failed. Please try again.";
+    readonly WORKSPACE_TOOL_RESULT_MISSING: "The tool didn't return a usable result. Please try again.";
+    readonly WORKSPACE_MODEL_STREAM_FAILED: "The model stream ended unexpectedly. Please try again.";
+    readonly WORKSPACE_MODEL_STREAM_ABORTED: "Generation was interrupted before finishing. Please try again.";
+    readonly MODEL_OUTPUT_TRUNCATED: "The response was too long and was cut off before any change was applied. Try again, or split the request into smaller changes.";
+    readonly WORKSPACE_EDIT_NOT_APPLIED: "No change was applied. Try describing the change differently.";
+    readonly WORKSPACE_INITIAL_EXECUTION_FAILED: "Initial generation failed. Please retry from the brief.";
+    readonly WORKSPACE_INITIAL_GENERATION_CHECK_FAILED: "Initial generation could not be verified. Please retry.";
+    readonly WORKSPACE_INITIAL_GENERATION_FINALIZE_FAILED: "Initial generation could not finalize. Please retry.";
+    readonly WORKSPACE_INITIAL_GENERATION_QUALITY_GATE_FAILED: "Initial generation failed quality checks. Please regenerate the site.";
+    readonly WORKSPACE_ITERATION_QUALITY_GATE_FAILED: "Quality check failed. The change was rolled back; try a smaller or more specific request.";
+    readonly WORKSPACE_SOCKET_DEAD: "The workspace connection was lost. Please retry.";
+    readonly WORKSPACE_RUN_CANCELLED: "The run was cancelled.";
+    readonly WORKSPACE_RUN_ABANDONED: "This run was interrupted and did not finish. Please try again.";
+    readonly WORKSPACE_RUN_REQUEST_FAILED: "Couldn't start the workspace. Please try again.";
+    readonly WORKSPACE_RUN_BAD_RESPONSE: "The server response was malformed. Please try again.";
+    readonly WORKSPACE_SOCKET_UNAVAILABLE: "Workspace connection unavailable. Please try again.";
+    readonly WORKSPACE_SOCKET_ERROR: "The workspace connection had an error. Please try again.";
+    readonly WORKSPACE_SOCKET_CLOSED: "The workspace connection closed. Please try again.";
+    readonly WORKSPACE_SOCKET_OPEN_TIMEOUT: "Couldn't reach the workspace in time. Please try again.";
+    readonly WORKSPACE_CLIENT_MESSAGE_ID_MISSING: "Something went wrong sending your message. Please try again.";
+    readonly SITE_SNAPSHOT_REQUIRED: "This site has no usable snapshot yet. Complete Step 3 first.";
+    readonly AGENT_TIMEOUT: "That took longer than expected. Try breaking the change into smaller pieces.";
+    readonly SANDBOX_NOT_AVAILABLE: "The preview environment isn't ready. Your edits have still been saved.";
+    readonly PREVIEW_BUILD_FAILED: "Preview is available, but the production build failed. Fix the reported build error before deploying.";
+    readonly PREVIEW_BUILD_NOT_CONFIGURED: "Preview is available, but the production build check is not configured.";
+    readonly PREVIEW_BUILD_SANDBOX_NOT_FOUND: "Preview is available, but the build check could not find the active preview sandbox.";
+    readonly WS_CONNECTION_ERROR: "Connection lost. Reconnecting…";
+    readonly USER_MESSAGE_PERSIST_FAILED: "Your message wasn't saved. Please send it again.";
+    readonly CLARIFICATION_REPLY_STALE: "That question has expired. Please tell me what you'd like to do now.";
+    readonly CLARIFY_MODEL_FAILED: "Clarify couldn't finish generating questions. Please try again.";
+    readonly WORKSPACE_RUN_IN_FLIGHT: "Another session is already running. Please try again in a moment.";
+    readonly SITE_OPERATION_LOCKED: "Another change is already running for this site. Wait for it to finish, then try again.";
+    readonly EDIT_ENGINE_VERSION_INVALID: "Invalid editor version. Refresh the page and try again.";
+    readonly SANDBOX_DEPENDENCY_SYNC_FAILED: "The preview runtime could not be prepared. Please try again.";
+    readonly SANDBOX_DEPENDENCY_VERSION_MISMATCH: "The preview runtime could not be verified. Please try again.";
+    readonly SANDBOX_RUNTIME_NOT_READY: "The preview needs to be refreshed before this change can be applied. Refresh the preview and try again.";
+    readonly GENERIC: "Something went wrong. Please try again.";
+};
+export declare const REFUSAL_COPY: {
+    readonly UNDO_OR_ROLLBACK: "I can't roll back from chat. Use the version history at the top right to pick a restore point.";
+    readonly HISTORY_RECALL: "Tell me what you'd like to change now—I'll work from the current page state.";
+    readonly OUT_OF_SCOPE: "That's outside what I can do from chat. Try the corresponding panel on the right.";
+};
+export declare const CLARIFICATION_COPY: {
+    readonly CARD_HEADER: "Needs your confirmation";
+    readonly FREE_TEXT_PLACEHOLDER: "Or describe what you'd like instead";
+    readonly SUBMIT_LABEL: "Submit";
+};
+export declare const CHAT_COPY: {
+    readonly SEND_FAILED_RETRY: "Send failed — tap to retry";
+};
+export type ErrorCopyKey = keyof typeof ERROR_COPY;
+export type RefusalCopyKey = keyof typeof REFUSAL_COPY;
+export type ClarificationCopyKey = keyof typeof CLARIFICATION_COPY;
+export type ChatCopyKey = keyof typeof CHAT_COPY;

package/dist/workspace-design-apply.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/** Anchor-seed + font selection applied by the workspace design panel. */
+export declare const WorkspaceDesignApplyRequestSchema: z.ZodObject<{
+    colorSeeds: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodString;
+        accent: z.ZodString;
+    }, z.core.$strict>>;
+    fonts: z.ZodOptional<z.ZodObject<{
+        heading: z.ZodString;
+        body: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkspaceDesignApplyRequest = z.infer<typeof WorkspaceDesignApplyRequestSchema>;
+export declare const WorkspaceDesignApplyResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    design_plan_version: z.ZodNumber;
+    snapshot_id: z.ZodString;
+}, z.core.$strip>;
+export type WorkspaceDesignApplyResponse = z.infer<typeof WorkspaceDesignApplyResponseSchema>;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@vcp-dev/contracts",
+  "version": "0.3.14",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.cedemo.cn/vibe-coding-platform/vcp.git"
+  },
+  "homepage": "https://gitlab.cedemo.cn/vibe-coding-platform/vcp",
+  "bugs": {
+    "url": "https://gitlab.cedemo.cn/vibe-coding-platform/vcp/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./site-edit-runtime-capability": {
+      "development": "./src/site-edit-runtime-capability.ts",
+      "types": "./dist/site-edit-runtime-capability.d.ts",
+      "default": "./dist/site-edit-runtime-capability.js"
+    },
+    "./design-tokens": {
+      "development": "./src/design-tokens.ts",
+      "types": "./dist/design-tokens.d.ts",
+      "default": "./dist/design-tokens.js"
+    },
+    "./colorway-distinctness": {
+      "development": "./src/colorway-distinctness.ts",
+      "types": "./dist/colorway-distinctness.d.ts",
+      "default": "./dist/colorway-distinctness.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "test": "vitest run --root ../.. packages/contracts/src",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "culori": "^4.0.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/culori": "^4.0.1",
+    "typescript": "^5.8.0"
+  }
+}