aihand 0.0.1 → 0.1.1

package/src/ui/core/candidates.ts

@@ -0,0 +1,348 @@
+/// <reference lib="dom" />
+// DOM 命中的纯判定原语 —— aihand write/read 路的命中地基。
+//
+// 全是浏览器原生 DOM API（document/getBoundingClientRect/elementFromPoint），零依赖。
+// 这 64 行同时被 read 侧（/screen 列 knobs、/click text= 匹配、miss 时的可点击清单）和
+// write 侧（doClick 的 elementFromPoint 命中测试）消费 —— 同进程内读写必须共用一份，否则
+// 立刻产生 read-says-clickable / write-can't 的不一致（reachable 注释里钉死的 bug）。
+//
+// teact 的 domHitSuite 也有一份逻辑等价的 candidates（测试侧，jsdom 采集命中轨迹）。那是
+// 跨仓的两份、不同进程、不同时演化，没有运行时耦合 —— 故各持一份，而非跨包运行时依赖
+// （后者会把 aihand 发布后强行拉一个会撞 npm 名的 teact，必炸）。改这里时记得 teact 那份。
+
+export const INTERACTIVE = 'a, button, input, textarea, select, [role], [onclick], [tabindex], [contenteditable], [aria-label]'
+
+// aria-labelledby: an element names itself by POINTING at other elements (one or more IDs),
+// whose visible text, concatenated, is the name. This is the TOP signal in the W3C accessible-
+// name algorithm — higher than aria-label — and is how real third-party frontends name custom
+// widgets (a role=textbox whose label is a separate visible <div id> above it). Zero app
+// cooperation: the association is already in the DOM. We resolve each id to its element's text
+// (getDirectText first, then full textContent), join with a space, skipping dangling ids.
+function labelledByText(el: Element): string {
+    const ids = (el.getAttribute('aria-labelledby') || '').trim()
+    if (!ids)
+        return ''
+    const out: string[] = []
+    // aria-labelledby is a space-separated ID token list (HTML spec). split on whitespace,
+    // drop empties — no regex on structured text, this is a flat token list, not syntax.
+    for (const id of ids.split(' ').map(s => s.trim()).filter(Boolean)) {
+        const ref = el.ownerDocument?.getElementById(id)
+        if (!ref)
+            continue
+        const t = (getDirectText(ref) || (ref.textContent || '').trim()).trim()
+        if (t)
+            out.push(t)
+    }
+    return out.join(' ')
+}
+
+// A form control names itself by its associated <label> — `<label for=id>` pointing at it OR a
+// wrapping <label>. Native, standard, present without app cooperation (how every accessible form
+// works). HTMLInputElement/Textarea/Select expose `.labels` (a live NodeList of BOTH kinds), so
+// we read it directly — no id-into-selector escaping, no regex. Concatenate the labels' visible
+// text. Returns '' if the control type has no `.labels` (e.g. a contenteditable div).
+function associatedLabelText(el: Element): string {
+    const labels = (el as HTMLInputElement).labels
+    if (!labels || labels.length === 0)
+        return ''
+    const out: string[] = []
+    for (const lab of Array.from(labels)) {
+        const t = (getDirectText(lab) || (lab.textContent || '').trim()).trim()
+        if (t)
+            out.push(t)
+    }
+    return out.join(' ')
+}
+
+// An icon-only button carries no text/aria/title, but its icon's identity IS its meaning, and
+// every icon library stamps that identity into the <svg> class — lucide emits `lucide ellipsis`
+// → class "lucide lucide-ellipsis", feather "feather feather-trash", heroicons similar. The
+// fingerprint that distinguishes an icon-name token from a utility class (w-3.5, text-gray-500)
+// is the PAIR: a bare library token (`lucide`) AND a `lucide-<name>` token co-occur on the same
+// svg. Utility classes never form that prefix/prefix-name pair. So we find any token of the form
+// `<p>-<name>` whose prefix `<p>` is itself a standalone token on the element, and read `<name>`
+// (kebab→space). This is a browser-native, zero-app-cooperation signal — the icon library emits
+// it for everyone. It is the WEAKEST label (an icon name is cruder than a real word), so it sits
+// at the very bottom of elementLabel's chain, below every accname signal: a title-bearing icon
+// button still shows its title, never "search". Returns '' if no icon-library class is present.
+function iconNameOf(el: Element): string {
+    const svg = el.tagName === 'svg' ? el : el.querySelector('svg')
+    if (!svg)
+        return ''
+    const tokens = (svg.getAttribute('class') || '').split(' ').map(s => s.trim()).filter(Boolean)
+    const bare = new Set(tokens.filter(t => !t.includes('-')))
+    for (const t of tokens) {
+        const dash = t.indexOf('-')
+        if (dash <= 0)
+            continue
+        const prefix = t.slice(0, dash)
+        if (bare.has(prefix)) // `lucide` + `lucide-ellipsis` → the icon-library fingerprint
+            return t.slice(dash + 1).split('-').join(' ') // trash-2 → "trash 2", chevron-down → "chevron down"
+    }
+    return ''
+}
+
+// Direct text children only — skip nested element text (a button's icon-span <title>,
+// a badge count) so the label is the element's own words, not its descendants'.
+export function getDirectText(el: Element): string {
+    let text = ''
+    for (const node of el.childNodes) {
+        if (node.nodeType === 3) { // TEXT_NODE
+            const t = node.textContent?.trim()
+            if (t)
+                text += (text ? ' ' : '') + t
+        }
+    }
+    return text
+}
+
+// The ONE label of an element — what /screen lists it as AND what /click matches text= on.
+// Both reading (knobs) and writing (find target) go through this, so the projection can
+// never name a control the click can't find (the read-says-clickable, write-can't bug).
+//
+// The fallback chain is the W3C accessible-name computation (accname) — the SAME algorithm
+// every screen reader uses to name an element — restricted to its load-bearing signals. This
+// is what makes aihand universal: it extracts names from browser-native, standardized signals
+// that arbitrary third-party frontends already emit for accessibility, with ZERO cooperation
+// from the app under test. The order is accname's priority order:
+//   1. aria-labelledby — element points at other elements whose text is its name (TOP signal,
+//      how custom widgets like a role=textbox name themselves by a visible sibling label).
+//   2. aria-label — the inline name.
+//   3. getDirectText — the element's own words (a button's label text).
+//   4. title — icon buttons carry their word here, not in text.
+//   5. textContent — full subtree text when own text is empty.
+// If still empty and it's a form control, fall to its native associations:
+//   6. <label for> / wrapping <label> — the standard way a form field is named.
+//   7. placeholder — the visible gray-text name of an input.
+//   8. value (safeValue) — last resort; the control's content is its only human-readable word
+//      (textContent is always empty for form controls). Through safeValue so a password/token
+//      field's label is its redaction, never the plaintext secret.
+// A clickable CONTAINER with empty own text often wraps the control holding its name (a sidebar
+// row is a div wrapping a pointer-events-none <input value=…>), so we descend to the first form
+// control and run the same native-association chain on it.
+//   9. icon name (iconNameOf) — the FINAL, weakest fallback: an icon-only button with no accname
+//      signal at all (a `<MoreHorizontal/>` menu trigger) takes its name from the icon library's
+//      svg class (lucide-ellipsis → "ellipsis"). Below everything else so a real name always wins.
+// 空白归一化:HTML 把 `74&nbsp;comments` 渲成含 U+00A0(不间断空格)的文本,但人看到的、人输入
+// 到 text= 的是普通空格 `74 comments`。JS 的 `\s` 不含 U+00A0,故 includes 直接漏匹配(live 实测
+// HN 评论链接 `no element for 74 comments`,而 clickable 列表里明明列着它)。把所有 Unicode 空白
+// (nbsp/各种宽度空格/制表/换行)折叠成单个普通空格 + trim,读侧(label 显示)写侧(text= 匹配)同源:
+// /screen 列 `74 comments`、pickByText 比较 `74 comments`,普通空格直接命中。这是空白字符的字节
+// 归一(非对结构化语法做 pattern match),正则在此正当。\s 加   补 JS 的盲点。
+function normWs(s: string): string {
+    return s.replace(/[\s ]+/g, ' ').trim()
+}
+
+export function elementLabel(el: Element): string {
+    return normWs(rawLabel(el))
+}
+
+function rawLabel(el: Element): string {
+    const text = (labelledByText(el) || el.getAttribute('aria-label') || getDirectText(el) || el.getAttribute('title') || (el.textContent || '').trim()).trim()
+    if (text)
+        return text
+    const tag = el.tagName
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
+        return controlLabel(el)
+    const ctrl = el.querySelector('input, textarea, select')
+    if (ctrl) {
+        const cl = controlLabel(ctrl)
+        if (cl)
+            return cl
+    }
+    return iconNameOf(el)
+}
+
+// The name of a form control reached either as the element itself or by descending into a
+// clickable container that wraps it. Full accname order on the control: aria-labelledby →
+// aria-label → <label> → title → placeholder → value. (own/textContent are always empty for
+// form controls, so they're skipped.) Through safeValue so a secret field's name is its
+// redaction, never the plaintext value.
+function controlLabel(el: Element): string {
+    return (labelledByText(el) || el.getAttribute('aria-label') || associatedLabelText(el) || el.getAttribute('title') || el.getAttribute('placeholder') || safeValue(el)).trim()
+}
+
+export function isVisible(el: Element): boolean {
+    const r = el.getBoundingClientRect()
+    return r.width > 0 && r.height > 0
+}
+
+// A name that marks a value as a secret to never echo in plaintext: API keys, tokens,
+// passwords. The substring signals (no regex) that gate redaction. This is the ONE predicate
+// over a *name string* — shared by the DOM-element reader (isSensitive, action.ts: input's
+// type/name/aria) AND the domain-field reader (collectScreen/diffScreen: a `store.field` key).
+// Both routes echo values; the redaction must hang off this single key-level predicate or a
+// different endpoint leaks what another redacts (sessionToken was plaintext in /screen's domain
+// block because only the DOM route was guarded — same hole, second consumer).
+// Substrings that mark a name (form-field name/aria, domain key, OR an HTTP header name) as
+// secret-bearing. `authorization`/`cookie`/`set-cookie` carry credentials but contain none of
+// the token/key/secret words, so they're listed explicitly — a request-header dump (/network
+// ?full) leaks `Authorization: Bearer sk-…` exactly the way the domain block leaked sessionToken.
+const SECRET_HINTS = ['password', 'api key', 'apikey', 'api-key', 'api_key', 'secret', 'token', 'private key', 'authorization', 'cookie']
+
+// Substrings that look secret-bearing by `token` but are plainly a COUNT, not a credential. A
+// credential is a single `token` (authToken/githubToken/sessionToken/syncToken); the plural
+// `tokens` and `tokenCount` are LLM token quantities (maxTokensK, showTokenCount). Without this,
+// `'maxtokensk'.includes('token')` redacts a harmless number — and a redacted config value is
+// strictly worse for a reader (it can't see the setting) than an exposed count is risky (it isn't).
+const SECRET_EXEMPTIONS = ['tokens', 'tokencount']
+
+export function isSecretKey(name: string): boolean {
+    const lower = name.toLowerCase()
+    if (SECRET_EXEMPTIONS.some(e => lower.includes(e)))
+        return false
+    return SECRET_HINTS.some(h => lower.includes(h))
+}
+
+// A domain field that names an in-flight operation — generating, loading, a pending request.
+// While such a field is truthy the app is mid-async; the DOM may fall silent (waiting on the
+// network for the first token) yet the state machine has NOT settled. settle uses this to tell a
+// real resting state from a mid-flight lull: "DOM quiet" ∧ "no busy field truthy" = actually done.
+// This is the dual of isSecretKey — a key-level semantic classifier, generic over any app's
+// __AIPEEK_SCREEN__ (it never hard-codes a field like 流式中). Bilingual: an app may name the
+// field in Chinese (流式中/加载中/思考中/请求中) or English (isLoading/streaming/pending/busy).
+// Strong markers: unambiguous in-progress words. A key containing one is busy no matter what — they
+// never collide with a neutral noun, so no exemption applies to them.
+const BUSY_STRONG = ['loading', 'streaming', 'pending', 'busy', 'fetching', 'inflight', 'in-flight', 'generating', 'waiting', '加载中', '生成中', '思考中', '流式中', '请求中', '发送中']
+
+// Weak markers fire only after exemptions clear. '中' and bare '-ing' are real in-progress signals
+// (…中 / streaming) but also land inside neutral nouns (中文 / setting), so the exemptions below
+// suppress the false hits. Strong markers above bypass this gate entirely.
+const BUSY_WEAK = ['中', 'ing']
+const BUSY_EXEMPTIONS = ['中文', '中间', '居中', '集中', 'setting', 'heading', 'string', 'rating', 'meeting', 'missing', 'training', 'ring', 'ceiling', 'sibling']
+
+export function isBusyKey(name: string): boolean {
+    const lower = name.toLowerCase()
+    if (BUSY_STRONG.some(h => lower.includes(h)))
+        return true
+    if (BUSY_EXEMPTIONS.some(e => lower.includes(e)))
+        return false
+    return BUSY_WEAK.some(h => lower.includes(h))
+}
+
+// True when a domain entry asserts work is in flight: an in-progress-named key holding a NON-EMPTY
+// value. (`流式中: true` yes; `流式中: false` no; `模型: "Sonnet"` no — not an in-progress key.)
+// The empty-collection gate is load-bearing, not cosmetic: a busy-named key can hold a container
+// whose EMPTINESS is the rest state — `typing: {}` (nobody typing), `replyingTo: {}` (not replying),
+// `pendingReqs: []` (none pending). An empty {} / [] is truthy in JS, so without this gate every
+// such key reads as perpetually busy and settle never terminates. The value, not the name, is the
+// honest in-flight signal; the gate makes "named busy but holding nothing" collapse to rest.
+export function isBusyState(key: string, value: unknown): boolean {
+    if (!isBusyKey(key))
+        return false
+    if (value === false || value === null || value === undefined || value === 0 || value === '')
+        return false
+    if (Array.isArray(value))
+        return value.length > 0
+    if (typeof value === 'object')
+        return Object.keys(value as object).length > 0
+    return true
+}
+
+// Length-preserving redaction of a value (so "empty vs set / roughly how long" stays
+// observable without exposing the secret). The single masking shape, shared by every reader
+// that echoes a value under a secret-named key — DOM input, domain field, HTTP header.
+export function redactSecretValue(value: string): string {
+    return value ? `‹redacted ${value.length} chars›` : value
+}
+
+// A field whose live value must never be echoed: API keys, tokens, passwords. `.value`
+// returns the real string even for type=password (masking is visual only), so reading it
+// out in /dom, /query, /screen or as a label would leak the secret in plaintext. We redact
+// instead. Signals (substring, no regex): type=password, autocomplete=*-password /
+// one-time-code, or a name/placeholder/aria-label hinting a secret. Lives here next to the
+// redaction primitives because elementLabel (this file) now reads value too — both the label
+// and the state suffix must pass through the same one chokepoint or one re-leaks the other.
+export function isSensitive(el: Element): boolean {
+    if ((el as HTMLInputElement).type === 'password')
+        return true
+    const ac = (el.getAttribute('autocomplete') || '').toLowerCase()
+    if (ac.includes('password') || ac === 'one-time-code')
+        return true
+    const hint = `${el.getAttribute('name') || ''} ${el.getAttribute('placeholder') || ''} ${el.getAttribute('aria-label') || ''}`
+    return isSecretKey(hint)
+}
+
+// The value to show for a field: real value, or a length-preserving redaction for secrets
+// (so "is it empty / roughly how long" stays observable without exposing the secret).
+export function safeValue(el: Element): string {
+    const v = (el as HTMLInputElement).value ?? ''
+    return isSensitive(el) ? redactSecretValue(v) : v
+}
+
+// text → element is a RANKING problem, not a filter. The old `filter(includes).find(reachable)`
+// collapsed three orthogonal axes into "substring + DOM order", and each lost axis revived a
+// real miss class seen in live driving:
+//   1. EXACTNESS — a tab button labelled exactly "外观" vs the whole nav strip whose text
+//      *contains* "外观". Pure substring + DOM-order let the giant container win. So an exact
+//      label beats a prefix/suffix beats a mere substring.
+//   2. REACHABILITY — a knob that's clickable now beats one merely boxed (covered/off-screen).
+//   3. TIGHTNESS — at equal exactness, the SMALLEST element wins: the leaf <button> over the
+//      <div> wrapping it, the icon control over its tooltip-portal ancestor. Drop this and a
+//      substring match hands the click to the biggest enclosing box.
+// Removing any one axis brings back a miss class — this 3-tuple is the minimal complete order.
+// matchScore returns null for a non-match; higher tuple (lexicographic, then larger = better)
+// is the better target. Pure & deterministic so teact's domHitSuite can mirror it 1:1.
+interface MatchScore { exact: number, reach: number, tight: number }
+
+function matchScore(el: Element, lowerText: string): MatchScore | null {
+    if (!isVisible(el))
+        return null
+    const label = elementLabel(el).toLowerCase()
+    if (!label.includes(lowerText))
+        return null
+    const exact = label === lowerText ? 2 : (label.startsWith(lowerText) || label.endsWith(lowerText)) ? 1 : 0
+    const r = el.getBoundingClientRect()
+    return { exact, reach: reachable(el) ? 1 : 0, tight: -(r.width * r.height) }
+}
+
+// Lexicographic compare of two scores: exact, then reach, then tight (all larger = better).
+function scoreBetter(a: MatchScore, b: MatchScore): boolean {
+    if (a.exact !== b.exact) return a.exact > b.exact
+    if (a.reach !== b.reach) return a.reach > b.reach
+    return a.tight > b.tight
+}
+
+// argmax of matchScore over a candidate set — the one element a text= should resolve to.
+export function pickByText(candidates: Iterable<Element>, text: string): Element | null {
+    // text= 输入同样归一化:label 已是普通空格,输入侧也折叠(用户粘贴带 nbsp 的文本时两侧仍同源)。
+    const lower = normWs(text).toLowerCase()
+    let best: Element | null = null
+    let bestScore: MatchScore | null = null
+    for (const el of candidates) {
+        const s = matchScore(el, lower)
+        if (s && (!bestScore || scoreBetter(s, bestScore))) {
+            best = el
+            bestScore = s
+        }
+    }
+    return best
+}
+
+// One judgment of "can a real click land on this element *right now*", shared by the read
+// side (/screen knobs, findElement text-match, the miss clickable-list) and the write side
+// (doClick hit-tests via elementFromPoint). They used to disagree: readers only checked
+// isVisible (has a box), but a boxed element can be covered by an overlay, pointer-events:
+// none, or scrolled out of the viewport — so /screen listed knobs that /click then couldn't
+// hit. reachable is the write-side truth: a mouse at the element's center hits this element
+// or something in its own subtree chain. isVisible stays the cheap precondition.
+export function reachable(el: Element): boolean {
+    if (!isVisible(el))
+        return false
+    // No hit-testing available (jsdom) → fall back to the box check; real browsers always
+    // have elementFromPoint, so this degrades only in tests, never in the live inspector.
+    if (typeof document.elementFromPoint !== 'function')
+        return true
+    const r = el.getBoundingClientRect()
+    const x = r.left + r.width / 2
+    const y = r.top + r.height / 2
+    // Off-viewport (scrolled away) → elementFromPoint can't reach it → not clickable now.
+    if (x < 0 || y < 0 || x > innerWidth || y > innerHeight)
+        return false
+    const hit = document.elementFromPoint(x, y)
+    if (!hit)
+        return false
+    // Hit lands inside this element's own chain (it, a descendant, or an ancestor that the
+    // click still routes to) — same containment test doClick uses to decide "landed on us".
+    return el.contains(hit) || hit.contains(el)
+}

package/src/ui/core/canvas.ts

@@ -0,0 +1,305 @@
+/// <reference lib="dom" />
+// 界面 → 等价草图。唯一标准:肉眼在屏幕上看到什么矩形,就在字符网格上画那个矩形 —— 像人手画
+// wireframe。代替视觉喂 AI,不走截图/像素逆向。
+//
+// 这是一台「抽象 UI 渲染引擎」:把真实视口几何降采样到有上限(MAX_COLS×MAX_ROWS)的字符网格。
+// 位置+尺寸就是布局:三栏=三个并排矩形;bot 消息=左侧框,user 消息=右侧框,日期=居中无框;
+// 高消息=高框,矮消息=矮框。
+//
+// 两步正交分离:
+//   ① collectCanvas(浏览器,读 DOM)—— 见 client.ts,带副作用、读真实 DOM + 视口可见性 + 几何。
+//      它把每个框降采样成「相对父框内部原点」的整数网格矩形 {col,row,w,h},烘进 Box 树。
+//   ② renderCanvas(纯函数,本文件)—— Box 树 → 字符串,零 DOM、零像素坐标,teact 钉死契约。
+//      只消费离散整数坐标,画到可变字符网格。零位置数学。
+//
+// 单递归 + 几何停止:collector 对每个框问「降采样后框宽塞得下文字吗?能 → 填文字前缀(超了 …);
+// 不能且有内部结构 → 递归画子框」。三档(窄=label/中=正文/大=容器)从框宽涌现,不硬编码。
+// 人画草图不给每个词画框 —— 纯文本段 drawBorder=false,只有真矩形(栏/气泡/按钮)画框。
+
+const MAX_COLS = 160 // 字符画布列宽上限(画布物理边界)
+const MAX_ROWS = 80 // 字符画布行高上限(cap 防巨页炸满)
+
+export type Side = 'left' | 'center' | 'right' // 仅作框内 label 对齐提示;摆位本身靠 col/row
+export type BoxKind = 'frame' | 'bubble' | 'knob' | 'text'
+
+// 一个画出来的矩形。collector 已把一切降采样成「相对父框内部原点」的整数网格坐标 —— renderer
+// 零位置数学,只按 col/row/w/h 画框 + 写 label + 递归子框。
+export interface Box {
+    kind: BoxKind
+    col: number // 相对父框内部原点的 x 字符偏移 (>=0)
+    row: number // 相对父框内部原点的 y 行偏移 (>=0)
+    w: number // 字符宽,含 2 列边框 (>=1)
+    h: number // 行高,含 2 行边框 (>=1)
+    label: string // 已截断的文字/图标/landmark 名,或 ''
+    morphism: string // ' → store.{ field=to }' / ''
+    drawBorder: boolean // true → 画 ┌┐└┘─│;false → 纯 label 块(文本段/日期)
+    children: Box[] // 子框,坐标相对本框内部
+}
+
+export type Node = Box // 别名,client.ts 的 import 仍解析
+
+// @kN 可寻址旋钮 ref:单一权威源。按 renderKnobs 同款栏序遍历(root 直接 frame 子分组、栏内
+// 递归收 knob),给每个 kind==='knob' 的 Box 依次编 @k1 @k2…。四投影都读这一份映射 → 号必一致。
+// 缺省不传 refs 时四投影逐字节同旧(纯增量旁路)。
+export function numberKnobs(root: Box): Map<Box, string> {
+    const refs = new Map<Box, string>()
+    let n = 0
+    const collect = (box: Box, acc: Box[]): void => {
+        if (box.kind === 'knob')
+            acc.push(box)
+        for (const c of box.children)
+            collect(c, acc)
+    }
+    const columns = root.children.filter(c => c.kind === 'frame')
+    const cols = columns.length ? columns : [root]
+    for (const col of cols) {
+        const knobs: Box[] = []
+        collect(col, knobs)
+        for (const k of knobs)
+            refs.set(k, `@k${++n}`)
+    }
+    return refs
+}
+
+// 该框的 ref 前缀(有号则 '@k3 ',否则 '')。
+function refPrefix(box: Box, refs?: Map<Box, string>): string {
+    const r = refs?.get(box)
+    return r ? `${r} ` : ''
+}
+
+// 显示宽度:CJK/全角字符占 2 列,其余 1 列。JS .length 是 code unit 数,CJK 算 1 —— 直接
+// padEnd 会让「群聊」比「AI 对话」视觉更短,列对不齐,AI 读错结构。代替视觉必须按真实占列。
+function displayWidth(s: string): number {
+    let w = 0
+    for (const ch of s) {
+        const c = ch.codePointAt(0)!
+        const wide = (c >= 0x1100 && c <= 0x115F) // Hangul Jamo
+            || (c >= 0x2E80 && c <= 0xA4CF) // CJK 部首…彝文(含〔〕「」、汉字、假名)
+            || (c >= 0xAC00 && c <= 0xD7A3) // Hangul 音节
+            || (c >= 0xF900 && c <= 0xFAFF) // CJK 兼容表意
+            || (c >= 0xFE30 && c <= 0xFE4F) // CJK 兼容形式
+            || (c >= 0xFF00 && c <= 0xFF60) // 全角 ASCII
+            || (c >= 0xFFE0 && c <= 0xFFE6) // 全角符号
+            || (c >= 0x20000 && c <= 0x3FFFD) // CJK 扩展 B+
+        w += wide ? 2 : 1
+    }
+    return w
+}
+
+// 截到恰好 width 显示列:在宽字边界停下(不切半个 CJK),被截则末尾留位放 …。
+// 纯字符遍历,禁正则。width 不足放 … 时退化成尽量塞。
+function clipDisplay(s: string, width: number): string {
+    if (displayWidth(s) <= width)
+        return s
+    if (width <= 1)
+        return '…'.slice(0, width)
+    let w = 0
+    let out = ''
+    for (const ch of s) {
+        const cw = displayWidth(ch)
+        if (w + cw > width - 1) // 留 1 列给 …
+            break
+        out += ch
+        w += cw
+    }
+    return out + '…'
+}
+
+function clampInt(v: number, lo: number, hi: number): number {
+    return v < lo ? lo : v > hi ? hi : v
+}
+
+// 去尾空格,纯字符扫描(禁正则)。
+function trimEnd(s: string): string {
+    let end = s.length
+    while (end > 0 && s[end - 1] === ' ')
+        end--
+    return s.slice(0, end)
+}
+
+// 把字符串写进网格,从 (row,col) 起逐字铺。CJK 占两格:左格放字、右格放 '' 哨兵并跳 2,
+// 绝不切半个宽字。越界即停。
+function writeText(grid: string[][], row: number, col: number, s: string): void {
+    const cols = grid[0]?.length ?? 0
+    if (row < 0 || row >= grid.length)
+        return
+    let c = col
+    for (const ch of s) {
+        if (c >= cols)
+            break
+        if (displayWidth(ch) === 2) {
+            if (c + 1 >= cols)
+                break
+            grid[row][c] = ch
+            grid[row][c + 1] = ''
+            c += 2
+        }
+        else {
+            grid[row][c] = ch
+            c += 1
+        }
+    }
+}
+
+// label 装得下态射就拼上(宽框行内显态射),否则只 label(窄框态射降级到尾部图例)。
+// 有 @kN ref 时前缀 '@k3 ':ref 是寻址锚,比文字更重要 —— 框宽不够时由 clipDisplay 截 label
+// 尾部(前缀在头部天然保留)。
+function composeLabel(box: Box, innerW: number, refs?: Map<Box, string>): string {
+    const pre = refPrefix(box, refs)
+    if (box.morphism && displayWidth(pre + box.label + box.morphism) <= innerW)
+        return pre + box.label + box.morphism
+    return pre + box.label
+}
+
+// 一个框是否会把态射行内渲出来 —— 与 composeLabel 同判据,collectLegend 据此挑漏网的。
+function morphismShownInline(box: Box): boolean {
+    const innerW = box.drawBorder ? box.w - 2 : box.w
+    return displayWidth(box.label + box.morphism) <= innerW
+}
+
+// 把一个框画进网格。originCol/originRow = 本框左上角的绝对网格坐标。
+function paint(grid: string[][], box: Box, originCol: number, originRow: number, refs?: Map<Box, string>): void {
+    const rows = grid.length
+    const cols = grid[0]?.length ?? 0
+    if (rows === 0 || cols === 0)
+        return
+    const c0 = clampInt(originCol, 0, cols - 1)
+    const r0 = clampInt(originRow, 0, rows - 1)
+    const c1 = clampInt(c0 + Math.max(1, box.w) - 1, 0, cols - 1) // 含右边框列
+    const r1 = clampInt(r0 + Math.max(1, box.h) - 1, 0, rows - 1) // 含下边框行
+
+    // 太薄画不成框(内宽<2 或内高<1)→ 降级:不画框,有 label 当裸文本铺。
+    const drawable = box.drawBorder && (c1 - c0) >= 2 && (r1 - r0) >= 1
+    if (drawable) {
+        for (let c = c0; c <= c1; c++) {
+            grid[r0][c] = c === c0 ? '┌' : c === c1 ? '┐' : '─'
+            grid[r1][c] = c === c0 ? '└' : c === c1 ? '┘' : '─'
+        }
+        for (let r = r0 + 1; r < r1; r++) {
+            grid[r][c0] = '│'
+            grid[r][c1] = '│'
+        }
+    }
+
+    // 内部原点:有框则缩进 1 让 child.col=0 贴内壁;无框则就在框原点。
+    const ic = drawable ? c0 + 1 : c0
+    const ir = drawable ? r0 + 1 : r0
+    const innerW = drawable ? (c1 - c0 - 1) : (c1 - c0 + 1)
+
+    // label 行必须落在内部:有框时严格在下边框之上(ir<r1),无框时就在框内(ir<=r1)。
+    const labelRowOk = drawable ? ir < r1 : ir <= r1
+    if (box.label && innerW >= 1 && labelRowOk)
+        writeText(grid, ir, ic, clipDisplay(composeLabel(box, innerW, refs), innerW))
+
+    for (const child of box.children)
+        paint(grid, child, ic + child.col, ir + child.row, refs)
+}
+
+// 态射图例:递归全树,拼成尾部块。两类入图例:
+//   ① 所有有 ref 的 knob(带 @kN)—— 让「看图例即得全部可寻址号」,即便其框已行内显出。
+//   ② 非 knob 但有态射且没被行内渲出的框 —— 窄图标 store 跃迁框太小写不下也不能丢。
+// 缺省无 refs 时退化成旧行为(只挑漏网的)。
+function collectLegend(root: Box, refs?: Map<Box, string>): string {
+    const lines: string[] = []
+    const walk = (box: Box): void => {
+        const ref = refs?.get(box)
+        if (ref)
+            lines.push(`${ref} ${box.label ? `[${box.label}]` : `<${box.kind}>`}${box.morphism}`)
+        else if (box.morphism && !morphismShownInline(box))
+            lines.push(`${box.label ? `[${box.label}]` : `<${box.kind}>`}${box.morphism}`)
+        for (const c of box.children)
+            walk(c)
+    }
+    walk(root)
+    if (lines.length === 0)
+        return ''
+    return ['┄ 控制面板态射 ┄', ...lines].join('\n')
+}
+
+export function renderCanvas(root: Box, refs?: Map<Box, string>): string {
+    const rows = Math.min(MAX_ROWS, Math.max(1, root.h))
+    const cols = Math.min(MAX_COLS, Math.max(1, root.w))
+    const grid: string[][] = Array.from({ length: rows }, () => Array.from({ length: cols }, () => ' '))
+    paint(grid, root, 0, 0, refs)
+    const body = grid.map(r => trimEnd(r.join(''))).join('\n')
+    const legend = collectLegend(root, refs)
+    return legend ? `${body}\n\n${legend}` : body
+}
+
+// ── 同源派生:下面三个纯函数消费同一棵 Box 树,渲成 B/C/D 三种文本形态。 ───────────────
+// 与 renderCanvas(A=ASCII)同源、零手写。几何全在 Box 的 col/row/w/h 里,各形态只是不同投影:
+//   B 语义布局树 —— 几何编码进关系词(左/中/右 + 大/中/小),缩进表嵌套。
+//   C 关系式     —— 几何展平成 above/below/left-of/right-of/inside 三元组。
+//   D 旋钮表     —— 只投影可操作面(kind=knob)+ 态射,按顶层栏分组。
+
+// 一个框相对父内部宽的水平位置档:left/center/right(纯 col/w 算术,不读 DOM)。
+function colBand(box: Box, parentInnerW: number): Side {
+    const center = box.col + box.w / 2
+    if (center < parentInnerW / 3)
+        return 'left'
+    if (center > (parentInnerW * 2) / 3)
+        return 'right'
+    return 'center'
+}
+
+// 尺寸档:按字符面积粗分大/中/小(给 AI「视觉体量」直觉,Q7 类题靠这个)。
+function sizeBand(box: Box): string {
+    const area = box.w * box.h
+    if (area >= 600)
+        return '大'
+    if (area >= 80)
+        return '中'
+    return '小'
+}
+
+const SIDE_CN: Record<Side, string> = { left: '左', center: '中', right: '右' }
+
+// B:语义布局树。每行 = 缩进 + kind 记号 + (@kN) + label + (位置/尺寸/态射)标注。
+export function renderSemanticTree(root: Box, refs?: Map<Box, string>): string {
+    const lines: string[] = ['语义布局树(几何→关系词;缩进=嵌套):']
+    const walk = (box: Box, depth: number, parentInnerW: number): void => {
+        if (depth > 0) {
+            const tags: string[] = []
+            const band = colBand(box, parentInnerW)
+            if (band !== 'center' || box.kind === 'bubble')
+                tags.push(SIDE_CN[band])
+            if (box.kind === 'frame' || box.kind === 'bubble')
+                tags.push(sizeBand(box))
+            const mark = box.kind === 'knob' ? '●' : box.kind === 'frame' ? '▢' : box.kind === 'bubble' ? '◷' : '·'
+            const text = box.label || `<${box.kind}>`
+            const tagStr = tags.length ? ` (${tags.join('/')})` : ''
+            lines.push(`${'  '.repeat(depth)}${mark} ${refPrefix(box, refs)}${text}${tagStr}${box.morphism}`)
+        }
+        const innerW = box.drawBorder ? Math.max(1, box.w - 2) : box.w
+        for (const c of box.children)
+            walk(c, depth + 1, innerW)
+    }
+    walk(root, 0, Math.max(1, root.w))
+    return lines.join('\n')
+}
+
+// D:控制论旋钮表。只投影 kind=knob(可操作面)+ 态射,按顶层栏(root 的直接 frame 子)分组。
+// 每行带 @kN(可寻址号);此栏序遍历与 numberKnobs 同款 → 号与编号权威源天然一致。
+export function renderKnobs(root: Box, refs?: Map<Box, string>): string {
+    const lines: string[] = ['控制论投影:能拨的旋钮(可点,@kN 可寻址)+ 态射。布局=旋钮所在栏。']
+    const collectKnobs = (box: Box, acc: Box[]): void => {
+        if (box.kind === 'knob')
+            acc.push(box)
+        for (const c of box.children)
+            collectKnobs(c, acc)
+    }
+    // 顶层栏 = root 的直接 frame 子(并排栏)。每栏内收集旋钮。
+    const columns = root.children.filter(c => c.kind === 'frame')
+    const cols = columns.length ? columns : [root]
+    for (const col of cols) {
+        const knobs: Box[] = []
+        collectKnobs(col, knobs)
+        if (knobs.length === 0)
+            continue
+        const colName = col.label || `<${col.kind}>`
+        lines.push(`\n[${colName} 栏]`)
+        for (const k of knobs)
+            lines.push(`  ${refPrefix(k, refs)}${k.label || `<${k.kind}>`}${k.morphism}`)
+    }
+    return lines.join('\n')
+}