cardbuddy 0.6.0

package/dist/server-core/renderStatus.js

@@ -0,0 +1,207 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { createSSRApp, h } from 'vue'
+import { renderToString } from '@vue/server-renderer'
+
+/**
+ * SSR 渲染自检端点（L0 闭环之一）：
+ * - GET /__render-status/<id> → 用 dev server 自身 vite 实例 ssrLoadModule 渲染，
+ *   返回结构统计 + 绑定/运行时/渲染错误 + JSAPI 清单（静态扫描 schema 的 callJSAPI）。
+ * - 复用 vite 实例（省冷启动、HMR 生效）；语义边界：只保证「结构合法 + 绑定可解析 +
+ *   渲染不抛错」，视觉正确性交给 /__screenshot。错误来源：bindingErrors 读 buffer
+ *   （SSR 不跑 mounted）、runtimeErrors 读 rt.eventErrors（created 已执行 load-action）、
+ *   renderErrors 走 app.config.errorHandler。
+ */
+
+/** 递归统计 schema 组件树：分布 + 未知组件(metaMissing) */
+function walkSchema(node, dist, metaMissing, getComponent) {
+  if (!node || typeof node !== 'object') return
+  const cn = node.className
+  if (cn) {
+    dist[cn] = (dist[cn] || 0) + 1
+    if (getComponent && !getComponent(cn) && !metaMissing.includes(cn)) metaMissing.push(cn)
+  }
+  const comps = node.components || []
+  for (const c of comps) walkSchema(c, dist, metaMissing, getComponent)
+  for (const slot of node.slots || []) {
+    for (const c of slot.components || []) walkSchema(c, dist, metaMissing, getComponent)
+  }
+}
+
+/** 组件树指纹：className+componentId 序列的 sha1 前 12 位，供版本 diff */
+function structureDigest(view) {
+  const parts = []
+  const rec = (node) => {
+    if (!node || typeof node !== 'object') return
+    parts.push(`${node.className || '?'}:${node.componentId || ''}`)
+    for (const c of node.components || []) rec(c)
+    for (const slot of node.slots || []) for (const c of slot.components || []) rec(c)
+  }
+  rec(view)
+  return 'sha1:' + crypto.createHash('sha1').update(parts.join('|')).digest('hex').slice(0, 12)
+}
+
+/** 静态扫描 schema 里所有 callJSAPI('x') 调用，去重 */
+function scanJsapi(schema) {
+  const text = JSON.stringify(schema)
+  const re = /callJSAPI\(\s*['"]([\w]+)['"]/g
+  const set = new Set()
+  let m
+  while ((m = re.exec(text))) set.add(m[1])
+  return [...set]
+}
+
+/**
+ * 渲染单卡并返回自检结果。纯函数、无 HTTP，便于 CI 的 card-check 直接复用。
+ * @param {import('vite').ViteDevServer} viteServer 含 ssrLoadModule 的 vite 实例
+ * @param {string} id 卡片 id
+ * @param {string} dir 卡片目录（含 schema.json / data.json）
+ */
+export async function renderStatusFor(viteServer, id, dir) {
+  const t0 = Date.now()
+  let schema
+  try {
+    schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
+  } catch (e) {
+    return { id, ok: false, fatal: 'schema-parse-error', message: String(e && e.message), durationMs: Date.now() - t0 }
+  }
+  let data = null
+  try {
+    data = JSON.parse(fs.readFileSync(path.join(dir, 'data.json'), 'utf8'))
+  } catch {
+    /* 无 data.json 时以空作用域渲染，绑定错误会据此暴露 */
+  }
+
+  // 每次请求都走 ssrLoadModule：模块未失效时 Vite 直接返回缓存（无重编译），
+  // 被 HMR 失效后自动返回新版 —— 兼顾性能与「改 preview/runtime 免重启」。
+  const { default: RenderTree } = await viteServer.ssrLoadModule('/components/RenderTree.vue')
+  const { default: Adapter } = await viteServer.ssrLoadModule('/runtime/adapter.js')
+  const { createCardRuntime } = await viteServer.ssrLoadModule('/runtime/card-runtime.js')
+  const { buildPreview } = await viteServer.ssrLoadModule('/runtime/toPreview.js')
+  const { getComponent } = await viteServer.ssrLoadModule('/components/index.js')
+
+  const adapter = new Adapter()
+  const rt = createCardRuntime(data || {}, adapter)
+  const preview = buildPreview(schema)
+
+  // SSR 沙箱：卡片 customAction 脚本（含 setTimeout 里）会直接引用全局 `ynet` /
+  // `window` / `self`（宿主运行时提供，SSR 下本不存在）。不 mock 会在 created()
+  // 同步执行或异步定时器触发时报 ReferenceError 炸进程。这里补上与浏览器一致的
+  // 桩，并**持久保留**（不还原）——因为 setTimeout 在 renderToString 之后才触发。
+  // 这是预期内的「SSR 无真实运行时」兜底，不影响错误收集。
+  const ynetMock = {
+    callJSAPI(api, p, cb) {
+      try {
+        rt.pushApiCall(api, p)
+      } catch {
+        /* ignore */
+      }
+      if (typeof cb === 'function') {
+        try {
+          cb({})
+        } catch {
+          /* ignore */
+        }
+      }
+    },
+  }
+  if (typeof globalThis.ynet === 'undefined') globalThis.ynet = ynetMock
+  if (typeof globalThis.window === 'undefined') {
+    globalThis.window = { innerWidth: 375, devicePixelRatio: 2, ynet: ynetMock }
+  }
+  if (typeof globalThis.self === 'undefined') globalThis.self = globalThis.window
+
+  const componentDist = {}
+  const metaMissing = []
+  walkSchema(schema.view, componentDist, metaMissing, getComponent)
+  const componentCount = Object.values(componentDist).reduce((a, b) => a + b, 0)
+
+  const wrapper = {
+    name: 'RenderStatusWrapper',
+    provide() {
+      return { adapter, cardRuntime: rt, customComponents: {} }
+    },
+    render() {
+      return h(RenderTree, { node: preview.view, scope: rt.rootScope })
+    },
+  }
+  const app = createSSRApp(wrapper)
+  const renderErrors = []
+  app.config.errorHandler = (err, vm, info) => {
+    renderErrors.push(`${info}: ${err && err.message}`)
+  }
+
+  // runLoadActions 在 created 里执行 customAction，会触发 console.error；
+  // 这些内容 rt 已结构化收集，这里静音避免刷屏（全局 console 短时替换，影响可忽略）。
+  const origErr = console.error
+  console.error = () => {}
+  let html = ''
+  let threw = null
+  try {
+    html = await renderToString(app)
+  } catch (e) {
+    threw = { message: e && e.message, stack: (e && e.stack ? String(e.stack).split('\n').slice(0, 3) : []) }
+  } finally {
+    console.error = origErr
+  }
+
+  const bindingErrors = (rt.getBindingBuffer() || []).map((e) => ({
+    path: e.path,
+    expr: e.expr,
+    message: e.msg,
+  }))
+  const runtimeErrors = [...(rt.eventErrors || []), ...(rt.errors || [])].map((e) => ({
+    kind: e.kind,
+    msg: e.msg,
+  }))
+  const jsapiCalls = scanJsapi(schema)
+  const renderOk = renderErrors.length === 0 && !threw
+  // 约定：ok 反映「渲染不抛错」。bindingErrors 单独列出——SSR 下异步数据缺失会
+  // 产生误报（卡片在真实运行时由 customAction/RPC 补数据），故不计入 ok，避免 CI 泛洪。
+  const ok = renderOk
+
+  return {
+    id,
+    ok,
+    renderOk,
+    bindingErrorCount: bindingErrors.length,
+    componentCount,
+    componentDist,
+    metaMissing,
+    structureDigest: structureDigest(schema.view),
+    bindingErrors,
+    runtimeErrors,
+    renderErrors,
+    jsapiCalls,
+    htmlLength: html.length,
+    durationMs: Date.now() - t0,
+    threw,
+  }
+}
+
+export function createRenderStatusMiddleware({ root, viteServer }) {
+  return async function renderStatusMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__render-status\/([^/]+)$/)
+    if (!m) return next()
+    const id = decodeURIComponent(m[1])
+    const dir = path.join(root, 'src', 'cards', id)
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'card not found', id }))
+    }
+    try {
+      const status = await renderStatusFor(viteServer, id, dir)
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify(status))
+    } catch (e) {
+      res.statusCode = 500
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'render-status failed', id, message: String(e && e.message) }))
+    }
+  }
+}

package/dist/server-core/screenshot.js

@@ -0,0 +1,123 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import { getBrowser, serialize, openCardScreen, MAX_QUEUED } from './browser.js'
+
+/**
+ * 无头截图端点（L0 闭环之一，Step 4）：GET /__screenshot/<id>?width=390&format=png|json，
+ * 仅截卡片根（.phone__screen）。要点：①固定 chromium.launch({channel:'chrome'}) 走系统 Chrome；
+ * ②等 [data-card-ready] 而非 networkidle；③截图只代表「真实画出」，视觉正确性以截图为准
+ * （互补 /__render-status 的结构/绑定检查）；④单例浏览器 + 串行队列，>10 排队 429；
+ * ⑤惰性启动 + 空闲 5 分钟关闭；⑥失败一律结构化响应（429/500/503/504），不抛未捕获异常；
+ * ⑦Chrome 缺失返回 503 + 修复指引。playwright 动态 import（build 不依赖它）。
+ * 浏览器单例/页面加载逻辑已抽到 ./browser.js，与 /__bbox 共用同一实例。
+ */
+
+/**
+ * 对单卡截图。纯函数、无 HTTP。任何失败都返回 { error, code, message, ... } 而非抛出。
+ * @param {string} id 卡片 id
+ * @param {number} width 视口宽度（卡片框固定 375px，这里给外层留白）
+ * @param {'png'|'json'} format
+ */
+export async function takeScreenshot(id, width, format) {
+  let browser
+  try {
+    browser = await getBrowser()
+  } catch (e) {
+    return {
+      error: 'browser-launch-failed',
+      code: 503,
+      message: String((e && e.message) || e),
+      fix: '系统 Chrome 未找到或未启动。请安装 Google Chrome，并确保 playwright 以 channel:"chrome" 启动（本端点固定使用该通道）。',
+    }
+  }
+
+  let context
+  try {
+    context = await browser.newContext({
+      viewport: { width: width + 80, height: 800 },
+      deviceScaleFactor: 2,
+    })
+    const { page, screen } = await openCardScreen(context, id)
+    try {
+      if (!screen) {
+        return { error: 'capture-target-not-found', code: 500, message: '.phone__screen 元素未找到' }
+      }
+
+      const buf = await screen.screenshot({ type: 'png' })
+      if (format === 'json') {
+        const box = await screen.boundingBox()
+        return {
+          json: {
+            id,
+            mime: 'image/png',
+            width: box ? Math.round(box.width) : null,
+            height: box ? Math.round(box.height) : null,
+            base64: buf.toString('base64'),
+          },
+        }
+      }
+      return { buffer: buf }
+    } finally {
+      await page.close().catch(() => {})
+    }
+  } catch (e) {
+    // 导航超时 / data-card-ready 未出现 / 截图异常：转成结构化错误，绝不向上抛
+    const isTimeout = /Timeout\s*\d+ms exceeded/.test(String((e && e.message) || e))
+    return {
+      error: isTimeout ? 'render-wait-timeout' : 'screenshot-failed',
+      code: isTimeout ? 504 : 500,
+      message: String((e && e.message) || e),
+      fix: isTimeout
+        ? '卡片首帧未在限定时间内挂载（data-card-ready 未出现）。检查该卡是否在 chrome=off 模式下渲染报错，或卡片依赖真实运行时数据（customAction/RPC）而无法在纯渲染模式落定。'
+        : undefined,
+    }
+  } finally {
+    if (context) await context.close().catch(() => {})
+  }
+}
+
+export function createScreenshotMiddleware({ root }) {
+  return async function screenshotMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__screenshot\/([^/]+)$/)
+    if (!m) return next()
+    const id = decodeURIComponent(m[1])
+
+    const dir = path.join(root, 'src', 'cards', id)
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'card not found', id }))
+    }
+
+    const url = new URL(req.url, 'http://localhost')
+    const width = parseInt(url.searchParams.get('width') || '390', 10) || 390
+    const format = url.searchParams.get('format') === 'json' ? 'json' : 'png'
+
+    const result = await serialize(() => takeScreenshot(id, width, format))
+    if (result.tooBusy) {
+      res.statusCode = 429
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(
+        JSON.stringify({ error: 'too-busy', message: '截图队列已满（并发上限 ' + MAX_QUEUED + '），请稍后重试' }),
+      )
+    }
+    if (result.error) {
+      const code = result.code || 503
+      res.statusCode = code
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: result.error, message: result.message, fix: result.fix }))
+    }
+
+    if (format === 'json') {
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify(result.json))
+    }
+    res.statusCode = 200
+    res.setHeader('Content-Type', 'image/png')
+    res.setHeader('Cache-Control', 'no-store')
+    return res.end(result.buffer)
+  }
+}

package/dist/server-core/sliceStatic.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * 切图本地静态服务（issue-slices）：把卡片 schema 引用的 /slices/<扁平名>@3x.png
+ * 映射到仓库级单一落点 src/slices/<扁平名>@3x.png。
+ *
+ * 与 dsl-card-generator 的「切图统一输出到 src/slices + schema 以 /slices/ 引用」约定对齐。
+ * 该中间件同时挂到两处：
+ *   - Vite(5180)：编辑器预览同源访问 /slices/*；
+ *   - cardbuddy(8787)：本地开发服务若直接托管预览页，也能取到切图。
+ * 仅服务本地生成产物，不做任何远端回源（远端切图走 assetProxy 的 /minio 等前缀）。
+ */
+
+const MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.gif': 'image/gif',
+}
+
+/**
+ * @param {{ root: string }} opts  root = 仓库根（含 src/slices）
+ * @returns {(req, res, next) => void}
+ */
+export function createSliceStaticMiddleware({ root }) {
+  const slicesRoot = path.join(root, 'src', 'slices')
+  return (req, res, next) => {
+    const url = (req.url || '').split('?')[0]
+    if (!url.startsWith('/slices/')) return next()
+    const rel = decodeURIComponent(url.slice('/slices/'.length))
+    // 防目录穿越：禁止 .. 且解析后必须仍在 src/slices 内
+    if (rel.includes('..')) return next()
+    const file = path.join(slicesRoot, rel)
+    if (!file.startsWith(slicesRoot + path.sep) && file !== slicesRoot) return next()
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return next()
+    const ext = path.extname(file).toLowerCase()
+    res.setHeader('Content-Type', MIME[ext] || 'application/octet-stream')
+    res.setHeader('Cache-Control', 'public, max-age=0')
+    fs.createReadStream(file).pipe(res)
+  }
+}