@tapepack/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thewho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @tapepack/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把静态站点压缩后部署到 DeWEB（TapeOut 生态）链上。网站逐字节存在链上，**压缩比 ≈ 省钱比**。产物在未修改的 TapeKit 查看器、网关下直接运行。
+
+支持 BNB Smart Chain、X Layer、Base。需要 Node ≥ 20。
+
+## 一条命令部署
+
+```bash
+export TAPEPACK_PRIVATE_KEY=0x…        # 容器持有人钱包的私钥，只从环境变量读
+npx -p @tapepack/core tapepack deploy ./dist --site 1.2.344
+```
+
+流程依次是：
+
+1. **读链上现有档案作增量基准**：只把变化的文件打成增量卷。
+2. **与链上逐文件比对**：只传变化的文件。
+3. **报价**：列出链上费用、服务费和预估合计，确认后才执行。非交互环境加 `--yes`；只看报价用 `--dry-run`，不需要私钥。
+4. **操作员模式上传**，与网页版同一套：
+   - 主钱包只签两笔：给临时钱包充值（含服务费），授权它写入 2 小时。
+   - 临时钱包流水线写入，写完转服务费，剩余余额退回主钱包，最后读链复核。
+   - 按 Ctrl-C 会在当前这笔确认后停止，并照常退款。中途停止不收服务费。
+
+| 选项 | 说明 |
+|---|---|
+| `--site <名字>` | 链上站点名，如 `1.2.344`；用容器地址时另加 `--chain bnb\|xlayer\|base` |
+| `--dry-run` | 只报价 |
+| `--yes` | 不再询问，直接执行 |
+| `--full` | 不做增量，整体重打 |
+| `--remove-leftovers` | 删除链上有、本地没有的文件（`.well-known/` 等点目录除外） |
+| `--out <目录>` | 保留产物（缺省用临时目录） |
+| `--preset fast\|balanced\|max`、`--strategy auto\|speed\|gas` | 压缩档位、加载策略 |
+| `--rpc <url>` 或环境变量 `TAPEPACK_RPC` | 自备节点 |
+
+上次中断（进程被杀等）时，余额可能留在本机临时钱包（`~/.tapepack/`，权限 0600）。下次部署会接着用，也可以手动退回：
+
+```bash
+npx -p @tapepack/core tapepack refund --chain xlayer
+```
+
+## 服务费
+
+只有部署时收：本次节省额（原样上传费用 − TapePack 上传费用）× 20%，封顶 $2。
+
+- 节省额不到 $0.10、内容没变、取不到实时币价时都不收。
+- 增量更新只按变化的文件计算。
+- 收款地址：`0x6acf9e40122a37e8a43eb594efab2b1752158625`（三条链相同）。
+
+压缩、估算、盘点都免费。
+
+`plan`、`diff`、`deploy-page` 产出可直接发送的 calldata。加 `--src <源站点目录>` 时会附上服务费金额和一笔 `serviceFeeCall`，自行发送时请在全部写完后一并发送。
+
+## 其他命令
+
+```bash
+tapepack pack <站点目录> <产物目录> [--base 1.2.344 | --base-dir <上次产物>]   # 只压缩
+tapepack estimate <目录> --chain all                                       # 三链费用对比
+tapepack inspect <站点名|容器地址>                                          # 盘点链上站点
+tapepack diff <产物目录> --site <站点名> [--src <源站点目录>]                 # 增量更新计划
+```
+
+## 网络
+
+在需要代理的网络里，Node 内置的 fetch 默认不走 `HTTPS_PROXY`。读链和取币价都需要联网，请加：
+
+```bash
+export NODE_USE_ENV_PROXY=1   # Node ≥ 22.21 / 24
+```
+
+取不到实时币价时，本次不收服务费，部署照常进行。

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@tapepack/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TapePack：把静态站点压缩后部署到 DeWEB（TapeOut）链上，上链 Gas 直降——压缩、估算、增量更新、一条命令部署",
+  "license": "MIT",
+  "keywords": [
+    "tapepack",
+    "deweb",
+    "tapeout",
+    "onchain",
+    "web3",
+    "deploy",
+    "compression"
+  ],
+  "bin": {
+    "tapepack": "src/cli.mjs"
+  },
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./src/*": "./src/*",
+    "./vendor/*": "./vendor/*"
+  },
+  "files": [
+    "src",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2",
+    "ethers": "^6.13.0",
+    "sharp": "^0.35.5"
+  }
+}

package/src/archive.mjs

@@ -0,0 +1,38 @@
+// 档案装配编排（浏览器 / Node 共用，pack.mjs 与 web 的 pipeline.js 都走这里，保证产物一致）：
+// 首屏分类 → 整体分卷或增量分层 → 按加载策略决定是否内嵌首屏卷（strategy.mjs）。
+
+import { buildOutputs, BOOT_PATH, G_LAZY, LAZY_RUNTIME_MARK } from './assemble.mjs';
+import { classifyLazy } from './firstscreen.mjs';
+import { planDelta } from './incremental.mjs';
+import { planEmbed } from './strategy.mjs';
+
+/**
+ * @param {Array<{ path: string, bytes: Uint8Array }>} splitFiles 已优化、已分片、含渲染段的站点文件
+ * @param {{ gzip, gunzip?, single?: boolean, base?: object | null, lazy?: boolean | Set<string>,
+ *           embedMax?: number, costRatio?: number, pages?: boolean, lazyTextMin?: number, lazyStoredMin?: number }} opts
+ *   single：整站内嵌进 index.html（不分延后卷、不做增量）
+ *   base：现有档案（增量，见 incremental.planDelta）；lazy：false 关闭首屏分卷，Set 指定延后路径（strategy.planLazy），缺省自动分类
+ *   embedMax：入口内嵌首屏卷的总字节上限（0 = 不内嵌）；costRatio：内嵌多花的 gas 占比上限（见 strategy.planEmbed）
+ * @returns {Promise<{ outputs: object[], groups: Array, embedded: object[], incremental: object | null, lazy: Set<string>,
+ *           baseFile: Set<string> | undefined, embedPlan: object }>}
+ *   outputs：要上链的卷（不含入口、不含已内嵌的卷）；embedded：本次内嵌进入口的卷（校验用）；
+ *   baseFile：交给 renderEntries（多页站点 tpk-base.js 里放哪些卷）
+ */
+export async function assembleArchive(splitFiles, opts) {
+  const { gzip, gunzip, single = false } = opts;
+  const lazy = single || opts.lazy === false ? new Set() : opts.lazy instanceof Set ? opts.lazy : classifyLazy(splitFiles);
+  const sizes = { lazy, lazyTextMin: opts.lazyTextMin, lazyStoredMin: opts.lazyStoredMin };
+  const incremental = opts.base && !single ? await planDelta(splitFiles, opts.base, { gzip, gunzip, ...sizes }) : null;
+  const layered = incremental && incremental.mode !== 'full';
+  const built = layered ? incremental : await buildOutputs(splitFiles, { gzip, ...sizes });
+  // 增量且基准的首屏卷已全部内嵌：沿用（否则更新后打开反而多读一次链）
+  const continuing = layered && opts.base.groups.every((g) => g[1] & G_LAZY || g[2]);
+  const r = planEmbed(built, { files: splitFiles, single, embedMax: opts.embedMax, costRatio: opts.costRatio, pages: opts.pages, continuing });
+  const baseFile = layered ? opts.base.baseFile || new Set() : r.baseFile;
+  // 有延后卷就必须配带延后支持的渲染段（否则延后卷里的文件永远等不到）
+  const boot = splitFiles.find((f) => f.path === BOOT_PATH);
+  if (boot && r.groups.some((g) => g[1] & G_LAZY && !g[2]) && !new TextDecoder().decode(boot.bytes).includes(LAZY_RUNTIME_MARK)) {
+    throw new Error('渲染段缺少延后卷支持：renderBootJs 需要 lazy: true（增量基准里有延后卷时）');
+  }
+  return { outputs: r.outputs, groups: r.groups, embedded: r.embedded, incremental, lazy, baseFile, embedPlan: r.plan };
+}

package/src/assemble.mjs

@@ -0,0 +1,366 @@
+// 分组装配（零 Node 依赖，浏览器/Node 双端）：文本/存储分组、分卷、大文件分片、loader 渲染。
+// 浏览器端（web）与 CLI/MCP（pack.mjs）共用，保证产物格式完全一致。
+
+import { encodeTpk } from './tpk.mjs';
+import { classifyLazy } from './firstscreen.mjs';
+
+/** SiteRegistry 单文件硬上限：350 块 × 24,000B = 8.4MB */
+export const MAX_CHAIN_FILE = 350 * 24_000;
+export const SPLIT_SUFFIX = '.tpkpart'; // 大文件分片后缀：<name>.tpkpart0..N
+export const BOOT_PATH = '.tpk-boot.js'; // loader 渲染段在档案内的路径（index.html 只留引导段）
+// 存储卷索引（写在同一层的文本卷里）：{ v:1, vols: { "g1.tpk": [[path, size, sha256 前 128 位 hex], …] } }
+// 增量更新据此判断存储卷里的文件是否变化，不必下载图片 / wasm 等大卷（见 incremental.mjs / onchain.fetchBase）
+export const INDEX_PATH = '.tpk-index.json';
+export async function shortSha(u8) {
+  const d = new Uint8Array(await crypto.subtle.digest('SHA-256', u8));
+  return Array.from(d.subarray(0, 16), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+const BOOT_RE = /<script type="tpk\/boot">\n([\s\S]*?)<\/script>\n?/;
+
+/**
+ * 大文件分片：超过阈值的文件拆成若干 <name>.tpkpartN（loader 解压后自动拼回）。
+ * 平台单文件上限 8.4MB——esbuild.wasm 这类 12MB 资产必须分片才能上链。
+ */
+export function splitBigFiles(files, threshold = 7_800_000) {
+  const out = [], splits = [];
+  for (const f of files) {
+    if (f.bytes.length <= threshold) { out.push(f); continue; }
+    const n = Math.ceil(f.bytes.length / threshold);
+    for (let i = 0; i < n; i++) {
+      out.push({ path: f.path + SPLIT_SUFFIX + i, bytes: f.bytes.subarray(i * threshold, (i + 1) * threshold) });
+    }
+    splits.push({ path: f.path, bytes: f.bytes.length, parts: n });
+  }
+  return { files: out, splits };
+}
+
+/** 卷表标志位（loader 卷表 G 的第 2 项）：gzip 文本卷 / 延后卷（首屏渲染不等它，见 firstscreen.mjs） */
+export const G_GZIP = 1;
+export const G_LAZY = 2;
+/** 延后文件太少时不单独成卷（多一个链上文件、多一次读取，不划算）：延后文本 / 存储的原始字节下限 */
+export const LAZY_TEXT_MIN = 16_000;
+export const LAZY_STORED_MIN = 16_000;
+/** 入口里内嵌的首屏卷（base64）总字节上限：小站省掉「入口 → 档案」这一次串行读链 */
+export const EMBED_MAX = 16_000;
+export const DEFAULT_NAMES = Object.freeze({ text: 'g0', stored: 'g1', lazyText: 'g2', lazyStored: 'g3' });
+
+/**
+ * 分组 → 卷：文本组 gzip（可多卷）、存储组原样（可多卷）；首屏与延后各自成卷。
+ * 每卷编码后必须 ≤ MAX_CHAIN_FILE；文本卷超限时把末尾文件挪到下一卷重编（gzip 体积无法精确预算）。
+ * 卷名：首屏文本 g0.tpk, g0b.tpk, g0c…；首屏存储 g1…；延后文本 g2…；延后存储 g3…。
+ * 有存储卷或延后卷时，首屏文本层首卷带卷索引（INDEX_PATH：这些卷各有哪些文件；只有存储文件时首卷只含索引）——
+ * loader 据此在延后卷到达前就知道哪些路径在路上，增量更新据此不必下载这些卷。
+ * @param {object[]} files 已分片、已优化的站点文件
+ * @param {{ gzip?: (u8: Uint8Array) => Promise<Uint8Array>, textBudget?: number, storedBudget?: number,
+ *           names?: { text: string, stored: string, lazyText?: string, lazyStored?: string },
+ *           lazy?: Set<string>, lazyTextMin?: number, lazyStoredMin?: number }} [opts]
+ *   names：卷名前缀（缺省 DEFAULT_NAMES；增量卷用 d<N> / d<N>s / d<N>l / d<N>m，见 incremental.mjs）
+ *   lazy：可延后的路径（classifyLazy）；延后文件合计不足 lazyTextMin / lazyStoredMin 时并回首屏卷
+ *   gzip 必须提供（Node：tpk.mjs 的 encodeTpkGzip；浏览器：CompressionStream 封装）
+ * @returns {Promise<{ outputs: Array<{ path, bytes, group: 'text'|'stored', lazy?: true }>, groups: Array<[string, number]> }>}
+ */
+export async function buildOutputs(files, opts = {}) {
+  if (!opts.gzip) throw new Error('buildOutputs: opts.gzip required');
+  const lazySet = opts.lazy || new Set();
+  // 分片按原路径算（策略层对切片前的文件分类，集合里是原路径；分类器直接看分片时集合里是分片名）
+  const isLazy = (p) => lazySet.has(p) || lazySet.has(p.replace(/\.tpkpart\d+$/, ''));
+  const { text: allText, stored: allStored } = splitGroups(files);
+  const sum = (a) => a.reduce((s, f) => s + f.bytes.length, 0);
+  let lazyText = allText.filter((f) => isLazy(f.path)), lazyStored = allStored.filter((f) => isLazy(f.path));
+  if (sum(lazyText) < (opts.lazyTextMin ?? LAZY_TEXT_MIN)) lazyText = [];
+  if (sum(lazyStored) < (opts.lazyStoredMin ?? LAZY_STORED_MIN)) lazyStored = [];
+  const later = new Set([...lazyText, ...lazyStored]);
+  const text = allText.filter((f) => !later.has(f)), stored = allStored.filter((f) => !later.has(f));
+  const outputs = [], groups = [];
+
+  const volName = (base, i) => (i === 0 ? `${base}.tpk` : `${base}${String.fromCharCode(97 + i)}.tpk`);
+  const names = { ...DEFAULT_NAMES, ...opts.names };
+  if (!opts.names?.lazyText && opts.names) names.lazyText = names.text + 'l';
+  if (!opts.names?.lazyStored && opts.names) names.lazyStored = names.text + 'm';
+
+  // 存储组（首屏 / 延后）先分卷（按原始字节贪心装箱，编码近似恒等，预算可靠）
+  const pack = (list) => {
+    const vols = [], budget = opts.storedBudget ?? 8_000_000;
+    let vol = [], volBytes = 0;
+    for (const f of list) {
+      if (vol.length && volBytes + f.bytes.length > budget) { vols.push(vol); vol = []; volBytes = 0; }
+      vol.push(f); volBytes += f.bytes.length;
+    }
+    if (vol.length) vols.push(vol);
+    return vols;
+  };
+  const storedVols = pack(stored), lazyStoredVols = pack(lazyStored);
+  // 文本组按预算分桶，gzip 后超限把桶尾文件下沉到下一桶重编
+  // bulk：大块数据（wasm、切片）另起一卷——和懒加载的 JS / CSS 同卷的话，等一个小模块也得等几 MB
+  const textVols = async (list, base, head, bulk = () => false) => {
+    const budget = opts.textBudget ?? 9_000_000;
+    const buckets = [[]];
+    let acc = 0, prevBulk = false;
+    for (const f of list) {
+      const b = bulk(f);
+      if (buckets[buckets.length - 1].length && (acc + f.bytes.length > budget || b !== prevBulk)) { buckets.push([]); acc = 0; }
+      prevBulk = b;
+      buckets[buckets.length - 1].push(f); acc += f.bytes.length;
+    }
+    if (head) buckets[0].unshift(head); // 索引不计预算，固定在首卷
+    const out = [];
+    for (let bi = 0; bi < buckets.length; bi++) {
+      let bucket = buckets[bi];
+      let encoded = await opts.gzip(encodeTpk(bucket));
+      while (encoded.length > MAX_CHAIN_FILE && bucket.length > 1) {
+        const moved = bucket.pop();
+        if (!buckets[bi + 1]) buckets[bi + 1] = [];
+        buckets[bi + 1].unshift(moved);
+        encoded = await opts.gzip(encodeTpk(bucket));
+      }
+      if (encoded.length > MAX_CHAIN_FILE) throw new Error(`文本卷超限且无法再分（单文件压缩后仍 > 8.4MB）`);
+      out.push({ path: volName(base, bi), bytes: encoded, entries: bucket });
+    }
+    return out;
+  };
+  const isBulk = (f) => /\.wasm$|\.tpkpart\d+$/i.test(f.path);
+  const lazyTextVols = lazyText.length
+    ? await textVols([...lazyText.filter((f) => !isBulk(f)), ...lazyText.filter(isBulk)], names.lazyText, null, isBulk)
+    : [];
+
+  // 卷索引：存储卷与延后卷各有哪些文件（[路径, 字节数, SHA-256 前 128 位]）
+  const vols = {};
+  const listVol = async (name, entries) => { vols[name] = await Promise.all(entries.map(async (f) => [f.path, f.bytes.length, await shortSha(f.bytes)])); };
+  for (let vi = 0; vi < storedVols.length; vi++) await listVol(volName(names.stored, vi), storedVols[vi]);
+  for (const v of lazyTextVols) await listVol(v.path, v.entries);
+  for (let vi = 0; vi < lazyStoredVols.length; vi++) await listVol(volName(names.lazyStored, vi), lazyStoredVols[vi]);
+  const index = Object.keys(vols).length ? { path: INDEX_PATH, bytes: new TextEncoder().encode(JSON.stringify({ v: 1, vols })) } : null;
+
+  // 产物顺序：首屏文本（g0 起）→ 首屏存储 → 延后文本 → 延后存储（同一层内路径不重复，顺序只影响取卷先后）
+  if (text.length || index) {
+    for (const v of await textVols(text, names.text, index)) { outputs.push({ path: v.path, bytes: v.bytes, group: 'text' }); groups.push([v.path, G_GZIP]); }
+  }
+  const storedOut = (list, base, lazy) => {
+    for (let vi = 0; vi < list.length; vi++) {
+      const o = { path: volName(base, vi), bytes: encodeTpk(list[vi]), group: 'stored', ...(lazy ? { lazy: true } : {}) };
+      if (o.bytes.length > MAX_CHAIN_FILE) throw new Error(`存储卷超限 ${o.path}: ${o.bytes.length} > ${MAX_CHAIN_FILE}（单文件本身超限？）`);
+      outputs.push(o);
+      groups.push([o.path, lazy ? G_LAZY : 0]);
+    }
+  };
+  storedOut(storedVols, names.stored, false);
+  for (const v of lazyTextVols) { outputs.push({ path: v.path, bytes: v.bytes, group: 'text', lazy: true }); groups.push([v.path, G_GZIP | G_LAZY]); }
+  storedOut(lazyStoredVols, names.lazyStored, true);
+
+  return { outputs, groups };
+}
+
+/**
+ * 把小的首屏卷内嵌进入口（卷表项第 3 位放 base64）：入口读到就能渲染，省掉「入口 → 档案」这次串行读链
+ * （每次读链是「文件信息 + 内容」两轮多节点核对，公共节点上约 1 秒）。base64 多 1/3 字节，
+ * 但少一个链上文件的固定开销（约 77K gas ≈ 360 字节）。
+ * 首屏卷是并行取的，只要还有一个要读链，内嵌其余的就不省时间——所以要么全部首屏卷（含增量时沿用的旧卷）
+ * 一起内嵌（总量 ≤ max），要么都不内嵌。（只内嵌个别极小卷看似省掉一个文件，但内嵌的字节随入口在每次增量更新时重传，
+ * 更新一次就亏回去了。）
+ * 延后卷不内嵌（--single 除外）：它们本来就不挡首屏，内嵌只会把它们变回首屏数据。
+ * @param {Array<{ path, bytes, group, lazy?, keep? }>} outputs 卷产物（不含入口）
+ * @param {Array<[string, number] | [string, number, string]>} groups 卷表（已内嵌的旧卷第 3 位是 base64）
+ * @param {{ max?: number, all?: boolean }} [opts] all：全部内嵌（--single 单文件模式）；max = 0 不内嵌
+ * @returns {{ outputs: object[], groups: Array, embedded: object[] }} outputs 去掉已内嵌的卷；embedded 为本次内嵌的卷
+ */
+export function embedVolumes(outputs, groups, opts = {}) {
+  const max = opts.all ? Infinity : (opts.max ?? EMBED_MAX);
+  const byPath = new Map(outputs.map((o) => [o.path, o]));
+  const can = (g) => { const o = byPath.get(g[0]); return !g[2] && o && o.bytes && !o.keep ? o : null; };
+  const used = groups.reduce((s, g) => s + (g[2] ? Math.floor((g[2].length * 3) / 4) : 0), 0);
+  // 首屏卷全部内嵌是否可行：还要读链的首屏卷都能内嵌、且总量不超
+  const firstNeed = groups.filter((g) => !(g[1] & G_LAZY) && !g[2]);
+  const allFit = opts.all || (firstNeed.every(can) && used + firstNeed.reduce((s, g) => s + can(g).bytes.length, 0) <= max);
+  const take = new Set();
+  for (const g of groups) {
+    const o = can(g);
+    if (!o) continue;
+    if (opts.all || (allFit && !(g[1] & G_LAZY))) take.add(o);
+  }
+  const embedded = [...take];
+  return {
+    outputs: outputs.filter((o) => !take.has(o)),
+    groups: groups.map((g) => (take.has(byPath.get(g[0])) && !g[2] ? [g[0], g[1], toBase64(byPath.get(g[0]).bytes)] : g)),
+    embedded,
+  };
+}
+
+// 进 gzip 卷的扩展名：文本类，以及压缩率高的二进制 wasm（esbuild.wasm 14MB → gzip 3.8MB；
+// 原样存储时链上多付约 3 倍费用、打开时多读约 3 倍数据）
+export const TEXT_EXT = new Set(['html', 'htm', 'css', 'js', 'mjs', 'json', 'svg', 'txt', 'xml', 'map', 'webmanifest', 'csv', 'wasm']);
+
+/** 内层结构分组的产物描述；真正编码见 tpk.mjs 的 encodeTpk / encodeTpkGzip。分片按原文件扩展名归组 */
+export function splitGroups(files) {
+  const text = [], stored = [];
+  for (const f of files) {
+    const name = f.path.replace(/\.tpkpart\d+$/, '');
+    const ext = name.slice(name.lastIndexOf('.') + 1).toLowerCase();
+    (TEXT_EXT.has(ext) ? text : stored).push(f);
+  }
+  return { text, stored };
+}
+
+/**
+ * 渲染 loader index.html。
+ * @param {string} template loader-template.html 原文（Node 端 fs 读，web 端 ?raw 导入）
+ * @param {object[]} files 站点文件（取 index.html 的 <title>）
+ * @param {Array<[string, number] | [string, number, string]>} groups 卷表 [[档案名, 标志(G_GZIP|G_LAZY), 内嵌 base64?], ...]（见 embedVolumes）
+ * @param {{ minify?: (code: string) => Promise<string>, title?: string }} [opts]
+ */
+export function renderLoaderHtml(template, files, groups, opts = {}) {
+  let tpl = template;
+  const idx = files.find((f) => /^(index\.html|index\.htm)$/i.test(f.path));
+  const m = idx && new TextDecoder().decode(idx.bytes).match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  const title = opts.title || (m ? m[1].trim().slice(0, 120) : '');
+  tpl = tpl.replace('<title>...</title>', `<title>${title.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))}</title>`);
+
+  tpl = tpl.replace(BOOT_RE, ''); // 渲染段不进 index.html，见 renderBootJs
+  // 引导段按卷表剥离：没有延后卷（不再等）就去掉延后处理，没有内嵌卷就去掉 base64 解码
+  tpl = stripSections(tpl, { LAZY: groups.some((g) => g[1] & G_LAZY && !g[2]), EMB: groups.some((g) => g[2]) });
+  tpl = tpl.replace(/__TPK_GROUPS__/g, () => JSON.stringify(groups.length ? groups : [['g0.tpk', G_GZIP]]));
+
+  if (!opts.minify) return tpl;
+  // 最小化：内联脚本过压缩器，HTML 骨架去过注释/空白
+  return opts.minify(tpl);
+}
+
+export const LOADER_JS = 'tpk-loader.js'; // 多页站点共享的引导脚本
+export const BASE_JS = 'tpk-base.js'; // 多页站点：内嵌的首屏卷（base64），只在整体重打时变
+
+/**
+ * 链上入口文件。单页站点：只有 index.html（内联引导段）。
+ * 多页站点：内核对有扩展名的路径不走 fallback（SPEC §6），档案里的 page2.html 直接访问会 404，
+ * 所以每个 HTML 页面在原路径放一个极小入口（~150B：本页标题 + TPK 路由提示 + 引用共享
+ * tpk-loader.js），引导段只上链一份。
+ * 多页站点内嵌的首屏卷放进 tpk-base.js（var TPKB = { 卷名: base64 }，卷表里该项第 3 位记 1）：
+ * 增量更新只改 tpk-loader.js 里的卷表，tpk-base.js 不变、不重传；查看器预取全部 .js、网关下浏览器并行取
+ * 两个脚本，所以不多一次串行读链。单页站点内嵌在 index.html 里（只有它这一个文件，别处放就得多读一次）。
+ * @param {{ pages?: boolean, baseFile?: Set<string> }} [opts] pages：强制多页/单页入口；缺省按 HTML 页数（>1 即多页）
+ *   baseFile：放进 tpk-base.js 的内嵌卷（增量时沿用基准的，见 incremental.resolveBaseFile）；缺省 = 全部内嵌卷（整体打包）
+ *   其余同 renderLoaderHtml
+ * @returns {Promise<Array<{ path: string, text: string }>>}
+ */
+export async function renderEntries(template, files, groups, opts = {}) {
+  const pages = files.filter((f) => /\.html?$/i.test(f.path)).map((f) => f.path);
+  if (!(opts.pages ?? pages.length > 1)) return [{ path: 'index.html', text: await renderLoaderHtml(template, files, groups, opts) }];
+  for (const own of [LOADER_JS, BASE_JS]) if (files.some((f) => f.path === own)) throw new Error(`站点自带 ${own}，与 TapePack 引导脚本重名`);
+  const inBase = opts.baseFile ?? new Set(groups.filter((g) => typeof g[2] === 'string').map((g) => g[0]));
+  const baseVols = groups.filter((g) => typeof g[2] === 'string' && inBase.has(g[0]));
+  const html = await renderLoaderHtml(template, files, groups.map((g) => (baseVols.includes(g) ? [g[0], g[1], 1] : g)), opts);
+  const m = html.match(/<script>([\s\S]*?)<\/script>/);
+  const td = new TextDecoder();
+  const esc = (t) => t.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+  const out = [{ path: LOADER_JS, text: m[1].trim() + '\n' }];
+  if (baseVols.length) out.push({ path: BASE_JS, text: 'var TPKB=' + JSON.stringify(Object.fromEntries(baseVols.map((g) => [g[0], g[2]]))) + ';\n' });
+  for (const f of files) {
+    if (!pages.includes(f.path)) continue;
+    const root = '../'.repeat(f.path.split('/').length - 1);
+    const t = td.decode(f.bytes).match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const tag = (baseVols.length ? '<script src="' + root + BASE_JS + '"></script>' : '')
+      + '<script>var TPK=' + JSON.stringify([f.path, root]) + '</script><script src="' + root + LOADER_JS + '"></script>';
+    out.push({ path: f.path, text: html.replace(m[0], () => tag).replace(/<title>[\s\S]*?<\/title>/, () => '<title>' + esc(t ? t[1].trim().slice(0, 120) : '') + '</title>') });
+  }
+  return out;
+}
+
+/**
+ * loader 渲染段（.tpk-boot.js）：从模板摘出，按需剥离可选段。调用方最小化后作为
+ * { path: BOOT_PATH } 文件加入档案（文本组，享受 gzip），再 buildOutputs。
+ * 可选段（缺省按站点内容自动判断，漏判会坏站，所以判定从宽）：
+ *   worker  —— Worker 拦截（站点脚本出现 Worker( 或 import.meta.url）
+ *   modules —— ES 模块图：相对 import 改写 + import map + import.meta（站点有 ES 模块语法）
+ *   runtime —— 运行时资源地址映射 setAttribute/属性/XHR（站点有任何脚本）
+ *   lazy    —— 延后卷：挂起还没到的文件、到了再补（会分出延后卷时，见 needsLazyRuntime；增量基准里已有延后卷时调用方强制保留）
+ *   cssRuntime —— 运行时样式文本（JS 写入的 <style>、insertRule、FontFace）里的 url() 改写（脚本里出现 url( / FontFace；随 runtime 剥离）
+ *   csp     —— 站点自带 CSP（<meta http-equiv="Content-Security-Policy">）：脚本重建完再放宽插回（HTML 里出现这个 meta）
+ * @param {{ worker?: boolean, modules?: boolean, runtime?: boolean, lazy?: boolean, cssRuntime?: boolean, csp?: boolean }} [opts] 强制保留/剥离
+ */
+export function renderBootJs(template, files, opts = {}) {
+  const m = template.match(BOOT_RE);
+  if (!m) throw new Error('loader template missing tpk/boot section');
+  const keep = {
+    WORKER: opts.worker ?? usesWorker(files),
+    MOD: opts.modules ?? usesModules(files),
+    RT: opts.runtime ?? usesScripts(files),
+    LAZY: opts.lazy ?? needsLazyRuntime(files),
+    CSSRT: opts.cssRuntime ?? usesCssInScripts(files),
+    CSP: opts.csp ?? usesCsp(files),
+  };
+  return stripSections(m[1], keep);
+}
+
+/** 可选段：/*TPK_<名>{*\/ … /*}TPK_<名>*\/ 保留时只去掉标记，否则整段删除 */
+function stripSections(js, keep) {
+  for (const [tag, on] of Object.entries(keep)) {
+    js = on
+      ? js.replace(new RegExp(`/\\*(TPK_${tag}\\{|\\}TPK_${tag})\\*/`, 'g'), '')
+      : js.replace(new RegExp(`/\\*TPK_${tag}\\{\\*/[\\s\\S]*?/\\*\\}TPK_${tag}\\*/`, 'g'), '');
+  }
+  return js;
+}
+
+/** 渲染段里延后卷支持的标志串（剥离后不再出现）：装配时据此确认带延后卷的产物配的是带支持的渲染段 */
+export const LAZY_RUNTIME_MARK = 'data-tpkp-';
+
+/**
+ * 这批文件分卷后会不会出现延后卷（与 buildOutputs 同一套门槛）。站点文件的超集判断：分片前的大文件、
+ * 增量层只含部分文件时都只会更少，所以「不会」是可靠的，渲染段据此剥离延后支持。
+ * @param {{ lazy?: boolean | Set<string>, lazyTextMin?: number, lazyStoredMin?: number }} [opts]
+ */
+export function needsLazyRuntime(files, opts = {}) {
+  if (opts.lazy === false) return false;
+  const lazy = opts.lazy instanceof Set ? opts.lazy : classifyLazy(files);
+  if (!lazy.size) return false;
+  const { text, stored } = splitGroups(files.filter((f) => lazy.has(f.path) || lazy.has(f.path.replace(/\.tpkpart\d+$/, ''))));
+  const sum = (a) => a.reduce((s, f) => s + f.bytes.length, 0);
+  return sum(text) >= (opts.lazyTextMin ?? LAZY_TEXT_MIN) || sum(stored) >= (opts.lazyStoredMin ?? LAZY_STORED_MIN);
+}
+
+const SCRIPT_FILE = /\.(m?js)$/i;
+const HTML_FILE = /\.html?$/i;
+/** 站点是否用 ES 模块（.mjs、<script type=module>、import/export 语法、import.meta） */
+export function usesModules(files) {
+  const td = new TextDecoder();
+  return files.some((f) => {
+    if (/\.mjs$/i.test(f.path)) return true;
+    if (HTML_FILE.test(f.path)) return /<script\b[^>]*type\s*=\s*["']?module/i.test(td.decode(f.bytes));
+    if (!SCRIPT_FILE.test(f.path)) return false;
+    return /\bimport\s*[({"'`*\w]|\bexport\s*[{*\w]|\bimport\.meta\b/.test(td.decode(f.bytes));
+  });
+}
+/** 站点是否有任何脚本（JS 文件或 HTML 内联 / 外链 <script>） */
+export function usesScripts(files) {
+  const td = new TextDecoder();
+  return files.some((f) => SCRIPT_FILE.test(f.path) || (HTML_FILE.test(f.path) && /<script\b/i.test(td.decode(f.bytes))));
+}
+
+/** 站点脚本是否在运行时写 CSS 资源地址（url( 或 FontFace；含 HTML 内联脚本，判定从宽） */
+export function usesCssInScripts(files) {
+  const td = new TextDecoder();
+  return files.some((f) => {
+    if (SCRIPT_FILE.test(f.path)) return /url\(|FontFace/.test(td.decode(f.bytes));
+    if (!HTML_FILE.test(f.path)) return false;
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script>/gi; let m; const h = td.decode(f.bytes);
+    while ((m = re.exec(h))) if (/url\(|FontFace/.test(m[1])) return true;
+    return false;
+  });
+}
+
+/** 站点页面是否自带 CSP（<meta http-equiv="Content-Security-Policy">；判定从宽：出现这个 http-equiv 值就算） */
+export function usesCsp(files) {
+  const td = new TextDecoder();
+  return files.some((f) => HTML_FILE.test(f.path) && /http-equiv\s*=\s*["']?content-security-policy/i.test(td.decode(f.bytes)));
+}
+
+/** 站点脚本是否用到 Worker 或 import.meta.url（loader 需对应垫片） */
+export function usesWorker(files) {
+  const td = new TextDecoder();
+  return files.some((f) => /\.(m?js|html?)$/i.test(f.path) && /\bimport\.meta\.url\b|\bWorker\s*\(/.test(td.decode(f.bytes)));
+}
+
+function toBase64(u8) {
+  if (typeof Buffer !== 'undefined') return Buffer.from(u8).toString('base64');
+  let s = '';
+  for (const b of u8) s += String.fromCharCode(b);
+  return btoa(s);
+}

package/src/chain-read.mjs

@@ -0,0 +1,88 @@
+// 链上站点读取：基于 vendored TapeKit 内核（MIT，零依赖，见 vendor/tapekit/）。
+// 用于 inspect（现状盘点）与 diff（增量更新计划）——只读，不签名不花钱。
+
+import { createHash } from 'node:crypto';
+import { createKernel } from '../vendor/tapekit/kernel.js';
+import { NETWORKS, BSC_MAINNET } from '../vendor/tapekit/config.js';
+import { buildDeployPlan } from './deploy-plan.mjs';
+import { chainById } from './chains.mjs';
+import { estimateGasForFiles } from './estimate.mjs';
+import { isDotPath } from './external.mjs';
+
+const sha256Hex = (u8) => '0x' + createHash('sha256').update(u8).digest('hex');
+
+export function makeKernel() {
+  return createKernel(); // 多链内核：名字带区号自动选链，容器地址全链并查
+}
+
+/**
+ * 盘点一个链上站点：清单 + 每文件 size/sha/updatedAt + 成本估算。
+ * input 支持：链上名字（4246.0 或 1.2.344）/ 容器地址 / 处理器合约#ID（与内核 parseInput 一致）
+ */
+export async function inspectSite(input, opts = {}) {
+  const kernel = opts.kernel || makeKernel();
+  const res = await kernel.resolve(input, { fresh: !!opts.fresh });
+  if (res.status !== 'ok') {
+    const e = new Error(`site status: ${res.status}`);
+    e.detail = res;
+    throw e;
+  }
+  const site = await kernel.openSite(res);
+  const man = site.manifest;
+  // 内核 site.info(p) 是单路径接口；并发逐查（内部各自合并成批请求）
+  const infos = await Promise.all(man.paths.map((p) => site.info(p)));
+  const files = man.paths.map((p, i) => {
+    const f = infos[i];
+    return { path: p, size: f?.size ?? 0, chunks: f?.chunkCount ?? 0, sha: f?.sha ?? null, updatedAt: f?.updatedAt ?? 0 };
+  });
+  const bytes = files.reduce((s, f) => s + f.size, 0);
+  return {
+    input, name: res.name, container: res.container, chainId: res.chainId,
+    fallback: man.fallback, files, fileCount: files.length, bytes,
+    gasEstimate: estimateGasForFiles(files.map((f) => ({ path: f.path, bytes: new Uint8Array(f.size) }))),
+  };
+}
+
+/**
+ * 增量更新计划：本地 TapePack 产物 vs 链上现状。
+ * 返回 { same, changed, added, removed, plan }——plan 只含需要上链的调用（putFile/appendChunk/removeFile）。
+ */
+export async function diffSite(localOutputs, siteInput, opts = {}) {
+  const remote = await inspectSite(siteInput, opts);
+  const remoteBy = new Map(remote.files.map((f) => [f.path, f]));
+  const localBy = new Map(localOutputs.map((o) => [o.path, o]));
+
+  const same = [], changed = [], added = [];
+  for (const o of localOutputs) {
+    const r = remoteBy.get(o.path);
+    // 增量保留卷：链上已有即算相同（不上传、不删除）；链上没有说明基准与链上不符
+    if (o.keep) {
+      if (!r || r.chunks === 0) throw new Error(`增量保留卷 ${o.path} 不在链上：基准与链上现状不符，请以链上为基准重新打包`);
+      same.push({ path: o.path, bytes: r.size, kept: true });
+      continue;
+    }
+    const localSha = sha256Hex(o.bytes);
+    if (!r || r.chunks === 0) added.push({ path: o.path, bytes: o.bytes.length });
+    else if (r.sha?.toLowerCase() === localSha.toLowerCase() && r.size === o.bytes.length) same.push({ path: o.path, bytes: o.bytes.length });
+    else changed.push({ path: o.path, bytes: o.bytes.length, wasBytes: r.size });
+  }
+  // 点开头的目录（.well-known/ 等）不进档案、别的程序直接读：不列入删除，单独报出
+  const extra = remote.files.filter((f) => f.chunks > 0 && !localBy.has(f.path));
+  const removed = extra.filter((f) => !isDotPath(f.path)).map((f) => ({ path: f.path, bytes: f.size }));
+  const keptDot = extra.filter((f) => isDotPath(f.path)).map((f) => f.path);
+
+  const needsUpload = localOutputs.filter((o) => changed.some((c) => c.path === o.path) || added.some((a) => a.path === o.path));
+  const plan = buildDeployPlan(needsUpload, remote.container, {
+    remove: removed.map((r) => r.path),
+    fallback: opts.fallback,
+    registry: chainById(remote.chainId)?.registry,
+  });
+  return {
+    site: { input: siteInput, name: remote.name, container: remote.container, chainId: remote.chainId },
+    same, changed, added, removed, keptDot,
+    updateBytes: needsUpload.reduce((s, o) => s + o.bytes.length, 0),
+    fullBytes: localOutputs.reduce((s, o) => s + o.bytes.length, 0),
+    plan,
+    planGas: estimateGasForFiles(needsUpload.map((o) => ({ path: o.path, bytes: o.bytes }))),
+  };
+}