@adep/web-container 0.2.1 → 0.2.3

package/dist/bundle-export.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 产物导出（PV-006）：把浏览器内 dev server 的 **blob 文档**序列化成一份可经真实 HTTP 源服务的
+ * 自包含产物（`{ html, modules, paths }`），交给平台预览子域。
+ *
+ * 背景（为什么需要它）：Web IDE 的前端预览由 `@adep/web-container` 的 `vite` 命令在浏览器内编译，
+ * 产物是一个 **`blob:` 入口文档**——模块之间的 import 说明符在编译期被改写成彼此的 blob URL。
+ * blob URL 只在「创建它的那个标签页」里有效：复制出去在别的浏览器打开必然失效，且 blob 是不可
+ * 分层 scheme，`history.pushState('/about')` 这类单页路由调用直接抛错。于是「像 CodeSandbox 那样
+ * 复制预览链接」这件事在 blob 形态下不可能做到。
+ *
+ * 本模块的做法：**顺着 blob 引用抓一份完整模块图，改写成内容寻址的 HTTP 路径**——
+ * 1. 读入口文档 → 找出其中所有 `blob:` 引用（`<script src="blob:…">`）；
+ * 2. 逐个读取这些 blob 的源码，再从中找出它们的 `blob:` 引用（编译期已改写为依赖的 URL）→ 递归，
+ *    直到闭包；
+ * 3. 每份源码按内容哈希命名（同内容必然同路径 → 跨版本复用、天然去重、变更必然换名），
+ *    路径形如 `/_adep/m/<hash>.js`（与服务端 `PREVIEW_MODULE_URL_RE` 白名单一致）；
+ * 4. 把所有源码里的 blob URL 替换成对应路径，得到自包含产物。
+ *
+ * 增量发布（`known`）：每次发布都把**完整闭包读一遍**（blob 就在页内存里，读取代价近乎为零），
+ * 但只把「服务端还没有的模块」放进产物体 `modules`——内容寻址下「同路径 ⇔ 同内容」，判据就是
+ * 「路径是否出现在上一次发布的映射值里」。产物另带 `paths`（本次入口所需的**全部**模块路径，
+ * 含未重复上传的那些），服务端据此写清单并清理幽灵模块：**清单必须完整**，漏报会把仍在用的
+ * 模块当幽灵删掉（页面白屏）。
+ *
+ * 为什么不干脆「已知模块连读都跳过」（更省一层）：跳读会丢掉该模块的依赖边，除非调用方保证
+ * `known` 是**完整闭包**——把正确性押在调用方的记性上，一旦传了半张表就静默产出缺模块的产物，
+ * 白屏且极难诊断。读一遍是最便宜的保险；真正贵的是网络上传，而那部分已经省掉了。
+ *
+ * 产物随后由 `POST /api/v1/projects/:id/preview` 落到项目桶，由预览子域服务：真实 HTTP 源 →
+ * 跨浏览器可用、SPA 路由（history 模式）原生可用、`/api/*` 走平台网关执行项目函数。
+ *
+ * 边界：只搬运**文本模块**。图片等二进制资产若出现在 VFS 里，dev server 本就不会把它编译成模块
+ * （解析链只认 JS/TS/CSS/JSON/Vue），故不在此处理；`readText` 拿不到内容时响亮抛错，不静默产出残缺产物。
+ */
+/** 模块 URL 前缀（与 `server/domains/preview/store.ts` 的 `PREVIEW_MODULE_URL_PREFIX` 对齐）。 */
+export declare const BUNDLE_MODULE_PATH_PREFIX = "/_adep/m/";
+export interface BundleExportOptions {
+    /** 入口文档 URL（dev server 产出的 blob 文档）。 */
+    documentUrl: string;
+    /**
+     * 读取 URL 文本（默认 `fetch(url).then(r => r.text())`）。
+     * 注入缝：Node 单测用假实现，不依赖真实 blob 存储。
+     */
+    readText?: (url: string) => Promise<string>;
+    /** 模块 URL 前缀（默认 `/_adep/m/`）。 */
+    modulePathPrefix?: string;
+    /** 内容 → 模块名（不含扩展名）。默认 sha256 前 16 位 hex；注入以便单测确定化。 */
+    moduleName?: (code: string) => string | Promise<string>;
+    /** 注入到入口文档 `</body>` 前的脚本（IDE 侧用于错误中继等；默认不注入）。 */
+    appendScript?: string;
+    /**
+     * 上一次发布的 blob URL → 模块路径映射（即上次 `ExportedBundle.urls`）。
+     * 用途只有一个：**跳过重复上传**（值集 = 服务端已有的路径集）。传空/不传 = 全量发布。
+     */
+    known?: ReadonlyMap<string, string>;
+}
+export interface ExportedBundle {
+    /** 自包含入口文档（blob 引用已改写为模块路径）。 */
+    html: string;
+    /** **需要上传**的模块（路径 → 源码）：已在上一次发布里存在的模块不再出现在这里。 */
+    modules: Record<string, string>;
+    /** 本次入口文档所需的**全部**模块路径（含本次未重复上传的；服务端据此写清单与清理幽灵）。 */
+    paths: string[];
+    /** 本次闭包的 blob URL → 路径映射；调用方保存，下次作为 `known` 传入。 */
+    urls: Map<string, string>;
+}
+/** 默认模块名：sha256 前 16 位 hex（浏览器均有 `crypto.subtle`）。 */
+export declare function defaultModuleName(code: string): Promise<string>;
+/** 找出文本里的全部 blob 引用（去重、保序）。 */
+export declare function findBlobRefs(text: string): string[];
+/**
+ * 导出产物：入口文档 + 递归闭包内全部模块（内容寻址命名 + 引用改写）。
+ * 读不到某个 blob（已被撤销 / 网络异常）→ 抛错（残缺产物比失败更糟：页面白屏且难以诊断）。
+ */
+export declare function exportBundle(options: BundleExportOptions): Promise<ExportedBundle>;

package/dist/function-fetch-proxy.d.ts

@@ -6,6 +6,8 @@
  * fetch 拦截器，把 `/api/*` 请求经 `window.parent.postMessage` 转发到 IDE 主线程；主线程
  * 用 `OfflineRunner` 执行**当前项目的云函数草稿**（改函数即生效，因为每次都实时取草稿），
  * 再把执行结果 postMessage 回 iframe。与 origin 无关：blob URL 与异源 Nodebox 隧道都能用。
+ * 新窗口打开预览（window.open）时 window.parent === window，回退到 window.opener.postMessage，
+ * 主线程经 event.source 单播回响应——新窗口与 iframe 共用同一套协议。
  *
  * 消息协议（两侧逐字对齐；改任一侧必须同步另一侧——见 web-project-template.ts 的
  * web/vite.config.ts 模板里那份逐字复制的 FN_PROXY_SCRIPT）：
@@ -28,9 +30,21 @@ export interface OfflineRunner {
 /**
  * 浏览器端 fetch 拦截器脚本（IIFE，纯 JS——必须能直接内联进 `<script>`，不能有 TS / ESM）。
  *
- * **同步纪律**：本字符串与 `shared/sdk/web-project-template.ts` 里 web/vite.config.ts 模板的
- * `FN_PROXY_SCRIPT` 必须**逐字一致**（两处复制粘贴，无共享 import——预览 iframe 与浏览器内
- * vite-dev 是两个独立加载上下文，共享一份源码反而会引入打包耦合）。改这里务必同步另一侧。
+ * **同步纪律**：本字符串与 `packages/vite-plugin/src/ide-proxy.ts` 的
+ * `FN_FETCH_INTERCEPTOR_SCRIPT`（单一真相源）必须**逐字一致**（两处复制粘贴，无共享
+ * import——预览 iframe 与浏览器内 vite-dev 是两个独立加载上下文，共享一份源码反而会引入
+ * 打包耦合）。改这里务必同步另一侧。
+ *
+ * blob base 兼容（2026-09-11 修复）：浏览器内 vite-dev 预览文档的 baseURI 是 blob: URL，
+ * `new URL('/api/x', 'blob:…')` 抛 TypeError → 拦截器退化成原生 fetch 报
+ * "Failed to parse URL"。首次解析失败时用 `window.location.origin`（blob 继承创建者
+ * origin）兜底再解析一次。
+ *
+ * 新窗口预览（2026-09-12）：`window.open` 打开的新标签页 `window.parent === window`，
+ * 回退到 `window.opener.postMessage` 转发 /api/* 请求（不能用 noopener，否则 opener 为 null）。
+ * blob URL SPA 路由：patch `history.pushState/replaceState`，对相对路径直接吞掉（blob 不可
+ * 分层，原生 pushState 解析相对路径抛 TypeError），`location.pathname` 覆盖为当前路由路径，
+ * sessionStorage 持久化，刷新后恢复。
  */
 export declare const FN_FETCH_INTERCEPTOR_SCRIPT: string;
 /** IDE 主线程侧的消息处理器类型：直接挂到 `window.addEventListener('message', handler)`。 */

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export type { ModuleCache, RequireOptions } from './module-loader';
 export { createViteServer, scanEsmSpecifiers, ViteDevError } from './vite-dev';
 export type { SfcCompiler, ViteServer, ViteServerOptions, ViteCommandPort, ViteCommandOutcome, EsmSpecifierHit, } from './vite-dev';
 export * as posix from './path';
+export { exportBundle, findBlobRefs, defaultModuleName, BUNDLE_MODULE_PATH_PREFIX, } from './bundle-export';
+export type { BundleExportOptions, ExportedBundle } from './bundle-export';
 export { snapshotVfs, restoreVfs, entriesToTree, createMemoryFsBackend, createIndexedDbFsBackend, pickDefaultFsBackend, createFsPersistence, createMemoryKvStorage, createCommandHistory, } from './persistence';
 export type { FsPersistEntry, FsPersistenceBackend, FsPersistence, FsPersistenceOptions, CommandHistory, KvStorage, } from './persistence';
 export { SHELL_COMMANDS, EXTRA_COMMANDS, COMPLETABLE_COMMANDS, parseCompletionContext, completeWithListing, completeShellInput, completeContainerInput, applyCompletion, candidateLabel, } from './completion';