Roc REPL WebAssembly 模块自包含、有状态、结构化协议的原生 REPL 集成指南【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本篇指南围绕 Roc 语言仓库中repl.wasm这一自包含的 WebAssembly REPL 模块展开它不依赖 playground 的编译器状态机也不暴露平台效应单个 WASM 实例即可独立承载一个完整的内存会话。读完本文你将掌握roc_repl_alloc/roc_repl_process等 Host ABI 的调用方式、eval/analyze/complete/inspect/get_state/clear/set_modules/capabilities八个操作的完整契约、编译期求值语义、UTF-8 字节偏移与补全规则以及如何在浏览器中通过 Web Worker 构建一个支持笔记本分格、补全、可终止、可恢复会话的 REPL 前端。模块定位与 playground 的边界划分repl.wasm是一个纯 REPLpure REPL。与仓库中的 playground WASM 不同它不暴露 playground 的编译器检查状态机也不暴露 echo platform见 README。这种刻意的最小化设计带来明确的语义一个 WebAssembly 实例 一个内存会话session会话状态完全封闭在线性内存中不依赖任何外部存储模块没有文件系统、网络、包解析器、stdin、历史存储和平台效应持久化与取消完全由 Host 负责协议中不含任何前端展示字符串——例如定义结果不会返回assigned foo这类文本而是返回结构化的kind、definition_kind、name、type、committed、revision等字段浏览器端只渲染结构化字段从不解析编译器展示文本。从源码结构看模块入口由 Zig 编写src/repl_wasm/main.zig顶层的std_options在 freestanding 的 wasm 构建下把日志静默掉quietLog保证 Host 只能通过 JSON 协议看到结果而不会混入 Zig 日志输出——这是“纯协议”边界在实现层的体现main.zig#L16-L23。Host ABI四个导出函数与内存约定模块对外只导出四个函数README导出函数签名职责roc_repl_alloc(len) - ptr在模块线性内存中分配请求字节返回指针分配失败返回 0roc_repl_free(ptr, len)释放roc_repl_alloc分配的请求缓冲roc_repl_process(ptr, len) - response_ptr处理一个 UTF-8 JSON 请求返回响应指针roc_repl_free_response(response_ptr)释放roc_repl_process返回的响应关键的内存与格式约定roc_repl_process接受 UTF-8 编码的 JSON返回值的起始处是一个四字节小端little-endian负载长度随后紧跟 UTF-8 JSON 响应体模块将线性内存导出为memoryHost 通过它读写请求、读取响应请求分配失败或处理失败时返回0Host 必须检查该值。这些约定在 main.zig 中均有直接实现storeResponse负责把响应长度以小端序写入前 4 字节再拷贝负载main.zig#L632-L641responseLength反向读取长度main.zig#L643-L649四个导出函数则位于 main.zig#L652-L680。参考实现Bytebox 集成测试如何调用 ABI仓库的集成测试 test/repl-wasm-test/main.zig 用 Bytebox 把四个导出函数封装成Interface完整演示了 Host 侧的标准调用序列先roc_repl_alloc分配请求缓冲把请求字节memcpy进线性内存再roc_repl_process处理随后roc_repl_free释放请求最后从响应指针读出前 4 字节长度并拷贝响应体再roc_repl_free_response释放响应main.zig#L23-L58。这份测试同时是协议契约的“活文档”它断言capabilities、eval等各操作的响应片段例如通过sendAndCheck检查响应包含预期字段、排除被拒绝字段main.zig#L67-L88。请求/响应信封protocol、id、op 与严格校验每个请求都是一个信封envelope包含protocol、id、op以及可选的params{protocol:1,id:1,op:eval,params:{source:x 41\nx 1}}响应规则每个响应都会回显protocol和id便于 Host 将异步结果与请求配对成功时包含ok: true与result失败时包含ok: false与稳定的结构化errorcodemessage未知请求字段会被拒绝——这样拼写错误的参数不会静默改变行为。这一“严格解析”在实现层由processJson完成JSON 解析失败返回invalid_json错误操作分派失败则映射为missing_source、missing_cursor、invalid_cursor、missing_modules、duplicate_module、reserved_module或兜底的internal_errormain.zig#L612-L630协议版本不匹配时返回unsupported_protocol错误main.zig#L586-L589。protocol.d.tssrc/repl_wasm/protocol.d.ts用 TypeScript 描述了版本 1 的完整请求与响应形状供 JavaScript/TypeScript 嵌入方直接引用ReplRequest用可辨识联合discriminated union精确约束每个op的params形状ReplResponse则区分ok: true与ok: false两种形态且id被声明为JsonValue可为任意 JSON 值。定义结果示例无展示字符串协议刻意不返回诸如assigned foo的展示文本定义结果只返回结构化字段。eval一个定义foo bar的典型响应{ source: foo \bar\, kind: definition, definition_kind: value, name: foo, status: ok, committed: true, revision: 1, type: Str, diagnostics: [], events: [] }字段语义kindexpression或definitiondefinition_kindvalue/annotation/type/import/file_importprotocol.d.ts#L2committed该片段是否改变了会话状态定义会提交表达式恒为falserevision提交后会话的新修订号type值的已检查类型如Strdiagnostics/events诊断与运行时事件均为独立字段。八个操作与范围契约版本 1 的完整操作集README操作契约capabilities报告协议操作、所有权边界与支持的功能特性eval解析器支撑的多行/批量输入从左到右求值在第一个失败的片段处停止此前成功的定义仍然保留committedanalyze不改变会话报告输入是完整complete、不完整incomplete还是无效invalidcomplete依据params.cursor处结束的标识符前缀过滤会话定义返回插入文本与显式替换范围inspect不求值返回一个表达式的已检查类型get_state返回有序的结构化定义、精确重放源replay source、虚拟模块源、挂起注解状态与修订号clear清除定义但保留虚拟模块set_modules原子替换具名内存模块并清除定义对应关系在实现层是一一映射的handleRequest将capabilities/eval/analyze/complete/inspect/get_state/set_modules/clear分发到capabilities、evaluate、analyze、complete、getState、setModules及内联的 clear 逻辑main.zig#L586-L610并在capabilities响应中把同样的操作清单与特性开关返回给 Hostmain.zig#L555-L584。capabilities特性自描述capabilities响应是 Host 侧特性探测的权威来源包含session_model: one_session_per_wasm_instanceprotocol_version、operations八个操作的数组text_encoding: utf8、offset_unit: utf8_bytesrevision_scope: wasm_instance、revision_bits: 32completion_scope: session_definitionsfeatures布尔/字符串开关如stateful_definitions、state_revision、parser_backed_multiline、batch_commit: left_to_right_until_failure、structured_diagnostics、diagnostic_scope: blocking_only、diagnostic_regions: optional、ordered_runtime_events、virtual_modules、cli_commands: false、presentation_strings: false、filesystem: false、network: false、platform_effects: false、host_managed_history、host_managed_cancellationmain.zig#L555-L584。这些开关让嵌入方无需猜测例如想确认模块是否支持平台效应直接读features.platform_effects即可而不是依赖文档外的假设。eval批量求值与左到右提交eval是核心操作。输入先经splitInputIntoStatements切成语句再逐条stepLanguageWithConfig求值main.zig#L264-L348。求值语义从左到右遇到第一个诊断片段时停止completed置为falsestop_reason为diagnostic运行时崩溃时stop_reason为crash每个片段报告committed表达式恒为committed: false批量结果报告completed、stop_reason、committed_count与最终会话revision当后续片段失败时此前成功的定义仍然保留——这是 Notebook 类前端最需要的行为一个坏 cell 不会回滚之前的好 cell。revision是限定在单个 WASM 实例内的无符号 32 位计数器session_revision见 main.zig#L14因此它们恰好是 JavaScript 的精确数值Host 不得跨实例比较修订号。计数耗尽时advanceRevision返回RevisionExhausted错误main.zig#L206-L210。analyze不改会话的三态预检analyze在不改变会话的前提下判断输入状态main.zig#L350-L390complete返回kind、definition_kind、name元数据如输入是一个定义incomplete输入不完整比如多行表达式还差一半适合前端据此提示“继续输入”或触发多行续行 UIinvalid解析错误附带parse_error诊断。inspect不求值的类型检查inspect返回表达式的已检查类型而不求值main.zig#L410-L450。细节输入必须是表达式传入定义会得到expected_expression诊断不完整输入返回incomplete_input解析错误返回parse_error类型错误返回type_error成功时status: ok并返回type字段。complete会话定义补全complete依据params.cursor结束处的标识符前缀过滤当前 REPL 会话中的定义返回插入文本与显式替换范围main.zig#L465-L500响应包含prefix、cursor、replacementRegion零基 UTF-8 字节起止偏移、items每个 item 有label、insert_text、kind、detail以及details_available补全范围被刻意限定为会话内定义名不宣称支持字段、标签、关键字或内建补全该范围由capabilities.completion_scope明确报告独立的注解是一个合法中间状态当details_available为false时名字仍然可补全——即只写了类型注解、尚未绑定实现时补全依然可用光标超出源码或落在多字节码点内部时返回invalid_cursor请求错误实现中通过utf8ValidateSlice校验光标前的字节是否为合法 UTF-8 边界见 main.zig#L470。get_state、clear、set_modules会话状态管理get_statemain.zig#L502-L532返回有序的definitionsname/source/kind、精确重放源definition_source可直接再次eval以还原会话、modules虚拟模块名与源、has_pending_annotation与revisionclearmain.zig#L597-L608清除定义但保留虚拟模块返回changed、removed_definition_count与revisionset_modulesmain.zig#L534-L553原子替换具名内存模块并清除定义返回module_count、module_names、cleared_definition_count与revision。模块名必须唯一重复返回duplicate_module且Repl是保留名、不可替换返回reserved_module。诊断与运行时事件结构化、不毒化会话表达式值、已检查类型、定义元数据、诊断与有序的dbg事件是相互独立的字段诊断具有稳定的code、severity版本 1 恒为error、人类可读的message与可空的region零基 UTF-8 字节偏移protocol.d.ts#L11-L23编译期expect失败或用户编写的crash是检查诊断不会毒化下一个请求——会话依然可用运行时事件是有序的RuntimeEvent{ kind: dbg | expect_failed | crashed; message: string }protocol.d.ts#L25。实现层copyEvents把会话中的dbg、expect_failed、crashed事件复制进响应main.zig#L168-L184版本 1 只枚举阻塞性blocking诊断非阻塞的编译器警告不在当前契约内——这一限制由capabilities响应的diagnostic_scope: blocking_only显式报告而不是隐式假定。编译期求值表达式是显式的编译期根REPL 表达式是显式的编译期求值根compile-time roots纯表达式产出已检查值inspected valuedbg观测变为有序的结构化事件对应events字段带效应的表达式会被拒绝并给出Effectful Compile Time Expression诊断——因为 WebAssembly 模块不暴露平台效应边界features.platform_effects: false。这意味着repl.wasm的求值模型是“编译期求值 结构化观测”与完整运行时/平台分离嵌入方因此获得可预测、可复现的求值语义。文本偏移与补全规则一律 UTF-8 字节源码字符串是 UTF-8所有协议偏移都是零基 UTF-8 字节偏移capabilities.offset_unit与每个补全响应都显式声明这一点响应中offset_unit: utf8_bytes光标超出源码或落在多字节码点内部 →invalid_cursor请求错误补全的替换范围replacement也是 UTF-8 字节区间Region。浏览器端的难点在于JS 字符串是 UTF-16 索引而协议要 UTF-8 字节偏移。演示实现提供了双向转换工具utf16ToUtf8Offset与utf8ToUtf16Offsetsrc/repl_wasm/www/cells.js#L67-L96并显式拒绝切分代理对surrogate pair的非法偏移completionDocumentRange再把 cell 局部的 UTF-8 替换范围换算回文档级的 UTF-16 范围供 textarea 的setRangeText使用cells.js#L99-L105。这些转换逻辑由 test/repl-wasm-test/cells.test.mjs 覆盖。前端边界CLI 命令、Worker、取消与状态重放前端边界划分非常明确ReplSession.stepLanguageWithConfig接受 Roc 语法并返回带类型的语言结果typed language result终端命令由 CLI 前端解析作为带类型命令传给executeCommandWithConfigWASM 协议不认识 CLI 命令features.cli_commands: false模块没有文件系统、网络、包解析器、stdin、历史存储或平台效应持久化与取消由 Host 负责。Web Worker 演示Notebook 单元格与状态重放演示src/repl_wasm/www/index.html、app.js、worker.js、cells.js展示了一个完整的最佳实践Worker 层worker.jsWebAssembly.instantiateStreaming加载repl.wasm用TextEncoder编码请求、roc_repl_alloc分配、写内存、roc_repl_process处理、roc_repl_free释放、按前 4 字节读长度解码响应、roc_repl_free_response释放——与 Bytebox 测试的调用序列完全一致worker.js#L19-L35。Notebook 分格cells.js整个可编辑笔记本源码保存在一个 textarea 中只含#%%的行作为单元格分隔符delimiterPattern /^[\t ]*#%%[\t ]*(?:\r?\n|$)/gm。findCells切分单元格分隔行归属于其后的单元格activeCell依据光标定位活动单元格advanceCell在最后一个单元格后追加新单元格。运行快捷键为Ctrl/Command-Enter求值活动单元格并前进到下一个app.js#L211-L248补全请求只携带活动单元格的源码并把浏览器 UTF-16 光标位置换算为协议 UTF-8 字节偏移utf16ToUtf8Offset接受的候选经completionDocumentRange换算回文档 UTF-16 范围后插入。快捷键还包括 Ctrl/Command-Space 强制补全、Tab 接受、Esc 关闭index.html 的 shortcuts 面板与 app.js#L329-L353。取消与重放Stop 按钮终止 Worker、创建新的模块实例并把get_state返回的精确结构化definition_source以及虚拟模块重放回新实例app.js#L355-L361、app.js#L160-L165——这是“Host 拥有持久化与取消”的最佳示范repl.wasm本身不可取消但通过“丢弃实例 精确重放”实现了可取消、可恢复的会话。语法高亮为何被刻意延后纯 textarea 能保持选区、输入法组合、可访问性与单元格边界行为的正确性而无需引入第二层同步的文本层README 的 Frontend boundary 一节。这一取舍避免了编辑器内核与协议之间的状态漂移。如何嵌入 repl.wasmHost 侧最小实现路径综合 README、main.zig、protocol.d.ts 与 worker.js一个最小 Host 集成的标准步骤是加载模块实例化repl.wasm浏览器用WebAssembly.instantiateStreamingNode/Zig 侧可用 Bytebox见 test/repl-wasm-test/main.zig取导出函数与memory发送请求roc_repl_alloc(len)分配 → 将TextEncoder编码的 JSON 请求写入memory→roc_repl_process(ptr, len)→roc_repl_free(ptr, len)读取响应读memory中响应指针处的前 4 字节小端长度再读对应长度的 UTF-8 JSON处理完roc_repl_free_response(ptr)解析响应先看okok: true时按result的具体形状见 protocol.d.ts 的ReplResult联合消费ok: false时按error.code处理如invalid_json、missing_source、invalid_cursor、unsupported_protocol等会话管理首次用capabilities探测能力eval推进会话、analyze/inspect做预检与类型查询、complete做补全需要持久化/取消时用get_state拿到definition_source在新建实例上重放set_moduleseval。构建方面repl.wasm由仓库的 build.zig 产出ci/tidy.zig也引用了它相关构建与集成测试均可参考test/repl-wasm-test目录。小结repl.wasm把“Roc REPL”压缩为一个无外部依赖、单实例单会话、全结构化协议的小体积模块Host 侧只需四个导出函数就能驱动解析、求值、类型检查、补全与状态重放而编译期求值模型与“无平台效应”的边界让嵌入方可以放心地把它放进 Worker、编辑器或任何需要沙箱化求值 Roc 代码的前端环境中。结合仓库内的 协议类型定义、Zig 实现、浏览器演示 与 集成测试你可以快速在自己的项目中复刻这套“结构化、可恢复、可嵌入”的 REPL 集成方案。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Roc REPL WebAssembly 模块：自包含、有状态、结构化协议的原生 REPL 集成指南
Roc REPL WebAssembly 模块自包含、有状态、结构化协议的原生 REPL 集成指南【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本篇指南围绕 Roc 语言仓库中repl.wasm这一自包含的 WebAssembly REPL 模块展开它不依赖 playground 的编译器状态机也不暴露平台效应单个 WASM 实例即可独立承载一个完整的内存会话。读完本文你将掌握roc_repl_alloc/roc_repl_process等 Host ABI 的调用方式、eval/analyze/complete/inspect/get_state/clear/set_modules/capabilities八个操作的完整契约、编译期求值语义、UTF-8 字节偏移与补全规则以及如何在浏览器中通过 Web Worker 构建一个支持笔记本分格、补全、可终止、可恢复会话的 REPL 前端。模块定位与 playground 的边界划分repl.wasm是一个纯 REPLpure REPL。与仓库中的 playground WASM 不同它不暴露 playground 的编译器检查状态机也不暴露 echo platform见 README。这种刻意的最小化设计带来明确的语义一个 WebAssembly 实例 一个内存会话session会话状态完全封闭在线性内存中不依赖任何外部存储模块没有文件系统、网络、包解析器、stdin、历史存储和平台效应持久化与取消完全由 Host 负责协议中不含任何前端展示字符串——例如定义结果不会返回assigned foo这类文本而是返回结构化的kind、definition_kind、name、type、committed、revision等字段浏览器端只渲染结构化字段从不解析编译器展示文本。从源码结构看模块入口由 Zig 编写src/repl_wasm/main.zig顶层的std_options在 freestanding 的 wasm 构建下把日志静默掉quietLog保证 Host 只能通过 JSON 协议看到结果而不会混入 Zig 日志输出——这是“纯协议”边界在实现层的体现main.zig#L16-L23。Host ABI四个导出函数与内存约定模块对外只导出四个函数README导出函数签名职责roc_repl_alloc(len) - ptr在模块线性内存中分配请求字节返回指针分配失败返回 0roc_repl_free(ptr, len)释放roc_repl_alloc分配的请求缓冲roc_repl_process(ptr, len) - response_ptr处理一个 UTF-8 JSON 请求返回响应指针roc_repl_free_response(response_ptr)释放roc_repl_process返回的响应关键的内存与格式约定roc_repl_process接受 UTF-8 编码的 JSON返回值的起始处是一个四字节小端little-endian负载长度随后紧跟 UTF-8 JSON 响应体模块将线性内存导出为memoryHost 通过它读写请求、读取响应请求分配失败或处理失败时返回0Host 必须检查该值。这些约定在 main.zig 中均有直接实现storeResponse负责把响应长度以小端序写入前 4 字节再拷贝负载main.zig#L632-L641responseLength反向读取长度main.zig#L643-L649四个导出函数则位于 main.zig#L652-L680。参考实现Bytebox 集成测试如何调用 ABI仓库的集成测试 test/repl-wasm-test/main.zig 用 Bytebox 把四个导出函数封装成Interface完整演示了 Host 侧的标准调用序列先roc_repl_alloc分配请求缓冲把请求字节memcpy进线性内存再roc_repl_process处理随后roc_repl_free释放请求最后从响应指针读出前 4 字节长度并拷贝响应体再roc_repl_free_response释放响应main.zig#L23-L58。这份测试同时是协议契约的“活文档”它断言capabilities、eval等各操作的响应片段例如通过sendAndCheck检查响应包含预期字段、排除被拒绝字段main.zig#L67-L88。请求/响应信封protocol、id、op 与严格校验每个请求都是一个信封envelope包含protocol、id、op以及可选的params{protocol:1,id:1,op:eval,params:{source:x 41\nx 1}}响应规则每个响应都会回显protocol和id便于 Host 将异步结果与请求配对成功时包含ok: true与result失败时包含ok: false与稳定的结构化errorcodemessage未知请求字段会被拒绝——这样拼写错误的参数不会静默改变行为。这一“严格解析”在实现层由processJson完成JSON 解析失败返回invalid_json错误操作分派失败则映射为missing_source、missing_cursor、invalid_cursor、missing_modules、duplicate_module、reserved_module或兜底的internal_errormain.zig#L612-L630协议版本不匹配时返回unsupported_protocol错误main.zig#L586-L589。protocol.d.tssrc/repl_wasm/protocol.d.ts用 TypeScript 描述了版本 1 的完整请求与响应形状供 JavaScript/TypeScript 嵌入方直接引用ReplRequest用可辨识联合discriminated union精确约束每个op的params形状ReplResponse则区分ok: true与ok: false两种形态且id被声明为JsonValue可为任意 JSON 值。定义结果示例无展示字符串协议刻意不返回诸如assigned foo的展示文本定义结果只返回结构化字段。eval一个定义foo bar的典型响应{ source: foo \bar\, kind: definition, definition_kind: value, name: foo, status: ok, committed: true, revision: 1, type: Str, diagnostics: [], events: [] }字段语义kindexpression或definitiondefinition_kindvalue/annotation/type/import/file_importprotocol.d.ts#L2committed该片段是否改变了会话状态定义会提交表达式恒为falserevision提交后会话的新修订号type值的已检查类型如Strdiagnostics/events诊断与运行时事件均为独立字段。八个操作与范围契约版本 1 的完整操作集README操作契约capabilities报告协议操作、所有权边界与支持的功能特性eval解析器支撑的多行/批量输入从左到右求值在第一个失败的片段处停止此前成功的定义仍然保留committedanalyze不改变会话报告输入是完整complete、不完整incomplete还是无效invalidcomplete依据params.cursor处结束的标识符前缀过滤会话定义返回插入文本与显式替换范围inspect不求值返回一个表达式的已检查类型get_state返回有序的结构化定义、精确重放源replay source、虚拟模块源、挂起注解状态与修订号clear清除定义但保留虚拟模块set_modules原子替换具名内存模块并清除定义对应关系在实现层是一一映射的handleRequest将capabilities/eval/analyze/complete/inspect/get_state/set_modules/clear分发到capabilities、evaluate、analyze、complete、getState、setModules及内联的 clear 逻辑main.zig#L586-L610并在capabilities响应中把同样的操作清单与特性开关返回给 Hostmain.zig#L555-L584。capabilities特性自描述capabilities响应是 Host 侧特性探测的权威来源包含session_model: one_session_per_wasm_instanceprotocol_version、operations八个操作的数组text_encoding: utf8、offset_unit: utf8_bytesrevision_scope: wasm_instance、revision_bits: 32completion_scope: session_definitionsfeatures布尔/字符串开关如stateful_definitions、state_revision、parser_backed_multiline、batch_commit: left_to_right_until_failure、structured_diagnostics、diagnostic_scope: blocking_only、diagnostic_regions: optional、ordered_runtime_events、virtual_modules、cli_commands: false、presentation_strings: false、filesystem: false、network: false、platform_effects: false、host_managed_history、host_managed_cancellationmain.zig#L555-L584。这些开关让嵌入方无需猜测例如想确认模块是否支持平台效应直接读features.platform_effects即可而不是依赖文档外的假设。eval批量求值与左到右提交eval是核心操作。输入先经splitInputIntoStatements切成语句再逐条stepLanguageWithConfig求值main.zig#L264-L348。求值语义从左到右遇到第一个诊断片段时停止completed置为falsestop_reason为diagnostic运行时崩溃时stop_reason为crash每个片段报告committed表达式恒为committed: false批量结果报告completed、stop_reason、committed_count与最终会话revision当后续片段失败时此前成功的定义仍然保留——这是 Notebook 类前端最需要的行为一个坏 cell 不会回滚之前的好 cell。revision是限定在单个 WASM 实例内的无符号 32 位计数器session_revision见 main.zig#L14因此它们恰好是 JavaScript 的精确数值Host 不得跨实例比较修订号。计数耗尽时advanceRevision返回RevisionExhausted错误main.zig#L206-L210。analyze不改会话的三态预检analyze在不改变会话的前提下判断输入状态main.zig#L350-L390complete返回kind、definition_kind、name元数据如输入是一个定义incomplete输入不完整比如多行表达式还差一半适合前端据此提示“继续输入”或触发多行续行 UIinvalid解析错误附带parse_error诊断。inspect不求值的类型检查inspect返回表达式的已检查类型而不求值main.zig#L410-L450。细节输入必须是表达式传入定义会得到expected_expression诊断不完整输入返回incomplete_input解析错误返回parse_error类型错误返回type_error成功时status: ok并返回type字段。complete会话定义补全complete依据params.cursor结束处的标识符前缀过滤当前 REPL 会话中的定义返回插入文本与显式替换范围main.zig#L465-L500响应包含prefix、cursor、replacementRegion零基 UTF-8 字节起止偏移、items每个 item 有label、insert_text、kind、detail以及details_available补全范围被刻意限定为会话内定义名不宣称支持字段、标签、关键字或内建补全该范围由capabilities.completion_scope明确报告独立的注解是一个合法中间状态当details_available为false时名字仍然可补全——即只写了类型注解、尚未绑定实现时补全依然可用光标超出源码或落在多字节码点内部时返回invalid_cursor请求错误实现中通过utf8ValidateSlice校验光标前的字节是否为合法 UTF-8 边界见 main.zig#L470。get_state、clear、set_modules会话状态管理get_statemain.zig#L502-L532返回有序的definitionsname/source/kind、精确重放源definition_source可直接再次eval以还原会话、modules虚拟模块名与源、has_pending_annotation与revisionclearmain.zig#L597-L608清除定义但保留虚拟模块返回changed、removed_definition_count与revisionset_modulesmain.zig#L534-L553原子替换具名内存模块并清除定义返回module_count、module_names、cleared_definition_count与revision。模块名必须唯一重复返回duplicate_module且Repl是保留名、不可替换返回reserved_module。诊断与运行时事件结构化、不毒化会话表达式值、已检查类型、定义元数据、诊断与有序的dbg事件是相互独立的字段诊断具有稳定的code、severity版本 1 恒为error、人类可读的message与可空的region零基 UTF-8 字节偏移protocol.d.ts#L11-L23编译期expect失败或用户编写的crash是检查诊断不会毒化下一个请求——会话依然可用运行时事件是有序的RuntimeEvent{ kind: dbg | expect_failed | crashed; message: string }protocol.d.ts#L25。实现层copyEvents把会话中的dbg、expect_failed、crashed事件复制进响应main.zig#L168-L184版本 1 只枚举阻塞性blocking诊断非阻塞的编译器警告不在当前契约内——这一限制由capabilities响应的diagnostic_scope: blocking_only显式报告而不是隐式假定。编译期求值表达式是显式的编译期根REPL 表达式是显式的编译期求值根compile-time roots纯表达式产出已检查值inspected valuedbg观测变为有序的结构化事件对应events字段带效应的表达式会被拒绝并给出Effectful Compile Time Expression诊断——因为 WebAssembly 模块不暴露平台效应边界features.platform_effects: false。这意味着repl.wasm的求值模型是“编译期求值 结构化观测”与完整运行时/平台分离嵌入方因此获得可预测、可复现的求值语义。文本偏移与补全规则一律 UTF-8 字节源码字符串是 UTF-8所有协议偏移都是零基 UTF-8 字节偏移capabilities.offset_unit与每个补全响应都显式声明这一点响应中offset_unit: utf8_bytes光标超出源码或落在多字节码点内部 →invalid_cursor请求错误补全的替换范围replacement也是 UTF-8 字节区间Region。浏览器端的难点在于JS 字符串是 UTF-16 索引而协议要 UTF-8 字节偏移。演示实现提供了双向转换工具utf16ToUtf8Offset与utf8ToUtf16Offsetsrc/repl_wasm/www/cells.js#L67-L96并显式拒绝切分代理对surrogate pair的非法偏移completionDocumentRange再把 cell 局部的 UTF-8 替换范围换算回文档级的 UTF-16 范围供 textarea 的setRangeText使用cells.js#L99-L105。这些转换逻辑由 test/repl-wasm-test/cells.test.mjs 覆盖。前端边界CLI 命令、Worker、取消与状态重放前端边界划分非常明确ReplSession.stepLanguageWithConfig接受 Roc 语法并返回带类型的语言结果typed language result终端命令由 CLI 前端解析作为带类型命令传给executeCommandWithConfigWASM 协议不认识 CLI 命令features.cli_commands: false模块没有文件系统、网络、包解析器、stdin、历史存储或平台效应持久化与取消由 Host 负责。Web Worker 演示Notebook 单元格与状态重放演示src/repl_wasm/www/index.html、app.js、worker.js、cells.js展示了一个完整的最佳实践Worker 层worker.jsWebAssembly.instantiateStreaming加载repl.wasm用TextEncoder编码请求、roc_repl_alloc分配、写内存、roc_repl_process处理、roc_repl_free释放、按前 4 字节读长度解码响应、roc_repl_free_response释放——与 Bytebox 测试的调用序列完全一致worker.js#L19-L35。Notebook 分格cells.js整个可编辑笔记本源码保存在一个 textarea 中只含#%%的行作为单元格分隔符delimiterPattern /^[\t ]*#%%[\t ]*(?:\r?\n|$)/gm。findCells切分单元格分隔行归属于其后的单元格activeCell依据光标定位活动单元格advanceCell在最后一个单元格后追加新单元格。运行快捷键为Ctrl/Command-Enter求值活动单元格并前进到下一个app.js#L211-L248补全请求只携带活动单元格的源码并把浏览器 UTF-16 光标位置换算为协议 UTF-8 字节偏移utf16ToUtf8Offset接受的候选经completionDocumentRange换算回文档 UTF-16 范围后插入。快捷键还包括 Ctrl/Command-Space 强制补全、Tab 接受、Esc 关闭index.html 的 shortcuts 面板与 app.js#L329-L353。取消与重放Stop 按钮终止 Worker、创建新的模块实例并把get_state返回的精确结构化definition_source以及虚拟模块重放回新实例app.js#L355-L361、app.js#L160-L165——这是“Host 拥有持久化与取消”的最佳示范repl.wasm本身不可取消但通过“丢弃实例 精确重放”实现了可取消、可恢复的会话。语法高亮为何被刻意延后纯 textarea 能保持选区、输入法组合、可访问性与单元格边界行为的正确性而无需引入第二层同步的文本层README 的 Frontend boundary 一节。这一取舍避免了编辑器内核与协议之间的状态漂移。如何嵌入 repl.wasmHost 侧最小实现路径综合 README、main.zig、protocol.d.ts 与 worker.js一个最小 Host 集成的标准步骤是加载模块实例化repl.wasm浏览器用WebAssembly.instantiateStreamingNode/Zig 侧可用 Bytebox见 test/repl-wasm-test/main.zig取导出函数与memory发送请求roc_repl_alloc(len)分配 → 将TextEncoder编码的 JSON 请求写入memory→roc_repl_process(ptr, len)→roc_repl_free(ptr, len)读取响应读memory中响应指针处的前 4 字节小端长度再读对应长度的 UTF-8 JSON处理完roc_repl_free_response(ptr)解析响应先看okok: true时按result的具体形状见 protocol.d.ts 的ReplResult联合消费ok: false时按error.code处理如invalid_json、missing_source、invalid_cursor、unsupported_protocol等会话管理首次用capabilities探测能力eval推进会话、analyze/inspect做预检与类型查询、complete做补全需要持久化/取消时用get_state拿到definition_source在新建实例上重放set_moduleseval。构建方面repl.wasm由仓库的 build.zig 产出ci/tidy.zig也引用了它相关构建与集成测试均可参考test/repl-wasm-test目录。小结repl.wasm把“Roc REPL”压缩为一个无外部依赖、单实例单会话、全结构化协议的小体积模块Host 侧只需四个导出函数就能驱动解析、求值、类型检查、补全与状态重放而编译期求值模型与“无平台效应”的边界让嵌入方可以放心地把它放进 Worker、编辑器或任何需要沙箱化求值 Roc 代码的前端环境中。结合仓库内的 协议类型定义、Zig 实现、浏览器演示 与 集成测试你可以快速在自己的项目中复刻这套“结构化、可恢复、可嵌入”的 REPL 集成方案。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考