@joplo-app/server 0.0.0-stage → 0.1.1

package/dist/export.d.ts

@@ -0,0 +1,82 @@
+import type http from 'node:http';
+import { type Project } from '@joplo-app/core';
+import { type PlaywrightModule } from './render.js';
+export type Device = 'desktop' | 'mobile';
+/**
+ * 导出画面的尺寸：电脑 = 舞台 1280×800；手机 = 外框（renderer 的 phoneFrameSize(390, 844) = 446×934）
+ * 四周再留 16px（RenderApp 的 frame 模式）。舞台正下方是字幕区（SUBTITLE_HEIGHT），一起导出。
+ */
+export declare const EXPORT_SIZE: Record<Device, {
+    width: number;
+    height: number;
+}>;
+export type VideoJob = {
+    id: string;
+    projectId: string;
+    scenarioId: string;
+    status: 'running' | 'done' | 'error';
+    /** starting 启动浏览器 → recording 录制中 → saving 写文件。 */
+    phase: 'starting' | 'recording' | 'saving' | 'done' | 'error';
+    step: number;
+    total: number;
+    /** 0–100。 */
+    percent: number;
+    /** 完成后：相对项目目录的路径（exports/…webm）。 */
+    file: string | null;
+    error: string | null;
+};
+/** 录制实现：报告进度，返回写好的文件绝对路径。测试可注入。 */
+export type VideoRecorder = (input: {
+    url: string;
+    size: {
+        width: number;
+        height: number;
+    };
+    out: string;
+    total: number;
+    progress: (step: number) => void;
+    signal: AbortSignal;
+}) => Promise<void>;
+export type ExportDeps = {
+    loadPlaywright: () => Promise<PlaywrightModule>;
+    recordVideo: VideoRecorder;
+};
+type Ctx = {
+    projectId: string;
+    dir: string;
+    project: Project | null;
+    /** Origin + 令牌（+ needJson 时 Content-Type）检查；false 表示已拒绝并写好响应。 */
+    guardWrite: (needJson?: boolean) => boolean;
+    jsonBody: () => Promise<{
+        ok: true;
+        body: unknown;
+    } | {
+        ok: false;
+    }>;
+    fail: (e: unknown) => void;
+};
+/** 缺省的录制：Playwright recordVideo + 渲染路由的录制模式（window.__JOPLO_RECORD__）。 */
+export declare function defaultRecorder(load: () => Promise<PlaywrightModule>): VideoRecorder;
+export declare class ExportHub {
+    private readonly opts;
+    private jobs;
+    private listeners;
+    private aborts;
+    private running;
+    private deps;
+    constructor(opts: {
+        baseUrl: () => string;
+        log: (s: string) => void;
+        deps?: Partial<ExportDeps>;
+        onEvent?: (j: VideoJob) => void;
+    });
+    private renderUrl;
+    job(projectId: string): VideoJob | null;
+    private update;
+    handle(sub: string, req: http.IncomingMessage, res: http.ServerResponse, ctx: Ctx): Promise<void>;
+    private image;
+    private startVideo;
+    private sse;
+    close(): Promise<void>;
+}
+export {};

package/dist/export.js

@@ -0,0 +1,245 @@
+/**
+ * 看板「…」菜单的导出（D39）：
+ *
+ * - 图片：`POST /__joplo/p/<id>/export/image` `{ scenarioId, position, theme }` → PNG（当前步骤；尺寸跟随页面自己的 viewport，
+ *   手机页面带外框；D44 起不再选择设备；镜头用这一步的导演镜头）。Playwright 打开本看板的渲染路由（与 renderStep 同一条渲染路径），截取 `[data-jexport]`。
+ * - 视频（只在本机）：`POST …/export/video` `{ scenarioId, theme }` → 202 `{ jobId }`（尺寸跟随场景起始页面的 viewport）；
+ *   Playwright `recordVideo` 录下渲染路由的自动播放（含鼠标与字幕），保存为 `<项目>/exports/<场景>-<时间>.webm`。
+ *   进度：`GET …/export/video/events`（SSE，先发当前状态，之后每次变化一条，结束后关闭）；`GET …/export/video` 取当前状态。
+ *   同一项目同时只能有一个视频任务（再提交返回 409）。没有 Playwright / Chromium 时任务失败，错误里带安装命令。
+ *
+ * 字段流向：job（写入点：这里的 runJob）→ jobs Map（存储）→ SSE / GET（读取点）→ 看板的导出视频弹窗（消费者）。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { JoploError, SUBTITLE_HEIGHT, THEME_NAME, displaySceneId } from '@joplo-app/core';
+import { launch, loadPlaywright } from "./render.js";
+/**
+ * 导出画面的尺寸：电脑 = 舞台 1280×800；手机 = 外框（renderer 的 phoneFrameSize(390, 844) = 446×934）
+ * 四周再留 16px（RenderApp 的 frame 模式）。舞台正下方是字幕区（SUBTITLE_HEIGHT），一起导出。
+ */
+export const EXPORT_SIZE = {
+    desktop: { width: 1280, height: 800 + SUBTITLE_HEIGHT },
+    mobile: { width: 446 + 32, height: 934 + 32 + SUBTITLE_HEIGHT },
+};
+const send = (res, status, body) => {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    res.end(JSON.stringify(body));
+};
+function parseRequest(project, body, needPosition) {
+    if (!project)
+        throw new JoploError('INVALID_SCHEMA', '项目还没有成功编译过，无法导出');
+    const b = (body ?? {});
+    if (typeof b.scenarioId !== 'string' || !project.scenarios[b.scenarioId])
+        throw new JoploError('USAGE', `场景不存在：${String(b.scenarioId)}`);
+    const sc = project.scenarios[b.scenarioId];
+    const position = needPosition ? Number(b.position ?? 0) : 0;
+    if (!Number.isInteger(position) || position < 0 || position > sc.steps.length)
+        throw new JoploError('USAGE', `位置应为 0–${sc.steps.length} 的整数`);
+    // 设备跟随页面自己的 viewport（D44）
+    const sceneId = displaySceneId(project, sc.id, position);
+    const device = project.scenes[sceneId]?.viewport === 'mobile' ? 'mobile' : 'desktop';
+    // 主题（D51）：请求里的主题名，没有或不合法时用项目配置的主题
+    const theme = typeof b.theme === 'string' && THEME_NAME.test(b.theme) ? b.theme : project.theme;
+    return { sc, position, device, theme };
+}
+const fileSafe = (s) => s.replace(/[^\w.-]+/g, '_').slice(0, 80) || 'scenario';
+const stamp = (d = new Date()) => `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, '0')}${String(d.getDate()).padStart(2, '0')}-${String(d.getHours()).padStart(2, '0')}${String(d.getMinutes()).padStart(2, '0')}${String(d.getSeconds()).padStart(2, '0')}`;
+async function waitReady(page) {
+    await page.waitForFunction(() => window.__JOPLO_READY__ === true, null, { timeout: 60000 });
+    const err = await page.evaluate(() => window.__JOPLO_ERROR__ ?? null);
+    if (err)
+        throw new JoploError('RENDER_FAILED', `渲染路由报告错误：${err}`);
+}
+/** 缺省的录制：Playwright recordVideo + 渲染路由的录制模式（window.__JOPLO_RECORD__）。 */
+export function defaultRecorder(load) {
+    return async ({ url, size, out, progress, signal }) => {
+        const pw = await load();
+        const browser = await launch(pw);
+        const tmp = fs.mkdtempSync(path.join(path.dirname(out), '.rec-'));
+        try {
+            const ctx = await browser.newContext({ viewport: size, deviceScaleFactor: 1, recordVideo: { dir: tmp, size } });
+            const page = await ctx.newPage();
+            await page.goto(url, { waitUntil: 'domcontentloaded' });
+            await waitReady(page);
+            await page.waitForTimeout(400);
+            await page.evaluate(() => window.__JOPLO_RECORD__.play());
+            const t0 = Date.now();
+            for (;;) {
+                if (signal.aborted)
+                    throw new JoploError('EXPORT_FAILED', '导出已取消');
+                const p = await page.evaluate(() => window.__JOPLO_RECORD__.progress);
+                if (p.error)
+                    throw new JoploError('EXPORT_FAILED', `播放出错：${p.error}`);
+                progress(p.step);
+                if (p.done)
+                    break;
+                if (Date.now() - t0 > 5 * 60_000)
+                    throw new JoploError('EXPORT_FAILED', '录制超过 5 分钟，已停止');
+                await page.waitForTimeout(150);
+            }
+            await page.waitForTimeout(900); // 停留在结果画面
+            const video = page.video();
+            await ctx.close();
+            if (!video)
+                throw new JoploError('EXPORT_FAILED', '浏览器没有生成视频');
+            await video.saveAs(out);
+        }
+        finally {
+            await browser.close().catch(() => undefined);
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+    };
+}
+export class ExportHub {
+    opts;
+    jobs = new Map();
+    listeners = new Map();
+    aborts = new Map();
+    running = new Set();
+    deps;
+    constructor(opts) {
+        this.opts = opts;
+        const load = opts.deps?.loadPlaywright ?? (() => loadPlaywright());
+        this.deps = { loadPlaywright: load, recordVideo: opts.deps?.recordVideo ?? defaultRecorder(load) };
+    }
+    renderUrl(projectId, q) {
+        return `${this.opts.baseUrl()}?${new URLSearchParams({ render: '1', project: projectId, ...q })}`;
+    }
+    job(projectId) {
+        return this.jobs.get(projectId) ?? null;
+    }
+    update(job, patch) {
+        Object.assign(job, patch);
+        const snap = { ...job };
+        for (const l of this.listeners.get(job.projectId) ?? [])
+            l(snap);
+        this.opts.onEvent?.(snap);
+    }
+    async handle(sub, req, res, ctx) {
+        const method = req.method ?? 'GET';
+        try {
+            if (sub === 'image' && method === 'POST') {
+                if (!ctx.guardWrite())
+                    return;
+                const b = await ctx.jsonBody();
+                if (!b.ok)
+                    return;
+                const { sc, position, device, theme } = parseRequest(ctx.project, b.body, true);
+                const png = await this.image(ctx.projectId, sc.id, position, device, theme);
+                res.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'no-store', 'content-disposition': `attachment; filename="${fileSafe(sc.id)}-${position}.png"` });
+                res.end(png);
+                return;
+            }
+            if (sub === 'video' && method === 'POST') {
+                if (!ctx.guardWrite())
+                    return;
+                const b = await ctx.jsonBody();
+                if (!b.ok)
+                    return;
+                const { sc, device, theme } = parseRequest(ctx.project, b.body, false);
+                const cur = this.jobs.get(ctx.projectId);
+                if (cur?.status === 'running')
+                    return send(res, 409, { error: { code: 'UNSUPPORTED_ACTION', message: '这个项目已有一个视频正在导出，请等它完成' }, job: cur });
+                const job = this.startVideo(ctx.projectId, ctx.dir, sc.id, sc.steps.length, device, theme);
+                return send(res, 202, { jobId: job.id, job });
+            }
+            if (sub === 'video' && method === 'GET')
+                return send(res, 200, { job: this.job(ctx.projectId) });
+            if (sub === 'video/events' && method === 'GET') {
+                if (!ctx.guardWrite(false))
+                    return;
+                return this.sse(ctx.projectId, res);
+            }
+            return send(res, 404, { error: { code: 'NOT_FOUND', message: `没有这个接口：${method} export/${sub}` } });
+        }
+        catch (e) {
+            if (!res.headersSent)
+                ctx.fail(e);
+            else
+                res.end();
+        }
+    }
+    async image(projectId, scenarioId, position, device, theme) {
+        const pw = await this.deps.loadPlaywright();
+        const browser = await launch(pw);
+        try {
+            const page = await browser.newPage({ viewport: EXPORT_SIZE[device], deviceScaleFactor: 2, reducedMotion: 'reduce' });
+            await page.goto(this.renderUrl(projectId, { scenario: scenarioId, position: String(position), theme, frame: '1' }), { waitUntil: 'domcontentloaded' });
+            await waitReady(page);
+            return await page.locator('[data-jexport]').screenshot({ type: 'png', animations: 'disabled' });
+        }
+        finally {
+            await browser.close().catch(() => undefined);
+        }
+    }
+    startVideo(projectId, dir, scenarioId, total, device, theme) {
+        const job = { id: crypto.randomBytes(6).toString('hex'), projectId, scenarioId, status: 'running', phase: 'starting', step: 0, total, percent: 0, file: null, error: null };
+        this.jobs.set(projectId, job);
+        const ac = new AbortController();
+        this.aborts.set(projectId, ac);
+        const rel = `exports/${fileSafe(scenarioId)}-${stamp()}.webm`;
+        const out = path.join(dir, rel);
+        const p = (async () => {
+            try {
+                fs.mkdirSync(path.dirname(out), { recursive: true });
+                this.update(job, { phase: 'starting', percent: 2 });
+                await this.deps.recordVideo({
+                    url: this.renderUrl(projectId, { scenario: scenarioId, position: '0', theme, frame: '1', record: '1' }),
+                    size: EXPORT_SIZE[device],
+                    out,
+                    total,
+                    signal: ac.signal,
+                    progress: (step) => {
+                        const s = Math.max(0, Math.min(step, total));
+                        const percent = Math.round(5 + (total ? s / total : 1) * 85);
+                        if (job.phase !== 'recording' || s !== job.step)
+                            this.update(job, { phase: 'recording', step: s, percent });
+                    },
+                });
+                this.update(job, { phase: 'saving', percent: 95 });
+                if (!fs.existsSync(out))
+                    throw new JoploError('EXPORT_FAILED', '录制完成，但没有生成视频文件');
+                this.update(job, { status: 'done', phase: 'done', percent: 100, step: total, file: rel });
+                this.opts.log(`[joplo] 已导出视频：${out}`);
+            }
+            catch (e) {
+                this.update(job, { status: 'error', phase: 'error', error: e instanceof Error ? e.message : String(e) });
+            }
+            finally {
+                this.aborts.delete(projectId);
+            }
+        })();
+        this.running.add(p);
+        void p.finally(() => this.running.delete(p));
+        return job;
+    }
+    sse(projectId, res) {
+        res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', connection: 'keep-alive', 'x-content-type-options': 'nosniff' });
+        const write = (j) => res.write(`data: ${JSON.stringify(j)}\n\n`);
+        const cur = this.job(projectId);
+        write(cur);
+        if (!cur || cur.status !== 'running') {
+            res.end();
+            return;
+        }
+        const set = this.listeners.get(projectId) ?? new Set();
+        this.listeners.set(projectId, set);
+        const l = (j) => {
+            write(j);
+            if (j.status !== 'running') {
+                set.delete(l);
+                res.end();
+            }
+        };
+        set.add(l);
+        res.on('close', () => set.delete(l));
+    }
+    async close() {
+        for (const ac of this.aborts.values())
+            ac.abort();
+        await Promise.allSettled([...this.running]);
+        this.listeners.clear();
+    }
+}

package/dist/home.d.ts

@@ -0,0 +1,49 @@
+export type ProjectRecord = {
+    dir: string;
+    name: string;
+    lastOpened: string;
+};
+export type ServerInfo = {
+    port: number;
+    pid: number;
+    token: string;
+};
+export declare function joploHome(env?: Record<string, string | undefined>): string;
+/** 项目在 URL 里的标识：目录名（小写、只留安全字符）+ 目录绝对路径的短哈希，稳定且不暴露完整路径。 */
+export declare function projectIdOf(dir: string): string;
+export declare class Registry {
+    readonly home: string;
+    readonly file: string;
+    constructor(home: string);
+    /** 读取记录（文件不存在或损坏时为空列表；无效条目跳过），按最近打开排序。 */
+    list(): ProjectRecord[];
+    private save;
+    /** 登记或更新一个项目（打开时间刷新为现在）。 */
+    touch(dir: string, name?: string): ProjectRecord;
+    /** 只更新名称（编译成功后用 config 的 name），不改变打开时间；记录不存在时不新增。 */
+    rename(dir: string, name: string): void;
+    /** 从列表移除；返回是否存在。只改 projects.json。 */
+    remove(dir: string): boolean;
+}
+export declare const serverInfoFile: (home: string) => string;
+export declare function readServerInfo(home: string): ServerInfo | null;
+export declare function writeServerInfo(home: string, info: ServerInfo): void;
+/** 只删除自己写的 server.json（pid 一致），不误删后来者的。 */
+export declare function clearServerInfo(home: string, pid: number): void;
+export declare function pidAlive(pid: number): boolean;
+/**
+ * `{ version: 1, theme?: string | null, projects?: { [项目 id]: { theme: string | null } } }`
+ * theme：所有项目的主题选择；projects[id].theme：按项目覆盖，null 表示“恢复为项目默认”（使用项目 config 里的主题）。
+ * 写入点：看板设置页（PUT /__joplo/settings）；读取点：看板演示页与设置页（GET /__joplo/settings）。原子写入。
+ */
+export type BoardSettings = {
+    version: 1;
+    theme?: string | null;
+    projects?: Record<string, {
+        theme: string | null;
+    }>;
+};
+/** 校验并规范化设置（未知字段丢弃，主题名不合法的条目丢弃）。 */
+export declare function normalizeSettings(v: unknown): BoardSettings;
+export declare function readSettings(home: string): BoardSettings;
+export declare function writeSettings(home: string, s: unknown): BoardSettings;

package/dist/home.js

@@ -0,0 +1,168 @@
+/**
+ * 本机看板的持久数据（D39）：一个本机只运行一个看板进程，它记住打开过的项目。
+ *
+ * - `<JOPLO_HOME>/projects.json`：`{ version: 1, projects: [{ dir, name, lastOpened }] }`，按 lastOpened 倒序显示。
+ *   写入点：hub 启动时登记首个项目、注册接口（再次 `joplo dev`）、编译成功后更新名称、移除接口。
+ *   读取点：hub 的项目列表接口 → 看板首页左栏。原子写入（临时文件 + rename）。
+ * - `<JOPLO_HOME>/server.json`：`{ port, pid, token }`，权限 0600。写入点：hub 开始监听后；
+ *   读取点：`joplo dev` 启动时判断是否已有存活的看板；hub 关闭时删除（只删自己写的那份）。
+ *
+ * JOPLO_HOME 缺省为 ~/.joplo。测试一律把 JOPLO_HOME 指向临时目录。
+ * 删除记录只改 projects.json，从不触碰项目目录。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function joploHome(env = process.env) {
+    const v = env.JOPLO_HOME;
+    return v && v.trim() ? path.resolve(v) : path.join(os.homedir(), '.joplo');
+}
+/** 项目在 URL 里的标识：目录名（小写、只留安全字符）+ 目录绝对路径的短哈希，稳定且不暴露完整路径。 */
+export function projectIdOf(dir) {
+    const base = path.basename(dir).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32) || 'project';
+    const hash = crypto.createHash('sha256').update(dir).digest('hex').slice(0, 6);
+    return `${base}-${hash}`;
+}
+function atomicWrite(file, text, mode) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    fs.writeFileSync(tmp, text, mode === undefined ? undefined : { mode });
+    if (mode !== undefined)
+        fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, file);
+}
+const isRecord = (v) => {
+    const r = v;
+    return !!r && typeof r === 'object' && typeof r.dir === 'string' && path.isAbsolute(r.dir) && typeof r.name === 'string' && typeof r.lastOpened === 'string';
+};
+export class Registry {
+    home;
+    file;
+    constructor(home) {
+        this.home = home;
+        this.file = path.join(home, 'projects.json');
+    }
+    /** 读取记录（文件不存在或损坏时为空列表；无效条目跳过），按最近打开排序。 */
+    list() {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+        const items = raw?.projects;
+        if (!Array.isArray(items))
+            return [];
+        const seen = new Set();
+        const out = [];
+        for (const it of items) {
+            if (!isRecord(it) || seen.has(it.dir))
+                continue;
+            seen.add(it.dir);
+            out.push({ dir: it.dir, name: it.name, lastOpened: it.lastOpened });
+        }
+        return out.sort((a, b) => b.lastOpened.localeCompare(a.lastOpened));
+    }
+    save(list) {
+        atomicWrite(this.file, JSON.stringify({ version: 1, projects: list }, null, 2) + '\n');
+    }
+    /** 登记或更新一个项目（打开时间刷新为现在）。 */
+    touch(dir, name) {
+        const list = this.list();
+        const prev = list.find((p) => p.dir === dir);
+        const rec = { dir, name: name ?? prev?.name ?? path.basename(dir), lastOpened: new Date().toISOString() };
+        this.save([rec, ...list.filter((p) => p.dir !== dir)]);
+        return rec;
+    }
+    /** 只更新名称（编译成功后用 config 的 name），不改变打开时间；记录不存在时不新增。 */
+    rename(dir, name) {
+        const list = this.list();
+        const rec = list.find((p) => p.dir === dir);
+        if (!rec || rec.name === name)
+            return;
+        rec.name = name;
+        this.save(list);
+    }
+    /** 从列表移除；返回是否存在。只改 projects.json。 */
+    remove(dir) {
+        const list = this.list();
+        const next = list.filter((p) => p.dir !== dir);
+        if (next.length === list.length)
+            return false;
+        this.save(next);
+        return true;
+    }
+}
+export const serverInfoFile = (home) => path.join(home, 'server.json');
+export function readServerInfo(home) {
+    try {
+        const v = JSON.parse(fs.readFileSync(serverInfoFile(home), 'utf8'));
+        if (Number.isInteger(v.port) && v.port > 0 && Number.isInteger(v.pid) && v.pid > 0 && typeof v.token === 'string' && v.token)
+            return v;
+    }
+    catch {
+        // 不存在或损坏：视为没有运行中的看板
+    }
+    return null;
+}
+export function writeServerInfo(home, info) {
+    atomicWrite(serverInfoFile(home), JSON.stringify(info) + '\n', 0o600);
+}
+/** 只删除自己写的 server.json（pid 一致），不误删后来者的。 */
+export function clearServerInfo(home, pid) {
+    const cur = readServerInfo(home);
+    if (cur && cur.pid !== pid)
+        return;
+    try {
+        fs.rmSync(serverInfoFile(home), { force: true });
+    }
+    catch {
+        // 忽略
+    }
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+const NAME = /^[A-Za-z][\w-]*$/;
+/** 校验并规范化设置（未知字段丢弃，主题名不合法的条目丢弃）。 */
+export function normalizeSettings(v) {
+    const o = (v && typeof v === 'object' ? v : {});
+    const out = { version: 1 };
+    if (typeof o.theme === 'string' && NAME.test(o.theme))
+        out.theme = o.theme;
+    else if (o.theme === null)
+        out.theme = null;
+    const projects = o.projects && typeof o.projects === 'object' ? o.projects : {};
+    const p = {};
+    for (const [id, x] of Object.entries(projects)) {
+        if (!/^[\w-]{1,64}$/.test(id) || !x || typeof x !== 'object')
+            continue;
+        const t = x.theme;
+        if (t === null || (typeof t === 'string' && NAME.test(t)))
+            p[id] = { theme: t };
+    }
+    if (Object.keys(p).length)
+        out.projects = p;
+    return out;
+}
+export function readSettings(home) {
+    try {
+        return normalizeSettings(JSON.parse(fs.readFileSync(path.join(home, 'settings.json'), 'utf8')));
+    }
+    catch {
+        return { version: 1 };
+    }
+}
+export function writeSettings(home, s) {
+    const n = normalizeSettings(s);
+    atomicWrite(path.join(home, 'settings.json'), JSON.stringify(n, null, 2) + '\n');
+    return n;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @joplo-app/server：CLI 只依赖这里导出的三个函数（接口见 contract.ts）。
+ *
+ * - startDev：单进程 Vite 开发服务，提供看板、编译与热更新；选中写入 .joplo/selection.json。
+ * - buildSite：静态发布站（只含选定方案，hash 路由，file:// 可直接打开）。
+ * - renderStep：某个场景某一步之后的截图、元素索引（带 at）与渲染告警。
+ */
+export type { BuildOptions, BuildResult, DevHandle, DevOptions, RenderOptions, RenderResult, RenderedElement } from './contract.js';
+export { startDev } from './dev.js';
+export { buildSite } from './build.js';
+export { renderStep } from './render.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { startDev } from "./dev.js";
+export { buildSite } from "./build.js";
+export { renderStep } from "./render.js";

package/dist/page-report.js

@@ -0,0 +1,82 @@
+/* 在渲染页面内执行（Playwright page.evaluate），生成元素索引与渲染告警（PRD 8.8 / AC-22）。
+ * 纯 JS，运行时以文本注入，避免转译器注入辅助函数。参数：{ nextTargetId, theme }。 */
+(args) => {
+  const stage = document.querySelector('[data-joplo-stage]');
+  const sr = stage.getBoundingClientRect();
+  const warnings = [];
+  // 文本节点（#text）不进索引：它们属于父元素
+  const els = Array.from(stage.querySelectorAll('[data-jid]:not([data-jtype="#text"])'));
+  const name = (el) => {
+    const owner = el.closest('[data-jid]:not([data-jtype="#text"])');
+    return owner ? `「${owner.dataset.jlabel ?? ''}」(${owner.dataset.jid})` : el.closest('[data-jtoast]') ? 'Toast' : el.closest('[data-jbackdrop]') ? '弹窗遮罩' : el.tagName.toLowerCase();
+  };
+  const elements = els.map((el) => {
+    const r = el.getBoundingClientRect();
+    const box = { x: Math.round(r.left - sr.left), y: Math.round(r.top - sr.top), width: Math.round(r.width), height: Math.round(r.height) };
+    const style = getComputedStyle(el);
+    const intersects = r.right > sr.left && r.left < sr.right && r.bottom > sr.top && r.top < sr.bottom;
+    const visible = r.width > 0 && r.height > 0 && intersects && style.visibility !== 'hidden' && style.display !== 'none';
+    return { id: el.dataset.jid, type: el.dataset.jtype, label: el.dataset.jlabel ?? '', visible, disabled: el.hasAttribute('data-jdisabled'), at: el.dataset.jat ?? null, box };
+  });
+
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const offViewport = [];
+  const dialogOpen = !!stage.querySelector('[data-jbackdrop]');
+  const overlap = (a, b) => Math.min(a.right, b.right) - Math.max(a.left, b.left) > 2 && Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) > 2;
+
+  // 1. 可见的可交互元素：中心点必须命中它自身
+  els.forEach((el, i) => {
+    const e = elements[i];
+    if (!el.hasAttribute('data-jinteractive') || !e.visible) return;
+    const r = el.getBoundingClientRect();
+    const cx = r.left + r.width / 2;
+    const cy = r.top + r.height / 2;
+    if (cx < sr.left || cx > sr.right || cy < sr.top || cy > sr.bottom) {
+      warnings.push(`超出画框：「${e.label}」(${e.id}) 的中心点不在画框内`);
+      return;
+    }
+    // 视口小于舞台时，视口外的点 elementFromPoint 返回 null——那不是遮挡，单独汇总
+    if (cx < 0 || cy < 0 || cx >= vw || cy >= vh) {
+      offViewport.push(e.id);
+      return;
+    }
+    const hit = document.elementFromPoint(cx, cy);
+    if (hit && (hit === el || el.contains(hit))) return;
+    // 弹窗打开时，背景被遮罩或弹窗面板覆盖是预期的层次，不算遮挡（窄屏下面板常盖住背景按钮）
+    if ((hit?.closest('[data-jbackdrop]') || (dialogOpen && hit?.closest('[role="dialog"]'))) && !el.closest('[role="dialog"]')) return;
+    warnings.push(`被遮挡：「${e.label}」(${e.id}) 的中心点被 ${hit ? name(hit) : '画框外内容'} 覆盖`);
+  });
+
+  if (offViewport.length)
+    warnings.push(`不在视口内：视口 ${vw}×${vh} 小于舞台，${offViewport.length} 个可交互元素的中心点在视口外，未做遮挡检查（${offViewport.join(', ')}）`);
+
+  // 2. 标签文字溢出
+  stage.querySelectorAll('[data-jtext], .jtrunc').forEach((t) => {
+    if (t.scrollWidth > t.clientWidth + 1) warnings.push(`标签文字溢出：${name(t)} 的文字「${(t.textContent ?? '').slice(0, 40)}」显示不全`);
+  });
+
+  // 3. Toast 等浮层（pointer-events:none，elementFromPoint 看不到）与可交互元素按几何相交检测
+  const toasts = Array.from(stage.querySelectorAll('[data-jtoast]')).map((t) => t.getBoundingClientRect());
+  if (toasts.length) {
+    els.forEach((el, i) => {
+      const e = elements[i];
+      if (!el.hasAttribute('data-jinteractive') || !e.visible) return;
+      if (dialogOpen && !el.closest('[role="dialog"]')) return; // 被弹窗遮罩盖住的背景本来就不可操作
+      const r = el.getBoundingClientRect();
+      if (!toasts.some((b) => overlap(b, r))) return;
+      warnings.push(e.id === args.nextTargetId ? `Toast 遮挡了下一步操作的目标：${name(el)}` : `Toast 覆盖了可交互元素：${name(el)}`);
+    });
+  }
+
+  // 4. 字体
+  // 主题用到手写字体时（--jp-font 含 Excalifont）检查它们已加载
+  if (/Excalifont|Xiaolai/.test(getComputedStyle(stage).fontFamily)) {
+    const text = stage.innerText || '中文';
+    if (!document.fonts.check('16px "Joplo Excalifont"', text) || !document.fonts.check('16px "Joplo Xiaolai"', text)) warnings.push('字体未加载：手写字体（Excalifont / Xiaolai）尚未就绪，截图可能使用了后备字体');
+  }
+  const failed = Array.from(document.fonts).filter((f) => f.status === 'error');
+  if (failed.length) warnings.push(`字体未加载：${failed.length} 个字体文件加载失败（${failed[0].family}）`);
+
+  return { elements, warnings };
+}

package/dist/project.d.ts

@@ -0,0 +1,14 @@
+import { type Diagnostic, type Project } from '@joplo-app/core';
+import { discoverFiles } from '@joplo-app/core/node';
+import type { ViteDevServer } from 'vite';
+export type CompileOutcome = {
+    /** 本次编译成功的 IR；失败时为 null。 */
+    project: Project | null;
+    diagnostics: Diagnostic[];
+    /** joplo.config 的 home（看板与发布站的首页路径）。 */
+    home: string | null;
+};
+export declare function compileProject(server: ViteDevServer, projectDir: string, mode: 'dev' | 'publish'): Promise<CompileOutcome>;
+/** 让项目源文件在下次载入时重新转译、重新求值。 */
+export declare function invalidateProjectModules(server: ViteDevServer, projectDir: string): void;
+export { discoverFiles };