网页编译之约 0.1.0

此包令浏览器中豫言之客于本机编译一组豫言源文件：源文件由客授之，编译于后台工作线程中由浏览器版豫言编译器（WasmGC 加 JSPI）为之，输出、诊断与阶段之进度，皆作事而入统一事列（见[网页事件之约](../网页事件/规范.文言.md)），终果以“完成”之事报之。用于云控制台之“本地编译”：源在云端，编于用户之浏览器，果与日志回传云端。客依此包，诸术皆当具。

此包惟定编译（源文件 → 编译通否、标准输出与标准错误、产物之摘要），不定运行编译之产物，亦不定编译器资源如何发布。

编译客户端

宿主凭一“编译客户端”模块行编译，默认自页面基址目录下之“编译/客户端.mjs”动态载之（如页 /cloud/ 载 /cloud/编译/客户端.mjs）；创宿主时可以选项“编译客户端”易为他模块之址或已载之物（测试之用）。模块须出二函数：

浏览器编译(输入, 仅编译, 报告)：输入为 {"files":{路径:内容}}；返 Promise，解为果之物 {ok, stdout, stderr, error, phase, artifact:{sha256}}；过程中以“报告(事)”回报 {type:"stage",phase,label}、{type:"output",stream,text}、{type:"diagnostic",text}。
停止编译()：终止当前编译（客户端使上述 Promise 以 {ok:false,error:"已停止"} 而终）。

语言仓之“宿主/浏览器/编译器/”乃此二函数之参考实现（主线程之计时、Worker、九十秒编译之限、五秒运行之限，皆由其负责）。

诸术

本地编译可用：有，返爻

浏览器兼有 WebAssembly.promising（JSPI）、Worker、DecompressionStream 则返阳，否则返阴。惟察浏览器之能，不验编译客户端与编译资源可载否；载败则于启动之后以“完成”事报之。可用以定界面上有无“本地编译”之选。

启动本地编译：字符串（文件癸象文），返整数

参数乃癸象对象，键为文件之径，值为文件之内容（字符串）：{"入口。豫":"…","库/甲。豫":"…"}。至多四千零九十六文件；径一至五百一十二 UTF-16 码元，无 NUL；内容总量至多三十二 MiB（UTF-8 字节）。返编译号（正整数，实例内递增，不复用），编译于后台行。同一时刻惟许一编译：已有编译在行则发事故；参数不合或逾限亦发事故。

停止本地编译：有，返爻

止在行之编译。确有编译在行则返阳，随后投一“完成”事（成为假，错误曰“已停止”）；无编译在行则返阴。

事

类曰“编译”，订阅号即编译号，同一编译之事保先后，末者恒为“完成”。

名“进度”

{"批":[{"类":"阶段","阶段":"load","标签":"正在加载浏览器编译器与标准库"},
       {"类":"输出","流":"stderr","文字":"正在编译：/库/标准库.豫\n"},
       {"类":"诊断","文字":"错误：…"}]}

宿主合五十毫秒内所至之进度为一批（一至六十四项，一批总量至多约一 MiB，更大之单项自成一批）。“类”曰“阶段”（惟带“阶段”与“标签”）、“输出”（惟带“流”与“文字”，“流”为 stdout 或 stderr）、“诊断”（惟带“文字”）；客户端未给之值为空文；客户端所报之他类，略之。编译器亦以标准错误书常规之编译进度，客不可因“流”为 stderr 即断其败，当观“完成”之“成”。进度之事不失：宿主于列中此编译之进度积压过多时，缓其合批之投，待客取后再续（编译线程自身不受影响，时限由客户端负责）。

名“完成”

{"成":true,"标准输出":"…","标准错误":"…","错误":"","阶段":"compile","产物摘要":"e3b0…"}

“成”乃编译通否；“标准输出”“标准错误”乃完整之输出（宿主不截断，客上报云端时自限其长）；“错误”乃败之释（如“已停止”“加载或编译超过九十秒时限”“编译客户端不可用：…”），成则空文；“阶段”乃败所发之阶段（load、compile、run），可空；“产物摘要”乃产物之 SHA-256 十六进制，无产物则空文。“完成”之前，此编译已收之进度必先投毕。

限额与败之类

| 项 | 限 | | --- | --- | | 同时行之编译 | 一 | | 文件数 | 四千零九十六 | | 径 | 五百一十二 UTF-16 码元 | | 内容总量 | 三十二 MiB（UTF-8） | | 一批进度 | 六十四项且约一 MiB |

违约之调用（文件癸象文不合、逾限、已有编译在行、宿主已闭）发豫言事故；编译败、超时、客户端载败，皆以“完成”事（成为假）报之，不发事故。浏览器不备所需之能，启动本地编译仍可调用，旋以“完成”（成为假，错误言所缺之能）而终。

一致性之例

于一简源文件启动本地编译：依次收若干“进度”事（含“阶段”项）与一“完成”，成为真，产物摘要为六十四位十六进制文。
源文件含语法之误：“完成”之成为假，标准错误或错误含诊断，“进度”中现“诊断”项或标准错误之输出。
编译中途停止本地编译：返阳；收“完成”，成为假，错误曰“已停止”；其后可再启动本地编译。
编译在行时再启动本地编译：发事故。
编译客户端模块不存：启动本地编译返编译号，随后“完成”之成为假，错误以“编译客户端不可用”首。
客户端报告一百条输出：客所收诸“进度”批中依序恰有一百条“输出”项。

界

此包不定：运行编译之产物、增量编译与缓存、编译器资源（编译器 Wasm、标准库资料、Binaryen）之发布与版本核对、多编译并行、“仅编译”以外之模式、写产物于文件。

豫言操作系统网页编译 0.1.0