openpuppet-language 2.0__py3-none-any.whl

openpuppet_language-2.0.data/data/share/puppet/spec/04-vocabulary.md

@@ -0,0 +1,227 @@
+# 04 · 词汇
+
+## 1. 总则
+
+- 词汇是**标准的一部分**：控件、属性、事件、图标名都由本规范**按语义**定义。
+- **禁止**以"某个渲染后端不支持"为理由从标准中删除词汇；渲染器缺失支持时**必须**声明并产生可见降级（`DEGRADED_FEATURE`），**禁止**渲染成空白。
+- 属性分两类：
+  - **值类**：可以写字面量，也可以写表达式（构成活绑定，见 `03-semantics.md` 第 2 节）。
+  - **引用类**：必须是指向程序中另一实体的地址引用或字面量，**禁止**写表达式（违反即 `REF_ATTR_EXPR`）。
+- 未出现在本表内的属性名 → **警告** `UNKNOWN_ATTR`（带行号与近似建议），**禁止**静默丢弃。
+
+## 2. 节点类型
+
+| 类型 | 语义 | 备注 |
+|---|---|---|
+| `window` | 顶层窗口 / 页面 | 根节点的直接子节点 |
+| `col` | 纵向容器 | 默认 `gap=8` |
+| `row` | 横向容器 | 默认 `gap=8` |
+| `navbar` | 顶部栏 | 标题 + 可选动作位 |
+| `list` | 数据源驱动的重复容器 | 需要 `source` 与 `template` |
+| `tabs` | 分页容器 | **每个直接子节点是一页**；`selected` 为页序号（从 0 起） |
+| `template` | 行模板 | 页面内不渲染；见 `01-grammar.md` 第 8 节 |
+| `text` | 文本 | — |
+| `icon` | 图标 | `icon` 取语义名 |
+| `divider` | 分隔线 | — |
+| `spacer` | 弹性留白 | — |
+| `progress` | 进度 | 不写 `value` 即"不确定态" |
+| `image` | 图片 | — |
+| `avatar` | 头像 | `src` / `initials` / `icon` 三选一，兜底可见 |
+| `button` | 按钮 | 可选 `icon` + `text`；默认圆角 8 |
+| `input` | 单行输入 | 值走 `value` |
+| `checkbox` | 勾选 | 值走 `value` |
+| `switch` | 开关 | 值走 `value` |
+| `slider` | 滑块 | `value` / `min` / `max` / `step` |
+| `dropdown` | 下拉选择 | **选中值走 `selected`**；选项由 `options` 提供 |
+
+## 3. 通用属性
+
+### 3.1 盒模型（值类）
+
+| 属性 | 语义 |
+|---|---|
+| `pad` | 内边距（单值或"上下 左右"两值） |
+| `margin` | 外边距 |
+| `bgcolor` | 背景颜色 |
+| `gradient` | 渐变（两个颜色） |
+| `radius` | 圆角 |
+| `border` | 边框（"宽度 颜色"） |
+| `shadow` | 阴影强度 |
+| `opacity` | 不透明度 |
+
+### 3.2 布局（值类）
+
+| 属性 | 语义 |
+|---|---|
+| `gap` | 子节点间距（`col`/`row`/`list` 默认 8） |
+| `justify` | 主轴分布 |
+| `align` | 交叉轴对齐 |
+| `wrap` | 是否换行 |
+| `flex` | 弹性占比 |
+| `scroll` | 溢出滚动方式 |
+| `w` / `h` | 尺寸（不写则由内容决定） |
+| `x` / `y` | 绝对位置（不参与正常流动布局） |
+| `offset` | 相对偏移（在正常布局位置基础上平移） |
+| `scale` | 缩放比例 |
+| `rotate` | 旋转角度 |
+
+### 3.3 排版（值类）
+
+`fg`、`size`、`weight`、`italic`、`font`、`tooltip`。
+
+- `window` 上的 `font` 与 `primary` 是**整页主题**（全局字体与主色）。
+
+### 3.4 内容
+
+| 属性 | 类别 | 语义 |
+|---|---|---|
+| `text` | 值类 | 文本内容 |
+| `icon` | 值类 | 图标语义名（未知即 `UNKNOWN_ICON`） |
+| `src` | 值类 | 资源地址（相对资源目录或远程地址） |
+| `fit` | 值类 | 图片填充方式 |
+| `initials` | 值类 | 头像文字兜底 |
+| `size` | 值类 | 头像直径 |
+| `value` | 值类 | 输入 / 选择 / 进度的当前值 |
+| `selected` | 值类 | `dropdown` 的选中项、`tabs` 的页序号 |
+| `min` / `max` / `step` | 值类 | 滑块边界与步长 |
+| `placeholder` | 值类 | 占位提示 |
+| `title` | 值类 | 窗口标题 |
+| `source` | **引用类** | 数据源地址 |
+| `template` | **引用类** | 模板地址 |
+| `options` | **引用类** | 下拉选项的数据源地址 |
+| `option_label` / `option_value` | 值类 | 选项在数据行中对应的字段名 |
+| `as` | 声明 | 模板的绑定名（不是值，不参与求值） |
+| `primary` | 值类 | 主题主色 |
+
+### 3.5 状态标志（运行期属性，可读写）
+
+`hover`、`focus`、`pressed`、`error`、`visible`、`disabled`。
+
+- 读取：`#id.<标志>`；写入：`set #id <标志>=<布尔>`。
+- `disabled=true` 的节点**不触发**交互事件（引擎层拦截，见 `03-semantics.md` 第 3.4 节）。
+- `visible=false` 的节点**不占位**、不接收交互。
+
+### 3.6 状态外观 `states`（值类，字典）
+
+```
+states={hover: {bgcolor: "#eef2ff"}, error: {border: "1 #dc2626"}, focus: {border: "2 #93c5fd"}}
+```
+
+- 键：状态名（`hover` / `focus` / `pressed` / `error`）。
+- 值：**外观属性表**，允许的属性白名单见下。
+- 白名单：`bgcolor`、`fg`、`gradient`、`border`、`radius`、`shadow`、`opacity`、`size`、`weight`、`italic`、`align`。
+- 出现布局类属性（`pad` / `margin` / `gap` / `flex` / `w` / `h` / `x` / `y` / `scroll` / `justify` / `wrap`）→ **警告** `STATE_LAYOUT_ATTR`。
+- 出现白名单外属性 → **警告** `STATE_UNKNOWN_ATTR`。
+- 状态外观**不触发事件、不改写程序**。
+
+### 3.7 动效
+
+| 属性 | 类别 | 语义 |
+|---|---|---|
+| `animate` | 值类 | 参与过渡的属性名列表 |
+| `duration` | 值类 | 过渡时长（毫秒），默认 200 |
+| `curve` | 值类 | 缓动名，默认 `ease_out` |
+
+- 未声明 `animate` 即**不做任何过渡**。
+- 交互控件的状态过渡**可以**由实现默认开启（且必须在能力声明中可见）。
+
+## 4. 控件专属属性汇编
+
+- `window`：`title`、`w`、`h`、`bgcolor`（整窗底色）、`font` / `primary`（整页主题）。
+- `list`：`source`、`template`。
+- `tabs`：`selected`。
+- `input`：`value`、`placeholder`。
+- `checkbox` / `switch`：`value`。
+- `slider`：`value`、`min`、`max`、`step`。
+- `dropdown`：`selected`、`options`、`option_label`、`option_value`。
+- `progress`：`value`（省略即不确定态）。
+- `image`：`src`、`fit`、`radius`。
+- `avatar`：`src`、`initials`、`icon`、`size`。
+
+属性用于不适用的类型 → **警告** `ATTR_ON_TYPE`。
+
+## 5. 事件名
+
+| 事件 | 来源 |
+|---|---|
+| `click` | 可交互节点的点按 |
+| `change` | 值变化（输入、勾选、开关、滑块、下拉） |
+| `submit` | 输入框确认 |
+| `focus` / `blur` | 获得 / 失去焦点 |
+| `change`（数据源） | 数据源内容变化 |
+| `pending` / `done` / `error` / `timeout` / `cancel` | 槽状态变化 |
+
+未识别事件名 → **警告** `UNKNOWN_EVENT`。
+
+### 5.1 主交互事件
+
+| 控件 | 主交互事件 |
+|---|---|
+| `button` | `click` |
+| `checkbox` / `switch` / `slider` / `dropdown` | `change` |
+
+- 这些事件**既没有处理器、也没有被订阅、且其值无人读取**时 → **警告** `UNCOVERED_INTERACTION`：用户对它做的那个动作**不会有任何反应**——因为**没有任何人在看它**。
+- 这不是"必须绑定"，而是"你漏了这件事必须被说出来"——因为"点了没反应"是最典型的静默失败。
+- **两种"有人管"的情形，不得报警告**：
+  - **被 `listen` 订阅**：外部驱动者（LLM 或调度者）会在观察流里看到并响应；
+  - **值在别处被读取**：`#控件.value` / `#控件.selected` 出现在程序的任何表达式里——"提交时才读控件的值"是常见且完全正当的写法。
+- **不在表内的两类控件**：
+  - `input`：能打字本身不是需要被响应的动作。若应用确实需要，显式绑定 `change` 或 `submit`；
+  - `tabs`：切换选项卡本身就有渲染效果（换显示哪一页），不需要处理器。
+
+## 6. 可动画属性（语义定义）
+
+按**语义类别**定义，不按任何后端的实现能力定义：
+
+| 类别 | 属性 |
+|---|---|
+| 透明度 | `opacity` |
+| 颜色 | `bgcolor`、`fg`、`gradient`、`border` |
+| 尺寸 | `w`、`h`、`size`、`radius`、`pad`、`margin`、`gap` |
+| 位置 | `x`、`y`、`align`、`justify`、`offset` |
+| 变换 | `scale`、`rotate` |
+| 值 | `value` |
+
+`animate` 中出现表外属性 → **警告** `ANIMATE_UNKNOWN`。
+渲染器**可以**不支持其中部分属性，但**必须**在能力声明中列出，并在实际降级时产生 `DEGRADED_FEATURE`。
+
+## 7. 图标
+
+### 7.1 规则
+
+- 图标以**语义名**引用（如 `add`、`delete`、`search`）。
+- 实现**必须**支持**核心子集**；**可以**支持更多。
+- 未识别的图标名 → **警告** `UNKNOWN_ICON`（带近似建议）；**禁止**静默渲染为空白。
+
+### 7.2 核心子集（必须支持）
+
+```
+add  remove  delete  edit  save  close  check  cancel  search  settings
+home  menu  more  refresh  download  upload  share  copy  filter  sort
+star  favorite  user  users  lock  unlock  mail  phone  calendar  clock
+location  image  camera  play  pause  stop  file  folder  document  list
+grid  chart  cart  payment  bell  warning  info  error  success  help
+arrow_up  arrow_down  arrow_left  arrow_right  chevron_up  chevron_down
+chevron_left  chevron_right  plus  minus  eye  eye_off  link  tag  flag
+```
+
+## 8. 内置函数
+
+算术与比较不属函数。以下内置函数由标准定义：
+
+| 函数 | 说明 |
+|---|---|
+| `count(x)` | 集合 / 列表长度（**普通函数**，不限于数据源） |
+| `len(x)` | 字符串或集合长度 |
+| `upper(s)` / `lower(s)` / `trim(s)` | 字符串处理 |
+| `contains(a, b)` | 包含判定 |
+| `num(x)` / `str(x)` | 显式类型转换 |
+| `abs(x)` / `min(a, b)` / `max(a, b)` / `sum(xs)` / `round(x)` | 数值处理 |
+| `join(xs, sep)` / `split(s, sep)` | 字符串与列表互转 |
+| `at(xs, i)` / `first(xs)` / `last(xs)` / `slice(xs, a, b)` | 列表访问 |
+| `keys(d)` / `values(d)` / `has(d, k)` | 字典访问 |
+| `fmt(tpl, …)` | 格式化 |
+
+- 函数集**可以扩充**（属兼容改动）。
+- 未知函数 → **错误** `EXPR_UNKNOWN_FUNC`。
+- 参数个数或类型不符 → **错误** `EXPR_TYPE`。

openpuppet_language-2.0.data/data/share/puppet/spec/05-render-contract.md

@@ -0,0 +1,126 @@
+# 05 · 渲染契约
+
+## 1. 总则：本契约只描述**可观察行为**
+
+- 本文件定义"用户能看到什么、能在什么条件下触发什么"，**不定义**任何后端的控件、属性或 API 映射。
+- **禁止**在本文件中出现"某属性等价于某后端某类的某字段"这类写法。渲染器如何实现是渲染器的自由。
+- 凡本文件**未定义**的（字体度量、像素级外观、滚动条样式、动画缓动的精确曲线）→ **实现自由**，但同一实现在等价输入下**必须**给出一致结果。
+- 渲染器**必须**声明其支持范围：控件 / 属性 / 动效 / 图标四类**词汇能力**，外加**几何** / **截图** /
+  **无 GUI 驱动**三项观测与驱动能力。声明**必须机读**（conformance 实现协议第 4.1.1 节的 `hello`
+  握手）：词汇能力为数组（`null` = 支持全部标准），观测能力为布尔。
+- **任何缺失或不支持都必须产生可见降级**（`DEGRADED_FEATURE`，**必须**带 `feature` 字段指明被
+  降级的特性），**禁止**渲染成空白、**禁止**静默忽略。
+- **声明即 oracle**：conformance 以声明决定每条渲染期望是硬断言、还是退化为要求可见降级——
+  声明支持却做不到 = 不符；未声明支持却静默 = 不符。
+
+## 2. 布局语义
+
+- **子节点顺序**：容器按声明顺序排列子节点；锚点插入（`before` / `after`）改变的是这个顺序。
+- **主轴与交叉轴**：
+  - `col` 的主轴为纵向，`row` 的主轴为横向；
+  - `gap` 定义**相邻子节点之间的间隔**；`justify` 定义子节点在主轴上的分布；`align` 定义在交叉轴上的对齐。
+- **窗口布局**（派生决定，已确认）：`window` 的直接子节点按**纵向**流动，等价于一个隐式的 `col`
+  （`gap` / `justify` / `align` 同样适用）。渲染器不必为 window 另造一套布局规则。
+- **弹性**：`flex` 表示剩余空间的分配比例。未声明 `flex` 的节点按内容尺寸参与布局。
+- **换行**：`wrap=true` 时，主轴放不下的子节点进入下一行 / 下一列。
+- **滚动**：`scroll` 声明时，溢出内容可滚动；未声明时溢出**可以**被裁剪。
+- **尺寸**：显式给出 `w` / `h` 即为固定尺寸；未给出即由内容决定。`flex` 与显式尺寸同时存在时，**应该**以 `flex` 分配为基础、显式尺寸为约束下限。
+- **绝对定位**：给出 `x` / `y` 的节点不参与正常流动布局。
+- **不占位**：`visible=false` 的节点**必须**从布局中移除（不留空位）。
+
+## 3. 值呈现语义
+
+- **文本**：超出可用空间时**应该**截断或以省略号收尾；`tooltip` 存在时**应该**提供完整内容的查看方式。
+- **图标**：以单色字形呈现，颜色随 `fg`。
+- **进度**：给出 `value` 时为确定进度；未给出时**必须**呈现为"正在进行"的不确定态（而不是空条）。
+- **图片**：`fit` 定义图片与可用空间的关系；**加载失败必须可见**（占位或错误标记），**禁止**空白。
+- **头像**：`src` / `initials` / `icon` 三选一；资源不可用时**必须**回退到下一个可用形式，全部不可用时**必须**显示可见占位。兜底内容在资源加载期间**应该**已经可见。
+- **下拉选项**：`options` 指向的数据源为空时，**必须**呈现为"无可选项"的可见状态。
+
+## 4. 交互语义
+
+- **可交互节点**：`button`、`input`、`checkbox`、`switch`、`slider`、`dropdown`、`tabs`，以及声明了 `ink` 语义的容器。
+- **渲染器必须把用户动作转成对应事件**：用户在节点上的实际操作（点按、输入内容、勾选、切换）
+  **必须**按下面的可观察定义产生事件。渲染器**禁止**把事件来源限制为"只有程序化调用"——
+  否则外部驱动者无法分辨"用户真的点了"与"只是引擎内部调了一下"。
+- **不能转必须可见降级**：渲染器无法投递某类用户动作时（如根本没有渲染层），
+  **必须**在投递时产生 `DEGRADED_FEATURE(feature=interaction)` 并如实报告"未送达"，
+  **禁止**假装已送达——"点了没反应"正是静默失败。
+- **事件触发条件**（可观察定义）：
+  - `click`：在节点范围内按下并释放；
+  - `change`：值发生变化（输入内容改变、勾选改变、开关翻转、滑块移动、下拉选中改变）；
+  - `submit`：输入框内确认动作；
+  - `focus` / `blur`：该节点成为 / 不再是键盘输入目标。
+- **禁用**：`disabled=true` 的节点**不响应**交互，且**必须**呈现为不可用外观。拦截**必须**在引擎层同时生效（见 `03-semantics.md` 第 3.4 节），不得只依赖界面层。
+- **不可见**：`visible=false` 的节点不占位，因此不可能被交互。
+- **`tooltip`**：指针悬停一段时间后呈现，内容为 `tooltip` 的值。
+- **`ink` 语义**：容器声明可点按高亮时，按下/悬停**应该**呈现可感知的反馈。
+
+## 5. 状态外观语义
+
+### 5.1 状态来源
+
+- `hover`：指针进入节点范围；`focus`：节点成为键盘目标；`pressed`：按住；`error`：由程序写入的运行期标志。
+- 这四个状态是**运行期属性**，程序可以读取（`#id.hover`）与写入（`set #id error=true`）。
+
+### 5.2 状态优先级（派生决定，已确认）
+
+- **互斥组**：`hover` / `focus` / `pressed` 同时最多一个生效，优先级 **`pressed` > `focus` > `hover`**。
+- **正交叠加**：`error` 与 `disabled` 不参与上面的互斥，可与互斥组中的状态同时存在。
+- **生效顺序**：
+  1. 节点的基础属性；
+  2. 互斥组中优先级最高的那个状态的外观（若 `states` 中有声明）；
+  3. `error` 的外观覆盖（若声明且 `error=true`）；
+  4. `disabled=true` 时，整体呈现不可用外观（降亮或等价处理）。
+
+### 5.3 约束
+
+- `states` 中只允许外观属性（见 `04-vocabulary.md` 第 3.6 节）；布局属性与非白名单属性分别触发 `STATE_LAYOUT_ATTR` / `STATE_UNKNOWN_ATTR`。
+- 状态外观**不触发事件**、**不改写程序**。
+
+## 6. 动效语义
+
+- `animate` 列出参与过渡的属性；这些属性在值变化时**应该**在 `duration` 毫秒内按 `curve` 过渡到新值。
+- 未声明 `animate` → **不做过渡**，值立即改变。
+- 状态外观的变化（如悬停变色）**可以**默认带过渡；若默认开启，**必须**在能力声明中说明。
+- 渲染器不支持某属性动画时 → **必须**产生 `DEGRADED_FEATURE`，并立即改变该值（不得静默保持原值导致"看起来没反应"）。
+
+## 7. 可观察性（最低要求）
+
+渲染器**必须**让外部驱动者能够获得以下三类观察——这是"能观察"的定义，也是外部调度者唯一被保证的能力：
+
+| 观察面 | 内容 |
+|---|---|
+| **事件流** | 诊断、状态变更摘要、槽状态、订阅事件（见 `03-semantics.md` 第 6 节） |
+| **状态快照** | 数据项、节点运行期状态、槽状态、修订号 |
+| **视觉快照** | 当前界面的图像表示（供驱动者自行决定是否用作自检）；**可选**能力 |
+| **几何快照** | **可选**：各节点的矩形（见第 8 节）。不支持时**必须**在被询问（`where`）时可见降级 |
+
+- **是否使用**视觉快照做自检，属驱动者的决定，**不是**渲染器的模式。能力不随"是否带 LLM"而出现或消失。
+- 视觉快照**可以**按需产生，不必持续。
+- 几何快照与视觉快照是**两条独立**的观测能力：各自声明、各自降级——有几何者仍**可以**没有截图，反之亦然。截图是**兜底**（人看 / 驱动者自行判断），几何是**断言**（机器可判定关系）；二者不互相替代。
+
+## 8. 几何快照与关系断言词汇（可选观测）
+
+几何快照是**可选**能力；一旦提供，外部驱动者即有权用以下**定性 / 相对**关系描述布局期望。
+全部关系**不比较绝对坐标**——字号、DPI、窗口尺寸不同**不得**导致断言不可移植：
+
+| 类别 | 关系 | 语义 |
+|---|---|---|
+| 方位 | `left_of` / `right_of` / `above` / `below` | a 整体在 b 的左 / 右 / 上 / 下（允许 `tol` 内的接触） |
+| 包含 | `contains` / `inside` | a 的矩形完全罩住 / 被罩于 b（允许 `tol`） |
+| 重叠 | `overlaps` / `disjoint` | 两矩形相交面积非零 / 不相交 |
+| 对齐 | `aligned_x` / `aligned_y` | 左缘 / 上缘之差 ≤ `tol` |
+| 对齐 | `aligned_center_x` / `aligned_center_y` | 中心之差 ≤ 2·`tol` |
+| 尺寸 | `same_width` / `same_height` / `same_size` | 宽 / 高 / 两者之差 ≤ `tol` |
+| 间距 | `gap_h` / `gap_v` | 相邻间隙 == `value` ± `tol` |
+| 比例 | `width_ratio` / `height_ratio` | 宽 / 高之比 == `value` ± `tol`（比例容差缺省 0.05） |
+
+- `tol` 为像素容差，缺省 **1**；间距 / 比例关系**必须**显式给 `value`。
+- 坐标系：以**窗口内容区**左上角为原点，向右 / 向下为正，单位为**浮点像素**。
+- 本节是**断言词汇**，不是布局系统的定义——布局语义仍以第 2 节为准；conformance 用例
+  （`conformance/cases/render.json`）按本表编写。
+
+## 9. 明确不定义的
+
+字体族与度量、像素级抗锯齿与阴影质量、滚动条外观、缓动曲线的精确数学形式、窗口装饰、主题的具体配色表。

openpuppet_language-2.0.data/data/share/puppet/spec/06-diagnostics.md

@@ -0,0 +1,151 @@
+# 06 · 诊断与错误模型
+
+## 1. 诊断的形状
+
+每条诊断**必须**包含：
+
+| 字段 | 说明 |
+|---|---|
+| 码 | 稳定标识符（本文件第 4 节的表），机读用 |
+| 级别 | 错误 / 警告 / 信息 |
+| 消息 | 人读说明，讲"发生了什么" |
+| 位置 | **编译期诊断必须有**：行号 + 列号；运行期诊断必须有可追溯来源 |
+| 建议 | 可选，讲"是不是想写…"，用于可猜错的场合（属性名、图标名） |
+
+诊断**必须**同时具备机读形式与文本形式。
+
+## 2. 级别语义
+
+| 级别 | 含义 |
+|---|---|
+| **错误** | 该语句**未应用**（编译期），或该运行期操作**失败**。**不中断本批**其余语句。 |
+| **警告** | 已应用，但语义可疑或很可能不是本意。 |
+| **信息** | 正常但驱动者值得知道：降级发生、陈旧结果被丢弃、事件丢失、状态被重建。 |
+
+## 3. 三条不可让步
+
+1. **精确位置**：编译期诊断必须带行号（**应该**带列号）。没有位置的诊断视为不合格。
+2. **部分应用 + 全量收集**：一条语句失败不阻断后续；批结束时**必须**给出全部诊断的汇总。
+3. **没有静默**：任何"降级 / 丢弃 / 未实现 / 上限触发 / 重建"**必须**至少产生一条信息级诊断或一条观察事件。**禁止**静默截断、静默丢弃、静默空白。
+
+## 4. 码表
+
+### 4.1 结构与地址
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `SYNTAX` | 错误 | 该行不符合语法（词法或语法错误），**该行未应用**，不影响本批其余行 |
+| `ID_DUP` | 错误 | 地址已被占用 |
+| `PARENT_MISSING` | 错误 | 父地址不存在 |
+| `TARGET_MISSING` | 错误 | `set` 目标不存在 |
+| `ANCHOR_MISSING` | 错误 | `before` / `after` 锚点不存在 |
+| `MOVE_CYCLE` | 错误 | `move` 造成自环或成环 |
+| `DEL_MISSING` | 警告 | `del` 目标不存在 |
+| `ROW_CONTEXT` | 错误 | 派发行内事件却无法确定行上下文（不在模板内 / 行序号越界 / 模板未绑定） |
+| `TEMPLATE_UNUSED` | 警告 | 模板未被任何列表绑定 |
+
+### 4.2 词汇
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `UNKNOWN_ATTR` | 警告 | 属性名不在词汇表中（带近似建议） |
+| `UNKNOWN_TYPE` | 警告 | 节点类型不在词汇表中 |
+| `UNKNOWN_ICON` | 警告 | 图标语义名未识别（带近似建议） |
+| `UNKNOWN_EVENT` | 警告 | 事件名未识别 |
+| `ATTR_ON_TYPE` | 警告 | 属性不适用于该节点类型 |
+| `REF_ATTR_EXPR` | 错误 | 引用类属性写了表达式 |
+
+### 4.3 状态与动效
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `STATE_LAYOUT_ATTR` | 警告 | `states` 中出现布局类属性 |
+| `STATE_UNKNOWN_ATTR` | 警告 | `states` 中出现外观白名单之外的属性 |
+| `DISABLED_HANDLER` | 警告 | 静态 `disabled=true` 的节点却绑定了交互处理器 |
+| `ANIMATE_UNKNOWN` | 警告 | `animate` 中出现非语义可动画属性 |
+
+### 4.4 绑定与表达式
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `BIND_CYCLE` | 错误 | 绑定图出现环（编译期） |
+| `BIND_UNKNOWN_REF` | 错误 | 绑定的引用目标不存在 |
+| `BIND_EVAL` | 错误 | 绑定的运行期求值失败（类型不符、除零、未知字段、函数错误） |
+| `BIND_OVERRIDDEN` | 信息 | `set` / `upsert` 覆盖了一个已绑定属性，该绑定被解除 |
+| `WHEN_NOT_BOOL` | 错误 | `when` 守卫求值结果不是布尔 |
+| `EXPR_TYPE` | 错误 | 表达式类型不符（不在白名单转换内的混用） |
+| `EXPR_UNKNOWN_FUNC` | 错误 | 未知函数 |
+| `EXPR_DIV_ZERO` | 错误 | 运行期除零 |
+
+### 4.5 能力与槽
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `CALL_CONTRACT` | 错误 | 参数缺失 / 多余 / 类型不符 |
+| `CALL_UNKNOWN` | 错误 | 目标函数不存在 |
+| `CALL_RESULT` | 错误 | 返回值不可序列化或不符合声明结构 |
+| `CAP_NO_DOC` | 错误 | 能力的说明文本（docstring）为空——**不予注册** |
+| `CAP_DEPS_MISMATCH` | 警告 | 能力模块的依赖声明与实际 import 不一致（不迁移、不缺包） |
+| `CAP_IMPORT` | 错误 | 能力模块加载失败（文件缺失或导入抛错） |
+| `SLOT_TIMEOUT` | 错误 | 调用超时（观察为超时态） |
+| `SLOT_STALE_DROPPED` | 信息 | 旧序号的调用结果到达后被丢弃 |
+| `SLOT_CANCELLED` | 信息 | 进行中的调用被新调用取消 |
+
+### 4.6 执行与持久化
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `CONVERGENCE_LIMIT` | 错误 | 处理器级联达到轮次上限（**可见**，带触发链快照） |
+| `PERSIST_SCHEMA_DRIFT` | 警告 | 状态与程序声明不符（不迁移、不丢数据） |
+| `STATE_REBUILT` | 信息 | 状态文件缺失或不可读，从默认值重建 |
+
+### 4.7 观察与降级
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `OBSERVATION_DROPPED` | 警告 | 观察流发生事件丢失（必须带丢失区间） |
+| `DEGRADED_FEATURE` | 信息 | 渲染器不支持某**能力声明之外**的控件 / 属性 / 动效 / 图标 / 几何 / 截图 / 用户动作投递，已明确降级。**必须**带 `feature` 字段（机读）：`geometry` / `snapshot` / `interaction` / `control:<类型>` / `attr:<名>` / `animation:<名>` / `icon:<名>` |
+| `PROBE_NO_CONSUMER` | 警告 | 探针动词在无驱动者连接时被使用。**由宿主发出**——只有宿主知道有没有消费者 |
+
+**`DEGRADED_FEATURE` 与能力声明的闭环（声明即 oracle）**：能力声明（`05-render-contract.md`
+第 1 节）说"我支持什么"，本码说"我没支持的我说了"。conformance（`conformance/README.md`
+第 6 节）据此分档：声明支持却做不到、或未声明支持却静默，都不符合规范。降级的发生**不得**
+取决于"有没有 LLM 在看"——信息级诊断进观察流，谁连上谁看到。
+
+### 4.8 交互覆盖
+
+| 码 | 级别 | 触发 |
+|---|---|---|
+| `UNCOVERED_INTERACTION` | 警告 | 控件的主交互事件（见 `04-vocabulary.md` 第 5.1 节）**既没有处理器、也没有被订阅**——没有任何人在看它，用户操作不会有任何反应 |
+| `BOUND_VALUE_NOT_WRITTEN` | 警告 | 控件的 `value` / `selected` 绑定了数据源，且它有 `change` 处理器，但那些处理器**没有回写该数据源**——用户改动会被绑定重算覆盖（界面弹回） |
+
+## 5. 版本变更记录
+
+### 2.0（相对 1.x，**语义不兼容**）
+
+程序的可观察行为发生改变，旧程序**不能**保证在新实现下表现一致：
+
+- **值传播**：值类属性可直接写表达式并在渲染期持续求值；"`add` 静态字面量、`set` 求值"的分裂语义**废除**。
+- **程序与状态分离**：运行期产生的值**不再**写回程序文本。
+- **模板**：由语句改为节点类型，拥有独立地址与子节点；旧的"模板体内子节点"结构**不再存在**。
+- **状态**：`hover` / `focus` / `pressed` / `error` 由"仅外观的字符串字段"改为**可读写的运行期属性**；状态外观统一收敛到 `states`。旧写法**不再被接受**。
+- **控件**：`dropdown` 的选中值由 `value` 改为 `selected`。
+- **动效与图标**：白名单改由**语义**定义，不再跟随任何后端的实现能力。
+- **槽**：由三态（进行中 / 成功 / 失败）扩展为**五态**，新增**超时**与**取消**。
+- **收敛**：绑定传播不再有轮次上限（DAG 拓扑序一次求值到位）；处理器级联的上限触发改为**可见错误** `CONVERGENCE_LIMIT`，取代旧的静默截断。
+- **观察流**：队列压力下**不得**静默丢事件。
+- **依赖**：能力依赖由"扫描源码 import"改为**显式声明 + 扫描兜底 + 不一致报警**。
+- **插件**：取消"可改写下发的命令流"的钩子；标准语义不再可被插件改写。
+- **`listen`**：不再有"某模式下无消费者则降级"的特殊规则。
+- **注释记号**：`//` 取代 `#` + 空白（`#` 只作地址 / 颜色），两者彻底消歧。
+- **渲染观测面**：几何快照（`observe.geometry`）与视觉快照（`snapshot`）成为一等的
+  可选观测面；渲染器**必须**声明支持范围，未声明者被使用时产生 `DEGRADED_FEATURE`。
+- **用户动作投递**：渲染器**必须**把用户动作转成事件；不能转必须可见降级
+  （`feature=interaction`），**禁止**假装送达。
+- **能力层**：新增 `CAP_NO_DOC` / `CAP_DEPS_MISMATCH` / `CAP_IMPORT`；参数契约补齐
+  "多余参数"与"类型不符"的判定（此前只查缺失）。
+- **诊断形状**：`DEGRADED_FEATURE` 必须带机读的 `feature` 字段。
+
+### 2.x 兼容改动
+
+新增可选属性、控件、事件、图标、内置函数、诊断码，均属兼容改动，提升修订号即可。

openpuppet_language-2.0.data/data/share/puppet/spec/README.md

@@ -0,0 +1,73 @@
+# Puppet 语言规范
+
+- **规范版本**：`2.0`
+- **状态**：**已冻结**。冻结后任何条款都不得再改；改动语义**必须**升版本（见下），
+  并在 `06-diagnostics.md` 的变更记录中登记。冻结意味着：既有 `.puppet` 程序的行为
+  由本规范定义，实现不得反向影响它。
+- **本目录的性质**：语言标准的人读规范，**不是**实现文档。`puppet` 包的实现必须符合本规范；**conformance 用例从本规范编写**，不从实现反推。
+- **上层文件**：`docs/design-v2-draft.md`（设计草案）决定"为什么"；本目录决定"是什么"。
+
+---
+
+## 规范用语
+
+| 用语 | 含义 |
+|---|---|
+| **必须** / **禁止** | 实现必须满足；违反即不符合本规范 |
+| **应该** | 强烈建议；允许有理由的偏离，但必须产生可见诊断 |
+| **可以** | 可选 |
+| **未定义** | 本规范不作规定；实现可以自行选择，但**不得静默**——必须给出可见诊断或明确降级说明 |
+
+**贯穿全规范的一条总则**：任何"降级、丢弃、无效、未实现"都**必须**产生可见的诊断、日志或事件。静默失败视为规范违反。
+
+---
+
+## 章节
+
+| 章节 | 内容 |
+|---|---|
+| `01-grammar.md` | 词法与命令语法（记号、字面量、表达式、各动词） |
+| `02-ir.md` | 中间表示：**程序 IR 与状态 IR 两本账**、绑定图 |
+| `03-semantics.md` | 执行语义：命令批应用、值传播、事件、能力与槽、持久化 |
+| `04-vocabulary.md` | 词汇：控件、属性、状态、动画、图标 |
+| `05-render-contract.md` | 渲染契约：**只描述可观察行为** |
+| `06-diagnostics.md` | 诊断码表与错误模型 |
+
+---
+
+## 版本与兼容承诺
+
+- 规范有**独立版本号**，与实现版本解耦。
+- **改动语义即升版本**：任何使既有 `.puppet` 程序行为改变的改动，必须提升次版本或主版本，并在 `06-diagnostics.md` 的变更记录中登记。
+- **新增可选属性/控件**属兼容改动，可以只提升修订号。
+- 实现必须声明自己符合的规范版本；**行为与本规范不符时，以本规范为准**。
+
+---
+
+## 已确认的"派生决定"
+
+规范必须把设计草案里未落到语法层面的地方定下来。以下条款都是**从已定决定推导出来的**，
+已在正文标出，并经实现与 conformance 用例坐实；用户已逐条确认。**2.0 冻结时无未决项。**
+
+1. **`template` 从动词降为节点类型**：既然模板升格为一等节点（住节点表、有子节点），它就应该用 `add` 声明。因此动词总数由 13 降为 12。
+2. **状态外观收敛为单个 `states=` 属性**：既然状态标志（可读可写的运行期属性）与"状态下的外观"是两种东西，就应该分开。`states={hover: {bgcolor: #1d4ed8}}` 取代逐状态的字符串字段。
+3. **`set` 作用于已绑定属性时，解除绑定并写入字面量**，同时**必须**产生一条诊断（不得静默地"设置无效"）。
+4. **注释记号为 `//`**（不再与地址记号 `#` 共用）：`//` 到行尾为注释，`#` 只作地址/颜色。由此
+   `#bad` / `#dad` 这类短地址不再有被误判为颜色的风险。
+5. **颜色字面量与地址记号的消歧**：`#` 后接 **6 或 8 位**十六进制 = 颜色；`#` 后接其他标识符 = 地址。**不采用 3 位简写**——`#bad` / `#dad` / `#abc` / `#fed` 这类短地址会被误判成颜色（此问题由 conformance 用例暴露）。
+6. **动作可直接作顶层语句**：集合原语既可作为 `on` 之下的动作，也可作为独立语句由驱动者直接下发（见 `01-grammar.md` 第 7 节）。
+7. **行内事件必须携带行上下文**：派发者需给出行序号，引擎把模板的绑定名指向该行（见 `01-grammar.md` 第 8.1 节）。无法确定即报错 `ROW_CONTEXT`。
+8. **`window` 的子节点按纵向流动**：窗口子节点的排布语义与 `col` 一致（主轴纵向，`gap` / `justify` / `align` 同样适用），渲染器不必为 window 另造布局规则（由两个参考渲染器的实现反推，见 `05-render-contract.md` 第 2 节）。
+9. **绑定表达式不设额外白名单**：**任何值类属性都可以写表达式**（构成活绑定）；引用类属性一律禁止（`REF_ATTR_EXPR`）。属性归属哪一类由 `04-vocabulary.md` 标注，未标注者默认为值类。
+10. **探针"无人消费"不产生编译期警告**：探针是**只读查询**，不改变程序或状态，因此没有"无人消费"造成的失败。编译期也无从知道有没有驱动者连接——"有没有人看"由**宿主**在运行时判断（见 `01-grammar.md` 第 7.10 节）。
+
+---
+
+## 2.1 之后如何提新议题
+
+冻结**不是**终点，而是换了一种提要求的方式：
+
+- 新增可选属性 / 控件 / 事件 / 图标 / 内置函数 / 诊断码 → **兼容改动**，提升修订号（`2.1`）。
+- 任何使既有程序行为改变的改动 → 提升次版本或主版本，并在变更记录中登记。
+- 想让某个语义**变得可选或可替换**（例如渲染器可选择不提供几何）→ 属"能力声明 + 可见降级"的范畴，
+  由 `05-render-contract.md` 第 1 节的机制承载，**不需要**改语言语义。

openpuppet_language-2.0.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: openpuppet-language
+Version: 2.0
+Summary: Puppet 语言标准实现（设计 + 语言规范 + 参考实现）。零第三方依赖。
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: tk
+
+# Puppet 语言标准（发行名 `openpuppet-language`）
+
+**An app is an agent.** 本仓是 **Puppet 语言标准**的规范与参考实现：不含任何具体渲染实现，
+不含 app 宿主。
+
+| 目录 | 内容 |
+|---|---|
+| `spec/` | **人读规范**（`2.0`，**已冻结**）：01 词法语法 / 02 IR / 03 执行语义 / 04 词汇 / 05 渲染契约 / 06 诊断 |
+| `conformance/` | **可执行用例集**：随发行包分发，任意实现用它自证合规 |
+| `puppet/` | **参考实现**（零第三方依赖）：词法、IR、引擎、协议适配器、Tk 渲染器 |
+| `docs/design-v2-draft.md` | 设计草案：决定"为什么" |
+| `examples/` | 真实示例程序（`puppet validate examples --strict` 零诊断） |
+
+## 安装
+
+```bash
+pip install openpuppet-language
+```
+
+Tk 参考渲染器（`puppet conformance --tk`，真实几何）需要 Tcl/Tk：
+Debian/Ubuntu 需 `apt install python3-tk`。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `puppet spec` | 规范版本与位置 |
+| `puppet validate <路径>` | 静态校验 `.puppet` 文件或目录（`--strict`：有任何诊断即失败） |
+| `puppet conformance` | 跑合规用例集（`--tk` 改用 Tk 渲染器；`--filter <子串>` 过滤） |
+
+只想校验用例文件本身、不需要任何实现：
+
+```bash
+python conformance/runner.py --check
+```
+
+## 参与
+
+- **用例与实现都以 `spec/` 为准**：conformance 用例**从规范写**，不移植旧测试。
+- **杜绝静默失败**：任何降级、丢弃、未实现都必须产生诊断或观察事件。
+- **渲染器按能力声明行事**：启动握手（`hello`）声明支持范围，未声明支持的词汇被使用时
+  必须产生 `DEGRADED_FEATURE`——标准不靠信任，靠用例抓。