From c3e7d01c091d0a75b4d6d0f0d190c0573dd5ff2c Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 21:18:12 +0800 Subject: [PATCH] docs: clarify tool outputs and example window contexts --- examples/window.endor | 3 ++- examples/windows.endor | 3 ++- scripts/build-macos-app.sh | 3 ++- scripts/render-uml.mjs | 5 ++++- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/examples/window.endor b/examples/window.endor index 61adcf1..3c8a1d0 100644 --- a/examples/window.endor +++ b/examples/window.endor @@ -23,7 +23,8 @@ class WindowBand: RectBlock { return MeasureResult(constraints.maxWidth, 32) } } -// ui.window 返回当前主窗口托管资源；page.open 指定同一资源，后面的 title/resize 为原生命令。 +// 此文件顶层在默认主窗口上下文执行，ui.window() 因而取主窗口；事件/渲染回调中则跟随其当前窗口上下文。 +// page.open 指定保存的同一资源，后面的 title/resize 为异步原生命令，不等于已改变原生实际尺寸。 window = ui.window() actions = WindowActions(window) band = WindowBand(80, 32, 0, "#237A45") diff --git a/examples/windows.endor b/examples/windows.endor index 7abf4d3..a0c7964 100644 --- a/examples/windows.endor +++ b/examples/windows.endor @@ -22,7 +22,8 @@ right.title = "独立窗口页面" right.render(Column(24,16,TextBlock("关闭窗口会解除 Page 归属，保留的对象仍可重开"),ui.textOf(count,"value"),rightButton)) // 把页面放到 other，上下文更换将重建出现位置，业务 count 仍不变。 right.open(other) -// open 把 right 归入副窗口；下面 ui.window() 仍用于源会话的主窗口，other 则显式选中副窗口资源。 +// open 把 right 归入副窗口；它不把后续顶层执行上下文永久改为该窗口，下面 ui.window() 仍取默认主窗口。 +// 若在副窗口事件回调里调用 ui.window()，则取该事件窗口；other 变量始终显式指向此处构造的副窗口资源。 // 窗口命令针对各自资源编号排队；成功输入后再交 GUI，另一窗口设置自己的尺寸。 ui.window().setTitle("Endor Main") other.setTitle("Endor Shared") diff --git a/scripts/build-macos-app.sh b/scripts/build-macos-app.sh index 92bc383..4d32f16 100755 --- a/scripts/build-macos-app.sh +++ b/scripts/build-macos-app.sh @@ -12,9 +12,10 @@ fi # 以脚本所在目录的父目录作为仓库根；清空这一次 cd 的 CDPATH，防止用户 shell 配置改变目录解析。 cd "$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)" # 锁定依赖并生成 release 可执行文件；附加参数原样交给 Cargo。 +# 后续复制路径固定为 target/release/tessera，不会随 --target、--target-dir 或 CARGO_TARGET_DIR 自动调整。 # 这里确实触发编译，不是只验证清单；依赖锁不匹配时 --locked 要求失败而非自动更新 Cargo.lock。 cargo build --release --locked "$@" -# 从 Cargo 包元数据读取首个 version 值，空值由 test 拒绝，不生成缺版本的 bundle。 +# 从 Cargo.toml 文本读取首个行首 version 值，空值由 test 拒绝；这不是 cargo metadata 的结构化查询。 # version 从清单文本读取，后面用于两个 plist 版本键；脚本不调用构建后的 Tessera 来查询版本。 version=$(awk -F '"' '$1 ~ /^version[[:space:]]*=/ { print $2; exit }' Cargo.toml) test -n "$version" diff --git a/scripts/render-uml.mjs b/scripts/render-uml.mjs index 2bbcf06..7c18cb2 100644 --- a/scripts/render-uml.mjs +++ b/scripts/render-uml.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node // 文档 UML 批量渲染入口：读取仓库内 .puml，在 rendered 中写入 SVG/PNG。 -// 固定版本的工具包安装到独立临时目录，由 UML_RENDER_TOOLS 指定；不会修改应用依赖。 +// UML_RENDER_TOOLS 指向已安装依赖的工具目录；README 给出固定版本安装示例，脚本自身不安装或校验版本。 import { createRequire } from 'node:module'; import { readFile, readdir, mkdir, writeFile } from 'node:fs/promises'; import path from 'node:path'; @@ -18,6 +18,7 @@ const sharp = require('sharp'); // 官方 PlantUML JS 引擎依赖 DOM、Graphviz 和 Canvas 文本度量。 // 在导入引擎前补齐全局环境，让 Node 进程可执行原本面向浏览器的布局过程。 +// 这些赋值修改当前 Node 进程 globalThis，脚本结束前不恢复；按独立命令行工具使用，不是无全局副作用的库。 globalThis.PLANTUML_VIZ = require('@viz-js/viz'); globalThis.window = globalThis; globalThis.XMLSerializer = XMLSerializer; @@ -83,6 +84,7 @@ for (const filename of (await readdir(source)).filter(name => name.endsWith('.pu const rendered = await new Promise((resolve, reject) => renderToString(text.split('\n'), resolve, reject)); const xml = new DOMParser().parseFromString(rendered, 'image/svg+xml'); // 引擎有时以正常 SVG 输出错误页，所以不能只判断 Promise resolve；还要检查文字层的错误标签。 + // 检查根标签和几类错误文本，不是完整 SVG/XML 语义验证，也不保证识别引擎所有错误页格式。 const labels = Array.from(xml.getElementsByTagName('text'), node => node.textContent).join('\n'); if (xml.documentElement.tagName !== 'svg' || /syntax error|error line|assumed diagram type|an error has occurr/i.test(labels)) { throw new Error(`${filename}: renderer returned an error diagram\n${labels}`); @@ -96,6 +98,7 @@ for (const filename of (await readdir(source)).filter(name => name.endsWith('.pu // 同时保存可缩放 SVG 和通用 PNG；写完读取 PNG 元数据确认生成尺寸。 const stem = filename.slice(0, -5); // 两种产物顺序写入且不组成事务；SVG 成功后若 PNG 失败，前面已写出的文件不会自动回滚。 + // 同名文件直接覆盖；本轮没有对应 .puml 的旧产物不会被自动删除，较早已完成的图也不会因后图失败撤回。 await writeFile(path.join(output, `${stem}.svg`), svg); // 以 192 DPI 光栅化为 PNG 供通用预览；SVG 同时保留矢量文字和缩放能力。 const png = sharp(Buffer.from(svg), { density: 192 });