base-paint 0.1.0 → 0.3.0

package/dist/spec/help.d.ts

@@ -0,0 +1,353 @@
+/** base-paint/spec/help：HELP 壳与 scene-data 契约（#78 冻结面）。
+ *
+ * B6：HELP 形态 = HTML 速查台；Q11：取 F3 并回补 F1／F2 的逐场景 CLI 展示与变体示例。
+ * AC-3：场景类型徽章字段取 **`types`（复数）**，不提供 `type` 别名（旧侧
+ *   `docs/scene-data-contract.md:78` 与 `docs/scene_data.schema.json:70` 用 `types`，
+ *   旧侧 `docs/help-template-contract.md:51` 用 `type` —— 本契约是对该分歧的裁定）。
+ *   引证更正（#78 施工期取证 R2）：旧稿把笔误出处写成 `assets/help_template.html:52`，
+ *   该行实为 CSS；模板资产本身用 `s.types`（`help_template.html:224`）。裁定结论不变。
+ * AC-4：`SCENE_DATA_SCHEMA` 是**唯一机读权威**，文档 §3.5 只是它的可读投影。
+ *
+ * 依赖红线：只许 `import type`（AC-13）；壳复用面见 `HelpShellInput`（#88 直接消费）。
+ */
+import type { FillTemplateOutput, TemplateAssets } from './template.js';
+/** 场景状态只允许两值（旧 `injector.py:168-169`）。 */
+export declare const SCENE_STATUS: readonly ["", "【待开发】"];
+export type SceneStatus = (typeof SCENE_STATUS)[number];
+/** 唯一权威字段名（AC-3）：复数，无单数别名。 */
+export declare const SCENE_TYPE_FIELD: "types";
+export interface SceneTypeBadge {
+    readonly text: string;
+    readonly bg?: string;
+    readonly fg?: string;
+}
+export interface SceneEditableField {
+    readonly name: string;
+    readonly label: string;
+    readonly value: string;
+    readonly hint?: string;
+    readonly required?: boolean;
+}
+export interface Scene {
+    readonly id: string;
+    readonly title: string;
+    readonly wake_word: string;
+    readonly types?: readonly (string | SceneTypeBadge)[];
+    readonly status: SceneStatus;
+    readonly prompt_template: string;
+    readonly editable_fields?: readonly SceneEditableField[];
+}
+export interface SceneSubgroup {
+    readonly id: string;
+    readonly label: string;
+    readonly scenes: readonly Scene[];
+}
+export interface SceneGroup {
+    readonly id: string;
+    readonly icon?: string;
+    readonly label: string;
+    readonly subgroups: readonly SceneSubgroup[];
+}
+export interface SceneMetaBlock {
+    readonly id: string;
+    readonly title: string;
+    /** 技能方提供的 HTML 原文，Base 原样透传（转义由技能方自理）。 */
+    readonly html: string;
+}
+export interface SceneInitBanner {
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly button_text?: string;
+    readonly prompt?: string;
+    readonly steps?: readonly string[];
+}
+export interface SceneContactItem {
+    readonly label: string;
+    readonly value: string;
+}
+export interface SceneContact {
+    readonly items: readonly SceneContactItem[];
+    readonly copy_all?: string;
+}
+export interface SceneRecommendation {
+    readonly name: string;
+    readonly reason?: string;
+    readonly wake_word?: string;
+}
+/** HELP 页对外参数（scene_data）顶层契约。 */
+export interface SceneData {
+    readonly skill_name: string;
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly meta_blocks?: readonly SceneMetaBlock[];
+    readonly groups: readonly SceneGroup[];
+    readonly init_banner?: SceneInitBanner;
+    readonly contact?: SceneContact;
+    readonly version?: string;
+    readonly recommendations?: readonly SceneRecommendation[];
+}
+/** 唯一机读 schema（draft-07 子集；文档 §3.5 逐字段投影它）。 */
+export declare const SCENE_DATA_SCHEMA: Readonly<{
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "ilife://base-paint/scene-data.schema.json";
+    readonly title: "scene_data";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["skill_name", "title", "groups"];
+    readonly properties: {
+        readonly skill_name: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly subtitle: {
+            readonly type: "string";
+        };
+        readonly meta_blocks: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "title", "html"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly html: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly groups: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "label", "subgroups"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly icon: {
+                        readonly type: "string";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                    };
+                    readonly subgroups: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "label", "scenes"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly label: {
+                                    readonly type: "string";
+                                };
+                                readonly scenes: {
+                                    readonly type: "array";
+                                    /** 文档 §3.5.2 明写「`scenes[]`（必填，**非空**）」；机读权威此前缺该约束
+                                     *  （#78 施工期取证 R1 缺陷 1，AC-4 下即缺陷态）→ 补齐 `minItems: 1`。 */
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["id", "title", "wake_word", "status", "prompt_template"];
+                                        readonly properties: {
+                                            readonly id: {
+                                                readonly type: "string";
+                                            };
+                                            readonly title: {
+                                                readonly type: "string";
+                                            };
+                                            readonly wake_word: {
+                                                readonly type: "string";
+                                            };
+                                            readonly types: {
+                                                readonly type: "array";
+                                                readonly items: {
+                                                    readonly oneOf: readonly [{
+                                                        readonly type: "string";
+                                                    }, {
+                                                        readonly type: "object";
+                                                        readonly additionalProperties: false;
+                                                        readonly required: readonly ["text"];
+                                                        readonly properties: {
+                                                            readonly text: {
+                                                                readonly type: "string";
+                                                            };
+                                                            readonly bg: {
+                                                                readonly type: "string";
+                                                            };
+                                                            readonly fg: {
+                                                                readonly type: "string";
+                                                            };
+                                                        };
+                                                    }];
+                                                };
+                                            };
+                                            readonly status: {
+                                                readonly enum: readonly ["", "【待开发】"];
+                                            };
+                                            readonly prompt_template: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly editable_fields: {
+                                                readonly type: "array";
+                                                readonly items: {
+                                                    readonly type: "object";
+                                                    readonly additionalProperties: false;
+                                                    readonly required: readonly ["name", "label", "value"];
+                                                    readonly properties: {
+                                                        readonly name: {
+                                                            readonly type: "string";
+                                                        };
+                                                        readonly label: {
+                                                            readonly type: "string";
+                                                        };
+                                                        readonly value: {
+                                                            readonly type: "string";
+                                                        };
+                                                        readonly hint: {
+                                                            readonly type: "string";
+                                                        };
+                                                        readonly required: {
+                                                            readonly type: "boolean";
+                                                        };
+                                                    };
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly init_banner: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["title"];
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                };
+                readonly subtitle: {
+                    readonly type: "string";
+                };
+                readonly button_text: {
+                    readonly type: "string";
+                };
+                readonly prompt: {
+                    readonly type: "string";
+                };
+                readonly steps: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly contact: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["items"];
+            readonly properties: {
+                readonly items: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["label", "value"];
+                        readonly properties: {
+                            readonly label: {
+                                readonly type: "string";
+                            };
+                            readonly value: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+                readonly copy_all: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly version: {
+            readonly type: "string";
+        };
+        readonly recommendations: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["name"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                    readonly wake_word: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+}>;
+export declare const HELP_SHELL_ID = "ilife-help-shell";
+/** 一键复制目标（Q11／#88 复用面）。 */
+export declare const HELP_COPY_TARGETS: readonly ["prompt", "wakeWord", "params"];
+export type HelpCopyTarget = (typeof HELP_COPY_TARGETS)[number];
+/** id → actionId → 对外文案（FX-7）：文案统一「复制…」，`prompt` 一律写「**复制指令**」
+ *  （不写「复制 prompt」）；actionId 供 `bindCopyAction` 分发（§3.3）。 */
+export declare const HELP_COPY_ACTIONS: Readonly<{
+    readonly prompt: {
+        readonly actionId: "ilife-help-copy-prompt";
+        readonly label: "复制指令";
+    };
+    readonly wakeWord: {
+        readonly actionId: "ilife-help-copy-wakeWord";
+        readonly label: "复制唤醒词";
+    };
+    readonly params: {
+        readonly actionId: "ilife-help-copy-params";
+        readonly label: "复制参数";
+    };
+}>;
+export interface HelpShellInput {
+    readonly sceneData: SceneData;
+    /** 共享资产走同一填充器（B3）：HELP 壳不得自填。 */
+    readonly assets: TemplateAssets;
+    readonly strict?: boolean;
+    /** 覆盖内置壳模板；缺省用 base-paint 自带模板。 */
+    readonly template?: string;
+}
+/** 冻结签名：`renderHelpShell(input: HelpShellInput): FillTemplateOutput`。 */
+export type RenderHelpShell = (input: HelpShellInput) => FillTemplateOutput;
+export declare const HELP_SCHEMA_ERROR_CODES: readonly ["schema-invalid", "duplicate-id", "status-invalid", "types-invalid"];
+export type HelpSchemaErrorCode = (typeof HELP_SCHEMA_ERROR_CODES)[number];
+export interface HelpSchemaErrorShape {
+    readonly name: 'HelpSchemaError';
+    readonly code: HelpSchemaErrorCode;
+    readonly path: string;
+    readonly message: string;
+}
+//# sourceMappingURL=help.d.ts.map

package/dist/spec/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/spec/help.ts"],"names":[],"mappings":"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"}

package/dist/spec/help.js

@@ -0,0 +1,167 @@
+/** base-paint/spec/help：HELP 壳与 scene-data 契约（#78 冻结面）。
+ *
+ * B6：HELP 形态 = HTML 速查台；Q11：取 F3 并回补 F1／F2 的逐场景 CLI 展示与变体示例。
+ * AC-3：场景类型徽章字段取 **`types`（复数）**，不提供 `type` 别名（旧侧
+ *   `docs/scene-data-contract.md:78` 与 `docs/scene_data.schema.json:70` 用 `types`，
+ *   旧侧 `docs/help-template-contract.md:51` 用 `type` —— 本契约是对该分歧的裁定）。
+ *   引证更正（#78 施工期取证 R2）：旧稿把笔误出处写成 `assets/help_template.html:52`，
+ *   该行实为 CSS；模板资产本身用 `s.types`（`help_template.html:224`）。裁定结论不变。
+ * AC-4：`SCENE_DATA_SCHEMA` 是**唯一机读权威**，文档 §3.5 只是它的可读投影。
+ *
+ * 依赖红线：只许 `import type`（AC-13）；壳复用面见 `HelpShellInput`（#88 直接消费）。
+ */
+/** 场景状态只允许两值（旧 `injector.py:168-169`）。 */
+export const SCENE_STATUS = ['', '【待开发】'];
+/** 唯一权威字段名（AC-3）：复数，无单数别名。 */
+export const SCENE_TYPE_FIELD = 'types';
+/** 唯一机读 schema（draft-07 子集；文档 §3.5 逐字段投影它）。 */
+export const SCENE_DATA_SCHEMA = Object.freeze({
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'ilife://base-paint/scene-data.schema.json',
+    title: 'scene_data',
+    type: 'object',
+    additionalProperties: false,
+    required: ['skill_name', 'title', 'groups'],
+    properties: {
+        skill_name: { type: 'string', minLength: 1 },
+        title: { type: 'string', minLength: 1 },
+        subtitle: { type: 'string' },
+        meta_blocks: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'title', 'html'],
+                properties: { id: { type: 'string' }, title: { type: 'string' }, html: { type: 'string' } },
+            },
+        },
+        groups: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'label', 'subgroups'],
+                properties: {
+                    id: { type: 'string' },
+                    icon: { type: 'string' },
+                    label: { type: 'string' },
+                    subgroups: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['id', 'label', 'scenes'],
+                            properties: {
+                                id: { type: 'string' },
+                                label: { type: 'string' },
+                                scenes: {
+                                    type: 'array',
+                                    /** 文档 §3.5.2 明写「`scenes[]`（必填，**非空**）」；机读权威此前缺该约束
+                                     *  （#78 施工期取证 R1 缺陷 1，AC-4 下即缺陷态）→ 补齐 `minItems: 1`。 */
+                                    minItems: 1,
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        required: ['id', 'title', 'wake_word', 'status', 'prompt_template'],
+                                        properties: {
+                                            id: { type: 'string' },
+                                            title: { type: 'string' },
+                                            wake_word: { type: 'string' },
+                                            types: {
+                                                type: 'array',
+                                                items: {
+                                                    oneOf: [
+                                                        { type: 'string' },
+                                                        {
+                                                            type: 'object',
+                                                            additionalProperties: false,
+                                                            required: ['text'],
+                                                            properties: { text: { type: 'string' }, bg: { type: 'string' }, fg: { type: 'string' } },
+                                                        },
+                                                    ],
+                                                },
+                                            },
+                                            status: { enum: ['', '【待开发】'] },
+                                            prompt_template: { type: 'string', minLength: 1 },
+                                            editable_fields: {
+                                                type: 'array',
+                                                items: {
+                                                    type: 'object',
+                                                    additionalProperties: false,
+                                                    required: ['name', 'label', 'value'],
+                                                    properties: {
+                                                        name: { type: 'string' },
+                                                        label: { type: 'string' },
+                                                        value: { type: 'string' },
+                                                        hint: { type: 'string' },
+                                                        required: { type: 'boolean' },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        init_banner: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['title'],
+            properties: {
+                title: { type: 'string' },
+                subtitle: { type: 'string' },
+                button_text: { type: 'string' },
+                prompt: { type: 'string' },
+                steps: { type: 'array', items: { type: 'string' } },
+            },
+        },
+        contact: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['items'],
+            properties: {
+                items: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['label', 'value'],
+                        properties: { label: { type: 'string' }, value: { type: 'string' } },
+                    },
+                },
+                copy_all: { type: 'string' },
+            },
+        },
+        version: { type: 'string' },
+        recommendations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['name'],
+                properties: { name: { type: 'string' }, reason: { type: 'string' }, wake_word: { type: 'string' } },
+            },
+        },
+    },
+});
+export const HELP_SHELL_ID = 'ilife-help-shell';
+/** 一键复制目标（Q11／#88 复用面）。 */
+export const HELP_COPY_TARGETS = ['prompt', 'wakeWord', 'params'];
+/** id → actionId → 对外文案（FX-7）：文案统一「复制…」，`prompt` 一律写「**复制指令**」
+ *  （不写「复制 prompt」）；actionId 供 `bindCopyAction` 分发（§3.3）。 */
+export const HELP_COPY_ACTIONS = Object.freeze({
+    prompt: { actionId: 'ilife-help-copy-prompt', label: '复制指令' },
+    wakeWord: { actionId: 'ilife-help-copy-wakeWord', label: '复制唤醒词' },
+    params: { actionId: 'ilife-help-copy-params', label: '复制参数' },
+});
+export const HELP_SCHEMA_ERROR_CODES = [
+    'schema-invalid',
+    'duplicate-id',
+    'status-invalid',
+    'types-invalid',
+];
+//# sourceMappingURL=help.js.map

package/dist/spec/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/spec/help.ts"],"names":[],"mappings":"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"}

package/dist/spec/index.d.ts

@@ -0,0 +1,40 @@
+/** base-paint/spec：冻结的共享层契约类型汇总（#92 / 79a）。
+ *
+ * 本目录 = **冻结的共享层契约类型**；`src/contract.ts` = **既有渲染契约**
+ *（envelope→HTML）。两者不同物：前者是 #74–#78 的施工图，后者是既有运行时。
+ *
+ * 纪律：spec/ 内只许类型与纯数据常量，禁函数体实现、禁副作用、
+ * 禁第三方 import、禁 `node:`、禁运行时 import base-link-core（只许 `import type`）。
+ *
+ * `SPEC_FROZEN_SURFACE` 是**冻结面清单**（机器可读唯一真相源）：
+ * 文档 §3 的签名表是它的投影，`test-d/contract-signatures.ts` 与
+ * `test/contract-signatures.test.mjs` 把清单／文档／类型三者绑死。
+ *
+ * 覆盖面口径（V1 洞 15）：清单锁**主签名**（每条 = 一个对外名字）；
+ * 被主签名引用但未单列的类型（`ClipboardChannel`／`CopyButtonInput`／`ToastAction`／8 个 `*ChartInput`／
+ * `SceneGroup` 等）以 `src/spec/*.ts` 为唯一真相源，其形状变更视同签名变更（须走 changeset ＋ 三处同步）。
+ */
+export * from './template.js';
+export * from './style.js';
+export * from './controls.js';
+export * from './text.js';
+export * from './charts.js';
+export * from './help.js';
+/** 契约版本（与 RENDER_CONTRACT_VERSION／ENVELOPE_VERSION 同值，漂移由签名测试钉死）。 */
+export declare const BASE_PAINT_CONTRACT_VERSION: "0.1.0";
+export type FrozenSurfaceKind = 'runtime' | 'type';
+export type FrozenSurfaceStatus = 'implemented' | 'pending';
+export type FrozenSurfaceSection = '3.1' | '3.2' | '3.3' | '3.4' | '3.5' | '5' | '7';
+export type FrozenSurfaceTicket = '#74' | '#75' | '#76' | '#77' | '#78' | '#92';
+export interface FrozenSurfaceEntry {
+    readonly name: string;
+    readonly kind: FrozenSurfaceKind;
+    readonly ticket: FrozenSurfaceTicket;
+    /** implemented = #92 已落地（纯数据／类型）；pending = 留给执行票实现。 */
+    readonly status: FrozenSurfaceStatus;
+    readonly section: FrozenSurfaceSection;
+    /** 逐字签名（与文档 §3 签名表逐字一致，由签名测试比对）。 */
+    readonly signature: string;
+}
+export declare const SPEC_FROZEN_SURFACE: readonly FrozenSurfaceEntry[];
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/spec/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAE1B,qEAAqE;AACrE,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAAC;AACnD,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,SAAS,CAAC;AAC5D,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,GAAG,GAAG,GAAG,CAAC;AACrF,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEhF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,mBAAmB,EAAE,SAAS,kBAAkB,EAgJ3D,CAAC"}