@awacloud/fw 0.1.0 → 1.0.0

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 (609) hide show
  1. package/CHANGELOG.md +125 -0
  2. package/NOTICE +8 -0
  3. package/README.md +163 -31
  4. package/dist/build/fw.core.pure.meta.json +6 -6
  5. package/dist/build/fw.core.pure.min.js +15 -12
  6. package/dist/build/fw.full.pure.meta.json +13 -7
  7. package/dist/build/fw.full.pure.min.js +45 -42
  8. package/dist/build/fw.minimal.pure.meta.json +6 -6
  9. package/dist/build/fw.minimal.pure.min.js +16 -13
  10. package/dist/build/fw.pack.compress-heavy.pure.meta.json +6 -6
  11. package/dist/build/fw.pack.compress-heavy.pure.min.js +3 -3
  12. package/dist/build/fw.pack.crypto-advanced.pure.meta.json +6 -6
  13. package/dist/build/fw.pack.crypto-advanced.pure.min.js +1 -1
  14. package/dist/build/fw.pack.crypto-basic.pure.meta.json +6 -6
  15. package/dist/build/fw.pack.crypto-basic.pure.min.js +1 -1
  16. package/dist/build/fw.pack.crypto-identity.pure.meta.json +7 -6
  17. package/dist/build/fw.pack.crypto-identity.pure.min.js +4 -4
  18. package/dist/build/fw.pwa.pure.meta.json +7 -6
  19. package/dist/build/fw.pwa.pure.min.js +38 -35
  20. package/dist/build/fw.site-interactive.pure.meta.json +6 -6
  21. package/dist/build/fw.site-interactive.pure.min.js +37 -34
  22. package/dist/build/fw.site.pure.meta.json +6 -6
  23. package/dist/build/fw.site.pure.min.js +24 -21
  24. package/dist/build/fw.spa.pure.meta.json +8 -7
  25. package/dist/build/fw.spa.pure.min.js +41 -38
  26. package/dist/build/sanity-base-classic.min.js +1 -1
  27. package/dist/build/sanity.min.js +1 -1
  28. package/dist/types/core/internal.d.ts +29 -0
  29. package/dist/types/core/internal.d.ts.map +1 -0
  30. package/dist/types/core/logger.d.ts +23 -4
  31. package/dist/types/core/logger.d.ts.map +1 -1
  32. package/dist/types/core/modules.d.ts +374 -61
  33. package/dist/types/core/modules.d.ts.map +1 -1
  34. package/dist/types/core/runtime.d.ts +10 -6
  35. package/dist/types/core/runtime.d.ts.map +1 -1
  36. package/dist/types/core/worker-helper.d.ts +35 -0
  37. package/dist/types/core/worker-helper.d.ts.map +1 -1
  38. package/dist/types/crypto/cipher/aes.d.ts +1 -7
  39. package/dist/types/crypto/cipher/aes.d.ts.map +1 -1
  40. package/dist/types/crypto/cipher/chacha20.d.ts +0 -10
  41. package/dist/types/crypto/cipher/chacha20.d.ts.map +1 -1
  42. package/dist/types/crypto/hash/argon2.d.ts +0 -15
  43. package/dist/types/crypto/hash/argon2.d.ts.map +1 -1
  44. package/dist/types/crypto/hash/blake2b.d.ts.map +1 -1
  45. package/dist/types/crypto/hash/hmac.d.ts.map +1 -1
  46. package/dist/types/crypto/hash/pbkdf2.d.ts.map +1 -1
  47. package/dist/types/crypto/hash/poly1305.d.ts.map +1 -1
  48. package/dist/types/crypto/hash/sha224.d.ts +1 -1
  49. package/dist/types/crypto/hash/sha256.d.ts +4 -13
  50. package/dist/types/crypto/hash/sha256.d.ts.map +1 -1
  51. package/dist/types/crypto/hash/sha3.d.ts.map +1 -1
  52. package/dist/types/crypto/hash/sha384.d.ts +1 -1
  53. package/dist/types/crypto/hash/sha512.d.ts +4 -13
  54. package/dist/types/crypto/hash/sha512.d.ts.map +1 -1
  55. package/dist/types/crypto/mode/cmac.d.ts +0 -6
  56. package/dist/types/crypto/mode/cmac.d.ts.map +1 -1
  57. package/dist/types/crypto/mode/ctr.d.ts +0 -6
  58. package/dist/types/crypto/mode/ctr.d.ts.map +1 -1
  59. package/dist/types/crypto/mode/gcm.d.ts +0 -9
  60. package/dist/types/crypto/mode/gcm.d.ts.map +1 -1
  61. package/dist/types/crypto/pkc/ecc.d.ts +0 -1
  62. package/dist/types/crypto/pkc/ecc.d.ts.map +1 -1
  63. package/dist/types/crypto/pkc/ed25519.d.ts +4 -25
  64. package/dist/types/crypto/pkc/ed25519.d.ts.map +1 -1
  65. package/dist/types/crypto/pkc/hybridSign.d.ts +25 -5
  66. package/dist/types/crypto/pkc/hybridSign.d.ts.map +1 -1
  67. package/dist/types/crypto/pkc/ml_dsa.d.ts +6 -26
  68. package/dist/types/crypto/pkc/ml_dsa.d.ts.map +1 -1
  69. package/dist/types/crypto/pkc/ml_kem.d.ts +0 -43
  70. package/dist/types/crypto/pkc/ml_kem.d.ts.map +1 -1
  71. package/dist/types/crypto/pkc/rsa.d.ts +0 -24
  72. package/dist/types/crypto/pkc/rsa.d.ts.map +1 -1
  73. package/dist/types/crypto/pkc/slh_dsa.d.ts +6 -16
  74. package/dist/types/crypto/pkc/slh_dsa.d.ts.map +1 -1
  75. package/dist/types/crypto/pkc/x25519.d.ts +0 -6
  76. package/dist/types/crypto/pkc/x25519.d.ts.map +1 -1
  77. package/dist/types/crypto/utils/bitArray.d.ts +0 -8
  78. package/dist/types/crypto/utils/bitArray.d.ts.map +1 -1
  79. package/dist/types/crypto/utils/jws.d.ts +6 -14
  80. package/dist/types/crypto/utils/jws.d.ts.map +1 -1
  81. package/dist/types/crypto/utils/keyformat.d.ts +52 -0
  82. package/dist/types/crypto/utils/keyformat.d.ts.map +1 -1
  83. package/dist/types/crypto/utils/random.d.ts +1 -10
  84. package/dist/types/crypto/utils/random.d.ts.map +1 -1
  85. package/dist/types/crypto/utils/rsaKeygen.d.ts +0 -10
  86. package/dist/types/crypto/utils/rsaKeygen.d.ts.map +1 -1
  87. package/dist/types/crypto/utils/uuid.d.ts.map +1 -1
  88. package/dist/types/crypto/utils/x509.d.ts +397 -0
  89. package/dist/types/crypto/utils/x509.d.ts.map +1 -0
  90. package/dist/types/crypto/wasm/argon2.d.ts +2 -1
  91. package/dist/types/crypto/wasm/argon2.d.ts.map +1 -1
  92. package/dist/types/crypto/wasm/pbkdf2.d.ts +2 -2
  93. package/dist/types/crypto/wasm/pbkdf2.d.ts.map +1 -1
  94. package/dist/types/crypto/wasm/rsa.d.ts.map +1 -1
  95. package/dist/types/crypto/wasm/runtime.d.ts +13 -0
  96. package/dist/types/crypto/wasm/runtime.d.ts.map +1 -1
  97. package/dist/types/crypto/webcrypto/aes.d.ts.map +1 -1
  98. package/dist/types/crypto/webcrypto/aeskw.d.ts.map +1 -1
  99. package/dist/types/crypto/webcrypto/digest.d.ts +0 -4
  100. package/dist/types/crypto/webcrypto/digest.d.ts.map +1 -1
  101. package/dist/types/crypto/webcrypto/rsa.d.ts.map +1 -1
  102. package/dist/types/dom/fs/fileIntake.d.ts +59 -0
  103. package/dist/types/dom/fs/fileIntake.d.ts.map +1 -0
  104. package/dist/types/dom/fs/fsAccess.d.ts.map +1 -1
  105. package/dist/types/dom/query/dnd.d.ts.map +1 -1
  106. package/dist/types/dom/query/sound.d.ts +89 -0
  107. package/dist/types/dom/query/sound.d.ts.map +1 -0
  108. package/dist/types/dom/rendering/chart.d.ts.map +1 -1
  109. package/dist/types/dom/rendering/component.d.ts +9 -3
  110. package/dist/types/dom/rendering/component.d.ts.map +1 -1
  111. package/dist/types/dom/rendering/parser.d.ts +39 -0
  112. package/dist/types/dom/rendering/parser.d.ts.map +1 -1
  113. package/dist/types/dom/rendering/render.d.ts.map +1 -1
  114. package/dist/types/dom/rendering/sanitize.d.ts +4 -0
  115. package/dist/types/dom/rendering/sanitize.d.ts.map +1 -1
  116. package/dist/types/dom/rendering/secPolicy.d.ts.map +1 -1
  117. package/dist/types/dom/rendering/styleSheet.d.ts +74 -0
  118. package/dist/types/dom/rendering/styleSheet.d.ts.map +1 -0
  119. package/dist/types/dom/rendering/template.d.ts +9 -3
  120. package/dist/types/dom/rendering/template.d.ts.map +1 -1
  121. package/dist/types/dom/rendering/themeTokens.d.ts +9 -3
  122. package/dist/types/dom/rendering/themeTokens.d.ts.map +1 -1
  123. package/dist/types/dom/rendering/uiSession-core.d.ts +9 -3
  124. package/dist/types/dom/rendering/uiSession-core.d.ts.map +1 -1
  125. package/dist/types/dom/rendering/uiSession-list.d.ts +9 -3
  126. package/dist/types/dom/rendering/uiSession-list.d.ts.map +1 -1
  127. package/dist/types/dom/rendering/uiSession.d.ts +18 -6
  128. package/dist/types/dom/rendering/uiSession.d.ts.map +1 -1
  129. package/dist/types/dom/sw/installPrompt.d.ts +89 -0
  130. package/dist/types/dom/sw/installPrompt.d.ts.map +1 -0
  131. package/dist/types/dom/sw/precache.d.ts +149 -0
  132. package/dist/types/dom/sw/precache.d.ts.map +1 -0
  133. package/dist/types/dom/sw/swUpdate.d.ts +129 -0
  134. package/dist/types/dom/sw/swUpdate.d.ts.map +1 -0
  135. package/dist/types/dom/utils/clipboard.d.ts +8 -0
  136. package/dist/types/dom/utils/clipboard.d.ts.map +1 -1
  137. package/dist/types/dom/utils/keybindings.d.ts.map +1 -1
  138. package/dist/types/dom/utils/route.d.ts.map +1 -1
  139. package/dist/types/dom/utils/ua.d.ts +2 -2
  140. package/dist/types/dom/utils/ua.d.ts.map +1 -1
  141. package/dist/types/io/calc/crc32.d.ts.map +1 -1
  142. package/dist/types/io/codec/b64.d.ts +24 -0
  143. package/dist/types/io/codec/b64.d.ts.map +1 -1
  144. package/dist/types/io/codec/cbor.d.ts +1 -0
  145. package/dist/types/io/codec/cbor.d.ts.map +1 -1
  146. package/dist/types/io/codec/hex.d.ts.map +1 -1
  147. package/dist/types/io/codec/msgpack.d.ts +1 -0
  148. package/dist/types/io/codec/msgpack.d.ts.map +1 -1
  149. package/dist/types/io/codec/url.d.ts +3 -1
  150. package/dist/types/io/codec/url.d.ts.map +1 -1
  151. package/dist/types/io/codec/utf8.d.ts.map +1 -1
  152. package/dist/types/io/compress/bitstream.d.ts +1 -1
  153. package/dist/types/io/compress/brotli.d.ts +0 -1
  154. package/dist/types/io/compress/brotli.d.ts.map +1 -1
  155. package/dist/types/io/compress/brotli_shared.d.ts +0 -4
  156. package/dist/types/io/compress/brotli_shared.d.ts.map +1 -1
  157. package/dist/types/io/compress/deflate.d.ts +14 -1
  158. package/dist/types/io/compress/deflate.d.ts.map +1 -1
  159. package/dist/types/io/compress/gzip.d.ts +4 -0
  160. package/dist/types/io/compress/gzip.d.ts.map +1 -1
  161. package/dist/types/io/compress/huffman.d.ts +7 -0
  162. package/dist/types/io/compress/huffman.d.ts.map +1 -1
  163. package/dist/types/io/compress/lz4.d.ts +4 -2
  164. package/dist/types/io/compress/lz4.d.ts.map +1 -1
  165. package/dist/types/io/compress/lz77.d.ts +17 -0
  166. package/dist/types/io/compress/lz77.d.ts.map +1 -1
  167. package/dist/types/io/compress/lzw.d.ts +2 -0
  168. package/dist/types/io/compress/lzw.d.ts.map +1 -1
  169. package/dist/types/io/compress/zip.d.ts.map +1 -1
  170. package/dist/types/io/compress/zlib.d.ts +9 -2
  171. package/dist/types/io/compress/zlib.d.ts.map +1 -1
  172. package/dist/types/io/math/linalg.d.ts.map +1 -1
  173. package/dist/types/process/rpc.d.ts.map +1 -1
  174. package/dist/types/process/workerPool.d.ts.map +1 -1
  175. package/dist/types/sanity/base.d.ts +12 -2
  176. package/dist/types/sanity/base.d.ts.map +1 -1
  177. package/dist/types/sanity/lockdown.d.ts +6 -5
  178. package/dist/types/sanity/lockdown.d.ts.map +1 -1
  179. package/dist/types/sanity/wasm-gate.d.ts +1 -1
  180. package/docs/README.md +17 -10
  181. package/docs/api/README.md +5 -5
  182. package/docs/api/core/logger.md +2 -1
  183. package/docs/api/core/modules.md +3 -3
  184. package/docs/api/core/runtime.md +9 -9
  185. package/docs/api/core/worker-helper.md +12 -2
  186. package/docs/api/crypto/README.md +1 -1
  187. package/docs/api/crypto/cipher/README.md +2 -2
  188. package/docs/api/crypto/cipher/aes.md +5 -10
  189. package/docs/api/crypto/cipher/chacha20.md +3 -8
  190. package/docs/api/crypto/hash/README.md +5 -5
  191. package/docs/api/crypto/hash/adf.md +21 -11
  192. package/docs/api/crypto/hash/argon2.md +3 -12
  193. package/docs/api/crypto/hash/blake2b.md +12 -14
  194. package/docs/api/crypto/hash/pbkdf2.md +1 -1
  195. package/docs/api/crypto/hash/sha224.md +2 -2
  196. package/docs/api/crypto/hash/sha256.md +4 -4
  197. package/docs/api/crypto/hash/sha3.md +2 -2
  198. package/docs/api/crypto/hash/sha384.md +1 -1
  199. package/docs/api/crypto/hash/sha512.md +5 -5
  200. package/docs/api/crypto/hash/sha512_224.md +1 -1
  201. package/docs/api/crypto/hash/sha512_256.md +1 -1
  202. package/docs/api/crypto/mode/README.md +3 -3
  203. package/docs/api/crypto/mode/cbc.md +2 -2
  204. package/docs/api/crypto/mode/chacha20poly1305.md +1 -1
  205. package/docs/api/crypto/mode/cmac.md +4 -4
  206. package/docs/api/crypto/mode/ctr.md +2 -3
  207. package/docs/api/crypto/mode/gcm.md +5 -5
  208. package/docs/api/crypto/mode/kw.md +4 -4
  209. package/docs/api/crypto/pkc/README.md +8 -8
  210. package/docs/api/crypto/pkc/ecc.md +19 -17
  211. package/docs/api/crypto/pkc/ed25519.md +10 -15
  212. package/docs/api/crypto/pkc/hybridKem.md +8 -2
  213. package/docs/api/crypto/pkc/hybridSign.md +34 -7
  214. package/docs/api/crypto/pkc/ml_dsa.md +20 -19
  215. package/docs/api/crypto/pkc/ml_kem.md +3 -3
  216. package/docs/api/crypto/pkc/rsa.md +7 -9
  217. package/docs/api/crypto/pkc/slh_dsa.md +12 -12
  218. package/docs/api/crypto/pkc/x25519.md +5 -4
  219. package/docs/api/crypto/utils/README.md +7 -7
  220. package/docs/api/crypto/utils/aes_modes.md +2 -5
  221. package/docs/api/crypto/utils/asn1.md +25 -16
  222. package/docs/api/crypto/utils/jws.md +6 -4
  223. package/docs/api/crypto/utils/keyformat.md +24 -15
  224. package/docs/api/crypto/utils/pad.md +1 -1
  225. package/docs/api/crypto/utils/pem.md +3 -3
  226. package/docs/api/crypto/utils/random.md +3 -4
  227. package/docs/api/crypto/utils/rsaKeygen.md +2 -2
  228. package/docs/api/crypto/utils/totp.md +2 -2
  229. package/docs/api/crypto/utils/uuid.md +5 -5
  230. package/docs/api/crypto/utils/x509.md +124 -0
  231. package/docs/api/crypto/wasm/aes.md +1 -1
  232. package/docs/api/crypto/wasm/argon2.md +6 -4
  233. package/docs/api/crypto/wasm/ml_kem.md +1 -0
  234. package/docs/api/crypto/wasm/pbkdf2.md +8 -8
  235. package/docs/api/crypto/wasm/rsa.md +1 -1
  236. package/docs/api/crypto/wasm/runtime.md +27 -10
  237. package/docs/api/crypto/webcrypto/aes.md +1 -1
  238. package/docs/api/crypto/webcrypto/aeskw.md +2 -2
  239. package/docs/api/crypto/webcrypto/digest.md +3 -5
  240. package/docs/api/crypto/webcrypto/ecc.md +1 -1
  241. package/docs/api/crypto/webcrypto/ed25519.md +1 -1
  242. package/docs/api/crypto/webcrypto/rsa.md +3 -2
  243. package/docs/api/crypto/webcrypto/x25519.md +1 -1
  244. package/docs/api/dom/README.md +6 -1
  245. package/docs/api/dom/fs/README.md +1 -0
  246. package/docs/api/dom/fs/fileIntake.md +120 -0
  247. package/docs/api/dom/fs/fsAccess.md +1 -0
  248. package/docs/api/dom/fs/indexedDB.md +1 -1
  249. package/docs/api/dom/fs/storage.md +1 -1
  250. package/docs/api/dom/query/README.md +2 -1
  251. package/docs/api/dom/query/dnd.md +4 -1
  252. package/docs/api/dom/query/dom.md +5 -0
  253. package/docs/api/dom/query/sound.md +103 -0
  254. package/docs/api/dom/rendering/README.md +4 -3
  255. package/docs/api/dom/rendering/chart.md +5 -4
  256. package/docs/api/dom/rendering/component.md +25 -3
  257. package/docs/api/dom/rendering/parser.md +5 -2
  258. package/docs/api/dom/rendering/reactiveBind.md +1 -1
  259. package/docs/api/dom/rendering/render.md +2 -2
  260. package/docs/api/dom/rendering/sanitize.md +10 -2
  261. package/docs/api/dom/rendering/secPolicy.md +4 -4
  262. package/docs/api/dom/rendering/styleSheet.md +85 -0
  263. package/docs/api/dom/rendering/template.md +20 -5
  264. package/docs/api/dom/rendering/themeTokens.md +6 -3
  265. package/docs/api/dom/rendering/uiSession.md +18 -5
  266. package/docs/api/dom/rendering/virtualScroll.md +2 -2
  267. package/docs/api/dom/sensors/geolocation.md +1 -1
  268. package/docs/api/dom/sw/README.md +7 -1
  269. package/docs/api/dom/sw/cache.md +2 -1
  270. package/docs/api/dom/sw/installPrompt.md +111 -0
  271. package/docs/api/dom/sw/precache.md +124 -0
  272. package/docs/api/dom/sw/serviceWorker.md +4 -2
  273. package/docs/api/dom/sw/swUpdate.md +112 -0
  274. package/docs/api/dom/utils/clipboard.md +56 -5
  275. package/docs/api/dom/utils/entropyCollector.md +1 -1
  276. package/docs/api/dom/utils/keybindings.md +17 -2
  277. package/docs/api/dom/utils/leaderElection.md +2 -2
  278. package/docs/api/dom/utils/route.md +1 -0
  279. package/docs/api/dom/utils/ua.md +15 -10
  280. package/docs/api/io/calc/crc32.md +4 -1
  281. package/docs/api/io/codec/README.md +2 -2
  282. package/docs/api/io/codec/b64.md +31 -2
  283. package/docs/api/io/codec/buffer.md +1 -1
  284. package/docs/api/io/codec/cbor.md +6 -4
  285. package/docs/api/io/codec/csv.md +178 -178
  286. package/docs/api/io/codec/hex.md +10 -2
  287. package/docs/api/io/codec/msgpack.md +4 -3
  288. package/docs/api/io/codec/url.md +4 -3
  289. package/docs/api/io/codec/utf8.md +3 -3
  290. package/docs/api/io/compress/bitstream.md +6 -3
  291. package/docs/api/io/compress/brotli.md +36 -4
  292. package/docs/api/io/compress/brotli_shared.md +1 -1
  293. package/docs/api/io/compress/deflate.md +42 -34
  294. package/docs/api/io/compress/gzip.md +26 -6
  295. package/docs/api/io/compress/huffman.md +2 -1
  296. package/docs/api/io/compress/lz4.md +5 -3
  297. package/docs/api/io/compress/lz77.md +26 -3
  298. package/docs/api/io/compress/lzw.md +13 -8
  299. package/docs/api/io/compress/zip.md +36 -10
  300. package/docs/api/io/compress/zlib.md +21 -5
  301. package/docs/api/io/math/linalg.md +1 -1
  302. package/docs/api/io/utils/valid.md +1 -1
  303. package/docs/api/process/rpc.md +3 -2
  304. package/docs/api/process/workerPool.md +1 -1
  305. package/docs/api/sanity/base.md +9 -5
  306. package/docs/api/sanity/lockdown.md +7 -6
  307. package/docs/api/surface.json +12311 -0
  308. package/docs/api/typed.md +5 -3
  309. package/docs/dev/README.md +2 -0
  310. package/docs/dev/bench.md +76 -0
  311. package/docs/dev/crypto-references.md +54 -0
  312. package/docs/dev/provenance.md +30 -7
  313. package/docs/dev/publishing.md +7 -7
  314. package/docs/dev/runtime.md +1 -1
  315. package/docs/dev/testing.md +13 -0
  316. package/docs/evidence/l4-evidence.md +86 -0
  317. package/docs/evidence/pqc-hybrid-evidence.md +7 -6
  318. package/docs/guide/README.md +1 -0
  319. package/docs/guide/_QUICK_REF.md +5 -5
  320. package/docs/guide/doc-format.md +4 -3
  321. package/docs/guide/integrations-hmr.md +1 -1
  322. package/docs/guide/module-creation-workflow.md +8 -8
  323. package/docs/guide/rendering-pipeline.md +11 -4
  324. package/docs/guide/security.md +7 -5
  325. package/docs/guide/stability.md +123 -0
  326. package/docs/guide/tutorial-todo.md +20 -8
  327. package/docs/guide/typescript.md +9 -0
  328. package/docs/guide/worker-confinement.md +30 -17
  329. package/docs/notes/lz77-deflate-factorization.md +3 -3
  330. package/docs/tools/README.md +1 -1
  331. package/docs/tools/bundler.md +3 -3
  332. package/docs/tools/codegen.md +1 -1
  333. package/docs/tools/standalone.md +0 -1
  334. package/fw.config.json +2 -2
  335. package/integrations/_shared/catalog.generated.json +7 -1
  336. package/integrations/_shared/core.js +1 -1
  337. package/integrations/astro/index.js +1 -1
  338. package/integrations/eslint/README.md +7 -1
  339. package/integrations/nextjs/index.js +1 -1
  340. package/integrations/nodejs/README.md +3 -3
  341. package/integrations/turbopack/index.js +2 -2
  342. package/integrations/typedoc/categorize.js +1 -1
  343. package/integrations/typedoc/typedoc.json +2 -1
  344. package/integrations/vite/index.js +2 -2
  345. package/integrations/vite/vite-env.d.ts +7 -4
  346. package/integrations/webpack/index.js +3 -3
  347. package/package.json +76 -10
  348. package/src/core/internal.js +31 -0
  349. package/src/core/logger.js +95 -23
  350. package/src/core/modules.js +17 -8
  351. package/src/core/readyState.js +1 -1
  352. package/src/core/runtime.js +74 -27
  353. package/src/core/worker-helper.js +83 -4
  354. package/src/crypto/NIST_CONFORMANCE.md +47 -34
  355. package/src/crypto/cipher/aes.acvp.md +7 -8
  356. package/src/crypto/cipher/aes.js +280 -229
  357. package/src/crypto/cipher/chacha20.acvp.md +6 -7
  358. package/src/crypto/cipher/chacha20.js +91 -61
  359. package/src/crypto/hash/adf.js +1 -1
  360. package/src/crypto/hash/argon2.acvp.md +11 -15
  361. package/src/crypto/hash/argon2.js +9 -24
  362. package/src/crypto/hash/blake2b.js +157 -125
  363. package/src/crypto/hash/hkdf.acvp.md +15 -15
  364. package/src/crypto/hash/hkdf.js +1 -1
  365. package/src/crypto/hash/hmac.acvp.md +10 -12
  366. package/src/crypto/hash/hmac.js +5 -1
  367. package/src/crypto/hash/pbkdf2.acvp.md +13 -13
  368. package/src/crypto/hash/pbkdf2.js +36 -8
  369. package/src/crypto/hash/poly1305.acvp.md +10 -6
  370. package/src/crypto/hash/poly1305.js +171 -50
  371. package/src/crypto/hash/sha224.acvp.md +3 -3
  372. package/src/crypto/hash/sha224.js +4 -4
  373. package/src/crypto/hash/sha256.acvp.md +2 -2
  374. package/src/crypto/hash/sha256.js +514 -50
  375. package/src/crypto/hash/sha3.acvp.md +9 -9
  376. package/src/crypto/hash/sha3.js +127 -71
  377. package/src/crypto/hash/sha384.acvp.md +3 -3
  378. package/src/crypto/hash/sha384.js +4 -4
  379. package/src/crypto/hash/sha512.acvp.md +7 -8
  380. package/src/crypto/hash/sha512.js +107 -108
  381. package/src/crypto/hash/sha512_224.acvp.md +6 -6
  382. package/src/crypto/hash/sha512_224.js +2 -2
  383. package/src/crypto/hash/sha512_256.acvp.md +6 -6
  384. package/src/crypto/hash/sha512_256.js +2 -2
  385. package/src/crypto/mode/cbc.acvp.md +2 -2
  386. package/src/crypto/mode/cbc.js +1 -1
  387. package/src/crypto/mode/chacha20poly1305.acvp.md +6 -6
  388. package/src/crypto/mode/chacha20poly1305.js +3 -3
  389. package/src/crypto/mode/cmac.acvp.md +5 -5
  390. package/src/crypto/mode/cmac.js +8 -8
  391. package/src/crypto/mode/ctr.acvp.md +2 -2
  392. package/src/crypto/mode/ctr.js +1 -3
  393. package/src/crypto/mode/gcm.acvp.md +6 -6
  394. package/src/crypto/mode/gcm.js +7 -7
  395. package/src/crypto/mode/kw.acvp.md +4 -4
  396. package/src/crypto/mode/kw.js +5 -5
  397. package/src/crypto/pkc/ecc.acvp.md +13 -13
  398. package/src/crypto/pkc/ecc.js +9 -11
  399. package/src/crypto/pkc/ed25519.acvp.md +30 -34
  400. package/src/crypto/pkc/ed25519.js +453 -94
  401. package/src/crypto/pkc/hybrid-kat.provenance.md +4 -4
  402. package/src/crypto/pkc/hybridSign.js +103 -24
  403. package/src/crypto/pkc/ml_dsa.acvp.md +18 -18
  404. package/src/crypto/pkc/ml_dsa.js +29 -32
  405. package/src/crypto/pkc/ml_kem.acvp.md +7 -7
  406. package/src/crypto/pkc/ml_kem.js +15 -21
  407. package/src/crypto/pkc/rsa.acvp.md +11 -15
  408. package/src/crypto/pkc/rsa.js +7 -44
  409. package/src/crypto/pkc/slh_dsa.acvp.md +16 -16
  410. package/src/crypto/pkc/slh_dsa.js +16 -18
  411. package/src/crypto/pkc/x25519.acvp.md +13 -10
  412. package/src/crypto/pkc/x25519.js +273 -29
  413. package/src/crypto/utils/aes_modes.acvp.md +1 -2
  414. package/src/crypto/utils/aes_modes.js +2 -2
  415. package/src/crypto/utils/asn1-oid.js +1 -1
  416. package/src/crypto/utils/asn1.js +1 -1
  417. package/src/crypto/utils/bitArray.js +33 -48
  418. package/src/crypto/utils/bn.js +1 -1
  419. package/src/crypto/utils/jws.js +37 -41
  420. package/src/crypto/utils/keyformat.js +181 -2
  421. package/src/crypto/utils/pem.js +1 -1
  422. package/src/crypto/utils/random.acvp.md +5 -5
  423. package/src/crypto/utils/random.js +845 -846
  424. package/src/crypto/utils/rsaKeygen.acvp.md +3 -2
  425. package/src/crypto/utils/rsaKeygen.js +6 -6
  426. package/src/crypto/utils/totp.js +1 -1
  427. package/src/crypto/utils/uuid.acvp.md +5 -5
  428. package/src/crypto/utils/uuid.js +11 -10
  429. package/src/crypto/utils/x509.js +591 -0
  430. package/src/crypto/wasm/aes.js +1 -1
  431. package/src/crypto/wasm/aes.scalar.wasm +0 -0
  432. package/src/crypto/wasm/argon2.js +17 -1
  433. package/src/crypto/wasm/argon2.scalar.wasm +0 -0
  434. package/src/crypto/wasm/blake2b.scalar.wasm +0 -0
  435. package/src/crypto/wasm/blake2b.simd.wasm +0 -0
  436. package/src/crypto/wasm/chacha20poly1305.scalar.wasm +0 -0
  437. package/src/crypto/wasm/chacha20poly1305.simd.wasm +0 -0
  438. package/src/crypto/wasm/cmac.scalar.wasm +0 -0
  439. package/src/crypto/wasm/ecc.js +3 -3
  440. package/src/crypto/wasm/ecc.scalar.wasm +0 -0
  441. package/src/crypto/wasm/ed25519.js +1 -1
  442. package/src/crypto/wasm/ed25519.scalar.wasm +0 -0
  443. package/src/crypto/wasm/hkdf.scalar.wasm +0 -0
  444. package/src/crypto/wasm/hmac.scalar.wasm +0 -0
  445. package/src/crypto/wasm/ml_dsa.js +2 -2
  446. package/src/crypto/wasm/ml_dsa.scalar.wasm +0 -0
  447. package/src/crypto/wasm/ml_dsa.simd.wasm +0 -0
  448. package/src/crypto/wasm/ml_kem.js +2 -2
  449. package/src/crypto/wasm/ml_kem.scalar.wasm +0 -0
  450. package/src/crypto/wasm/ml_kem.simd.wasm +0 -0
  451. package/src/crypto/wasm/pbkdf2.js +8 -6
  452. package/src/crypto/wasm/pbkdf2.scalar.wasm +0 -0
  453. package/src/crypto/wasm/rsa.js +6 -5
  454. package/src/crypto/wasm/rsa.scalar.wasm +0 -0
  455. package/src/crypto/wasm/runtime.js +84 -17
  456. package/src/crypto/wasm/sha2.scalar.wasm +0 -0
  457. package/src/crypto/wasm/sha3.scalar.wasm +0 -0
  458. package/src/crypto/wasm/sha3.simd.wasm +0 -0
  459. package/src/crypto/wasm/slh_dsa.js +1 -1
  460. package/src/crypto/wasm/slh_dsa.scalar.wasm +0 -0
  461. package/src/crypto/wasm/x25519.js +1 -1
  462. package/src/crypto/wasm/x25519.scalar.wasm +0 -0
  463. package/src/crypto/webcrypto/aes.js +8 -2
  464. package/src/crypto/webcrypto/aeskw.js +7 -2
  465. package/src/crypto/webcrypto/digest.js +1 -15
  466. package/src/crypto/webcrypto/ecc.js +2 -2
  467. package/src/crypto/webcrypto/ed25519.js +2 -2
  468. package/src/crypto/webcrypto/hmac.js +2 -2
  469. package/src/crypto/webcrypto/rsa.js +7 -2
  470. package/src/crypto/webcrypto/x25519.js +2 -2
  471. package/src/dom/display/animate.js +1 -1
  472. package/src/dom/display/fullscreen.js +1 -1
  473. package/src/dom/fs/download.js +1 -1
  474. package/src/dom/fs/fileIntake.js +192 -0
  475. package/src/dom/fs/fsAccess.js +2 -3
  476. package/src/dom/fs/indexedDB.js +1 -1
  477. package/src/dom/fs/remoteStore.js +1 -1
  478. package/src/dom/fs/storage.js +1 -1
  479. package/src/dom/lifecycle/idle.js +1 -1
  480. package/src/dom/lifecycle/visibility.js +1 -1
  481. package/src/dom/lifecycle/wakeLock.js +1 -1
  482. package/src/dom/net/ajax.js +1 -1
  483. package/src/dom/net/network.js +1 -1
  484. package/src/dom/net/sse.js +1 -1
  485. package/src/dom/net/webrtc.js +1 -1
  486. package/src/dom/net/ws.js +1 -1
  487. package/src/dom/query/dnd.js +56 -4
  488. package/src/dom/query/dom.js +1 -1
  489. package/src/dom/query/events.js +1 -1
  490. package/src/dom/query/gesture.js +1 -1
  491. package/src/dom/query/media.js +1 -1
  492. package/src/dom/query/sound.js +333 -0
  493. package/src/dom/rendering/chart.js +736 -663
  494. package/src/dom/rendering/component.js +25 -14
  495. package/src/dom/rendering/devtools.js +2 -2
  496. package/src/dom/rendering/parser.js +155 -12
  497. package/src/dom/rendering/render.js +14 -4
  498. package/src/dom/rendering/sanitize.js +11 -4
  499. package/src/dom/rendering/secPolicy.js +6 -4
  500. package/src/dom/rendering/styleSheet.js +217 -0
  501. package/src/dom/rendering/template.js +72 -13
  502. package/src/dom/rendering/themeTokens.js +542 -522
  503. package/src/dom/rendering/uiSession-core.js +51 -6
  504. package/src/dom/rendering/uiSession-direct.js +1 -1
  505. package/src/dom/rendering/uiSession-list.js +4 -4
  506. package/src/dom/rendering/uiSession.js +1 -1
  507. package/src/dom/rendering/virtualScroll.js +341 -341
  508. package/src/dom/sensors/battery.js +1 -1
  509. package/src/dom/sensors/geolocation.js +1 -1
  510. package/src/dom/sensors/networkInfo.js +1 -1
  511. package/src/dom/sensors/sensors.js +1 -1
  512. package/src/dom/sw/backgroundSync.js +1 -1
  513. package/src/dom/sw/cache.js +1 -1
  514. package/src/dom/sw/installPrompt.js +151 -0
  515. package/src/dom/sw/precache.js +257 -0
  516. package/src/dom/sw/push.js +1 -1
  517. package/src/dom/sw/sharedWorker.js +1 -1
  518. package/src/dom/sw/swUpdate.js +239 -0
  519. package/src/dom/utils/a11y.js +1 -1
  520. package/src/dom/utils/clipboard.js +56 -6
  521. package/src/dom/utils/entropyCollector.js +1 -1
  522. package/src/dom/utils/focus.js +1 -1
  523. package/src/dom/utils/form.js +1 -1
  524. package/src/dom/utils/keybindings.js +600 -574
  525. package/src/dom/utils/leaderElection.js +1 -1
  526. package/src/dom/utils/notifications.js +1 -1
  527. package/src/dom/utils/permissions.js +107 -107
  528. package/src/dom/utils/route.js +14 -2
  529. package/src/dom/utils/ua.js +42 -28
  530. package/src/dom/utils/webauthn.js +1 -1
  531. package/src/io/binary/reader.js +1 -1
  532. package/src/io/binary/writer.js +1 -1
  533. package/src/io/calc/bigint.js +1 -1
  534. package/src/io/calc/crc32.js +28 -2
  535. package/src/io/calc/easing.js +514 -514
  536. package/src/io/codec/b64.js +189 -52
  537. package/src/io/codec/base32.js +1 -1
  538. package/src/io/codec/base58.js +1 -1
  539. package/src/io/codec/buffer.js +1 -1
  540. package/src/io/codec/cbor.js +111 -18
  541. package/src/io/codec/csv.js +1 -1
  542. package/src/io/codec/hex.js +51 -6
  543. package/src/io/codec/mime.js +1 -1
  544. package/src/io/codec/msgpack.js +47 -6
  545. package/src/io/codec/url.js +24 -7
  546. package/src/io/codec/utf8.js +5 -3
  547. package/src/io/codec/xml.js +1 -1
  548. package/src/io/compress/bitstream.js +2 -2
  549. package/src/io/compress/brotli.js +663 -163
  550. package/src/io/compress/brotli_dict.js +1 -1
  551. package/src/io/compress/brotli_dict_words.js +1 -1
  552. package/src/io/compress/brotli_frame.js +1 -1
  553. package/src/io/compress/brotli_shared.js +7 -7
  554. package/src/io/compress/deflate.js +87 -53
  555. package/src/io/compress/gzip.js +187 -74
  556. package/src/io/compress/huffman.js +24 -1
  557. package/src/io/compress/lz4.js +45 -7
  558. package/src/io/compress/lz77.js +148 -63
  559. package/src/io/compress/lzw.js +35 -19
  560. package/src/io/compress/zip.js +862 -815
  561. package/src/io/compress/zlib.js +87 -7
  562. package/src/io/i18n/i18n.js +1 -1
  563. package/src/io/math/fixed-point.js +1 -1
  564. package/src/io/math/geom.js +1 -1
  565. package/src/io/math/interp.js +1 -1
  566. package/src/io/math/linalg.js +10 -4
  567. package/src/io/math/stats.js +1 -1
  568. package/src/io/structures/btree.js +1 -1
  569. package/src/io/structures/heap.js +1 -1
  570. package/src/io/structures/lruCache.js +1 -1
  571. package/src/io/structures/ringBuffer.js +1 -1
  572. package/src/io/structures/tree-walker.js +1 -1
  573. package/src/io/structures/trie.js +1 -1
  574. package/src/io/sync/abort.js +1 -1
  575. package/src/io/sync/atomics.js +1 -1
  576. package/src/io/sync/cancellable.js +1 -1
  577. package/src/io/sync/channel.js +1 -1
  578. package/src/io/sync/mutex.js +1 -1
  579. package/src/io/sync/semaphore.js +1 -1
  580. package/src/io/sync/tokenBucket.js +1 -1
  581. package/src/io/text/ansi.js +1 -1
  582. package/src/io/text/html-entities.js +1 -1
  583. package/src/io/time/date.js +1 -1
  584. package/src/io/timing/clock.js +1 -1
  585. package/src/io/timing/rateLimit.js +1 -1
  586. package/src/io/timing/scheduler.js +1 -1
  587. package/src/io/utils/errors.js +1 -1
  588. package/src/io/utils/eventBus.js +1 -1
  589. package/src/io/utils/signal.js +1 -1
  590. package/src/io/utils/valid.js +1 -1
  591. package/src/main.js +1 -1
  592. package/src/process/message.js +1 -1
  593. package/src/process/rpc.js +7 -3
  594. package/src/process/workerPool.js +11 -4
  595. package/src/sanity/base.js +85 -39
  596. package/src/sanity/lockdown-apply.js +3 -3
  597. package/src/sanity/lockdown.js +58 -32
  598. package/src/sanity/wasm-gate.js +2 -2
  599. package/src/typed.js +7 -3
  600. package/third-party/NOTICE-brotli-dictionary.txt +69 -0
  601. package/third-party/NOTICE-fw-wasm-crypto.txt +576 -0
  602. package/third-party/NOTICE-whatwg-entities.txt +44 -0
  603. package/types/registry.generated.d.ts +7 -1
  604. package/types/typed.d.ts +7 -3
  605. package/dist/types/crypto/utils/aes_ctr.d.ts +0 -84
  606. package/dist/types/crypto/utils/aes_ctr.d.ts.map +0 -1
  607. package/docs/api/crypto/utils/aes_ctr.md +0 -71
  608. package/src/crypto/utils/aes_ctr.acvp.md +0 -67
  609. package/src/crypto/utils/aes_ctr.js +0 -134
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: component
3
3
  category: dom/rendering
4
- dependencies: [reactiveBind]
4
+ dependencies: [reactiveBind, styleSheet]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -11,7 +11,7 @@ status: complete
11
11
 
12
12
  > Reusable component primitive on top of `uiSession`. Encapsulates template + state + lifecycle + automatic cleanup.
13
13
 
14
- **Module** `component` | **Source** `packages/front/fw/src/dom/rendering/component.js` | **Deps** none | **Worker-safe** no
14
+ **Module** `component` | **Source** `packages/front/fw/src/dom/rendering/component.js` | **Deps** `reactiveBind`, `styleSheet` | **Worker-safe** no
15
15
 
16
16
  ## Resolve
17
17
 
@@ -229,9 +229,30 @@ automatically:
229
229
  .fw-comp-7 .icon { animation: fw-comp-7-spin 1s linear infinite; }
230
230
  ```
231
231
 
232
+ ### Id selectors do not match
233
+
234
+ The rendered ids are not the authored ones: each node gets a fresh runtime
235
+ id when the template is rendered, so a scoped `& #label { … }` rule is
236
+ injected as `.fw-comp-7 #label` and matches nothing. Select by class or
237
+ attribute instead:
238
+
239
+ ```css
240
+ /* authored template: <span class="label">…</span> */
241
+ & .label { font-weight: bold; }
242
+ ```
243
+
232
244
  Injection remains **once per blueprint** — multiple instances of the same
233
245
  component share the single `<style data-fw-component="fw-comp-N">` tag in
234
- `<head>`.
246
+ `<head>` in the default mode.
247
+
248
+ ### Under a strict CSP
249
+
250
+ The CSS is attached through the [`styleSheet`](./styleSheet.md) module. With a
251
+ `style-src 'self'` policy (no `'unsafe-inline'`, no nonce) an inline `<style>`
252
+ is refused: call `runtime.resolve('styleSheet').mode('adopted')` **before the
253
+ first `define`**. The scoped CSS is then attached as one constructable
254
+ stylesheet per blueprint and no `<style>` element is created. A factory wired
255
+ by hand without the `styleSheet` argument keeps the `<style>` element path.
235
256
 
236
257
  ## Reactive bindings (`self.bind`)
237
258
 
@@ -284,4 +305,5 @@ See [reactiveBind](./reactiveBind.md) for the full controller API
284
305
  - [uiSession](./uiSession.md) — underlying session layer.
285
306
  - [reactiveBind](./reactiveBind.md) — signal-to-DOM binding controller used by `self.bind`.
286
307
  - [parser](./parser.md) — produces `ParseResult` templates.
308
+ - [styleSheet](./styleSheet.md) — attaches the scoped CSS (`<style>` element or constructable stylesheet).
287
309
  - [Guide rendering-pipeline](../../../guide/rendering-pipeline.md).
@@ -1,4 +1,4 @@
1
- ---
1
+ ---
2
2
  module: parser
3
3
  category: dom/rendering
4
4
  dependencies: [secPolicy]
@@ -30,12 +30,14 @@ const parser = runtime.resolve('parser');
30
30
  |---------|-----------|-------------|
31
31
  | `fromHTML` | `(html: string, options?: FromHTMLOptions) => ParseResult` | HTML → elm-array + iterates |
32
32
  | `toHTML` | `(input: ElmNode[]\|ParseResult) => string` | elm-array → HTML (reverse) |
33
+ | `createCache` | `(opts?: { max?: number }) => SharedParseCache` | A parse cache several instances share through `fromHTML(html, { cache })` (`size()`, `clear()`, `stats()`; `max` defaults to 64, `0` disables it) |
33
34
 
34
35
  ### Typedef: FromHTMLOptions
35
36
 
36
37
  | Field | Type | Description |
37
38
  |---|---|---|
38
39
  | `reserveIds` | `Iterable<string>` | Explicit ids the caller knows the assembled document will contain, declared **up front**. Reserved for the whole parser instance — this call and every later one — so an auto `p<n>` never collides with an explicit id the instance has not met yet. Empty and non-string entries are ignored. Supplying the option **bypasses the `ParseResult` cache** (read *and* write), because the reservation changes which ids are minted. |
40
+ | `cache` | `SharedParseCache` | A cache from `createCache`, used **instead of** this instance's own. It is **transparent**: a hit returns exactly what a fresh parse on this instance would — the document's explicit ids join the instance's reserved set and every auto `p<n>` is minted by this instance's counter, in the original order — so instances with different histories (one per route of a site build) share it without an id collision. Only the parse itself is saved. |
39
41
 
40
42
  ### `parser.fromHTML(html)`
41
43
 
@@ -185,8 +187,9 @@ const page = parser.toHTML([...head.template, ...body.template]);
185
187
 
186
188
  ## Notes
187
189
 
190
+ - **Cache.** Identical input strings are parsed once per instance (`cache.stats()`, `cache.setMax(n)`, `cache.clear()`). Every call returns its own deep copy of the cached `ParseResult`, hit or miss: mutating a result never reaches the cache or another caller, and two calls never return the same object. A hit of this per-instance cache returns the ids of the first parse; a shared cache (`createCache`) re-mints them instead, see `FromHTMLOptions.cache`.
188
191
  - SVG children: `svg_` prefix (e.g. `svg_use`, `svg_rect`, `svg_path`).
189
- - Mixed text nodes: synthetic tag `"text"`.
192
+ - Mixed text nodes: synthetic tag `"text"`. A text node keeps the boundary space on the side of an inline sibling (`or <b>this</b>` keeps `"or "`); whitespace beside block elements or at the parent's edges is dropped, and so is a whitespace-only node, even between two inline elements (a synthetic text node renders as a `<span>`: put such a space inside an element, or write `&#32;`). A leaf's sole text is trimmed.
190
193
  - HTML ids are preserved in `elm.id`; otherwise auto-incremented (`p0`, `p1`, ...).
191
194
  - The auto counter is scoped to the parser **instance** and keeps running across `fromHTML` calls, so a site build that shares one parser gets stable, non-repeating ids. Within a single `fromHTML` call the ids are **guaranteed unique for that document**: a `pN` value already used as an explicit `id` anywhere in the parsed markup is skipped (the whole document is scanned before the first mint, so an explicit id further down the tree counts too). Feeding parser output back through `fromHTML` is therefore safe.
192
195
  - **Multi-call document assembly.** A consumer that builds one logical document from *several* `fromHTML` calls on a shared instance gets the guarantee across that seam too, in two layers. (1) *Accumulation, always on*: every explicit id seen by a call is reserved for the instance, so a later call never re-mints it. (2) *Caller-supplied reservation*: pass the full explicit-id set of the assembled document as `fromHTML(html, { reserveIds })` on the **first** call — this is the only way to cover the opposite direction, an explicit `pN` that only arrives in a *later* call, which accumulation cannot foresee. A reservation is instance-wide and permanent; it applies to every subsequent call with no options. Reservation only affects *future* mints, so it must be declared before the first parse of the assembly. Uniqueness matters because `buildTree` merges nodes by id with last-write-wins: a collision **deletes** a subtree from the assembled output rather than duplicating it.
@@ -231,4 +231,4 @@ comparisons.
231
231
 
232
232
  - [signal](../../io/utils/signal.md) — reactive primitives: `create`, `effect`, `computed`.
233
233
  - [uiSession](./uiSession.md) — the session that `reactiveBind` patches.
234
- - [component](./component.md) — higher-level component system; task 04 will add `self.bind` which wraps `reactiveBind`.
234
+ - [component](./component.md) — higher-level component system; its `self.bind` wraps `reactiveBind`.
@@ -1,4 +1,4 @@
1
- ---
1
+ ---
2
2
  module: render
3
3
  category: dom/rendering
4
4
  dependencies: [secPolicy]
@@ -45,7 +45,7 @@ const render = runtime.resolve('render');
45
45
 
46
46
  | Method | Description |
47
47
  |---------|-------------|
48
- | `toHTML(parseResult, data, opts?)` | Pure function — serialises a `ParseResult` (or elm-array) to final HTML, without the DOM. Default security (URL/clobbering/event filter). Emits `data-fw-id` for future hydration. See the `rendering-pipeline.md` guide for the full signature. |
48
+ | `toHTML(parseResult, data, opts?)` | Pure function — serialises a `ParseResult` (or elm-array) to final HTML, without the DOM. Default security (URL/clobbering/event filter). Emits `data-fw-id` for future hydration, and `data-fw-row="<i>"` on the root(s) of each iterate row. See the `rendering-pipeline.md` guide for the full signature. |
49
49
 
50
50
  #### Attribute value semantics of the SSR writer
51
51
 
@@ -1,4 +1,4 @@
1
- ---
1
+ ---
2
2
  module: sanitize
3
3
  category: dom/rendering
4
4
  dependencies: [secPolicy]
@@ -38,6 +38,7 @@ const sanitizer = runtime.resolve('sanitize');
38
38
  | `allowedAttributes` | `object` | default list | Map `tag → Set<attr>`, key `'*'` for all tags |
39
39
  | `urlSchemes` | `string[]` | `['http','https','mailto','tel','ftp']` | Allowed URL schemes |
40
40
  | `dropDangerousContent` | `boolean` | `true` | Strips the inner content of `<script>`, `<style>`, `<iframe>`, etc. |
41
+ | `allowDataImage` | `boolean` | `false` | Keeps a `data:image/*` URL on `<img src>` only (see Notes) |
41
42
 
42
43
  ## Examples
43
44
 
@@ -61,6 +62,12 @@ s.sanitizeHtml('<custom-tag>x</custom-tag>', {
61
62
  });
62
63
  // → '<custom-tag>x</custom-tag>'
63
64
 
65
+ // Pasted image kept as a data: URL (img src only)
66
+ s.sanitizeHtml('<img src="data:image/png;base64,iVBOR==" alt="x">', { allowDataImage: true });
67
+ // → '<img src="data:image/png;base64,iVBOR==" alt="x" />'
68
+ s.sanitizeHtml('<a href="data:image/png;base64,iVBOR==">x</a>', { allowDataImage: true });
69
+ // → '<a>x</a>'
70
+
64
71
  // URL check
65
72
  s.isSafeUrl('https://example.com'); // true
66
73
  s.isSafeUrl('javascript:alert(1)'); // false
@@ -87,7 +94,8 @@ const worker = fw.createWorker(
87
94
  - Dangerous tags (`<script>`, `<iframe>`, `<style>`, `<svg>`, `<math>`, etc.) have their entire content stripped (not just the wrapper tag), preventing bypasses via incomplete tags.
88
95
  - Event handlers (`on*`) and risky attributes (`style`, `srcdoc`, `formaction`) are stripped unconditionally, even if the parent tag is in the allowlist.
89
96
  - External links (`https://`, `http://`) with `target="_blank"` (or any other named target) automatically receive `rel="noopener noreferrer"`. In-place links (without `target` or `target="_self"`) do **not** receive this `rel` — the `window.opener` relationship only exists for new navigation contexts.
90
- - `javascript:`, `vbscript:`, and `data:text/html` URLs are blocked in `href` and `src`; image data-URIs are only allowed if `allowDataImage: true` is passed to `isSafeUrl`.
97
+ - `javascript:`, `vbscript:`, and `data:text/html` URLs are blocked in `href` and `src`.
98
+ - **`data:` images** — by default every `data:` URL is dropped. `sanitizeHtml(html, { allowDataImage: true })` keeps a `data:image/*` URL (the [`secPolicy.DATA_IMAGE_RE`](./secPolicy.md) types: png, jpeg, gif, webp, svg+xml, bmp, ico, avif, apng) **on `<img src>` only** — an image element runs no script. `href` never accepts `data:` (a navigable `data:` link is an injection vector), no other element's `src` does either (even when a custom allowlist lets `iframe`, `embed`, `source`… through), and non-image `data:` URLs (`data:text/html`, `data:application/…`) are dropped with or without the option. Mixed-case and whitespace/control-obfuscated forms are judged like the canonical form. The standalone `isSafeUrl(url, schemes, true)` stays the element-agnostic predicate.
91
99
  - This sanitiser is a defence-in-depth layer suited to Markdown → HTML, docx → HTML pipelines, etc. For stricter requirements (arbitrary HTML from untrusted users), combine with server-side validation.
92
100
 
93
101
  ## See also
@@ -1,4 +1,4 @@
1
- ---
1
+ ---
2
2
  module: secPolicy
3
3
  category: dom/rendering
4
4
  dependencies: []
@@ -52,15 +52,15 @@ The returned object exposes **constants** (Sets, RegExp) and **pure functions**
52
52
  | `URL_ATTRS` | `Set<string>` | URL-bearing attributes: `href`, `src`, `action`, `formaction`, `srcset`, `xlink:href`, `data`, `codebase` |
53
53
  | `SCHEME_DANGEROUS_RE` | `RegExp` | Categorically refused schemes: `javascript:`, `vbscript:`, `file:`, `jar:`, `data:text`, `data:application` |
54
54
  | `SAFE_SCHEMES` | `Set<string>` | Default allowed schemes: `http`, `https`, `mailto`, `tel`, `ftp` |
55
- | `DATA_IMAGE_RE` | `RegExp` | Accepted `data:image/*` MIMEs when `allowDataImage=true` |
56
- | `isSafeUrl(url, schemes?, allowDataImage?)` | function | Decides whether `url` can be set on a URL-bearing attribute |
55
+ | `DATA_IMAGE_RE` | `RegExp` | Accepted `data:image/*` MIMEs (png, jpeg, gif, webp, svg+xml, bmp, ico, avif, apng), followed by a parameter (`;base64`, `;utf8`) or directly by the data (`,`) — both RFC 2397 forms |
56
+ | `isSafeUrl(url, schemes?, allowDataImage?)` | function | Decides whether `url` can be set on a URL-bearing attribute. `schemes` is an array or a `Set` of lowercase scheme names (no colon) that replaces `SAFE_SCHEMES`; `allowDataImage` defaults to `true` (only an explicit `false` refuses `data:image`) |
57
57
 
58
58
  `isSafeUrl` applies in order:
59
59
  1. Non-string → unsafe
60
60
  2. Empty (after stripping control chars) → safe
61
61
  3. Starts with `#`, `/`, `?`, `.` → safe (anchor / relative)
62
62
  4. Matches `SCHEME_DANGEROUS_RE` → unsafe
63
- 5. `data:` → safe **only** if `allowDataImage` AND matches `DATA_IMAGE_RE`
63
+ 5. `data:` → safe **only** if `allowDataImage` is not `false` AND the URL matches `DATA_IMAGE_RE`
64
64
  6. No `:` → safe (relative)
65
65
  7. `:` after a `/` → safe (path containing `:`)
66
66
  8. Scheme in `schemes` (or `SAFE_SCHEMES` by default)
@@ -0,0 +1,85 @@
1
+ ---
2
+ module: styleSheet
3
+ category: dom/rendering
4
+ dependencies: []
5
+ returns: object
6
+ worker-safe: false
7
+ status: complete
8
+ ---
9
+
10
+ # styleSheet
11
+
12
+ > Attach CSS text to a document as a style element or a constructable stylesheet.
13
+
14
+ **Module** `styleSheet` | **Source** `packages/front/fw/src/dom/rendering/styleSheet.js` | **Deps** none | **Worker-safe** no
15
+
16
+ Owns one job: put this CSS text into that document. Two channels exist: a `<style>` element (mode `'element'`, the default) and a constructable stylesheet appended to `document.adoptedStyleSheets` (mode `'adopted'`), which a CSP `style-src` without `'unsafe-inline'` and without a nonce does not refuse. The consumer chooses the mode; the module never detects a CSP and never retries another channel.
17
+
18
+ ## Resolve
19
+
20
+ ```js
21
+ const styleSheet = runtime.resolve('styleSheet');
22
+ // Returns: { support, mode, attach }
23
+ ```
24
+
25
+ ## API
26
+
27
+ | Method | Signature | Returns |
28
+ |--------|-----------|---------|
29
+ | `support` | `() => { constructable: boolean }` | Whether constructable stylesheets are available right now (evaluated at each call) |
30
+ | `mode` | `() => 'element' \| 'adopted'` | Current default mode of this instance |
31
+ | `mode` | `(value: 'element' \| 'adopted') => void` | Sets the default mode (later `attach()` calls only); other values throw `TypeError("styleSheet: unknown mode '<value>'")` |
32
+ | `attach` | `(css: string, opts?: StyleAttachOptions) => StyleHandle` | Attaches the CSS; non-string `css` throws `TypeError('styleSheet: css must be a string')` |
33
+
34
+ `StyleAttachOptions`:
35
+
36
+ | Option | Type | Meaning |
37
+ |--------|------|---------|
38
+ | `mode` | `'element' \| 'adopted'` | Per-call override of the instance mode |
39
+ | `head` | `Element` | Element receiving the `<style>` (default `document.head`); its `ownerDocument` is the target document |
40
+ | `id` | `string` | Element mode sets `el.id`; kept on the handle in both modes |
41
+ | `attrs` | `Record<string, string>` | Own keys set with `setAttribute` (element mode only) |
42
+ | `nonce` | `string` | CSP nonce, `''` means none; `undefined` uses the default read from `<meta name="csp-nonce">` at factory time (element mode only) |
43
+
44
+ `StyleHandle`:
45
+
46
+ | Member | Type | Meaning |
47
+ |--------|------|---------|
48
+ | `mode` | `'element' \| 'adopted' \| 'none'` | Channel that actually ran (`'none'` = inert, no document) |
49
+ | `id` | `string \| null` | The `opts.id`, if any |
50
+ | `element` | `HTMLStyleElement \| null` | The `<style>` (element mode) |
51
+ | `sheet` | `CSSStyleSheet \| null` | The constructed sheet (adopted mode) |
52
+ | `set(css)` | `(css: string) => void` | Replaces the text; element mode re-appends a removed element; no-op after `detach()` |
53
+ | `detach()` | `() => void` | Removes the style; idempotent |
54
+
55
+ ## Examples
56
+
57
+ ```js
58
+ const styleSheet = runtime.resolve('styleSheet');
59
+
60
+ // Default: a <style> element in document.head.
61
+ const h = styleSheet.attach('.card { color: red }', { id: 'card-css' });
62
+ h.set('.card { color: blue }');
63
+ h.detach();
64
+
65
+ // Under a CSP `style-src 'self'`: use a constructable stylesheet.
66
+ styleSheet.mode('adopted');
67
+ const a = styleSheet.attach('.badge { padding: 4px }');
68
+ console.log(a.mode); // 'adopted' (or 'element' on a platform without the API)
69
+ a.detach();
70
+ ```
71
+
72
+ ## Notes
73
+
74
+ - The default mode is `'element'`, so resolving the module changes nothing for an existing page; `'adopted'` is opt-in.
75
+ - Choose `'adopted'` when the CSP `style-src` has neither `'unsafe-inline'` nor a nonce: a `<style>` element would be refused, a constructable stylesheet is not.
76
+ - Where constructable stylesheets are missing (no `adoptedStyleSheets`, `CSSStyleSheet` or `replaceSync` on the target document's own realm), an `'adopted'` request falls back to the element channel; `handle.mode` tells which ran.
77
+ - Cascade order: adopted sheets come after the document's own sheets, so a rule of equal specificity wins where a `<style>` in `<head>` might not.
78
+ - A constructed sheet ignores `@import` rules (platform rule).
79
+ - The mode lives in factory scope: one per runtime container, not shared between instances. Not worker-safe: without a `document`, `attach` returns an inert handle (`mode: 'none'`).
80
+
81
+ ## See also
82
+
83
+ [component](./component.md) — scoped component CSS injection
84
+ [template](./template.md) — template CSS injection
85
+ [themeTokens](./themeTokens.md) — design-token `<style>` management
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: template
3
3
  category: dom/rendering
4
- dependencies: [secPolicy]
4
+ dependencies: [secPolicy, styleSheet]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -11,7 +11,7 @@ status: complete
11
11
 
12
12
  > DOM engine: materialises elm-arrays into DOM nodes. Manages named contexts and a `<template>` catalogue as cloning sources.
13
13
 
14
- **Module** `template` | **Source** `packages/front/fw/src/dom/rendering/template.js` | **Deps** `secPolicy` | **Worker-safe** no
14
+ **Module** `template` | **Source** `packages/front/fw/src/dom/rendering/template.js` | **Deps** `secPolicy`, `styleSheet` | **Worker-safe** no
15
15
 
16
16
  > **Security**: `applyAttributes` rejects dangerous URLs on `href`/`src`/`action`/…, DOM-clobbering values on `id`/`name`, and `on*` attributes. The shared policy lives in [`secPolicy`](./secPolicy.md).
17
17
 
@@ -39,7 +39,7 @@ const tpl = runtime.resolve('template');
39
39
  | `clearElm` | `(name, id) => void` | Removes an element and its children |
40
40
  | `clearIn` | `(name, id) => void` | Removes children (keeps the element) |
41
41
  | `clearAll` | `(name) => void` | Clears the entire context |
42
- | `clearContext` | `(name) => void` | Destroys the context (DOM + map + catalogue) |
42
+ | `clearContext` | `(name) => void` | Destroys the context (DOM + map + catalogue); a page context keeps `body`, empties it and removes its own `<style>` / `<script>` |
43
43
  | `style` | `(name, id, styles) => void` | Injects `<style>` into `<head>` (page contexts) |
44
44
  | `script` | `(name, id, content) => void` | Injects `<script>` into `<head>` (page contexts) |
45
45
 
@@ -218,7 +218,7 @@ Returns: `string[]` — names added (existing entries are overwritten).
218
218
  | `tpl.clearElm(name, id)` | Removes an element and its children from the DOM and the `map` |
219
219
  | `tpl.clearIn(name, id)` | Removes the **children** of an element (keeps the element) |
220
220
  | `tpl.clearAll(name)` | Clears the entire context |
221
- | `tpl.clearContext(name)` | Destroys the context (DOM + map + catalogue if needed) |
221
+ | `tpl.clearContext(name)` | Destroys the context (DOM + map + catalogue if needed). A **page** context renders into `document.body`, which stays in the document: its children are cleared and the `<style>` / `<script>` elements the context injected are removed |
222
222
 
223
223
  ---
224
224
 
@@ -229,8 +229,20 @@ Injection into `<head>` (page contexts only).
229
229
  ```js
230
230
  tpl.style('page', 'myStyle', 'body { background: #eee; }');
231
231
  tpl.script('page', 'myScript', 'console.log("loaded")');
232
+ tpl.removeStyle('page', 'myStyle');
232
233
  ```
233
234
 
235
+ `style` goes through the [`styleSheet`](./styleSheet.md) module. By default it
236
+ inserts (or updates in place) a `<style id>` element in the context's `<head>`,
237
+ with the CSP nonce from `setNonce` or the `<meta name="csp-nonce">` tag.
238
+ Under a strict CSP (`style-src 'self'`, no `'unsafe-inline'`, no nonce) call
239
+ `runtime.resolve('styleSheet').mode('adopted')` before the first `style`: each
240
+ id then becomes one constructable stylesheet (a second `style` with the same id
241
+ replaces its text) and no `<style>` element is created. `removeStyle` and
242
+ `clearContext` detach exactly the styles their context added, in either mode.
243
+ A factory wired by hand without the `styleSheet` argument keeps the `<style>`
244
+ element path. `script` is unchanged.
245
+
234
246
  ### Default tags (auto-generated catalogue)
235
247
 
236
248
  When no `tpl` is provided to `init`, the catalogue contains the common semantic HTML5 tags:
@@ -245,7 +257,9 @@ When no `tpl` is provided to `init`, the catalogue contains the common semantic
245
257
  - **Media**: `video`, `audio`, `picture`, `img`, `figure`, `figcaption`
246
258
  - **Canvas / SVG**: `cvs` (canvas), `svg`, `svg_use`
247
259
 
248
- To add other tags, either pass a `tpl: [...]` array to `init`, or call `tpl.registerTags([...])` after init.
260
+ A tag outside the catalogue (`output`, a custom element such as `my-widget`, …) is created with `document.createElement` (an `svg_<name>` tag with `createElementNS` in the SVG namespace) and rendered like any other. Two kinds are never rendered: the blocked tags (`script`, `object`, `embed`, `iframe`, see [`secPolicy`](./secPolicy.md)) and names that are not valid element names; their children, if any, are placed on the context root. Register a tag (`tpl: [...]` at `init`, or `tpl.registerTags([...])` after it) to give it preset attributes or an SVG wrapper.
261
+
262
+ `tpl.elm(name, node)` never writes into `node`: an id-less node gets a generated id on an internal copy.
249
263
 
250
264
  ### Conditional attributes
251
265
 
@@ -296,6 +310,7 @@ tpl.clearElm('app', 'content');
296
310
 
297
311
  ## See also
298
312
 
313
+ - [styleSheet](./styleSheet.md) — the channel behind `tpl.style` / `tpl.removeStyle`
299
314
  - [render](./render.md) — produces elm-arrays for `tpl.elms`
300
315
  - [parser](./parser.md) — produces elm-arrays via `fromHTML`
301
316
  - [uiSession](./uiSession.md) — facade that wraps `template` + `render` + `parser`
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: themeTokens
3
3
  category: dom/rendering
4
- dependencies: [dom]
4
+ dependencies: [dom, styleSheet]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -11,7 +11,7 @@ status: complete
11
11
 
12
12
  > CSS design-token manager — definition, variants, light/dark/a11y modes.
13
13
 
14
- **Module** `themeTokens` | **Source** `packages/front/fw/src/dom/rendering/themeTokens.js` | **Deps** `dom` | **Worker-safe** no
14
+ **Module** `themeTokens` | **Source** `packages/front/fw/src/dom/rendering/themeTokens.js` | **Deps** `dom`, `styleSheet` | **Worker-safe** no
15
15
 
16
16
  Manages the application's CSS Custom Properties via dedicated `<style>` elements per instance (no conflict between multiple instances).
17
17
  Supports tokens as scalar values or mode variants (`light`, `dark`, `highContrast`, `reducedMotion`),
@@ -162,7 +162,9 @@ theme.dispose(); // removes the <style>, detaches all MQ listeners
162
162
 
163
163
  ## Notes
164
164
 
165
- - A single `<style id="data-fw-theme-tokens">` element is created in `<head>`; successive calls to `define()` or `mode()` rewrite its entire content.
165
+ - Each instance creates one `<style id="data-fw-theme-tokens-N">` element in `<head>` (through [`styleSheet`](./styleSheet.md)); successive calls to `define()` or `mode()` rewrite its entire content.
166
+ - The element carries the page's `<meta name="csp-nonce">` nonce when there is one (read when the factory runs). Before it carried none, so a nonce-based CSP refused the tokens.
167
+ - Under a strict CSP (`style-src 'self'`, no `'unsafe-inline'`, no nonce) call `runtime.resolve('styleSheet').mode('adopted')` before the first `create()`: each instance then uses one constructable stylesheet and there is no `<style id="data-fw-theme-tokens-N">` element; `dispose()` removes that sheet and only it. `get()` still reads computed values from the scope element. A factory wired by hand without the `styleSheet` argument keeps the element path (no nonce).
166
168
  - The fallback cascade for `highContrast` without an explicit variant is: `highContrast` → `dark` → `light` → `default`.
167
169
  - `forced-colors: active` (Windows High Contrast) is detected and automatically forces `resolved: 'high-contrast'`, regardless of the configured mode.
168
170
  - Listeners passed to `onChange` are called on **every** `mode()` call, even if the resolved mode does not change (the caller's explicit intent is honoured).
@@ -171,5 +173,6 @@ theme.dispose(); // removes the <style>, detaches all MQ listeners
171
173
  ## See also
172
174
 
173
175
  - [dom](../query/dom.md) — low-level DOM manipulation
176
+ - [styleSheet](./styleSheet.md) — attaches the token CSS (`<style>` element or constructable stylesheet)
174
177
  - [template](./template.md) — elm-array → DOM render engine
175
178
  - [uiSession](./uiSession.md) — high-level facade
@@ -31,7 +31,7 @@ const ui = uiSession('myContext');
31
31
 
32
32
  ```js
33
33
  const tpl = runtime.resolve('template');
34
- tpl.init('content', { to: '#app' });
34
+ tpl.init('content', { to: '#app', main: true }); // main: the shared tag catalogue
35
35
 
36
36
  const ui = uiSession('content');
37
37
  ```
@@ -88,7 +88,7 @@ Alias for `add` — semantically explicit for appending.
88
88
 
89
89
  ### `ui.prepend(items[])` → this
90
90
 
91
- Inserts blocks **before** existing content.
91
+ Inserts blocks **before** existing content — before the first existing child of each item's target (the session container, or the slot of an `attach`). Several prepended items keep their order: `ui.prepend([a, b])` gives `a, b, …existing`. `ui.add([{ …, prepend: true }])` does the same for that item.
92
92
 
93
93
  ```js
94
94
  ui.prepend([{ id: 'banner', block: b, data: { msg: 'Header' } }]);
@@ -120,6 +120,7 @@ ui.hydrate(
120
120
  - All subsequent operations (`ui.text/attr/on/list/clear/remove/...`) work normally.
121
121
  - `ui.clear(blockId)` removes the block from the DOM with its usual cascade.
122
122
  - Throws with an explicit message if an expected `data-fw-id` is missing (template ↔ SSR HTML mismatch).
123
+ - The rows of an SSR iterate block share their `data-fw-id` values and carry `data-fw-row="<i>"` (their index); `ui.list(…).adopt(rows)` takes them over by position.
123
124
 
124
125
  **v1 limitations**:
125
126
  - Iterate blocks (`<!-- $name -->`) are not auto-reconnected to a `ui.list`. The wrapper is adopted, but to react to the array, call `ui.list(parent, slot, …).sync(items)` after hydrate.
@@ -349,9 +350,9 @@ ui.list(parent, slot, {
349
350
  For each `sync(items)` call:
350
351
 
351
352
  1. **Remove**: every key present before and absent after → `ui.clear(itemId)` (releases DOM + managed listeners).
352
- 2. **Add**: every new key → mount at the end (will be reordered in phase 3).
353
+ 2. **Add**: every new key → mount at the end (will be reordered in step 3).
353
354
  3. **Update**: key present and `eqFn(old, new) === false` → `clear+add` of the item block (re-render), unless `onUpdate` is `'patch'`/`'none'`/a custom function — see [Update modes](#update-modes-onupdate). Otherwise, no change.
354
- 4. **Reorder**: `dom.reorder` reorders existing nodes with minimal moves whenever the current key order differs from `newKeys`, **or** whenever phase 3 replaced at least one item (a `'replace'`d row is a fresh DOM node freshly mounted at the slot's end, regardless of its position in the key sequence — the key-sequence diff alone can't see that the row moved). `delta.reordered` reflects whichever condition fired.
355
+ 4. **Reorder**: `dom.reorder` reorders existing nodes with minimal moves whenever the current key order differs from `newKeys`, **or** whenever step 3 replaced at least one item (a `'replace'`d row is a fresh DOM node freshly mounted at the slot's end, regardless of its position in the key sequence — the key-sequence diff alone can't see that the row moved). `delta.reordered` reflects whichever condition fired.
355
356
 
356
357
  `upsert(item)` and `update(key, item)` apply the same rule for a single key: a `'replaced'` outcome from `_replaceItem` restores the row's position via the same reorder pass, even though the key's index in the list didn't change. A `'patched'` or `'unchanged'` outcome never moves the node, so no reorder runs for it.
357
358
 
@@ -468,6 +469,18 @@ Guarantees:
468
469
 
469
470
  For individual **list** items, see `ui.list(parent, slot, { onRemove })` which covers the same need per item.
470
471
 
472
+ ---
473
+
474
+ ### `ui.portal(name, opts?)` → UISession · `ui.closePortal(name)` → this
475
+
476
+ Opens a side session rendered outside the session's container — a modal, a toast, a menu — typically on `document.body` (the default `opts.to`). The portal renders into a host it owns, `<div data-fw-portal="<name>">`, appended to the target: `portal.clear()` empties that host and `ui.closePortal(name)` removes it, so neither ever touches the target or the target's other children. `portal(name)` is idempotent by name; a closed portal reopens as a fresh session with a fresh host. A full `ui.clear()` closes every portal.
477
+
478
+ ```js
479
+ const modal = ui.portal('modal'); // into document.body
480
+ modal.add([{ id: 'dlg', block: dialogTpl, data: { title: 'Save?' } }]);
481
+ ui.closePortal('modal'); // body and the page stay
482
+ ```
483
+
471
484
  ## Examples
472
485
 
473
486
  ### Basic example
@@ -481,7 +494,7 @@ domReady.loaded(() => {
481
494
  const uiSession = runtime.resolve('uiSession');
482
495
  const dom = runtime.resolve('dom');
483
496
 
484
- tpl.init('app', { to: '#root' });
497
+ tpl.init('app', { to: '#root', main: true });
485
498
  const ui = uiSession('app');
486
499
 
487
500
  const b = ui.parse('<div><h1>#{title}</h1><p>#{body}</p></div>');
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: virtualScroll
3
3
  category: dom/rendering
4
- dependencies: [dom, events]
4
+ dependencies: [dom]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -11,7 +11,7 @@ status: complete
11
11
 
12
12
  > Virtualised list — renders only visible items for 10⁴–10⁶ entries.
13
13
 
14
- **Module** `virtualScroll` | **Source** `packages/front/fw/src/dom/rendering/virtualScroll.js` | **Deps** `dom`, `events` | **Worker-safe** no
14
+ **Module** `virtualScroll` | **Source** `packages/front/fw/src/dom/rendering/virtualScroll.js` | **Deps** `dom` | **Worker-safe** no
15
15
 
16
16
  Virtualises the rendering of a long list: only items within the visible window plus a configurable overscan are materialised in the DOM. The rest is represented by a CSS spacer of calculated height, avoiding any memory cost for off-screen nodes.
17
17
 
@@ -83,7 +83,7 @@ const stop = geolocation.watch(pos => {
83
83
  stop();
84
84
  ```
85
85
 
86
- ### Combined with `permissions` (plan 29)
86
+ ### Combined with `permissions`
87
87
 
88
88
  ```js
89
89
  const permissions = runtime.resolve('permissions');
@@ -6,9 +6,12 @@ Service Worker lifecycle + Cache API.
6
6
  |--------|----------|------|-------------|
7
7
  | [backgroundSync](./backgroundSync.md) | `{register, list, support}` | `serviceWorker` | Background Sync API — offline replay via SyncManager (Chrome only) |
8
8
  | [cache](./cache.md) | `{open, delete, has, keys, match}` | none | Cache API wrapper |
9
+ | [installPrompt](./installPrompt.md) | `{install, launchQueue}` | none | PWA install prompt deferral + File Handling launch queue |
10
+ | [precache](./precache.md) | `{create, DEFAULT_MESSAGES}` | `cache` | Worker-side release precache + cache-first / network-first strategies |
11
+ | [push](./push.md) | `{subscribe, unsubscribe, current, permission, support}` | `serviceWorker`, `b64` | PushManager wrapper — VAPID subscription, permission |
9
12
  | [serviceWorker](./serviceWorker.md) | `{register, unregister, ready, update, onUpdate, postMessage, onMessage, controller, isSupported}` | none | SW lifecycle (window-side) |
10
- | [push](./push.md) | `{subscribe, unsubscribe, current, permission, support}` | `serviceWorker`, `b64` | PushManager wrapper — VAPID subscription, subscription, permission |
11
13
  | [sharedWorker](./sharedWorker.md) | `{create, support}` | `processRPC` | SharedWorker cross-tab connection + bidirectional RPC |
14
+ | [swUpdate](./swUpdate.md) | `{create, DEFAULT_MESSAGES}` | `serviceWorker` | Waiting-release update flow: report once, check, apply, version |
12
15
 
13
16
  ## Common pattern
14
17
 
@@ -24,6 +27,9 @@ serviceWorker.onUpdate((reg) => {
24
27
  console.log('New SW waiting:', reg.waiting);
25
28
  });
26
29
 
30
+ // Or the waiting-release flow: report once, apply on the user's word
31
+ const updates = await runtime.resolve('swUpdate').create({ swUrl: '/sw.js', onUpdateReady: showBanner });
32
+
27
33
  // Use the cache
28
34
  const c = await cache.open('v1');
29
35
  await c.put('/api/data', response);
@@ -108,9 +108,10 @@ const worker = fw.createWorker(
108
108
  - The Cache API **has no native expiration** — implement TTL at the application level (e.g. store a timestamp in the key or the response).
109
109
  - `cache.open` is idempotent — repeated calls with the same name return the same instance (native semantics).
110
110
  - Throws `'cache: caches API is not available'` if `globalThis.caches` is absent (very old browser or non-secure context).
111
- - For precomposed offline-first/stale-while-revalidate strategies, this layer should be enriched on the `lib/` side.
111
+ - Precomposed offline strategies are in [`precache`](./precache.md) (worker side: cache-first, network-first, the release precache); `cache` stays the raw Cache Storage layer.
112
112
 
113
113
  ## See also
114
114
 
115
115
  - [serviceWorker](./serviceWorker.md) — SW lifecycle (window-side)
116
+ - [precache](./precache.md) — worker-side release precache with cache-first / network-first strategies
116
117
  - [broadcastChannel](../net/broadcastChannel.md) — SW ↔ clients communication
@@ -0,0 +1,111 @@
1
+ ---
2
+ module: installPrompt
3
+ category: dom/sw
4
+ dependencies: []
5
+ returns: object
6
+ worker-safe: false
7
+ status: complete
8
+ ---
9
+
10
+ # installPrompt
11
+
12
+ > PWA install prompt deferral and File Handling launch queue consumer (page side).
13
+
14
+ **Module** `installPrompt` | **Source** `packages/front/fw/src/dom/sw/installPrompt.js` | **Deps** none | **Worker-safe** no
15
+
16
+ Two feature-detected page helpers for an installable app. `install()` keeps the browser's `beforeinstallprompt` offer until the page prompts it, and follows `appinstalled`. `launchQueue()` hands the files an installed app was opened with (File Handling API) to a callback, as `FileSystemFileHandle`s.
17
+
18
+ ## Resolve
19
+
20
+ ```js
21
+ const installPrompt = runtime.resolve('installPrompt');
22
+ // Returns: { install, launchQueue }
23
+ ```
24
+
25
+ ## API
26
+
27
+ | Method | Signature | Returns |
28
+ |--------|-----------|---------|
29
+ | `install` | `(opts?: InstallOptions) => InstallOffer` | The deferred install offer |
30
+ | `launchQueue` | `(opts: LaunchQueueOptions) => LaunchQueueConsumer` | The launch-queue consumer |
31
+
32
+ ### `install(opts)`
33
+
34
+ Listens for `beforeinstallprompt` (calls `preventDefault()` and keeps the event) and `appinstalled` (drops it). Throws `TypeError('installPrompt.install: win must be an EventTarget')` when `win.addEventListener` is not a function.
35
+
36
+ | Option | Type | Default | Description |
37
+ |--------|------|---------|-------------|
38
+ | `win` | `EventTarget` | `globalThis` | The window the events fire on |
39
+ | `onAvailable` | `() => void` | — | Called when the browser offers installation |
40
+ | `onInstalled` | `() => void` | — | Called once the app is installed |
41
+
42
+ **Returned offer:**
43
+
44
+ | Member | Signature | Description |
45
+ |--------|-----------|-------------|
46
+ | `available` | `() => boolean` | An offer is deferred and can be prompted |
47
+ | `prompt` | `() => Promise<'accepted' \| 'dismissed' \| 'unavailable'>` | Shows the deferred offer once; `'unavailable'` when nothing is deferred; a rejected `prompt()` or `userChoice`, or a missing `userChoice`, resolves `'dismissed'` — never rejects |
48
+ | `dispose` | `() => void` | Removes both listeners and drops the deferred offer |
49
+
50
+ ### `launchQueue(opts)`
51
+
52
+ Registers a `launchQueue.setConsumer` consumer that calls `onFiles(handles)` with the launched files' handles (never an empty list). Throws `TypeError('installPrompt.launchQueue: onFiles must be a function')`.
53
+
54
+ | Option | Type | Default | Description |
55
+ |--------|------|---------|-------------|
56
+ | `win` | `object` | `globalThis` | The window carrying `launchQueue` |
57
+ | `onFiles` | `(handles: FileSystemFileHandle[]) => void` | — | Receives the launched handles (required) |
58
+
59
+ **Returned consumer:**
60
+
61
+ | Member | Type | Description |
62
+ |--------|------|-------------|
63
+ | `supported` | `boolean` | `win.launchQueue.setConsumer` exists; when `false`, nothing was touched |
64
+ | `dispose` | `() => void` | Replaces the consumer with a no-op (a consumer cannot be removed) |
65
+
66
+ ## Examples
67
+
68
+ ### An install button shown only when installation is offered
69
+
70
+ ```js
71
+ const installPrompt = runtime.resolve('installPrompt');
72
+ const button = document.getElementById('install');
73
+
74
+ const offer = installPrompt.install({
75
+ onAvailable: () => { button.hidden = false; },
76
+ onInstalled: () => { button.hidden = true; },
77
+ });
78
+
79
+ button.addEventListener('click', async () => {
80
+ button.hidden = true;
81
+ const outcome = await offer.prompt(); // 'accepted' | 'dismissed' | 'unavailable'
82
+ console.log('install:', outcome);
83
+ });
84
+ ```
85
+
86
+ ### Open the files the system launched the app with
87
+
88
+ ```js
89
+ const installPrompt = runtime.resolve('installPrompt');
90
+
91
+ installPrompt.launchQueue({
92
+ onFiles: async (handles) => {
93
+ const [first] = handles;
94
+ const file = await first.getFile();
95
+ openDocument(file, first); // keep the handle to write back later
96
+ },
97
+ });
98
+ ```
99
+
100
+ ## Notes
101
+
102
+ - `beforeinstallprompt`, `appinstalled` and `launchQueue` are Chromium-only today; elsewhere `onAvailable` never fires and `launchQueue()` returns `supported: false`.
103
+ - Never a nag: call `prompt()` only from a user gesture (a click); the browser ignores or refuses an unprompted call, and the offer can be shown only once.
104
+ - The launch queue hands `FileSystemFileHandle`s, not `File`s: call `handle.getFile()` to read, keep the handle to save back (see `fsAccess`).
105
+ - The File Handling launch queue needs a `file_handlers` entry in the web app manifest; this module does not write the manifest.
106
+
107
+ ## See also
108
+
109
+ - [serviceWorker](./serviceWorker.md) — registration, the other half of an installable app
110
+ - [swUpdate](./swUpdate.md) — waiting-release update flow for the installed app
111
+ - [fsAccess](../fs/fsAccess.md) — reading and writing through `FileSystemFileHandle`s