@joplo-app/server 0.0.0-stage → 0.1.1

package/dist/project.js

@@ -0,0 +1,79 @@
+/**
+ * 用 Vite 的 ssrLoadModule 载入项目源文件，交给 core 的 loadAuthoring + compile。
+ * dev（看板、截图）与 build（发布站）共用这一条路径。
+ */
+import path from 'node:path';
+import { compile } from '@joplo-app/core';
+import { discoverFiles, loadAuthoring } from '@joplo-app/core/node';
+import { isProjectSource } from "./vite-shared.js";
+const LOC_IN_MESSAGE = /((?:[\w@.-]+\/)*[\w@.-]+\.(?:tsx|ts|jsx|js|mts)):(\d+):(\d+)/;
+/** 运行时错误（模块求值时抛出）：从调用栈里找第一处项目文件位置。 */
+function stackLoc(projectDir, e) {
+    const stack = e instanceof Error ? (e.stack ?? '') : '';
+    for (const line of stack.split('\n')) {
+        const m = /\(?((?:file:\/\/)?\/[^():\s]+):(\d+):(\d+)\)?\s*$/.exec(line);
+        if (!m)
+            continue;
+        const file = decodeURIComponent(m[1].replace(/^file:\/\//, ''));
+        if (isProjectSource(projectDir, file))
+            return `${path.relative(projectDir, file).split(path.sep).join('/')}:${m[2]}:${m[3]}`;
+    }
+    return null;
+}
+export async function compileProject(server, projectDir, mode) {
+    const errorAt = new Map(); // 载入失败的文件（绝对路径）→ 精确位置
+    const importer = async (abs) => {
+        try {
+            return (await server.ssrLoadModule(abs));
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const m = LOC_IN_MESSAGE.exec(msg);
+            const at = m ? `${m[1]}:${m[2]}:${m[3]}` : stackLoc(projectDir, e);
+            if (at)
+                errorAt.set(abs, at);
+            throw e instanceof Error ? e : new Error(msg);
+        }
+    };
+    const loaded = await loadAuthoring(projectDir, importer);
+    const rel = (abs) => path.relative(projectDir, abs).split(path.sep).join('/');
+    const byRel = new Map([...errorAt].map(([abs, at]) => [rel(abs), at]));
+    const seen = new Set();
+    const diagnostics = [];
+    for (const d of loaded.diagnostics) {
+        let out = d;
+        if (d.code === 'LOAD_FAILED' && d.at) {
+            const file = d.at.replace(/:\d+:\d+$/, '');
+            const precise = byRel.get(file);
+            if (precise)
+                out = {
+                    ...d,
+                    at: precise,
+                    // 位置已在 at 里，说明只保留第一行的原因
+                    message: d.message.replace(/\x1b\[[0-9;]*m/g, '').split('\n')[0].replace(`载入失败：${precise} `, '载入失败：'),
+                };
+        }
+        const key = `${out.code}|${out.at}|${out.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        diagnostics.push(out);
+    }
+    if (!loaded.authoring)
+        return { project: null, diagnostics, home: null };
+    const home = loaded.authoring.config.home ?? null;
+    if (diagnostics.some((d) => d.severity === 'error'))
+        return { project: null, diagnostics, home };
+    const r = compile(loaded.authoring, mode);
+    return { project: r.project, diagnostics: [...diagnostics, ...r.diagnostics], home };
+}
+/** 让项目源文件在下次载入时重新转译、重新求值。 */
+export function invalidateProjectModules(server, projectDir) {
+    for (const env of Object.values(server.environments)) {
+        const graph = env.moduleGraph;
+        for (const mod of graph.idToModuleMap.values())
+            if (mod.file && isProjectSource(projectDir, mod.file))
+                graph.invalidateModule(mod);
+    }
+}
+export { discoverFiles };

package/dist/render.d.ts

@@ -0,0 +1,9 @@
+import type { Browser } from 'playwright';
+import type { RenderOptions, RenderResult } from './contract.js';
+export type PlaywrightModule = typeof import('playwright');
+/** 按需载入 Playwright；没有安装时抛出带安装命令的 RENDER_FAILED。 */
+export declare function loadPlaywright(importer?: () => Promise<PlaywrightModule>): Promise<PlaywrightModule>;
+/** 浏览器启动失败时的一行提示。 */
+export declare function launchHint(e: unknown): string;
+export declare function launch({ chromium }: PlaywrightModule): Promise<Browser>;
+export declare function renderStep(opts: RenderOptions): Promise<RenderResult>;

package/dist/render.js

@@ -0,0 +1,150 @@
+/**
+ * renderStep：用随机端口启动一次性的 dev 服务（只编译一次、不监听），Playwright 打开渲染路由，
+ * 截取舞台并返回元素索引（带 at）与渲染告警：遮挡、溢出、Toast 重叠、字体（PRD 8.8 / AC-22）。
+ * 页面读取的 IR 与这里用来计算位置、隐藏元素的 IR 是同一份（无 TOCTOU）。
+ *
+ * Playwright 是可选依赖（D36）：只在这里按需载入；没装或没有浏览器时给出安装命令，dev/check/build 不受影响。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { JoploError, SUBTITLE_HEIGHT, VIEWPORT_SIZE, displaySceneId, findNode, isNodeDisabled, nodeLabel, positionAfterStep, resolveProps, stateAt, walkNodes } from '@joplo-app/core';
+import { createDev } from "./dev.js";
+import { realProjectDir } from "./vite-shared.js";
+const STAGE_SIZE = VIEWPORT_SIZE;
+const NOT_NEEDED = 'dev、check、build 不需要它。';
+const isMissingModule = (e) => {
+    const code = e?.code;
+    return (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') && /playwright/.test(e instanceof Error ? e.message : String(e));
+};
+/** 按需载入 Playwright；没有安装时抛出带安装命令的 RENDER_FAILED。 */
+export async function loadPlaywright(importer = () => import('playwright')) {
+    try {
+        return await importer();
+    }
+    catch (e) {
+        if (!isMissingModule(e))
+            throw e;
+        throw new JoploError('RENDER_FAILED', `截图需要 Playwright 和 Chromium，当前没有安装。运行：npm i -D playwright && npx playwright install chromium（约 150 MB）。${NOT_NEEDED}`);
+    }
+}
+/** 浏览器启动失败时的一行提示。 */
+export function launchHint(e) {
+    const first = (e instanceof Error ? e.message : String(e)).split('\n')[0].trim();
+    return `截图需要 Chromium，无法启动浏览器（${first}）。运行：npx playwright install chromium（约 150 MB）。${NOT_NEEDED}`;
+}
+export async function launch({ chromium }) {
+    try {
+        return await chromium.launch({ headless: true });
+    }
+    catch (first) {
+        try {
+            return await chromium.launch({ headless: true, channel: 'chrome' });
+        }
+        catch {
+            throw new JoploError('RENDER_FAILED', launchHint(first));
+        }
+    }
+}
+/** 解析符号链接后的绝对路径；不存在的部分按原样拼接（以最近的已存在祖先为基准）。 */
+function realish(p) {
+    const abs = path.resolve(p);
+    const rest = [];
+    let cur = abs;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(cur), ...rest);
+        }
+        catch {
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return abs;
+            rest.unshift(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/** 截图不得覆盖项目源文件或 .joplo/（即使传了 overwrite）。 */
+function assertNotProjectData(projectDir, out) {
+    const fold = (p) => (process.platform === 'darwin' || process.platform === 'win32' ? p.toLowerCase() : p);
+    const o = fold(realish(out));
+    const dir = fold(realish(projectDir));
+    const dataDir = path.join(dir, '.joplo');
+    if (o === dataDir || o.startsWith(dataDir + path.sep))
+        throw new JoploError('USAGE', `不能写入项目数据：${out}（.joplo/ 由 Joplo 管理）`);
+    if (/\.(tsx?|jsx?|mts)$/.test(o) && o.startsWith(dir + path.sep))
+        throw new JoploError('USAGE', `不能用截图覆盖项目源文件：${out}`);
+}
+export async function renderStep(opts) {
+    const projectDir = realProjectDir(opts.projectDir);
+    const out = path.resolve(opts.out);
+    assertNotProjectData(projectDir, out);
+    if (fs.existsSync(out) && !opts.overwrite)
+        throw new JoploError('USAGE', `目标文件已存在：${out}。如需覆盖请传 overwrite: true（CLI：--overwrite）`);
+    // 先确认 Playwright 可用，再启动编译服务（缺失时尽快失败）
+    const playwright = await loadPlaywright();
+    const server = await createDev({ projectDir, port: 0, watch: false, log: () => undefined });
+    let browser = null;
+    try {
+        const payload = server.payload();
+        const project = payload.project;
+        if (!project) {
+            const errs = payload.diagnostics.filter((d) => d.severity === 'error');
+            throw new JoploError('INVALID_SCHEMA', `项目编译失败：${errs.map((d) => `${d.at ?? ''} ${d.message}`).join('；')}`, { diagnostics: payload.diagnostics });
+        }
+        const sc = project.scenarios[opts.scenarioId];
+        if (!sc)
+            throw new JoploError('NOT_FOUND', `场景不存在：${opts.scenarioId}（可用：${Object.keys(project.scenarios).join('、') || '无'}）`);
+        const position = opts.stepId ? positionAfterStep(project, sc.id, opts.stepId) : 0;
+        const state = stateAt(project, sc.id, position); // 回放失败会抛出 PLAYBACK_FAILED
+        // 有层级的方案：截图与元素索引用这一步导演层的画面（每层一个独立画面）
+        const scene = project.scenes[displaySceneId(project, sc.id, position)];
+        const theme = opts.theme ?? project.theme ?? 'sketch';
+        const next = state.completed ? undefined : sc.steps[position];
+        const nextTargetId = next && 'target' in next.action ? next.action.target : null;
+        const stage = STAGE_SIZE[scene.viewport === 'mobile' ? 'mobile' : 'desktop'];
+        // 舞台正下方是字幕区（与演示页一致）：页面高度加上字幕区，截图截舞台 + 字幕区
+        const viewport = opts.viewport ?? { width: stage.width, height: stage.height + SUBTITLE_HEIGHT };
+        browser = await launch(playwright);
+        const page = await browser.newPage({ viewport, deviceScaleFactor: opts.scale ?? 1, reducedMotion: 'reduce' });
+        // D44：舞台宽度固定为页面自己的 viewport；指定 viewport 时它只是截图尺寸（舞台按比例放进去）
+        const q = new URLSearchParams({ render: '1', project: server.projectId, scenario: sc.id, position: String(position), theme, ...(opts.viewport ? { w: String(opts.viewport.width), h: String(opts.viewport.height) } : {}) });
+        await page.goto(`${server.url}?${q}`, { waitUntil: 'domcontentloaded' });
+        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}`);
+        const report = (await page.evaluate(`(${COLLECT_REPORT})(${JSON.stringify({ nextTargetId, theme })})`));
+        const png = await page.locator(opts.viewport ? '[data-jshot]' : '[data-jrender]').screenshot({ type: 'png', animations: 'disabled' });
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        if (opts.overwrite)
+            fs.writeFileSync(out, png);
+        else
+            fs.writeFileSync(out, png, { flag: 'wx' });
+        // DOM 中没有的节点（隐藏/未渲染）也列入索引，visible=false
+        const seen = new Set(report.elements.map((e) => e.id));
+        const hidden = [];
+        walkNodes(scene.root, (node) => {
+            if (seen.has(node.id) || node.type === '#text')
+                return;
+            hidden.push({
+                id: node.id,
+                type: node.type,
+                label: nodeLabel({ type: node.type, props: resolveProps(node, state), children: node.children }),
+                visible: false,
+                disabled: isNodeDisabled(node, state),
+                at: node.source ?? null,
+                box: { x: 0, y: 0, width: 0, height: 0 },
+            });
+        });
+        const elements = [...report.elements, ...hidden];
+        const warnings = [...report.warnings];
+        if (nextTargetId && findNode(scene, nextTargetId) && !elements.find((e) => e.id === nextTargetId && e.visible))
+            warnings.push(`下一步操作的目标 ${nextTargetId} 没有显示在画面中`);
+        return { path: out, sceneId: scene.id, position, elements, warnings, scale: opts.scale ?? 1 };
+    }
+    finally {
+        await browser?.close().catch(() => undefined);
+        await server.close();
+    }
+}
+const COLLECT_REPORT = fs.readFileSync(path.join(import.meta.dirname, 'page-report.js'), 'utf8').replace(/^\/\*[\s\S]*?\*\/\s*/, '');

package/dist/selection.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { type Project, type Selection } from '@joplo-app/core';
+/** 浏览器提交的选中（服务端补全其余字段）。 */
+export declare const SelectionInput: z.ZodObject<{
+    optionId: z.ZodNullable<z.ZodString>;
+    scenarioId: z.ZodNullable<z.ZodString>;
+    position: z.ZodNumber;
+    sceneId: z.ZodString;
+    nodeId: z.ZodNullable<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type SelectionInput = z.infer<typeof SelectionInput>;
+export declare const SelectionBody: z.ZodObject<{
+    selection: z.ZodNullable<z.ZodObject<{
+        optionId: z.ZodNullable<z.ZodString>;
+        scenarioId: z.ZodNullable<z.ZodString>;
+        position: z.ZodNumber;
+        sceneId: z.ZodString;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** 对照当前 IR 校验并补全；返回 Selection 或问题描述。 */
+export declare function resolveSelection(project: Project, input: SelectionInput, now?: Date): {
+    ok: true;
+    selection: Selection;
+} | {
+    ok: false;
+    problem: string;
+};
+/** 临时文件 + rename 的原子写入。 */
+export declare function writeFileAtomic(file: string, data: string): void;
+export declare const selectionFile: (projectDir: string) => string;
+export declare function writeSelection(projectDir: string, sel: Selection | null): void;
+export declare function readSelection(projectDir: string): Selection | null;

package/dist/selection.js

@@ -0,0 +1,123 @@
+/**
+ * 看板写入 `.joplo/selection.json`（core 的 Selection 类型）。
+ *
+ * 流向：看板 DOM 的 data-jat → 浏览器提交「选中了谁」→ 这里对照当前 IR 校验，并由服务端
+ * 重新计算 at / label / route / featureId（不信任浏览器给的 at）→ 原子写入文件 → `joplo selection` 读取。
+ *
+ * 不变量：每次写接口返回后，selection.json 与界面显示的选中一致。被拒绝（409）时服务端写入 null，
+ * 并在响应里返回 `current: null`，看板据此清除选中并明确提示。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { findNode, nodeLabel, stateAt, walkNodes } from '@joplo-app/core';
+/** 浏览器提交的选中（服务端补全其余字段）。 */
+export const SelectionInput = z.strictObject({
+    optionId: z.string().min(1).max(256).nullable(),
+    scenarioId: z.string().min(1).max(256).nullable(),
+    position: z.number().int().nonnegative().max(10000),
+    sceneId: z.string().min(1).max(256),
+    nodeId: z.string().min(1).max(128).nullable(),
+    /** 只选中步骤（审阅模式点步骤芯片）时给出。 */
+    stepId: z.string().min(1).max(300).nullable().optional(),
+});
+export const SelectionBody = z.strictObject({ selection: SelectionInput.nullable() });
+/** 对照当前 IR 校验并补全；返回 Selection 或问题描述。 */
+export function resolveSelection(project, input, now = new Date()) {
+    let sceneId = input.sceneId;
+    let stepId = null;
+    let featureId = null;
+    const optionId = input.optionId;
+    if (optionId !== null) {
+        const opt = project.options[optionId];
+        if (!opt)
+            return { ok: false, problem: `方案 ${optionId} 不存在` };
+        featureId = opt.featureId;
+    }
+    if (input.scenarioId !== null) {
+        const sc = project.scenarios[input.scenarioId];
+        if (!sc)
+            return { ok: false, problem: `场景 ${input.scenarioId} 不存在` };
+        if (optionId !== sc.optionId)
+            return { ok: false, problem: `场景 ${sc.id} 不属于方案 ${optionId ?? '(无)'}` };
+        if (input.position > sc.steps.length)
+            return { ok: false, problem: `位置 ${input.position} 超出场景 ${sc.id} 的范围 0..${sc.steps.length}` };
+        try {
+            sceneId = stateAt(project, sc.id, input.position).sceneId;
+        }
+        catch (e) {
+            return { ok: false, problem: `场景 ${sc.id} 无法回放到位置 ${input.position}：${e instanceof Error ? e.message : String(e)}` };
+        }
+        // 有层级的方案：用户看的是某一层的画面（各层共享同一份状态），也接受
+        const layerScenes = Object.values(project.options[sc.optionId]?.layers ?? {}).map((l) => l.sceneId);
+        if (layerScenes.includes(input.sceneId))
+            sceneId = input.sceneId;
+        if (input.sceneId !== sceneId)
+            return { ok: false, problem: `位置 ${input.position} 的画面是 ${sceneId}，不是 ${input.sceneId}` };
+        stepId = sc.steps[input.position - 1]?.id ?? null;
+        if (input.stepId) {
+            if (!sc.steps.some((s) => s.id === input.stepId))
+                return { ok: false, problem: `步骤 ${input.stepId} 不在场景 ${sc.id} 中` };
+            stepId = input.stepId;
+        }
+    }
+    else if (input.position !== 0 || input.stepId)
+        return { ok: false, problem: '没有场景时位置必须为 0，且不能选中步骤' };
+    const scene = project.scenes[sceneId];
+    if (!scene)
+        return { ok: false, problem: `画面 ${sceneId} 不存在` };
+    if (input.scenarioId === null && optionId !== null && scene.optionId !== optionId && scene.optionId !== null)
+        return { ok: false, problem: `画面 ${sceneId} 不属于方案 ${optionId}` };
+    let at = null;
+    let label = null;
+    if (input.nodeId) {
+        const hit = findNode(scene, input.nodeId);
+        if (!hit)
+            return { ok: false, problem: `元素 ${input.nodeId} 不在画面 ${sceneId} 中` };
+        at = hit.node.source ?? null;
+        label = nodeLabel(hit.node); // Mantine 输入组件直接带 label 属性
+    }
+    else if (input.stepId && input.scenarioId) {
+        const st = project.scenarios[input.scenarioId].steps.find((s) => s.id === input.stepId);
+        at = st.source ?? null;
+        label = st.caption;
+    }
+    else
+        return { ok: false, problem: '选中必须指向一个元素或一个步骤' };
+    return {
+        ok: true,
+        selection: {
+            featureId,
+            optionId,
+            scenarioId: input.scenarioId,
+            position: input.position,
+            stepId,
+            sceneId,
+            route: scene.route,
+            nodeId: input.nodeId,
+            at,
+            label,
+            selectedAt: now.toISOString(),
+        },
+    };
+}
+/** 临时文件 + rename 的原子写入。 */
+export function writeFileAtomic(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+}
+export const selectionFile = (projectDir) => path.join(projectDir, '.joplo', 'selection.json');
+export function writeSelection(projectDir, sel) {
+    writeFileAtomic(selectionFile(projectDir), JSON.stringify(sel, null, 2) + '\n');
+}
+export function readSelection(projectDir) {
+    try {
+        return JSON.parse(fs.readFileSync(selectionFile(projectDir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/vite-shared.d.ts

@@ -0,0 +1,29 @@
+import { type Plugin } from 'vite';
+import { type WebAssets } from './web-assets.js';
+export { kitAliases, locateWebAssets } from './web-assets.js';
+/** 项目目录统一用真实路径（macOS 的 /tmp → /private/tmp），保证 jsxDEV 与调用栈给出的路径能被 relSource 转成相对路径。 */
+export declare function realProjectDir(dir: string): string;
+/** 不参与编译的项目子目录。 */
+export declare const IGNORED_DIRS: string[];
+export declare function isProjectSource(projectDir: string, file: string): boolean;
+/** 语法错误的位置：从转译器报错里取 `文件:行:列`。 */
+export type SourceLoc = {
+    file: string;
+    line: number;
+    column: number;
+};
+export declare class ProjectSyntaxError extends Error {
+    readonly loc: SourceLoc;
+    constructor(message: string, loc: SourceLoc);
+}
+export declare function parseErrorLoc(message: string, file: string): {
+    line: number;
+    column: number;
+} | null;
+/** 作者 className 的 CSS 入口：追加每个项目目录为 Tailwind @source（看板进程同时服务多个项目）。 */
+export declare function cssSourcePlugin(dirs: () => string[], web?: WebAssets): Plugin;
+/**
+ * 转译项目源文件（TSX → 收集数据的 JS）；把 Tailwind @source 指向项目目录。
+ * dist 形态下 CSS 入口是 @joplo-app/web/dist/project.css，其中的 `@import "tailwindcss"` 改为从 server 的依赖解析。
+ */
+export declare function joploProjectPlugin(projectDir: string, web?: WebAssets): Plugin;

package/dist/vite-shared.js

@@ -0,0 +1,100 @@
+/**
+ * dev / build / render 共用的 Vite 配置片段。
+ *
+ * - 看板与发布站的界面源码在 packages/web（Vite root）。
+ * - 项目源文件（作者的 TSX）只在服务端经 ssrLoadModule 载入：用 automatic JSX、
+ *   jsxImportSource '@joplo-app/kit'、development=true 转译，jsxDEV 因此拿到 文件:行:列。
+ * - Tailwind 需要编译项目源文件里出现的 className：把项目目录追加为 index.css 的 @source。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { transformWithOxc } from 'vite';
+import { cssEntry, locateWebAssets, tailwindIndexCss } from "./web-assets.js";
+export { kitAliases, locateWebAssets } from "./web-assets.js";
+/** 项目目录统一用真实路径（macOS 的 /tmp → /private/tmp），保证 jsxDEV 与调用栈给出的路径能被 relSource 转成相对路径。 */
+export function realProjectDir(dir) {
+    const abs = path.resolve(dir);
+    try {
+        return fs.realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** 不参与编译的项目子目录。 */
+export const IGNORED_DIRS = ['.joplo', 'dist', 'node_modules', '.git'];
+export function isProjectSource(projectDir, file) {
+    if (!file.startsWith(projectDir + path.sep))
+        return false;
+    const rel = file.slice(projectDir.length + 1);
+    const first = rel.split(path.sep)[0] ?? '';
+    return !IGNORED_DIRS.includes(first);
+}
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+export class ProjectSyntaxError extends Error {
+    loc;
+    constructor(message, loc) {
+        super(message);
+        this.name = 'ProjectSyntaxError';
+        this.loc = loc;
+    }
+}
+export function parseErrorLoc(message, file) {
+    const text = stripAnsi(message);
+    const base = path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const m = new RegExp(`${base}:(\\d+):(\\d+)`).exec(text) ?? /:(\d+):(\d+)/.exec(text);
+    return m ? { line: Number(m[1]), column: Number(m[2]) } : null;
+}
+/** 作者 className 的 CSS 入口：追加每个项目目录为 Tailwind @source（看板进程同时服务多个项目）。 */
+export function cssSourcePlugin(dirs, web = locateWebAssets()) {
+    const entry = cssEntry(web);
+    return {
+        name: 'joplo:css-sources',
+        enforce: 'pre',
+        transform(code, id) {
+            if (id.split('?')[0] !== entry)
+                return;
+            const css = web.mode === 'dist' ? code.replace(/@import\s+["']tailwindcss["']/, `@import ${JSON.stringify(tailwindIndexCss())}`) : code;
+            return { code: `${css}\n${dirs().map((d) => `@source ${JSON.stringify(d)};`).join('\n')}\n`, map: null };
+        },
+    };
+}
+/**
+ * 转译项目源文件（TSX → 收集数据的 JS）；把 Tailwind @source 指向项目目录。
+ * dist 形态下 CSS 入口是 @joplo-app/web/dist/project.css，其中的 `@import "tailwindcss"` 改为从 server 的依赖解析。
+ */
+export function joploProjectPlugin(projectDir, web = locateWebAssets()) {
+    const entry = cssEntry(web);
+    return {
+        name: 'joplo:project',
+        enforce: 'pre',
+        async transform(code, id) {
+            const file = id.split('?')[0];
+            if (file === entry) {
+                // Tailwind v4：@source 绝对路径；JSON.stringify 负责转义引号与反斜杠
+                const css = web.mode === 'dist' ? code.replace(/@import\s+["']tailwindcss["']/, `@import ${JSON.stringify(tailwindIndexCss())}`) : code;
+                return { code: `${css}\n@source ${JSON.stringify(projectDir)};\n`, map: null };
+            }
+            if (!isProjectSource(projectDir, file) || !/\.(tsx|ts|jsx|js|mts)$/.test(file))
+                return;
+            const lang = file.endsWith('.tsx') ? 'tsx' : file.endsWith('.jsx') ? 'jsx' : file.endsWith('.js') ? 'js' : 'ts';
+            try {
+                const r = await transformWithOxc(code, file, {
+                    lang,
+                    jsx: { runtime: 'automatic', importSource: '@joplo-app/kit', development: true },
+                    sourcemap: true,
+                });
+                return { code: r.code, map: r.map ?? null };
+            }
+            catch (e) {
+                const raw = e instanceof Error ? e.message : String(e);
+                const errs = e.errors;
+                const first = stripAnsi(errs?.[0]?.message ?? raw);
+                const loc = parseErrorLoc(first, file) ?? { line: 1, column: 1 };
+                const rel = path.relative(projectDir, file).split(path.sep).join('/');
+                const brief = (first.split('\n')[0] ?? '').replace(/^\s*\[[A-Z_]+\]\s*/, '').trim();
+                throw new ProjectSyntaxError(`${rel}:${loc.line}:${loc.column} 语法错误：${brief || '无法解析'}`, { file, ...loc });
+            }
+        },
+    };
+}

package/dist/web-assets.d.ts

@@ -0,0 +1,35 @@
+import type { Alias } from 'vite';
+export type SourceWeb = {
+    mode: 'source';
+    webDir: string;
+    indexCss: string;
+    kitSrc: string;
+};
+export type DistWeb = {
+    mode: 'dist';
+    webDir: string;
+    /** 看板 index.html 与发布站 site.html 所在目录（Vite 开发服务的 root）。 */
+    appDir: string;
+    /** 发布站需要复制的文件（相对 appDir）。 */
+    siteFiles: string[];
+    /** 作者 className 的 Tailwind 入口。 */
+    projectCss: string;
+    version: string;
+};
+export type WebAssets = SourceWeb | DistWeb;
+/** 读取并校验 @joplo-app/web 的 dist/manifest.json。 */
+export declare function readWebDist(webDir: string): DistWeb;
+/** 看板与发布站资源。结果按进程缓存（env 只在首次调用时生效；测试可传入 env 绕过缓存）。 */
+export declare function locateWebAssets(env?: Record<string, string | undefined>): WebAssets;
+/** 作者 className 的 CSS 入口（source：packages/web/src/index.css；dist：@joplo-app/web/dist/project.css）。 */
+export declare const cssEntry: (web: WebAssets) => string;
+/** Tailwind 的 index.css，从 server 自己的依赖解析（pnpm 严格布局下 @joplo-app/web 没有 tailwindcss 依赖）。 */
+export declare function tailwindIndexCss(): string;
+/** 从 dir 起向上找 node_modules/<name>/package.json（与 Node 的包解析顺序一致，不依赖 exports）。 */
+export declare function findPackageJson(dir: string, name: string): string | null;
+/**
+ * 项目源文件里的 `@joplo-app/kit` 怎样解析：
+ * - source：指向仓库里的 kit 源码（项目可在任意目录，不需要自己的 node_modules）；`@/` 指向 web 源码。
+ * - dist：项目装了 @joplo-app/kit 就按项目依赖解析（与 `joplo check` 用的 tsx 一致）；没装则退回 CLI 自带的 kit。
+ */
+export declare function kitAliases(web: WebAssets, projectDir: string): Alias[];