xbintsc 0.5.32 → 0.5.36

package/doc/zh-CN/gui/webgl.md

@@ -55,7 +55,7 @@ SDL_GPU 不能在运行时编译 GLSL，且每个后端只消费自己的格式
 
 两个阶段的非采样器 uniform 会合并成同一个块，并在每个阶段各声明一次（顶点 set 1、片元 set 3），与 SDL_GPU 的 Vulkan 描述符布局一致。在 Metal 上同一批声明会变成 `[[buffer(0)]]` 与 `[[texture(N)]]`/`[[sampler(N)]]`，正是 SDL_GPU Metal 后端绑定的槽位。`uniformMatrix4fv` 按列主序写入反射出的偏移；对采样器调用 `uniform1i` 时记录纹理单元。每次绘制都用动态 uniform 缓冲接口推送该块。
 
-翻译器的限制：结构体 uniform、用户 uniform 块、预处理后仍无法确定长度的 uniform 数组、采样器数组与立方体贴图都会被拒绝（着色器/链接日志会说明）。`#ifdef` 内的代码没问题；非采样器 uniform 声明会被移到外层顶层位置，保证块是无条件的。
+翻译器的限制：结构体 uniform、用户 uniform 块、预处理后仍无法确定长度的 uniform 数组、采样器数组与采样器类型不匹配的声明会被拒绝（着色器/链接日志会说明）。`#ifdef` 内的代码没问题；非采样器 uniform 声明会被移到外层顶层位置，保证块是无条件的。
 
 ### GLSL ES 3.00（WebGL 2）
 
@@ -63,15 +63,15 @@ SDL_GPU 不能在运行时编译 GLSL，且每个后端只消费自己的格式
 
 ## 支持的 API
 
-- **上下文**：`getContext("webgl")`、`canvas`、`drawingBufferWidth/Height`、`getParameter`、`getError`、`getSupportedExtensions`、`getExtension`、`getContextAttributes`、`isContextLost`、`getShaderPrecisionFormat`，以及模板入口（接受状态；深度目标没有模板附件）。
+- **上下文**：`getContext("webgl")`、`canvas`、`drawingBufferWidth/Height`、`getParameter`、`getError`、`getSupportedExtensions`、`getExtension`、`getContextAttributes`、`isContextLost`、`getShaderPrecisionFormat`，以及 8 位模板缓冲（`getContextAttributes().stencil` 为 `true`，`STENCIL_BITS` 为 8）。`WEBGL_lose_context` 的 `loseContext`/`restoreContext` 会真正丢弃并重建上下文（对象全部失效），并派发 `webglcontextlost` / `webglcontextrestored` 事件。
 - **着色器与程序**：`createShader`、`shaderSource`、`compileShader`、`getShaderParameter`、`getShaderInfoLog`、`getShaderSource`、`deleteShader`、`createProgram`、`attachShader`、`detachShader`、`linkProgram`、`getProgramParameter`、`getProgramInfoLog`、`getAttachedShaders`、`validateProgram`、`deleteProgram`、`useProgram`、`getActiveUniform`/`getActiveAttrib`、`getUniformLocation`、`getAttribLocation`、`bindAttribLocation`。
 - **Uniform**：`uniform1f`…`uniform4f`、`uniform1i`…`uniform4i`、`uniform1fv`…`uniform4fv`、`uniform1iv`…`uniform4iv`、`uniformMatrix2fv`/`3fv`/`4fv`、`getUniform`。
-- **缓冲与顶点属性**：`createBuffer`、`bindBuffer`、`bufferData`、`bufferSubData`、`deleteBuffer`、`getBufferParameter`、`enableVertexAttribArray`、`disableVertexAttribArray`、`vertexAttribPointer`、`vertexAttrib1f`…`4f` / `1fv`…`4fv`、`getVertexAttrib`。
+- **缓冲与顶点属性**：`createBuffer`、`bindBuffer`、`bufferData`、`bufferSubData`、`deleteBuffer`、`getBufferParameter`、`enableVertexAttribArray`、`disableVertexAttribArray`、`vertexAttribPointer`、`vertexAttrib1f`…`4f` / `1fv`…`4fv`、`getVertexAttrib`。`bufferData` 的 `usage` 提示（`STREAM_DRAW`/`STATIC_DRAW`/`DYNAMIC_DRAW`）会被记录，`getBufferParameter(…, BUFFER_USAGE)` 可读回。
 - **绘制**：`drawArrays`、`drawElements`（UNSIGNED_BYTE、UNSIGNED_SHORT、UNSIGNED_INT；`TRIANGLE_FAN` 与 `LINE_LOOP` 会展开为列表）。`POINTS`、`LINES`、`LINE_STRIP`、`TRIANGLES`、`TRIANGLE_STRIP` 映射到对应的 SDL 图元。
-- **纹理**：`createTexture`、`bindTexture`、`activeTexture`、`texParameteri`/`texParameterf`、`getTexParameter`、`texImage2D`（原始像素、`<img>`、`<canvas>`、`ImageData`）、`texSubImage2D`、`generateMipmap`、`deleteTexture`。支持 `UNPACK_FLIP_Y_WEBGL` 与 `UNPACK_PREMULTIPLY_ALPHA_WEBGL`。全部转换为 RGBA8；接受 `RGBA`、`RGB`、`LUMINANCE`、`ALPHA`、`LUMINANCE_ALPHA` 配 `UNSIGNED_BYTE`。
-- **Framebuffer**：`createFramebuffer`、`bindFramebuffer`、`framebufferTexture2D`（颜色附件）、`checkFramebufferStatus`、`createRenderbuffer`、`bindRenderbuffer`、`renderbufferStorage`（深度）、`framebufferRenderbuffer`、`delete*`。足以实现渲染到纹理、阴影贴图与后处理。
-- **状态**：`enable`/`disable`/`isEnabled`（`BLEND`、`DEPTH_TEST`、`CULL_FACE`、`SCISSOR_TEST`；模板状态接受但不生效）、`clearColor`/`clearDepth`/`clearStencil`、`clear`、`blendFunc`/`blendFuncSeparate`、`blendEquation`/`blendEquationSeparate`、`depthFunc`、`depthMask`、`colorMask`、`cullFace`、`frontFace`、`viewport`、`scissor`、`pixelStorei`、`finish`。
-- **读回**：`readPixels`（RGBA/UNSIGNED_BYTE），可从默认帧缓冲或绑定的 framebuffer 读取。它会阻塞到 GPU 完成；用于测试和截图，不要每帧调用。
+- **纹理**：`createTexture`、`bindTexture`、`activeTexture`、`texParameteri`/`texParameterf`、`getTexParameter`、`texImage2D`（原始像素、`<img>`、`<canvas>`、`ImageData`）、`texSubImage2D`、`generateMipmap`、`deleteTexture`。支持 `UNPACK_FLIP_Y_WEBGL` 与 `UNPACK_PREMULTIPLY_ALPHA_WEBGL`。默认转换为 RGBA8；`RGBA`/`RGB`/`LUMINANCE`/`ALPHA`/`LUMINANCE_ALPHA` 配 `UNSIGNED_BYTE` 可用。浮点纹理（`RGBA32F`、`RGBA16F`、`RGB32F`、`RGB16F`、`RG32F`/`RG16F`、`R32F`/`R16F`，`FLOAT` 或 `HALF_FLOAT` 数据，以及 WebGL 1 的 `OES_texture_float`/`OES_texture_half_float`）映射到 SDL 的 RGBA32F/RGBA16F；深度纹理（`DEPTH_COMPONENT16/24/32F`、`DEPTH_STENCIL`、`DEPTH24_STENCIL8`）映射到 `D32_FLOAT`/`D32_FLOAT_S8_UINT`，可作为采样源或深度附件。压缩纹理通过 `compressedTexImage2D`/`compressedTexSubImage2D` 上传，支持 `WEBGL_compressed_texture_s3tc`（BC1/BC2/BC3）、`WEBGL_compressed_texture_s3tc_srgb` 与 `WEBGL_compressed_texture_astc`；扩展只在设备确实支持对应格式时公布。`texImage2D` 还接受 `<video>` 的最新解码帧与 `createImageBitmap` 产生的 `ImageBitmap`。立方体贴图（`bindTexture(TEXTURE_CUBE_MAP)` + 六个 `texImage2D` 面）与 3D/数组纹理（`texImage3D`/`texStorage3D`）可用对应采样器（`samplerCube`、`sampler3D`、`sampler2DArray`）采样；`texSubImage3D` 可更新 3D/数组纹理的子区域，`framebufferTextureLayer` 可把数组/立方体贴图的指定层作为颜色附件渲染。
+- **Framebuffer**：`createFramebuffer`、`bindFramebuffer`（`FRAMEBUFFER`/`READ_FRAMEBUFFER`/`DRAW_FRAMEBUFFER`）、`framebufferTexture2D`（`COLOR_ATTACHMENT0`、`DEPTH_ATTACHMENT`、`DEPTH_STENCIL_ATTACHMENT`）、`checkFramebufferStatus`、`createRenderbuffer`、`bindRenderbuffer`、`renderbufferStorage`（深度/深度模板）、`framebufferRenderbuffer`、`delete*`，以及 `blitFramebuffer`（颜色附件；深度/模板位被接受但不复制）。足以实现渲染到纹理、阴影贴图与后处理。
+- **状态**：`enable`/`disable`/`isEnabled`（`BLEND`、`DEPTH_TEST`、`CULL_FACE`、`SCISSOR_TEST`、`STENCIL_TEST`）、`clearColor`/`clearDepth`/`clearStencil`、`clear`（开启 `SCISSOR_TEST` 时颜色、深度与模板都只清除 scissor 矩形）、`blendColor`、`blendFunc`/`blendFuncSeparate`、`blendEquation`/`blendEquationSeparate`、`depthFunc`、`depthMask`、`colorMask`、`stencilFunc`/`stencilFuncSeparate`、`stencilOp`/`stencilOpSeparate`、`stencilMask`/`stencilMaskSeparate`、`cullFace`、`frontFace`、`viewport`、`scissor`、`pixelStorei`、`finish`。模板测试真正参与光栅化，`clear(STENCIL_BUFFER_BIT)` 会清空模板附件；SDL_GPU 只有一份前后脸共用的 reference 与 compare/write mask，若前后脸设置不同，使用前脸值。
+- **读回**：`readPixels`（RGBA/UNSIGNED_BYTE），可从默认帧缓冲或绑定的 RGBA8 framebuffer 读取；浮点/深度附件先采样到 RGBA8 目标再读回。它会阻塞到 GPU 完成；用于测试和截图，不要每帧调用。
 
 WebGL 2 额外提供：
 
@@ -80,18 +80,18 @@ WebGL 2 额外提供：
 - **整数属性与 uniform**：`vertexAttribIPointer`、`vertexAttribI4*` 系列、`uniform1ui`…`uniform4ui`。
 - **采样器对象**：`createSampler`、`bindSampler`、`deleteSampler`、`samplerParameteri/f`、`getSamplerParameter`；绑定的采样器会覆盖该单元上纹理自身的过滤/环绕状态。
 - **不可变纹理与缓冲拷贝**：`texStorage2D`（后端始终分配完整 mip 链）、`copyBufferSubData`、`getBufferSubData`。
+- **绘图缓冲**：`drawingBufferStorage(width, height)` 固定绘图缓冲尺寸；此后 `canvas.width` / `canvas.height` 不再重建它。
 - **清除**：`clearBufferfv`、`clearBufferiv`、`clearBufferuiv`、`clearBufferfi`。
+- **多渲染目标**：`drawBuffers` 最多 4 个颜色附件，`readBuffer` 选择 `readPixels` 的附件；`framebufferTexture2D` 可挂 `COLOR_ATTACHMENT0`…`3`，片元着色器的多个 `out` 按顺序写入。
 - **查询与栅栏**：对象与入口都存在（`createQuery`/`beginQuery`/`endQuery`/`getQueryParameter`、`fenceSync`/`clientWaitSync`/`waitSync`/`getSyncParameter`），行为是优雅降级：栅栏报告 `ALREADY_SIGNALED`，查询结果为 0。
-- **Uniform 块**：`getUniformBlockIndex` 返回 `INVALID_INDEX`，让库回退到独立 uniform；块相关入口为空操作。
-- **Transform feedback、3D 纹理与压缩格式**：入口存在但为空操作，避免特性探测类库抛错。
+- **Uniform 块**：`getUniformBlockIndex`、`getActiveUniformBlockParameter`、`getActiveUniformBlockName`、`uniformBlockBinding`、`bindBufferBase`/`bindBufferRange`、`getIndexedParameter`。块成员按 std140 合并进引擎的单一 uniform 块，绘制时从绑定缓冲复制；支持标量/向量/矩阵与定长数组，不支持嵌套结构体、采样器成员和省略实例名的块。
+- **Transform feedback**：入口存在但为空操作，避免特性探测类库抛错。
 
-纹理创建时带完整 mip 链；在 `generateMipmap` 之前采样被钳制到第 0 层。矩阵顶点属性会占用相应数量的连续 location，每个 location 读取一列。未启用的属性由最近一次 `vertexAttrib*f` 的值通过一个小常量缓冲提供。
+纹理创建时带完整 mip 链；在 `generateMipmap` 之前采样被钳制到第 0 层。矩阵顶点属性会占用相应数量的连续 location，每个 location 读取一列。未启用的属性由最近一次 `vertexAttrib*f` 的值通过一个小常量缓冲提供。顶点着色器可以像片元着色器一样采样纹理：`MAX_VERTEX_TEXTURE_IMAGE_UNITS` 报告 16，顶点采样器走 set 0，并在每次绘制时通过 `SDL_BindGPUVertexSamplers` 绑定。深度值按后端的 `[0, 1]` 裁剪空间存储，不做 GL 的 `[-1, 1] → [0, 1]` 重映射：`gl_Position.z = 0.5` 写入的深度是 `0.5`（真实 WebGL 为 `0.75`）。
 
 ## 未实现
 
-着色器源码里的 uniform buffer 对象、transform feedback（入口为空操作）、立方体贴图、3D/数组纹理、浮点/半浮点纹理、深度纹理、压缩纹理、多渲染目标（只写第一个片元输出）、`blitFramebuffer`、MSAA/采样缓冲、模板操作（状态接受，但不写模板缓冲）、常量混合颜色、`drawingBufferStorage`、上下文丢失、`bufferData` 的非 static/dynamic `usage`（提示被忽略）、`texImage2D` 对 `HTMLVideoElement`/`ImageBitmap` 的支持，以及带 scissor 的 `clear`（clear 会清空整个附件）。使用内建块、用户 uniform 块或超出支持范围的 `gl_FragDepth` 的着色器会以编译/链接日志报错。
-
-引擎报告的顶点纹理单元数量为 0，因此行为良好的 WebGL 1 程序不会在顶点着色器里采样纹理。
+transform feedback（入口为空操作）与 MSAA/采样缓冲（SDL_GPU 的 Metal 多采样 resolve 在 scissor 与实例化绘制下返回未定义像素，因此上下文保持单采样）。`blitFramebuffer` 只复制颜色附件，深度/模板位被接受但不复制。使用内建块或 `gl_FragDepth` 的着色器会以编译/链接日志报错。
 
 ## 平台
 
@@ -101,8 +101,14 @@ WebGL 2 额外提供：
 
 ## 测试
 
-- `tests/e2e/gui-webgl.test.ts` 编译 GLSL、绘制带纹理和深度测试的四边形、检查面剔除，并读回像素。
-- `tests/e2e/gui-webgl2.test.ts` 覆盖 WebGL 2 的新增能力：`#version 300 es` 着色器、VAO 往返、带 divisor 的实例化绘制、`texStorage2D`、`clearBufferfv`、缓冲拷贝、采样器对象与结构体 uniform 字段。
+- `tests/e2e/gui-webgl.test.ts` 编译 GLSL、绘制带纹理和深度测试的四边形、检查面剔除，并读回像素；它还覆盖混合常量色、动态缓冲 usage、顶点着色器纹理采样、`gl_FragDepth` 诊断、上下文丢失/恢复与立方体贴图。
+- `tests/e2e/gui-webgl2.test.ts` 覆盖 WebGL 2 的着色器/状态新增能力：`#version 300 es` 着色器、VAO 往返、带 divisor 的实例化绘制、`texStorage2D`、`clearBufferfv`、缓冲拷贝、采样器对象、结构体 uniform 字段与 `drawingBufferStorage`。
+- `tests/e2e/gui-webgl2-formats.test.ts` 覆盖模板、浮点/深度纹理、压缩纹理与 `ImageBitmap`。
+- `tests/e2e/gui-webgl2-blit.test.ts` 覆盖带 scissor 的颜色/深度清除、framebuffer blit，以及局部 blit 之外必须保留的像素（在 Metal 上，若目标 load-op 丢弃这些像素，该测试就会失败）。
+- `tests/e2e/gui-webgl2-3d.test.ts` 覆盖 2D 数组纹理与 3D 纹理的多层采样、`texSubImage3D` 子区域更新与 `framebufferTextureLayer` 渲染到数组层。
+- `tests/e2e/gui-webgl2-mrt.test.ts` 覆盖两个片元输出分别写入两个颜色附件。
+- `tests/e2e/gui-webgl2-ubo.test.ts` 覆盖 uniform 块的绑定、std140 成员与运行时更新。
+- `tests/e2e/gui-media.test.ts` 还会把 `<video>` 的最新解码帧上传为纹理并读回像素。
 - `examples/gui/webgl-cube` 是一个旋转、受光、带纹理的立方体；它在浏览器中原样运行，并由 `tests/e2e/gui-example-webgl.test.ts` 覆盖。
 - `examples/gui/webgl2-cubes` 用一次绘制调用画出 64 个实例化立方体，使用 `#version 300 es` 与 VAO；由 `tests/e2e/gui-example-webgl2.test.ts` 覆盖。
 
@@ -112,4 +118,4 @@ WebGL 2 额外提供：
 
 `.js` 资源加载器现在只修补 three.js 的着色器循环展开；`WebGLRenderer` 在本引擎真正的 WebGL 2 后端上原样运行，**不再打包 Canvas2D 回退**。已用 three.js r160 通过 SDL_GPU 验证：`MeshBasicMaterial`、`MeshStandardMaterial`、`MeshPhongMaterial`、`CanvasTexture`、线性雾、环境光/平行光/点光/聚光/半球光、`Sprite`、`Line`、`Points` 与 `InstancedMesh`。
 
-本引擎子集之外的能力仍无法模拟：阴影贴图（深度纹理）、立方体贴图/环境贴图、HDR/浮点渲染目标、多渲染目标、transform feedback 与压缩纹理。需要这些能力的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。
+本引擎子集之外的能力仍无法模拟：transform feedback 与 MSAA；立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标与压缩纹理已经可用。需要这些能力的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。

package/doc/zh-CN/gui.md

@@ -5,7 +5,7 @@
 状态：**M19** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
 `<video>`/`<audio>`——可选的 `media` 扩展用 vendored 的最小 FFmpeg 在主线程解码，
 视频帧走图像纹理路径、音频进入 SDL 流，DOM 媒体 API 暴露
-`play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
+`play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。浏览器全局还带有真正可用的 `AudioContext`：`runtime/ext_gui/audio_mixer.cpp` 中的 48 kHz 混音器，以及 `decodeAudioData`（WAV 由引擎内解码，压缩格式经 `media`）——见 [GUI API](./gui/api.md#web-audio)。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
 填充、路径、文本与 `drawImage`），并经图像纹理路径上传——参见
 [Canvas](./gui/canvas.md)。**M15** 增加了 CSS `transform` /
 `transform-origin`：每个布局盒一个合成好的 `Matrix2D`，由显示列表一路带到
@@ -142,7 +142,8 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
      只记录日志而不标注运行。
    - `package` job 在组装发布之前构建 `gui.a`/`gui.lib` 与 `media.a`/`media.lib`，
      因此两者都会随现有 runtime 归档一起发布（`package-release` 复制整个
-     `runtime/`）。Windows x64 已包含；Windows arm64 仍跳过。
+     `runtime/`），也会打进可选的 `@xbintsc/<os>-<arch>` npm 包。Windows x64
+     已包含；Windows arm64 仍跳过。
    - `vendor/`（GUI 归档的 SDL3/FreeType/HarfBuzz，以及 `media` 的 FFmpeg，
      缓慢的部分）按 OS/arch 缓存，以 `scripts/build-gui.ts` /
      `scripts/build-media.ts` 为键。Windows x64 有独立的源码 + FFmpeg 安装前缀

package/doc/zh-CN/npm-package.md

@@ -34,8 +34,8 @@ npx xbintsc build src/main.ts --out build
 4. 运行产物（`./build/<name>`，Windows 上是 `.exe`），并报告其路径。
 5. 如果构建报不支持的语法，阅读安装包里的子集指南
    `node_modules/xbintsc/doc/ai/language-support.md`；不要假设 Node 能跑的
-   TypeScript 就一定能编译。首次构建还会编译 C 运行时，请预留比增量构建更多的
-   时间。
+   TypeScript 就一定能编译。装有可选平台包时，首次构建直接链接预编译运行时；
+   没有平台包时才会从源码编译 C 运行时，那次构建会明显更慢。
 
 不要在 `node_modules/xbintsc` 里运行 `npm install`，也不要用 `tsc`/`esbuild`
 代替 xbintsc：原生产物必须由 `npx xbintsc` 生成。`xbintsc` 不读取
@@ -52,15 +52,18 @@ npx xbintsc build src/main.ts --out build
 它通过 Node.js 运行编译器。产出的二进制仍然是独立的：不嵌入 Node、V8 或
 TypeScript 编译器。
 
+安装它时还会安装宿主平台对应的可选包 `@xbintsc/<os>-<arch>`（例如
+`@xbintsc/linux-x64`）。该包在 `runtime/lib/<os>-<arch>/` 下携带预编译运行时归档：
+`core`、`ext_node`，以及发布时为该平台构建的 `gui` 与 `media`。驱动会就地链接这些
+归档，因此首次构建不再编译 C 运行时，也不需要用户再去发布页下载。
+
 这个包**不包含**：
 
-- C 编译器——构建机器需要 clang 16+；
-- 预编译的运行时归档（`runtime/lib/<os>-<arch>/core.a`）。驱动会在首次使用时
-  从随包发布的源码编译 C 运行时并缓存目标文件，所以第一次构建会更慢
-  （见[首次构建与缓存](#首次构建与缓存)）；
-- GUI/media 的原生归档（`gui.a`/`gui.lib`、`media.a`/`media.lib`）。如果你需要
-  `--ext gui` 或 `--ext media`，请使用 Linux/macOS/Windows x64 的发布压缩包，
-  或从源码检出中构建这些归档。
+- C 编译器——构建机器需要 clang 16+。
+
+如果 npm 跳过了这个可选包（`--omit=optional`、不安装可选依赖的包管理器，或发布
+未覆盖的宿主平台），驱动会回退到从随包源码编译 C 运行时并缓存目标文件；这样仍能
+工作，但首次构建更慢，`--ext gui` / `--ext media` 也需要归档存在。
 
 ## 环境要求
 
@@ -175,7 +178,7 @@ npm run build:native
 ./build/main          # Windows 上是 .\build\main.exe
 ```
 
-预期输出（首次构建还会编译 C 运行时）：
+预期输出：
 
 ```text
 xbintsc: wrote /absolute/path/my-app/build/main
@@ -187,14 +190,32 @@ Hello from xbintsc
 
 ## 首次构建与缓存
 
-运行时目标文件按源码/头文件内容哈希缓存。默认缓存目录是**执行命令时所在目录**下
-的 `.xbintsc/`（不一定是配置文件所在目录）；可以用 `xbintsc_CACHE_DIR` 改到别处。
+装有平台包时，首次构建直接链接预编译的
+`runtime/lib/<os>-<arch>/core.a`（Windows 上是 `.lib`），完全不编译 C，耗时与
+增量构建接近。
+
+如果可选包缺失——`npm install --omit=optional`、包管理器不安装可选依赖，或发布
+未覆盖当前宿主平台——驱动才会从随包源码编译 C 运行时。运行时目标文件按源码/
+头文件内容哈希缓存。默认缓存目录是**执行命令时所在目录**下的 `.xbintsc/`
+（不一定是配置文件所在目录）；可以用 `xbintsc_CACHE_DIR` 改到别处。这种回退构建
+会明显比后续构建慢。
+
+如果确实想忽略平台包归档、改从主包自带的源码编译 C 运行时（例如修改了
+`runtime/`，或预编译归档与当前环境不匹配），可以设置：
+
+```bash
+xbintsc_PREFER_PREBUILT=0 npx xbintsc build src/main.ts --out build
+```
+
+目标文件仍会缓存到 `.xbintsc/`；要完整重编，请把 `xbintsc_CACHE_DIR` 指向空目录
+（或删除 `.xbintsc/`）。只加 `--force` 不会绕过预编译归档。归档文件本身由源码
+检出中的 `npm run runtime` 生成；普通用户编译时不需要重新生成它们。
 
-npm 包只带运行时的 C 源码，不带预编译的 `core.a`，所以第一次构建会逐个编译
-运行时的翻译单元。这次构建会明显比后续构建慢。`--time` 可以看到时间花在哪里：
+`--time` 可以看到时间花在哪里：
 
 ```bash
 npx xbintsc build src/main.ts --out build --time
+# 未装平台包时的回退构建：
 # xbintsc: timing (frontend 4ms, codegen 7ms, clang 1089ms, runtime 37770ms, link 1966ms)
 ```
 
@@ -208,8 +229,8 @@ npx xbintsc build src/main.ts --out build
 实际使用中的建议：
 
 - 把 `.xbintsc/` 加进 `.gitignore`；
-- 在 CI 里保留 `.xbintsc/`（或把 `xbintsc_CACHE_DIR` 指向持久目录），避免每次
-  都重新编译运行时；
+- 在 CI 里保留 `.xbintsc/`（或把 `xbintsc_CACHE_DIR` 指向持久目录），避免回退
+  构建每次都重新编译运行时；
 - 删除 `.xbintsc/` 是安全的——下一次构建会重新生成；
 - `--force` 只忽略构建新鲜度记录，已缓存且内容哈希相同的运行时目标文件仍会复用。
   如果要强制完整重编 C 运行时，请删除 `.xbintsc/`。
@@ -350,15 +371,15 @@ jobs:
 | | npm 包（`xbintsc`） | 预编译发布压缩包 |
 | --- | --- | --- |
 | 需要 Node.js | 是，22+ | 否 |
-| 首次构建 | 从源码编译 C 运行时 | 直接链接预编译运行时 |
-| GUI / media 扩展 | 不包含 | Linux/macOS 与 Windows x64 压缩包包含 |
+| 首次构建 | 链接可选平台包里的预编译运行时 | 直接链接预编译运行时 |
+| GUI / media 扩展 | Linux/macOS 与 Windows x64（发布为这些平台构建）包含 | Linux/macOS 与 Windows x64 压缩包包含 |
 | 安装方式 | `npm install` + lockfile / provenance | 下载、校验 `.sha256`、解压 |
 | 编程 API | 有 | 无（仅 CLI） |
 | 交叉编译 | 否——只构建宿主平台 | 否——只构建宿主平台 |
-| 适合 | Node 项目与 CI，沿用熟悉的 npm 流程 | 没有 Node 的机器、首次构建要快、GUI 应用 |
+| 适合 | Node 项目与 CI，沿用熟悉的 npm 流程 | 没有 Node 的机器、GUI 应用、完全自包含的安装 |
 
-如果只需要核心运行时和 `node` 扩展，npm 包最方便。如果需要最快的冷启动构建，
-或者需要 GUI/media 归档，请使用发布压缩包（开发时也可以从源码构建）。
+npm 包通过可选平台包获得同一套预编译运行时，只有在跳过该包时才会付出从源码编译
+的冷启动成本。没有 Node 时请使用发布压缩包。
 
 ## 与普通 Node 构建的差异
 
@@ -383,10 +404,10 @@ jobs:
 | `npx xbintsc` 用了意料之外的版本 | 运行 `npx --no-install xbintsc version` 和 `npm ls xbintsc`；在 `package.json` 中固定版本，CI 用 `npm ci`。 |
 | `requires Node.js 22` / engine 错误 | 升级 Node；编译器使用了较新的 Node API。 |
 | `No C compiler found` 或 `requires clang 16 or newer` | 安装 clang 16+，运行 `npx xbintsc doctor`；需要时用 `xbintsc_CLANG` 指定 clang。 |
-| 第一次构建很慢 | 正常：正在编译并缓存运行时 C 源码。后续构建会复用 `.xbintsc/`；`--time` 可确认。如果冷启动必须快，请使用发布压缩包。 |
+| 第一次构建很慢 | 可选包 `@xbintsc/<os>-<arch>` 被跳过（或该宿主没有预编译包），正在编译并缓存运行时 C 源码。用 `npm ls @xbintsc/<os>-<arch>` 检查，并去掉 `--omit=optional` 重新安装；`--time` 可确认。 |
 | 写 `.xbintsc/` 权限错误 | 用 `xbintsc_CACHE_DIR` 指向可写目录，或在可写目录中运行。 |
 | `module 'fs' is provided by the 'node' extension` | 加 `--ext node`，或在配置里写 `"extensions": ["node"]`。 |
-| `GUI native library not found` / `media native library not found` | npm 包不包含 `gui.a`/`gui.lib` 或 `media.a`/`media.lib`；请使用 Linux/macOS/Windows x64 发布压缩包，或从源码检出构建。 |
+| `GUI native library not found` / `media native library not found` | 携带 `gui.a`/`gui.lib` 或 `media.a`/`media.lib` 的可选平台包被跳过，或该宿主没有预编译的 GUI/media 归档（Windows arm64）。去掉 `--omit=optional` 重新安装，或使用 Linux/macOS/Windows x64 发布压缩包，或从源码检出构建。 |
 | `require("xbintsc")` 失败 | 包只提供 ESM；使用 `import`（或动态 `import()`）。 |
 | Windows 链接时报缺少 MSVC 库 | 在 Native Tools 命令提示符中运行，安装 VS C++ 生成工具，并检查 `npx xbintsc doctor`。 |
 | `npm ci --omit=dev` 后构建找不到 `xbintsc` | 在构建阶段安装 devDependencies，或把 `xbintsc` 移到 `dependencies`。 |

package/doc/zh-CN/requirements.md

@@ -76,7 +76,10 @@ xbintsc-<os>-<arch>/
   runtime/               C 运行期 + 预编译 runtime/lib/<os>-<arch>/
 ```
 
-Windows 归档不含预编译 `runtime/lib/`；驱动会用用户的 clang 按需编译 C 运行期。
+每个归档都带有该宿主的预编译运行期，位于 `runtime/lib/<os>-<arch>/`：所有平台都有
+`core` 与 `ext_node`（Windows 的 MSVC ABI 下是 `.lib` 而不是 `.a`），发布为其构建
+时还包括 `gui`/`media`。npm 包通过可选的 `@xbintsc/<os>-<arch>` 依赖获得同一套归档，
+因此从 npm 安装也不需要编译 C 运行期。
 
 解压后把 `bin/` 加入 `PATH`（或直接调用 `bin/xbintsc`），再按下面的平台说明安装
 工具链。建议先校验下载内容：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.32",
+  "version": "0.5.36",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,12 @@
   "files": [
     "src",
     "dist",
+    "!dist/release",
+    "!dist/npm-platform",
+    "!dist/xbintsc",
+    "!dist/*.exe",
     "runtime",
+    "!runtime/lib",
     "scripts",
     "bin",
     "doc",
@@ -39,6 +44,9 @@
     "gui": "tsx scripts/build-gui.ts",
     "media": "tsx scripts/build-media.ts",
     "package-release": "tsx scripts/package-release.ts",
+    "package-platform": "tsx scripts/package-platform.ts",
+    "platform-versions": "tsx scripts/set-platform-version.ts",
+    "verify:platform": "tsx scripts/verify-platform-package.ts",
     "runtime:clean": "node -e \"require('fs').rmSync('build/runtime-obj',{recursive:true,force:true});require('fs').rmSync('runtime/lib',{recursive:true,force:true})\"",
     "xbintsc": "tsx src/cli/main.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -63,6 +71,14 @@
     "typescript-eslint": "^8.70.1",
     "vitest": "^2.1.8"
   },
+  "optionalDependencies": {
+    "@xbintsc/linux-x64": "0.5.36",
+    "@xbintsc/linux-arm64": "0.5.36",
+    "@xbintsc/darwin-x64": "0.5.36",
+    "@xbintsc/darwin-arm64": "0.5.36",
+    "@xbintsc/win32-x64": "0.5.36",
+    "@xbintsc/win32-arm64": "0.5.36"
+  },
   "engines": {
     "node": ">=22"
   }