docs(scripts): explain build and icon generation boundaries

scripts/build-headless.mjs

@@ -9,6 +9,7 @@ import { join, resolve } from 'node:path';
 
 // 路径基于脚本URL而非当前终端目录；tsc仍显式以仓库根作为cwd解析项目依赖。
 const root=resolve(fileURLToPath(new URL('..',import.meta.url))),output=join(root,'.headless-dist');
+// 原产物先删除，后续任一步失败不会恢复上一版；调用方须通过脚本成功退出和包验收后才采用目录。
 await rm(output,{recursive:true,force:true});
 // 同步等待TypeScript生成ESM及声明；继承终端输出，编译失败直接中止后续处理。
 execFileSync(process.execPath,[join(root,'node_modules/typescript/bin/tsc'),'-p',join(root,'tsconfig.headless.json')],{cwd:root,stdio:'inherit'});
@@ -28,6 +29,7 @@ async function declarations(directory){
   }
 }
 // 原生编译器处理运行时import后缀，声明文件仍需此补充；完成后再修URL字面量里的Worker源后缀。
+// 后处理逐文件直接写入，未使用临时目录整体 rename；中途错误可留下部分已改写的输出。
 await declarations(join(output,'modules'));
 // 两个浏览器适配器各应含一个预期Worker URL；要求目标.js文件存在并且源字符串只出现一次才改写。
 for(const [module,worker]of [['browser-digests','digest.worker'],['browser-images','image.worker']]){

scripts/canvas-icon-labels.mjs

@@ -2,6 +2,7 @@
  * 图标资源生成时使用的中文标注表。作为静态元数据输入给generate-canvas-icons，不在运行时逐个请求翻译。
  */
 /** 完整PascalCase图标名到中文标签的人工覆盖表；未列出的图标由生成脚本回退slug拆词名称。 */
+// 两张表都是共享的普通对象，const 不冻结字段；生成器只读取，修改映射后需显式重新生成目录。
 export const chinese = {
   "Star": "星星",
   "Heart": "爱心",

scripts/generate-canvas-icons.mjs

@@ -34,6 +34,7 @@ const categories = [
 /** Lucide常用集合用于默认分类；Tabler试用集稍后全部标记common。 */
 const common = new Set(["Star", "Heart", "Lightbulb", "Sparkles", "Zap", "Target", "Check", "Smile", "Coffee", "Leaf", "Sun", "Moon", "Globe", "MapPin", "ArrowRight", "BookOpen", "FileText", "Folder", "Calendar", "Users", "Image", "Camera", "Music", "Palette"]);
 // Map以唯一name聚合元数据和SVG节点，Lucide加载器的__iconData提供路径，尚未在此写最终分片。
+// Map 以 PascalCase 名称去重，同名后项覆盖；不单独报告名称转换碰撞，输入包格式须按固定版本审查。
 const entries = new Map();
 for (const [slug, load] of Object.entries(dynamicIconImports)) {
   const name = pascal(slug);
@@ -67,8 +68,10 @@ const catalog = records.map(({ node, ...entry }) => {
 });
 // 输出目录带两套版本，manifest把分片逻辑key映射到真实文件名；不在运行时猜hash路径。
 const assetDir = "public/canvas-icons/lucide-1.69.0-tabler-3.50.0";
+// 输出在仓库当前工作目录逐文件写入，不是整体原子替换；失败时可能保留新分片和旧 manifest 的组合。
 await mkdir(assetDir, { recursive: true });
 let totalBytes = 0;
+// 文件名摘要用于资源版本命名，不把截断的12位摘要当作完整校验/授权凭据；消费者按 manifest 定位。
 const assets = {};
 // 每个分片用紧凑JSON计算SHA-256前12位作文件名，写文件额外加换行；totalBytes统计未加换行的内容字节。
 for (const [key, nodes] of shards) {

scripts/loaders/xyflow-retained.cjs

@@ -5,6 +5,7 @@
 // App-only extension for the pinned @xyflow/react 12.12.1 ESM renderer. This
 // transforms compiler input; shared node_modules and the headless SDK are untouched.
 // 读取安装包版本，固定12.12.1；库升级必须人工审查目标实现，不能凭相同函数名继续替换。
+// require 在 loader 模块求值时读取一次版本，不在每个输入转换时重新扫描安装目录。
 const version = require('@xyflow/react/package.json').version;
 /** webpack/Turbopack loader接收源码并返回改写后的源码；任何版本或锚点不符立即失败，防止悄悄失去保留能力。 */
 module.exports = function retainVisibility(source) {
@@ -20,6 +21,7 @@ module.exports = function retainVisibility(source) {
   }
   // 节点追加未hidden且显式保留的ID并Set去重；边以保留标记或原可见判断二选一，维持原生索引。
   // 最后一处改为空数组不订阅完整选择集合，减少无选择监听时的不必要全图selector工作。
+  // 返回新字符串，不写磁盘；锚点检查只确认当前四段文本的形状，不证明升级后所有语义仍等价。
   return source
     .replace(nodes, `Array.from(new Set([
       ...${nodes},