@joplo-app/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/dist/catalog.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 组件目录 v3（D35）：名称与属性对齐 Mantine（数据表对齐 mantine-datatable），另加少量 AI 交互组件、
+ * HTML 兜底标签和 Joplo 专用组件。复合组件用点语法：`<AppShell.Header>` 编译出的节点 type 就是 'AppShell.Header'。
+ *
+ * 目录是唯一来源：@joplo-app/kit/ui 的导出、渲染器（@joplo-app/web）的实现、COMPONENT_DOCS 都必须与 COMPONENT_TYPES 一致
+ * （packages/core/test/catalog.test.ts 与渲染器的类型检查保证）。目录之外的名称在编译时报错，不会被静默渲染。
+ * 只换词汇，不换渲染：运行时不引入 Mantine，仍由 Joplo 渲染成低保真风格。
+ */
+export declare const COMPONENT_TYPES: readonly ["AppShell", "AppShell.Header", "AppShell.Navbar", "AppShell.Main", "AppShell.Aside", "AppShell.Footer", "Container", "Stack", "Group", "Flex", "Grid", "Grid.Col", "SimpleGrid", "Center", "Box", "Space", "Paper", "Card", "Card.Section", "Divider", "ScrollArea", "Title", "Text", "Code", "Kbd", "Blockquote", "List", "List.Item", "Badge", "Avatar", "Image", "ThemeIcon", "Indicator", "Timeline", "Timeline.Item", "Table", "Table.Thead", "Table.Tbody", "Table.Tr", "Table.Th", "Table.Td", "DataTable", "Accordion", "Accordion.Item", "Accordion.Panel", "Radio", "Tabs.List", "Tabs.Panel", "Breadcrumbs", "Stepper", "Stepper.Step", "Alert", "Loader", "Progress", "RingProgress", "Skeleton", "Notification", "Modal", "Drawer", "ChatMessage", "ToolCall", "Terminal", "Terminal.Command", "Terminal.Output", "Phone", "Diagram", "Diagram.Group", "Diagram.Node", "Diagram.Edge", "div", "span", "p", "h1", "h2", "h3", "h4", "main", "section", "header", "footer", "nav", "aside", "ul", "ol", "li", "strong", "em", "small", "code", "Placeholder", "Custom", "#text", "Button", "ActionIcon", "CloseButton", "Anchor", "a", "NavLink", "Burger", "TextInput", "PasswordInput", "NumberInput", "Textarea", "Select", "MultiSelect", "Checkbox", "Radio.Group", "Switch", "SegmentedControl", "FileInput", "Tabs", "Tabs.Tab", "Accordion.Control", "Pagination", "PromptInput", "Terminal.Input"];
+export type ComponentType = (typeof COMPONENT_TYPES)[number];
+export declare const INTERACTIVE_TYPES: ReadonlySet<string>;
+/** 可接收输入值；type/select/toggle 动作写入 state.inputs[nodeId]。 */
+export declare const VALUE_TYPES: ReadonlySet<string>;
+/** 只有 opened（兼容旧写法 open）为真时自身和子节点才可见的浮层。 */
+export declare const GATED_CONTAINERS: ReadonlySet<string>;
+/** Joplo 在 Mantine 属性之外追加的属性，编译器会从 props 中取出，放到节点字段上。 */
+export declare const JOPLO_PROPS: readonly ["id", "when", "disabledReason", "unmodeled", "note"];
+/**
+ * 每个组件一行常用属性提示（`joplo skill components` 由此生成）。所有组件另外都接受：
+ * 样式属性 m/mt/mb/ml/mr/mx/my、p/pt/pb/pl/pr/px/py、w/h/miw/maw/mih/mah、c/bg/fz/fw/ta/ff/lh/opacity，
+ * 响应式写成 { base, xs, sm, md, lg, xl }；visibleFrom / hiddenFrom；以及 Joplo 属性 id/when/disabled/disabledReason/unmodeled/note。
+ */
+export declare const COMPONENT_DOCS: Record<ComponentType, string>;
+/** Mantine 默认断点：36/48/62/75/88em，按 16px 换算。 */
+export declare const BREAKPOINTS: {
+    readonly xs: 576;
+    readonly sm: 768;
+    readonly md: 992;
+    readonly lg: 1200;
+    readonly xl: 1408;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+declare const BP_KEYS: readonly ["base", "xs", "sm", "md", "lg", "xl"];
+/** 页面 viewport 对应的舞台尺寸。 */
+export declare const VIEWPORT_SIZE: {
+    readonly desktop: {
+        readonly width: 1280;
+        readonly height: 800;
+    };
+    readonly mobile: {
+        readonly width: 390;
+        readonly height: 844;
+    };
+};
+/**
+ * 字幕区：画面下方、播放控制上方的一块固定高度区域，最多两行：一行本步说明（大字），一行 explain（小一号）。
+ * 演示页、发布站、renderStep 截图、导出图片与视频都把它放在舞台正下方，宽度与舞台（手机含外框）相同。
+ */
+export declare const SUBTITLE_HEIGHT = 84;
+/**
+ * 内置主题（D51）：每个主题是一个只写 CSS 变量（--jp-*）的样式表，CSS 在 web 包里（renderer/themes.ts）。
+ * 作者可以在项目根目录 themes/<name>.css 写自己的主题；与内置同名时用作者的。
+ */
+export declare const BUILTIN_THEMES: readonly ["sketch", "clean", "blueprint", "nord", "dracula", "solarized-light", "terminal", "kraft", "contrast"];
+/** 主题名：字母开头，字母、数字、连字符、下划线（也是 themes/ 下的文件名）。 */
+export declare const THEME_NAME: RegExp;
+/** 字幕的“字数”：中文（及其他全角字符）一个算 1，英文、数字、标点按 0.5 算；空白不算。check 用它提示说明与 explain 过长。 */
+export declare function captionLength(s: string): number;
+/** 说明 / explain 的建议上限（超过时 check 报 CAPTION_TOO_LONG / EXPLAIN_TOO_LONG）。 */
+export declare const CAPTION_MAX = 24;
+export declare const EXPLAIN_MAX = 48;
+/** 没有声明 layers 的方案：镜头作用在路径页面上，记为这个伪层级（不出现在层级栏）。作者的层级键不能以 @ 开头。 */
+export declare const PAGE_LAYER = "@page";
+/** shot()（不带 id）在有层级的方案里：作用于“当时导演所在的层”，让它回到整体。 */
+export declare const DIRECTOR_LAYER = "@director";
+/** Diagram.Node 的 kind 与 Node / Edge 的 state（D41）。 */
+export declare const DIAGRAM_NODE_KINDS: readonly ["client", "service", "model", "database", "queue", "storage", "external", "tool", "user"];
+export declare const DIAGRAM_STATES: readonly ["idle", "active", "ok", "error", "dim"];
+/** 子节点排版用的宽度：Phone 内部按手机宽度（响应式取值、visibleFrom / hiddenFrom、AppShell 收起都按它算），其余节点沿用外部宽度。 */
+export declare function childWidth(type: string, width: number): number;
+/** 是否为响应式对象 `{ base, sm, md }`：普通对象，至少一个键，且全部键都是断点名。 */
+export declare function isResponsive(v: unknown): v is Partial<Record<(typeof BP_KEYS)[number], unknown>>;
+/** 按舞台宽度取响应式属性的值：取不超过宽度的最大断点；都不满足时取 base；非响应式值原样返回。 */
+export declare function atWidth(v: unknown, width: number): unknown;
+/** 断点名、数字（px）或 `40em` / `600px` 字符串 → 像素；无法识别返回 null。 */
+export declare function breakpointPx(bp: unknown): number | null;
+/** visibleFrom / hiddenFrom：在给定舞台宽度下是否被隐藏。 */
+export declare function hiddenAtWidth(props: Record<string, unknown> | undefined, width: number): boolean;
+export type Choice = {
+    value: string;
+    label: string;
+};
+/** Mantine 的 data：string[]、{ value, label }[]，或分组 { group, items }[]。 */
+export declare function choicesFromData(data: unknown): Choice[];
+/** 按 value 或 label 匹配一个选项。 */
+export declare function matchChoice(choices: Choice[], v: string): Choice | null;
+type LabelNode = {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: LabelNode[];
+};
+/** 元素的人类可读标签：优先 label/title/aria-label/placeholder 等属性（Mantine 输入组件直接带 label），其次子文本。 */
+export declare function nodeLabel(node: LabelNode): string;
+export {};

package/dist/catalog.js

@@ -0,0 +1,310 @@
+/**
+ * 组件目录 v3（D35）：名称与属性对齐 Mantine（数据表对齐 mantine-datatable），另加少量 AI 交互组件、
+ * HTML 兜底标签和 Joplo 专用组件。复合组件用点语法：`<AppShell.Header>` 编译出的节点 type 就是 'AppShell.Header'。
+ *
+ * 目录是唯一来源：@joplo-app/kit/ui 的导出、渲染器（@joplo-app/web）的实现、COMPONENT_DOCS 都必须与 COMPONENT_TYPES 一致
+ * （packages/core/test/catalog.test.ts 与渲染器的类型检查保证）。目录之外的名称在编译时报错，不会被静默渲染。
+ * 只换词汇，不换渲染：运行时不引入 Mantine，仍由 Joplo 渲染成低保真风格。
+ */
+/** 布局、展示与容器：不可操作。 */
+const STRUCTURE = [
+    // 布局
+    'AppShell', 'AppShell.Header', 'AppShell.Navbar', 'AppShell.Main', 'AppShell.Aside', 'AppShell.Footer',
+    'Container', 'Stack', 'Group', 'Flex', 'Grid', 'Grid.Col', 'SimpleGrid', 'Center', 'Box', 'Space',
+    'Paper', 'Card', 'Card.Section', 'Divider', 'ScrollArea',
+    // 文字与展示
+    'Title', 'Text', 'Code', 'Kbd', 'Blockquote', 'List', 'List.Item', 'Badge', 'Avatar', 'Image', 'ThemeIcon', 'Indicator',
+    'Timeline', 'Timeline.Item',
+    'Table', 'Table.Thead', 'Table.Tbody', 'Table.Tr', 'Table.Th', 'Table.Td', 'DataTable',
+    'Accordion', 'Accordion.Item', 'Accordion.Panel',
+    'Radio',
+    // 导航
+    'Tabs.List', 'Tabs.Panel', 'Breadcrumbs', 'Stepper', 'Stepper.Step',
+    // 反馈与浮层
+    'Alert', 'Loader', 'Progress', 'RingProgress', 'Skeleton', 'Notification', 'Modal', 'Drawer',
+    // AI 交互（Joplo 自有）
+    'ChatMessage', 'ToolCall',
+    // 设备外框（Joplo 自有）：终端与手机
+    'Terminal', 'Terminal.Command', 'Terminal.Output', 'Phone',
+    // 架构图（Joplo 自有，D41）：节点与连线的 state 绑定 $.ui，由 flow 步骤驱动
+    'Diagram', 'Diagram.Group', 'Diagram.Node', 'Diagram.Edge',
+    // HTML 兜底
+    'div', 'span', 'p', 'h1', 'h2', 'h3', 'h4', 'main', 'section', 'header', 'footer', 'nav', 'aside', 'ul', 'ol', 'li', 'strong', 'em', 'small', 'code',
+    // Joplo
+    'Placeholder', // props: label, h —— 图片/图表等占位
+    'Custom', // props: kind —— 逃生口：目录没有的组件，渲染为带说明的占位框
+    '#text', // 编译器生成的文本节点：props.text 为字面量或 `$ui.x` 绑定
+];
+/** 看起来可操作：必须有演示行为、明确禁用并说明原因，或标记 unmodeled。 */
+const INTERACTIVE = [
+    'Button', 'ActionIcon', 'CloseButton', 'Anchor', 'a', 'NavLink', 'Burger',
+    'TextInput', 'PasswordInput', 'NumberInput', 'Textarea', 'Select', 'MultiSelect', 'Checkbox', 'Radio.Group', 'Switch',
+    'SegmentedControl', 'FileInput', 'Tabs', 'Tabs.Tab', 'Accordion.Control', 'Pagination', 'PromptInput', 'Terminal.Input',
+];
+export const COMPONENT_TYPES = [...STRUCTURE, ...INTERACTIVE];
+export const INTERACTIVE_TYPES = new Set(INTERACTIVE);
+/** 可接收输入值；type/select/toggle 动作写入 state.inputs[nodeId]。 */
+export const VALUE_TYPES = new Set([
+    'TextInput', 'PasswordInput', 'NumberInput', 'Textarea', 'Select', 'MultiSelect', 'Checkbox', 'Radio.Group', 'Switch',
+    'SegmentedControl', 'FileInput', 'Tabs', 'Accordion', 'Pagination', 'PromptInput', 'Terminal.Input',
+]);
+/** 只有 opened（兼容旧写法 open）为真时自身和子节点才可见的浮层。 */
+export const GATED_CONTAINERS = new Set(['Modal', 'Drawer']);
+/** Joplo 在 Mantine 属性之外追加的属性，编译器会从 props 中取出，放到节点字段上。 */
+export const JOPLO_PROPS = ['id', 'when', 'disabledReason', 'unmodeled', 'note'];
+/**
+ * 每个组件一行常用属性提示（`joplo skill components` 由此生成）。所有组件另外都接受：
+ * 样式属性 m/mt/mb/ml/mr/mx/my、p/pt/pb/pl/pr/px/py、w/h/miw/maw/mih/mah、c/bg/fz/fw/ta/ff/lh/opacity，
+ * 响应式写成 { base, xs, sm, md, lg, xl }；visibleFrom / hiddenFrom；以及 Joplo 属性 id/when/disabled/disabledReason/unmodeled/note。
+ */
+export const COMPONENT_DOCS = {
+    AppShell: 'header={{ height }}, navbar={{ width, breakpoint, collapsed: { mobile, desktop } }}, aside={{ width, breakpoint, collapsed }}, footer={{ height }}, padding；窄于 breakpoint 时导航收起并显示 Burger',
+    'AppShell.Header': '顶栏；p, px',
+    'AppShell.Navbar': '侧边导航；p；放 NavLink',
+    'AppShell.Main': '主内容区；放 <Outlet />',
+    'AppShell.Aside': '右侧栏；p',
+    'AppShell.Footer': '底栏；p',
+    Container: 'size: xs|sm|md|lg|xl|number（默认 md）, fluid',
+    Stack: 'gap（默认 md）, align, justify —— 纵向排列',
+    Group: 'gap（默认 md）, justify, align（默认 center）, wrap, grow —— 横向排列',
+    Flex: 'direction, gap, rowGap, columnGap, align, justify, wrap —— 均可响应式',
+    Grid: 'columns（默认 12）, gutter, justify, align, grow；子元素用 Grid.Col',
+    'Grid.Col': 'span: number|"auto"|"content"|{ base, md }, offset',
+    SimpleGrid: 'cols={{ base: 1, md: 3 }}, spacing, verticalSpacing',
+    Center: 'inline —— 内容居中',
+    Box: '通用容器，只用样式属性',
+    Space: 'h, w —— 空白间隔',
+    Paper: 'p, withBorder, shadow, radius',
+    Card: 'padding（默认 md）, withBorder, shadow, radius；Card.Section 贴边分区',
+    'Card.Section': 'withBorder, inheritPadding',
+    Divider: 'label, labelPosition: left|center|right, orientation, my',
+    ScrollArea: 'h, mah',
+    Title: 'order: 1-6；文字写在子节点',
+    Text: 'size: xs|sm|md|lg|xl, c: dimmed|red|green|…, fw, ta, truncate, lineClamp, span；保留换行',
+    Code: 'block（多行代码块）, color',
+    Kbd: '键盘按键',
+    Blockquote: 'cite, color',
+    List: 'type: ordered|unordered, spacing；子元素用 List.Item',
+    'List.Item': '列表项',
+    Badge: 'color, variant: filled|light|outline|dot|default, size',
+    Avatar: 'name（显示首字）, src, color, radius, size',
+    Image: 'src, alt, h, w, radius —— 渲染为带 alt 的占位',
+    ThemeIcon: 'color, variant, size, radius；子节点放一个字符',
+    Indicator: 'label, color, disabled；包裹一个元素，在角上显示标记',
+    Timeline: 'active（已完成到第几项）, bulletSize；子元素用 Timeline.Item',
+    'Timeline.Item': 'title, bullet；子节点是说明',
+    Table: 'data={{ head: [...], body: [[...]] }} 或 Table.Thead/Tbody/Tr/Th/Td；striped, withTableBorder',
+    'Table.Thead': '表头',
+    'Table.Tbody': '表体',
+    'Table.Tr': '行',
+    'Table.Th': '表头单元格',
+    'Table.Td': '单元格',
+    DataTable: 'records（可绑定 $.data.x）, columns: [{ accessor, title }], noRecordsText —— 对齐 mantine-datatable',
+    Accordion: 'value / defaultValue（展开项）；select 动作写入展开项；子元素用 Accordion.Item',
+    'Accordion.Item': 'value；内含 Accordion.Control 与 Accordion.Panel',
+    'Accordion.Panel': '展开后显示的内容',
+    Radio: 'value, label —— 放在 Radio.Group 里',
+    'Tabs.List': '标签栏；放 Tabs.Tab',
+    'Tabs.Panel': 'value —— 当前标签的内容',
+    Breadcrumbs: 'separator；子节点放 Anchor 或文字',
+    Stepper: 'active（从 0 开始）；子元素用 Stepper.Step',
+    'Stepper.Step': 'label, description；子节点是该步内容（只显示当前步）',
+    Alert: 'title, color（默认 blue）, variant；子节点是说明',
+    Loader: 'size, color, type；可带子文字',
+    Progress: 'value 0-100, color, size, striped',
+    RingProgress: 'sections: [{ value, color }], label, size, thickness',
+    Skeleton: 'h, w, circle, radius, visible',
+    Notification: 'title, color, loading, withCloseButton —— 页面内的通知条（临时提示用步骤里的 toast）',
+    Modal: 'opened（门控，常写 opened={$.ui.open}）, title, size, centered, fullScreen',
+    Drawer: 'opened（门控）, title, position: left|right|top|bottom（默认 left）, size',
+    ChatMessage: "from: 'user'|'assistant', name；子节点是消息内容（保留换行）",
+    ToolCall: "title, state: 'running'|'done'|'error'；子节点是调用详情",
+    Terminal: 'title —— 终端窗口（命令行原型），子节点是 Terminal.Command / Terminal.Output / Terminal.Input；内容超出 h 或 mah 时内部滚动',
+    Diagram: "direction: 'right'|'down'（默认 right）, h（高度，默认 420）—— 架构图，子节点是 Diagram.Group / Diagram.Node / Diagram.Edge；布局自动生成且确定（state 变化不移动节点）；整图缩放放进容器（不滚动），看细节用演示页统一的缩放平移（滚轮 / 捏合 / 拖动）或镜头推近；连线正交走线、出入口与平行段间距 ≥ 10px；shot 同一张图里 2 个及以上节点（或一条连线）时，这些节点移到中央排成紧凑的聚焦小图；节点多、宽度有限时用 direction='down'。逐段出现：给 Group / Node / Edge 写 when={$.ui.x}，flow 里 set 为真时出现（布局按全部元素预先算好，已有元素不动）；调用链用步骤里的 trace() 描述，节点与连线的 state 自动推算",
+    'Diagram.Group': 'label —— 带标题的分组框，子节点是 Diagram.Node 或嵌套的 Diagram.Group',
+    'Diagram.Node': "id（必填，连线与 trace 靠它）, label, description（第二行小字）, kind: 'client'|'service'|'model'|'database'|'queue'|'storage'|'external'|'tool'|'user', state（可选）: 'idle'|'active'|'ok'|'error'|'dim'——不写时由步骤里的 trace() 自动推算；写了就以它为准",
+    'Diagram.Edge': "from, to（同一个 Diagram 里的 Node id）, label, async（虚线）, state（可选）: 'idle'|'active'|'ok'|'error'|'dim'；id 缺省为 \"from->to\"。演示调用链：步骤里写 trace('app', 'biz')（走这条线，自动变 active，之后 ok）、trace.fail(...)（error）、trace.skip(...)（dim），不用手写 state；同一方向有多条连线时 trace('连线 id')",
+    'Terminal.Command': 'prompt（默认 "$"）；子节点是命令文字',
+    'Terminal.Output': "tone: 'plain'|'ok'|'warn'|'error'（默认 plain）；子节点是输出文字（保留换行）",
+    Phone: 'scale（视觉缩放，默认 1）, h（屏幕高度，默认 844）—— 手机外框，子节点按手机宽度 390 排版，响应式断点按这个宽度计算；页面写 viewport: "mobile" 时舞台自动套上，不用写它',
+    div: 'HTML 兜底，建议改用 Box/Stack/Group',
+    span: 'HTML 兜底，建议改用 Text span',
+    p: 'HTML 兜底，建议改用 Text',
+    h1: 'HTML 兜底，建议改用 Title order={1}',
+    h2: 'HTML 兜底，建议改用 Title order={2}',
+    h3: 'HTML 兜底，建议改用 Title order={3}',
+    h4: 'HTML 兜底，建议改用 Title order={4}',
+    main: 'HTML 兜底，建议改用 AppShell.Main',
+    section: 'HTML 兜底，建议改用 Box',
+    header: 'HTML 兜底，建议改用 AppShell.Header',
+    footer: 'HTML 兜底，建议改用 AppShell.Footer',
+    nav: 'HTML 兜底，建议改用 AppShell.Navbar',
+    aside: 'HTML 兜底，建议改用 AppShell.Aside',
+    ul: 'HTML 兜底，建议改用 List',
+    ol: 'HTML 兜底，建议改用 List type="ordered"',
+    li: 'HTML 兜底，建议改用 List.Item',
+    strong: 'HTML 兜底，建议改用 Text fw={700} span',
+    em: 'HTML 兜底，建议改用 Text fs="italic" span',
+    small: 'HTML 兜底，建议改用 Text size="xs"',
+    code: 'HTML 兜底，建议改用 Code',
+    Placeholder: 'label, h —— 图片、图表等占位',
+    Custom: 'kind —— 目录没有的组件，渲染为带说明的占位框',
+    '#text': '编译器生成的文本节点（不要直接使用）',
+    Button: 'variant: filled|light|outline|subtle|default|white, color, size, fullWidth, loading, leftSection（字符）',
+    ActionIcon: "图标按钮：aria-label（必写，用作名称）, variant, color, size；子节点放一个字符如 '+'",
+    CloseButton: 'aria-label, size',
+    Anchor: 'href（看板内路径，不会真正跳转）, c, underline',
+    a: 'HTML 兜底，建议改用 Anchor',
+    NavLink: 'label, description, href（等于当前路径时高亮）, active, leftSection（字符）；可嵌套 NavLink',
+    Burger: 'opened, aria-label —— 窄屏导航开关，常配 hiddenFrom="sm"',
+    TextInput: 'label, placeholder, description, error, withAsterisk, type —— type 动作写入',
+    PasswordInput: 'label, placeholder, description, error —— type 动作写入，显示为圆点',
+    NumberInput: 'label, placeholder, min, max, suffix, prefix —— type 动作写入',
+    Textarea: 'label, placeholder, description, error, minRows, autosize —— type 动作写入',
+    Select: 'label, data: string[] | { value, label }[], placeholder, description —— select 动作接受 value 或 label',
+    MultiSelect: 'label, data, placeholder —— 每次 select 动作切换一个选项',
+    Checkbox: 'label, description, checked —— toggle 动作写入',
+    'Radio.Group': 'label, value；子元素用 Radio value/label —— select 动作接受 value 或 label',
+    Switch: 'label, description, checked —— toggle 动作写入',
+    SegmentedControl: 'data: string[] | { value, label }[], fullWidth —— select 动作接受 value 或 label',
+    FileInput: 'label, placeholder, accept —— type 动作写入文件名',
+    Tabs: 'value / defaultValue；Tabs.List 内放 Tabs.Tab，Tabs.Panel 放内容 —— select 动作切换标签',
+    'Tabs.Tab': 'value, leftSection（字符）',
+    'Accordion.Control': '可点击的标题（需要 id）',
+    Pagination: 'total, value / defaultValue —— select 动作写入页码',
+    PromptInput: 'placeholder —— AI 输入框，type 动作写入；发送按钮用 ActionIcon 或 Button',
+    'Terminal.Input': 'prompt（默认 "$"）, placeholder —— 终端里的输入行（需要 id），type 动作写入',
+};
+// ---------- 响应式（Mantine 默认断点，按舞台宽度取值） ----------
+/** Mantine 默认断点：36/48/62/75/88em，按 16px 换算。 */
+export const BREAKPOINTS = { xs: 576, sm: 768, md: 992, lg: 1200, xl: 1408 };
+const BP_KEYS = ['base', 'xs', 'sm', 'md', 'lg', 'xl'];
+/** 页面 viewport 对应的舞台尺寸。 */
+export const VIEWPORT_SIZE = { desktop: { width: 1280, height: 800 }, mobile: { width: 390, height: 844 } };
+/**
+ * 字幕区：画面下方、播放控制上方的一块固定高度区域，最多两行：一行本步说明（大字），一行 explain（小一号）。
+ * 演示页、发布站、renderStep 截图、导出图片与视频都把它放在舞台正下方，宽度与舞台（手机含外框）相同。
+ */
+export const SUBTITLE_HEIGHT = 84;
+/**
+ * 内置主题（D51）：每个主题是一个只写 CSS 变量（--jp-*）的样式表，CSS 在 web 包里（renderer/themes.ts）。
+ * 作者可以在项目根目录 themes/<name>.css 写自己的主题；与内置同名时用作者的。
+ */
+export const BUILTIN_THEMES = ['sketch', 'clean', 'blueprint', 'nord', 'dracula', 'solarized-light', 'terminal', 'kraft', 'contrast'];
+/** 主题名：字母开头，字母、数字、连字符、下划线（也是 themes/ 下的文件名）。 */
+export const THEME_NAME = /^[A-Za-z][\w-]*$/;
+/** 字幕的“字数”：中文（及其他全角字符）一个算 1，英文、数字、标点按 0.5 算；空白不算。check 用它提示说明与 explain 过长。 */
+export function captionLength(s) {
+    let n = 0;
+    for (const ch of s) {
+        if (/\s/.test(ch))
+            continue;
+        n += (ch.codePointAt(0) ?? 0) > 0x2e80 ? 1 : 0.5;
+    }
+    return n;
+}
+/** 说明 / explain 的建议上限（超过时 check 报 CAPTION_TOO_LONG / EXPLAIN_TOO_LONG）。 */
+export const CAPTION_MAX = 24;
+export const EXPLAIN_MAX = 48;
+/** 没有声明 layers 的方案：镜头作用在路径页面上，记为这个伪层级（不出现在层级栏）。作者的层级键不能以 @ 开头。 */
+export const PAGE_LAYER = '@page';
+/** shot()（不带 id）在有层级的方案里：作用于“当时导演所在的层”，让它回到整体。 */
+export const DIRECTOR_LAYER = '@director';
+/** Diagram.Node 的 kind 与 Node / Edge 的 state（D41）。 */
+export const DIAGRAM_NODE_KINDS = ['client', 'service', 'model', 'database', 'queue', 'storage', 'external', 'tool', 'user'];
+export const DIAGRAM_STATES = ['idle', 'active', 'ok', 'error', 'dim'];
+/** 子节点排版用的宽度：Phone 内部按手机宽度（响应式取值、visibleFrom / hiddenFrom、AppShell 收起都按它算），其余节点沿用外部宽度。 */
+export function childWidth(type, width) {
+    return type === 'Phone' ? VIEWPORT_SIZE.mobile.width : width;
+}
+/** 是否为响应式对象 `{ base, sm, md }`：普通对象，至少一个键，且全部键都是断点名。 */
+export function isResponsive(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const keys = Object.keys(v);
+    return keys.length > 0 && keys.every((k) => BP_KEYS.includes(k));
+}
+/** 按舞台宽度取响应式属性的值：取不超过宽度的最大断点；都不满足时取 base；非响应式值原样返回。 */
+export function atWidth(v, width) {
+    if (!isResponsive(v))
+        return v;
+    let out = undefined;
+    for (const k of BP_KEYS) {
+        if (!(k in v))
+            continue;
+        const min = k === 'base' ? 0 : BREAKPOINTS[k];
+        if (width >= min)
+            out = v[k];
+    }
+    return out;
+}
+/** 断点名、数字（px）或 `40em` / `600px` 字符串 → 像素；无法识别返回 null。 */
+export function breakpointPx(bp) {
+    if (typeof bp === 'number' && Number.isFinite(bp))
+        return bp;
+    if (typeof bp !== 'string')
+        return null;
+    if (bp in BREAKPOINTS)
+        return BREAKPOINTS[bp];
+    const m = /^(\d+(?:\.\d+)?)(px|em|rem)?$/.exec(bp.trim());
+    if (!m)
+        return null;
+    return m[2] === 'em' || m[2] === 'rem' ? Number(m[1]) * 16 : Number(m[1]);
+}
+/** visibleFrom / hiddenFrom：在给定舞台宽度下是否被隐藏。 */
+export function hiddenAtWidth(props, width) {
+    if (!props)
+        return false;
+    const from = breakpointPx(props.visibleFrom);
+    if (from !== null && width < from)
+        return true;
+    const until = breakpointPx(props.hiddenFrom);
+    if (until !== null && width >= until)
+        return true;
+    return false;
+}
+/** Mantine 的 data：string[]、{ value, label }[]，或分组 { group, items }[]。 */
+export function choicesFromData(data) {
+    if (!Array.isArray(data))
+        return [];
+    const out = [];
+    for (const d of data) {
+        if (typeof d === 'string' || typeof d === 'number')
+            out.push({ value: String(d), label: String(d) });
+        else if (d && typeof d === 'object') {
+            const o = d;
+            if (Array.isArray(o.items))
+                out.push(...choicesFromData(o.items));
+            else if (o.value !== undefined && o.value !== null)
+                out.push({ value: String(o.value), label: typeof o.label === 'string' ? o.label : String(o.value) });
+        }
+    }
+    return out;
+}
+/** 按 value 或 label 匹配一个选项。 */
+export function matchChoice(choices, v) {
+    return choices.find((c) => c.value === v) ?? choices.find((c) => c.label === v) ?? null;
+}
+// ---------- 标签 ----------
+const IS_BINDING = /^\$(?:ui|data|inputs)(?:\.|$)/;
+/** 元素的人类可读标签：优先 label/title/aria-label/placeholder 等属性（Mantine 输入组件直接带 label），其次子文本。 */
+export function nodeLabel(node) {
+    const p = node.props ?? {};
+    for (const k of ['label', 'title', 'aria-label', 'placeholder', 'name', 'kind', 'alt']) {
+        const v = p[k];
+        if (typeof v === 'string' && v && !IS_BINDING.test(v))
+            return v;
+    }
+    // 没有 label 的连线：「from → to」
+    if (node.type === 'Diagram.Edge' && typeof p.from === 'string' && typeof p.to === 'string')
+        return `${p.from} → ${p.to}`;
+    const text = collectText(node).trim();
+    return text || node.type;
+}
+function collectText(node) {
+    if (node.type === '#text') {
+        const t = node.props?.text;
+        return typeof t === 'string' && !IS_BINDING.test(t) ? t : '';
+    }
+    return (node.children ?? []).map(collectText).join('');
+}

package/dist/compile.d.ts

@@ -0,0 +1,32 @@
+import type { ConfigDef, FeatureDef, LayoutDef, OptionDef, PageDef } from '@joplo-app/kit';
+import { Project } from './schema.js';
+import type { Diagnostic } from './result.js';
+export type AuthoringProject = {
+    /** 项目根目录绝对路径，用于把源位置改成相对路径。 */
+    root: string;
+    config: ConfigDef & {
+        file: string;
+    };
+    layouts: Record<string, LayoutDef & {
+        file: string;
+    }>;
+    routes: Record<string, PageDef & {
+        file: string;
+    }>;
+    features: Record<string, {
+        def: FeatureDef & {
+            file: string;
+        };
+        options: Record<string, OptionDef & {
+            file: string;
+        }>;
+    }>;
+    /** 作者主题（D51）：themes/<name>.css 的原文。 */
+    themes?: Record<string, string>;
+};
+export type CompileResult = {
+    project: Project | null;
+    diagnostics: Diagnostic[];
+};
+export declare function compile(src: AuthoringProject, mode: 'dev' | 'publish'): CompileResult;
+export declare function relSource(root: string, s: string): string;