docs: clarify tool outputs and example window contexts

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")

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")

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"

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 });