@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
@@ -0,0 +1,124 @@
1
+ ---
2
+ module: precache
3
+ category: dom/sw
4
+ dependencies: [cache]
5
+ returns: object
6
+ worker-safe: true
7
+ status: complete
8
+ ---
9
+
10
+ # precache
11
+
12
+ > Worker-side release precache with cache-first / network-first strategies.
13
+
14
+ **Module** `precache` | **Source** `packages/front/fw/src/dom/sw/precache.js` | **Deps** `cache` | **Worker-safe** yes
15
+
16
+ The service-worker half of a versioned offline app. `install` pre-caches the release's files into a cache named `prefix + version`; `activate` deletes this prefix's older caches and claims the pages; `fetch` serves same-origin GET requests cache-first or network-first, chosen per request; `message` answers the page-side [`swUpdate`](./swUpdate.md) protocol. The worker scope is passed explicitly (`scope: self`).
17
+
18
+ ## Resolve
19
+
20
+ ```js
21
+ const precache = runtime.resolve('precache');
22
+ // Returns: { create, DEFAULT_MESSAGES }
23
+ ```
24
+
25
+ ## API
26
+
27
+ | Member | Signature | Returns |
28
+ |--------|-----------|---------|
29
+ | `create` | `(opts: PrecacheOptions) => PrecacheInstance` | A release precache for one scope |
30
+ | `DEFAULT_MESSAGES` | `Readonly<{ skipWaiting: string, version: string }>` | The default wire protocol (shared with `swUpdate`) |
31
+
32
+ ### `create(opts)`
33
+
34
+ Throws `TypeError` (`precache.create: …`) when `scope` has no `addEventListener`, `prefix` or `version` is not a non-empty string, `urls` is not an array of strings, `strategy` is not a function, or `takeOver` is not one of `'first-install'`, `'always'`, `'never'`.
35
+
36
+ | Option | Type | Default | Description |
37
+ |--------|------|---------|-------------|
38
+ | `scope` | `ServiceWorkerGlobalScope` | — | The worker scope (`self`); required, never defaulted |
39
+ | `prefix` | `string` | — | Cache-name prefix owned by this app |
40
+ | `version` | `string` | — | The release; the cache is `prefix + version` |
41
+ | `urls` | `string[]` | — | The release's files, relative to the worker |
42
+ | `strategy` | `(request, url) => 'cache-first' \| 'network-first' \| 'pass'` | `() => 'cache-first'` | Per-request strategy |
43
+ | `navigationFallback` | `string \| null` | `'./'` | Served for a navigation miss in cache-first; `null` goes to the network |
44
+ | `cacheRuntime` | `boolean` | `true` | Keep a copy of each 200 network response |
45
+ | `takeOver` | `'first-install' \| 'always' \| 'never'` | `'first-install'` | When install calls `skipWaiting()` |
46
+ | `claim` | `boolean` | `true` | `clients.claim()` on activate |
47
+ | `messages` | `{ skipWaiting, version } \| null` | `DEFAULT_MESSAGES` | Message protocol; `null` installs no `message` listener |
48
+
49
+ ### `PrecacheInstance`
50
+
51
+ | Member | Signature | Description |
52
+ |--------|-----------|-------------|
53
+ | `cacheName` | `string` | `prefix + version` |
54
+ | `handlers` | `{ install, activate, fetch, message }` | The event handlers, callable directly |
55
+ | `cacheFirst` | `(request) => Promise<Response>` | The release's copy first (a navigation ignores the query, then falls back to `navigationFallback`), else the network (kept when 200 and `cacheRuntime`), else `Response.error()` |
56
+ | `networkFirst` | `(request) => Promise<Response>` | The network first (kept when 200 and `cacheRuntime`), else the last copy, else `Response.error()` |
57
+ | `listen` | `() => PrecacheInstance` | Attaches `install`, `activate`, `fetch` and (with `messages`) `message` to the scope; idempotent |
58
+
59
+ ### Strategy function contract
60
+
61
+ `strategy(request, url)` runs only for same-origin GET requests (others are left to the browser, no `respondWith`). It returns:
62
+
63
+ | Value | Effect |
64
+ |-------|--------|
65
+ | `'cache-first'` | `respondWith(cacheFirst(request))` — the default, for a versioned shell |
66
+ | `'network-first'` | `respondWith(networkFirst(request))` — e.g. for a development build |
67
+ | `'pass'` | no `respondWith`: the browser handles the request |
68
+
69
+ ### First-install take-over
70
+
71
+ With the default `takeOver: 'first-install'`, install calls `skipWaiting()` only when the registration has no active worker yet — the first visit works offline at once — while every later release installs and **waits** until the page sends the skip-waiting message. `'always'` skips waiting on every install; `'never'` always waits.
72
+
73
+ ### Message protocol
74
+
75
+ | Message `type` (default) | Effect |
76
+ |--------------------------|--------|
77
+ | `'awa-sw-skip-waiting'` | `event.waitUntil(scope.skipWaiting())` |
78
+ | `'awa-sw-version'` | `event.ports[0].postMessage({ version })` when a port is transferred |
79
+
80
+ Any other type is ignored. Pass the same `messages` object to `swUpdate` to change the strings.
81
+
82
+ ## Examples
83
+
84
+ ### A development build stays network-first
85
+
86
+ ```js
87
+ const VERSION = typeof __APP_VERSION__ === 'string' ? __APP_VERSION__ : 'dev';
88
+ precache.factory(cache.factory()).create({
89
+ scope: self,
90
+ prefix: 'my-app-',
91
+ version: VERSION,
92
+ urls: ['./'],
93
+ strategy: () => (VERSION === 'dev' ? 'network-first' : 'cache-first'),
94
+ }).listen();
95
+ ```
96
+
97
+ ## Worker Usage
98
+
99
+ The service-worker script itself (a module worker, registered with `{ type: 'module' }`):
100
+
101
+ ```js
102
+ // sw.js
103
+ import { cache } from '@awacloud/fw/dom/sw/cache.js';
104
+ import { precache } from '@awacloud/fw/dom/sw/precache.js';
105
+
106
+ precache.factory(cache.factory()).create({
107
+ scope: self,
108
+ prefix: 'my-app-',
109
+ version: 'v42',
110
+ urls: ['./', 'main.js', 'app.css', 'icon-192.png'],
111
+ }).listen();
112
+ ```
113
+
114
+ ## Notes
115
+
116
+ - Only this prefix's caches are deleted on activate — never another app's caches on the same origin, never other storage.
117
+ - `cacheRuntime` keeps runtime responses only when the status is 200; cache write errors are swallowed, never surfaced to the page.
118
+ - The factory captures nothing: `scope`, `caches`, `fetch` and `Response` are read at call time, so the module evaluates in any realm and tests pass a fake scope.
119
+
120
+ ## See also
121
+
122
+ - [cache](./cache.md) — the CacheStorage wrapper this module opens and deletes through
123
+ - [serviceWorker](./serviceWorker.md) — page-side registration
124
+ - [swUpdate](./swUpdate.md) — the page side of the update and version protocol
@@ -56,8 +56,9 @@ if (serviceWorker.isSupported()) {
56
56
  console.log('SW registered:', reg.scope);
57
57
 
58
58
  serviceWorker.onUpdate((reg) => {
59
- // Offer the user a page reload
60
- if (confirm('Update available. Reload?')) location.reload();
59
+ // Offer the user a reload through the page's own UI: the sanity
60
+ // tiers block confirm() / alert(). swUpdate drives the whole flow.
61
+ showUpdateBanner(() => location.reload());
61
62
  });
62
63
  }
63
64
  ```
@@ -87,4 +88,5 @@ window.addEventListener('unload', unsub);
87
88
  ## See also
88
89
 
89
90
  - [cache](./cache.md) — Cache API (usable SW-side and window-side)
91
+ - [swUpdate](./swUpdate.md) — waiting-release update flow built on this module
90
92
  - [broadcastChannel](../net/broadcastChannel.md) — alternative cross-tab communication
@@ -0,0 +1,112 @@
1
+ ---
2
+ module: swUpdate
3
+ category: dom/sw
4
+ dependencies: [serviceWorker]
5
+ returns: object
6
+ worker-safe: false
7
+ status: complete
8
+ ---
9
+
10
+ # swUpdate
11
+
12
+ > Waiting-release update flow: report once, check, apply, version (page side).
13
+
14
+ **Module** `swUpdate` | **Source** `packages/front/fw/src/dom/sw/swUpdate.js` | **Deps** `serviceWorker` | **Worker-safe** no
15
+
16
+ Registers a service worker and drives its updates the safe way: a new release installs beside the running one and **waits**. The page is told once that a release is ready, checks on demand, and lets the waiting release take over only when the user accepts — then reloads on the next `controllerchange`. Pairs with the worker-side [`precache`](./precache.md), which answers the same message protocol.
17
+
18
+ ## Resolve
19
+
20
+ ```js
21
+ const swUpdate = runtime.resolve('swUpdate');
22
+ // Returns: { create, DEFAULT_MESSAGES }
23
+ ```
24
+
25
+ ## API
26
+
27
+ | Member | Signature | Returns |
28
+ |--------|-----------|---------|
29
+ | `create` | `(opts: SwUpdateOptions) => Promise<SwUpdateController>` | The update controller |
30
+ | `DEFAULT_MESSAGES` | `Readonly<{ skipWaiting: string, version: string }>` | The default wire protocol |
31
+
32
+ ### `create(opts)`
33
+
34
+ Throws `TypeError('swUpdate.create: swUrl must be a non-empty string')` synchronously, before any await. Without service workers it resolves a controller in state `'unsupported'`; when `register` rejects, state `'failed'` — in both cases every member answers (`false`, `null`, `'unavailable'`).
35
+
36
+ | Option | Type | Default | Description |
37
+ |--------|------|---------|-------------|
38
+ | `swUrl` | `string` | — | Worker script URL (required) |
39
+ | `registerOptions` | `RegistrationOptions` | `{ type: 'module', updateViaCache: 'none' }` | Forwarded to `serviceWorker.register` |
40
+ | `win` | `Window` | `globalThis` | The page window |
41
+ | `onUpdateReady` | `() => void` | — | Called once when a newer release waits on a controlled page |
42
+ | `onControlled` | `() => void` | — | Called at creation when a worker controls the page, and on every `controllerchange` |
43
+ | `messages` | `{ skipWaiting, version }` | `DEFAULT_MESSAGES` | Message types posted to the worker |
44
+ | `installWait` | `number` | `30000` | ms a check waits for a found release to finish installing |
45
+ | `versionWait` | `number` | `2000` | ms `version()` waits for the worker's answer |
46
+
47
+ ### `SwUpdateController`
48
+
49
+ | Member | Signature | Description |
50
+ |--------|-----------|-------------|
51
+ | `state` | `'registered' \| 'unsupported' \| 'failed'` | Registration outcome |
52
+ | `updateReady` | `() => boolean` | A release waits and a worker controls the page |
53
+ | `checkForUpdates` | `() => Promise<CheckResult>` | Asks the server for a newer release |
54
+ | `applyUpdate` | `() => boolean` | Posts the skip-waiting message to the waiting worker and reloads on the next `controllerchange`; `false` when none waits |
55
+ | `version` | `() => Promise<string \| null>` | The release the active worker serves, over a `MessageChannel`; `null` without a worker, without `MessageChannel`, on a non-string answer or after `versionWait` |
56
+ | `controlled` | `() => boolean` | A worker controls the page |
57
+ | `dispose` | `() => void` | Removes the `updatefound`, `statechange` and `controllerchange` listeners it added |
58
+
59
+ ### `CheckResult`
60
+
61
+ | Value | Meaning |
62
+ |-------|---------|
63
+ | `'current'` | No newer release |
64
+ | `'ready'` | A newer release is installed and waits (also reported through `onUpdateReady`, once) |
65
+ | `'offline'` | `navigator.onLine` is `false` or `registration.update()` rejected |
66
+ | `'unavailable'` | No service worker on this page |
67
+
68
+ ### Message protocol (`DEFAULT_MESSAGES`)
69
+
70
+ Shared with [`precache`](./precache.md); override both sides with the same `messages` object.
71
+
72
+ | Key | Default type | Posted to | Worker answer |
73
+ |-----|--------------|-----------|---------------|
74
+ | `skipWaiting` | `'awa-sw-skip-waiting'` | the waiting worker | calls `skipWaiting()` |
75
+ | `version` | `'awa-sw-version'` | the controller (or the active worker), with a transferred port | `{ version }` on that port |
76
+
77
+ ## Examples
78
+
79
+ ### Banner with Update now / Later
80
+
81
+ ```js
82
+ const swUpdate = runtime.resolve('swUpdate');
83
+ const banner = document.getElementById('update-banner');
84
+
85
+ const updates = await swUpdate.create({
86
+ swUrl: './sw.js',
87
+ onUpdateReady: () => { banner.hidden = false; },
88
+ });
89
+
90
+ document.getElementById('update-now').addEventListener('click', () => {
91
+ updates.applyUpdate(); // the page reloads once the new release controls it
92
+ });
93
+ document.getElementById('update-later').addEventListener('click', () => {
94
+ banner.hidden = true; // the release keeps waiting; it is not reported again
95
+ });
96
+
97
+ // An About panel
98
+ const result = await updates.checkForUpdates(); // 'current' | 'ready' | 'offline' | 'unavailable'
99
+ const release = await updates.version(); // e.g. 'a1b2c3', or null
100
+ ```
101
+
102
+ ## Notes
103
+
104
+ - **Reported once, to a controlled page**: `onUpdateReady` fires at most once per `create()`, and only when a release waits AND a worker already controls the page — the first install of an uncontrolled page is not an update.
105
+ - Nothing reloads on its own: a `controllerchange` caused elsewhere (another tab accepting) does not reload this page; only a `controllerchange` after this page's `applyUpdate()` does.
106
+ - The default `updateViaCache: 'none'` makes every update check ask the server for the worker script.
107
+ - Requires a secure context (HTTPS or localhost), like every service worker API.
108
+
109
+ ## See also
110
+
111
+ - [serviceWorker](./serviceWorker.md) — the registration primitive this module drives
112
+ - [precache](./precache.md) — the worker side answering the same protocol
@@ -17,26 +17,29 @@ status: complete
17
17
 
18
18
  ```js
19
19
  const clipboard = runtime.resolve('clipboard');
20
- // Returns: { isSupported, set, get, share }
20
+ // Returns: { isSupported, set, setRich, get, share }
21
21
  ```
22
22
 
23
23
  ## API
24
24
 
25
25
  | Method | Signature | Returns |
26
26
  |---------|-----------|---------|
27
- | `isSupported` | `() => { read: boolean, write: boolean, share: boolean }` | Available capabilities (computed at init) |
27
+ | `isSupported` | `() => { read: boolean, write: boolean, richWrite: boolean, share: boolean }` | Available capabilities (computed at init) |
28
28
  | `set` | `(text: string) => Promise<void>` | Copies text to the clipboard |
29
+ | `setRich` | `({ html: string \| Promise<string>, text: string \| Promise<string> }) => Promise<void>` | Copies one item with a `text/html` and a `text/plain` flavour |
29
30
  | `get` | `() => Promise<string>` | Reads the text content of the clipboard |
30
31
  | `share` | `(opts?: { title?, text?, url?, files? }) => Promise<void>` | Invokes the native share sheet |
31
32
 
32
- ### `clipboard.isSupported() → { read, write, share }`
33
+ ### `clipboard.isSupported() → { read, write, richWrite, share }`
33
34
 
34
35
  ```js
35
36
  const caps = clipboard.isSupported();
36
- // → { read: boolean, write: boolean, share: boolean }
37
+ // → { read: boolean, write: boolean, richWrite: boolean, share: boolean }
37
38
  ```
38
39
 
39
- Checked once at factory initialisation — no per-call overhead.
40
+ Checked once at factory initialisation — no per-call overhead. `richWrite` is
41
+ true when `navigator.clipboard.write` is a function and `ClipboardItem` is a
42
+ constructor.
40
43
 
41
44
  ---
42
45
 
@@ -52,6 +55,31 @@ Requires a secure context (HTTPS or `localhost`). May require a user gesture.
52
55
 
53
56
  ---
54
57
 
58
+ ### `clipboard.setRich({ html, text }) → Promise<void>`
59
+
60
+ Copies ONE clipboard item carrying a `text/html` and a `text/plain` flavour:
61
+ a paste into a word processor keeps the formatting, a plain-text target gets
62
+ the text. `html` and `text` are each a string or a `Promise<string>`.
63
+
64
+ ```js
65
+ await clipboard.setRich({ html: '<p><b>Total</b>: 42</p>', text: 'Total: 42' });
66
+ ```
67
+
68
+ - **Gesture rule.** The item is built and `navigator.clipboard.write` is
69
+ called synchronously, inside the caller's user gesture, with the values
70
+ still pending. WebKit refuses a write whose item is created after an
71
+ `await`, so pass a slow conversion as a promise — never `await` it before
72
+ calling `setRich`. Chromium accepts promised values too.
73
+ - **No implicit fallback.** When `isSupported().richWrite` is false, the call
74
+ rejects with an `Error` whose message starts `clipboard: rich write
75
+ unsupported`. Check the flag first and fall back to `set(text)` yourself.
76
+ - **Not sanitized.** The HTML is written as given. It is the caller's, and
77
+ must be sanitized before it reaches the clipboard.
78
+ - The returned promise rejects when either value rejects or when the browser
79
+ refuses the write.
80
+
81
+ ---
82
+
55
83
  ### `clipboard.get() → Promise<string>`
56
84
 
57
85
  Reads the text content of the clipboard.
@@ -102,6 +130,29 @@ if (caps.write) {
102
130
  }
103
131
  ```
104
132
 
133
+ ### "Copy with formatting" from a conversion started on click
134
+
135
+ ```js
136
+ const clipboard = runtime.resolve('clipboard');
137
+ const events = runtime.resolve('events');
138
+
139
+ events.on('copyRich', copyRichBtn, 'click', () => {
140
+ // Start the slow work, but do NOT await it before the write:
141
+ // setRich must run inside the click's user gesture.
142
+ const md = convertToMarkdown(doc); // Promise<string>
143
+ const html = md.then(renderSanitizedHtml); // Promise<string>, sanitized by the caller
144
+
145
+ const done = clipboard.isSupported().richWrite
146
+ ? clipboard.setRich({ html, text: md })
147
+ : md.then((text) => clipboard.set(text)); // plain-text fallback, the caller's choice
148
+
149
+ done.then(
150
+ () => { copyRichBtn.textContent = 'Copied!'; },
151
+ () => { copyRichBtn.textContent = 'Copy failed'; },
152
+ );
153
+ });
154
+ ```
155
+
105
156
  ### Native share button with copy fallback
106
157
 
107
158
  ```js
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: entropyCollector
3
3
  category: dom/utils
4
- dependencies: ['sensors']
4
+ dependencies: [sensors]
5
5
  returns: function
6
6
  worker-safe: false
7
7
  status: complete
@@ -76,10 +76,12 @@ Parses a combo and returns a descriptor or an array (chord).
76
76
 
77
77
  **Accepted modifiers** (case-insensitive): `Ctrl`, `Shift`, `Alt`, `Meta`/`Cmd`/`Super`.
78
78
 
79
- **Keys**: `A`–`Z`, `0`–`9`, `F1`–`F12`, `Escape`/`Esc`, `Tab`, `Enter`/`Return`, `Space`, `Backspace`, `Delete`/`Del`, `ArrowUp`/`Up`, `ArrowDown`/`Down`, `ArrowLeft`/`Left`, `ArrowRight`/`Right`, `Home`, `End`, `PageUp`, `PageDown`, `Insert`.
79
+ **Keys**: `A`–`Z`, `0`–`9`, `F1`–`F12`, `Escape`/`Esc`, `Tab`, `Enter`/`Return`, `Space`, `Backspace`, `Delete`/`Del`, `ArrowUp`/`Up`, `ArrowDown`/`Down`, `ArrowLeft`/`Left`, `ArrowRight`/`Right`, `Home`, `End`, `PageUp`, `PageDown`, `Insert`, `Plus`, `Minus` (or the literal `-`), `Equal` (or the literal `=`).
80
80
 
81
81
  **Resolution strategy**: `event.code` for alphanumerics (layout-independent, e.g. `KeyA` = physical A key), `event.key` for named keys.
82
82
 
83
+ **Punctuation keys** (`Plus`, `Minus`, `Equal`) match on `event.key` — the character the layout produced, numpad included — and ignore the Shift modifier (`+` is Shift+`=` on most layouts); `Shift+Plus` is refused at parse time. `+` itself is the separator: write `Plus`.
84
+
83
85
  Throws `TypeError` if the combo is empty or not a string, `Error` if the syntax is invalid or the key is unknown.
84
86
 
85
87
  ## Examples
@@ -123,10 +125,23 @@ const all = kb.list();
123
125
  console.table(all.map(({ combo, context, priority }) => ({ combo, context, priority })));
124
126
  ```
125
127
 
128
+ ### Zoom keys
129
+
130
+ ```js
131
+ // '+' is Shift+'=' on most layouts and a plain key on the numpad: the bindings
132
+ // below fire on all of them. Ctrl+Plus does not match these bindings, so the
133
+ // browser's own zoom keeps working.
134
+ kb.bind('Plus', zoomIn, { preventDefault: false });
135
+ kb.bind('Equal', zoomIn, { preventDefault: false });
136
+ kb.bind('Minus', zoomOut, { preventDefault: false });
137
+ kb.bind('0', reset, { preventDefault: false });
138
+ ```
139
+
126
140
  ## Notes
127
141
 
128
142
  - The `event.code` strategy makes alphanumeric shortcuts independent of the keyboard layout (AZERTY/QWERTY). Named keys (`Escape`, `F1`, etc.) use `event.key`.
129
- - Chord: if the first keystroke matches a chord prefix, a `chordTimeout` timer starts. If the second keystroke does not match, the chord is cancelled and processing resumes with simple bindings on the next keystroke.
143
+ - Punctuation keys ignore Shift on the event side and refuse it on the binding side: the shifted character is already the key (`+` = Shift+`=`), so `Shift+Plus` and `Shift+=` throw at parse time. Ctrl, Alt and Meta still qualify them (`Ctrl+Plus`).
144
+ - Chord: if the first keystroke matches a chord prefix, a `chordTimeout` timer starts. Every chord whose segments so far matched stays a candidate, so chords sharing a prefix (`Ctrl+K Ctrl+A`, `Ctrl+K Ctrl+H`) all complete; each keystroke narrows the set. When chords complete on the same keystroke, the highest `priority` fires (the first registered on a tie), and a completed chord wins over a longer one sharing its prefix. A keystroke that matches no candidate cancels the chord and is processed as a simple binding.
130
145
  - When a context is active (non-empty stack), only bindings for that context trigger. Bindings without a context are suspended until `popContext()`.
131
146
  - Each trigger emits `keybindings:matched` on the instance's internal `eventBus` — consumed by the command palette to display active shortcuts.
132
147
  - `dispose()` detaches listeners and clears bindings, but does not delete references to the instance. Create a fresh instance if needed.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: leaderElection
3
3
  category: dom/utils
4
- dependencies: [broadcastChannel]
4
+ dependencies: [broadcastChannel, uuid]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -11,7 +11,7 @@ status: complete
11
11
 
12
12
  > Elects a unique leader among multiple tabs/clients of the same origin.
13
13
 
14
- **Module** `leaderElection` | **Source** `packages/front/fw/src/dom/utils/leaderElection.js` | **Deps** `broadcastChannel` | **Worker-safe** no
14
+ **Module** `leaderElection` | **Source** `packages/front/fw/src/dom/utils/leaderElection.js` | **Deps** `broadcastChannel`, `uuid` | **Worker-safe** no
15
15
 
16
16
  Used to centralise a WebSocket connection, relay cross-tab via a single writer, avoid job duplication (remote sync, cron), or as a fallback when SharedWorker is unavailable.
17
17
 
@@ -100,6 +100,7 @@ route.replace('/login'); // without a new history entry
100
100
 
101
101
  - **Re-entry guard**: if a handler calls `route.go(...)`, the chained dispatch accumulates cleanly — no infinite recursion or double-fire.
102
102
  - **`go()` on the same hash** still forces a dispatch (equivalent to clicking the active link).
103
+ - **`go()` dispatches once.** It dispatches directly; the `hashchange` its own hash assignment causes is ignored (the listener skips an event whose hash equals the last dispatched one), so a handler that fetches runs one request, not two. A real `hashchange` — back, a link, a manual assignment — dispatches as usual.
103
104
  - **Multiple routes match** (without parent/child relationship): handlers are invoked in **registration order** — all match independently. For "unique match", use a single route per canonical path.
104
105
  - **Downstream chain invalidation**: when a parent route guard returns `false`, all children in the chain are short-circuited — dispatch stops at the first refusal.
105
106
  - Native `pushState`/`replaceState` are blocked by sanity. `replace` uses `location.replace(url)`, which bypasses this limitation but triggers a full reload **if the URL changes outside the fragment** — `replace` here only acts on the hash, without reload.
@@ -9,7 +9,7 @@ status: complete
9
9
 
10
10
  # ua
11
11
 
12
- > User agent detection — mobile, touch, and OS platform. All values computed once at init.
12
+ > Client detection — mobile, touch and platform, from UA Client Hints first and the UA string only where they say nothing.
13
13
 
14
14
  **Module** `ua` | **Source** `packages/front/fw/src/dom/utils/ua.js` | **Deps** none | **Worker-safe** no
15
15
 
@@ -25,9 +25,9 @@ const ua = runtime.resolve('ua');
25
25
  | Method | Signature | Returns |
26
26
  |---------|-----------|---------|
27
27
  | `string` | `() => string` | Raw `navigator.userAgent` (computed at init) |
28
- | `mobile` | `() => boolean` | `true` on iOS/Android (pattern match at init) |
28
+ | `mobile` | `() => boolean` | `true` on a phone-class device: UA-CH `mobile`, else "Mobi" in the UA (computed at init) |
29
29
  | `touch` | `() => boolean` | Touch support (evaluated on each call) |
30
- | `platform` | `() => 'ios' \| 'android' \| 'windows' \| 'mac' \| 'linux' \| 'unknown'` | Normalized OS (computed at init) |
30
+ | `platform` | `() => 'ios' \| 'android' \| 'windows' \| 'mac' \| 'linux' \| 'unknown'` | Normalized OS: UA-CH `platform`, else the UA string (computed at init) |
31
31
 
32
32
  ### `ua.string() → string`
33
33
 
@@ -40,14 +40,16 @@ ua.string();
40
40
 
41
41
  ### `ua.mobile() → boolean`
42
42
 
43
- Detects a mobile device via pattern matching on the UA string.
43
+ `true` on a phone-class device, following MDN's "Browser detection using the user
44
+ agent": `navigator.userAgentData.mobile` (User-Agent Client Hints, Chromium-based
45
+ browsers) when it exists, else the string "Mobi" anywhere in the UA. Tablets are not
46
+ mobile (an Android tablet UA has no "Mobile" token); an iPad in Safari's mobile mode
47
+ sends "Mobile/…" and is. Computed once at init.
44
48
 
45
49
  ```js
46
- ua.mobile(); // → true on iOS, Android, etc.
50
+ ua.mobile(); // → true on a phone
47
51
  ```
48
52
 
49
- Pattern-list detection (two regexes: full UA + 4-character prefix), computed once at init. Behaviour is pinned by the module's test table.
50
-
51
53
  ### `ua.touch() → boolean`
52
54
 
53
55
  Detects touch support at call time (runtime check).
@@ -56,11 +58,13 @@ Detects touch support at call time (runtime check).
56
58
  ua.touch(); // → true if the device supports touch
57
59
  ```
58
60
 
59
- Checks `'ontouchstart' in window` AND `navigator.maxTouchPoints > 0`. May change on hybrid devices (touch laptops).
61
+ `true` when `'ontouchstart' in window` OR `navigator.maxTouchPoints > 0`. May change on hybrid devices (touch laptops).
60
62
 
61
63
  ### `ua.platform() → string`
62
64
 
63
- Normalized OS — value computed at init.
65
+ Normalized OS — value computed at init. `navigator.userAgentData.platform` first (`Windows`, `macOS`, `Linux`,
66
+ `Android`, `iOS`, and `Chrome OS` → `'linux'`; any other hint → `'unknown'`), else a few UA tokens. A `Macintosh`
67
+ UA on a device with more than one touch point is iPadOS asking for desktop sites, so it reads `'ios'`.
64
68
 
65
69
  | Returns | System |
66
70
  |--------|---------|
@@ -110,7 +114,8 @@ if (ua.platform() === 'ios') {
110
114
 
111
115
  - `mobile()`, `platform()`, and `string()` return values computed once at init — no per-call overhead.
112
116
  - `touch()` is evaluated on each call because it may change on hybrid devices.
113
- - UA detection is **heuristic** and can be spoofed. Prefer feature detection (`ua.touch()`, `media.isSupported()`) when possible.
117
+ - Detection is **heuristic** and both the UA string and the hints can be spoofed (an emulator that overrides the UA string also derives the hints from it). Prefer feature detection (`ua.touch()`, `media.isSupported()`) when a capability is what you need.
118
+ - Measured in headless Chromium 148: `userAgentData` `{ platform: 'Windows', mobile: false }` → `platform()` `'windows'`, `mobile()` `false`.
114
119
  - Returns empty strings in non-browser environments.
115
120
 
116
121
  ## See also
@@ -67,7 +67,10 @@ const worker = fw.createWorker(
67
67
 
68
68
  - Each `new Crc32()` instance is independent — no shared internal state.
69
69
  - `get()` always returns a **unsigned** 32-bit integer (via `>>> 0`).
70
- - Pre-computed lookup table algorithm (256 entries) — fast for large volumes.
70
+ - Slicing-by-16 on `Uint8Array` input: one 16 KiB table set, sixteen bytes
71
+ folded per step (1 MiB in about 0.3-0.5 ms under Bun, 0.6 ms under Node);
72
+ an array of numbers and the last 0-15 bytes take the byte-at-a-time loop,
73
+ which reads each element's low 8 bits.
71
74
 
72
75
  ## See also
73
76
 
@@ -4,14 +4,14 @@ Encoding and decoding between bytes (`Uint8Array`) and text or binary representa
4
4
 
5
5
  Four families:
6
6
  - **bytes ↔ string** — `hex`, `b64`, `base32`, `base58`, `utf8`: API `fromBytes` / `toBytes` (+ `test`).
7
- - **JS value ↔ bytes** (binary serialisation) — `buffer` (internal awa format), `cbor` (RFC 8949), `msgpack` (MessagePack spec): API `encode` / `decode`.
7
+ - **JS value ↔ bytes** (binary serialisation) — `buffer` (internal AWA format), `cbor` (RFC 8949), `msgpack` (MessagePack spec): API `encode` / `decode`.
8
8
  - **JS value ↔ text** (tabular / querystring serialisation) — `csv` (RFC 4180), `url` (querystring + URL): API `parse` / `stringify`.
9
9
  - **HTTP web formats** — `mime` (multipart + headers): parse/format structured headers, encode/decode `multipart/*` bodies.
10
10
 
11
11
  | Module | Returns | Deps | Description |
12
12
  |--------|----------|------|-------------|
13
13
  | [hex](./hex.md) | `{toBytes, fromBytes}` | none | Hex string ↔ Uint8Array |
14
- | [b64](./b64.md) | `{toBytes, fromBytes, test}` | none | Base64 RFC 4648 encode/decode/validate |
14
+ | [b64](./b64.md) | `{toBytes, fromBytes, test, url}` | none | Base64 RFC 4648 encode/decode/validate, base64url (§ 5) under `url` |
15
15
  | [base32](./base32.md) | `{toBytes, fromBytes, test}` | none | Base32 RFC 4648 (A–Z 2–7, padding `=`) |
16
16
  | [base58](./base58.md) | `{toBytes, fromBytes, test}` | none | Base58 Bitcoin/IPFS alphabet (no padding) |
17
17
  | [utf8](./utf8.md) | `{toBytes, fromBytes}` | none | JS String ↔ UTF-8 bytes |
@@ -9,7 +9,7 @@ status: complete
9
9
 
10
10
  # b64
11
11
 
12
- > Base64 encoding/decoding (RFC 4648) with `=` padding. Format validation included.
12
+ > Base64 encoding/decoding (RFC 4648 § 4) with `=` padding, and base64url (§ 5) without padding under `url`. Format validation included.
13
13
 
14
14
  **Module** `b64` | **Source** `packages/front/fw/src/io/codec/b64.js` | **Deps** none | **Worker-safe** yes
15
15
 
@@ -17,7 +17,7 @@ status: complete
17
17
 
18
18
  ```js
19
19
  const b64 = runtime.resolve('b64');
20
- // Returns: { fromBytes, toBytes, test }
20
+ // Returns: { fromBytes, toBytes, test, url }
21
21
  ```
22
22
 
23
23
  ## API
@@ -27,6 +27,9 @@ const b64 = runtime.resolve('b64');
27
27
  | `fromBytes` | `(bytes: Uint8Array\|number[]) => string` | Base64 string with padding |
28
28
  | `toBytes` | `(str: string) => Uint8Array` | Byte array |
29
29
  | `test` | `(str: string) => boolean` | `true` if valid Base64 |
30
+ | `url.fromBytes` | `(bytes: Uint8Array\|number[]) => string` | base64url (`-` and `_`), no padding |
31
+ | `url.toBytes` | `(str: string) => Uint8Array \| false` | Bytes, or `false` unless `str` is the canonical unpadded form |
32
+ | `url.test` | `(str: string) => boolean` | `true` when `url.toBytes` accepts `str` |
30
33
 
31
34
  ### `b64.fromBytes(bytes)`
32
35
 
@@ -51,6 +54,21 @@ b64.test('SGVsbG8'); // false — missing padding
51
54
  b64.test(''); // true — empty string is valid
52
55
  ```
53
56
 
57
+ ### `b64.url`
58
+
59
+ base64url (RFC 4648 § 5), the alphabet of JWS, JWT and URL tokens. The
60
+ decoder is strict: it accepts the canonical unpadded form only — no `=`, no
61
+ `+` or `/`, no length of 1 mod 4, and the unused low bits of the last
62
+ character must be zero (§ 3.5) — so one byte string has exactly one accepted
63
+ spelling, and anything else returns `false` without a warning.
64
+
65
+ ```js
66
+ b64.url.fromBytes(new Uint8Array([251, 255])); // "-_8"
67
+ b64.url.toBytes('-_8'); // Uint8Array [251, 255]
68
+ b64.url.toBytes('-_8='); // false — padding
69
+ b64.url.toBytes('Zh'); // false — unused bits set (canonical: "Zg")
70
+ ```
71
+
54
72
  ## Examples
55
73
 
56
74
  ```js
@@ -86,6 +104,17 @@ const worker = fw.createWorker(
86
104
  - Implements standard RFC 4648 (with `+` and `/`, not URL-safe).
87
105
  - `=` padding is always added.
88
106
  - `test` validates: length multiple of 4, valid characters, correct padding.
107
+ - Speed: `fromBytes` on a `Uint8Array` and `toBytes` on canonical input
108
+ use the platform's `Uint8Array.prototype.toBase64` / `Uint8Array.fromBase64`
109
+ where the realm has them (JavaScriptCore — Safari, Bun — and Firefox);
110
+ elsewhere (V8: Chrome, Node) JS paths over typed arrays (`TextDecoder` for
111
+ the output string). 1 MiB encodes in about 0.2 ms (Bun) / 1.1 ms (Node) and
112
+ decodes in about 0.2 ms / 2 ms.
113
+ - `toBytes` is lenient, as it always was: an input that is not canonical
114
+ base64 (a character outside the alphabet, an `=` before the end, a length
115
+ that is not a multiple of 4) goes through the original decoder, which
116
+ reads an unknown character as zero bits and throws a `TypeError` on a
117
+ missing padding. Check untrusted input with `test` first.
89
118
 
90
119
  ## See also
91
120
 
@@ -17,7 +17,7 @@ status: complete
17
17
 
18
18
  ```js
19
19
  const buf = runtime.resolve('buffer');
20
- // Returns: { out, in, consume, clone, concat, const }
20
+ // Returns: { out, in, consume, clone, concat }
21
21
  ```
22
22
 
23
23
  ## Binary format
@@ -32,7 +32,7 @@ const cbor = runtime.resolve('cbor');
32
32
  | Method | Signature | Returns |
33
33
  |--------|-----------|---------|
34
34
  | `encode` | `(value: any, options?: {deterministic?: boolean}) => Uint8Array` | CBOR representation |
35
- | `decode` | `(bytes: Uint8Array, options?: {useMap?: boolean}) => any` | Reconstructed JS value |
35
+ | `decode` | `(bytes: Uint8Array, options?: {useMap?: boolean, maxDepth?: number}) => any` | Reconstructed JS value; nesting deeper than `maxDepth` (default 512) throws |
36
36
  | `Tagged` | `class Tagged(tag, value)` | CBOR tag wrapper (major type 6) |
37
37
  | `Simple` | `class Simple(value)` | CBOR simple value (major type 7, 0..255 excluding 20..23 which alias primitives and 24..31 reserved) |
38
38
 
@@ -43,8 +43,8 @@ const cbor = runtime.resolve('cbor');
43
43
  | `null` | `0xf6` |
44
44
  | `undefined` | `0xf7` |
45
45
  | `false` / `true` | `0xf4` / `0xf5` |
46
- | `Number` integer in `[-2^32, 2^32-1]` | major 0 / 1 (shortest form) |
47
- | `Number` fractional or out of range | float16 / float32 / float64 (shortest exact) |
46
+ | `Number` safe integer (`Number.isSafeInteger`) | major 0 / 1 (shortest form; `1e12` → `1b000000e8d4a51000`, RFC 8949 App. A) |
47
+ | `Number` fractional or past 2^53 | float16 / float32 / float64 (shortest exact) |
48
48
  | `BigInt` 0..2^64-1 | major 0 |
49
49
  | `BigInt` -2^64..-1 | major 1 |
50
50
  | `BigInt` beyond | tag 2 / 3 + byte string |
@@ -166,14 +166,16 @@ const worker = fw.createWorker(
166
166
 
167
167
  ## Notes
168
168
 
169
+ - A map decoded to a plain object never takes its prototype from the payload: the object has a `null` prototype (`Object.create(null)`: no inherited key such as `toString` or `hasOwnProperty`; use `Object.hasOwn`), and a `"__proto__"` key is an own enumerable property holding the decoded value.
169
170
  - `Number.isInteger(x)` triggers integer encoding even for `1.0`, `0.0` (identical in JS). To force a float, use an explicit fractional value.
170
171
  - Unsupported JS types: `Symbol`, `Function`, `Promise`, `Date` — no implicit conversion. For dates, wrap via `Tagged(0, iso)` (tag 0, RFC 8949 §3.4.1) or `Tagged(1, epoch)` (tag 1, §3.4.2) depending on the intended semantics.
171
172
  - `Map` → CBOR map (order preserved). To retrieve a `Map` on decode, use `{ useMap: true }`.
173
+ - **Well-formedness** (RFC 8949 App. F): every not-well-formed example is refused (a throw): truncated heads and string data, reserved additional information, two-byte simple values below 32, indefinite strings whose chunks are not definite strings of the same type, and a break (`0xff`) anywhere but at the end of an indefinite-length item.
172
174
  - Duplicate keys on input: the decoder takes the last occurrence (RFC §5.6 classifies this as "well-formed but invalid" — the emitter's responsibility).
173
175
  - Comparison with [buffer](./buffer.md): `buffer` is more compact for small integers and uses a typed header; `cbor` is standard and interoperates with COSE, WebAuthn, IPLD, CTAP.
174
176
 
175
177
  ## See also
176
178
 
177
179
  - [msgpack](./msgpack.md) — more compact non-IETF alternative
178
- - [buffer](./buffer.md) — awa internal binary format
180
+ - [buffer](./buffer.md) — AWA internal binary format
179
181
  - [utf8](./utf8.md) — dependency