asdshuaishuai/moonviz/core does not have a README file

    Action

    pub(all) enum Action {
    NavigateTo(String)
    Back
    ToggleState(String, String)
    SetState(String, String)
    SetText(String, String)
    SubmitForm(Array[String])
    ShowToast(String)
    HapticFeedback
    PlaySound(String)
    }

    Action::describe

    fn Action::describe(self : Action) -> String

    AgentNote

    pub(all) struct AgentNote {
    artboard : String
    note : String
    priority : String
    }

    Agent 中间产物协议:.moonviz 项目文件。

    这是 Agent 之间的"交接棒"——一个结构化的项目快照文件, 任何 Agent(或人类)都能读取当前设计状态、未完成事项、交互定义, 然后继续工作而不需要从零理解。

    格式为 JSON(可 diff、可版本控制、可跨语言解析):
    { "meta": { "version": "...", "created_by": "...", "context": "..." }, "tokens": { ... }, "artboards": { "login": { "decl": "...", "interactions": [...] } }, "flows": [ ... ], "todo": [ "待办事项" ], "notes": [ { "artboard": "...", "note": "...", "priority": "..." } ] }

    AgentSession

    pub(all) struct AgentSession {
    agent_id : String
    base_revision : Int
    ops : Array[DesignOp]
    }

    AgentSession::add_op

    fn AgentSession::add_op(self : AgentSession, op : DesignOp) -> Unit

    AgentSession::new

    fn AgentSession::new(agent_id : String, base_revision : Int) -> AgentSession

    AgentSession::summary

    fn AgentSession::summary(self : AgentSession) -> String

    会话摘要

    AgentTool

    pub(all) struct AgentTool {
    name : String
    description : String
    args : Array[ToolArg]
    }

    AlignmentHint

    pub(all) struct AlignmentHint {
    node_a : String
    node_b : String
    axis : String
    delta : Double
    suggestion : String
    }

    AnimatableProperty

    pub(all) enum AnimatableProperty {
    AnimFill(String)
    AnimOpacity(Double)
    AnimX(Double)
    AnimY(Double)
    AnimWidth(Double)
    AnimHeight(Double)
    AnimRadius(Double)
    AnimFontSize(Double)
    }

    AnimatableProperty::name

    fn AnimatableProperty::name(self : AnimatableProperty) -> String

    AnimatableProperty::to_double

    fn AnimatableProperty::to_double(self : AnimatableProperty) -> Double

    属性值的数值表示(用于插值;颜色返回 -1 表示不支持数值插值)

    AnimationClip

    pub(all) struct AnimationClip {
    node_id : String
    keyframes : Array[Keyframe]
    easing : Easing
    duration : Double
    delay : Double
    }

    AnimationClip::add_keyframe

    fn AnimationClip::add_keyframe(self : AnimationClip, time : Double, props : Array[AnimatableProperty]) -> Unit

    AnimationClip::new

    fn AnimationClip::new(node_id : String) -> AnimationClip

    ArtboardBenchmark

    pub(all) struct ArtboardBenchmark {
    artboard : String
    node_count : Int
    max_depth : Int
    avg_children : Double
    stack_layout_count : Int
    fill_node_count : Int
    hug_node_count : Int
    text_node_count : Int
    total_text_length : Int
    svg_output_length : Int
    layout_complexity : Int
    render_complexity : Int
    memory_estimate_bytes : Int
    antipatterns : Array[String]
    score : Int
    }

    性能基准引擎:节点数 / 布局求解复杂度 / 渲染开销 / 内存估算。

    Agent 生成设计后需要知道"这个设计跑得动吗?" 引擎通过复杂度分析(而非平台相关的 wall-clock 计时)给出:
    • 节点统计:总数 / 最大深度 / 平均子节点
    • 布局复杂度:栈布局数 / Fill 节点数 / Hug 节点数(高开销)
    • 渲染开销:SVG 输出长度 / 文字节点占比
    • 内存估算:基于节点数和文本量的近似值
    • 性能反模式检测:节点过多 / 嵌套过深 / Fill 过多
    • 优化建议:合并节点 / 减少嵌套 / 用 Fixed 替代 Fill

    ArtboardBenchmark::to_json

    fn ArtboardBenchmark::to_json(self : ArtboardBenchmark) -> String

    ArtboardMeta

    pub(all) struct ArtboardMeta {
    id : String
    name : String
    width : Double
    height : Double
    doc : Document
    }

    多画板项目:真实原型有多个页面(登录→首页→详情→设置), 画板之间有导航流(Flow),共享设计令牌与组件库。

    AutoFixOp

    pub(all) struct AutoFixOp {
    node_id : String
    predicate : String
    action : String
    before : String
    after : String
    }

    自动修复引擎:Agent 调用 auto_fix 即可清除全部视觉债。

    修复策略按谓词分类:
    • contained_in_parent → 缩小尺寸适配父容器(优先缩宽,再缩高)
    • no_sibling_overlap → 沿 Y 轴平移到无重叠位置
    • constraint_solvable → Fill→Fixed 降级(取父容器剩余空间) 另有组件规范预修(norms.mbt:按钮放大到文案+留白 / 圆角归档 8 / 全宽条直角), 在谓词迭代之前执行——规范修复可能引入新违规,交给后续谓词循环一并清理。 返回修复操作列表(供 Agent 审阅)+ 修复后的新 Project。

    Breakpoint

    pub(all) struct Breakpoint {
    name : String
    width : Double
    height : Double
    columns : Int
    description : String
    }

    响应式断点系统:同一设计在手机/平板/桌面三种尺寸下自动适配。

    Agent 创建一个 390px 的手机原型后,调用 generate_responsive:
    • 引擎自动生成 _tablet(768px)和 _desktop(1200px)变体
    • 垂直布局 → 平板变 2 列 → 桌面变 3 列(或侧边栏)
    • 组件尺寸按比例适配(卡片加宽、字号保持可读)

    CollabManager

    pub(all) struct CollabManager {
    sessions : Map[String, AgentSession]
    base_revision : Int
    }

    CollabManager::join

    fn CollabManager::join(self : CollabManager, agent_id : String) -> AgentSession

    CollabManager::merge_all

    fn CollabManager::merge_all(self : CollabManager) -> Array[MergeResult]

    两两合并所有会话

    CollabManager::new

    fn CollabManager::new(base_revision : Int) -> CollabManager

    CollabManager::status

    fn CollabManager::status(self : CollabManager) -> String

    协作状态摘要

    CollabManager::total_conflicts

    fn CollabManager::total_conflicts(self : CollabManager) -> Int

    总冲突数

    ColorNote

    pub(all) struct ColorNote {
    node_id : String
    field : String
    hex : String
    token_name : String
    }

    ComponentDef

    pub(all) struct ComponentDef {
    id : String
    kind : String
    description : String
    variants : Map[String, NodePatch]
    default_variant : String
    default_size : (Double, Double)
    default_layout : StackLayout?
    category : String
    }

    组件系统:Agent 可发现、可实例化、可变体的设计组件库。

    每个组件定义(ComponentDef)是一个"配方":
    • 有一组语义属性(variant: primary / secondary / danger)
    • 有默认的布局/样式(映射到设计令牌) Agent 通过 instantiate(def, variant) 获得可直接放入文档的 Node。

    ComponentNote

    pub(all) struct ComponentNote {
    node_id : String
    component : String
    variant : String
    props : String
    }

    ComponentStateDef

    pub(all) struct ComponentStateDef {
    node_id : String
    states : Map[String, NodePatch]
    current : String
    }

    组件多态(同一组件的不同视觉状态)

    Conflict

    pub(all) struct Conflict {
    node_id : String
    field : String
    ours_desc : String
    theirs_desc : String
    resolution : String
    suggestion : String
    }

    CritiqueResult

    pub(all) struct CritiqueResult {
    principle : String
    score : Int
    verdict : String
    observation : String
    advice : String
    }

    AI 设计批评引擎:像资深设计师一样评审原型。

    不是检查规则(那是 lint),而是基于设计原则给出整体评价:
    1. 视觉层次 — 有没有清晰的"第一眼看到什么"
    2. 亲密性 — 相关元素是否靠近(格式塔原理)
    3. 对齐 — 是否有一致的视觉轴线
    4. 一致性 — 相似元素是否有相似处理
    5. 留白 — 是否有足够的呼吸空间
    6. 平衡 — 视觉重量是否分布合理
    7. 焦点 — 是否有明确的主动作(CTA)
    8. 节奏 — 间距和尺寸是否有韵律感

    输出:结构化评审报告(每个原则一个评分 + 具体建议)

    DesignHistory

    pub(all) struct DesignHistory {
    entries : Array[HistoryEntry]
    current_revision : Int
    branch_name : String
    undo_stack : Array[Int]
    redo_stack : Array[Int]
    }

    DesignHistory::branch

    fn DesignHistory::branch(self : DesignHistory, from_rev : Int, branch_name : String) -> Result[Document, String]

    DesignHistory::checkout

    fn DesignHistory::checkout(self : DesignHistory, revision : Int) -> Result[Document, String]

    DesignHistory::commit

    fn DesignHistory::commit(self : DesignHistory, agent_id : String, message : String, ops : Array[DesignOp], doc : Document) -> Int

    DesignHistory::diff

    fn DesignHistory::diff(self : DesignHistory, from_rev : Int, to_rev : Int) -> Result[String, String]

    DesignHistory::log

    fn DesignHistory::log(self : DesignHistory) -> String

    DesignHistory::new

    fn DesignHistory::new(initial_doc : Document) -> DesignHistory

    DesignHistory::redo

    fn DesignHistory::redo(self : DesignHistory) -> Result[Document, String]

    DesignHistory::replay

    fn DesignHistory::replay(self : DesignHistory, from_rev : Int, to_rev : Int) -> Result[String, String]

    DesignHistory::rev

    fn DesignHistory::rev(self : DesignHistory) -> Int

    DesignHistory::undo

    fn DesignHistory::undo(self : DesignHistory) -> Result[Document, String]

    DesignLint

    pub(all) struct DesignLint {
    rule : String
    severity : String
    node_id : String
    message : String
    suggestion : String
    }

    DesignOp

    pub(all) enum DesignOp {
    OpInsert(String, String)
    OpDelete(String)
    OpMove(String, String)
    OpSetFill(String, String, String)
    OpSetRadius(String, Double, Double)
    OpSetFontSize(String, Double, Double)
    OpSetText(String, String, String)
    OpSetPosition(String, Double, Double, Double, Double)
    OpSetSize(String, Double, Double, Double, Double)
    OpSetGap(String, Double, Double)
    }

    多 Agent 设计协作系统:并行设计 + 冲突检测 + 三方合并。

    AI 时代的核心场景:多个 Agent 同时在一个原型上工作。
    • Agent A 设计登录页,Agent B 优化仪表盘,Agent C 调设计令牌
    • 完成后合并各自的修改,自动检测冲突

    合并策略(Git 风格三方合并):
    • base:两个 Agent 共同的起点
    • ours:Agent A 的操作序列
    • theirs:Agent B 的操作序列
    • 无交集 → 自动合并
    • 有交集 → 冲突标记 + 建议解法

    DesignOp::describe

    fn DesignOp::describe(self : DesignOp) -> String

    DesignOp::field

    fn DesignOp::field(self : DesignOp) -> String

    操作影响的字段(用于冲突检测:同字段 = 潜在冲突)

    DesignOp::from_text

    fn DesignOp::from_text(spec : String) -> DesignOp?

    DesignOp 文本规格(CLI/MCP 共用,分号分隔多个 op): insert:: | delete: | move:: fill::: | radius::: | font::: text::: | pos::::: size::::: | gap:::

    DesignOp::node_id

    fn DesignOp::node_id(self : DesignOp) -> String

    DesignSuggestion

    pub(all) struct DesignSuggestion {
    category : String
    severity : String
    description : String
    fix_command : String
    }

    DesignTokens

    pub(all) struct DesignTokens {
    colors : Map[String, String]
    spacing : Map[String, Double]
    radii : Map[String, Double]
    typography : Map[String, Double]
    }

    设计令牌系统:Agent 驱动设计的基础语言。

    统一管理颜色/间距/圆角/字号,组件和节点都引用令牌而非硬编码值。 Agent 通过 apply_token 引用令牌,引擎在布局/渲染时解析为具体值。 这样 Agent 生成的设计自动获得一致的主题(换主题只需改令牌表)。

    DesignTokens::apply_to_node

    fn DesignTokens::apply_to_node(self : DesignTokens, node : Node) -> Node

    将节点样式中的令牌引用解析为具体值(就地修改)

    DesignTokens::default

    fn DesignTokens::default() -> DesignTokens

    DesignTokens::resolve_color

    fn DesignTokens::resolve_color(self : DesignTokens, token_or_hex : String) -> String

    解析颜色令牌:"primary" → "#4B6BFB";非令牌直接返回

    DesignTokens::resolve_font

    fn DesignTokens::resolve_font(self : DesignTokens, token : String) -> Double?

    解析字号令牌:"h2" → 24.0

    DesignTokens::resolve_radius

    fn DesignTokens::resolve_radius(self : DesignTokens, token : String) -> Double?

    解析圆角令牌:"lg" → 12.0

    DesignTokens::resolve_spacing

    fn DesignTokens::resolve_spacing(self : DesignTokens, token : String) -> Double?

    解析间距令牌:"md" → 8.0

    DesignTokens::to_json

    fn DesignTokens::to_json(self : DesignTokens) -> String

    列出所有可用令牌(Agent 发现用)

    DiffEntry

    pub(all) struct DiffEntry {
    node_id : String
    before : String
    after : String
    }

    DocComment

    pub(all) struct DocComment {
    text : String
    anchor : String?
    }

    文档级宿主批注(issue #20):引擎零语义,原文透传。 anchor 为其后最近的画板 id/name(None = 文档级,序列化在文末)。

    DocDiff

    pub(all) struct DocDiff {
    added : Array[String]
    removed : Array[String]
    moved : Array[DiffEntry]
    resized : Array[DiffEntry]
    restyled : Array[DiffEntry]
    relayout : Array[DiffEntry]
    }

    语义 Diff:比较两个文档状态,输出人可读 + 机器可解析的变更描述。

    Agent 在执行操作后调用 diff_docs(before, after) 获得:
    • added:新增了哪些节点
    • removed:删除了哪些节点
    • moved:位置变化的节点
    • resized:尺寸变化的节点
    • restyled:样式变化的节点
    • relayout:布局参数变化 Agent 把这个 diff 作为"我做了什么"的自省报告。

    DocDiff::summary

    fn DocDiff::summary(self : DocDiff) -> String

    人可读摘要(一行)

    DocDiff::to_json

    fn DocDiff::to_json(self : DocDiff) -> String

    Diff 的 JSON 序列化(Agent 审阅用)

    Document

    pub(all) struct Document {
    root_id : String
    nodes : Map[String, Node]
    revision : Int
    journal : Array[JournalEntry]
    content_seq : Int
    }

    Document::clone

    fn Document::clone(self : Document) -> Document

    深拷贝:事务式合并的候选副本(apply 前先在副本上验证,见 docs/05)

    Document::find_parent

    fn Document::find_parent(self : Document, id : String) -> String?

    广度优先找父节点(v1 树很浅,无需缓存父指针)

    Document::from_json

    fn Document::from_json(text : String) -> Result[Document, String]

    从 JSON 文本重建 Document(失败返回 Err)

    Document::get

    fn Document::get(self : Document, id : String) -> Node?

    Document::has

    fn Document::has(self : Document, id : String) -> Bool

    Document::insert_node

    fn Document::insert_node(self : Document, node : Node, parent_id : String) -> Bool

    内部插入(不验证)。对外入口一律走补丁(docs/05)。

    Document::new

    fn Document::new(viewport : Size) -> Document

    Document::register

    fn Document::register(self : Document, node : Node) -> Bool

    直接注册节点到 nodes 表(不挂到任何父;克隆/批量构建用)

    Document::sample_login

    fn Document::sample_login() -> Document

    示例:登录页(栈布局 + Fill/Hug),与 docs/05 的 Agent 工作流示例一致。

    Document::to_json

    fn Document::to_json(self : Document) -> String

    文档的规范代码表示:嵌套 children 的 JSON 树。 Agent 读取这份 JSON 来理解当前设计,然后提交补丁。

    Document::update_node

    fn Document::update_node(self : Document, id : String, f : (Node) -> Node) -> Bool

    Easing

    pub(all) enum Easing {
    Linear
    EaseIn
    EaseOut
    EaseInOut
    Spring(Double)
    Bounce
    None
    }

    属性动画系统:原型需要动效——属性插值 / 缓动函数 / 时间线编排。

    Agent 定义关键帧动画("按钮按下时缩小到 0.95 再弹回"), 引擎生成 CSS animation 或直接驱动运行时插值。

    • Keyframe:某时刻某属性的值
    • Easing:缓动函数(linear / ease-in / ease-out / spring / bounce)
    • Timeline:多条动画的编排(并行 / 顺序 / 延迟)

    Easing::css_value

    fn Easing::css_value(self : Easing) -> String

    CSS cubic-bezier 等价(用于导出)

    Easing::name

    fn Easing::name(self : Easing) -> String

    ExtractedComponent

    pub(all) struct ExtractedComponent {
    inferred_name : String
    instance_count : Int
    common_fill : String
    common_radius : Double
    common_height : Double
    sample_ids : Array[String]
    }

    ExtractedDesignSystem

    pub(all) struct ExtractedDesignSystem {
    color_tokens : Array[ExtractedToken]
    spacing_tokens : Array[ExtractedSpacing]
    font_tokens : Array[ExtractedFontSize]
    components : Array[ExtractedComponent]
    total_nodes : Int
    total_colors : Int
    total_sizes : Int
    }

    ExtractedDesignSystem::summary

    fn ExtractedDesignSystem::summary(self : ExtractedDesignSystem) -> String

    人类可读摘要

    ExtractedDesignSystem::to_json

    fn ExtractedDesignSystem::to_json(self : ExtractedDesignSystem) -> String

    ExtractedFontSize

    pub(all) struct ExtractedFontSize {
    value : Double
    usage_count : Int
    suggested_name : String
    }

    ExtractedSpacing

    pub(all) struct ExtractedSpacing {
    value : Double
    usage_count : Int
    suggested_name : String
    }

    ExtractedToken

    pub(all) struct ExtractedToken {
    name : String
    value : String
    usage_count : Int
    confidence : Double
    }

    设计系统反向提取:从现有设计反推组件库和令牌。

    这是"设计考古学"——Agent 拿到一个已有原型,引擎自动:
    1. 扫描所有颜色 → 聚类 → 推断语义令牌名(primary/surface/error)
    2. 扫描所有间距 → 识别间距体系(4/8/12/16/24)
    3. 扫描所有字号 → 映射到标准字号阶(h1=32/h2=24/body=14/caption=12)
    4. 检测重复结构 → 推断为同一"组件"的不同实例
    5. 输出完整设计系统(可复用于创建新页面)

    Agent 得到的不只是一份分析报告——是一套可以直接 place_component 的 令牌表和组件定义。

    FlowEdge

    pub(all) struct FlowEdge {
    from : String
    to : String
    trigger : String
    }

    FontNote

    pub(all) struct FontNote {
    node_id : String
    size : Double
    color : String
    token_hint : String
    }

    Gate

    pub(all) enum Gate {
    HumanGate
    AgentGate
    }

    合并门槛:两条路线对同一组谓词采用不同策略(docs/04 的策略矩阵)。

    • HumanGate:结构谓词硬阻断(编辑器交互保证极少触发),视觉谓词软提示。
    • AgentGate:全部硬阻断——任何违规都整体拒绝补丁。

    GateDecision

    pub(all) enum GateDecision {
    Allow(Array[Violation])
    Reject(Array[Violation])
    }

    GenIntent

    pub(all) struct GenIntent {
    template_id : String
    artboard_name : String
    width : Double
    height : Double
    theme : String
    page_hint : String
    alternatives : Array[String]
    }

    意图解析结果(确定性:同输入恒同决策;歧义时给候选留一次精修线索)

    HistoryEntry

    pub(all) struct HistoryEntry {
    revision : Int
    timestamp : String
    agent_id : String
    message : String
    ops : Array[DesignOp]
    snapshot : Document
    }

    设计版本控制:时间旅行 / 分支 / 变更回放。

    每次对项目的修改都产生一个"commit"(快照 + 操作记录)。 Agent 可以:
    • 查看完整历史(谁在什么时候做了什么)
    • 时间旅行到任意版本(预览旧状态)
    • 从任意版本分叉新分支(探索不同方向)
    • 回放两个版本之间的变更(逐步看每步做了什么)
    • 撤销 / 重做

    InteractionDef

    pub(all) struct InteractionDef {
    node_id : String
    trigger : Trigger
    action : Action
    transition : Transition
    }

    JournalEntry

    pub(all) struct JournalEntry {
    revision : Int
    source : OpSource
    message : String
    violation_count : Int
    }

    JsonNodeStore

    type JsonNodeStore

    parse 期间注册的节点表(id → Node,children id 已带)

    Justify

    pub(all) enum Justify {
    Start
    Center
    End
    }

    主轴对齐:剩余空间(无 Fill 子项时)如何分配

    Keyframe

    pub(all) struct Keyframe {
    time : Double
    properties : Array[AnimatableProperty]
    }

    pub(all) struct LT {
    node : Node
    kids : Array[LT]
    }

    布局树:节点本体 + 子树(Document.children 只存 id,构建期用 LT 携带子树)

    LT::color

    fn LT::color(self : LT, c : String) -> LT

    LT::cx

    fn LT::cx(self : LT) -> LT

    LT::h

    fn LT::h(self : LT, spec : SizeSpec) -> LT

    LT::w

    fn LT::w(self : LT, spec : SizeSpec) -> LT

    微调:主/副轴规格、cross 居中、文字颜色(声明处链式使用)

    LayoutIntent

    pub(all) enum LayoutIntent {
    CenterNode(String)
    VerticalStack
    HorizontalRow
    EqualWidth
    EqualHeight
    EqualSpacing
    GridAlign(Double)
    MoveTop
    MoveBottom
    MoveCenter
    ScaleAll(Double)
    SetPadding(Double)
    SetGap(Double)
    Unknown
    }

    布局推理引擎:Agent 用自然语言说"居中对齐按钮",引擎推断参数并执行。

    这不是 NLP——是结构化的约束语言解析: 引擎识别设计意图关键词(居中/排列/等宽/间距/缩放), 匹配到对应的布局操作,返回可直接执行的动作。

    支持 12 种意图: 居中 / 垂直排列 / 水平排列 / 等宽 / 等高 / 等间距 / 网格对齐 / 移到顶部 / 移到底部 / 整体缩放 / 增加边距 / 自动布局

    LayoutIntent::describe

    fn LayoutIntent::describe(self : LayoutIntent) -> String

    LoadOutcome

    type LoadOutcome

    MergeResult

    pub(all) struct MergeResult {
    clean : Bool
    conflicts : Array[Conflict]
    auto_resolved : Int
    total_ops_ours : Int
    total_ops_theirs : Int
    applied_ops : Int
    }

    MergeResult::auto_resolve

    fn MergeResult::auto_resolve(self : MergeResult, strategy? : String) -> MergeResult

    冲突解决策略:自动选择

    MergeResult::to_json

    fn MergeResult::to_json(self : MergeResult) -> String

    MergeResult JSON(Agent 审阅用)

    MoonVizArtifact

    pub(all) struct MoonVizArtifact {
    meta_version : String
    meta_created_by : String
    meta_context : String
    artboard_decls : Map[String, String]
    artboard_names : Map[String, String]
    artboard_sizes : Map[String, (Double, Double)]
    flows : Array[(String, String, String)]
    todos : Array[String]
    notes : Array[AgentNote]
    }

    MoonVizArtifact::add_note

    fn MoonVizArtifact::add_note(self : MoonVizArtifact, artboard : String, note : String, priority : String) -> Unit

    MoonVizArtifact::add_todo

    fn MoonVizArtifact::add_todo(self : MoonVizArtifact, text : String) -> Unit

    MoonVizArtifact::new

    MoonVizArtifact::summary

    fn MoonVizArtifact::summary(self : MoonVizArtifact) -> String

    MoonVizRT

    pub(all) struct MoonVizRT {
    project : Project
    nav : NavigationState
    overlay_toast : String?
    input_values : Map[String, String]
    listeners : Array[(StateChange) -> Unit]
    }

    MoonVizRT::can_go_back

    fn MoonVizRT::can_go_back(self : MoonVizRT) -> Bool

    MoonVizRT::create

    fn MoonVizRT::create(project : Project, initial_artboard? : String) -> Result[MoonVizRT, String]

    创建运行时实例

    MoonVizRT::current_artboard

    fn MoonVizRT::current_artboard(self : MoonVizRT) -> String

    MoonVizRT::get_all_inputs

    fn MoonVizRT::get_all_inputs(self : MoonVizRT) -> Map[String, String]

    MoonVizRT::get_input

    fn MoonVizRT::get_input(self : MoonVizRT, node_id : String) -> String

    MoonVizRT::handle_event

    fn MoonVizRT::handle_event(self : MoonVizRT, event : VizEvent) -> Array[StateChange]

    处理一个交互事件,返回状态变更列表

    MoonVizRT::hot_reload_doc

    fn MoonVizRT::hot_reload_doc(self : MoonVizRT, doc : Document) -> Result[String, String]

    热重载:用新的文档替换当前画板内容,保留导航栈与仍存在的输入值。

    声明文本解析属于 decl 包,core 不依赖 decl——故本原语接收已解析好的 Document。 旧版接收字符串却仅校验非空就返回 hot_reloaded:true,是结构性假成功(core 永远 无法真正解析声明文本),已移除,避免调用方误信变更已生效。

    MoonVizRT::nav_stack

    fn MoonVizRT::nav_stack(self : MoonVizRT) -> Array[String]

    MoonVizRT::on_change

    fn MoonVizRT::on_change(self : MoonVizRT, listener : (StateChange) -> Unit) -> Unit

    MoonVizRT::render_plan

    fn MoonVizRT::render_plan(self : MoonVizRT) -> Result[RenderPlan, String]

    当前状态 → 后端无关的渲染指令列表

    MoonVizRT::set_input

    fn MoonVizRT::set_input(self : MoonVizRT, node_id : String, value : String) -> Unit

    pub(all) struct NavigationState {
    stack : Array[String]
    current : String
    }

    fn NavigationState::go_back(self : NavigationState) -> String?

    fn NavigationState::navigate(self : NavigationState, target : String) -> String

    fn NavigationState::new(initial : String) -> NavigationState

    Node

    pub(all) struct Node {
    id : String
    kind : NodeKind
    name : String
    component : String
    width : SizeSpec
    height : SizeSpec
    x : PosSpec
    y : PosSpec
    layout : StackLayout?
    style : NodeStyle
    text : String
    children : Array[String]
    constraint : String
    }

    Node::make

    fn Node::make(id : String, kind : NodeKind) -> Node

    带默认值的节点工厂,配合结构更新语法使用:{ ..Node::make(id, kind), ... }

    NodeKind

    pub(all) enum NodeKind {
    Frame
    Group
    Rect
    Text
    Image
    }

    节点种类

    NodePatch

    pub(all) struct NodePatch {
    name : String?
    width : SizeSpec?
    height : SizeSpec?
    x : PosSpec?
    y : PosSpec?
    text : String?
    layout_dir : StackDir?
    layout_gap : Double?
    layout_justify : Justify?
    layout_padding : Padding?
    fill : String?
    stroke : String?
    corner_radius : Double?
    font_size : Double?
    text_color : String?
    }

    节点字段补丁:None = 不修改

    NodePatch::empty

    fn NodePatch::empty() -> NodePatch

    NodeStyle

    pub(all) struct NodeStyle {
    fill : String
    stroke : String
    stroke_width : Double
    corner_radius : Double
    opacity : Double
    font_size : Double
    text_color : String
    font_weight : String
    shadow : String
    rotate : Double
    blur : Double
    blend : String
    line_height : Double
    tracking : Double
    flip : String
    text_align : String
    font_style : String
    stroke_dash : String
    visible : Bool
    }

    视觉样式(v4:+ 文本对齐 / 斜体 / 描边虚线 / 可见性)

    NodeStyle::default

    fn NodeStyle::default() -> NodeStyle

    NormListRun

    pub(all) struct NormListRun {
    parent_id : String
    row_ids : Array[String]
    }

    齐缝列表行连排:同一父节点下 ≥3 个 list_item,宽度一致(±2)、高度一致 (±4)、纵向齐缝或近齐缝(行距 -1~6)——「裸列表」形态,是分割线规范的 检测对象。检测与修复(norm_list_divider_fix)共用本结构。

    NormsProfile

    pub(all) struct NormsProfile {
    radius_base : Double
    contrast_min : Double
    touch_min : Double
    }

    issue #24:norms 阈值画像——一次解析 design_spec 得到三档,供 critique/auto_fix/norms 各检测与修复通道共享(消除链上重复解析)。
    pub(all) enum Op {
    InsertNode(Node, String)
    UpdateNode(String, NodePatch)
    MoveNode(String, String)
    DeleteNode(String)
    }

    OpEntry

    pub(all) struct OpEntry {
    op : String
    usage : String
    category : String
    description : String
    }

    单条 mutating op:名称 / 用法(与 ops.mbt 分发器的 mbt_operation_usage: 逐字一致)/ 分类 / 说明。

    OpSource

    pub(all) enum OpSource {
    HumanOp
    AgentOp
    }

    操作来源:两条路线在 journal 里的身份

    OpSource::name

    fn OpSource::name(self : OpSource) -> String

    Padding

    pub(all) struct Padding {
    top : Double
    right : Double
    bottom : Double
    left : Double
    }

    Padding::uniform

    fn Padding::uniform(v : Double) -> Padding

    PageType

    pub(all) enum PageType {
    AuthPage
    DashboardPage
    ListPage
    DetailPage
    ProfilePage
    SettingsPage
    FormPage
    NavigationPage
    EmptyStatePage
    UnknownPage
    }

    设计智能:引擎不仅执行设计——它理解设计。

    • infer_page_type:从节点结构推断页面类型(login/dashboard/list...)
    • infer_missing_elements:基于页面类型推断缺失的常见元素
    • suggest_improvements:基于设计原则给出改进建议
    • design_quality_score:综合评分(层次/一致性/密度/可访问性)

    这是"AI-native"的核心差异化:引擎有设计常识,能主动告诉 Agent "你做的这个页面缺了什么"和"怎么做会更好"。

    PageType::name

    fn PageType::name(self : PageType) -> String

    ParseResult

    type ParseResult

    Patch

    pub(all) struct Patch {
    base_revision : Int
    message : String
    ops : Array[Op]
    }

    PatchError

    pub(all) enum PatchError {
    StaleBase(Int)
    UnknownNode(String)
    UnknownParent(String)
    DuplicateId(String)
    HierarchyError(String)
    StructuralBlock(Array[Violation])
    HardBlock(Array[Violation])
    }

    PatchError::to_json

    fn PatchError::to_json(self : PatchError) -> String

    PlaceArgs

    pub(all) struct PlaceArgs {
    variant : String
    x : Double
    y : Double
    w : Double
    h : Double
    args : Map[String, String]
    error : String
    }

    place 参数解析结果(variant/x/y/w/h 槽 + 尾部 k=v 用户参数槽)。

    PosSpec

    pub(all) enum PosSpec {
    Fixed(Double)
    AlignStart(Double)
    AlignEnd(Double)
    CenterInParent
    }

    位置规格(相对父容器内容盒;栈布局中主轴分量被忽略,由布局游标决定)

    Predicate

    pub(all) enum Predicate {
    TreeValid
    SizeValid
    ContainedInParent
    NoSiblingOverlap
    ConstraintSolvable
    }

    “不崩”谓词(docs/04):对 (文档, 求解结果) 的纯函数检查。

    分级原则:结构硬,视觉软/硬。
    • 结构性谓词(TreeValid / SizeValid):文档坏到无法继续,两条路线都硬阻断。
    • 视觉性谓词(ContainedInParent / NoSiblingOverlap / ConstraintSolvable): 人类路线软提示(保留决定权),Agent 路线硬门槛(拒绝合并)。 策略落地在 policy.mbt 的 decide()。

    Predicate::is_structural

    fn Predicate::is_structural(self : Predicate) -> Bool

    Predicate::name

    fn Predicate::name(self : Predicate) -> String

    Project

    pub(all) struct Project {
    artboards : Map[String, ArtboardMeta]
    flows : Array[FlowEdge]
    tokens : DesignTokens
    components : Map[String, ComponentDef]
    user_components : Map[String, UserComponentDef]
    node_states : Map[String, ComponentStateDef]
    revision : Int
    token_overrides : Map[String, String]?
    active_theme : String
    doc_comments : Array[DocComment]
    extra_front_matter : Array[String]
    design_spec : String
    }

    Project::active_state_patch

    fn Project::active_state_patch(self : Project, node_id : String) -> NodePatch?

    当前状态下节点应有的补丁(default 缺省则返回空补丁)。

    Project::add_agent_note

    fn Project::add_agent_note(self : Project, artboard~ : String, note~ : String, priority? : String) -> Unit

    Project 侧也支持添加 Agent 备注

    Project::add_flow

    fn Project::add_flow(self : Project, from~ : String, to~ : String, trigger? : String) -> Unit

    Project::add_interaction

    fn Project::add_interaction(self : Project, artboard~ : String, node_id~ : String, trigger~ : Trigger, action~ : Action, transition? : Transition) -> Result[String, String]

    为节点添加交互定义

    Project::align_nodes

    fn Project::align_nodes(self : Project, artboard~ : String, mode~ : String, node_ids~ : Array[String]) -> Result[String, String]

    多节点对齐:left|right|top|bottom|hcenter|vcenter(相对节点集合包围盒)

    Project::apply_constraint

    fn Project::apply_constraint(self : Project, text : String, artboard~ : String, parent_id? : String) -> Result[String, String]

    一步到位:解析文本 → 执行意图

    Project::apply_design_spec

    fn Project::apply_design_spec(self : Project, artboard~ : String, spec~ : String) -> Result[Unit, String]

    spec 应用(issue #24):调色板 → token 覆盖 + 重着色;字号阶/圆角档按 spec 规范化。spec 空白 → design_spec_required(不静默兜底)。

    Project::apply_intent

    fn Project::apply_intent(self : Project, intent : LayoutIntent, artboard~ : String, parent_id? : String) -> Result[String, String]

    执行解析后的布局意图

    Project::apply_template

    fn Project::apply_template(self : Project, template_id~ : String, name? : String, width? : Double, height? : Double) -> Result[String, String]

    实例化模板 → 完整画板。 width/height > 0 时覆盖模板默认尺寸(结构式模板按宽度选择结构分支)

    Project::apply_theme

    fn Project::apply_theme(self : Project, theme_name : String) -> Result[String, String]

    应用主题到项目(更新令牌表并重新解析所有节点颜色)

    Project::attach_interaction

    fn Project::attach_interaction(self : Project, artboard~ : String, node_id~ : String, trigger~ : String, action_spec~ : String) -> Result[String, String]

    追加交互标记到节点名(幂等:同名标记不重复追加)。

    Project::audit_design_system

    fn Project::audit_design_system(self : Project) -> String

    审计整个项目:找出所有偏离设计系统的硬编码值

    Project::auto_arrange

    fn Project::auto_arrange(self : Project, artboard~ : String, parent_id? : String) -> Result[String, String]

    所有子元素垂直等间距排列(容器内)

    Project::auto_fix

    fn Project::auto_fix(self : Project, artboard~ : String) -> Result[String, String]

    一键修复:遍历所有违规节点,逐一应用修复策略

    Project::autofill_missing

    fn Project::autofill_missing(self : Project, artboard~ : String) -> Result[String, String]

    一键补缺:infer_missing → 逐元素物化 → auto_fix 清偿重叠/溢出 → 报告(placed/skipped/补后缺失数)。报告驱动、可重入:报告里的每个 可物化元素都落地后,后续 infer_missing 对该画板归零。

    Project::benchmark

    fn Project::benchmark(self : Project) -> ProjectBenchmark

    Project::benchmark_artboard

    fn Project::benchmark_artboard(self : Project, artboard~ : String) -> Result[ArtboardBenchmark, String]

    Project::build_artboard

    fn Project::build_artboard(self : Project, name~ : String, width~ : Double, height~ : Double, tree~ : LT) -> String

    把布局树构建为画板:递归插入,几何交给求解器

    Project::center_in_parent

    fn Project::center_in_parent(self : Project, artboard~ : String, node_id~ : String) -> Result[String, String]

    将节点在父容器内水平居中

    Project::clone

    fn Project::clone(self : Project) -> Project

    深拷贝当前项目状态(会话路径的失败回滚用:克隆上应用 op,通过门检 查才 replace_with 回会话,apply 失败不污染会话)。

    Project::component_lineage

    fn Project::component_lineage(self : Project, component_id~ : String) -> Result[String, String]

    查找指定组件类型的所有实例

    Project::copy_node

    fn Project::copy_node(self : Project, artboard~ : String, node_id~ : String, new_id~ : String, dx~ : Double, dy~ : Double) -> Result[String, String]

    复制节点:子树克隆 + 偏移

    Project::create_artboard

    fn Project::create_artboard(self : Project, name~ : String, width? : Double, height? : Double) -> String

    Project::critique

    fn Project::critique(self : Project, artboard~ : String) -> Result[String, String]

    综合评审:对画板进行 8 项设计原则评审

    Project::critique_summary

    fn Project::critique_summary(self : Project, artboard~ : String) -> Result[String, String]

    评审摘要(一行)

    Project::define_component_state

    fn Project::define_component_state(self : Project, artboard~ : String, node_id~ : String, state_name~ : String, patch~ : NodePatch) -> Result[String, String]

    为组件定义多态状态(真实存储补丁,而非仅写标记)。

    状态作用于渲染/命中前的节点变换:default 为该节点的基准补丁, pressed/disabled 等为相对基准的覆盖。此前该函数接收 patch 却完全丢弃, 只留一个无人读取的名字标记——签名承诺的能力实际不存在。

    Project::delete_artboard

    fn Project::delete_artboard(self : Project, id~ : String) -> Result[String, String]

    删除画板:至少保留一个画板;同时清理引用该画板的交互流。 节点随画板 doc 整体移除,无需逐个 delete。

    Project::delete_node

    fn Project::delete_node(self : Project, artboard~ : String, node_id~ : String) -> Result[String, String]

    人类删除:摘除整个子树

    Project::design_quality_score

    fn Project::design_quality_score(self : Project, artboard~ : String) -> Result[String, String]

    Project::design_spec_component_violations

    fn Project::design_spec_component_violations(self : Project, artboard~ : String) -> Array[String]

    spec 组件白名单/禁用项校验(issue #24 要求 2:规范是生成的第一权威)。 结构组件(root/frame)不参与判定。

    Project::design_spec_radius_base

    fn Project::design_spec_radius_base(self : Project) -> Double

    按钮族圆角基准(norms 用):spec.radius.sm 在场取 spec,否则内置 8。

    Project::design_spec_text_contrast

    fn Project::design_spec_text_contrast(self : Project) -> Double

    rules[] 中的可读性对比度阈值(issue #24 要求 2:norms 以 spec 为准)。

    Project::design_spec_touch_min

    fn Project::design_spec_touch_min(self : Project) -> Double

    rules[] 中的触控目标下限(默认 44)。

    Project::detach_interaction

    fn Project::detach_interaction(self : Project, artboard~ : String, node_id~ : String) -> Result[String, String]

    移除节点名的全部交互标记(保留原始名)。

    Project::duplicate_artboard

    fn Project::duplicate_artboard(self : Project, src~ : String, new_name~ : String) -> Result[String, String]

    画板复制(Studio 的 ⌘D):深拷贝文档并重命名

    Project::edit_node

    fn Project::edit_node(self : Project, artboard~ : String, node_id~ : String, kvs~ : Array[(String, String)]) -> Result[String, String]

    人类编辑:key=value 批量更新节点属性。 支持键:w h text fill text_color stroke radius opacity font_size weight

    Project::enable_auto_dark

    fn Project::enable_auto_dark(self : Project) -> Result[String, String]

    自动生成当前主题的暗色版本并应用。

    从 active_theme 对应主题推导(而非恒从 light),并与 apply_theme/set_token 对齐状态三元组:tokens / active_theme / token_overrides——派生主题的全部 角色值记入 token_overrides,随 canonical MBT frontmatter tokens: 段往返, 节点字面量经 recolor_with 重着色,保持状态与 canonical 一致。

    Project::export_artifact

    fn Project::export_artifact(self : Project, agent_id? : String, context? : String) -> String

    Project::export_design_system

    fn Project::export_design_system(self : Project, artboard~ : String) -> Result[String, String]

    设计系统导出:把反向提取结果打包为可直接消费的形态——tokens JSON (机器)+ CSS Custom Properties(前端直用)。与 extract_design_system 同源同判据,这是导出形态,不是新的提取口径。

    Project::export_html

    fn Project::export_html(self : Project) -> String

    导出为自包含 HTML(SVG 内嵌 + 画板切换 + 导航流模拟)

    Project::export_react

    fn Project::export_react(self : Project) -> String

    导出为 React TSX 组件桩(每个画板一个组件,内联样式)

    Project::export_svg

    fn Project::export_svg(self : Project, artboard~ : String) -> Result[String, String]

    Project::extract_design_system

    fn Project::extract_design_system(self : Project, artboard~ : String) -> Result[ExtractedDesignSystem, String]

    Project::fill_slot

    fn Project::fill_slot(self : Project, artboard~ : String, instance_id~ : String, slot_name~ : String, content~ : String) -> Result[String, String]

    填充槽位内容

    Project::fill_slot_with_component

    fn Project::fill_slot_with_component(self : Project, artboard~ : String, instance_id~ : String, slot_name~ : String, child_component~ : String, child_id~ : String) -> Result[String, String]

    向槽位中放入另一个组件(递归组合)

    Project::flip_node

    fn Project::flip_node(self : Project, artboard~ : String, node_id~ : String, axis~ : String) -> Result[String, String]

    翻转:flip h|v|both|none

    Project::flow_json

    fn Project::flow_json(self : Project) -> String

    Project::fork_variants

    fn Project::fork_variants(self : Project, base~ : String, names~ : Array[String]) -> Result[String, String]

    从基础画板 fork 出多个变体

    Project::from_project_json

    fn Project::from_project_json(self : Project, text : String) -> Result[Unit, String]

    从项目 JSON 重建 Project(替换当前内容;load 用)

    事务模式(对齐 replace_with):先全部解析进暂存表,全部成功才原子替换 现有画板——单板失败不再被静默吞掉,也不会出现「项目已被清空才报错」 的失败半态;任何 LoadErr 都汇总进 Err,现状保持不变。

    Project::generate

    fn Project::generate(self : Project, intent_text~ : String, name? : String, spec? : String) -> Result[String, String]

    生成式入口:意图一句话 → 完整画板 + 报告信封。 管线:模板实例化 → auto_fix(规范/谓词自愈,生成物即合规)→ infer_missing(还差什么)→ design_quality_score(质量分)。 name 缺省 = template_id;theme 非 "" 时对整个项目应用主题(生成前, 重着色项目内所有画板)。画板名经 sanitize_id 归一后与既有画板同名 时会静默覆盖旧 Document(连同其上的 tier-2 精修)——信封以 replaced:true 提示;width/height 暴露画板实际尺寸(模板可能不消费 意图宽度,见 apply_template)。

    Project::generate_multi

    fn Project::generate_multi(self : Project, segments : Array[String], name? : String, spec? : String) -> Result[String, String]

    组合意图生成:逐段分类 → 逐板实例化(纯主题段只换主题不生成板, 同模板重名加序号)→ 相邻板自动连线(出口启发)→ 流去重 → 逐板自愈/ 评分。信封 mode=multi,逐板带 replaced(覆盖探测,与单通道同构)、 autofix(ok/fixes[/remaining] 摘要)、missing_count/score。

    Project::generate_responsive

    fn Project::generate_responsive(self : Project, artboard~ : String) -> Result[String, String]

    为画板生成响应式变体(_tablet / _desktop)

    Project::generate_spec

    fn Project::generate_spec(self : Project, artboard~ : String) -> Result[String, String]

    生成画板的完整设计规范(Markdown 格式)

    Project::get_slot

    fn Project::get_slot(self : Project, artboard~ : String, instance_id~ : String, slot_name~ : String) -> Result[String, String]

    获取槽位当前内容

    Project::get_token

    fn Project::get_token(self : Project, token_name : String) -> Result[String, String]

    获取令牌当前值

    Project::group_nodes

    fn Project::group_nodes(self : Project, artboard~ : String, node_ids~ : Array[String], group_id~ : String) -> Result[String, String]

    打组:同父绝对容器下的多个节点 → Group

    Project::impact_analysis

    fn Project::impact_analysis(self : Project, artboard~ : String, node_id~ : String, patch~ : NodePatch) -> Result[String, String]

    预览:如果对某个节点应用补丁,会产生什么影响

    Project::infer_missing

    fn Project::infer_missing(self : Project, artboard~ : String) -> Result[String, String]

    基于页面类型推断常见缺失元素 Agent 得到"你的登录页还差一个忘记密码链接"这种建议

    Project::infer_page_type

    fn Project::infer_page_type(self : Project, artboard~ : String) -> Result[String, String]

    从画板节点结构推断页面类型 信号:输入框数量 + 按钮文字 + 卡片密度 + 布局模式

    Project::interactions_json

    fn Project::interactions_json(self : Project, artboard~ : String) -> Result[String, String]

    结构化交互清单:解析标记 → trigger/action 字段(供 Agent 审阅与回读)。

    Project::lint

    fn Project::lint(self : Project, artboard~ : String) -> Result[String, String]

    设计质量检查:对比度/触控目标/间距/一致性

    Project::list_artboards_json

    fn Project::list_artboards_json(self : Project) -> String

    Project::list_breakpoint_variants

    fn Project::list_breakpoint_variants(self : Project, artboard~ : String) -> String

    列出某画板的所有响应式变体

    Project::list_interactions

    fn Project::list_interactions(self : Project, artboard~ : String) -> Result[String, String]

    列出画板的所有交互定义(从节点名解析)

    Project::list_slots

    fn Project::list_slots(self : Project, artboard~ : String, instance_id~ : String) -> Result[String, String]

    列出实例的所有槽位及其内容

    Project::merge_variant

    fn Project::merge_variant(self : Project, source~ : String, target~ : String) -> Result[String, String]

    合并变体:把源画板的内容替换到目标画板

    Project::mock_data_gaps

    fn Project::mock_data_gaps(self : Project, artboard~ : String) -> Array[String]

    issue #25-B4(规则化):mock 数据缺口——只报告「哪个容器缺样例 / 哪段文本是 占位符」,不做任何内容内置。真实样例内容由 Agent(LLM)按语义自行填写; 引擎只保证规则可测(空壳 = 无子节点无文本;占位词表见 qa_is_placeholder_text)。

    Project::move_node

    fn Project::move_node(self : Project, artboard~ : String, node_id~ : String, x~ : Double, y~ : Double) -> Result[String, String]

    人类拖拽:把节点放到画布绝对坐标 (x, y)。 父容器无栈布局 → 就地改相对坐标;父容器有栈布局 → reparent 到自由层。

    Project::new

    fn Project::new() -> Project

    Project::node_states_json

    fn Project::node_states_json(self : Project, artboard~ : String) -> Result[String, String]

    结构化回读:节点的全部已定义状态与其当前值。

    Project::norm_back_issues

    fn Project::norm_back_issues(self : Project, artboard~ : String) -> Array[String]

    返回交互校验(返回交互是必须的,用户决策 2026-10-11): 非入口画板必须有离开路径——出边 flow,或返回类节点(runtime 对返回类 节点的 tap 有内置返回兜底)。两者皆无 = 用户会卡死在该页。 豁免条件与实现一致:有出边 flow 的画板、单画板项目。引擎不记录入口 画板(runtime initial_artboard 是会话参数,不入 Project)——未连线的 首页同样按本规则判,需给出边或返回类节点,不做入口特判。

    Project::norm_selected_state_issues

    fn Project::norm_selected_state_issues(self : Project, artboard~ : String) -> Array[String]

    issue #23 检测项(Project 级):组件状态可辨识。 选中态(selected/checked/active)补丁必须改变至少一个视觉字段, 否则「选中」在演示时不可辨识;选中色同样受纯黑禁令约束。

    Project::normalize_nesting

    fn Project::normalize_nesting(self : Project, artboard_id : String) -> Unit

    模板结构规范化:把「被兄弟完全包含」的节点收编为该兄弟的子节点。

    设计意图:宽屏模板用平铺节点表达视觉嵌套(标题栏上的交通灯、侧栏里的 文件项、卡片上的文字)。收编让树结构表达真实包含(#13 parent 读面、 ContainedInParent 检查都依赖它),坐标转为父相对、视觉不变。 注:NoSiblingOverlap 自 5a5641a 起豁免「兄弟全包含」对,纯为过门而 收编的必要性下降——但收编仍承载树语义与查询面,不可移除; 模板债回归锚见 wasm/contract_test「14 模板 × AgentGate」。

    选择「最小的完全包含者」作为新父(最紧拟和);仅收编 rect 严格被包含 且包含者非纯装饰尺寸过小者(宽高 ≥ 包含节点)的节点。单趟扫描即可, 模板层级至多两层嵌套。

    Project::norms_profile

    fn Project::norms_profile(self : Project) -> NormsProfile

    Project::place_component

    fn Project::place_component(self : Project, artboard~ : String, component_id~ : String, instance_id~ : String, variant? : String, parent_id? : String, x? : Double, y? : Double, w? : Double, h? : Double, args? : Map[String, String]) -> Result[String, String]

    Project::place_slotted

    fn Project::place_slotted(self : Project, artboard~ : String, component_id~ : String, instance_id~ : String, x? : Double, y? : Double) -> Result[String, String]

    放置组合式组件(自动创建槽位子节点)

    Project::preview_breakpoint

    fn Project::preview_breakpoint(self : Project, artboard~ : String, breakpoint~ : String) -> Result[String, String]

    预览指定断点

    Project::preview_themes

    fn Project::preview_themes(self : Project, node_id : String) -> Result[String, String]

    预览节点在各主题下的颜色:按默认调色板把节点 fill 反查为角色,再逐 主题取该角色的值(找不到节点或角色时回退 primary)——与 README 「preview the node under each theme」的承诺一致,而非无视 node_id 的 全局 primary 表。

    Project::qa_agent_conflicts

    fn Project::qa_agent_conflicts(self : Project) -> Result[Unit, String]

    AgentGate 冲突判定(issue #25-A3 / #26-A3):
    1. 同一节点多条 tap flow → interaction_conflict
    2. 两个可点热区(被 tap flow 绑定的容器)包围盒相交且无父子包含 → hotzone_overlap 任一命中即 Err("mbt_gate_block:<板>:<类>:<定位>"),由门路径拒绝。

    Project::qa_component_known

    fn Project::qa_component_known(self : Project, c : String) -> Bool

    组件必须来自组件库(builtin 或用户组件注册表)。

    Project::qa_is_bound

    fn Project::qa_is_bound(self : Project, artboard : String, n : Node) -> Bool

    交互去向判定(issue #25-A1):flow tap: / 名字里的交互标记(⚡ 或 [state:)/ 返回类节点(内置返回兜底)都算有去向。

    Project::qa_issues

    fn Project::qa_issues(self : Project, artboard~ : String) -> Array[String]

    critique 第 9 维追加项(issue #25/#26 软路径检测):
    1. 可交互组件无去向(无 flow/标记/返回兜底)
    2. 占位符残留文本
    3. 空壳 list/table/card(无示例条目)
    4. 非组件库组件(generic_node 当组件用)

    Project::query_nodes

    fn Project::query_nodes(self : Project, artboard~ : String, kind? : String, component? : String, text_contains? : String) -> Result[String, String]

    按条件查询画板中的节点

    Project::rebuild_node_states

    fn Project::rebuild_node_states(self : Project, artboard~ : String) -> Unit

    扫描节点名标记,重建 Project 的状态表(load 后调用)。 状态定义随名字往返,但内存表需在重建 Project 后重新填充。

    Project::remove_flow

    fn Project::remove_flow(self : Project, from~ : String, to~ : String, trigger~ : String) -> Result[Unit, String]

    删除单条导航边(issue #12):画错一条边不再需要整板删除重建。 trigger 写法与 add_flow 的调用约定对齐("tap:")。

    Project::reorder_node

    fn Project::reorder_node(self : Project, artboard~ : String, node_id~ : String, order~ : String) -> Result[String, String]

    Z 序:reorder front|back|up|down

    Project::replace_with

    fn Project::replace_with(self : Project, source : Project) -> Unit

    用从唯一 MBT 源码重建的项目快照原子替换临时计算缓存。

    Studio/CLI 不会持久化这个 Project;每次载入都应来自 .mbt.md,它只是 当前命令批次内的可变计算模型。

    Project::resize_canvas

    fn Project::resize_canvas(self : Project, artboard~ : String, width~ : Double, height~ : Double) -> Result[String, String]

    画板尺寸变更:按约束重排所有节点的 PosSpec / SizeSpec。 逐节点处理(父先于子不敏感——PosSpec 均相对父内容盒,dW/dH 逐层传递比例)。

    Project::restyle_component

    fn Project::restyle_component(self : Project, artboard~ : String, component_id~ : String, kvs~ : Array[(String, String)]) -> Result[String, String]

    主组件样式传播(Figma Component Override 的批量简化语义): restyle <component_id> k=v ... → 该画板所有 component 匹配的节点统一重样式。 引擎职责仍是确定性批量命令,不含任何 NL。

    Project::score_variants

    fn Project::score_variants(self : Project) -> String

    对所有画板评分( violations 越少越好)

    Project::set_artboard_doc

    fn Project::set_artboard_doc(self : Project, artboard~ : String, doc : Document) -> Result[Unit, String]

    把 Document 写回指定画板(history 时间旅行的落地原语)。 边界层(CLI/MCP)持有 DesignHistory,checkout/undo/redo 的结果经此 落回 Project——「源码是唯一事实源」不变:写回后仍走 canonical 序列化。

    Project::set_node_state

    fn Project::set_node_state(self : Project, node_id~ : String, state_name~ : String, toggle? : Bool) -> Result[String, String]

    切换/设置节点当前状态并返回变更后的节点。 ToggleState:在 default 与目标状态间切换;SetState:直接设为目标状态。

    Project::set_theme_tokens

    fn Project::set_theme_tokens(self : Project, theme_name : String) -> Unit

    加载路径恢复主题:只切换 tokens 与 active_theme,不做角色重着色—— canonical MBT 里的节点颜色已是主题字面量,重着色属于 apply_theme 的 职责,重复执行会把已是目标色的节点原样重写(幂等但徒增 revision)。

    Project::set_token

    fn Project::set_token(self : Project, token_name : String, value : String) -> Result[String, String]

    修改单个令牌值(全局生效)。

    "全局生效"必须包含两件事,只改内存 tokens 表对已落盘的字面量无效:
    1. 记录自定义覆盖(token_overrides),随 canonical MBT frontmatter tokens: 段往返——否则下一条命令从文本重建时覆盖即丢失;
    2. 立即重着色:旧值字面量 → 角色 → 新值,与 apply_theme 同一反查 表,因此同样可逆(换回原值即恢复)。

    Project::snap_to_grid

    fn Project::snap_to_grid(self : Project, artboard~ : String, grid? : Double) -> Result[String, String]

    所有节点位置吸附到 N px 网格

    Project::spec_json

    fn Project::spec_json(self : Project, artboard~ : String) -> Result[String, String]

    标注摘要(JSON,机器可读)

    Project::suggest_alignment

    fn Project::suggest_alignment(self : Project, artboard~ : String) -> Result[String, String]

    检测近似对齐并给出建议

    Project::suggest_fix

    fn Project::suggest_fix(self : Project, artboard~ : String, node_id~ : String) -> Result[String, String]

    针对不崩谓词违规给出可执行的修复补丁

    Project::suggest_improvements

    fn Project::suggest_improvements(self : Project, artboard~ : String) -> Result[String, String]

    基于设计原则给出改进建议

    Project::suggest_optimizations

    fn Project::suggest_optimizations(self : Project, artboard~ : String) -> Result[String, String]

    优化建议

    Project::to_project_json

    fn Project::to_project_json(self : Project) -> String

    整个项目序列化为 JSON(save 用)

    Project::token_lineage

    fn Project::token_lineage(self : Project, token_name~ : String) -> Result[String, String]

    查找使用指定颜色令牌的所有节点

    Project::ungroup_node

    fn Project::ungroup_node(self : Project, artboard~ : String, group_id~ : String) -> Result[String, String]

    解组:组员坐标还原回父坐标系

    ProjectBenchmark

    pub(all) struct ProjectBenchmark {
    artboards : Array[ArtboardBenchmark]
    total_nodes : Int
    total_memory : Int
    avg_score : Double
    grade : String
    }

    ProjectBenchmark::report

    fn ProjectBenchmark::report(self : ProjectBenchmark) -> String

    人类可读报告

    ProjectBenchmark::to_json

    fn ProjectBenchmark::to_json(self : ProjectBenchmark) -> String

    ProtoTest

    pub(all) struct ProtoTest {
    rt : MoonVizRT
    passed : Int
    failed : Int
    failures : Array[String]
    }

    原型测试:断言式验证交互流程。

    Agent(或 CI 管道)可以写"原型测试用例":
    test_rt.tap(160, 422).expect_navigate("home")
    test_rt.back().expect_artboard("login")
    test_rt.set_input("email", "test@x.com").expect_value("email", "test@x.com")
    这让原型变成可测试的,而不仅仅是"看起来对的"。

    ProtoTest::back_and_expect

    fn ProtoTest::back_and_expect(self : ProtoTest, expected : String) -> Bool

    模拟返回 → 期望回到指定画板

    ProtoTest::create

    fn ProtoTest::create(project : Project, initial? : String) -> Result[ProtoTest, String]

    创建原型测试运行器

    ProtoTest::expect_no_violations

    fn ProtoTest::expect_no_violations(self : ProtoTest) -> Bool

    期望当前画板无违规

    ProtoTest::expect_renderable

    fn ProtoTest::expect_renderable(self : ProtoTest) -> Bool

    期望渲染计划非空

    ProtoTest::is_pass

    fn ProtoTest::is_pass(self : ProtoTest) -> Bool

    ProtoTest::reject_invalid

    fn ProtoTest::reject_invalid(self : ProtoTest, detail : String) -> Bool

    记录一条语法/解析失败(不计 passed)。

    ProtoTest::result

    fn ProtoTest::result(self : ProtoTest) -> String

    ProtoTest::set_input_and_expect

    fn ProtoTest::set_input_and_expect(self : ProtoTest, node_id : String, value : String) -> Bool

    设置输入 → 期望值正确存储

    ProtoTest::swipe_and_expect

    fn ProtoTest::swipe_and_expect(self : ProtoTest, direction : String, expected : String) -> Bool

    模拟滑动导航

    ProtoTest::tap_and_expect_navigate

    fn ProtoTest::tap_and_expect_navigate(self : ProtoTest, x : Double, y : Double, expected : String) -> Bool

    模拟点击 → 期望导航到指定画板

    Rect

    pub(all) struct Rect {
    x : Double
    y : Double
    width : Double
    height : Double
    }

    Rect::bottom

    fn Rect::bottom(self : Rect) -> Double

    Rect::contains_rect

    fn Rect::contains_rect(self : Rect, other : Rect) -> Bool

    self 是否完整包含 other(“无溢出”谓词的几何核心)

    Rect::contains_rect_eps

    fn Rect::contains_rect_eps(self : Rect, other : Rect, eps : Double) -> Bool

    self 是否包含 other(带像素级容差):浮点求解的 Fill 子节点与父内容盒 理论上严丝合缝,但 IEEE754 尘埃会算出 2e-13 之类的假溢出(issue #14 adaptive_landing feat_bN 一类)。≤0.5px 的越界在渲染上不可见,视为包含。

    Rect::inset

    fn Rect::inset(self : Rect, t : Double, r : Double, b : Double, l : Double) -> Rect

    各边内缩(top, right, bottom, left)

    Rect::intersects

    fn Rect::intersects(self : Rect, other : Rect) -> Bool

    两矩形是否相交(“无重叠”谓词的几何核心;仅贴边不算相交)

    Rect::new

    fn Rect::new(x : Double, y : Double, width : Double, height : Double) -> Rect

    Rect::right

    fn Rect::right(self : Rect) -> Double

    RenderCommand

    pub(all) enum RenderCommand {
    CmdRect(Double, Double, Double, Double, String, Double)
    CmdText(Double, Double, String, Double, String)
    CmdLine(Double, Double, Double, Double, String)
    CmdClipPush(Double, Double, Double, Double)
    CmdClipPop
    }

    RenderPlan

    pub(all) struct RenderPlan {
    artboard : String
    width : Double
    height : Double
    commands : Array[RenderCommand]
    }

    ScalarOrSpec

    type ScalarOrSpec

    通用值:数值 / spec 对象,返回带类型的中间结构

    Size

    pub(all) struct Size {
    width : Double
    height : Double
    }

    SizeSpec

    pub(all) enum SizeSpec {
    Fixed(Double)
    Fill
    Hug
    }

    尺寸规格:Fixed 定值 / Fill 占满可用空间 / Hug 包裹内容

    SlotDef

    pub(all) struct SlotDef {
    name : String
    description : String
    accepts : Array[String]
    default_content : String
    }

    组件插槽系统:支持嵌套内容分发的组合式组件。

    定位:SDK-only 能力(README「组件插槽系统」,宿主经 MoonBit SDK 直调)—— 不进 agent_api 工具字典,CLI/MCP/WASM 三面不暴露;Agent 侧的组合 表达走 place_component + parent_id。

    这是让组件真正可组合的原语——像 React/Vue 的 children/slots:
    <Card> <CardHeader>Title</CardHeader> <CardContent>Body</CardContent> </Card>
    MoonViz 等价:
    p.place_component("card", "my_card")
    p.fill_slot("my_card", "header", "Title")
    p.fill_slot("my_card", "content", "Body text here")

    • 槽位定义:组件声明命名槽位
    • 槽位填充:Agent 把内容放进指定槽位
    • 默认内容:槽位为空时使用默认值
    • 组合组件:槽位里可以放其他组件(递归组合;SlotDef.accepts 非空时强校验)

    SlottedComponent

    pub(all) struct SlottedComponent {
    component_id : String
    display_name : String
    slots : Array[SlotDef]
    layout : StackLayout
    base_style : NodeStyle
    }

    SolveFailure

    pub(all) enum SolveFailure {
    MissingRoot
    MissingNode(String)
    NegativeResidual(String, Double)
    UnsupportedSpec(String)
    }

    布局求解:两遍法(先解尺寸、后解位置),见 docs/03。

    失败 ≠ 崩溃:求解器永远产出有限的矩形;解不开的约束记入 failures, 由谓词层(predicates.mbt)定级为“约束系统无解”。这个接口稳定, 未来可把实现换成 Cassowary / SMT 求解器而不影响验证协议。

    SolveFailure::describe

    fn SolveFailure::describe(self : SolveFailure) -> String

    SolvedLayout

    pub(all) struct SolvedLayout {
    rects : Map[String, Rect]
    failures : Array[SolveFailure]
    }

    SolvedLayout::rect_of

    fn SolvedLayout::rect_of(self : SolvedLayout, id : String) -> Rect?

    SpacingNote

    pub(all) struct SpacingNote {
    node_id : String
    label : String
    value : Double
    unit : String
    }

    设计标注系统:自动从原型生成开发者交接规范(Spec)。

    这是 Figma Dev Mode / Zeplin 的等价物:
    • 间距标注:每个元素到父容器/兄弟的精确距离
    • 颜色标注:所有用到的颜色及其语义令牌名
    • 字体标注:字号/颜色/令牌映射
    • 组件清单:用了哪些组件、每个的变体和属性
    • 交互标注:点击/滑动触发什么

    输出为结构化 Markdown,工程师直接复制使用。

    StackDir

    pub(all) enum StackDir {
    Vertical
    Horizontal
    }

    StackLayout

    pub(all) struct StackLayout {
    dir : StackDir
    gap : Double
    justify : Justify
    padding : Padding
    }

    栈布局:Figma Auto Layout 的最小可用子集

    StateChange

    pub(all) enum StateChange {
    ArtboardChanged(String)
    NodeUpdated(String)
    NavigationPushed(String)
    NavigationPopped(String)
    ToastShown(String)
    FormSubmitted(Map[String, String])
    }

    StateChange::describe

    fn StateChange::describe(self : StateChange) -> String

    StyleParse

    type StyleParse

    解析 style 子对象:返回 (fill, stroke, stroke_width, corner_radius, opacity, font_size, text_color, font_weight, shadow, rotate, blur, blend, line_height, tracking, flip, text_align, font_style, stroke_dash, visible)

    TemplateInfo

    pub(all) struct TemplateInfo {
    id : String
    name : String
    description : String
    category : String
    tags : Array[String]
    device : String
    }

    页面模板库:Agent 说"做一个登录页",引擎直接生成完整画板。

    每个模板是一个 (Project) → String 的函数: 输入当前项目(共享令牌/组件),输出新画板 ID。 模板内部使用设计令牌保证视觉一致性,组件间距遵循 Material 3 规范。

    这是"原型设计引擎"区别于"组件放置器"的关键: 模板理解页面语义——登录页有什么、仪表盘有什么、设置页有什么。

    Theme

    pub(all) struct Theme {
    name : String
    display_name : String
    tokens : DesignTokens
    is_dark : Bool
    }

    Theme::auto_dark

    fn Theme::auto_dark(base : Theme) -> Theme

    从主题自动生成暗色版本(RGB 通道反转——即色相旋转 180°,非保留色相的 亮度反演;HSL 语义的反转需要感知色相空间,v1 不引入)

    Theme::dark

    fn Theme::dark() -> Theme

    Theme::high_contrast

    fn Theme::high_contrast() -> Theme

    Theme::light

    fn Theme::light() -> Theme

    Theme::nord

    fn Theme::nord() -> Theme

    Theme::sepia

    fn Theme::sepia() -> Theme

    Theme::sunset

    fn Theme::sunset() -> Theme

    Timeline

    pub(all) struct Timeline {
    clips : Array[AnimationClip]
    total_duration : Double
    }

    Timeline::add

    fn Timeline::add(self : Timeline, clip : AnimationClip) -> Unit

    Timeline::add_parallel

    fn Timeline::add_parallel(self : Timeline, clips : Array[AnimationClip]) -> Unit

    并行添加(同时开始)

    Timeline::add_sequence

    fn Timeline::add_sequence(self : Timeline, clips : Array[AnimationClip]) -> Unit

    顺序添加(依次执行)

    Timeline::new

    fn Timeline::new() -> Timeline

    Timeline::to_css

    fn Timeline::to_css(self : Timeline) -> String

    生成 CSS @keyframes + animation 属性

    ToolArg

    pub(all) struct ToolArg {
    name : String
    type_ : String
    desc : String
    required : Bool
    }

    单个参数:名称 / JSON 类型 / 说明 / 是否必需

    Transition

    pub(all) enum Transition {
    Push
    Pop
    ModalPresent
    ModalDismiss
    SheetPresent
    Fade
    NoTransition
    }

    Transition::name

    fn Transition::name(self : Transition) -> String

    Trigger

    pub(all) enum Trigger {
    Tap
    LongPress(Double)
    SwipeLeft
    SwipeRight
    SwipeUp
    SwipeDown
    ScrollEnd
    KeyboardEnter
    Focus
    Blur
    }

    交互原型系统:原型不是静态图——它有状态、有事件、有转场。

    核心概念:
    • Trigger:什么触发了交互(tap / 长按 / 滑动 / 键盘)
    • Action:交互发生什么(导航 / 切换状态 / 更新文字 / 提交表单)
    • Transition:页面如何过渡(push / modal / fade)
    • ComponentState:交互组件的多态(default / pressed / disabled / loading)

    运行时引擎(runtime.mbt)消费这些定义,驱动可交互的原型。

    Trigger::name

    fn Trigger::name(self : Trigger) -> String

    UserComponentDef

    pub(all) struct UserComponentDef {
    id : String
    description : String
    category : String
    params : Array[UserParam]
    variants : Map[String, Map[String, String]]
    default_variant : String
    width : Double
    height : Double
    doc : Document
    source : String
    }

    用户组件:带参数槽的节点树模板。 doc 是组件画板(相对坐标);实例化 = 深拷贝 + 参数代入 + 放置。

    UserParam

    pub(all) struct UserParam {
    name : String
    kind : String
    default_value : String
    }

    VariantScore

    pub(all) struct VariantScore {
    artboard : String
    violations : Int
    lint_issues : Int
    alignment_hints : Int
    node_count : Int
    score : Int
    }

    变体探索:Agent 并行尝试多个设计方案,评审后选最优。

    设计师的工作流是"做几版然后挑最好的"。 Agent 的等价体验:fork_variants(project, base, ["v1","v2","v3"]) → 引擎为每个变体创建独立的画板分支 → Agent 分别修改每个变体 → score_variants(project) 对所有变体跑 lint + 谓词 + 对齐建议 → Agent 据此选出最优方案并合并

    Violation

    pub(all) struct Violation {
    predicate : Predicate
    node_id : String
    detail : String
    }

    Violation::to_json

    fn Violation::to_json(self : Violation) -> String

    VizEvent

    pub(all) enum VizEvent {
    TapEvent(Double, Double)
    LongPressEvent(Double, Double)
    SwipeEvent(String)
    KeyEvent(String)
    FocusEvent(String)
    BlurEvent(String)
    }

    嵌入式运行时 SDK:其他项目加载 .moonviz → 动态渲染 + 事件处理。

    宿主应用(编辑器 / Web 应用 / 桌面工具 / Agent 工作台)通过这个 SDK:
    1. MoonVizRT::create(project) → 创建运行时实例
    2. rt.handle_event(event) → 处理交互事件,返回状态变更列表
    3. rt.render_plan() → 获取后端无关的渲染指令(RenderPlan)
    4. rt.hot_reload_doc(doc) → 替换画板文档,保留导航栈与输入值

    RenderPlan 是一个 显示列表(display list): 任何渲染后端(Canvas / Skia / SVG / 终端 / OpenGL)都能消费。

    VizEvent::describe

    fn VizEvent::describe(self : VizEvent) -> String

    ASCII_ADVANCE_RATIO

    let ASCII_ADVANCE_RATIO : Double

    CJK_CODEPOINT_MIN

    let CJK_CODEPOINT_MIN : Int

    ENGINE_VERSION

    let ENGINE_VERSION : String

    引擎版本单一事实源:moon.mod 同步维护。 version_info(wasm)、CLI banner、MCP serverInfo、artifact meta_version 全部引用本常量——发布新版本时改这一处 + moon.mod。

    FREE_LAYER_ID

    let FREE_LAYER_ID : String

    自由层节点 id(每个画布一棵)

    GENERATE_MULTI_MAX

    let GENERATE_MULTI_MAX : Int

    组合意图上限:一句话最多展开 4 块画板(防滥用;真实原型一屏意图 极少超过 4 页)。

    MOTION_BASE

    let MOTION_BASE : Int

    MOTION_FAST

    let MOTION_FAST : Int

    动效时长刻度(ms)。导出 HTML 与一切宿主共用同一套节拍: 即时反馈 120 / 标准转场 240 / 强调慢速 360。

    MOTION_SLOW

    let MOTION_SLOW : Int

    NORM_CONTRAST_MIN

    let NORM_CONTRAST_MIN : Double

    NORM_PURE_DARK_LUMA_MAX

    let NORM_PURE_DARK_LUMA_MAX : Double

    纯黑/近黑灰背景禁令:灰度(通道差 < 8)且相对亮度 < 0.01 (覆盖 #000000–#151515 一类硬填黑,暗色主题的蓝调深底不受影响)。

    NORM_RADIUS_BASE

    let NORM_RADIUS_BASE : Double

    方正圆润圆角档:按钮族默认 8px

    NORM_TEXT_CONTRAST_LARGE_MIN

    let NORM_TEXT_CONTRAST_LARGE_MIN : Double

    大字号(>=24px)放宽到 WCAG AA 大文本 3.0。

    NORM_TEXT_CONTRAST_MIN

    let NORM_TEXT_CONTRAST_MIN : Double

    正文文字最小对比度(WCAG AA 正文 4.5)。

    NORM_TEXT_PAD_X

    let NORM_TEXT_PAD_X : Double

    横向留白下限(左右各 12):与 svg.mbt 渲染层 text pad 同值

    NORM_TEXT_PAD_Y

    let NORM_TEXT_PAD_Y : Double

    纵向留白下限(上下各 10)

    OPS_BATCH_LIMIT

    let OPS_BATCH_LIMIT : Int

    批量执行上限:防滥用/防失控循环;64 条足够覆盖一次精修轮。

    SIZE_SANITY_LIMIT

    let SIZE_SANITY_LIMIT : Double

    尺寸有效性上限:拦截 Infinity 与异常大的数值。 NaN 参与任何比较均为 false,因此天然被排除。

    TEXT_LINE_HEIGHT_RATIO

    let TEXT_LINE_HEIGHT_RATIO : Double

    文本内在尺寸估算(v1:CJK 全角按 1.0 倍字号,其余 0.6 倍;行高 1.5)。 M2 计划:编辑器运行时用 canvas measureText 实测后写入文档,见 docs/03。

    action_from_spec

    fn action_from_spec(spec : String) -> Action?

    action 规格 → Action。规格语法与 Action::describe 的输出对称: back | haptic | navigate_to: | show_toast:"msg" | play_sound: | toggle_state: | set_state:: | set_text::"text"

    animation_css

    fn animation_css(node_id : String, preset : String) -> String

    按预设生成单节点 CSS 动画(anim-css / animation_css): animation_css(node_id, preset) → { ok, css } 完整 @keyframes + class。

    animation_presets_json

    fn animation_presets_json() -> String

    预设动画清单(anim-list / animation_presets)。

    apply_agent_patch

    fn apply_agent_patch(doc : Document, patch : Patch) -> Result[Array[Violation], PatchError]

    Agent 路线入口:硬门槛。成功返回空违规集(永远为空)。

    apply_human_op

    fn apply_human_op(doc : Document, patch : Patch) -> Result[Array[Violation], PatchError]

    人类路线入口:结构硬、视觉软。成功时返回携带的视觉债。

    apply_operation

    fn apply_operation(project : Project, operation : String) -> Result[Unit, String]

    apply_operations

    fn apply_operations(project : Project, operations : Array[String]) -> Result[Int, (Int, String)]

    批量执行 mutating ops(生成式执行策略第二级:确定的精修一次提交, 替代 N 次单调用往返)。顺序执行、遇错即停——与逐条执行语义完全一致 (错误处之后的 op 不落,索引随错误返回供断点续批)。

    breakpoints_json

    fn breakpoints_json() -> String

    builtin_components

    fn builtin_components() -> Map[String, ComponentDef]

    内置组件库(Agent 的调色板)

    builtin_slotted_components

    fn builtin_slotted_components() -> Map[String, SlottedComponent]

    builtin_themes

    fn builtin_themes() -> Array[Theme]

    预定义主题注册表

    collect_param_refs

    fn collect_param_refs(def : UserComponentDef) -> Array[String] raise

    校验辅助:收集节点属性中出现的 ${name} 引用(compile 阶段闭合检查)。 单遍扫描(每轮 rest 严格前进),无轮数上限。

    component_norm

    fn component_norm(id : String) -> String?

    组件规范一句话(list_components 随条目下发——Agent 选组件时即可见规范, 不必等 critique 事后纠正)。返回 None 的组件不下发该字段。

    contrast_ratio

    fn contrast_ratio(fg : String, bg : String) -> Double

    WCAG 对比度

    decide

    fn decide(gate : Gate, violations : Array[Violation]) -> GateDecision

    default_breakpoints

    fn default_breakpoints() -> Array[Breakpoint]

    design_spec_draft_json

    fn design_spec_draft_json(intent_text : String) -> String

    spec 缺失时的可编辑草案(design_spec_required 随行返回)。 从 intent 抽取推荐强调色;其余取引擎基线,Agent 落盘后重试 generate。

    diff_docs

    fn diff_docs(before : Document, after : Document) -> DocDiff

    比较两个文档(通常 before = 操作前快照,after = 操作后)

    ds_components_policy

    fn ds_components_policy(spec : String) -> (Array[String], Array[String])

    spec.components 策略:数组 = 白名单;对象支持 allow/deny 数组。

    extended_components

    fn extended_components(m : Map[String, ComponentDef]) -> Map[String, ComponentDef]

    追加扩展组件(独立函数便于 builtin_components 尾部调用)

    extended_components_v5

    fn extended_components_v5(m : Map[String, ComponentDef]) -> Map[String, ComponentDef]

    追加 v5 批次:bento_grid / chat_bubble / command_palette / hover_card / lightbox / marquee / masonry / multi_select / resize_handle / scrim / status_dot / steps / toggle_group (数量漂移由 agent_test 的 catalog 断言锚定,注释不承载权威计数)

    extract_interaction_marker

    fn extract_interaction_marker(name : String) -> String

    从 name 中提取交互标记("⚡..."),无则空串。

    fade_in_animation

    fn fade_in_animation(node_id : String, duration? : Double) -> AnimationClip

    淡入效果

    index_of_str

    fn index_of_str(s : String, sub : String) -> Int

    查找子串首次出现位置;未找到返回 -1

    instantiate_component

    fn instantiate_component(def : ComponentDef, id : String, variant? : String, tokens? : DesignTokens) -> Node

    实例化组件:返回可直接放入文档的 Node

    interpolate

    fn interpolate(start : Double, end : Double, t : Double, easing : Easing) -> Double

    数值插值:根据缓动函数计算 t 时刻的值

    is_back_like_node

    fn is_back_like_node(n : Node) -> Bool

    返回类节点判定(与宿主端 isBackish 启发式同语义,双端不再各自维护):
    • id 词边界含 back/prev/return(backdrop 不算)
    • 文本为 返回/后退/上一步/back/←/‹/«,或以「返回」开头,或 ≤3 字含左箭头 runtime 对返回类节点的 tap 有内置返回兜底(无 flow/marker 时强制返回 上一层),热区导出与校验共用本判定。

    json_escape

    fn json_escape(s : String) -> String

    JSON 字符串转义(含引号、反斜杠与全部 C0 控制符——\b \f 等按 RFC 8259 统一输出 \u00xx,裸控制字符合法 JSON 不允许;playground 协议层复用)。

    json_string_array

    fn json_string_array(items : Array[String]) -> String

    字符串数组 → JSON 数组文本(逐项 json_escape;空数组恒输出 []—— issue #10 纪律:envelope 集合键不允许裸拼接)。信封构造的统一出口。

    list_components_json

    fn list_components_json(defs : Map[String, ComponentDef]) -> String

    组件清单 JSON(Agent 发现用)

    list_ops_json

    fn list_ops_json() -> String

    CLI op 面字典(list-ops / list_ops 输出): [{"op","usage","category","description","gates":{"agent":true,"human":true}}]

    全部 mutating op 在双路线共享(条数随注册表演进,由 core/ops_registry_wbtest 锚定,不写死数字;差别在提交门禁的校验强度: AgentGate 硬拦结构违规,HumanGate 放行视觉债);fix 的还债特例写进 description。

    list_slotted_json

    fn list_slotted_json() -> String

    组合式组件清单 JSON(Agent 发现用)

    list_templates

    fn list_templates() -> Array[TemplateInfo]

    可用模板清单(Agent 发现用)

    list_templates_json

    fn list_templates_json() -> String

    模板清单 JSON

    list_tools

    fn list_tools() -> Array[AgentTool]

    引擎内置工具清单:与 mcp/main.mbt execute_tool 的分支一一对应 (不写死数字,分支数随工具注册演进,漂移由 wbtest 锚定)。

    list_tools_json

    fn list_tools_json() -> String

    MCP tools/list 兼容的工具字典: [{"name","description","inputSchema":{"type":"object","properties":{...},"required":[...]}}]

    CLI list-tools、落地项目(Studio/playground)的 moonviz-tools.json 均以本函数输出为准。

    lt_box

    fn lt_box(id~ : String, fill~ : String, w~ : Double, h~ : Double, radius? : Double, shadow? : String, stroke? : String) -> LT

    通用盒(面板/背景/插图占位),宽高显式给定

    lt_btn

    fn lt_btn(id~ : String, label~ : String, variant? : String) -> LT

    按钮(主/次)——颜色查设计令牌,与组件目录 button 同源

    lt_card

    fn lt_card(id~ : String, gap? : Double, pad? : Double, kids? : Array[LT]) -> LT

    白卡(垂直栈 + 现代阴影 + 细边)——底色/描边查令牌

    lt_dot

    fn lt_dot(id~ : String, fill~ : String, d? : Double) -> LT

    圆形徽标

    lt_flex

    fn lt_flex(id~ : String, fill? : String) -> LT

    弹性盒:吃满剩余空间(用作分隔/自适应留白)

    lt_h

    fn lt_h(id~ : String, gap? : Double, pad? : Double, kids? : Array[LT]) -> LT

    水平栈(默认占满父容器)

    lt_input

    fn lt_input(id~ : String, ph~ : String) -> LT

    输入框(占位文字用 text_hint,描边用 outline——与令牌体系同源)

    lt_text

    fn lt_text(id~ : String, role~ : String, s~ : String) -> LT

    文本(按排版令牌定字号;宽 Fill 高 Hug)。 字号/文字色一律查 DesignTokens——结构式模板与组件目录、手机模板共用 同一排版体系,不允许本文件自立字号表(双源漂移回归锚)。

    lt_v

    fn lt_v(id~ : String, gap? : Double, pad? : Double, kids? : Array[LT]) -> LT

    垂直栈(默认占满父容器,子项沿主轴堆叠)

    mcf_header_json

    fn mcf_header_json(def : UserComponentDef) -> String

    组件元信息 → MCF header JSON(CLI/MCP 共用的唯一构造点, 保证同一 mcf-v1 版本的 header schema 一致)

    mcf_pack

    fn mcf_pack(header_json : String, mbt_source : String) -> Result[Bytes, String]

    打包:header_json + mbt 源码 → MCF 字节。 header TLV 长度字段是 u16:超限直接拒绝(防静默截断)。

    mcf_unpack

    fn mcf_unpack(bytes : Bytes) -> Result[(String, String), String]

    解包:严格校验 magic/version/长度/双 crc/指纹,任一不符即拒绝。

    merge_sessions

    fn merge_sessions(ours : AgentSession, theirs : AgentSession) -> MergeResult

    三方合并:检测 ours 和 theirs 的操作冲突

    冲突判定规则:
    1. 同节点同字段 → 冲突(除非值相同)
    2. 一方删除 + 另一方修改 → 冲突(建议:保留修改方,或标记删除方)
    3. 同节点不同字段 → 不冲突,可并行
    4. 不同节点 → 不冲突

    merge_sessions_from_spec

    fn merge_sessions_from_spec(spec : String) -> String

    合并请求规格(CLI collab-merge / MCP collab_merge 共用): <base_rev> <agentA>=<op>[+<op>...] <agentB>=<op>[+<op>...] ... 例:1 a=fill:btn:#000:#111 b=pos:btn:1:2:3:4+gap:btn:8:16 返回 MergeResult 数组的 JSON(含冲突标记与自动解决结果)。
    fn modal_present(node_id : String) -> AnimationClip

    弹出效果(modal)

    motion_tokens_css

    fn motion_tokens_css() -> String

    动效令牌 CSS(:root 变量):时长刻度 + 引擎缓动曲线(cubic-bezier 等价式)。 曲线一律出自 Easing::css_value——导出原型、宿主、运行时共用同一来源, 不允许各处手写贝塞尔(节拍/手感漂移是精致感的第一杀手)。

    norm_density_issues

    fn norm_density_issues(doc : Document) -> Array[String]

    norm_fix_pass

    fn norm_fix_pass(doc : Document, layout : SolvedLayout, radius_base? : Double) -> Array[String]

    规范修复:与 norm_issues 同一判据,直接改文档并返回修复明细 (JSON 片段,格式与 autofix 的 fix_* 家族一致)。

    norm_grid_issues

    fn norm_grid_issues(doc : Document) -> Array[String]

    norm_is_action_component

    fn norm_is_action_component(component : String) -> Bool

    操作组件族:承载短文案、点击即动作。文案与边缘必须有留白。

    norm_is_full_bleed_component

    fn norm_is_full_bleed_component(component : String) -> Bool

    全宽顶边/底边条与全宽行:占满画板宽度时应当直角(圆角会顶出屏幕边缘)

    norm_is_pure_dark

    fn norm_is_pure_dark(hex : String) -> Bool

    norm_is_rounded_component

    fn norm_is_rounded_component(component : String) -> Bool

    方正圆润族:默认 8px 圆角档(avatar 999 正圆、全宽条 0 不在此列)

    norm_issues

    fn norm_issues(doc : Document, layout : SolvedLayout, radius_base? : Double) -> Array[String]

    检测组件规范偏差,返回人可读问题清单(critique 第 9 维 norms)。 每条自带建议尺寸——Agent 读到就能改,不必自己换算。 顺序即优先级:结构性偏差(列表缺分割线)在前,逐条样式在后; 上限 8 条,控制报告体积(deepDesign 侧检视结果有 12KB 截断)。

    norm_issues_v2

    fn norm_issues_v2(doc : Document, layout : SolvedLayout, radius_base? : Double, contrast_min? : Double, touch_min? : Double) -> Array[String]

    norm_readability_issues

    fn norm_readability_issues(doc : Document, layout : SolvedLayout, contrast_min? : Double) -> Array[String]

    issue #23 检测项(doc 级):
    1. 可读性对比度:正文 < 4.5、大字号(>=24px)< 3.0——2.0 以下已由 v1 撞色规则报告并 auto_fix,这里补 [2.0, need) 区间(检测项,给改法)。
    2. 组件不可见:叶子节点纯色填充与父背景完全同色、无描边、无文本。
    3. 纯黑/近黑灰背景:有子节点的容器硬填灰度近黑(生硬刺眼,用户明确不要)。

    norm_touch_fix_pass

    fn norm_touch_fix_pass(doc : Document, layout : SolvedLayout, touch_min? : Double) -> Array[String]

    Norms v2 触控修复:交互组件低于触控最小值的抬到最小值。与 norm_touch_issues 同一判据(同一组件集、同一分档、同一 0.5 容差); 只抬 Fixed 维度——Hug/Fill 尺寸策略不得被静默降级为 Fixed。放大可能 引入溢出,由 auto_fix 在本 pass 之后的谓词循环清偿(与文案留白放大同序)。

    norm_touch_issues

    fn norm_touch_issues(doc : Document, layout : SolvedLayout, touch_min? : Double) -> Array[String]

    norm_type_issues

    fn norm_type_issues(doc : Document) -> Array[String]

    norms_list_runs

    fn norms_list_runs(doc : Document, layout : SolvedLayout) -> Array[NormListRun]

    扫描齐缝列表行连排(NormListRun)。每个 run 是一个「裸列表」: 检测(norm_issues)与修复(autofix 的 norm_list_divider_fix)都消费它。

    op_entries

    fn op_entries() -> Array[OpEntry]

    CLI op 面注册表:Agent 与 Human 双路线共享的全部 mutating 操作。

    ⚠️ 与 core/ops.mbt 的 apply_operation 分发器一一对应——新增 op 时 三处同步:分发器分支、本注册表、SKILL.md 语法块。drift-guard 测试 (ops_registry_wbtest.mbt)会对每条注册 op 实际打一遍分发器,usage 不一致或漏注册都会红。

    parse_double

    fn parse_double(s : String) -> Double

    解析十进制数(含小数与负号);非法输入返回 0

    parse_generate_intent

    fn parse_generate_intent(text : String) -> GenIntent

    意图 → 生成决策。中英关键词、设备暗示(web/平板/PC)与主题暗示 (dark/暗色 → dark)一次解析;页面语义按"具体优先"计分,平分时全部 记入 alternatives(信封可见,Agent 可换 template 精修)。

    parse_interaction_marker

    fn parse_interaction_marker(name : String) -> (String, String)?

    从节点名提取交互标记 → (trigger, action_spec)。 标记由 add_interaction 追加,格式 "…⚡→"。 用字符迭代 + ASCII 白名单提取 trigger,避免多字节 emoji 的字节偏移歧义。

    parse_layout_intent

    fn parse_layout_intent(text : String) -> LayoutIntent

    解析自然语言约束 → LayoutIntent Agent 传入 "居中对齐按钮" / "垂直排列" / "等宽" 等中文或英文

    parse_op_double

    fn parse_op_double(s : String) -> Double

    parse_place_args

    fn parse_place_args(parts : Array[String]) -> PlaceArgs

    place 尾部参数解析(issue #18 w/h 槽):CLI(cli_exec 的 place 命令) 与 apply_operation 的 place 臂共用此实现——「双路线解析必须一致」 由单一实现结构性兑现,不再各持副本互相漂移。 parts 为 split_cmd 产物,布局: [place, ab, comp, id, variant?, x?, y?, w?, h?, k=v...]。

    parse_state_markers

    fn parse_state_markers(name : String) -> Array[(String, NodePatch)]?

    解析名字中的全部 [state:name:spec] 标记 → (state_name, NodePatch) 列表。 标记定位转义感知(find_unescaped_seq):spec 的 text 值经 spec_escape 写入,值里的 ] / [state: 不是结构字符。

    place_user_component

    fn place_user_component(target : Document, def : UserComponentDef, instance_id : String, variant? : String, args? : Map[String, String], dx? : Double, dy? : Double) -> Result[String, String]

    深拷贝组件树到目标画板:BFS 按依赖序(父先子后)insert。 实例节点 id = <instance_id>::<原id>;顶层节点以 (dx, dy) 为组件 包围盒原点做绝对放置(首个顶层节点落在 (dx,dy),其余保持相对结构, 与内置组件的绝对落点语义一致)。 任一步失败时回滚已插入节点,目标画板保持调用前状态。 返回插入的顶层根节点 id。

    pop_animation

    fn pop_animation(node_id : String) -> AnimationClip

    缩放弹出(成功反馈)

    pos_offset_x

    fn pos_offset_x(p : PosSpec) -> Double

    取位置规格的数值分量(x_mode/y_mode 降级为 AlignStart 时保留原偏移)

    pos_offset_y

    fn pos_offset_y(p : PosSpec) -> Double

    press_animation

    fn press_animation(node_id : String) -> AnimationClip

    按钮按压效果:缩小到 0.95 再弹回

    qa_is_interactive_component

    fn qa_is_interactive_component(c : String) -> Bool

    可交互族组件(无 flow/交互标记时必须报告)。

    qa_is_mock_container

    fn qa_is_mock_container(c : String) -> Bool

    mock 容器族:空壳(无子节点、无文本)视为缺示例数据。

    qa_is_placeholder_text

    fn qa_is_placeholder_text(t : String) -> Bool

    占位符残留判定(issue #25-B5):TBD/TODO/Lorem/xxx/Item 1/项目一/示例文本/占位。

    rebuild_name

    fn rebuild_name(name : String, state_markers : Array[String]) -> String

    用新的状态标记重建节点名:保留原始名与交互标记,替换全部状态标记。

    render_svg

    fn render_svg(doc : Document, surface? : String, frame? : String) -> String

    文档 → SVG 字符串(根矩形即画布尺寸,浅底)

    surface 为画布底色令牌值:主题切换后由 Project 侧传入当前主题的 surface(如 nord 的 #2E3440);默认浅色 #F6F7F9 保持既有文档兼容。

    run_protest_script

    fn run_protest_script(project : Project, initial : String, script : String) -> String

    原型测试脚本(分号分隔,可带空行): tap:<x>:<y>><expect_board> 点击 → 期望导航 back><expect_board> 返回 → 期望画板 swipe:<dir>><expect_board> 滑动 → 期望画板(dir: left/right/up/down) set:<node>:<value> 输入 → 期望回读一致 noviol 期望零违规 render 期望可渲染 例:tap:160:422>home; back>login; noviol; render

    shake_animation

    fn shake_animation(node_id : String) -> AnimationClip

    抖动效果(错误提示)

    size_is_valid

    fn size_is_valid(w : Double, h : Double) -> Bool

    尺寸是否有效:非负、有限、且小于 sanity 上限

    slide_in_right

    fn slide_in_right(node_id : String) -> AnimationClip

    滑入效果(从右侧)

    solve

    fn solve(doc : Document) -> SolvedLayout

    求解入口:输入文档,输出每个节点的画布绝对矩形 + 求解失败列表

    split_cmd

    fn split_cmd(line : String) -> Array[String]

    split_intent_segments

    fn split_intent_segments(text : String) -> Array[String]

    意图分段:按 "+" / "+" 切分(保守分隔符——空格是单意图内的正常 组成部分,"登录页 dark" 不受影响),去空白、丢空段。

    strip_all_markers

    fn strip_all_markers(name : String) -> String

    去掉节点名中的全部标记(交互 ⚡ 与状态 [state:),还原原始名。

    strip_markers

    fn strip_markers(name : String) -> String

    去掉名称里的交互标记(含 marker 与其前的分隔空格)。

    text_intrinsic

    fn text_intrinsic(text : String, font_size : Double, line_height? : Double) -> Size

    transform_insert_index

    fn transform_insert_index(our_index : Int, their_index : Int, our_timestamp : Double, their_timestamp : Double) -> Int

    当两个 Agent 同时插入节点到同一父容器时,调整索引避免覆盖

    trigger_from_spec

    fn trigger_from_spec(spec : String) -> Trigger?

    trigger 规格 → Trigger(CLI / Agent 语法共用)。 别名与 Trigger::name 保持一致;keyboard_enter 接受 key_enter 简写。

    unescape_value

    fn unescape_value(s : String) -> String

    CLI/engine 边界的公共值还原:把 \" \\ \, \( \) \n \r \t 还原为字面字符。

    validate

    fn validate(doc : Document) -> Array[Violation]

    全量校验:结构 + 尺寸 + 视觉 + 可解性