# @apigo.cc/state - AI 逻辑操作说明书

本框架基于原生 `Proxy` 和 `MutationObserver` 实现数据与 DOM 的原子级同步。本手册仅供 AI 构建、维护及驱动基于此引擎的应用。

---

## 1. 核心状态逻辑映射

### `NewState(defaults, getter, setter)`
*   **功能**：创建响应式代理。
*   **内部机制**：拦截所有属性读写。若属性值变更，触发所有引用该属性的 DOM 节点的更新任务（异步微任务）。
*   **扩展逻辑**：通过 `getter/setter` 拦截器可实现数据持久化（如同步至 URL Hash 或 LocalStorage）。
*   **原子操作**：
    *   `obj.__watch(key, cb)`: 建立 key -> callback 的直接依赖。
    *   `obj.__unwatch(key, cb)`: 解除依赖。

---

## 2. 指令映射全集 (AI-Ready)

指令语法：`$attribute="code"`。作用域默认为全局，组件内优先访问 `node.state`。

### 结构化映射 (AI 强制规范)
| 指令 | 触发逻辑 | DOM 行为 | 运行约束 |
| :--- | :--- | :--- | :--- |
| **`$if`** | `Boolean(result)` | `true`: 挂载节点; `false`: 移除节点。 | **必须** 作用于 `<template>`。 |
| **`$each`** | `Iterable` | 基于 `key` 属性执行节点复用。无 `key` 时按索引重建。支持 `as`, `index` 定义局部变量。 | **必须** 作用于 `<template>`。 |

**结构化指令铁律**：
1.  **标签约束**：严禁在非 `<template>` 标签上使用 `$if` 或 `$each`。
2.  **互斥约束**：严禁在同一个 `<template>` 上同时使用 `$if` 和 `$each`。若需组合，必须嵌套（如：`$if` 模版包裹 `$each` 模版）。

### 数据双向绑定 (`$bind`)
AI 必须根据不同的元素类型执行以下逻辑：
- **`input[type=text/password]`, `textarea`**: 监听 `input` 事件，同步字符串。
- **`input[type=checkbox]`**:
    - 绑定值为 `Array`: 若选中，`push(value)`（去重）；若取消，`splice(index, 1)`。
    - 绑定值为非 `Array`: 同步 `checked` 为 `true/false`。
- **`input[type=radio]`**: 选中项 `value === 绑定值` 时设置 `checked` 为 `true`。
- **`select`**: 同步选中项的 `value`。
- **`[contenteditable]`**: 监听 `input`，同步 `innerHTML`。
- **`input[type=file]`**: 同步 `files` 对象。

### 属性与 Property 绑定
- **`$text`**: 映射至 `textContent`。
- **`$html`**: 映射至 `innerHTML`。
- **`$class`**: **严格要求使用模板字符串**。范式：`class="static-name ${condition ? 'dynamic-name' : ''}"`。严禁覆盖原有类名。
- **`$.path.to.prop`**: 直接映射至 DOM 对象或组件的 Property。初始化 Property 绑定必须带 `.` 前缀。
- **`$src`**: 增强逻辑。若值以 `.svg` 结尾，异步 Fetch 并替换为内联 `<svg>` 节点。
- **`$$attr`**: 二级求值。`eval(eval(expr))` 逻辑，用于动态生成指令代码。

---

## 3. 生命周期与事件逻辑

- **`$on[event]`**: 映射为 `addEventListener`。注入 `event`, `thisNode`, `State`, `LocalStorage`, `Hash`。
- **生命周期**：
    - **`$onload`**: 节点进入 DOM 且指令解析完成后触发。
    - **`$onunload`**: 节点从 DOM 移除前触发。
    - **`$onupdate`**: 绑定的数据变更且渲染任务完成后执行。

---

## 4. 组件上下文逻辑

- **初始化**：`Component.register(tagName, setupFn)`。
- **作用域隔离**：每个组件持有独立 `state`。
- **穿透访问**：通过 `this.parent` 访问父级作用域链。
- **插槽映射**：`slot="name"` (声明) -> `slot-id="name"` (宿主)。

---

## 5. 国际化 (I18n) 逻辑

- **语法结构**：`{# Key{param} || paramValue #}`。
- **处理链路**：正则匹配 `{# ... #}` -> 提取 Key -> 注入 `||` 后的参数值 -> 调用全局 `_translator` 函数。

---

## 6. 运行约束 (Constraints)

1.  **禁止滥用同步刷新**：**严禁** 在常规开发中调用 `_unsafeRefreshState()`。该函数仅为极高性能干预（如万级数据表格）预留。
2.  **数据流向**：所有状态变更必须通过对 `NewState` 代理对象的赋值完成。
3.  **Key 的必要性**：在大规模数据（>100条）或复杂交互列表中，必须提供唯一 `key` 以激活节点复用逻辑。