dsh-piggy 0.25.0

package/render.js

@@ -0,0 +1,357 @@
+// @ts-check
+/**
+ * dsh-piggy · render — every word the pig says.
+ *
+ * Pure string building: the command handlers, the HTTP actions, the tests and
+ * the client bubble all read from here, so the pig's voice lives in exactly one
+ * file.
+ *
+ * @module dsh-piggy/render
+ */
+
+import {
+  ACTIONS,
+  ACTION_ORDER,
+  JOBS,
+  MAX,
+  REVIVE_ITEM,
+  SCHOOL_STAGES,
+  SHOP,
+  SUBJECTS,
+  TRAITS,
+  TRAIT_ORDER,
+  TRIPS,
+  actionCooldownSeconds,
+  activitySecondsLeft,
+  bar,
+  courseView,
+  formatWeight,
+  healthPercent,
+  levelProgress,
+  formStageView,
+  mood,
+  outingGrowth,
+  traitView,
+} from './core.js'
+import { STUDY_GROWTH_PER_LESSON, illnessAt } from './data.js'
+
+const RULE = '━━━━━━━━━━━━━━━━━━━━━━━━━━'
+
+/** Which portrait face matches the mood. */
+function face(currentMood) {
+  switch (currentMood.key) {
+    case 'sleepy': return { l: '˘', r: '˘', m: 'ω' }
+    case 'hungry': return { l: '◕', r: '◕', m: 'o' }
+    case 'dirty': return { l: 'ò', r: 'ó', m: '益' }
+    case 'sick': return { l: '×', r: '×', m: '︿' }
+    case 'dead': return { l: '×', r: '×', m: '︵' }
+    case 'working': return { l: '•', r: '•', m: 'ω' }
+    case 'happy': return { l: '^', r: '^', m: 'ω' }
+    case 'lonely': return { l: '◕', r: '◕', m: '︵' }
+    default: return { l: '◕', r: '◕', m: 'ω' }
+  }
+}
+
+/** The pig, with a face that follows the mood. */
+export function portrait(stage, currentMood) {
+  if (stage.key === 'box') {
+    return [
+      '      🥚',
+      '   ╭───────╮',
+      '   │  〜〜  │',
+      '   ╰───────╯',
+    ]
+  }
+  const f = face(currentMood)
+  const hat = currentMood.key === 'working' ? ' 💼' : currentMood.key === 'dead' ? ' 💀' : ''
+  return [
+    `      ${stage.emoji}${hat}`,
+    '   ╭───────╮',
+    `   │ ${f.l}   ${f.r} │`,
+    `   │   ${f.m}   │`,
+    '   ╰───────╯',
+  ]
+}
+
+function xpLine(state) {
+  const progress = levelProgress(state.xp)
+  return progress.maxed
+    ? `✨ 成长  ${Math.floor(state.xp)}   Lv.${progress.level}（满级）`
+    : `✨ 成长  ${Math.floor(state.xp)}   Lv.${progress.level} · 还差 ${Math.ceil(progress.toNext)} 升级`
+}
+
+function statusLine(state, nowMs) {
+  if (state.dead) return '💀 状态  已经走了 · 用 ' + REVIVE_ITEM.label + ' 可以救回来'
+  if (state.activity !== null) {
+    const left = activitySecondsLeft(state, nowMs)
+    const kind = state.activity.kind === 'study' ? '上课' : state.activity.kind === 'trip' ? '旅行' : '打工'
+    return `${state.activity.emoji} ${kind}  ${state.activity.label}中 · 还有 ${left} 秒`
+  }
+  const ill = state.illness === null ? null : illnessAt(state.illness.chain, state.illness.stage)
+  if (ill !== null) return `🤒 生病  ${ill.name}（第 ${ill.stage}/4 期）· 需要「${ill.cure}」`
+  return null
+}
+
+/** The three QQ Pet traits, as one line. */
+function traitsLine(state) {
+  const traits = traitView(state)
+  return TRAIT_ORDER
+    .map(key => `${TRAITS[key].emoji} ${TRAITS[key].label} ${traits[key]}`)
+    .join('   ')
+}
+
+function memoriesBlock(state) {
+  if (state.memories.length === 0) return []
+  return ['', '🕘 最近', ...state.memories.slice(-4).map(line => `   ${line}`)]
+}
+
+/** The full `/pig` card. */
+export function renderStatus(state, nowMs) {
+  const stage = formStageView(state, nowMs)
+  const current = mood(state, nowMs)
+  const special = statusLine(state, nowMs)
+  const days = (nowMs - state.bornAt) / 86_400_000
+  const age = state.hatched !== true ? '还没拆开' : (days < 1 ? '今天刚出生' : `${Math.floor(days)} 天大`)
+  const lines = [
+    `${stage.emoji} ${state.name}  ${stage.label} · ${age}   ${current.emoji} ${current.label}`,
+    RULE,
+    `🍚 饱食  ${bar(state.satiety)}  ${Math.round(state.satiety)}`,
+    `❤️  心情  ${bar(state.happiness)}  ${Math.round(state.happiness)}`,
+    `🫧 清洁  ${bar(state.cleanliness)}  ${Math.round(state.cleanliness)}`,
+    `💚 健康  ${bar(healthPercent(state))}  ${state.health}/${MAX.health}`,
+    `🪙 金币  ${state.coins}`,
+    `⚖️  体重  ${formatWeight(state.weightG)}`,
+    xpLine(state),
+    traitsLine(state),
+  ]
+  if (special !== null) lines.push(RULE, special)
+  lines.push(
+    RULE,
+    ...portrait(stage, current),
+    `    「${stage.line}」`,
+    RULE,
+    '🍽  完成回合 +5 · 发消息 +2 · 工具调用 +3 · 报错也长肉',
+    '👆  右下角的猪点着就能养：喂食 · 洗澡 · 玩耍 · 打工 · 商店',
+  )
+  return [...lines, ...memoriesBlock(state)].join('\n')
+}
+
+/** The hatching ceremony. */
+export function renderHatch(state, nowMs) {
+  const stage = formStageView(state, nowMs)
+  return [
+    '   纸盒打开了 ——',
+    '',
+    ...portrait(stage, mood(state, nowMs)),
+    '',
+    `✨ ${stage.emoji} ${state.name} 蹦了出来（${stage.label}）`,
+    `   「${stage.line}」`,
+    '',
+    `初始盘缠：🪙 ${state.coins} 金币。`,
+    '正常干活就能养活它；右下角的猪点一下就能喂食、洗澡、送去打工。',
+  ].join('\n')
+}
+
+/** One care action's outcome card. */
+export function renderAction(state, nowMs, action, crossed) {
+  const spec = ACTIONS[action]
+  if (spec === undefined) return '🐖 不认识这个动作。'
+  const current = mood(state, nowMs)
+  const lines = [
+    `${state.name} ${spec.verb}`,
+    '',
+    ...portrait(formStageView(state, nowMs), current),
+    '',
+    `🍚 饱食  ${bar(state.satiety)}  ${Math.round(state.satiety)}`,
+    `❤️  心情  ${bar(state.happiness)}  ${Math.round(state.happiness)}`,
+    `🫧 清洁  ${bar(state.cleanliness)}  ${Math.round(state.cleanliness)}`,
+  ]
+  const wait = actionCooldownSeconds(state, action, nowMs)
+  if (wait > 0) lines.push('', `（${wait} 秒后还能再来一次）`)
+  return lines.join('\n')
+}
+
+/** The refusal card when a care action is still cooling down. */
+export function renderTooSoon(state, nowMs, action) {
+  const spec = ACTIONS[action]
+  if (spec === undefined) return '🐖 不认识这个动作。'
+  const wait = actionCooldownSeconds(state, action, nowMs)
+  const hints = {
+    feed: `${state.name} 摆摆手：刚吃过，肚子还圆着呢。`,
+    bathe: `${state.name} 缩了缩：刚洗完，香着呢，别再冲水了。`,
+    play: `${state.name} 喘着气：让我歇会儿，刚玩过。`,
+    pet: `${state.name} 还没缓过来。`,
+  }
+  return [hints[action] ?? `${state.name} 现在不想动。`, '', `${wait} 秒后可以再${spec.label}。`].join('\n')
+}
+
+/** Sent the pig out to work. */
+export function renderWorkReport(state, nowMs, job) {
+  return [
+    `${state.name} 背上小包出门了 ${job.emoji}`,
+    '',
+    `💼 工作    ${job.label}`,
+    `⏱  时长    ${job.minutes} 分钟`,
+    `🪙 报酬    ${job.coins} 金币`,
+    `🍚 消耗    饱食 ${job.satiety} · 清洁 ${job.cleanliness}`,
+    '',
+    `预计 ${activitySecondsLeft(state, nowMs)} 秒后回来。这期间不能喂食洗澡 —— 它在外面忙着。`,
+  ].join('\n')
+}
+
+/** Sent the pig to class. */
+export function renderStudyReport(state, nowMs, subject, stage) {
+  const level = courseView(state)[subject.key] ?? 0
+  return [
+    `${state.name} 背上书包去上课了 ${subject.emoji}`,
+    '',
+    `📚 课程    ${subject.label}（${stage.label}）`,
+    `⏱  时长    ${stage.minutes} 分钟`,
+    `🪙 学费    ${stage.tuition} 金币`,
+    `📈 收获    ${TRAITS[subject.trait].label} +${stage.gain} · 成长 +${STUDY_GROWTH_PER_LESSON}`,
+    `🍚 消耗    饱食 ${stage.satiety} · 心情 ${stage.happiness}`,
+    '',
+    `这是${subject.label}第 ${level + 1} 节。预计 ${activitySecondsLeft(state, nowMs)} 秒后下课。`,
+  ].join('\n')
+}
+
+/** Sent the pig travelling. */
+export function renderTripReport(state, nowMs, trip) {
+  return [
+    `${state.name} 拖着小行李箱出发了 ${trip.emoji}`,
+    '',
+    `🧳 目的地  ${trip.label}`,
+    `⏱  时长    ${trip.minutes} 分钟`,
+    `🪙 花费    ${trip.cost} 金币`,
+    `❤️  心情    +${trip.happiness} · 成长 +${outingGrowth(trip.minutes)}`,
+    `🍚 消耗    饱食 ${trip.satiety}`,
+    '',
+    `会带回一件纪念品。预计 ${activitySecondsLeft(state, nowMs)} 秒后回来。`,
+  ].join('\n')
+}
+
+/** A refusal from the work path, with the reason spelled out. */
+export function renderWorkRefusal(state, text) {
+  return [
+    `💼 出不了门`,
+    '',
+    text,
+    '',
+    `现在：${mood(state, Date.now()).emoji} ${mood(state, Date.now()).label} · 🍚 ${Math.round(state.satiety)} · 🪙 ${state.coins}`,
+  ].join('\n')
+}
+
+/** Bought something. */
+export function renderBuy(state, result, item) {
+  if (result?.ok !== true) {
+    if (result?.reason === 'poor') return `🪙 钱不够：${item.emoji} ${item.label} 要 ${item.price} 金币，你只有 ${state?.coins ?? 0}。`
+    if (result?.reason === 'dead') return `${state?.name ?? '猪'} 已经走了…先救回来再买东西。`
+    return `🐖 没能买下 ${item.label}。`
+  }
+  return [
+    `🛒 买到了 ${item.emoji} ${item.label}（-${item.price} 金币）`,
+    '',
+    `🪙 余额    ${state.coins}`,
+    `🎒 背包    ${item.label} ×${state.inventory?.[item.key] ?? 0}`,
+    '',
+    `用起来：/pig use ${item.key}`,
+  ].join('\n')
+}
+
+/** Used something from the backpack. */
+export function renderUse(state, result, item) {
+  if (result?.ok !== true) {
+    switch (result?.reason) {
+      case 'empty': return `🎒 背包里没有 ${item.emoji} ${item.label}。先去 /pig shop 买。`
+      case 'not-sick': return `${state?.name ?? '猪'} 现在没生病，吃药没用。`
+      case 'not-dead': return `${state?.name ?? '猪'} 活得好好的，用不上 ${REVIVE_ITEM.label}。`
+      case 'dead': return `${state?.name ?? '猪'} 已经走了…只有 ${REVIVE_ITEM.label} 能救回来。`
+      case 'wrong-medicine': {
+        const need = result.needs
+        return `💊 药不对症。${state?.name ?? '猪'} 现在需要的是「${need?.label ?? '别的药'}」。`
+      }
+      case 'working': return `${state?.name ?? '猪'} 在外面打工，回来再吃。`
+      default: return `🐖 没能用上 ${item.label}。`
+    }
+  }
+  const lines = [`${state.name} 用了 ${item.emoji} ${item.label}`]
+  if (item.kind === 'medicine') lines.push('', '💚 病好了！健康恢复满值。')
+  else if (item.kind === 'revive') lines.push('', '✨ 回来了！等级、成长值和金币都还在。')
+  else {
+    lines.push(
+      '',
+      `🍚 饱食  ${bar(state.satiety)}  ${Math.round(state.satiety)}`,
+      `❤️  心情  ${bar(state.happiness)}  ${Math.round(state.happiness)}`,
+      `🫧 清洁  ${bar(state.cleanliness)}  ${Math.round(state.cleanliness)}`,
+    )
+  }
+  return lines.join('\n')
+}
+
+/** The scales. */
+export function renderWeigh(state, nowMs) {
+  const stage = formStageView(state, nowMs)
+  const kilos = state.weightG / 1000
+  let verdict = '还算苗条，继续保持'
+  if (kilos >= 40) verdict = '这已经是一头正经的猪了'
+  else if (kilos >= 15) verdict = '抱起来有点费劲'
+  else if (kilos >= 6) verdict = '手感很好，沉甸甸的'
+  else if (kilos >= 3) verdict = '圆润，但还能抱得动'
+  return [
+    `⚖️  ${state.name} 站上了秤`,
+    '',
+    `        ${stage.emoji}`,
+    `     ${formatWeight(state.weightG)}`,
+    '',
+    `   「${verdict}」`,
+  ].join('\n')
+}
+
+/** `/pig about`. */
+export function renderAbout(commandName) {
+  const actions = ACTION_ORDER.map(key => `  ${ACTIONS[key].emoji} ${ACTIONS[key].label}`).join(' · ')
+  const jobs = JOBS.map(job => `  ${job.emoji} ${job.label}（Lv.${job.requires.level} · ${job.minutes} 分钟 · ${job.coins} 金币）`).join('\n')
+  const courses = SUBJECTS.map(s => `${s.emoji}${s.label}`).join(' ')
+  const stages = SCHOOL_STAGES.map(s => `  ${s.label}${Number.isFinite(s.upTo) ? `（到第 ${s.upTo} 节）` : ''}：${s.minutes} 分钟 · 学费 ${s.tuition} · +${s.gain}`).join('\n')
+  const trips = TRIPS.map(t => `  ${t.emoji} ${t.label}（${t.minutes} 分钟 · ${t.cost} 金币）`).join('\n')
+  const shop = SHOP.map(item => `  ${item.emoji} ${item.label}  ${String(item.price).padStart(3)} 金币`).join('\n')
+  return [
+    '🐖 dsh-piggy —— 一只住在 DSH 里的猪',
+    RULE,
+    '最省事的用法：点右下角的 🐖，面板上六个图标点着用。',
+    '  ① 状态  ② 学习  ③ 打工  ④ 商店  ⑤ 旅行  ⑥ 背包',
+    RULE,
+    `照顾：${actions}`,
+    '',
+    '📚 学习（九门课各算各的课时，课时决定能干什么工作）：',
+    `  ${courses}`,
+    stages,
+    '',
+    '💼 打工（出门赚钱）：',
+    jobs,
+    '',
+    '🧳 旅行（带回纪念品）：',
+    trips,
+    '',
+    '🛒 商店：',
+    shop,
+    '',
+    '🤒 生病：饿着或脏着太久会得病，健康上限 5。必须对症下药；',
+    `      健康归零就没了，用 ${REVIVE_ITEM.label} 救回来（保留等级、金币和收藏）。`,
+    RULE,
+    '命令（不想点鼠标时才用）：',
+    `/${commandName} · hatch · feed · bathe · play · pet`,
+    `/${commandName} study <科目> <小学|大学|研究生>`,
+    `/${commandName} work <odd|site|office> · trip <suburb|mountain|sea|abroad> · calloff`,
+    `/${commandName} shop · buy <物品> · use <物品>`,
+    `/${commandName} crown [形态]（长成后加冕）· weigh · name <名字> · about`,
+    RULE,
+    '它不调用模型、不注入上下文、不花一个 token。',
+    '存档在 $DSH_HOME/dsh-piggy/state.json。',
+  ].join('\n')
+}
+
+/** The empty-house prompt. */
+export function renderNoPig(commandName) {
+  return `这里还没有猪。/${commandName} hatch 孵一只 🥚 —— 它会吃你之后的真实工作长大。`
+}

package/routes.js

@@ -0,0 +1,201 @@
+// @ts-check
+/**
+ * HTTP 路由：面板读的快照、面板发的动作，以及手绘精灵图。
+ *
+ * 路由只做分发与序列化，不算业务规则 —— 每个动作都转发给 store（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/routes
+ */
+import { readFileSync } from 'node:fs'
+
+import { snapshot } from './snapshot.js'
+
+const STATE_ROUTE = '/dsh-piggy/state'
+const ACT_ROUTE = '/dsh-piggy/act'
+const ART_ROUTE = '/dsh-piggy/art'
+const BODY_LIMIT_BYTES = 2048
+
+const str = value => (typeof value === 'string' ? value : '')
+
+function sendJson(res, status, body, extra = {}) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...extra })
+  res.end(JSON.stringify(body))
+}
+
+async function readJsonBody(req) {
+  let text = ''
+  for await (const chunk of req) {
+    text += chunk
+    if (text.length > BODY_LIMIT_BYTES) return null
+  }
+  if (text.trim() === '') return {}
+  try {
+    const parsed = JSON.parse(text)
+    return typeof parsed === 'object' && parsed !== null ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Every operation the panel can invoke. One table means the HTTP route and the
+ * slash command cannot drift apart.
+ */
+const OPERATIONS = {
+  hatch: store => ({ ok: true, hatched: store.hatch() }),
+  adopt: store => ({ ok: store.adopt(), adopted: true }),
+  reset: store => ({ ok: store.reset(), reset: true }),
+  dev: (store, body) => ({ ok: store.dev(body.patch ?? {}), dev: true }),
+  ageFromNow: store => ({ ok: store.ageFromNow(), ageFromNow: true }),
+  timeScale: (store, body) => ({ ok: store.setTimeScale(body.scale), timeScale: true }),
+  // The three care actions spend an item; `item` says which one.
+  feed: (store, body) => store.act('feed', str(body.item)),
+  bathe: (store, body) => store.act('bathe', str(body.item)),
+  play: (store, body) => store.act('play', str(body.item)),
+  pet: store => store.act('pet'),
+  // Answer the pig's latest line: `line` is the message id, `index` the button.
+  reply: (store, body) => store.reply(Number(body.line), Number(body.index)),
+  // 日常：签到（在线礼包在 B5 的第二步接上）。
+  signIn: store => store.signIn(),
+  openGift: store => store.openGift(),
+  // The panel's timers ask the pig to speak up; the pig decides whether to.
+  chat: (store, body) => store.chat(str(body.reason)),
+  quiet: (store, body) => store.setQuiet(body.on === true),
+  owner: (store, body) => store.setOwnerName(str(body.name)),
+  // 居民卡: the catchphrase and the motto.
+  catchphrase: (store, body) => store.setCatchphrase(str(body.text)),
+  motto: (store, body) => store.setMotto(str(body.text)),
+  // 加冕: `form` picks which one (empty = the first).
+  crown: (store, body) => store.crown(str(body.form)),
+  // 改猪的名字（和斜杠命令 /pig name 同一条路）。
+  name: (store, body) => ({ ok: Boolean(store.rename(str(body.name))), name: true }),
+  work: (store, body) => store.startWork(str(body.job)),
+  study: (store, body) => store.startStudy(str(body.subject), str(body.stage)),
+  interest: (store, body) => store.startInterest(str(body.interest)),
+  trip: (store, body) => store.startTrip(str(body.trip)),
+  calloff: store => store.callOffActivity(),
+  buy: (store, body) => store.buy(str(body.item)),
+  use: (store, body) => store.useItem(str(body.item)),
+  doctor: store => store.seeDoctor(),
+  // Souvenirs are the only thing the pig can sell back.
+  sell: (store, body) => store.sellSouvenir(str(body.souvenir)),
+  // 家当: put a dress item on / take it off.
+  wear: (store, body) => store.wear(str(body.item), body.on !== false),
+  // Debug: one of everything.
+  giveAll: store => store.grantAll(),
+}
+
+/** GET /dsh-piggy/state — the one shape the panel reads. */
+function registerStateRoute(webServer, store) {
+  return webServer.register({
+    kind: 'exact',
+    path: STATE_ROUTE,
+    handler: async (req, res) => {
+      if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed; use GET' }, { allow: 'GET' })
+      try {
+        sendJson(res, 200, snapshot(store), { 'cache-control': 'no-store' })
+      } catch (error) {
+        sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+      }
+    },
+  })
+}
+
+/**
+ * GET /dsh-piggy/art/<name>.svg — the hand-drawn sprites.
+ *
+ * Serving them from the package keeps the art as real .svg files in the
+ * repository rather than a blob embedded in the client bundle.
+ */
+function registerArtRoute(webServer) {
+  return webServer.register({
+    kind: 'prefix',
+    path: ART_ROUTE,
+    handler: (req, res) => {
+      if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed; use GET' }, { allow: 'GET' })
+      const raw = String(req.url ?? '').split('?')[0]
+      const name = raw.startsWith(ART_ROUTE + '/') ? raw.slice(ART_ROUTE.length + 1) : ''
+      // Only the files this package ships: a fixed, boring name pattern, so
+      // nothing from the request can ever walk out of ./assets.
+      if (!/^[a-z][a-z0-9-]{0,31}\.svg$/.test(name)) return sendJson(res, 404, { error: 'not found' })
+      try {
+        const svg = readFileSync(new URL('./assets/' + name, import.meta.url))
+        res.writeHead(200, { 'content-type': 'image/svg+xml; charset=utf-8', 'cache-control': 'no-cache' })
+        res.end(svg)
+      } catch (error) {
+        console.warn(`[dsh-piggy] sprite missing: name="${name}" reason="${error instanceof Error ? error.message : String(error)}"`)
+        sendJson(res, 404, { error: 'not found' })
+      }
+    },
+  })
+}
+
+/**
+ * POST /dsh-piggy/act — one action from the panel.
+ *
+ * The operation's verdict must win over the snapshot's always-true `ok`:
+ * spreading the snapshot last silently swallowed every refusal.
+ */
+function registerActRoute(webServer, store) {
+  return webServer.register({
+    kind: 'exact',
+    path: ACT_ROUTE,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return sendJson(res, 405, { error: 'method not allowed; use POST' }, { allow: 'POST' })
+      const body = await readJsonBody(req)
+      if (body === null) return sendJson(res, 413, { error: 'body too large or not JSON' })
+      const operation = typeof body.action === 'string' ? body.action : ''
+      const run = Object.hasOwn(OPERATIONS, operation) ? OPERATIONS[operation] : null
+      if (run === null) {
+        return sendJson(res, 400, { error: `unknown action "${operation}"`, allowed: Object.keys(OPERATIONS) })
+      }
+      // A throwing operation must answer, not take the route down with it: an
+      // unhandled error here would leave the panel polling a dead handler.
+      try {
+        const result = run(store, body)
+        sendJson(res, 200, {
+          ...snapshot(store),
+          ok: result.ok !== false,
+          reason: result.reason,
+          wait: result.wait,
+          price: result.price,
+          missing: result.missing,
+          sold: result.sold,
+          need: result.need,
+          have: result.have,
+        }, { 'cache-control': 'no-store' })
+      } catch (error) {
+        console.warn(`[dsh-piggy] action failed: action="${operation}" reason="${error instanceof Error ? error.message : String(error)}"`)
+        sendJson(res, 500, { ok: false, reason: 'error' })
+      }
+    },
+  })
+}
+
+/**
+ * Register the three routes once the web seam exists.
+ *
+ * `ctx.inject` waits for the service instead of sampling it. The previous
+ * version read `ctx.get('webServer')` at apply time and bailed out when it was
+ * undefined — which is exactly what happened during profile activation, so the
+ * routes were never registered and the panel polled a 404 forever. A silent
+ * optionality guard is not the same thing as a tolerant one: this one still
+ * degrades on a host with no web seam, but only *after* the service has
+ * actually been waited for.
+ */
+export function registerRoutes(ctx, store) {
+  ctx.inject(['webServer'], (webCtx) => {
+    const webServer = webCtx.webServer
+    if (webServer === undefined) return () => {}
+    const disposers = []
+    try {
+      disposers.push(registerStateRoute(webServer, store))
+      disposers.push(registerArtRoute(webServer))
+      disposers.push(registerActRoute(webServer, store))
+    } catch (error) {
+      // A route already taken: the pig stays command-only rather than breaking
+      // activation, but this is a real failure and should be visible.
+      console.warn(`[dsh-piggy] 路由注册失败，猪只能用命令访问：${error instanceof Error ? error.message : String(error)}`)
+    }
+    return () => { for (const dispose of disposers) { try { dispose() } catch { /* best effort */ } } }
+  })
+}

package/scripts/build-client.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * 打包客户端插件。
+ *
+ * DSH 的客户端插件是按 classic <script src> 加载的**单文件**（见
+ * packages/client/modules/src/client/system.ts 的 loadBundle），源码拆分之后
+ * 必须有这一步；产物 client.js 提交入库，由 test/bundle.test.js 守住新鲜度。
+ *
+ * 用法：node scripts/build-client.mjs
+ */
+import { existsSync, readdirSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const entryPoint = join(packageRoot, 'src/client/index.js')
+const outfile = join(packageRoot, 'client.js')
+const require = createRequire(import.meta.url)
+
+/**
+ * Find esbuild, in order: an installed dependency, an explicit override, then a
+ * checkout that happens to have it in the pnpm store.
+ *
+ * The override exists because this environment has no registry access; the
+ * documented, portable way is `pnpm add -D esbuild`.
+ * @returns {any} the esbuild module
+ */
+function loadEsbuild() {
+  try {
+    return require('esbuild')
+  } catch {
+    // Not installed locally: fall through to the explicit locations below.
+  }
+
+  const explicit = process.env.DSH_PIG_ESBUILD
+  if (explicit !== undefined && explicit.trim() !== '') {
+    return require(explicit.trim())
+  }
+
+  // A sibling checkout (…/DSH/deepseek-harness next to …/DSH/workspaces/<pkg>)
+  // keeps this working in the author's environment without an install step.
+  const candidates = []
+  const stores = [
+    join(packageRoot, 'node_modules/.pnpm'),
+    resolve(packageRoot, '../../deepseek-harness/node_modules/.pnpm'),
+  ]
+  for (const store of stores) {
+    if (!existsSync(store)) continue
+    for (const entry of readdirSync(store)) {
+      if (!entry.startsWith('esbuild@')) continue
+      const candidate = join(store, entry, 'node_modules/esbuild')
+      if (existsSync(candidate)) candidates.push(candidate)
+    }
+  }
+  if (candidates.length === 0) {
+    throw new Error(
+      'build-client: esbuild not found. Install it with `pnpm add -D esbuild`, '
+      + 'or point DSH_PIG_ESBUILD at an esbuild entry.',
+    )
+  }
+  return require(candidates[candidates.length - 1])
+}
+
+/** @returns {Promise<string>} the bundle text */
+export async function buildClient() {
+  const esbuild = loadEsbuild()
+  const result = await esbuild.build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    format: 'iife',
+    platform: 'browser',
+    // No minify: the shipped file stays readable, and the freshness test compares
+    // bytes, so any transform change is visible in review.
+    minify: false,
+    legalComments: 'none',
+    absWorkingDir: packageRoot,
+    write: false,
+    logLevel: 'warning',
+    banner: {
+      js: '// GENERATED FILE. Edit src/client/ and run `npm run build`; do not edit by hand.',
+    },
+  })
+  return result.outputFiles[0].text
+}
+
+const invokedDirectly = process.argv[1] !== undefined
+  && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (invokedDirectly) {
+  try {
+    const text = await buildClient()
+    writeFileSync(outfile, text)
+    console.log(`build-client: wrote ${outfile} (${text.length} bytes)`)
+  } catch (error) {
+    console.error(`build-client failed: ${error instanceof Error ? error.message : String(error)}`)
+    process.exitCode = 1
+  }
+}