@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
@@ -34,12 +34,13 @@ const wasmRuntime = runtime.resolve('wasmRuntime');
34
34
  | `withBytes` | `(loaded: Handle, input: Uint8Array) => { ptr, len, free }` | Copies `input` INTO linear memory; returns ptr/len + a `free()` thunk |
35
35
  | `readBytes` | `(loaded: Handle, ptr: number, len: number) => Uint8Array` | Copies `len` bytes OUT of linear memory into a fresh `Uint8Array` |
36
36
  | `run` | `(loaded: Handle, fnName: string, args: number[]) => number` | Calls an export, returns its `i32` status; a trap throws to the caller's try/catch |
37
+ | `configure` | `({ baseUrl: string \| URL \| null }) => void` | Sets the asset base every later `load` uses — the algorithm wrappers included; `null` restores this module's directory. Throws `TypeError` when the base is not an absolute URL |
37
38
 
38
- `load` options (`opts`): `variant` (`'simd' | 'scalar'`) forces a variant (default = runtime selection); `fetchBytes(wasmModule, variant) => Promise<Uint8Array>` is a documented **test seam** overriding the colocated fetch. The success handle exposes: `instance`, `memory` (and a `mem` alias), `alloc`, `free`, `exports`, and `variant`.
39
+ `load` options (`opts`): `variant` (`'simd' | 'scalar'`) forces a variant (default = runtime selection); `baseUrl` (an absolute URL, the directory that holds the binaries; a missing trailing `/` is added) overrides the asset base for this call; `fetchBytes(wasmModule, variant) => Promise<Uint8Array>` is a documented **test seam** overriding the colocated fetch. The success handle exposes: `instance`, `memory` (and a `mem` alias), `alloc`, `free`, `exports`, and `variant`.
39
40
 
40
41
  `load` resolves `false` when:
41
42
  - `WebAssembly` is unavailable (`[crypto] NOT READY: WebAssembly unavailable` logged)
42
- - the fetch/compile/instantiate fails, or the zero-import invariant or a `memory`/`alloc`/`free`/`expectedExports` entry is missing (`[crypto] FAIL: wasmRuntime.load: <message>` logged)
43
+ - `baseUrl` is not an absolute URL, or the fetch/compile/instantiate fails, or the zero-import invariant or a `memory`/`alloc`/`free`/`expectedExports` entry is missing (`[crypto] FAIL: wasmRuntime.load: <message>` logged)
43
44
 
44
45
  ## Canonical WASM ABI
45
46
 
@@ -60,8 +61,15 @@ The binaries are **committed assets** next to this module:
60
61
  so the browser/worker cache can share the asset across page loads — the same
61
62
  rationale as `brotli_dict.bin`.
62
63
 
63
- `load` resolves `new URL('./<wasmModule>.<variant>.wasm', import.meta.url)` and
64
- `fetch`es it. The **SIMD win** comes from `load` fetching `<wasmModule>.simd.wasm`
64
+ `load` resolves `new URL('./<wasmModule>.<variant>.wasm', base)` and `fetch`es
65
+ it, where `base` is the call's `baseUrl`, else the `configure` base, else
66
+ `import.meta.url` (this module's directory). A module name is `[a-z0-9_]+`, so
67
+ it never walks out of the base. Every `load` fetches and compiles afresh: a
68
+ compile memo is withheld because, under JavaScriptCore (Bun, and the engine of
69
+ Safari), `chacha20poly1305.simd.wasm` returns a wrong Poly1305 tag once one
70
+ `WebAssembly.Module` has run `aead_seal` about six times, while V8 and a fresh
71
+ module per load are correct (`src/crypto/wasm/chacha-simd-jsc.test.js` pins
72
+ it). The **SIMD win** comes from `load` fetching `<wasmModule>.simd.wasm`
65
73
  when `hasSimd()` is true; scalar-only targets (no `.simd.wasm` colocated) must be
66
74
  loaded with `{ variant: 'scalar' }`. Wrappers always **load by name** — they never
67
75
  import a binary directly.
@@ -79,16 +87,24 @@ for a scalar-only target then fails — `load` resolves `false` per its no-throw
79
87
  contract rather than retrying scalar. Passing `{ variant: 'scalar' }` is part of
80
88
  a scalar-only wrapper's contract, not an optimisation.
81
89
 
82
- ### Asset resolution binds to this module's own URL
90
+ ### Asset base: this module's own URL, unless configured
83
91
 
84
- The colocated fetch is `new URL('./<wasmModule>.<variant>.wasm',
92
+ The default fetch is `new URL('./<wasmModule>.<variant>.wasm',
85
93
  import.meta.url)` evaluated **inside `factory()`**, so the base is wherever
86
94
  `runtime.js` itself was loaded from. A build step that inlines a descriptor by
87
95
  stringifying its factory (`factory.toString()`) re-binds `import.meta.url` to
88
96
  the *generated* file, and every wasm-tier path in that artifact then fails to
89
97
  fetch its binary while a tier-audit surface may still report the tier as
90
- effective. Ship `wasmRuntime` as a real module file, or supply
91
- `opts.fetchBytes`, when a bundler re-hosts factory source.
98
+ effective. Name the directory that holds the binaries instead:
99
+
100
+ ```js
101
+ const wasmRuntime = runtime.resolve('wasmRuntime');
102
+ wasmRuntime.configure({ baseUrl: 'https://cdn.example.com/fw/crypto/wasm/' });
103
+ // every wasm* wrapper resolved on this runtime now fetches from there
104
+ ```
105
+
106
+ The base is a place to fetch from, never bytes, so it stays open under
107
+ `lockdown()` — unlike `opts.fetchBytes`, which the gate refuses once armed.
92
108
 
93
109
  **Provenance.** The bytes are build artifacts of the `@awacloud/fw-wasm-crypto` package
94
110
  (`dist/<wasmModule>.{simd,scalar}.wasm`, emitted by `tools/wasm-crypto build`),
@@ -146,8 +162,9 @@ const fast = await wasmRuntime.hasSimd(); // true ⇒ load() picks the SIMD vari
146
162
  ```js
147
163
  const worker = fw.createWorker(
148
164
  function ({ libs }) {
149
- // The colocated .wasm is fetched by name (resolved from import.meta.url)
150
- // inside the worker — no main-thread closure is serialized.
165
+ // The colocated .wasm is fetched by name (resolved from import.meta.url,
166
+ // or from libs.wasmRuntime.configure({ baseUrl }) when the worker is
167
+ // served elsewhere) — no main-thread closure is serialized.
151
168
  libs.wasmRuntime.load('blake2b', ['blake2b']).then((h) => {
152
169
  self.postMessage(h !== false);
153
170
  });
@@ -39,7 +39,7 @@ const webcryptoAes = runtime.resolve('webcryptoAes');
39
39
  | `encryptCtr` | `(key: CryptoKey, counter: Uint8Array, counterBits: number, data: Uint8Array) => Promise<Uint8Array\|false>` | Encrypted bytes or `false` |
40
40
  | `decryptCtr` | `(key: CryptoKey, counter: Uint8Array, counterBits: number, data: Uint8Array) => Promise<Uint8Array\|false>` | Decrypted bytes or `false` |
41
41
 
42
- **Defaults**: `lengthBits` = 256, `extractable` for `generateKey` = `true`, `extractable` for `importKey` = `false`, `tagBits` = 128.
42
+ **Defaults**: `lengthBits` = 256, `extractable` = `false` for `generateKey` and `importKey` (pass `true` to export the key), `tagBits` = 128.
43
43
 
44
44
  **IV / counter length requirements**:
45
45
  - GCM: any length; 12 bytes (96-bit) strongly recommended (NIST SP 800-38D §8.2).
@@ -49,7 +49,7 @@ if (!webcryptoAesKw.isAvailable()) {
49
49
  // Fall back to the pure-JS kw module
50
50
  }
51
51
 
52
- // Generate a 256-bit KEK (non-extractable by default in importKek; extractable here)
52
+ // Generate a 256-bit KEK (non-extractable by default, as importKek's; pass true to export it)
53
53
  const kek = await webcryptoAesKw.generateKek(256, false);
54
54
 
55
55
  // The inner key must be extractable for wrapKey to succeed
@@ -109,7 +109,7 @@ const worker = fw.createWorker(
109
109
 
110
110
  - **RFC 3394 AES-KW**: WebCrypto exposes AES-KW only — KWP (with-pad, RFC 5649) is not available via `crypto.subtle`. Use the pure-JS `kw` module for KWP or for environments without `crypto.subtle`.
111
111
  - **Extractable inner key**: the key passed to `wrapKey` must be `extractable: true`; WebCrypto enforces this contract and rejects non-extractable keys — `wrapKey` returns `false` in that case.
112
- - **No-throw contract**: all methods are `async` and resolve to a value or `false`. `crypto.subtle` rejections (integrity failure, invalid parameters) are caught and logged via `console.error('[crypto] FAIL: webcryptoAesKw.<method>: …')`. They never propagate.
112
+ - **No-throw contract**: all methods are `async` and resolve to a value or `false`. `crypto.subtle` rejections are caught: an integrity failure of `unwrapKey` (`OperationError`) is an expected outcome logged via `console.warn('[crypto] CORRUPT: …')`; any other rejection is logged via `console.error('[crypto] FAIL: webcryptoAesKw.<method>: …')`. They never propagate.
113
113
  - **KEK sizes**: AES-KW supports 128, 192, and 256-bit KEKs. `importKek` validates `raw.length ∈ {16, 24, 32}` and returns `false` for other sizes.
114
114
  - **Worker-safe**: `crypto.subtle` is available in Web Workers; this module has no DOM dependency and no main-thread closures.
115
115
 
@@ -19,7 +19,7 @@ Opt-in alternative to the pure-JS hash modules. Async, `Uint8Array` in / `Uint8A
19
19
 
20
20
  ```js
21
21
  const webcryptoDigest = runtime.resolve('webcryptoDigest');
22
- // Returns: { isAvailable, digest, sha256, sha384, sha512, sha1 }
22
+ // Returns: { isAvailable, digest, sha256, sha384, sha512 }
23
23
  ```
24
24
 
25
25
  ## API
@@ -31,7 +31,6 @@ const webcryptoDigest = runtime.resolve('webcryptoDigest');
31
31
  | `sha256` | `(data: Uint8Array) => Promise<Uint8Array\|false>` | SHA-256 shorthand |
32
32
  | `sha384` | `(data: Uint8Array) => Promise<Uint8Array\|false>` | SHA-384 shorthand |
33
33
  | `sha512` | `(data: Uint8Array) => Promise<Uint8Array\|false>` | SHA-512 shorthand |
34
- | `sha1` | `(data: Uint8Array) => Promise<Uint8Array\|false>` | SHA-1 shorthand — emits deprecation warning |
35
34
 
36
35
  `digest` resolves `false` when:
37
36
  - `crypto.subtle` is unavailable (`[crypto] NOT READY` logged)
@@ -70,8 +69,7 @@ if (!webcryptoDigest.isAvailable()) {
70
69
  ### SHA-1 (legacy interop only)
71
70
 
72
71
  ```js
73
- // Emits: [crypto] DEPRECATED: SHA-1 is broken; use SHA-256+
74
- const digest = await webcryptoDigest.sha1(legacyBytes);
72
+ const digest = await webcryptoDigest.digest('SHA-1', legacyBytes);
75
73
  ```
76
74
 
77
75
  ## Worker Usage
@@ -91,7 +89,7 @@ const worker = fw.createWorker(
91
89
  - **Supported algorithms**: WebCrypto mandates exactly SHA-1, SHA-256, SHA-384, SHA-512 (FIPS 180-4). SHA-224, SHA-512/224, SHA-512/256, SHA-3, and BLAKE2b are **not** supported by the WebCrypto spec — use the pure-JS modules for those.
92
90
  - **No-throw contract**: all methods are `async` and resolve to `Uint8Array | false`. `crypto.subtle` rejections are caught and logged; they never propagate.
93
91
  - **Input type**: `data` must be a `Uint8Array`. Strings, `ArrayBuffer`, and `number[]` are rejected with `false`. Encode strings first with `TextEncoder` or `@awacloud/fw`'s `utf8` codec.
94
- - **SHA-1 deprecation**: SHA-1 is cryptographically broken. `sha1()` is provided for legacy interoperability only and always emits `console.warn('[crypto] DEPRECATED: SHA-1 is broken; use SHA-256+')`.
92
+ - **SHA-1**: cryptographically broken; reachable only as `digest('SHA-1', data)`, for legacy interoperability (the `sha1` shorthand is gone).
95
93
  - **Worker-safe**: `crypto.subtle` is available in Web Workers; this module has no DOM dependency and no main-thread closures.
96
94
 
97
95
  ## See also
@@ -35,7 +35,7 @@ const webcryptoEcc = runtime.resolve('webcryptoEcc');
35
35
  | `importKey` | `(format: 'raw'\|'spki'\|'pkcs8'\|'jwk', keyData: Uint8Array\|object, kind: 'ECDSA'\|'ECDH', curve: 'P-256'\|'P-384'\|'P-521', usages: string[], extractable?: boolean) => Promise<CryptoKey\|false>` | `CryptoKey` or `false` |
36
36
  | `exportKey` | `(format: 'raw'\|'spki'\|'pkcs8'\|'jwk', key: CryptoKey) => Promise<Uint8Array\|object\|false>` | `Uint8Array` (DER/raw), object (jwk), or `false` |
37
37
 
38
- ECDSA hash defaults to `SHA-256`; curve defaults to `P-256`. `generateKey` assigns usages by kind — ECDSA → `['sign','verify']`, ECDH → `['deriveBits','deriveKey']`. `importKey` defaults `extractable` to `false` for `pkcs8` (private keys), `true` otherwise. `'raw'` carries the public point only.
38
+ ECDSA hash defaults to `SHA-256`; curve defaults to `P-256`. `generateKey` makes the private key non-extractable unless `extractable` is `true`, and assigns usages by kind — ECDSA → `['sign','verify']`, ECDH → `['deriveBits','deriveKey']`. `importKey` defaults `extractable` to `false` for `pkcs8` (private keys), `true` otherwise. `'raw'` carries the public point only.
39
39
 
40
40
  Operations resolve `false` when:
41
41
  - `crypto.subtle` is unavailable (`[crypto] NOT READY` logged)
@@ -33,7 +33,7 @@ const webcryptoEd25519 = runtime.resolve('webcryptoEd25519');
33
33
  | `importKey` | `(format: 'raw'\|'spki'\|'pkcs8'\|'jwk', keyData: Uint8Array\|object, usages: KeyUsage[], extractable?: boolean) => Promise<CryptoKey\|false>` | Imported `CryptoKey` or `false` |
34
34
  | `exportKey` | `(format: 'raw'\|'spki'\|'pkcs8'\|'jwk', key: CryptoKey) => Promise<Uint8Array\|object\|false>` | Raw/DER → `Uint8Array`; jwk → object; `false` on error |
35
35
 
36
- `generateKey` defaults `extractable` to `true`. `importKey` defaults `extractable` to `false` for `pkcs8` (private key material) and `true` for all other formats.
36
+ `generateKey` defaults `extractable` to `false` (the private key cannot be exported; the public key always can). `importKey` defaults `extractable` to `false` for `pkcs8` (private key material) and `true` for all other formats.
37
37
 
38
38
  Every operation resolves `false` when:
39
39
  - `crypto.subtle` is unavailable (`[crypto] NOT READY` logged)
@@ -46,8 +46,8 @@ const webcryptoRsa = runtime.resolve('webcryptoRsa');
46
46
  | `exportKey` | `(format: 'spki'\|'pkcs8'\|'jwk', key: CryptoKey) => Promise<Uint8Array\|object\|false>` | Export a key (DER → `Uint8Array`, JWK → object) |
47
47
 
48
48
  **Defaults**: `modulusBits = 2048` (also `3072`, `4096`), `hash = 'SHA-256'`
49
- (also `'SHA-384'`, `'SHA-512'`, `'SHA-1'`), `extractable = true` for
50
- `generateKey`. Public exponent is fixed at 65537. `importKey` `extractable`
49
+ (also `'SHA-384'`, `'SHA-512'`, `'SHA-1'`), `extractable = false` for
50
+ `generateKey` (the private key; pass `true` to export it). Public exponent is fixed at 65537. `importKey` `extractable`
51
51
  defaults to `true` for `spki` and `false` otherwise.
52
52
 
53
53
  **PSS salt length**: `sign`/`verify` default `saltLength` to the hash output
@@ -124,6 +124,7 @@ const worker = fw.createWorker(
124
124
 
125
125
  ## Notes
126
126
 
127
+ - **Public exponent above 32 bits under Bun (measured).** Bun's WebCrypto verifies a valid PKCS#1 v1.5 signature to `false` when the public exponent exceeds 32 bits (an ACVP RSA-SigVer FIPS 186-5 key with a 6-byte `e`); Node verifies the same signature to `true`. Keys with `e = 65537` are unaffected.
127
128
  - **Schemes**: WebCrypto exposes exactly RSA-OAEP, RSA-PSS, and
128
129
  RSASSA-PKCS1-v1_5. **PKCS1-v1_5 encryption is not supported** (insecure and
129
130
  absent from the spec) — use OAEP for encryption.
@@ -33,7 +33,7 @@ const webcryptoX25519 = runtime.resolve('webcryptoX25519');
33
33
 
34
34
  ### Parameter details
35
35
 
36
- - `generateKey` — `extractable` defaults to `true`. Key pair usages are `['deriveBits', 'deriveKey']`.
36
+ - `generateKey` — `extractable` defaults to `false` (the private key; the public key always exports). Key pair usages are `['deriveBits', 'deriveKey']`.
37
37
  - `deriveBits` — `lengthBits` defaults to `256` (= 32 bytes). Guards `privateKey.algorithm.name === 'X25519'`.
38
38
  - `deriveKey` — `extractable` defaults to `false`. Guards `privateKey.algorithm.name === 'X25519'`.
39
39
  - `importKey` — `'raw'` format imports a 32-byte public key. `extractable` defaults to `false` for `'pkcs8'`, `true` otherwise.
@@ -43,7 +43,8 @@ Modules for DOM manipulation, events, rendering, storage, and network communicat
43
43
  | [dom](./query/dom.md) | `secPolicy` | no | Selection, styles, attributes, scroll (CSS filtering via `secPolicy`) |
44
44
  | [events](./query/events.md) | none | no | Named event management |
45
45
  | [gesture](./query/gesture.md) | `events` | no | Touch/pointer gestures: tap, swipe, pan, pinch |
46
- | [media](./query/media.md) | none | no | JS media queries |
46
+ | [media](./query/media.md) | none | no | Camera, microphone and screen streams |
47
+ | [sound](./query/sound.md) | none | no | Record and play short sound clips (Web Audio) |
47
48
 
48
49
  ### display
49
50
 
@@ -57,6 +58,7 @@ Modules for DOM manipulation, events, rendering, storage, and network communicat
57
58
  | Module | Deps | Worker-safe | Description |
58
59
  |--------|------|-------------|-------------|
59
60
  | [download](./fs/download.md) | none | no | File download |
61
+ | [fileIntake](./fs/fileIntake.md) | none | no | File intake: picker, OS file drop, keyboard dropzone |
60
62
  | [fsAccess](./fs/fsAccess.md) | none | partial | File System Access API + OPFS (DOM-bound pickers, OPFS worker-safe) |
61
63
  | [indexedDB](./fs/indexedDB.md) | none | no | IndexedDB wrapper |
62
64
  | [remoteStore](./fs/remoteStore.md) | `ajax`, `ws`, `eventBus` | yes | Remote key-value store HTTP/WS + watch + batch |
@@ -79,9 +81,12 @@ Modules for DOM manipulation, events, rendering, storage, and network communicat
79
81
  |--------|------|-------------|-------------|
80
82
  | [backgroundSync](./sw/backgroundSync.md) | `serviceWorker` | no | Background Sync API — offline replay via SyncManager (Chrome only) |
81
83
  | [cache](./sw/cache.md) | none | yes | Cache API wrapper |
84
+ | [installPrompt](./sw/installPrompt.md) | none | no | PWA install prompt deferral + File Handling launch queue |
85
+ | [precache](./sw/precache.md) | `cache` | yes | Worker-side release precache + cache-first / network-first strategies |
82
86
  | [push](./sw/push.md) | `serviceWorker`, `b64` | no | PushManager wrapper — VAPID subscription, subscription, permission |
83
87
  | [serviceWorker](./sw/serviceWorker.md) | none | no | SW lifecycle (window-side) |
84
88
  | [sharedWorker](./sw/sharedWorker.md) | `processRPC` | no | SharedWorker cross-tab connection + bidirectional RPC |
89
+ | [swUpdate](./sw/swUpdate.md) | `serviceWorker` | no | Waiting-release update flow: report once, check, apply, version |
85
90
 
86
91
  ### utils
87
92
 
@@ -7,6 +7,7 @@ Modules for local persistence and file download.
7
7
  | Module | Returns | Deps | Description |
8
8
  |--------|----------|------|-------------|
9
9
  | [download](./download.md) | `object` | none | Client-side file download |
10
+ | [fileIntake](./fileIntake.md) | `object` | none | File intake: picker, OS file drop, keyboard-operable dropzone → `File[]` |
10
11
  | [fsAccess](./fsAccess.md) | `object` | none | File System Access API + OPFS — pick, read, write, list (partial worker-safe) |
11
12
  | [indexedDB](./indexedDB.md) | `object` | `broadcastChannel` | Local key-value database with cross-tab notifications (`namespace`, `crossTab`) |
12
13
  | [remoteStore](./remoteStore.md) | `object` | `ajax`, `ws`, `eventBus` | Remote key-value store — HTTP/WS transport, WS watch, batch, auto-reconnect |
@@ -0,0 +1,120 @@
1
+ ---
2
+ module: fileIntake
3
+ category: dom/fs
4
+ dependencies: []
5
+ returns: object
6
+ worker-safe: false
7
+ status: complete
8
+ ---
9
+
10
+ # fileIntake
11
+
12
+ > File intake: picker, OS file drop and a keyboard-operable dropzone, one callback.
13
+
14
+ **Module** `fileIntake` | **Source** `packages/front/fw/src/dom/fs/fileIntake.js` | **Deps** none | **Worker-safe** no
15
+
16
+ ## Resolve
17
+
18
+ ```js
19
+ const fileIntake = runtime.resolve('fileIntake');
20
+ // Returns: { create }
21
+ ```
22
+
23
+ ## API
24
+
25
+ | Method | Signature | Returns |
26
+ |--------|-----------|---------|
27
+ | `create` | `(opts: FileIntakeOptions) => FileIntakeInstance` | Wire a picker, a drop target and a dropzone to one `onFiles` callback |
28
+
29
+ ### `create(opts)` options
30
+
31
+ | Option | Type | Required | Meaning |
32
+ |--------|------|----------|---------|
33
+ | `input` | `HTMLInputElement` | yes | The `type="file"` picker; its `change` event is read |
34
+ | `onFiles` | `(files: File[], source: 'picker' \| 'drop') => void` | yes | Every file chosen or dropped at once, in order; never called with an empty array |
35
+ | `dropTarget` | `EventTarget` | no | Where OS drops are accepted (typically the whole component region); without it there is no drop wiring |
36
+ | `zone` | `HTMLElement` | no | The keyboard-operable dropzone; without it there is no keyboard wiring |
37
+ | `dragoverAttribute` | `string` | no | Attribute set to `'true'` / `'false'` on `zone` and on `dropTarget` (when it has `setAttribute`) while a file drag is over the target. Default `'data-dragover'` |
38
+
39
+ `create` throws `TypeError('fileIntake.create: input is required')` when `input` is missing or has no `addEventListener`, and `TypeError('fileIntake.create: onFiles must be a function')` when `onFiles` is not a function.
40
+
41
+ ### Instance
42
+
43
+ | Method | Signature | Returns |
44
+ |--------|-----------|---------|
45
+ | `pick` | `() => void` | Opens the file picker (`input.click()`) |
46
+ | `focus` | `() => void` | Focuses the zone (no-op without a zone) |
47
+ | `dispose` | `() => void` | Removes every listener the instance added and resets a marked drag attribute to `'false'`; `pick` and `focus` are no-ops afterwards |
48
+
49
+ ### Behaviour
50
+
51
+ - **Picker**: on `change`, the chosen files are collected, the input is reset (`input.value = ''`, so choosing the same file again fires), and `onFiles(files, 'picker')` runs when the list is not empty.
52
+ - **Drop** (with `dropTarget`): `dragenter` and `dragover` call `preventDefault` (`dragover` also sets `dropEffect` to `'copy'`), `dragleave` unmarks once the drag has left every nested element, and `drop` calls `onFiles(files, 'drop')` when files were dropped.
53
+ - **Keyboard** (with `zone`): Enter and Space call `preventDefault` then open the picker; other keys are untouched. A zone without a `tabindex` attribute gets `tabIndex = 0`; an existing `tabindex` is respected.
54
+ - The module sets no `role` and no text: the markup is the caller's.
55
+
56
+ ## Examples
57
+
58
+ ### A dropzone that opens the first file and announces the rest
59
+
60
+ ```js
61
+ const { create } = runtime.resolve('fileIntake');
62
+
63
+ // Markup owned by the page:
64
+ // <section id="viewer">
65
+ // <label id="zone" for="file">Drop a document here, or choose one</label>
66
+ // <input id="file" type="file" accept=".pdf,.docx,.md" multiple hidden>
67
+ // <p id="status" role="status"></p>
68
+ // </section>
69
+ const input = document.getElementById('file');
70
+ const zone = document.getElementById('zone');
71
+ const region = document.getElementById('viewer');
72
+ const status = document.getElementById('status');
73
+
74
+ const intake = create({
75
+ input,
76
+ zone,
77
+ dropTarget: region,
78
+ onFiles(files, source) {
79
+ openDocument(files[0]);
80
+ if (files.length > 1) {
81
+ status.textContent = `${files.length - 1} more file(s) ignored (${source}).`;
82
+ }
83
+ }
84
+ });
85
+
86
+ // A button elsewhere can open the picker; focus returns to the zone on close.
87
+ document.getElementById('open').addEventListener('click', () => intake.pick());
88
+
89
+ // Style the drag-over state from the attribute:
90
+ // [data-dragover="true"] { outline: 2px dashed currentColor; }
91
+
92
+ intake.dispose(); // when the component is torn down
93
+ ```
94
+
95
+ ### Refuse by type in the consumer
96
+
97
+ ```js
98
+ create({
99
+ input,
100
+ onFiles(files) {
101
+ const accepted = files.filter((f) => f.type === 'application/pdf');
102
+ if (accepted.length < files.length) reportRefused(files.length - accepted.length);
103
+ accepted.forEach(open);
104
+ }
105
+ });
106
+ ```
107
+
108
+ ## Notes
109
+
110
+ - Drags that do not carry `Files` (selected text, a link) are ignored entirely: no `preventDefault`, no attribute, so the browser keeps its native behaviour.
111
+ - A depth counter pairs `dragenter` with `dragleave`, so entering and leaving nested children does not flicker the drag attribute; it returns to `'false'` only when the drag has left the target.
112
+ - The module never reads a file, never filters by type or size and never creates an element: `accept` and `multiple` stay attributes of the caller's input, and refusal is the consumer's decision.
113
+ - The picker is the alternative to dragging (WCAG 2.2, 2.5.7 Dragging Movements); the keyboard wiring makes the zone operable without a pointer.
114
+ - Element drag-and-drop is [dnd](../query/dnd.md) and the File System Access API is [fsAccess](./fsAccess.md); this module covers the legacy File API (`<input type="file">` and `dataTransfer.files`), which works in every browser.
115
+
116
+ ## See also
117
+
118
+ - [fsAccess](./fsAccess.md) — File System Access API and OPFS (handles, pickers)
119
+ - [dnd](../query/dnd.md) — pointer-based element drag-and-drop
120
+ - [download](./download.md) — file export without a picker
@@ -197,4 +197,5 @@ For OPFS from a dedicated worker, `FileSystemSyncAccessHandle` (synchronous API)
197
197
  - [indexedDB](./indexedDB.md) — structured key-value persistence (IndexedDB)
198
198
  - [storage](./storage.md) — localStorage / sessionStorage cross-tab
199
199
  - [download](./download.md) — file export without a picker
200
+ - [fileIntake](./fileIntake.md) — OS file drop and the `<input type=file>` picker
200
201
  - [mutex](../../io/sync/mutex.md) — async lock for concurrent OPFS writers
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: indexedDB
3
3
  category: dom/fs
4
- dependencies: ['broadcastChannel']
4
+ dependencies: [broadcastChannel]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  module: storage
3
3
  category: dom/fs
4
- dependencies: ['broadcastChannel']
4
+ dependencies: [broadcastChannel]
5
5
  returns: object
6
6
  worker-safe: false
7
7
  status: complete
@@ -10,7 +10,8 @@ Modules for querying and manipulating the DOM, managing events, and responding t
10
10
  | [dom](./dom.md) | `object` | `secPolicy` | Selection, attributes, styles, scroll, focus (CSS filtering via `secPolicy`) |
11
11
  | [events](./events.md) | `object` | none | Named events with lifecycle management |
12
12
  | [gesture](./gesture.md) | `object` | `events` | Touch/pointer gestures: tap, swipe, pan, pinch |
13
- | [media](./media.md) | `object` | none | JS media queries |
13
+ | [media](./media.md) | `object` | none | Camera, microphone and screen streams (`getUserMedia`, `getDisplayMedia`), device registry |
14
+ | [sound](./sound.md) | `object` | none | Short sound clips in memory: record from a microphone stream, trim / normalize, WAV bytes, play at any rate |
14
15
 
15
16
  ## Common pattern
16
17
 
@@ -41,7 +41,7 @@ Makes `el` draggable via Pointer Events. The drag only starts after the pointer
41
41
  | Option | Type | Default | Description |
42
42
  |--------|------|--------|-------------|
43
43
  | `data` | `() => any` | — | **Required.** Serialisable drag data, called at start. |
44
- | `preview` | `(data) => HTMLElement` | clone of `el` at opacity 0.6 | Visual element following the pointer. |
44
+ | `preview` | `(data) => HTMLElement` | clone of `el` at opacity 0.6, at `el`'s rendered width and height (`box-sizing: border-box`) | Visual element following the pointer. A custom preview is used as given. |
45
45
  | `handle` | `string \| Element` | `el` | Selector or element — drag only starts from this sub-element. |
46
46
  | `axis` | `'x' \| 'y' \| 'both'` | `'both'` | Axis constraint. |
47
47
  | `threshold` | `number` (px) | `5` | Distance before the drag is recognised. |
@@ -129,9 +129,12 @@ dnd.draggable(row, { data: () => ({ row: row.dataset.index }), axis: 'y' });
129
129
  - `dnd:start` and `dnd:end` are emitted via native `dispatchEvent` on `document` to allow observability without a dependency on `eventBus`.
130
130
  - Hovered zone detection uses `document.elementsFromPoint`; in the absence of this API (test environment without a full DOM), no drop target fires.
131
131
  - `pointer-events: none` on the preview prevents interference with `elementsFromPoint`.
132
+ - The default clone is sized like its source: appended to `<body>` with `position: fixed`, an unsized clone would take its intrinsic width (wider or narrower than the original). Inherited styles (colour, font, a background set on the source's container) are not copied: give the source its own, or pass a `preview`.
133
+ - While a drag is active the document's `user-select` is `none` (its inline value restored at the end, on cancel and on dispose), and a selection the gesture itself started is cleared; a selection the page had before is kept.
132
134
 
133
135
  ## See also
134
136
 
135
137
  - [gesture](./gesture.md) — touch/pointer gestures (tap, swipe, pinch)
136
138
  - [events](./events.md) — named listeners with lifecycle
137
139
  - [fsAccess](../fs/fsAccess.md) — file drag from the OS
140
+ - [fileIntake](../fs/fileIntake.md) — OS file drop and the `<input type=file>` picker
@@ -268,6 +268,11 @@ dom.style(ui.get('card', 'title'), 'fontWeight', 'bold');
268
268
  dom.attr(ui.get('card', 'link'), 'href', '/detail/1');
269
269
  ```
270
270
 
271
+ ## Notes
272
+
273
+ - Only `style` writes are filtered (`secPolicy.isSafeCss`: `expression(…)`, `url(javascript:…)`, `behavior`). `attr` calls `setAttribute` with the value as given — it does not check URL-bearing attributes or refuse `on*` names, so a value that is not yours goes through the rendering path (`template`, `render`) or `sanitize`, which do.
274
+ - The helpers take and return plain DOM nodes and keep no reference to them: a node removed from the document is collected as usual.
275
+
271
276
  ## See also
272
277
 
273
278
  - [events](./events.md) — event management
@@ -0,0 +1,103 @@
1
+ ---
2
+ module: sound
3
+ category: dom/query
4
+ dependencies: []
5
+ returns: object
6
+ worker-safe: false
7
+ status: complete
8
+ ---
9
+
10
+ # sound
11
+
12
+ > Short sound clips in memory — record from a microphone stream, shape, encode as WAV, play at any rate.
13
+
14
+ **Module** `sound` | **Source** `packages/front/fw/src/dom/query/sound.js` | **Deps** none | **Worker-safe** no
15
+
16
+ Built for clips of a second or two (a voice tag, a sound effect). A clip is an
17
+ `AudioBuffer` held in memory: nothing is written to storage and nothing is sent
18
+ anywhere. Moving a clip is the caller's business — `clip.bytes()` on one side,
19
+ `fromBytes` on the other. Main thread only (Web Audio and `MediaRecorder` do not
20
+ exist in workers); compatible with sanity `base`.
21
+
22
+ ## Resolve
23
+
24
+ ```js
25
+ const sound = runtime.resolve('sound');
26
+ // Returns: { support, unlock, record, fromBytes, fromBuffer, trim, normalize, play, rate, disposeAll }
27
+ ```
28
+
29
+ ## API
30
+
31
+ | Method | Signature | Returns |
32
+ |--------|-----------|---------|
33
+ | `support()` | `() => {context, recorder, mimeTypes}` | What this browser offers; `mimeTypes` are the recorder formats it can write |
34
+ | `unlock()` | `() => Promise<void>` | Creates the `AudioContext` and resumes it — call it from a user gesture before the first `play` |
35
+ | `record(source, opts?)` | `(StreamHandle \| MediaStream, {maxMs = 1500, mimeType?}) => Recording` | Starts recording; stops on its own at `maxMs` |
36
+ | `fromBytes(bytes)` | `(ArrayBuffer) => Promise<Clip>` | Decodes WAV, Ogg, WebM … (`decodeAudioData`), resampled to the context's rate |
37
+ | `fromBuffer(buffer)` | `(AudioBuffer) => Clip` | A clip from samples you made |
38
+ | `trim(clip, opts?)` | `(Clip, {thresholdDb = -45}) => Clip` | Drops leading and trailing samples quieter than the threshold (a silent clip keeps one sample) |
39
+ | `normalize(clip, opts?)` | `(Clip, {peak = 0.9}) => Clip` | Scales the clip so its loudest sample is `peak` |
40
+ | `play(clip, opts?)` | `(Clip, {rate = 1, gain = 1, when?}) => Voice` | Plays it; `rate` is the playback rate (pitch and speed together), `when` a context time |
41
+ | `rate(semitones)` | `(number) => number` | `2^(s/12)`: `rate(12)` is an octave up, `rate(-5)` a fourth down |
42
+ | `disposeAll()` | `() => Promise<void>` | Stops every voice, disposes every clip, closes the context |
43
+
44
+ `trim`, `normalize` and the `from*` entries return **new** clips; the source clip is
45
+ left as it was.
46
+
47
+ ### `Recording`
48
+
49
+ | Member | Description |
50
+ |---|---|
51
+ | `level()` | Live RMS level of the input, 0..1 — for a record meter; 0 once stopped |
52
+ | `stop()` | `Promise<Clip>`: stops and decodes. Idempotent: after the `maxMs` auto-stop it returns that clip |
53
+ | `cancel()` | Drops the recording; a later `stop()` rejects |
54
+
55
+ ### `Clip` and `Voice`
56
+
57
+ | Member | Description |
58
+ |---|---|
59
+ | `clip.id`, `durationMs`, `sampleRate`, `channels`, `buffer` | Its identity and its `AudioBuffer` |
60
+ | `clip.bytes()` | `Promise<ArrayBuffer>`: a 16-bit PCM WAV of the clip's current buffer |
61
+ | `clip.dispose()` | Releases it; any later use of the clip throws `TypeError` |
62
+ | `voice.stop()`, `voice.ended` | Stop it; a promise that resolves when it ends or is stopped |
63
+
64
+ Misuse throws `TypeError`: a source that is not a stream, a `maxMs` that is not
65
+ positive, a `mimeType` the recorder cannot write, a disposed clip, a rate that is
66
+ not positive, a negative gain.
67
+
68
+ ## Examples
69
+
70
+ ```js
71
+ const { media, sound } = fw.runtime.resolveAll(['media', 'sound']);
72
+
73
+ button.addEventListener('click', async () => {
74
+ await sound.unlock(); // inside the gesture
75
+ const mic = await media.audio.start();
76
+ const rec = sound.record(mic, { maxMs: 1500 });
77
+ meter.update(() => rec.level());
78
+ const clip = sound.normalize(sound.trim(await rec.stop()));
79
+ mic.stop();
80
+
81
+ sound.play(clip, { rate: sound.rate(4) }); // a major third up
82
+ peer.send(await clip.bytes()); // WAV bytes, yours to move
83
+ });
84
+
85
+ // on the receiving side
86
+ const clip = await sound.fromBytes(bytesFromPeer);
87
+ sound.play(clip, { rate: sound.rate(-3), gain: 0.8 });
88
+ ```
89
+
90
+ ## Notes
91
+
92
+ - **WAV clips at full scale**: 16-bit PCM holds -1..1. A recorder's decoded clip can reach a little past full scale (measured: 1.03 on Chromium's fake microphone, 6 samples in 0.6 s); `bytes()` clamps those. `normalize()` before `bytes()` keeps the peaks.
93
+ - **Rates**: `fromBytes` decodes to the context's sample rate, whatever the WAV says; the clip's `sampleRate` is that rate.
94
+ - **Measured in Chromium 148** (fake microphone): a 600 ms recording stopped by `maxMs`, its WAV decoded back within 1.4 LSB of 16 bits, trim, normalize to 0.9, and a play at `rate(5)` lasting `durationMs / rate` (125 ms for 128 expected).
95
+ - **Memory only**: the module never touches storage or the network; `disposeAll()` releases everything it holds.
96
+
97
+ ## Scope and boundary
98
+
99
+ `sound` holds short clips: it records through `MediaRecorder`, keeps an `AudioBuffer` in memory and plays it. It does not process audio frame by frame. Continuous capture and playback as 128-sample frames over a port, in an `AudioWorklet`, is the `audio.webaudio` module of `@awacloud/media-audio` (monorepo directory `packages/front/media/audio`, experimental, not on npm). The two modules share no public member and each creates its own `AudioContext`; whether fw absorbs the second is re-examined in a 1.x minor.
100
+
101
+ ## See also
102
+
103
+ - [media](./media.md) — the `StreamHandle` `record` takes (`media.audio.start()`)
@@ -24,10 +24,11 @@ Live DOM nodes
24
24
  | [parser](./parser.md) | HTML ↔ elm-array | `secPolicy` |
25
25
  | [render](./render.md) | Data transformer (no DOM) | `secPolicy` |
26
26
  | [sanitize](./sanitize.md) | Allowlist-based HTML sanitiser (XSS) | `secPolicy` |
27
- | [template](./template.md) | DOM engine, contexts, catalogue | `secPolicy` |
28
- | [themeTokens](./themeTokens.md) | CSS Custom Properties design tokens | `dom` |
27
+ | [template](./template.md) | DOM engine, contexts, catalogue | `secPolicy`, `styleSheet` |
28
+ | [themeTokens](./themeTokens.md) | CSS Custom Properties design tokens | `dom`, `styleSheet` |
29
+ | [styleSheet](./styleSheet.md) | Attach CSS text as a `<style>` element or a constructable stylesheet | none |
29
30
  | [uiSession](./uiSession.md) | High-level facade | `uiSessionCore`, `uiSessionDirect`, `uiSessionList` |
30
- | [component](./component.md) | Reusable component (template + state + lifecycle) | none |
31
+ | [component](./component.md) | Reusable component (template + state + lifecycle) | `reactiveBind`, `styleSheet` |
31
32
  | [reactiveBind](./reactiveBind.md) | Explicit signal→DOM binding controller (patch via uiSession, no re-render) | `signal` |
32
33
  | [virtualScroll](./virtualScroll.md) | Virtualised list for 10⁴–10⁶ items | `dom`, `events` |
33
34
  | [chart](./chart.md) | Canvas 2D charts — line, area, bar, sparkline | `dom`, `animate`, `stats`, `linalg` |
@@ -37,7 +37,7 @@ const chart = runtime.resolve('chart');
37
37
  |--------|------|--------|-------------|
38
38
  | `el` | `HTMLCanvasElement \| HTMLElement` | — | Canvas or container (canvas auto-created) |
39
39
  | `data` | `number[] \| {x:number,y:number}[]` | `[]` | Data to display |
40
- | `color` | `string` | `'#4a9eff'` | Primary CSS colour |
40
+ | `color` | `string` | `'#4a9eff'` | Primary colour: any CSS colour (`#abc`, 8-digit hex, `rgb()`, `hsl()`, a name). Area and bar fills are the same colour made translucent by `globalAlpha` (0.2 and 0.667) |
41
41
  | `animate` | `number \| false` | `false` | Animation duration in ms, or `false` |
42
42
 
43
43
  ### `line` / `area` options
@@ -53,8 +53,8 @@ const chart = runtime.resolve('chart');
53
53
  | Option | Type | Default | Description |
54
54
  |--------|------|--------|-------------|
55
55
  | `label` | `string?` | — | Axis label (not displayed in MVP) |
56
- | `ticks` | `number[]?` | auto (5) | Tick values |
57
- | `format` | `(v: number) => string` | `String(round(v))` | Tick formatter |
56
+ | `ticks` | `number[]?` | auto: round values (a step of 1, 2, 2.5 or 5 × 10ⁿ, at most 4 intervals) inside the domain | Tick values |
57
+ | `format` | `(v: number) => string` | auto ticks: the value at its step's precision; given `ticks`: rounded to 2 decimals | Tick formatter |
58
58
  | `domain` | `[min, max]?` | auto-fit | Explicit domain |
59
59
 
60
60
  ### `ChartHandle` interface
@@ -135,7 +135,8 @@ h.dispose();
135
135
  ## Notes
136
136
 
137
137
  - DPR-aware: `canvas.width = displayWidth * devicePixelRatio` + `ctx.scale(dpr, dpr)` — rendering stays sharp on Retina displays.
138
- - Auto-fit domain: if `domain` is not provided, the domain is computed from `stats.min/max` with 5% padding. If all values are identical, the domain is widened by ±1.
138
+ - Auto-fit domain: if `domain` is not provided, the domain is computed from `stats.min/max` with 5% padding. If all values are identical, the domain is widened by ±1. The automatic ticks are round values inside that domain (300–1000 ms gives 400, 600, 800, 1000), so the axis ends need not carry a label.
139
+ - Plot padding: the left padding fits the widest y label (`format` included — `"1000 ms"` is not clipped) and half the first x label, the right one half the last x label; never below 40 / 10 px. `handle._state.pad` holds the last draw's values.
139
140
  - `sparkline` displays no axes or ticks — ideal for compact inline trend indicators.
140
141
  - No tooltip, no interactivity, no PNG export in the MVP — deliberately out of scope to stay lightweight.
141
142
  - `ResizeObserver` is attached only when `el` is an HTML container (not a `<canvas>`) — call `resize()` manually if the canvas is resized directly.