@seanhogg/builderforce-webcontainers 2026.10.12 → 2026.10.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (372) hide show
  1. package/README.md +22 -0
  2. package/dist/adaptive/controller.d.ts +39 -0
  3. package/dist/adaptive/controller.d.ts.map +1 -0
  4. package/dist/adaptive/controller.js +108 -0
  5. package/dist/adaptive/controller.js.map +1 -0
  6. package/dist/adaptive/costModel.d.ts +37 -0
  7. package/dist/adaptive/costModel.d.ts.map +1 -0
  8. package/dist/adaptive/costModel.js +102 -0
  9. package/dist/adaptive/costModel.js.map +1 -0
  10. package/dist/adaptive/planner.d.ts +22 -0
  11. package/dist/adaptive/planner.d.ts.map +1 -0
  12. package/dist/adaptive/planner.js +114 -0
  13. package/dist/adaptive/planner.js.map +1 -0
  14. package/dist/adaptive/types.d.ts +138 -0
  15. package/dist/adaptive/types.d.ts.map +1 -0
  16. package/dist/adaptive/types.js +12 -0
  17. package/dist/adaptive/types.js.map +1 -0
  18. package/dist/assets.js +2 -2
  19. package/dist/check/cachedFetch.js.map +1 -1
  20. package/dist/check/index.d.ts +6 -1
  21. package/dist/check/index.d.ts.map +1 -1
  22. package/dist/check/index.js +6 -1
  23. package/dist/check/index.js.map +1 -1
  24. package/dist/componentCompilers.d.ts.map +1 -1
  25. package/dist/componentCompilers.js.map +1 -1
  26. package/dist/esbuildWasm.js.map +1 -1
  27. package/dist/host.d.ts +11 -5
  28. package/dist/host.d.ts.map +1 -1
  29. package/dist/host.js +19 -8
  30. package/dist/host.js.map +1 -1
  31. package/dist/inference/backends/mock.d.ts +24 -0
  32. package/dist/inference/backends/mock.d.ts.map +1 -0
  33. package/dist/inference/backends/mock.js +55 -0
  34. package/dist/inference/backends/mock.js.map +1 -0
  35. package/dist/inference/backends/onnx.d.ts +33 -0
  36. package/dist/inference/backends/onnx.d.ts.map +1 -0
  37. package/dist/inference/backends/onnx.js +60 -0
  38. package/dist/inference/backends/onnx.js.map +1 -0
  39. package/dist/inference/backends/webllm.d.ts +27 -0
  40. package/dist/inference/backends/webllm.d.ts.map +1 -0
  41. package/dist/inference/backends/webllm.js +52 -0
  42. package/dist/inference/backends/webllm.js.map +1 -0
  43. package/dist/inference/backends/wllama.d.ts +29 -0
  44. package/dist/inference/backends/wllama.d.ts.map +1 -0
  45. package/dist/inference/backends/wllama.js +51 -0
  46. package/dist/inference/backends/wllama.js.map +1 -0
  47. package/dist/inference/capabilities.d.ts +20 -0
  48. package/dist/inference/capabilities.d.ts.map +1 -0
  49. package/dist/inference/capabilities.js +33 -0
  50. package/dist/inference/capabilities.js.map +1 -0
  51. package/dist/inference/client.d.ts +45 -0
  52. package/dist/inference/client.d.ts.map +1 -0
  53. package/dist/inference/client.js +201 -0
  54. package/dist/inference/client.js.map +1 -0
  55. package/dist/inference/modelCache.d.ts +71 -0
  56. package/dist/inference/modelCache.d.ts.map +1 -0
  57. package/dist/inference/modelCache.js +91 -0
  58. package/dist/inference/modelCache.js.map +1 -0
  59. package/dist/inference/protocol.d.ts +94 -0
  60. package/dist/inference/protocol.d.ts.map +1 -0
  61. package/dist/inference/protocol.js +19 -0
  62. package/dist/inference/protocol.js.map +1 -0
  63. package/dist/inference/tokenStream.d.ts +26 -0
  64. package/dist/inference/tokenStream.d.ts.map +1 -0
  65. package/dist/inference/tokenStream.js +79 -0
  66. package/dist/inference/tokenStream.js.map +1 -0
  67. package/dist/inference/types.d.ts +108 -0
  68. package/dist/inference/types.d.ts.map +1 -0
  69. package/dist/inference/types.js +8 -0
  70. package/dist/inference/types.js.map +1 -0
  71. package/dist/inference/worker.bundle.js +5 -0
  72. package/dist/inference/worker.d.ts +35 -0
  73. package/dist/inference/worker.d.ts.map +1 -0
  74. package/dist/inference/worker.js +157 -0
  75. package/dist/inference/worker.js.map +1 -0
  76. package/dist/inference/workerEntry.d.ts +15 -0
  77. package/dist/inference/workerEntry.d.ts.map +1 -0
  78. package/dist/inference/workerEntry.js +17 -0
  79. package/dist/inference/workerEntry.js.map +1 -0
  80. package/dist/kvcache/advanced.d.ts +39 -0
  81. package/dist/kvcache/advanced.d.ts.map +1 -0
  82. package/dist/kvcache/advanced.js +59 -0
  83. package/dist/kvcache/advanced.js.map +1 -0
  84. package/dist/kvcache/compatibility.d.ts +14 -0
  85. package/dist/kvcache/compatibility.d.ts.map +1 -0
  86. package/dist/kvcache/compatibility.js +44 -0
  87. package/dist/kvcache/compatibility.js.map +1 -0
  88. package/dist/kvcache/lru.d.ts +45 -0
  89. package/dist/kvcache/lru.d.ts.map +1 -0
  90. package/dist/kvcache/lru.js +91 -0
  91. package/dist/kvcache/lru.js.map +1 -0
  92. package/dist/kvcache/paged.d.ts +86 -0
  93. package/dist/kvcache/paged.d.ts.map +1 -0
  94. package/dist/kvcache/paged.js +238 -0
  95. package/dist/kvcache/paged.js.map +1 -0
  96. package/dist/kvcache/quant.d.ts +30 -0
  97. package/dist/kvcache/quant.d.ts.map +1 -0
  98. package/dist/kvcache/quant.js +73 -0
  99. package/dist/kvcache/quant.js.map +1 -0
  100. package/dist/kvcache/radix.d.ts +28 -0
  101. package/dist/kvcache/radix.d.ts.map +1 -0
  102. package/dist/kvcache/radix.js +58 -0
  103. package/dist/kvcache/radix.js.map +1 -0
  104. package/dist/kvcache/runtime.d.ts +11 -0
  105. package/dist/kvcache/runtime.d.ts.map +1 -0
  106. package/dist/kvcache/runtime.js +204 -0
  107. package/dist/kvcache/runtime.js.map +1 -0
  108. package/dist/kvcache/types.d.ts +151 -0
  109. package/dist/kvcache/types.d.ts.map +1 -0
  110. package/dist/kvcache/types.js +10 -0
  111. package/dist/kvcache/types.js.map +1 -0
  112. package/dist/learning/fingerprint.d.ts +17 -0
  113. package/dist/learning/fingerprint.d.ts.map +1 -0
  114. package/dist/learning/fingerprint.js +46 -0
  115. package/dist/learning/fingerprint.js.map +1 -0
  116. package/dist/learning/index.d.ts +5 -0
  117. package/dist/learning/index.d.ts.map +1 -0
  118. package/dist/learning/index.js +3 -0
  119. package/dist/learning/index.js.map +1 -0
  120. package/dist/learning/learner.d.ts +21 -0
  121. package/dist/learning/learner.d.ts.map +1 -0
  122. package/dist/learning/learner.js +272 -0
  123. package/dist/learning/learner.js.map +1 -0
  124. package/dist/learning/ledger.d.ts +26 -0
  125. package/dist/learning/ledger.d.ts.map +1 -0
  126. package/dist/learning/ledger.js +40 -0
  127. package/dist/learning/ledger.js.map +1 -0
  128. package/dist/learning/selection.d.ts +44 -0
  129. package/dist/learning/selection.d.ts.map +1 -0
  130. package/dist/learning/selection.js +111 -0
  131. package/dist/learning/selection.js.map +1 -0
  132. package/dist/learning/stats.d.ts +19 -0
  133. package/dist/learning/stats.d.ts.map +1 -0
  134. package/dist/learning/stats.js +31 -0
  135. package/dist/learning/stats.js.map +1 -0
  136. package/dist/learning/types.d.ts +133 -0
  137. package/dist/learning/types.d.ts.map +1 -0
  138. package/dist/learning/types.js +8 -0
  139. package/dist/learning/types.js.map +1 -0
  140. package/dist/memory/envProbe.d.ts +16 -0
  141. package/dist/memory/envProbe.d.ts.map +1 -0
  142. package/dist/memory/envProbe.js +28 -0
  143. package/dist/memory/envProbe.js.map +1 -0
  144. package/dist/memory/estimates.d.ts +46 -0
  145. package/dist/memory/estimates.d.ts.map +1 -0
  146. package/dist/memory/estimates.js +72 -0
  147. package/dist/memory/estimates.js.map +1 -0
  148. package/dist/memory/eviction.d.ts +42 -0
  149. package/dist/memory/eviction.d.ts.map +1 -0
  150. package/dist/memory/eviction.js +143 -0
  151. package/dist/memory/eviction.js.map +1 -0
  152. package/dist/memory/manager.d.ts +34 -0
  153. package/dist/memory/manager.d.ts.map +1 -0
  154. package/dist/memory/manager.js +346 -0
  155. package/dist/memory/manager.js.map +1 -0
  156. package/dist/memory/managerTypes.d.ts +49 -0
  157. package/dist/memory/managerTypes.d.ts.map +1 -0
  158. package/dist/memory/managerTypes.js +7 -0
  159. package/dist/memory/managerTypes.js.map +1 -0
  160. package/dist/memory/pressure.d.ts +56 -0
  161. package/dist/memory/pressure.d.ts.map +1 -0
  162. package/dist/memory/pressure.js +80 -0
  163. package/dist/memory/pressure.js.map +1 -0
  164. package/dist/memory/spillTier.d.ts +47 -0
  165. package/dist/memory/spillTier.d.ts.map +1 -0
  166. package/dist/memory/spillTier.js +128 -0
  167. package/dist/memory/spillTier.js.map +1 -0
  168. package/dist/memory/storageSink.d.ts +69 -0
  169. package/dist/memory/storageSink.d.ts.map +1 -0
  170. package/dist/memory/storageSink.js +221 -0
  171. package/dist/memory/storageSink.js.map +1 -0
  172. package/dist/memory/types.d.ts +202 -0
  173. package/dist/memory/types.d.ts.map +1 -0
  174. package/dist/memory/types.js +15 -0
  175. package/dist/memory/types.js.map +1 -0
  176. package/dist/memory/victims.d.ts +32 -0
  177. package/dist/memory/victims.d.ts.map +1 -0
  178. package/dist/memory/victims.js +74 -0
  179. package/dist/memory/victims.js.map +1 -0
  180. package/dist/memory/workspace.d.ts +34 -0
  181. package/dist/memory/workspace.d.ts.map +1 -0
  182. package/dist/memory/workspace.js +55 -0
  183. package/dist/memory/workspace.js.map +1 -0
  184. package/dist/memoryIntegration/index.d.ts +8 -0
  185. package/dist/memoryIntegration/index.d.ts.map +1 -0
  186. package/dist/memoryIntegration/index.js +4 -0
  187. package/dist/memoryIntegration/index.js.map +1 -0
  188. package/dist/memoryIntegration/knowledgeMemory.d.ts +43 -0
  189. package/dist/memoryIntegration/knowledgeMemory.d.ts.map +1 -0
  190. package/dist/memoryIntegration/knowledgeMemory.js +285 -0
  191. package/dist/memoryIntegration/knowledgeMemory.js.map +1 -0
  192. package/dist/memoryIntegration/persistence.d.ts +15 -0
  193. package/dist/memoryIntegration/persistence.d.ts.map +1 -0
  194. package/dist/memoryIntegration/persistence.js +43 -0
  195. package/dist/memoryIntegration/persistence.js.map +1 -0
  196. package/dist/memoryIntegration/text.d.ts +57 -0
  197. package/dist/memoryIntegration/text.d.ts.map +1 -0
  198. package/dist/memoryIntegration/text.js +179 -0
  199. package/dist/memoryIntegration/text.js.map +1 -0
  200. package/dist/memoryIntegration/types.d.ts +131 -0
  201. package/dist/memoryIntegration/types.d.ts.map +1 -0
  202. package/dist/memoryIntegration/types.js +11 -0
  203. package/dist/memoryIntegration/types.js.map +1 -0
  204. package/dist/ml.d.ts +52 -0
  205. package/dist/ml.d.ts.map +1 -0
  206. package/dist/ml.js +33 -0
  207. package/dist/ml.js.map +1 -0
  208. package/dist/node/childRelay.d.ts +10 -0
  209. package/dist/node/childRelay.d.ts.map +1 -1
  210. package/dist/node/childRelay.js +12 -2
  211. package/dist/node/childRelay.js.map +1 -1
  212. package/dist/node/index.js.map +1 -1
  213. package/dist/node/portResponder.d.ts +2 -0
  214. package/dist/node/portResponder.d.ts.map +1 -1
  215. package/dist/node/portResponder.js +3 -3
  216. package/dist/node/portResponder.js.map +1 -1
  217. package/dist/node/processHost.d.ts +4 -1
  218. package/dist/node/processHost.d.ts.map +1 -1
  219. package/dist/node/processHost.js +19 -16
  220. package/dist/node/processHost.js.map +1 -1
  221. package/dist/node/protocol.d.ts +1 -0
  222. package/dist/node/protocol.d.ts.map +1 -1
  223. package/dist/node/responseWire.d.ts.map +1 -1
  224. package/dist/node/worker.js +127 -120
  225. package/dist/node/workerProcess.js +1 -1
  226. package/dist/node/workerProcess.js.map +1 -1
  227. package/dist/prefetch/admission.d.ts +41 -0
  228. package/dist/prefetch/admission.d.ts.map +1 -0
  229. package/dist/prefetch/admission.js +49 -0
  230. package/dist/prefetch/admission.js.map +1 -0
  231. package/dist/prefetch/loadRegistry.d.ts +56 -0
  232. package/dist/prefetch/loadRegistry.d.ts.map +1 -0
  233. package/dist/prefetch/loadRegistry.js +108 -0
  234. package/dist/prefetch/loadRegistry.js.map +1 -0
  235. package/dist/prefetch/predictor.d.ts +40 -0
  236. package/dist/prefetch/predictor.d.ts.map +1 -0
  237. package/dist/prefetch/predictor.js +178 -0
  238. package/dist/prefetch/predictor.js.map +1 -0
  239. package/dist/prefetch/prefetcher.d.ts +37 -0
  240. package/dist/prefetch/prefetcher.d.ts.map +1 -0
  241. package/dist/prefetch/prefetcher.js +339 -0
  242. package/dist/prefetch/prefetcher.js.map +1 -0
  243. package/dist/prefetch/residentStore.d.ts +49 -0
  244. package/dist/prefetch/residentStore.d.ts.map +1 -0
  245. package/dist/prefetch/residentStore.js +87 -0
  246. package/dist/prefetch/residentStore.js.map +1 -0
  247. package/dist/prefetch/selfTuner.d.ts +40 -0
  248. package/dist/prefetch/selfTuner.d.ts.map +1 -0
  249. package/dist/prefetch/selfTuner.js +78 -0
  250. package/dist/prefetch/selfTuner.js.map +1 -0
  251. package/dist/prefetch/stats.d.ts +52 -0
  252. package/dist/prefetch/stats.d.ts.map +1 -0
  253. package/dist/prefetch/stats.js +72 -0
  254. package/dist/prefetch/stats.js.map +1 -0
  255. package/dist/prefetch/streaming.d.ts +132 -0
  256. package/dist/prefetch/streaming.d.ts.map +1 -0
  257. package/dist/prefetch/streaming.js +141 -0
  258. package/dist/prefetch/streaming.js.map +1 -0
  259. package/dist/prefetch/targetIndex.d.ts +18 -0
  260. package/dist/prefetch/targetIndex.d.ts.map +1 -0
  261. package/dist/prefetch/targetIndex.js +32 -0
  262. package/dist/prefetch/targetIndex.js.map +1 -0
  263. package/dist/prefetch/types.d.ts +283 -0
  264. package/dist/prefetch/types.d.ts.map +1 -0
  265. package/dist/prefetch/types.js +19 -0
  266. package/dist/prefetch/types.js.map +1 -0
  267. package/dist/previewBridge.d.ts +6 -0
  268. package/dist/previewBridge.d.ts.map +1 -1
  269. package/dist/previewBridge.js +25 -5
  270. package/dist/previewBridge.js.map +1 -1
  271. package/dist/previewMessages.d.ts +4 -3
  272. package/dist/previewMessages.d.ts.map +1 -1
  273. package/dist/previewMessages.js +12 -6
  274. package/dist/previewMessages.js.map +1 -1
  275. package/dist/process-worker.js +127 -120
  276. package/dist/relay.html +1 -1
  277. package/dist/shared/clock.d.ts +7 -0
  278. package/dist/shared/clock.d.ts.map +1 -0
  279. package/dist/shared/clock.js +10 -0
  280. package/dist/shared/clock.js.map +1 -0
  281. package/dist/shared/hardwareProbe.d.ts +26 -0
  282. package/dist/shared/hardwareProbe.d.ts.map +1 -0
  283. package/dist/shared/hardwareProbe.js +62 -0
  284. package/dist/shared/hardwareProbe.js.map +1 -0
  285. package/dist/shared/idb.d.ts +41 -0
  286. package/dist/shared/idb.d.ts.map +1 -0
  287. package/dist/shared/idb.js +184 -0
  288. package/dist/shared/idb.js.map +1 -0
  289. package/dist/shared/tokens.d.ts +7 -0
  290. package/dist/shared/tokens.d.ts.map +1 -0
  291. package/dist/shared/tokens.js +9 -0
  292. package/dist/shared/tokens.js.map +1 -0
  293. package/dist/snapshotStore.d.ts +2 -1
  294. package/dist/snapshotStore.d.ts.map +1 -1
  295. package/dist/snapshotStore.js +27 -12
  296. package/dist/snapshotStore.js.map +1 -1
  297. package/dist/styleCompilers.d.ts.map +1 -1
  298. package/dist/styleCompilers.js.map +1 -1
  299. package/dist/transport.js.map +1 -1
  300. package/package.json +11 -5
  301. package/src/adaptive/controller.ts +151 -0
  302. package/src/adaptive/costModel.ts +131 -0
  303. package/src/adaptive/planner.ts +127 -0
  304. package/src/adaptive/types.ts +137 -0
  305. package/src/check/index.ts +6 -1
  306. package/src/host.ts +33 -11
  307. package/src/inference/backends/mock.ts +77 -0
  308. package/src/inference/backends/onnx.ts +91 -0
  309. package/src/inference/backends/webllm.ts +79 -0
  310. package/src/inference/backends/wllama.ts +79 -0
  311. package/src/inference/capabilities.ts +46 -0
  312. package/src/inference/client.ts +276 -0
  313. package/src/inference/modelCache.ts +145 -0
  314. package/src/inference/protocol.ts +119 -0
  315. package/src/inference/tokenStream.ts +92 -0
  316. package/src/inference/types.ts +115 -0
  317. package/src/inference/worker.ts +191 -0
  318. package/src/inference/workerEntry.ts +18 -0
  319. package/src/kvcache/advanced.ts +86 -0
  320. package/src/kvcache/compatibility.ts +51 -0
  321. package/src/kvcache/lru.ts +100 -0
  322. package/src/kvcache/paged.ts +270 -0
  323. package/src/kvcache/quant.ts +88 -0
  324. package/src/kvcache/radix.ts +68 -0
  325. package/src/kvcache/runtime.ts +239 -0
  326. package/src/kvcache/types.ts +167 -0
  327. package/src/learning/fingerprint.ts +50 -0
  328. package/src/learning/index.ts +15 -0
  329. package/src/learning/learner.ts +304 -0
  330. package/src/learning/ledger.ts +54 -0
  331. package/src/learning/selection.ts +137 -0
  332. package/src/learning/stats.ts +39 -0
  333. package/src/learning/types.ts +142 -0
  334. package/src/memory/envProbe.ts +30 -0
  335. package/src/memory/estimates.ts +98 -0
  336. package/src/memory/eviction.ts +145 -0
  337. package/src/memory/manager.ts +380 -0
  338. package/src/memory/managerTypes.ts +61 -0
  339. package/src/memory/pressure.ts +120 -0
  340. package/src/memory/spillTier.ts +159 -0
  341. package/src/memory/storageSink.ts +289 -0
  342. package/src/memory/types.ts +217 -0
  343. package/src/memory/victims.ts +80 -0
  344. package/src/memory/workspace.ts +74 -0
  345. package/src/memoryIntegration/index.ts +7 -0
  346. package/src/memoryIntegration/knowledgeMemory.ts +339 -0
  347. package/src/memoryIntegration/persistence.ts +54 -0
  348. package/src/memoryIntegration/text.ts +185 -0
  349. package/src/memoryIntegration/types.ts +145 -0
  350. package/src/ml.ts +180 -0
  351. package/src/node/childRelay.ts +16 -3
  352. package/src/node/portResponder.ts +5 -3
  353. package/src/node/processHost.ts +16 -15
  354. package/src/node/protocol.ts +1 -1
  355. package/src/node/workerProcess.ts +1 -1
  356. package/src/prefetch/admission.ts +74 -0
  357. package/src/prefetch/loadRegistry.ts +156 -0
  358. package/src/prefetch/predictor.ts +199 -0
  359. package/src/prefetch/prefetcher.ts +369 -0
  360. package/src/prefetch/residentStore.ts +121 -0
  361. package/src/prefetch/selfTuner.ts +110 -0
  362. package/src/prefetch/stats.ts +120 -0
  363. package/src/prefetch/streaming.ts +231 -0
  364. package/src/prefetch/targetIndex.ts +40 -0
  365. package/src/prefetch/types.ts +307 -0
  366. package/src/previewBridge.ts +25 -5
  367. package/src/previewMessages.ts +11 -6
  368. package/src/shared/clock.ts +9 -0
  369. package/src/shared/hardwareProbe.ts +68 -0
  370. package/src/shared/idb.ts +203 -0
  371. package/src/shared/tokens.ts +8 -0
  372. package/src/snapshotStore.ts +25 -10
package/src/host.ts CHANGED
@@ -2,7 +2,10 @@ import {
2
2
  DevServer,
3
3
  PortCookieJars,
4
4
  VirtualFileSystem,
5
+ baseToProject,
5
6
  buildProject,
7
+ projectToBase,
8
+ runArguments,
6
9
  rootedFileSystem,
7
10
  exportZip,
8
11
  importZip,
@@ -20,6 +23,7 @@ import {
20
23
  type StyleCompilers,
21
24
  type Transformer,
22
25
  type ZipExportOptions,
26
+ type ZipImportLimits,
23
27
  } from '@seanhogg/builderforce-webcontainers-core';
24
28
  import { PREVIEW_ID, isPortPath, isWireCancel, isWireRequest, previewBase, type WireReply, type WireResponse } from './protocol.js';
25
29
  import { createPortResponder, createProcessHost, type NodeRuntimeOptions, type ProcessInfo } from './node/index.js';
@@ -111,8 +115,8 @@ export interface PreviewRuntime {
111
115
  writeTree(files: FileTree, at?: string): void;
112
116
  /** The project as a zip — "Download project" with `exclude: ['node_modules']`, or a full snapshot to restore later. */
113
117
  exportZip(options?: ZipExportOptions): Uint8Array;
114
- /** Write a zip's contents (an `exportZip` snapshot, a downloaded template) into the runtime, under `at`. */
115
- importZip(zip: Uint8Array, at?: string): void;
118
+ /** Write a zip's contents (an `exportZip` snapshot, a downloaded template) into the runtime, under `at`. Throws `ZipLimitError` past `limits`. */
119
+ importZip(zip: Uint8Array, at?: string, limits?: ZipImportLimits): void;
116
120
  /** Reload every frame showing this preview now (live reload does this on edits by itself). */
117
121
  reload(): void;
118
122
  /** Whether this runtime can serve the mounted project, and why not. */
@@ -132,7 +136,9 @@ export interface PreviewRuntime {
132
136
  /**
133
137
  * Run a command — `node server.js`, `npm install`, `npm run dev`, `bfsh` for a
134
138
  * terminal — in its own Web Worker. Pass `{ terminal: { cols, rows } }` when
135
- * wiring it to xterm.js.
139
+ * wiring it to xterm.js. `cwd` is project-relative like every other path here
140
+ * (`/` is the project, `/packages/web` a folder in it; `..` cannot leave it);
141
+ * the default is the project itself.
136
142
  */
137
143
  run(command: string, args?: string[], options?: ProcessOptions): RuntimeProcess;
138
144
  run(command: string, options?: ProcessOptions): RuntimeProcess;
@@ -140,7 +146,11 @@ export interface PreviewRuntime {
140
146
  onServerListening(listener: (server: ServerAddress) => void): () => void;
141
147
  /** A virtual server opened or closed its port. */
142
148
  onPortChange(listener: (change: PortChange) => void): () => void;
143
- /** Processes still running, with the ports their servers listen on. */
149
+ /**
150
+ * Processes still running, with the ports their servers listen on. `cwd` is
151
+ * project-relative; a process that changed directory out of the project (a
152
+ * shell's `cd /tmp`) reports the absolute path it sees.
153
+ */
144
154
  listProcesses(): ProcessInfo[];
145
155
  /**
146
156
  * Cookies virtual servers set, per port. A service worker cannot set cookies,
@@ -157,6 +167,13 @@ function randomId(): string {
157
167
  return globalThis.crypto?.randomUUID?.().replace(/-/g, '').slice(0, 16) ?? Math.random().toString(36).slice(2, 18);
158
168
  }
159
169
 
170
+ /** 128 random bits, hex: the runtime's preview nonce. */
171
+ function randomNonce(): string {
172
+ const bytes = new Uint8Array(16);
173
+ globalThis.crypto.getRandomValues(bytes);
174
+ return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
175
+ }
176
+
160
177
  export function toWire(reqId: number, served: Awaited<ReturnType<DevServer['handle']>>): { message: WireResponse; transfer: Transferable[] } {
161
178
  if (typeof served.body === 'string') {
162
179
  return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body: served.body }, transfer: [] };
@@ -182,6 +199,8 @@ export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promi
182
199
  : await sameOriginTransport((options as SameOriginOptions).serviceWorkerUrl, options.scope);
183
200
 
184
201
  const base = previewBase(transport.scope, id);
202
+ // Every bridge this runtime injects carries it; preview messages without it are refused.
203
+ const nonce = randomNonce();
185
204
  const root = normalizePath(options.root ?? DEFAULT_ROOT);
186
205
  // Processes see the whole tree; everything else sees the project as `/`.
187
206
  const files = new VirtualFileSystem();
@@ -193,7 +212,7 @@ export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promi
193
212
  let server: DevServer;
194
213
  try {
195
214
  const transformer = options.transformer ?? (await createEsbuildWasmTransformer());
196
- server = new DevServer({ fs, transformer, base, cdn: options.cdn, components, styles, attribution: options.attribution, previewScripts, hot: options.hot });
215
+ server = new DevServer({ fs, transformer, base, cdn: options.cdn, components, styles, attribution: options.attribution, previewScripts, previewNonce: nonce, hot: options.hot });
197
216
  } catch (error) {
198
217
  transport.dispose();
199
218
  throw error;
@@ -212,7 +231,7 @@ export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promi
212
231
  const reply = (message: WireReply, transfer: Transferable[]) => channel.port1.postMessage(message, transfer);
213
232
  // Virtual servers' responses stream (one responder per channel: request ids are per worker).
214
233
  responder?.dispose();
215
- const ports = (responder = createPortResponder(processes, { cookies, scripts: () => previewScripts }));
234
+ const ports = (responder = createPortResponder(processes, { cookies, scripts: () => previewScripts, nonce }));
216
235
  channel.port1.onmessage = async (event) => {
217
236
  if (isWireCancel(event.data)) return ports.cancel(event.data.reqId);
218
237
  if (!isWireRequest(event.data)) return;
@@ -232,9 +251,9 @@ export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promi
232
251
  const reload = () => transport.send(base, { type: 'reload' });
233
252
  const stopWatching = options.liveReload === false ? undefined : watchForPreviewUpdates(fs, server, (update) => transport.send(base, update));
234
253
 
235
- const previewMessages = listenToPreview(window, transport.origin, base);
254
+ const previewMessages = listenToPreview(window, transport.origin, base, nonce);
236
255
  // WebSockets and document.cookie for virtual servers, which a service worker cannot carry.
237
- const bridge = listenToPreviewBridge(window, transport.origin, base, { upgrade: (port, request) => processes.upgrade(port, request), cookies });
256
+ const bridge = listenToPreviewBridge(window, transport.origin, base, { upgrade: (port, request) => processes.upgrade(port, request), cookies, nonce });
238
257
 
239
258
  return {
240
259
  id,
@@ -244,7 +263,7 @@ export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promi
244
263
  server,
245
264
  writeTree: (files, at) => fs.writeTree(files, at),
246
265
  exportZip: (zipOptions) => exportZip(fs, zipOptions),
247
- importZip: (zip, at) => importZip(fs, zip, at),
266
+ importZip: (zip, at, limits) => importZip(fs, zip, at, limits),
248
267
  reload,
249
268
  profile: () => server.profile(),
250
269
  async build(buildOptions = {}) {
@@ -258,10 +277,13 @@ export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promi
258
277
  server.setPreviewScripts(previewScripts);
259
278
  reload();
260
279
  },
261
- run: (command: string, args?: string[] | ProcessOptions, runOptions?: ProcessOptions) => processes.run(command, args as string[], runOptions),
280
+ run(command: string, argsOrOptions?: string[] | ProcessOptions, maybeOptions?: ProcessOptions) {
281
+ const [args, runOptions] = runArguments(argsOrOptions, maybeOptions);
282
+ return processes.run(command, args, runOptions.cwd === undefined ? runOptions : { ...runOptions, cwd: projectToBase(root, runOptions.cwd) });
283
+ },
262
284
  onServerListening: (listener) => processes.servers.onListening(listener),
263
285
  onPortChange: (listener) => processes.servers.onPortChange(listener),
264
- listProcesses: () => processes.list(),
286
+ listProcesses: () => processes.list().map((info) => ({ ...info, cwd: baseToProject(root, info.cwd) ?? info.cwd })),
265
287
  cookies,
266
288
  dispose() {
267
289
  bridge.dispose();
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Phase 1 — Local CPU Inference Engine: deterministic mock backend.
3
+ *
4
+ * Fixture-backed stand-in for a real 1B Q4 model. It generates a fixed token
5
+ * stream from a small embedded "vocabulary", sleeps `msPerToken` between
6
+ * tokens to simulate decode, and is used to validate the worker comms,
7
+ * caching, and offline paths without downloading a real model — this
8
+ * environment has no headless browser and no model host. The mock is a
9
+ * first-class backend in the abstraction so the runtime is testable end to
10
+ * end; real backends plug into the same interface.
11
+ */
12
+
13
+ import type {
14
+ BackendContext,
15
+ BackendInfo,
16
+ ChatMessage,
17
+ GenerateOptions,
18
+ InferenceBackend,
19
+ InferenceToken,
20
+ ModelRef,
21
+ } from '../types.js';
22
+ import { renderChatPrompt } from './onnx.js';
23
+
24
+ /** Tiny deterministic vocabulary the mock decodes from. */
25
+ export const MOCK_VOCAB = [
26
+ 'the', 'quick', 'brown', 'fox', 'jumps', 'over', 'lazy', 'dog', 'and', 'runs',
27
+ 'through', 'forest', 'while', 'birds', 'sing', 'softly', 'in', 'morning', 'light', '.',
28
+ ];
29
+
30
+ export interface MockBackendOptions {
31
+ /** Simulated decode latency per token (ms). Default 50 → 20 tok/s. */
32
+ msPerToken?: number;
33
+ /** Deterministic seed offset so repeated runs give the same stream. */
34
+ seed?: number;
35
+ now?: () => number;
36
+ sleep?: (ms: number) => Promise<void>;
37
+ }
38
+
39
+ export function createMockBackend(options: MockBackendOptions = {}): InferenceBackend {
40
+ const msPerToken = options.msPerToken ?? 50;
41
+ const seed = options.seed ?? 0;
42
+ const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
43
+ let loaded: ModelRef | undefined;
44
+
45
+ return {
46
+ kind: 'mock',
47
+
48
+ async probe(): Promise<BackendInfo> {
49
+ return { kind: 'mock', available: true, wasmSimd: false, webgpu: false };
50
+ },
51
+
52
+ async load(model, _weights, context: BackendContext): Promise<void> {
53
+ loaded = model;
54
+ context.log(`mock: loaded ${model.id}`);
55
+ },
56
+
57
+ async *generate(messages: ChatMessage[], genOptions?: GenerateOptions): AsyncIterable<InferenceToken> {
58
+ if (!loaded) throw new Error('mock: generate called before load');
59
+ const maxTokens = genOptions?.maxTokens ?? 32;
60
+ const prompt = renderChatPrompt(messages);
61
+ // Deterministic token stream: hash the prompt so different prompts
62
+ // give different (but stable) output.
63
+ let hash = seed;
64
+ for (let i = 0; i < prompt.length; i++) hash = (hash * 31 + prompt.charCodeAt(i)) | 0;
65
+ for (let index = 0; index < maxTokens; index++) {
66
+ if (genOptions?.signal?.aborted) return;
67
+ await sleep(msPerToken);
68
+ hash = (hash * 1103515245 + 12345) | 0;
69
+ yield { token: MOCK_VOCAB[Math.abs(hash) % MOCK_VOCAB.length] ?? 'the', index };
70
+ }
71
+ },
72
+
73
+ async dispose(): Promise<void> {
74
+ loaded = undefined;
75
+ },
76
+ };
77
+ }
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Phase 1 — Local CPU Inference Engine: ONNX Runtime Web backend.
3
+ *
4
+ * Chosen as the primary CPU-first backend (see `docs/phase-1/report.md` for
5
+ * the tradeoff analysis against Wllama/llama.cpp WASM and WebLLM). The
6
+ * backend is an adapter over a `ort-wasm` module object — tests inject a
7
+ * mock module; the browser loads the real `onnxruntime-web` package (an
8
+ * optional dependency the host app provides). Nothing here imports the
9
+ * package directly, keeping the core package dependency-free and the
10
+ * backend swappable.
11
+ */
12
+
13
+ import type {
14
+ BackendContext,
15
+ BackendInfo,
16
+ ChatMessage,
17
+ GenerateOptions,
18
+ InferenceBackend,
19
+ InferenceToken,
20
+ ModelRef,
21
+ } from '../types.js';
22
+ import { detectBackendEnv } from '../capabilities.js';
23
+
24
+ /** Minimal shape of the onnxruntime-web wasm inference session we use. */
25
+ export interface OrtWasmModule {
26
+ initRuntime(wasmSimd: boolean): Promise<void>;
27
+ createSession(weights: ArrayBuffer, modelId: string): Promise<OrtSession>;
28
+ }
29
+
30
+ export interface OrtSession {
31
+ run(prompt: string, options: { maxTokens: number; temperature: number; signal?: AbortSignal }): AsyncIterable<string>;
32
+ release(): Promise<void>;
33
+ }
34
+
35
+ export interface OnnxBackendOptions {
36
+ /** Load/inject the wasm module. Only called when the backend is used. */
37
+ loadModule(): Promise<OrtWasmModule>;
38
+ }
39
+
40
+ export function createOnnxBackend(options: OnnxBackendOptions): InferenceBackend {
41
+ let module: OrtWasmModule | undefined;
42
+ let session: OrtSession | undefined;
43
+ let loadedRef: ModelRef | undefined;
44
+
45
+ return {
46
+ kind: 'onnx',
47
+
48
+ async probe(): Promise<BackendInfo> {
49
+ const env = detectBackendEnv();
50
+ return {
51
+ kind: 'onnx',
52
+ available: env.wasm,
53
+ reason: env.wasm ? undefined : 'WebAssembly not available',
54
+ wasmSimd: env.wasmSimd,
55
+ webgpu: false,
56
+ };
57
+ },
58
+
59
+ async load(model, weights, context: BackendContext): Promise<void> {
60
+ module ??= await options.loadModule();
61
+ await module.initRuntime(context.wasmSimd);
62
+ session = await module.createSession(weights, model.id);
63
+ loadedRef = model;
64
+ context.log(`onnx: loaded ${model.id} (${model.quantization}, ${model.paramsB}B)`);
65
+ },
66
+
67
+ async *generate(messages: ChatMessage[], options?: GenerateOptions): AsyncIterable<InferenceToken> {
68
+ if (!session) throw new Error('onnx: generate called before load');
69
+ const prompt = renderChatPrompt(messages);
70
+ const maxTokens = options?.maxTokens ?? 256;
71
+ const temperature = options?.temperature ?? 0.7;
72
+ let index = 0;
73
+ for await (const token of session.run(prompt, { maxTokens, temperature, signal: options?.signal })) {
74
+ yield { token, index: index++ };
75
+ }
76
+ },
77
+
78
+ async dispose(): Promise<void> {
79
+ await session?.release();
80
+ session = undefined;
81
+ loadedRef = undefined;
82
+ },
83
+ };
84
+ }
85
+
86
+ /** Shared chat-prompt renderer — deterministic, used by all backends. */
87
+ export function renderChatPrompt(messages: ChatMessage[]): string {
88
+ return messages
89
+ .map((m) => `<|${m.role}|>\n${m.content}</|${m.role}|>`)
90
+ .join('\n') + '\n<|assistant|>\n';
91
+ }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Phase 1 — Local CPU Inference Engine: WebLLM backend (optional).
3
+ *
4
+ * WebLLM is WebGPU-only, so it is OPTIONAL and never required for core
5
+ * functionality — CPU-only operation must remain fully supported. This
6
+ * adapter reports unavailable when WebGPU is absent and the runtime's
7
+ * backend selection never depends on it. It exists so the abstraction is
8
+ * proven to host a WebGPU backend ahead of Phase 5.
9
+ */
10
+
11
+ import type {
12
+ BackendContext,
13
+ BackendInfo,
14
+ ChatMessage,
15
+ GenerateOptions,
16
+ InferenceBackend,
17
+ InferenceToken,
18
+ ModelRef,
19
+ } from '../types.js';
20
+ import { renderChatPrompt } from './onnx.js';
21
+
22
+ export interface WebLlmModule {
23
+ init(): Promise<void>;
24
+ loadModel(modelId: string): Promise<WebLlmModel>;
25
+ }
26
+
27
+ export interface WebLlmModel {
28
+ generate(prompt: string, options: { maxTokens: number; temperature: number; signal?: AbortSignal }): AsyncIterable<string>;
29
+ release(): Promise<void>;
30
+ }
31
+
32
+ export interface WebLlmBackendOptions {
33
+ loadModule(): Promise<WebLlmModule>;
34
+ }
35
+
36
+ export function createWebLlmBackend(options: WebLlmBackendOptions): InferenceBackend {
37
+ let module: WebLlmModule | undefined;
38
+ let model: WebLlmModel | undefined;
39
+
40
+ return {
41
+ kind: 'webllm',
42
+
43
+ async probe(): Promise<BackendInfo> {
44
+ const webgpu = typeof navigator !== 'undefined' && 'gpu' in navigator;
45
+ return {
46
+ kind: 'webllm',
47
+ available: webgpu,
48
+ reason: webgpu ? undefined : 'WebGPU not available (WebLLM requires WebGPU)',
49
+ wasmSimd: false,
50
+ webgpu,
51
+ };
52
+ },
53
+
54
+ async load(modelRef: ModelRef, _weights: ArrayBuffer, context: BackendContext): Promise<void> {
55
+ if (!context.webgpu) throw new Error('webllm: WebGPU not available');
56
+ module ??= await options.loadModule();
57
+ await module.init();
58
+ model = await module.loadModel(modelRef.id);
59
+ context.log(`webllm: loaded ${modelRef.id}`);
60
+ },
61
+
62
+ async *generate(messages: ChatMessage[], options?: GenerateOptions): AsyncIterable<InferenceToken> {
63
+ if (!model) throw new Error('webllm: generate called before load');
64
+ let index = 0;
65
+ for await (const token of model.generate(renderChatPrompt(messages), {
66
+ maxTokens: options?.maxTokens ?? 256,
67
+ temperature: options?.temperature ?? 0.7,
68
+ signal: options?.signal,
69
+ })) {
70
+ yield { token, index: index++ };
71
+ }
72
+ },
73
+
74
+ async dispose(): Promise<void> {
75
+ await model?.release();
76
+ model = undefined;
77
+ },
78
+ };
79
+ }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Phase 1 — Local CPU Inference Engine: Wllama (llama.cpp WASM) backend.
3
+ *
4
+ * Registered as an alternative CPU backend. Like the ONNX adapter, it wraps
5
+ * an injected `WllamaModule` so this package carries no llama.cpp/wllama
6
+ * dependency; a host that prefers GGUF models provides the module. Kept as
7
+ * the secondary path pending the Phase 1 decision recorded in
8
+ * `docs/phase-1/report.md`.
9
+ */
10
+
11
+ import type {
12
+ BackendContext,
13
+ BackendInfo,
14
+ ChatMessage,
15
+ GenerateOptions,
16
+ InferenceBackend,
17
+ InferenceToken,
18
+ ModelRef,
19
+ } from '../types.js';
20
+ import { renderChatPrompt } from './onnx.js';
21
+ import { detectBackendEnv } from '../capabilities.js';
22
+
23
+ export interface WllamaModule {
24
+ init(config: { simd: boolean }): Promise<void>;
25
+ loadModel(weights: ArrayBuffer, modelId: string): Promise<WllamaModel>;
26
+ }
27
+
28
+ export interface WllamaModel {
29
+ generate(prompt: string, options: { maxTokens: number; temperature: number; signal?: AbortSignal }): AsyncIterable<string>;
30
+ release(): Promise<void>;
31
+ }
32
+
33
+ export interface WllamaBackendOptions {
34
+ loadModule(): Promise<WllamaModule>;
35
+ }
36
+
37
+ export function createWllamaBackend(options: WllamaBackendOptions): InferenceBackend {
38
+ let module: WllamaModule | undefined;
39
+ let model: WllamaModel | undefined;
40
+
41
+ return {
42
+ kind: 'wllama',
43
+
44
+ async probe(): Promise<BackendInfo> {
45
+ const env = detectBackendEnv();
46
+ return {
47
+ kind: 'wllama',
48
+ available: env.wasm,
49
+ reason: env.wasm ? undefined : 'WebAssembly not available',
50
+ wasmSimd: env.wasmSimd,
51
+ webgpu: false,
52
+ };
53
+ },
54
+
55
+ async load(modelRef: ModelRef, weights: ArrayBuffer, context: BackendContext): Promise<void> {
56
+ module ??= await options.loadModule();
57
+ await module.init({ simd: context.wasmSimd });
58
+ model = await module.loadModel(weights, modelRef.id);
59
+ context.log(`wllama: loaded ${modelRef.id}`);
60
+ },
61
+
62
+ async *generate(messages: ChatMessage[], options?: GenerateOptions): AsyncIterable<InferenceToken> {
63
+ if (!model) throw new Error('wllama: generate called before load');
64
+ let index = 0;
65
+ for await (const token of model.generate(renderChatPrompt(messages), {
66
+ maxTokens: options?.maxTokens ?? 256,
67
+ temperature: options?.temperature ?? 0.7,
68
+ signal: options?.signal,
69
+ })) {
70
+ yield { token, index: index++ };
71
+ }
72
+ },
73
+
74
+ async dispose(): Promise<void> {
75
+ await model?.release();
76
+ model = undefined;
77
+ },
78
+ };
79
+ }
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Phase 1 — Local CPU Inference Engine: environment capability probe.
3
+ *
4
+ * Best-effort detection of what the current browser can run. SharedArrayBuffer
5
+ * and cross-origin isolation are OPTIONAL — the runtime must work without
6
+ * them — so these are reported, never assumed. The individual probes live in
7
+ * `shared/hardwareProbe.ts` (the one home shared with the adaptive controller
8
+ * and the memory manager); this module only assembles the report.
9
+ */
10
+
11
+ import {
12
+ detectCrossOriginIsolated,
13
+ detectSharedArrayBuffer,
14
+ detectWasm,
15
+ detectWasmSimd,
16
+ detectWebGpu,
17
+ } from '../shared/hardwareProbe.js';
18
+ import type { BackendKind, RuntimeCapabilities } from './types.js';
19
+
20
+ /** Shared wasm / wasm-SIMD detection for backend probes (onnx, wllama). */
21
+ export function detectBackendEnv(): { wasm: boolean; wasmSimd: boolean } {
22
+ const wasm = detectWasm();
23
+ return { wasm, wasmSimd: wasm && detectWasmSimd() };
24
+ }
25
+
26
+ export function probeRuntimeCapabilities(backends: InferenceBackendLike[] = []): RuntimeCapabilities {
27
+ const { wasm, wasmSimd } = detectBackendEnv();
28
+ const webgpu = detectWebGpu();
29
+ return {
30
+ wasm,
31
+ wasmSimd,
32
+ webgpu,
33
+ crossOriginIsolated: detectCrossOriginIsolated(),
34
+ sharedArrayBuffer: detectSharedArrayBuffer(),
35
+ backends: backends.map((b) => ({
36
+ kind: b.kind as BackendKind,
37
+ available: wasm,
38
+ wasmSimd,
39
+ webgpu,
40
+ })),
41
+ };
42
+ }
43
+
44
+ export interface InferenceBackendLike {
45
+ kind: string;
46
+ }