@chatu-ai/builder-sdk-vue 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chatu-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @chatu-ai/builder-sdk-vue
+
+Vue 3 composables for [`@chatu-ai/builder-sdk`](https://www.npmjs.com/package/@chatu-ai/builder-sdk).
+
+```ts
+import { useSandboxStatus, usePreviewUrl, useBuilderChat } from '@chatu-ai/builder-sdk-vue'
+
+const { state, refresh } = useSandboxStatus(client, conversationId)   // adaptive polling + heartbeat
+const { url } = usePreviewUrl(client, conversationId)                  // one-time preview token → iframe src
+```
+
+Peer dependency: `vue ^3.4`. MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { useBuilderChat } from './useBuilderChat';
+export { useSandboxStatus, type SandboxStatusOptions } from './useSandboxStatus';
+export { usePreviewUrl } from './usePreviewUrl';
+export { createInitialState, reduceEvent, type BuilderUiState, type RoundUi, type TaskCardUi, } from './reducer';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { useBuilderChat } from './useBuilderChat';
+export { useSandboxStatus } from './useSandboxStatus';
+export { usePreviewUrl } from './usePreviewUrl';
+export { createInitialState, reduceEvent, } from './reducer';

package/dist/reducer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 事件 → UI 状态归约（08 §3 规则的纯函数实现，框架无关、可独立测试）
+ * vue 层只做响应式包装。
+ */
+import type { BuilderEvent, SandboxState } from '@chatu-ai/builder-sdk';
+export interface TaskCardUi {
+    id: string;
+    label: string;
+    state: 'running' | 'done' | 'failed';
+    detail?: string;
+}
+export interface RoundUi {
+    xid: string;
+    /** 本轮用户输入（由 useBuilderChat.send 写入，事件流本身不含） */
+    userText?: string;
+    text: string;
+    taskCards: TaskCardUi[];
+    version?: {
+        sha: string;
+        message: string;
+        filesChanged: number;
+    };
+    done?: {
+        state: 'completed' | 'failed' | 'canceled';
+        error?: string;
+    };
+}
+export interface BuilderUiState {
+    agentState: 'idle' | 'streaming' | 'error';
+    rounds: RoundUi[];
+    sandbox: {
+        state: SandboxState | 'unknown';
+        previewUrl?: string;
+        lastError?: string | null;
+    };
+    changedPaths: string[];
+    versions: {
+        sha: string;
+        message: string;
+        filesChanged: number;
+    }[];
+    lastSeq: number;
+}
+export declare function createInitialState(): BuilderUiState;
+/** 就地归约（调用方负责传入响应式对象；seq 去重已由 core 保证） */
+export declare function reduceEvent(state: BuilderUiState, ev: BuilderEvent): void;

package/dist/reducer.js

@@ -0,0 +1,69 @@
+export function createInitialState() {
+    return {
+        agentState: 'idle',
+        rounds: [],
+        sandbox: { state: 'unknown' },
+        changedPaths: [],
+        versions: [],
+        lastSeq: 0,
+    };
+}
+function roundFor(state, xid) {
+    let round = state.rounds.find(r => r.xid === xid);
+    if (!round) {
+        round = { xid, text: '', taskCards: [] };
+        state.rounds.push(round);
+    }
+    return round;
+}
+/** 就地归约（调用方负责传入响应式对象；seq 去重已由 core 保证） */
+export function reduceEvent(state, ev) {
+    if (ev.kind !== 'ack')
+        state.lastSeq = ev.seq;
+    switch (ev.kind) {
+        case 'ack':
+            state.agentState = 'streaming';
+            state.sandbox = { state: ev.sandbox.state, previewUrl: ev.sandbox.previewUrl };
+            roundFor(state, ev.xid);
+            break;
+        case 'message':
+            roundFor(state, ev.xid).text += ev.text;
+            break;
+        case 'taskCard': {
+            const cards = roundFor(state, ev.xid).taskCards;
+            const existing = cards.find(c => c.id === ev.id);
+            if (existing) {
+                existing.state = ev.state;
+                if (ev.label)
+                    existing.label = ev.label; // 空 label = 仅状态更新（agent3 tool_result）
+                if (ev.detail !== undefined)
+                    existing.detail = ev.detail;
+            }
+            else {
+                cards.push({ id: ev.id, label: ev.label, state: ev.state, detail: ev.detail });
+            }
+            break;
+        }
+        case 'fileDiff':
+            if (!state.changedPaths.includes(ev.path))
+                state.changedPaths.push(ev.path);
+            break;
+        case 'preview':
+            state.sandbox = {
+                state: ev.state === 'ready' ? 'ready' : state.sandbox.state,
+                previewUrl: ev.url ?? state.sandbox.previewUrl,
+                lastError: ev.state === 'crashed' ? (ev.error ?? 'dev server crashed') : null,
+            };
+            break;
+        case 'version': {
+            const version = { sha: ev.sha, message: ev.message, filesChanged: ev.filesChanged };
+            roundFor(state, ev.xid).version = version;
+            state.versions.unshift(version);
+            break;
+        }
+        case 'done':
+            roundFor(state, ev.xid).done = { state: ev.state, error: ev.error };
+            state.agentState = ev.state === 'completed' ? 'idle' : 'error';
+            break;
+    }
+}

package/dist/useBuilderChat.d.ts

@@ -0,0 +1,47 @@
+import type { BuilderClient } from '@chatu-ai/builder-sdk';
+/**
+ * Builder 会话组合式 API（08 §1/§3）
+ * 流式消费 client.chat.stream（core 已保证有序无重与断线重连），就地归约到响应式状态。
+ */
+export declare function useBuilderChat(client: BuilderClient, conversationId: string): {
+    state: {
+        readonly agentState: "idle" | "streaming" | "error";
+        readonly rounds: readonly {
+            readonly xid: string;
+            readonly userText?: string | undefined;
+            readonly text: string;
+            readonly taskCards: readonly {
+                readonly id: string;
+                readonly label: string;
+                readonly state: "running" | "done" | "failed";
+                readonly detail?: string | undefined;
+            }[];
+            readonly version?: {
+                readonly sha: string;
+                readonly message: string;
+                readonly filesChanged: number;
+            } | undefined;
+            readonly done?: {
+                readonly state: "completed" | "failed" | "canceled";
+                readonly error?: string | undefined;
+            } | undefined;
+        }[];
+        readonly sandbox: {
+            readonly state: import("@chatu-ai/builder-sdk").SandboxState | "unknown";
+            readonly previewUrl?: string | undefined;
+            readonly lastError?: string | null | undefined;
+        };
+        readonly changedPaths: readonly string[];
+        readonly versions: readonly {
+            readonly sha: string;
+            readonly message: string;
+            readonly filesChanged: number;
+        }[];
+        readonly lastSeq: number;
+    };
+    streamError: Readonly<import("vue").Ref<string | null, string | null>>;
+    isStreaming: import("vue").ComputedRef<boolean>;
+    send: (prompt: string) => Promise<void>;
+    cancel: () => Promise<void>;
+    refreshVersions: () => Promise<void>;
+};

package/dist/useBuilderChat.js

@@ -0,0 +1,78 @@
+import { computed, reactive, readonly, ref } from 'vue';
+import { createInitialState, reduceEvent } from './reducer';
+/**
+ * Builder 会话组合式 API（08 §1/§3）
+ * 流式消费 client.chat.stream（core 已保证有序无重与断线重连），就地归约到响应式状态。
+ */
+export function useBuilderChat(client, conversationId) {
+    const state = reactive(createInitialState());
+    const streamError = ref(null);
+    let activeXid = null;
+    async function send(prompt) {
+        if (state.agentState === 'streaming') {
+            throw new Error('BUSY: a generation is already in progress (R11)');
+        }
+        state.agentState = 'streaming';
+        streamError.value = null;
+        try {
+            let pending = true;
+            for await (const ev of client.chat.stream(conversationId, prompt)) {
+                if (ev.kind === 'ack')
+                    activeXid = ev.xid;
+                reduceEvent(state, ev);
+                // 首个带真实 xid 的事件到达后，把用户输入挂到本轮
+                if (pending && ev.xid && ev.xid !== 'pending') {
+                    const round = state.rounds.find(r => r.xid === ev.xid);
+                    if (round) {
+                        round.userText = prompt;
+                        pending = false;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            state.agentState = 'error';
+            streamError.value = String(err);
+        }
+        finally {
+            activeXid = null;
+            void refreshVersions();
+        }
+    }
+    /**
+     * 用 REST 刷新版本列表（每轮收尾服务端才 commit，与 done 事件有毫秒级先后，故延迟重试一次）
+     */
+    async function refreshVersions() {
+        const load = async () => {
+            const list = await client.versions.list(conversationId);
+            state.versions.splice(0, state.versions.length, ...list.map(v => ({ sha: v.sha, message: v.message, filesChanged: v.filesChanged })));
+            return list.length;
+        };
+        try {
+            const before = await load();
+            await new Promise(r => setTimeout(r, 1500));
+            const after = await load();
+            if (after === before) {
+                await new Promise(r => setTimeout(r, 2500));
+                await load();
+            }
+        }
+        catch {
+            // 版本列表非关键路径，静默
+        }
+    }
+    async function cancel() {
+        if (activeXid)
+            await client.chat.cancel(conversationId, activeXid);
+    }
+    // 初次挂载：加载已有版本（重新打开会话时）
+    void refreshVersions();
+    return {
+        state: readonly(state),
+        streamError: readonly(streamError),
+        isStreaming: computed(() => state.agentState === 'streaming'),
+        send,
+        cancel,
+        refreshVersions,
+    };
+}

package/dist/usePreviewUrl.d.ts

@@ -0,0 +1,13 @@
+import { type Ref } from 'vue';
+import type { BuilderClient } from '@chatu-ai/builder-sdk';
+/**
+ * 预览地址（带一次性 token 的 iframe src，06 §6.1）：
+ * - 沙箱 previewUrl 出现/变化时取一次 token
+ * - 授权失效（预览域授权页 postMessage）时调用 refresh() 重取
+ * token 一次性：每次 refresh 都签发新 token，旧 iframe 已兑换为 cookie 不受影响
+ */
+export declare function usePreviewUrl(client: BuilderClient, conversationId: string, rawPreviewUrl: Ref<string | undefined>): {
+    src: Ref<string | undefined, string | undefined>;
+    error: Ref<string | null, string | null>;
+    refresh: () => Promise<void>;
+};

package/dist/usePreviewUrl.js

@@ -0,0 +1,35 @@
+import { ref, watch } from 'vue';
+/**
+ * 预览地址（带一次性 token 的 iframe src，06 §6.1）：
+ * - 沙箱 previewUrl 出现/变化时取一次 token
+ * - 授权失效（预览域授权页 postMessage）时调用 refresh() 重取
+ * token 一次性：每次 refresh 都签发新 token，旧 iframe 已兑换为 cookie 不受影响
+ */
+export function usePreviewUrl(client, conversationId, rawPreviewUrl) {
+    const src = ref(undefined);
+    const error = ref(null);
+    let seq = 0;
+    async function refresh() {
+        if (!rawPreviewUrl.value) {
+            src.value = undefined;
+            return;
+        }
+        const my = ++seq;
+        try {
+            const { previewUrl } = await client.sandbox.previewToken(conversationId);
+            if (my === seq) {
+                src.value = previewUrl || rawPreviewUrl.value;
+                error.value = previewUrl ? null : 'preview-token 响应缺少 previewUrl';
+            }
+        }
+        catch (err) {
+            if (my === seq) {
+                // 取不到 token 时回退原始地址：iframe 会显示授权页并 postMessage → 触发再次 refresh
+                error.value = String(err);
+                src.value = rawPreviewUrl.value;
+            }
+        }
+    }
+    watch(rawPreviewUrl, () => void refresh(), { immediate: true });
+    return { src, error, refresh };
+}

package/dist/useSandboxStatus.d.ts

@@ -0,0 +1,40 @@
+import type { BuilderClient } from '@chatu-ai/builder-sdk';
+export interface SandboxStatusOptions {
+    /** 过渡态（创建/预热/恢复/快照/未知）轮询间隔，默认 3000ms */
+    pollMs?: number;
+    /** 稳定态（ready/busy）轮询间隔，默认 60000ms——此时状态主要由 SSE 事件与心跳响应维护 */
+    idlePollMs?: number;
+    /** 休眠态轮询间隔，默认 15000ms（等待唤醒） */
+    hibernatedPollMs?: number;
+    /** 心跳间隔（08 §4：页面可见才发），默认 30000ms */
+    heartbeatMs?: number;
+    /** 可见性探针（默认读 document.visibilityState；测试可注入） */
+    isVisible?: () => boolean;
+    setInterval?: typeof globalThis.setInterval;
+    clearInterval?: typeof globalThis.clearInterval;
+}
+/**
+ * 沙箱状态 + 心跳组合式 API（08 §4）
+ * - 自适应轮询：过渡态密集、稳定态稀疏、休眠态中等；页面隐藏时不轮询、不心跳
+ * - 心跳响应携带 state，稳定态下以此为主要状态来源，避免高频打 status
+ */
+export declare function useSandboxStatus(client: BuilderClient, conversationId: string, opts?: SandboxStatusOptions): {
+    status: Readonly<import("vue").Ref<{
+        readonly state: import("@chatu-ai/builder-sdk").SandboxState;
+        readonly previewUrl?: string | undefined;
+        readonly devServer?: {
+            readonly running: boolean;
+            readonly lastError?: string | undefined;
+        } | undefined;
+    } | null, {
+        readonly state: import("@chatu-ai/builder-sdk").SandboxState;
+        readonly previewUrl?: string | undefined;
+        readonly devServer?: {
+            readonly running: boolean;
+            readonly lastError?: string | undefined;
+        } | undefined;
+    } | null>>;
+    error: Readonly<import("vue").Ref<string | null, string | null>>;
+    refresh: () => Promise<void>;
+    stop: () => void;
+};

package/dist/useSandboxStatus.js

@@ -0,0 +1,67 @@
+import { onScopeDispose, readonly, ref } from 'vue';
+const TRANSITIONAL = new Set(['requested', 'creating', 'warming', 'resuming', 'snapshotting']);
+/**
+ * 沙箱状态 + 心跳组合式 API（08 §4）
+ * - 自适应轮询：过渡态密集、稳定态稀疏、休眠态中等；页面隐藏时不轮询、不心跳
+ * - 心跳响应携带 state，稳定态下以此为主要状态来源，避免高频打 status
+ */
+export function useSandboxStatus(client, conversationId, opts = {}) {
+    const status = ref(null);
+    const error = ref(null);
+    const isVisible = opts.isVisible ??
+        (() => (typeof document === 'undefined' ? true : document.visibilityState === 'visible'));
+    const setI = opts.setInterval ?? globalThis.setInterval.bind(globalThis);
+    const clearI = opts.clearInterval ?? globalThis.clearInterval.bind(globalThis);
+    const pollMs = opts.pollMs ?? 3_000;
+    const idlePollMs = opts.idlePollMs ?? 60_000;
+    const hibernatedPollMs = opts.hibernatedPollMs ?? 15_000;
+    let lastPoll = 0;
+    function currentInterval() {
+        const s = status.value?.state;
+        if (!s || TRANSITIONAL.has(s))
+            return pollMs;
+        if (s === 'hibernated')
+            return hibernatedPollMs;
+        return idlePollMs;
+    }
+    async function refresh() {
+        lastPoll = Date.now();
+        try {
+            status.value = await client.sandbox.status(conversationId);
+            error.value = null;
+        }
+        catch (err) {
+            error.value = String(err);
+        }
+    }
+    async function beatOnce() {
+        if (!isVisible())
+            return;
+        try {
+            const r = (await client.sandbox.heartbeat(conversationId, { visible: true }));
+            // 心跳响应带 state（BuilderController），稳定态下据此更新，免打 status
+            if (r && typeof r === 'object' && r.state && status.value) {
+                status.value = { ...status.value, state: r.state };
+            }
+        }
+        catch {
+            // 心跳失败不打扰用户；状态轮询会暴露真实问题
+        }
+    }
+    // 单一 1s tick 调度器：按当前状态决定是否到期轮询（避免多定时器切换）
+    const tick = setI(() => {
+        if (!isVisible())
+            return;
+        if (Date.now() - lastPoll >= currentInterval())
+            void refresh();
+    }, 1_000);
+    const heartbeatTimer = setI(() => void beatOnce(), opts.heartbeatMs ?? 30_000);
+    function stop() {
+        clearI(tick);
+        clearI(heartbeatTimer);
+    }
+    onScopeDispose(stop);
+    void refresh();
+    void beatOnce();
+    return { status: readonly(status), error: readonly(error), refresh, stop };
+}

package/dist/vue.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vue.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMockBuilderClient, scenario1, scenario2 } from '@chatu-ai/builder-sdk-mock';
+import { useBuilderChat } from './useBuilderChat';
+import { useSandboxStatus } from './useSandboxStatus';
+import { createInitialState, reduceEvent } from './reducer';
+function fastScenario(s) {
+    return { ...s, steps: s.steps.map(st => ({ ...st, delayMs: 0 })) };
+}
+describe('reducer', () => {
+    it('reduces scenario1 event sequence into complete UI state', () => {
+        const state = createInitialState();
+        for (const step of scenario1.steps)
+            reduceEvent(state, step.event);
+        expect(state.agentState).toBe('idle'); // done(completed) 收尾
+        expect(state.rounds).toHaveLength(1);
+        const round = state.rounds[0];
+        expect(round.taskCards.map(c => c.state)).toEqual(['done', 'done', 'done']); // 三张卡全 done（原位更新）
+        expect(state.changedPaths).toContain('app/page.tsx');
+        expect(state.sandbox.state).toBe('ready');
+        expect(state.versions[0]?.sha).toBe('aaa111');
+        expect(round.version?.sha).toBe('aaa111');
+    });
+    it('taskCard upserts by id instead of appending', () => {
+        const state = createInitialState();
+        reduceEvent(state, { kind: 'taskCard', xid: 'x', seq: 1, id: 't1', label: 'a', state: 'running' });
+        reduceEvent(state, { kind: 'taskCard', xid: 'x', seq: 2, id: 't1', label: 'a', state: 'done' });
+        expect(state.rounds[0].taskCards).toHaveLength(1);
+        expect(state.rounds[0].taskCards[0].state).toBe('done');
+    });
+    it('preview crashed records lastError; ready clears it', () => {
+        const state = createInitialState();
+        reduceEvent(state, { kind: 'preview', xid: 'x', seq: 1, state: 'crashed', error: 'boom' });
+        expect(state.sandbox.lastError).toBe('boom');
+        reduceEvent(state, { kind: 'preview', xid: 'x', seq: 2, state: 'ready', url: 'https://a.b' });
+        expect(state.sandbox.lastError).toBeNull();
+        expect(state.sandbox.state).toBe('ready');
+    });
+});
+describe('useBuilderChat', () => {
+    it('streams scenario to completion and rejects concurrent send (R11)', async () => {
+        const client = createMockBuilderClient(fastScenario(scenario1));
+        const chat = useBuilderChat(client, 'c1');
+        const sending = chat.send('make a landing page');
+        await expect(chat.send('another')).rejects.toThrow('BUSY');
+        await sending;
+        expect(chat.state.agentState).toBe('idle');
+        expect(chat.state.rounds[0].done?.state).toBe('completed');
+        expect(chat.isStreaming.value).toBe(false);
+    });
+    it('survives scenario2 disconnect: state complete, no duplicate task cards', async () => {
+        const client = createMockBuilderClient(fastScenario(scenario2));
+        const chat = useBuilderChat(client, 'c1');
+        await chat.send('change color');
+        expect(chat.state.rounds[0].taskCards).toHaveLength(1);
+        expect(chat.state.versions[0]?.sha).toBe('bbb222');
+        expect(chat.state.lastSeq).toBe(6);
+    });
+});
+describe('useSandboxStatus', () => {
+    it('polls status and sends heartbeat only when visible', async () => {
+        vi.useFakeTimers();
+        const client = createMockBuilderClient(fastScenario(scenario1));
+        const heartbeat = vi.spyOn(client.sandbox, 'heartbeat');
+        let visible = true;
+        const s = useSandboxStatus(client, 'c1', {
+            isVisible: () => visible,
+            heartbeatMs: 1000,
+            pollMs: 500,
+        });
+        await vi.advanceTimersByTimeAsync(1100);
+        expect(heartbeat).toHaveBeenCalled();
+        const callsWhenVisible = heartbeat.mock.calls.length;
+        visible = false;
+        await vi.advanceTimersByTimeAsync(3000);
+        expect(heartbeat.mock.calls.length).toBe(callsWhenVisible); // 隐藏后不再心跳
+        s.stop();
+        vi.useRealTimers();
+    });
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@chatu-ai/builder-sdk-vue",
+  "version": "0.1.0",
+  "description": "Vue 3 bindings for @chatu-ai/builder-sdk: useBuilderChat / useSandboxStatus / usePreviewUrl",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatu-ai/chatu-builder-sdk.git",
+    "directory": "packages/vue"
+  },
+  "homepage": "https://github.com/chatu-ai/chatu-builder-sdk/tree/main/packages/vue#readme",
+  "bugs": "https://github.com/chatu-ai/chatu-builder-sdk/issues",
+  "keywords": [
+    "chatu",
+    "builder",
+    "ai",
+    "app-builder",
+    "sdk",
+    "vue",
+    "composables"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@chatu-ai/builder-sdk": "0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vue": "^3.5.0",
+    "vitest": "^3.0.0",
+    "@chatu-ai/builder-sdk-mock": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}