@tokenroll/joplo-kit 0.0.0-stage → 0.1.0

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/index.d.ts

@@ -0,0 +1,236 @@
+/**
+ * @tokenroll/joplo-kit：Agent 创作 Joplo 项目时调用的 SDK。
+ *
+ *   joplo.config.ts            config({...})
+ *   layouts/<id>.tsx           layout(<div>…<Outlet/>…</div>)
+ *   routes/<path>/page.tsx     page({ title }, <…/>)        文件夹路径 = 页面路径
+ *   features/<f>/feature.ts    feature({ name, goal, cases, rules, pick })
+ *   features/<f>/options/<o>.tsx  option({ name, idea, on, routes, state, scenarios })
+ *
+ * 所有函数只返回数据；画板不会执行这些代码，只消费编译出的 IR。
+ */
+import { type Bind, type CondExpr, type JNode } from './node.js';
+export { $, and, empty, eq, Fragment, neq, not, notEmpty, oneOf, or, Outlet, Slot } from './node.js';
+export type { Bind, CondExpr, JNode } from './node.js';
+type Json = string | number | boolean | null | Json[] | {
+    [k: string]: Json;
+};
+export type StateInit = {
+    ui?: Record<string, Json>;
+    data?: Record<string, Json>;
+    inputs?: Record<string, Json>;
+};
+export type ConfigDef = {
+    kind: 'config';
+    name: string;
+    description?: string;
+    theme?: 'sketch' | 'clean';
+    layout?: string;
+    home?: string;
+    source?: string;
+};
+export declare const config: (c: Omit<ConfigDef, "kind" | "source">) => ConfigDef;
+export type LayoutDef = {
+    kind: 'layout';
+    tree: JNode;
+    source?: string;
+};
+export declare const layout: (tree: JNode) => LayoutDef;
+export type PageDef = {
+    kind: 'page';
+    title: string;
+    layout?: string | false;
+    viewport?: 'desktop' | 'mobile';
+    tree: JNode;
+    source?: string;
+};
+export declare const page: (meta: {
+    title: string;
+    layout?: string | false;
+    viewport?: "desktop" | "mobile";
+}, tree: JNode) => PageDef;
+export type Dimension = 'main' | 'input' | 'permission' | 'lifecycle' | 'async' | 'interrupt' | 'conflict' | 'consistency';
+export type CaseDef = string | {
+    title: string;
+    dimension?: Dimension;
+    expected?: string;
+    priority?: 'high' | 'medium' | 'low';
+};
+export type Origin = 'user' | 'project_material' | 'ai_assumption' | 'code_observed' | 'feedback';
+export type RuleDef = {
+    kind: 'rule';
+    text: string;
+    origin: Origin;
+    status: 'pending' | 'confirmed' | 'conflict' | 'out_of_scope';
+    cases: string[];
+    elements: string[];
+    source?: string;
+};
+/** 规则。默认 origin 为 ai_assumption、status 为 pending：AI 补的规则不能自称已确认。 */
+export declare const rule: (text: string, opts?: {
+    origin?: Origin;
+    status?: RuleDef["status"];
+    cases?: string[];
+    elements?: string[];
+}) => RuleDef;
+export type QuestionDef = {
+    kind: 'question';
+    text: string;
+    severity: 'blocker' | 'major' | 'minor';
+    refs: string[];
+    source?: string;
+};
+/** 待决问题。 */
+export declare const question: (text: string, opts?: {
+    severity?: QuestionDef["severity"];
+    refs?: string[];
+}) => QuestionDef;
+export type FeatureDef = {
+    kind: 'feature';
+    name: string;
+    goal: string;
+    roles?: string[];
+    constraints?: Record<string, string | {
+        text: string;
+        hard?: boolean;
+    }>;
+    cases: Record<string, CaseDef>;
+    rules?: Record<string, RuleDef>;
+    questions?: Record<string, QuestionDef>;
+    /** 选定的方案（options/ 下的文件名）；build 只发布它。 */
+    pick?: string | null;
+    source?: string;
+};
+export declare const feature: (f: Omit<FeatureDef, "kind" | "source">) => FeatureDef;
+export type CoverageDecl = {
+    kind: 'coverage';
+    status: 'undecided' | 'missing' | 'not_applicable' | 'excluded';
+    reason?: string;
+};
+export declare const undecided: (reason: string) => CoverageDecl;
+export declare const missing: (reason?: string) => CoverageDecl;
+export declare const notApplicable: (reason: string) => CoverageDecl;
+export declare const excluded: (reason: string) => CoverageDecl;
+export type EffectDef = {
+    kind: 'effect';
+    type: 'set';
+    path: string;
+    value: Json;
+} | {
+    kind: 'effect';
+    type: 'append';
+    path: string;
+    value: Json;
+} | {
+    kind: 'effect';
+    type: 'toast';
+    text: string;
+    tone: 'success' | 'error' | 'info';
+} | {
+    kind: 'effect';
+    type: 'go';
+    route: string;
+} | {
+    kind: 'effect';
+    type: 'complete';
+    text: string;
+    outcome: 'success' | 'failure' | 'cancelled';
+} | {
+    kind: 'effect';
+    type: 'uses';
+    rules: string[];
+};
+export declare const set: (target: Bind, value: Json) => EffectDef;
+export declare const push: (target: Bind, value: Json) => EffectDef;
+/** 与 sonner 一致：toast('…')、toast.success('…')、toast.error('…')。 */
+export declare const toast: ((text: string) => EffectDef) & {
+    success: (text: string) => EffectDef;
+    error: (text: string) => EffectDef;
+    info: (text: string) => EffectDef;
+};
+/** 跳转到另一个路径。 */
+export declare const go: (route: string) => EffectDef;
+/** 场景结束。 */
+export declare const done: (text: string, outcome?: "success" | "failure" | "cancelled") => EffectDef;
+/** 这一步依据哪些规则（option 或 feature 中的规则键）。 */
+export declare const uses: (...rules: string[]) => EffectDef;
+/** 步骤参数：字符串是字幕（可省略，省略时自动生成），其余是效果。 */
+export type StepArg = string | EffectDef;
+export type StepDef = {
+    kind: 'user' | 'system';
+    action: {
+        type: 'click';
+        target: string;
+    } | {
+        type: 'type';
+        target: string;
+        value: string;
+    } | {
+        type: 'select';
+        target: string;
+        value: string;
+    } | {
+        type: 'toggle';
+        target: string;
+        value: boolean;
+    } | {
+        type: 'back';
+    } | {
+        type: 'event';
+        name: string;
+    };
+    caption?: string;
+    effects: EffectDef[];
+    source?: string;
+};
+export type FlowOpts = {
+    /** 覆盖的情况（feature.cases 的键）。 */
+    cases?: string[];
+    /** 模拟结果标签，例如“模拟失败”。缺省按 outcome 生成。 */
+    mock?: string;
+    outcome?: 'success' | 'failure' | 'denied' | 'other';
+    /** 起始路径；缺省为方案 on/routes 中的第一个路径。 */
+    start?: string;
+    /** 在 option.state 之上覆盖的初始状态。 */
+    state?: StateInit;
+    description?: string;
+    expected?: string;
+};
+export declare class Flow {
+    readonly name: string;
+    readonly opts: FlowOpts;
+    readonly kind = "flow";
+    readonly steps: StepDef[];
+    readonly source: string | undefined;
+    constructor(name: string, opts: FlowOpts);
+    private add;
+    click(target: string, ...args: StepArg[]): this;
+    type(target: string, value: string, ...args: StepArg[]): this;
+    select(target: string, value: string, ...args: StepArg[]): this;
+    toggle(target: string, value: boolean, ...args: StepArg[]): this;
+    back(...args: StepArg[]): this;
+    /** 系统事件，例如“请求成功（模拟）”。 */
+    system(name: string, ...args: StepArg[]): this;
+}
+/** 一条演示路径。 */
+export declare const flow: (name: string, opts?: FlowOpts) => Flow;
+export type OptionDef = {
+    kind: 'option';
+    name: string;
+    idea: string;
+    /** 这个方案主要改变了哪项设计决策。 */
+    focus?: string;
+    tradeoffs?: string[];
+    /** 堆叠到已有路径：{ '/members': { 'header.actions': <Button/>, overlay: <Dialog/> } } */
+    on?: Record<string, Record<string, JNode | JNode[]>>;
+    /** 本方案新增的路径。 */
+    routes?: Record<string, PageDef>;
+    state?: StateInit;
+    rules?: Record<string, RuleDef>;
+    questions?: Record<string, QuestionDef>;
+    coverage?: Record<string, CoverageDecl>;
+    scenarios: Record<string, Flow>;
+    source?: string;
+};
+export declare const option: (o: Omit<OptionDef, "kind" | "source">) => OptionDef;
+export type { CondExpr as Condition };

package/dist/index.js

@@ -0,0 +1,99 @@
+/**
+ * @tokenroll/joplo-kit：Agent 创作 Joplo 项目时调用的 SDK。
+ *
+ *   joplo.config.ts            config({...})
+ *   layouts/<id>.tsx           layout(<div>…<Outlet/>…</div>)
+ *   routes/<path>/page.tsx     page({ title }, <…/>)        文件夹路径 = 页面路径
+ *   features/<f>/feature.ts    feature({ name, goal, cases, rules, pick })
+ *   features/<f>/options/<o>.tsx  option({ name, idea, on, routes, state, scenarios })
+ *
+ * 所有函数只返回数据；画板不会执行这些代码，只消费编译出的 IR。
+ */
+import { bindPath, callsite, isBind } from "./node.js";
+export { $, and, empty, eq, Fragment, neq, not, notEmpty, oneOf, or, Outlet, Slot } from "./node.js";
+export const config = (c) => ({ kind: 'config', ...c, source: callsite() });
+export const layout = (tree) => ({ kind: 'layout', tree, source: callsite() });
+export const page = (meta, tree) => ({
+    kind: 'page',
+    ...meta,
+    tree,
+    source: callsite(),
+});
+/** 规则。默认 origin 为 ai_assumption、status 为 pending：AI 补的规则不能自称已确认。 */
+export const rule = (text, opts = {}) => ({
+    kind: 'rule',
+    text,
+    origin: opts.origin ?? 'ai_assumption',
+    status: opts.status ?? 'pending',
+    cases: opts.cases ?? [],
+    elements: opts.elements ?? [],
+    source: callsite(),
+});
+/** 待决问题。 */
+export const question = (text, opts = {}) => ({
+    kind: 'question',
+    text,
+    severity: opts.severity ?? 'major',
+    refs: opts.refs ?? [],
+    source: callsite(),
+});
+export const feature = (f) => ({ kind: 'feature', ...f, source: callsite() });
+export const undecided = (reason) => ({ kind: 'coverage', status: 'undecided', reason });
+export const missing = (reason) => ({ kind: 'coverage', status: 'missing', ...(reason ? { reason } : {}) });
+export const notApplicable = (reason) => ({ kind: 'coverage', status: 'not_applicable', reason });
+export const excluded = (reason) => ({ kind: 'coverage', status: 'excluded', reason });
+const pathOf = (b) => (isBind(b) ? bindPath(b) : b);
+export const set = (target, value) => ({ kind: 'effect', type: 'set', path: pathOf(target), value });
+export const push = (target, value) => ({ kind: 'effect', type: 'append', path: pathOf(target), value });
+/** 与 sonner 一致：toast('…')、toast.success('…')、toast.error('…')。 */
+export const toast = Object.assign((text) => ({ kind: 'effect', type: 'toast', text, tone: 'info' }), {
+    success: (text) => ({ kind: 'effect', type: 'toast', text, tone: 'success' }),
+    error: (text) => ({ kind: 'effect', type: 'toast', text, tone: 'error' }),
+    info: (text) => ({ kind: 'effect', type: 'toast', text, tone: 'info' }),
+});
+/** 跳转到另一个路径。 */
+export const go = (route) => ({ kind: 'effect', type: 'go', route });
+/** 场景结束。 */
+export const done = (text, outcome = 'success') => ({ kind: 'effect', type: 'complete', text, outcome });
+/** 这一步依据哪些规则（option 或 feature 中的规则键）。 */
+export const uses = (...rules) => ({ kind: 'effect', type: 'uses', rules });
+export class Flow {
+    name;
+    opts;
+    kind = 'flow';
+    steps = [];
+    source;
+    constructor(name, opts) {
+        this.name = name;
+        this.opts = opts;
+        this.source = callsite(4);
+    }
+    add(kind, action, args) {
+        const caption = args.find((a) => typeof a === 'string');
+        const effects = args.filter((a) => typeof a !== 'string');
+        this.steps.push({ kind, action, ...(caption ? { caption } : {}), effects, source: callsite(4) });
+        return this;
+    }
+    click(target, ...args) {
+        return this.add('user', { type: 'click', target }, args);
+    }
+    type(target, value, ...args) {
+        return this.add('user', { type: 'type', target, value }, args);
+    }
+    select(target, value, ...args) {
+        return this.add('user', { type: 'select', target, value }, args);
+    }
+    toggle(target, value, ...args) {
+        return this.add('user', { type: 'toggle', target, value }, args);
+    }
+    back(...args) {
+        return this.add('user', { type: 'back' }, args);
+    }
+    /** 系统事件，例如“请求成功（模拟）”。 */
+    system(name, ...args) {
+        return this.add('system', { type: 'event', name }, args);
+    }
+}
+/** 一条演示路径。 */
+export const flow = (name, opts = {}) => new Flow(name, opts);
+export const option = (o) => ({ kind: 'option', ...o, source: callsite() });

package/dist/jsx-dev-runtime.d.ts

@@ -0,0 +1,9 @@
+import { Fragment, type JNode } from './node.js';
+export { Fragment };
+export type { JSX } from './jsx-runtime.js';
+/** 开发模式：esbuild/Vite 会传入源位置，用于“选中元素 → 文件:行号”。 */
+export declare function jsxDEV(type: unknown, props: Record<string, unknown> | null, _key?: unknown, _isStatic?: boolean, source?: {
+    fileName?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}): JNode;

package/dist/jsx-dev-runtime.js

@@ -0,0 +1,6 @@
+import { createNode, Fragment } from "./node.js";
+export { Fragment };
+/** 开发模式：esbuild/Vite 会传入源位置，用于“选中元素 → 文件:行号”。 */
+export function jsxDEV(type, props, _key, _isStatic, source) {
+    return createNode(type, props, source);
+}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,13 @@
+import { Fragment, type JNode } from './node.js';
+export { Fragment };
+export declare const jsx: (type: unknown, props: Record<string, unknown> | null) => JNode;
+export declare const jsxs: (type: unknown, props: Record<string, unknown> | null) => JNode;
+export declare namespace JSX {
+    type Element = JNode;
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+    interface IntrinsicElements {
+        [tag: string]: Record<string, unknown>;
+    }
+}

package/dist/jsx-runtime.js

@@ -0,0 +1,4 @@
+import { createNode, Fragment } from "./node.js";
+export { Fragment };
+export const jsx = (type, props) => createNode(type, props);
+export const jsxs = jsx;

package/dist/node.d.ts

@@ -0,0 +1,64 @@
+/**
+ * JSX 收集：`<Button id="x">文字</Button>` 在这里变成普通数据（JNode），不会作为 React 执行。
+ * 作者自己写的函数组件（例如复用的页面骨架）会在收集时直接调用，展开成 JNode。
+ */
+export declare const NODE: unique symbol;
+export declare const COMPONENT: unique symbol;
+export declare const BIND: unique symbol;
+export type Bind = {
+    readonly [BIND]: string;
+};
+export type CondExpr = {
+    readonly $cond: unknown;
+};
+export type JNode = {
+    readonly [NODE]: true;
+    type: string;
+    props: Record<string, unknown>;
+    children: JChild[];
+    /** jsxDEV 提供的源位置（绝对路径:行:列），编译器会改成项目相对路径。 */
+    source?: string;
+};
+export type JChild = JNode | string | number | boolean | null | undefined | Bind | JChild[];
+/** 目录组件的标记函数。 */
+export type ComponentMarker = ((props: Record<string, unknown>) => never) & {
+    readonly [COMPONENT]: string;
+};
+export declare function component(name: string): ComponentMarker;
+export declare const isNode: (v: unknown) => v is JNode;
+export declare const isBind: (v: unknown) => v is Bind;
+export declare const bindPath: (b: Bind) => string;
+export declare const Fragment: ComponentMarker;
+/** 布局或页面中的插槽：方案把元素堆叠到这里。 */
+export declare const Slot: (props: {
+    name: string;
+}) => JNode;
+/** 布局中页面内容的位置。 */
+export declare const Outlet: (props: Record<string, never>) => JNode;
+type Source = {
+    fileName?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+} | undefined;
+export declare function createNode(type: unknown, rawProps: Record<string, unknown> | null, source?: Source): JNode;
+/** 状态引用：`$.ui.inviteOpen`、`$.data.members`、`$.inputs.in_email`。 */
+export declare const $: {
+    ui: Record<string, any>;
+    data: Record<string, any>;
+    inputs: Record<string, any>;
+};
+type Operand = Bind | CondExpr;
+export declare const not: (x: Operand) => CondExpr;
+export declare const eq: (b: Bind, v: unknown) => CondExpr;
+export declare const neq: (b: Bind, v: unknown) => CondExpr;
+export declare const empty: (b: Bind) => CondExpr;
+export declare const notEmpty: (b: Bind) => CondExpr;
+export declare const oneOf: (b: Bind, values: unknown[]) => CondExpr;
+export declare const and: (...xs: Operand[]) => CondExpr;
+export declare const or: (...xs: Operand[]) => CondExpr;
+export declare const isCond: (v: unknown) => v is CondExpr;
+/** 把 Bind 或条件表达式转成 IR 条件。 */
+export declare const toCondition: (x: unknown) => unknown;
+/** 取调用者位置，用于给 feature/option/flow 步骤记录源位置。 */
+export declare function callsite(depth?: number): string | undefined;
+export {};

package/dist/node.js

@@ -0,0 +1,99 @@
+/**
+ * JSX 收集：`<Button id="x">文字</Button>` 在这里变成普通数据（JNode），不会作为 React 执行。
+ * 作者自己写的函数组件（例如复用的页面骨架）会在收集时直接调用，展开成 JNode。
+ */
+export const NODE = Symbol.for('joplo.node');
+export const COMPONENT = Symbol.for('joplo.component');
+export const BIND = Symbol.for('joplo.bind');
+export function component(name) {
+    const fn = (() => {
+        throw new Error(`${name} 是 Joplo 组件标记，只能在 JSX 中使用`);
+    });
+    Object.defineProperty(fn, COMPONENT, { value: name });
+    Object.defineProperty(fn, 'displayName', { value: name });
+    return fn;
+}
+export const isNode = (v) => typeof v === 'object' && v !== null && v[NODE] === true;
+export const isBind = (v) => (typeof v === 'object' || typeof v === 'function') && v !== null && typeof v[BIND] === 'string';
+export const bindPath = (b) => b[BIND];
+export const Fragment = component('#fragment');
+/** 布局或页面中的插槽：方案把元素堆叠到这里。 */
+export const Slot = component('#slot');
+/** 布局中页面内容的位置。 */
+export const Outlet = component('#outlet');
+export function createNode(type, rawProps, source) {
+    const props = { ...(rawProps ?? {}) };
+    const children = props.children;
+    delete props.children;
+    const src = source?.fileName ? `${source.fileName}:${source.lineNumber ?? 0}:${source.columnNumber ?? 0}` : undefined;
+    if (typeof type === 'string')
+        return mk(type, props, children, src);
+    if (typeof type === 'function') {
+        const name = type[COMPONENT];
+        if (name)
+            return mk(name, props, children, src);
+        // 作者自定义的函数组件：收集时展开
+        const out = type({ ...props, children });
+        if (isNode(out)) {
+            if (!out.source && src)
+                out.source = src;
+            return out;
+        }
+        return mk('#fragment', {}, out, src);
+    }
+    throw new Error(`不支持的 JSX 类型：${String(type)}`);
+}
+function mk(type, props, children, source) {
+    const node = { [NODE]: true, type, props, children: children === undefined ? [] : Array.isArray(children) ? children : [children] };
+    if (source)
+        node.source = source;
+    return node;
+}
+// ---------- 状态绑定 $ ----------
+function makeBind(path) {
+    const target = function () { };
+    return new Proxy(target, {
+        get(_t, prop) {
+            if (prop === BIND)
+                return path;
+            if (prop === Symbol.toPrimitive)
+                return () => `$${path}`;
+            if (prop === 'toString' || prop === 'valueOf')
+                return () => `$${path}`;
+            if (typeof prop === 'symbol')
+                return undefined;
+            return makeBind(`${path}.${prop}`);
+        },
+        has(_t, prop) {
+            return prop === BIND;
+        },
+    });
+}
+/** 状态引用：`$.ui.inviteOpen`、`$.data.members`、`$.inputs.in_email`。 */
+export const $ = {
+    ui: makeBind('ui'),
+    data: makeBind('data'),
+    inputs: makeBind('inputs'),
+};
+const cond = (c) => ({ $cond: c });
+const asCond = (x) => (isBind(x) ? { truthy: bindPath(x) } : x.$cond);
+export const not = (x) => cond(isBind(x) ? { falsy: bindPath(x) } : { not: asCond(x) });
+export const eq = (b, v) => cond({ eq: [bindPath(b), v] });
+export const neq = (b, v) => cond({ neq: [bindPath(b), v] });
+export const empty = (b) => cond({ empty: bindPath(b) });
+export const notEmpty = (b) => cond({ notEmpty: bindPath(b) });
+export const oneOf = (b, values) => cond({ in: [bindPath(b), values] });
+export const and = (...xs) => cond({ and: xs.map(asCond) });
+export const or = (...xs) => cond({ or: xs.map(asCond) });
+export const isCond = (v) => typeof v === 'object' && v !== null && '$cond' in v;
+/** 把 Bind 或条件表达式转成 IR 条件。 */
+export const toCondition = (x) => (isBind(x) ? { truthy: bindPath(x) } : isCond(x) ? x.$cond : x);
+/** 取调用者位置，用于给 feature/option/flow 步骤记录源位置。 */
+export function callsite(depth = 3) {
+    const line = new Error().stack?.split('\n')[depth];
+    const m = line && /\(?((?:file:\/\/)?[^()\s]+?):(\d+):(\d+)\)?\s*$/.exec(line);
+    if (!m)
+        return undefined;
+    const file = decodeURIComponent(m[1].replace(/^file:\/\//, '').replace(/\?.*$/, ''));
+    return `${file}:${m[2]}:${m[3]}`;
+}

package/dist/ui.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 原型组件：名称与属性对齐 Mantine（数据表对齐 mantine-datatable），复合组件用点语法（AppShell.Header、Tabs.Tab）。
+ * 布局写成属性：<Stack gap="md">、<Group justify="space-between">、<SimpleGrid cols={{ base: 1, md: 3 }}>，
+ * 不需要 className；响应式对象与 visibleFrom / hiddenFrom 按舞台宽度生效。
+ *
+ * 另可加 Joplo 属性：id（可操作元素必填）、when（可见条件）、disabled（布尔或条件）、disabledReason、unmodeled、note。
+ * 行为（点击后发生什么）不写在组件上，写在 option 的 flow 步骤里。浮层用 Modal / Drawer 的 opened={$.ui.x} 控制。
+ *
+ * 组件清单与 @tokenroll/joplo-core 的 COMPONENT_TYPES 一一对应（core/test/catalog.test.ts 检查）。
+ */
+import { type Bind, type CondExpr, type JChild } from './node.js';
+type Responsive<T> = T | {
+    base?: T;
+    xs?: T;
+    sm?: T;
+    md?: T;
+    lg?: T;
+    xl?: T;
+};
+type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type JoploProps = {
+    id?: string;
+    when?: Bind | CondExpr;
+    disabled?: boolean | Bind | CondExpr;
+    disabledReason?: string;
+    unmodeled?: boolean;
+    note?: string;
+    visibleFrom?: Size;
+    hiddenFrom?: Size;
+    /** 逃生口：Tailwind 类名。优先使用布局组件与样式属性。 */
+    className?: string;
+    children?: JChild;
+    [prop: string]: unknown;
+};
+export type { Responsive };
+type C = (props: JoploProps) => any;
+export declare const AppShell: C & {
+    Header: C;
+    Navbar: C;
+    Main: C;
+    Aside: C;
+    Footer: C;
+};
+export declare const Container: C;
+export declare const Stack: C;
+export declare const Group: C;
+export declare const Flex: C;
+export declare const Grid: C & {
+    Col: C;
+};
+export declare const SimpleGrid: C;
+export declare const Center: C;
+export declare const Box: C;
+export declare const Space: C;
+export declare const Paper: C;
+export declare const Card: C & {
+    Section: C;
+};
+export declare const Divider: C;
+export declare const ScrollArea: C;
+export declare const Title: C;
+export declare const Text: C;
+export declare const Code: C;
+export declare const Kbd: C;
+export declare const Blockquote: C;
+export declare const List: C & {
+    Item: C;
+};
+export declare const Badge: C;
+export declare const Avatar: C;
+export declare const Image: C;
+export declare const ThemeIcon: C;
+export declare const Indicator: C;
+export declare const Timeline: C & {
+    Item: C;
+};
+export declare const Table: C & {
+    Thead: C;
+    Tbody: C;
+    Tr: C;
+    Th: C;
+    Td: C;
+};
+export declare const DataTable: C;
+export declare const Accordion: C & {
+    Item: C;
+    Control: C;
+    Panel: C;
+};
+export declare const Button: C;
+export declare const ActionIcon: C;
+export declare const CloseButton: C;
+export declare const TextInput: C;
+export declare const PasswordInput: C;
+export declare const NumberInput: C;
+export declare const Textarea: C;
+export declare const Select: C;
+export declare const MultiSelect: C;
+export declare const Checkbox: C;
+export declare const Radio: C & {
+    Group: C;
+};
+export declare const Switch: C;
+export declare const SegmentedControl: C;
+export declare const FileInput: C;
+export declare const Anchor: C;
+export declare const NavLink: C;
+export declare const Tabs: C & {
+    List: C;
+    Tab: C;
+    Panel: C;
+};
+export declare const Breadcrumbs: C;
+export declare const Pagination: C;
+export declare const Stepper: C & {
+    Step: C;
+};
+export declare const Burger: C;
+export declare const Alert: C;
+export declare const Loader: C;
+export declare const Progress: C;
+export declare const RingProgress: C;
+export declare const Skeleton: C;
+export declare const Notification: C;
+export declare const Modal: C;
+export declare const Drawer: C;
+export declare const ChatMessage: C;
+export declare const ToolCall: C;
+export declare const PromptInput: C;
+export declare const Placeholder: C;
+export declare const Custom: C;

package/dist/ui.js

@@ -0,0 +1,98 @@
+/**
+ * 原型组件：名称与属性对齐 Mantine（数据表对齐 mantine-datatable），复合组件用点语法（AppShell.Header、Tabs.Tab）。
+ * 布局写成属性：<Stack gap="md">、<Group justify="space-between">、<SimpleGrid cols={{ base: 1, md: 3 }}>，
+ * 不需要 className；响应式对象与 visibleFrom / hiddenFrom 按舞台宽度生效。
+ *
+ * 另可加 Joplo 属性：id（可操作元素必填）、when（可见条件）、disabled（布尔或条件）、disabledReason、unmodeled、note。
+ * 行为（点击后发生什么）不写在组件上，写在 option 的 flow 步骤里。浮层用 Modal / Drawer 的 opened={$.ui.x} 控制。
+ *
+ * 组件清单与 @tokenroll/joplo-core 的 COMPONENT_TYPES 一一对应（core/test/catalog.test.ts 检查）。
+ */
+import { component } from "./node.js";
+const c = (name) => component(name);
+// ---------- 布局 ----------
+export const AppShell = Object.assign(c('AppShell'), {
+    Header: c('AppShell.Header'),
+    Navbar: c('AppShell.Navbar'),
+    Main: c('AppShell.Main'),
+    Aside: c('AppShell.Aside'),
+    Footer: c('AppShell.Footer'),
+});
+export const Container = c('Container');
+export const Stack = c('Stack');
+export const Group = c('Group');
+export const Flex = c('Flex');
+export const Grid = Object.assign(c('Grid'), { Col: c('Grid.Col') });
+export const SimpleGrid = c('SimpleGrid');
+export const Center = c('Center');
+export const Box = c('Box');
+export const Space = c('Space');
+export const Paper = c('Paper');
+export const Card = Object.assign(c('Card'), { Section: c('Card.Section') });
+export const Divider = c('Divider');
+export const ScrollArea = c('ScrollArea');
+// ---------- 文字与展示 ----------
+export const Title = c('Title');
+export const Text = c('Text');
+export const Code = c('Code');
+export const Kbd = c('Kbd');
+export const Blockquote = c('Blockquote');
+export const List = Object.assign(c('List'), { Item: c('List.Item') });
+export const Badge = c('Badge');
+export const Avatar = c('Avatar');
+export const Image = c('Image');
+export const ThemeIcon = c('ThemeIcon');
+export const Indicator = c('Indicator');
+export const Timeline = Object.assign(c('Timeline'), { Item: c('Timeline.Item') });
+export const Table = Object.assign(c('Table'), {
+    Thead: c('Table.Thead'),
+    Tbody: c('Table.Tbody'),
+    Tr: c('Table.Tr'),
+    Th: c('Table.Th'),
+    Td: c('Table.Td'),
+});
+export const DataTable = c('DataTable');
+export const Accordion = Object.assign(c('Accordion'), {
+    Item: c('Accordion.Item'),
+    Control: c('Accordion.Control'),
+    Panel: c('Accordion.Panel'),
+});
+// ---------- 输入 ----------
+export const Button = c('Button');
+export const ActionIcon = c('ActionIcon');
+export const CloseButton = c('CloseButton');
+export const TextInput = c('TextInput');
+export const PasswordInput = c('PasswordInput');
+export const NumberInput = c('NumberInput');
+export const Textarea = c('Textarea');
+export const Select = c('Select');
+export const MultiSelect = c('MultiSelect');
+export const Checkbox = c('Checkbox');
+export const Radio = Object.assign(c('Radio'), { Group: c('Radio.Group') });
+export const Switch = c('Switch');
+export const SegmentedControl = c('SegmentedControl');
+export const FileInput = c('FileInput');
+// ---------- 导航 ----------
+export const Anchor = c('Anchor');
+export const NavLink = c('NavLink');
+export const Tabs = Object.assign(c('Tabs'), { List: c('Tabs.List'), Tab: c('Tabs.Tab'), Panel: c('Tabs.Panel') });
+export const Breadcrumbs = c('Breadcrumbs');
+export const Pagination = c('Pagination');
+export const Stepper = Object.assign(c('Stepper'), { Step: c('Stepper.Step') });
+export const Burger = c('Burger');
+// ---------- 反馈与浮层 ----------
+export const Alert = c('Alert');
+export const Loader = c('Loader');
+export const Progress = c('Progress');
+export const RingProgress = c('RingProgress');
+export const Skeleton = c('Skeleton');
+export const Notification = c('Notification');
+export const Modal = c('Modal');
+export const Drawer = c('Drawer');
+// ---------- AI 交互（Joplo 自有） ----------
+export const ChatMessage = c('ChatMessage');
+export const ToolCall = c('ToolCall');
+export const PromptInput = c('PromptInput');
+// ---------- Joplo ----------
+export const Placeholder = c('Placeholder');
+export const Custom = c('Custom');

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@tokenroll/joplo-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Joplo 创作 SDK：组件、feature/option/flow 与 JSX 运行时（收集成数据，不作为 React 执行）",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "default": "./dist/ui.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "default": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "default": "./dist/jsx-dev-runtime.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TokenRollAI/Joplo.git",
+    "directory": "packages/kit"
+  },
+  "homepage": "https://github.com/TokenRollAI/Joplo#readme",
+  "bugs": {
+    "url": "https://github.com/TokenRollAI/Joplo/issues"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.