@awacloud/fw 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (609) hide show
  1. package/CHANGELOG.md +125 -0
  2. package/NOTICE +8 -0
  3. package/README.md +163 -31
  4. package/dist/build/fw.core.pure.meta.json +6 -6
  5. package/dist/build/fw.core.pure.min.js +15 -12
  6. package/dist/build/fw.full.pure.meta.json +13 -7
  7. package/dist/build/fw.full.pure.min.js +45 -42
  8. package/dist/build/fw.minimal.pure.meta.json +6 -6
  9. package/dist/build/fw.minimal.pure.min.js +16 -13
  10. package/dist/build/fw.pack.compress-heavy.pure.meta.json +6 -6
  11. package/dist/build/fw.pack.compress-heavy.pure.min.js +3 -3
  12. package/dist/build/fw.pack.crypto-advanced.pure.meta.json +6 -6
  13. package/dist/build/fw.pack.crypto-advanced.pure.min.js +1 -1
  14. package/dist/build/fw.pack.crypto-basic.pure.meta.json +6 -6
  15. package/dist/build/fw.pack.crypto-basic.pure.min.js +1 -1
  16. package/dist/build/fw.pack.crypto-identity.pure.meta.json +7 -6
  17. package/dist/build/fw.pack.crypto-identity.pure.min.js +4 -4
  18. package/dist/build/fw.pwa.pure.meta.json +7 -6
  19. package/dist/build/fw.pwa.pure.min.js +38 -35
  20. package/dist/build/fw.site-interactive.pure.meta.json +6 -6
  21. package/dist/build/fw.site-interactive.pure.min.js +37 -34
  22. package/dist/build/fw.site.pure.meta.json +6 -6
  23. package/dist/build/fw.site.pure.min.js +24 -21
  24. package/dist/build/fw.spa.pure.meta.json +8 -7
  25. package/dist/build/fw.spa.pure.min.js +41 -38
  26. package/dist/build/sanity-base-classic.min.js +1 -1
  27. package/dist/build/sanity.min.js +1 -1
  28. package/dist/types/core/internal.d.ts +29 -0
  29. package/dist/types/core/internal.d.ts.map +1 -0
  30. package/dist/types/core/logger.d.ts +23 -4
  31. package/dist/types/core/logger.d.ts.map +1 -1
  32. package/dist/types/core/modules.d.ts +374 -61
  33. package/dist/types/core/modules.d.ts.map +1 -1
  34. package/dist/types/core/runtime.d.ts +10 -6
  35. package/dist/types/core/runtime.d.ts.map +1 -1
  36. package/dist/types/core/worker-helper.d.ts +35 -0
  37. package/dist/types/core/worker-helper.d.ts.map +1 -1
  38. package/dist/types/crypto/cipher/aes.d.ts +1 -7
  39. package/dist/types/crypto/cipher/aes.d.ts.map +1 -1
  40. package/dist/types/crypto/cipher/chacha20.d.ts +0 -10
  41. package/dist/types/crypto/cipher/chacha20.d.ts.map +1 -1
  42. package/dist/types/crypto/hash/argon2.d.ts +0 -15
  43. package/dist/types/crypto/hash/argon2.d.ts.map +1 -1
  44. package/dist/types/crypto/hash/blake2b.d.ts.map +1 -1
  45. package/dist/types/crypto/hash/hmac.d.ts.map +1 -1
  46. package/dist/types/crypto/hash/pbkdf2.d.ts.map +1 -1
  47. package/dist/types/crypto/hash/poly1305.d.ts.map +1 -1
  48. package/dist/types/crypto/hash/sha224.d.ts +1 -1
  49. package/dist/types/crypto/hash/sha256.d.ts +4 -13
  50. package/dist/types/crypto/hash/sha256.d.ts.map +1 -1
  51. package/dist/types/crypto/hash/sha3.d.ts.map +1 -1
  52. package/dist/types/crypto/hash/sha384.d.ts +1 -1
  53. package/dist/types/crypto/hash/sha512.d.ts +4 -13
  54. package/dist/types/crypto/hash/sha512.d.ts.map +1 -1
  55. package/dist/types/crypto/mode/cmac.d.ts +0 -6
  56. package/dist/types/crypto/mode/cmac.d.ts.map +1 -1
  57. package/dist/types/crypto/mode/ctr.d.ts +0 -6
  58. package/dist/types/crypto/mode/ctr.d.ts.map +1 -1
  59. package/dist/types/crypto/mode/gcm.d.ts +0 -9
  60. package/dist/types/crypto/mode/gcm.d.ts.map +1 -1
  61. package/dist/types/crypto/pkc/ecc.d.ts +0 -1
  62. package/dist/types/crypto/pkc/ecc.d.ts.map +1 -1
  63. package/dist/types/crypto/pkc/ed25519.d.ts +4 -25
  64. package/dist/types/crypto/pkc/ed25519.d.ts.map +1 -1
  65. package/dist/types/crypto/pkc/hybridSign.d.ts +25 -5
  66. package/dist/types/crypto/pkc/hybridSign.d.ts.map +1 -1
  67. package/dist/types/crypto/pkc/ml_dsa.d.ts +6 -26
  68. package/dist/types/crypto/pkc/ml_dsa.d.ts.map +1 -1
  69. package/dist/types/crypto/pkc/ml_kem.d.ts +0 -43
  70. package/dist/types/crypto/pkc/ml_kem.d.ts.map +1 -1
  71. package/dist/types/crypto/pkc/rsa.d.ts +0 -24
  72. package/dist/types/crypto/pkc/rsa.d.ts.map +1 -1
  73. package/dist/types/crypto/pkc/slh_dsa.d.ts +6 -16
  74. package/dist/types/crypto/pkc/slh_dsa.d.ts.map +1 -1
  75. package/dist/types/crypto/pkc/x25519.d.ts +0 -6
  76. package/dist/types/crypto/pkc/x25519.d.ts.map +1 -1
  77. package/dist/types/crypto/utils/bitArray.d.ts +0 -8
  78. package/dist/types/crypto/utils/bitArray.d.ts.map +1 -1
  79. package/dist/types/crypto/utils/jws.d.ts +6 -14
  80. package/dist/types/crypto/utils/jws.d.ts.map +1 -1
  81. package/dist/types/crypto/utils/keyformat.d.ts +52 -0
  82. package/dist/types/crypto/utils/keyformat.d.ts.map +1 -1
  83. package/dist/types/crypto/utils/random.d.ts +1 -10
  84. package/dist/types/crypto/utils/random.d.ts.map +1 -1
  85. package/dist/types/crypto/utils/rsaKeygen.d.ts +0 -10
  86. package/dist/types/crypto/utils/rsaKeygen.d.ts.map +1 -1
  87. package/dist/types/crypto/utils/uuid.d.ts.map +1 -1
  88. package/dist/types/crypto/utils/x509.d.ts +397 -0
  89. package/dist/types/crypto/utils/x509.d.ts.map +1 -0
  90. package/dist/types/crypto/wasm/argon2.d.ts +2 -1
  91. package/dist/types/crypto/wasm/argon2.d.ts.map +1 -1
  92. package/dist/types/crypto/wasm/pbkdf2.d.ts +2 -2
  93. package/dist/types/crypto/wasm/pbkdf2.d.ts.map +1 -1
  94. package/dist/types/crypto/wasm/rsa.d.ts.map +1 -1
  95. package/dist/types/crypto/wasm/runtime.d.ts +13 -0
  96. package/dist/types/crypto/wasm/runtime.d.ts.map +1 -1
  97. package/dist/types/crypto/webcrypto/aes.d.ts.map +1 -1
  98. package/dist/types/crypto/webcrypto/aeskw.d.ts.map +1 -1
  99. package/dist/types/crypto/webcrypto/digest.d.ts +0 -4
  100. package/dist/types/crypto/webcrypto/digest.d.ts.map +1 -1
  101. package/dist/types/crypto/webcrypto/rsa.d.ts.map +1 -1
  102. package/dist/types/dom/fs/fileIntake.d.ts +59 -0
  103. package/dist/types/dom/fs/fileIntake.d.ts.map +1 -0
  104. package/dist/types/dom/fs/fsAccess.d.ts.map +1 -1
  105. package/dist/types/dom/query/dnd.d.ts.map +1 -1
  106. package/dist/types/dom/query/sound.d.ts +89 -0
  107. package/dist/types/dom/query/sound.d.ts.map +1 -0
  108. package/dist/types/dom/rendering/chart.d.ts.map +1 -1
  109. package/dist/types/dom/rendering/component.d.ts +9 -3
  110. package/dist/types/dom/rendering/component.d.ts.map +1 -1
  111. package/dist/types/dom/rendering/parser.d.ts +39 -0
  112. package/dist/types/dom/rendering/parser.d.ts.map +1 -1
  113. package/dist/types/dom/rendering/render.d.ts.map +1 -1
  114. package/dist/types/dom/rendering/sanitize.d.ts +4 -0
  115. package/dist/types/dom/rendering/sanitize.d.ts.map +1 -1
  116. package/dist/types/dom/rendering/secPolicy.d.ts.map +1 -1
  117. package/dist/types/dom/rendering/styleSheet.d.ts +74 -0
  118. package/dist/types/dom/rendering/styleSheet.d.ts.map +1 -0
  119. package/dist/types/dom/rendering/template.d.ts +9 -3
  120. package/dist/types/dom/rendering/template.d.ts.map +1 -1
  121. package/dist/types/dom/rendering/themeTokens.d.ts +9 -3
  122. package/dist/types/dom/rendering/themeTokens.d.ts.map +1 -1
  123. package/dist/types/dom/rendering/uiSession-core.d.ts +9 -3
  124. package/dist/types/dom/rendering/uiSession-core.d.ts.map +1 -1
  125. package/dist/types/dom/rendering/uiSession-list.d.ts +9 -3
  126. package/dist/types/dom/rendering/uiSession-list.d.ts.map +1 -1
  127. package/dist/types/dom/rendering/uiSession.d.ts +18 -6
  128. package/dist/types/dom/rendering/uiSession.d.ts.map +1 -1
  129. package/dist/types/dom/sw/installPrompt.d.ts +89 -0
  130. package/dist/types/dom/sw/installPrompt.d.ts.map +1 -0
  131. package/dist/types/dom/sw/precache.d.ts +149 -0
  132. package/dist/types/dom/sw/precache.d.ts.map +1 -0
  133. package/dist/types/dom/sw/swUpdate.d.ts +129 -0
  134. package/dist/types/dom/sw/swUpdate.d.ts.map +1 -0
  135. package/dist/types/dom/utils/clipboard.d.ts +8 -0
  136. package/dist/types/dom/utils/clipboard.d.ts.map +1 -1
  137. package/dist/types/dom/utils/keybindings.d.ts.map +1 -1
  138. package/dist/types/dom/utils/route.d.ts.map +1 -1
  139. package/dist/types/dom/utils/ua.d.ts +2 -2
  140. package/dist/types/dom/utils/ua.d.ts.map +1 -1
  141. package/dist/types/io/calc/crc32.d.ts.map +1 -1
  142. package/dist/types/io/codec/b64.d.ts +24 -0
  143. package/dist/types/io/codec/b64.d.ts.map +1 -1
  144. package/dist/types/io/codec/cbor.d.ts +1 -0
  145. package/dist/types/io/codec/cbor.d.ts.map +1 -1
  146. package/dist/types/io/codec/hex.d.ts.map +1 -1
  147. package/dist/types/io/codec/msgpack.d.ts +1 -0
  148. package/dist/types/io/codec/msgpack.d.ts.map +1 -1
  149. package/dist/types/io/codec/url.d.ts +3 -1
  150. package/dist/types/io/codec/url.d.ts.map +1 -1
  151. package/dist/types/io/codec/utf8.d.ts.map +1 -1
  152. package/dist/types/io/compress/bitstream.d.ts +1 -1
  153. package/dist/types/io/compress/brotli.d.ts +0 -1
  154. package/dist/types/io/compress/brotli.d.ts.map +1 -1
  155. package/dist/types/io/compress/brotli_shared.d.ts +0 -4
  156. package/dist/types/io/compress/brotli_shared.d.ts.map +1 -1
  157. package/dist/types/io/compress/deflate.d.ts +14 -1
  158. package/dist/types/io/compress/deflate.d.ts.map +1 -1
  159. package/dist/types/io/compress/gzip.d.ts +4 -0
  160. package/dist/types/io/compress/gzip.d.ts.map +1 -1
  161. package/dist/types/io/compress/huffman.d.ts +7 -0
  162. package/dist/types/io/compress/huffman.d.ts.map +1 -1
  163. package/dist/types/io/compress/lz4.d.ts +4 -2
  164. package/dist/types/io/compress/lz4.d.ts.map +1 -1
  165. package/dist/types/io/compress/lz77.d.ts +17 -0
  166. package/dist/types/io/compress/lz77.d.ts.map +1 -1
  167. package/dist/types/io/compress/lzw.d.ts +2 -0
  168. package/dist/types/io/compress/lzw.d.ts.map +1 -1
  169. package/dist/types/io/compress/zip.d.ts.map +1 -1
  170. package/dist/types/io/compress/zlib.d.ts +9 -2
  171. package/dist/types/io/compress/zlib.d.ts.map +1 -1
  172. package/dist/types/io/math/linalg.d.ts.map +1 -1
  173. package/dist/types/process/rpc.d.ts.map +1 -1
  174. package/dist/types/process/workerPool.d.ts.map +1 -1
  175. package/dist/types/sanity/base.d.ts +12 -2
  176. package/dist/types/sanity/base.d.ts.map +1 -1
  177. package/dist/types/sanity/lockdown.d.ts +6 -5
  178. package/dist/types/sanity/lockdown.d.ts.map +1 -1
  179. package/dist/types/sanity/wasm-gate.d.ts +1 -1
  180. package/docs/README.md +17 -10
  181. package/docs/api/README.md +5 -5
  182. package/docs/api/core/logger.md +2 -1
  183. package/docs/api/core/modules.md +3 -3
  184. package/docs/api/core/runtime.md +9 -9
  185. package/docs/api/core/worker-helper.md +12 -2
  186. package/docs/api/crypto/README.md +1 -1
  187. package/docs/api/crypto/cipher/README.md +2 -2
  188. package/docs/api/crypto/cipher/aes.md +5 -10
  189. package/docs/api/crypto/cipher/chacha20.md +3 -8
  190. package/docs/api/crypto/hash/README.md +5 -5
  191. package/docs/api/crypto/hash/adf.md +21 -11
  192. package/docs/api/crypto/hash/argon2.md +3 -12
  193. package/docs/api/crypto/hash/blake2b.md +12 -14
  194. package/docs/api/crypto/hash/pbkdf2.md +1 -1
  195. package/docs/api/crypto/hash/sha224.md +2 -2
  196. package/docs/api/crypto/hash/sha256.md +4 -4
  197. package/docs/api/crypto/hash/sha3.md +2 -2
  198. package/docs/api/crypto/hash/sha384.md +1 -1
  199. package/docs/api/crypto/hash/sha512.md +5 -5
  200. package/docs/api/crypto/hash/sha512_224.md +1 -1
  201. package/docs/api/crypto/hash/sha512_256.md +1 -1
  202. package/docs/api/crypto/mode/README.md +3 -3
  203. package/docs/api/crypto/mode/cbc.md +2 -2
  204. package/docs/api/crypto/mode/chacha20poly1305.md +1 -1
  205. package/docs/api/crypto/mode/cmac.md +4 -4
  206. package/docs/api/crypto/mode/ctr.md +2 -3
  207. package/docs/api/crypto/mode/gcm.md +5 -5
  208. package/docs/api/crypto/mode/kw.md +4 -4
  209. package/docs/api/crypto/pkc/README.md +8 -8
  210. package/docs/api/crypto/pkc/ecc.md +19 -17
  211. package/docs/api/crypto/pkc/ed25519.md +10 -15
  212. package/docs/api/crypto/pkc/hybridKem.md +8 -2
  213. package/docs/api/crypto/pkc/hybridSign.md +34 -7
  214. package/docs/api/crypto/pkc/ml_dsa.md +20 -19
  215. package/docs/api/crypto/pkc/ml_kem.md +3 -3
  216. package/docs/api/crypto/pkc/rsa.md +7 -9
  217. package/docs/api/crypto/pkc/slh_dsa.md +12 -12
  218. package/docs/api/crypto/pkc/x25519.md +5 -4
  219. package/docs/api/crypto/utils/README.md +7 -7
  220. package/docs/api/crypto/utils/aes_modes.md +2 -5
  221. package/docs/api/crypto/utils/asn1.md +25 -16
  222. package/docs/api/crypto/utils/jws.md +6 -4
  223. package/docs/api/crypto/utils/keyformat.md +24 -15
  224. package/docs/api/crypto/utils/pad.md +1 -1
  225. package/docs/api/crypto/utils/pem.md +3 -3
  226. package/docs/api/crypto/utils/random.md +3 -4
  227. package/docs/api/crypto/utils/rsaKeygen.md +2 -2
  228. package/docs/api/crypto/utils/totp.md +2 -2
  229. package/docs/api/crypto/utils/uuid.md +5 -5
  230. package/docs/api/crypto/utils/x509.md +124 -0
  231. package/docs/api/crypto/wasm/aes.md +1 -1
  232. package/docs/api/crypto/wasm/argon2.md +6 -4
  233. package/docs/api/crypto/wasm/ml_kem.md +1 -0
  234. package/docs/api/crypto/wasm/pbkdf2.md +8 -8
  235. package/docs/api/crypto/wasm/rsa.md +1 -1
  236. package/docs/api/crypto/wasm/runtime.md +27 -10
  237. package/docs/api/crypto/webcrypto/aes.md +1 -1
  238. package/docs/api/crypto/webcrypto/aeskw.md +2 -2
  239. package/docs/api/crypto/webcrypto/digest.md +3 -5
  240. package/docs/api/crypto/webcrypto/ecc.md +1 -1
  241. package/docs/api/crypto/webcrypto/ed25519.md +1 -1
  242. package/docs/api/crypto/webcrypto/rsa.md +3 -2
  243. package/docs/api/crypto/webcrypto/x25519.md +1 -1
  244. package/docs/api/dom/README.md +6 -1
  245. package/docs/api/dom/fs/README.md +1 -0
  246. package/docs/api/dom/fs/fileIntake.md +120 -0
  247. package/docs/api/dom/fs/fsAccess.md +1 -0
  248. package/docs/api/dom/fs/indexedDB.md +1 -1
  249. package/docs/api/dom/fs/storage.md +1 -1
  250. package/docs/api/dom/query/README.md +2 -1
  251. package/docs/api/dom/query/dnd.md +4 -1
  252. package/docs/api/dom/query/dom.md +5 -0
  253. package/docs/api/dom/query/sound.md +103 -0
  254. package/docs/api/dom/rendering/README.md +4 -3
  255. package/docs/api/dom/rendering/chart.md +5 -4
  256. package/docs/api/dom/rendering/component.md +25 -3
  257. package/docs/api/dom/rendering/parser.md +5 -2
  258. package/docs/api/dom/rendering/reactiveBind.md +1 -1
  259. package/docs/api/dom/rendering/render.md +2 -2
  260. package/docs/api/dom/rendering/sanitize.md +10 -2
  261. package/docs/api/dom/rendering/secPolicy.md +4 -4
  262. package/docs/api/dom/rendering/styleSheet.md +85 -0
  263. package/docs/api/dom/rendering/template.md +20 -5
  264. package/docs/api/dom/rendering/themeTokens.md +6 -3
  265. package/docs/api/dom/rendering/uiSession.md +18 -5
  266. package/docs/api/dom/rendering/virtualScroll.md +2 -2
  267. package/docs/api/dom/sensors/geolocation.md +1 -1
  268. package/docs/api/dom/sw/README.md +7 -1
  269. package/docs/api/dom/sw/cache.md +2 -1
  270. package/docs/api/dom/sw/installPrompt.md +111 -0
  271. package/docs/api/dom/sw/precache.md +124 -0
  272. package/docs/api/dom/sw/serviceWorker.md +4 -2
  273. package/docs/api/dom/sw/swUpdate.md +112 -0
  274. package/docs/api/dom/utils/clipboard.md +56 -5
  275. package/docs/api/dom/utils/entropyCollector.md +1 -1
  276. package/docs/api/dom/utils/keybindings.md +17 -2
  277. package/docs/api/dom/utils/leaderElection.md +2 -2
  278. package/docs/api/dom/utils/route.md +1 -0
  279. package/docs/api/dom/utils/ua.md +15 -10
  280. package/docs/api/io/calc/crc32.md +4 -1
  281. package/docs/api/io/codec/README.md +2 -2
  282. package/docs/api/io/codec/b64.md +31 -2
  283. package/docs/api/io/codec/buffer.md +1 -1
  284. package/docs/api/io/codec/cbor.md +6 -4
  285. package/docs/api/io/codec/csv.md +178 -178
  286. package/docs/api/io/codec/hex.md +10 -2
  287. package/docs/api/io/codec/msgpack.md +4 -3
  288. package/docs/api/io/codec/url.md +4 -3
  289. package/docs/api/io/codec/utf8.md +3 -3
  290. package/docs/api/io/compress/bitstream.md +6 -3
  291. package/docs/api/io/compress/brotli.md +36 -4
  292. package/docs/api/io/compress/brotli_shared.md +1 -1
  293. package/docs/api/io/compress/deflate.md +42 -34
  294. package/docs/api/io/compress/gzip.md +26 -6
  295. package/docs/api/io/compress/huffman.md +2 -1
  296. package/docs/api/io/compress/lz4.md +5 -3
  297. package/docs/api/io/compress/lz77.md +26 -3
  298. package/docs/api/io/compress/lzw.md +13 -8
  299. package/docs/api/io/compress/zip.md +36 -10
  300. package/docs/api/io/compress/zlib.md +21 -5
  301. package/docs/api/io/math/linalg.md +1 -1
  302. package/docs/api/io/utils/valid.md +1 -1
  303. package/docs/api/process/rpc.md +3 -2
  304. package/docs/api/process/workerPool.md +1 -1
  305. package/docs/api/sanity/base.md +9 -5
  306. package/docs/api/sanity/lockdown.md +7 -6
  307. package/docs/api/surface.json +12311 -0
  308. package/docs/api/typed.md +5 -3
  309. package/docs/dev/README.md +2 -0
  310. package/docs/dev/bench.md +76 -0
  311. package/docs/dev/crypto-references.md +54 -0
  312. package/docs/dev/provenance.md +30 -7
  313. package/docs/dev/publishing.md +7 -7
  314. package/docs/dev/runtime.md +1 -1
  315. package/docs/dev/testing.md +13 -0
  316. package/docs/evidence/l4-evidence.md +86 -0
  317. package/docs/evidence/pqc-hybrid-evidence.md +7 -6
  318. package/docs/guide/README.md +1 -0
  319. package/docs/guide/_QUICK_REF.md +5 -5
  320. package/docs/guide/doc-format.md +4 -3
  321. package/docs/guide/integrations-hmr.md +1 -1
  322. package/docs/guide/module-creation-workflow.md +8 -8
  323. package/docs/guide/rendering-pipeline.md +11 -4
  324. package/docs/guide/security.md +7 -5
  325. package/docs/guide/stability.md +123 -0
  326. package/docs/guide/tutorial-todo.md +20 -8
  327. package/docs/guide/typescript.md +9 -0
  328. package/docs/guide/worker-confinement.md +30 -17
  329. package/docs/notes/lz77-deflate-factorization.md +3 -3
  330. package/docs/tools/README.md +1 -1
  331. package/docs/tools/bundler.md +3 -3
  332. package/docs/tools/codegen.md +1 -1
  333. package/docs/tools/standalone.md +0 -1
  334. package/fw.config.json +2 -2
  335. package/integrations/_shared/catalog.generated.json +7 -1
  336. package/integrations/_shared/core.js +1 -1
  337. package/integrations/astro/index.js +1 -1
  338. package/integrations/eslint/README.md +7 -1
  339. package/integrations/nextjs/index.js +1 -1
  340. package/integrations/nodejs/README.md +3 -3
  341. package/integrations/turbopack/index.js +2 -2
  342. package/integrations/typedoc/categorize.js +1 -1
  343. package/integrations/typedoc/typedoc.json +2 -1
  344. package/integrations/vite/index.js +2 -2
  345. package/integrations/vite/vite-env.d.ts +7 -4
  346. package/integrations/webpack/index.js +3 -3
  347. package/package.json +76 -10
  348. package/src/core/internal.js +31 -0
  349. package/src/core/logger.js +95 -23
  350. package/src/core/modules.js +17 -8
  351. package/src/core/readyState.js +1 -1
  352. package/src/core/runtime.js +74 -27
  353. package/src/core/worker-helper.js +83 -4
  354. package/src/crypto/NIST_CONFORMANCE.md +47 -34
  355. package/src/crypto/cipher/aes.acvp.md +7 -8
  356. package/src/crypto/cipher/aes.js +280 -229
  357. package/src/crypto/cipher/chacha20.acvp.md +6 -7
  358. package/src/crypto/cipher/chacha20.js +91 -61
  359. package/src/crypto/hash/adf.js +1 -1
  360. package/src/crypto/hash/argon2.acvp.md +11 -15
  361. package/src/crypto/hash/argon2.js +9 -24
  362. package/src/crypto/hash/blake2b.js +157 -125
  363. package/src/crypto/hash/hkdf.acvp.md +15 -15
  364. package/src/crypto/hash/hkdf.js +1 -1
  365. package/src/crypto/hash/hmac.acvp.md +10 -12
  366. package/src/crypto/hash/hmac.js +5 -1
  367. package/src/crypto/hash/pbkdf2.acvp.md +13 -13
  368. package/src/crypto/hash/pbkdf2.js +36 -8
  369. package/src/crypto/hash/poly1305.acvp.md +10 -6
  370. package/src/crypto/hash/poly1305.js +171 -50
  371. package/src/crypto/hash/sha224.acvp.md +3 -3
  372. package/src/crypto/hash/sha224.js +4 -4
  373. package/src/crypto/hash/sha256.acvp.md +2 -2
  374. package/src/crypto/hash/sha256.js +514 -50
  375. package/src/crypto/hash/sha3.acvp.md +9 -9
  376. package/src/crypto/hash/sha3.js +127 -71
  377. package/src/crypto/hash/sha384.acvp.md +3 -3
  378. package/src/crypto/hash/sha384.js +4 -4
  379. package/src/crypto/hash/sha512.acvp.md +7 -8
  380. package/src/crypto/hash/sha512.js +107 -108
  381. package/src/crypto/hash/sha512_224.acvp.md +6 -6
  382. package/src/crypto/hash/sha512_224.js +2 -2
  383. package/src/crypto/hash/sha512_256.acvp.md +6 -6
  384. package/src/crypto/hash/sha512_256.js +2 -2
  385. package/src/crypto/mode/cbc.acvp.md +2 -2
  386. package/src/crypto/mode/cbc.js +1 -1
  387. package/src/crypto/mode/chacha20poly1305.acvp.md +6 -6
  388. package/src/crypto/mode/chacha20poly1305.js +3 -3
  389. package/src/crypto/mode/cmac.acvp.md +5 -5
  390. package/src/crypto/mode/cmac.js +8 -8
  391. package/src/crypto/mode/ctr.acvp.md +2 -2
  392. package/src/crypto/mode/ctr.js +1 -3
  393. package/src/crypto/mode/gcm.acvp.md +6 -6
  394. package/src/crypto/mode/gcm.js +7 -7
  395. package/src/crypto/mode/kw.acvp.md +4 -4
  396. package/src/crypto/mode/kw.js +5 -5
  397. package/src/crypto/pkc/ecc.acvp.md +13 -13
  398. package/src/crypto/pkc/ecc.js +9 -11
  399. package/src/crypto/pkc/ed25519.acvp.md +30 -34
  400. package/src/crypto/pkc/ed25519.js +453 -94
  401. package/src/crypto/pkc/hybrid-kat.provenance.md +4 -4
  402. package/src/crypto/pkc/hybridSign.js +103 -24
  403. package/src/crypto/pkc/ml_dsa.acvp.md +18 -18
  404. package/src/crypto/pkc/ml_dsa.js +29 -32
  405. package/src/crypto/pkc/ml_kem.acvp.md +7 -7
  406. package/src/crypto/pkc/ml_kem.js +15 -21
  407. package/src/crypto/pkc/rsa.acvp.md +11 -15
  408. package/src/crypto/pkc/rsa.js +7 -44
  409. package/src/crypto/pkc/slh_dsa.acvp.md +16 -16
  410. package/src/crypto/pkc/slh_dsa.js +16 -18
  411. package/src/crypto/pkc/x25519.acvp.md +13 -10
  412. package/src/crypto/pkc/x25519.js +273 -29
  413. package/src/crypto/utils/aes_modes.acvp.md +1 -2
  414. package/src/crypto/utils/aes_modes.js +2 -2
  415. package/src/crypto/utils/asn1-oid.js +1 -1
  416. package/src/crypto/utils/asn1.js +1 -1
  417. package/src/crypto/utils/bitArray.js +33 -48
  418. package/src/crypto/utils/bn.js +1 -1
  419. package/src/crypto/utils/jws.js +37 -41
  420. package/src/crypto/utils/keyformat.js +181 -2
  421. package/src/crypto/utils/pem.js +1 -1
  422. package/src/crypto/utils/random.acvp.md +5 -5
  423. package/src/crypto/utils/random.js +845 -846
  424. package/src/crypto/utils/rsaKeygen.acvp.md +3 -2
  425. package/src/crypto/utils/rsaKeygen.js +6 -6
  426. package/src/crypto/utils/totp.js +1 -1
  427. package/src/crypto/utils/uuid.acvp.md +5 -5
  428. package/src/crypto/utils/uuid.js +11 -10
  429. package/src/crypto/utils/x509.js +591 -0
  430. package/src/crypto/wasm/aes.js +1 -1
  431. package/src/crypto/wasm/aes.scalar.wasm +0 -0
  432. package/src/crypto/wasm/argon2.js +17 -1
  433. package/src/crypto/wasm/argon2.scalar.wasm +0 -0
  434. package/src/crypto/wasm/blake2b.scalar.wasm +0 -0
  435. package/src/crypto/wasm/blake2b.simd.wasm +0 -0
  436. package/src/crypto/wasm/chacha20poly1305.scalar.wasm +0 -0
  437. package/src/crypto/wasm/chacha20poly1305.simd.wasm +0 -0
  438. package/src/crypto/wasm/cmac.scalar.wasm +0 -0
  439. package/src/crypto/wasm/ecc.js +3 -3
  440. package/src/crypto/wasm/ecc.scalar.wasm +0 -0
  441. package/src/crypto/wasm/ed25519.js +1 -1
  442. package/src/crypto/wasm/ed25519.scalar.wasm +0 -0
  443. package/src/crypto/wasm/hkdf.scalar.wasm +0 -0
  444. package/src/crypto/wasm/hmac.scalar.wasm +0 -0
  445. package/src/crypto/wasm/ml_dsa.js +2 -2
  446. package/src/crypto/wasm/ml_dsa.scalar.wasm +0 -0
  447. package/src/crypto/wasm/ml_dsa.simd.wasm +0 -0
  448. package/src/crypto/wasm/ml_kem.js +2 -2
  449. package/src/crypto/wasm/ml_kem.scalar.wasm +0 -0
  450. package/src/crypto/wasm/ml_kem.simd.wasm +0 -0
  451. package/src/crypto/wasm/pbkdf2.js +8 -6
  452. package/src/crypto/wasm/pbkdf2.scalar.wasm +0 -0
  453. package/src/crypto/wasm/rsa.js +6 -5
  454. package/src/crypto/wasm/rsa.scalar.wasm +0 -0
  455. package/src/crypto/wasm/runtime.js +84 -17
  456. package/src/crypto/wasm/sha2.scalar.wasm +0 -0
  457. package/src/crypto/wasm/sha3.scalar.wasm +0 -0
  458. package/src/crypto/wasm/sha3.simd.wasm +0 -0
  459. package/src/crypto/wasm/slh_dsa.js +1 -1
  460. package/src/crypto/wasm/slh_dsa.scalar.wasm +0 -0
  461. package/src/crypto/wasm/x25519.js +1 -1
  462. package/src/crypto/wasm/x25519.scalar.wasm +0 -0
  463. package/src/crypto/webcrypto/aes.js +8 -2
  464. package/src/crypto/webcrypto/aeskw.js +7 -2
  465. package/src/crypto/webcrypto/digest.js +1 -15
  466. package/src/crypto/webcrypto/ecc.js +2 -2
  467. package/src/crypto/webcrypto/ed25519.js +2 -2
  468. package/src/crypto/webcrypto/hmac.js +2 -2
  469. package/src/crypto/webcrypto/rsa.js +7 -2
  470. package/src/crypto/webcrypto/x25519.js +2 -2
  471. package/src/dom/display/animate.js +1 -1
  472. package/src/dom/display/fullscreen.js +1 -1
  473. package/src/dom/fs/download.js +1 -1
  474. package/src/dom/fs/fileIntake.js +192 -0
  475. package/src/dom/fs/fsAccess.js +2 -3
  476. package/src/dom/fs/indexedDB.js +1 -1
  477. package/src/dom/fs/remoteStore.js +1 -1
  478. package/src/dom/fs/storage.js +1 -1
  479. package/src/dom/lifecycle/idle.js +1 -1
  480. package/src/dom/lifecycle/visibility.js +1 -1
  481. package/src/dom/lifecycle/wakeLock.js +1 -1
  482. package/src/dom/net/ajax.js +1 -1
  483. package/src/dom/net/network.js +1 -1
  484. package/src/dom/net/sse.js +1 -1
  485. package/src/dom/net/webrtc.js +1 -1
  486. package/src/dom/net/ws.js +1 -1
  487. package/src/dom/query/dnd.js +56 -4
  488. package/src/dom/query/dom.js +1 -1
  489. package/src/dom/query/events.js +1 -1
  490. package/src/dom/query/gesture.js +1 -1
  491. package/src/dom/query/media.js +1 -1
  492. package/src/dom/query/sound.js +333 -0
  493. package/src/dom/rendering/chart.js +736 -663
  494. package/src/dom/rendering/component.js +25 -14
  495. package/src/dom/rendering/devtools.js +2 -2
  496. package/src/dom/rendering/parser.js +155 -12
  497. package/src/dom/rendering/render.js +14 -4
  498. package/src/dom/rendering/sanitize.js +11 -4
  499. package/src/dom/rendering/secPolicy.js +6 -4
  500. package/src/dom/rendering/styleSheet.js +217 -0
  501. package/src/dom/rendering/template.js +72 -13
  502. package/src/dom/rendering/themeTokens.js +542 -522
  503. package/src/dom/rendering/uiSession-core.js +51 -6
  504. package/src/dom/rendering/uiSession-direct.js +1 -1
  505. package/src/dom/rendering/uiSession-list.js +4 -4
  506. package/src/dom/rendering/uiSession.js +1 -1
  507. package/src/dom/rendering/virtualScroll.js +341 -341
  508. package/src/dom/sensors/battery.js +1 -1
  509. package/src/dom/sensors/geolocation.js +1 -1
  510. package/src/dom/sensors/networkInfo.js +1 -1
  511. package/src/dom/sensors/sensors.js +1 -1
  512. package/src/dom/sw/backgroundSync.js +1 -1
  513. package/src/dom/sw/cache.js +1 -1
  514. package/src/dom/sw/installPrompt.js +151 -0
  515. package/src/dom/sw/precache.js +257 -0
  516. package/src/dom/sw/push.js +1 -1
  517. package/src/dom/sw/sharedWorker.js +1 -1
  518. package/src/dom/sw/swUpdate.js +239 -0
  519. package/src/dom/utils/a11y.js +1 -1
  520. package/src/dom/utils/clipboard.js +56 -6
  521. package/src/dom/utils/entropyCollector.js +1 -1
  522. package/src/dom/utils/focus.js +1 -1
  523. package/src/dom/utils/form.js +1 -1
  524. package/src/dom/utils/keybindings.js +600 -574
  525. package/src/dom/utils/leaderElection.js +1 -1
  526. package/src/dom/utils/notifications.js +1 -1
  527. package/src/dom/utils/permissions.js +107 -107
  528. package/src/dom/utils/route.js +14 -2
  529. package/src/dom/utils/ua.js +42 -28
  530. package/src/dom/utils/webauthn.js +1 -1
  531. package/src/io/binary/reader.js +1 -1
  532. package/src/io/binary/writer.js +1 -1
  533. package/src/io/calc/bigint.js +1 -1
  534. package/src/io/calc/crc32.js +28 -2
  535. package/src/io/calc/easing.js +514 -514
  536. package/src/io/codec/b64.js +189 -52
  537. package/src/io/codec/base32.js +1 -1
  538. package/src/io/codec/base58.js +1 -1
  539. package/src/io/codec/buffer.js +1 -1
  540. package/src/io/codec/cbor.js +111 -18
  541. package/src/io/codec/csv.js +1 -1
  542. package/src/io/codec/hex.js +51 -6
  543. package/src/io/codec/mime.js +1 -1
  544. package/src/io/codec/msgpack.js +47 -6
  545. package/src/io/codec/url.js +24 -7
  546. package/src/io/codec/utf8.js +5 -3
  547. package/src/io/codec/xml.js +1 -1
  548. package/src/io/compress/bitstream.js +2 -2
  549. package/src/io/compress/brotli.js +663 -163
  550. package/src/io/compress/brotli_dict.js +1 -1
  551. package/src/io/compress/brotli_dict_words.js +1 -1
  552. package/src/io/compress/brotli_frame.js +1 -1
  553. package/src/io/compress/brotli_shared.js +7 -7
  554. package/src/io/compress/deflate.js +87 -53
  555. package/src/io/compress/gzip.js +187 -74
  556. package/src/io/compress/huffman.js +24 -1
  557. package/src/io/compress/lz4.js +45 -7
  558. package/src/io/compress/lz77.js +148 -63
  559. package/src/io/compress/lzw.js +35 -19
  560. package/src/io/compress/zip.js +862 -815
  561. package/src/io/compress/zlib.js +87 -7
  562. package/src/io/i18n/i18n.js +1 -1
  563. package/src/io/math/fixed-point.js +1 -1
  564. package/src/io/math/geom.js +1 -1
  565. package/src/io/math/interp.js +1 -1
  566. package/src/io/math/linalg.js +10 -4
  567. package/src/io/math/stats.js +1 -1
  568. package/src/io/structures/btree.js +1 -1
  569. package/src/io/structures/heap.js +1 -1
  570. package/src/io/structures/lruCache.js +1 -1
  571. package/src/io/structures/ringBuffer.js +1 -1
  572. package/src/io/structures/tree-walker.js +1 -1
  573. package/src/io/structures/trie.js +1 -1
  574. package/src/io/sync/abort.js +1 -1
  575. package/src/io/sync/atomics.js +1 -1
  576. package/src/io/sync/cancellable.js +1 -1
  577. package/src/io/sync/channel.js +1 -1
  578. package/src/io/sync/mutex.js +1 -1
  579. package/src/io/sync/semaphore.js +1 -1
  580. package/src/io/sync/tokenBucket.js +1 -1
  581. package/src/io/text/ansi.js +1 -1
  582. package/src/io/text/html-entities.js +1 -1
  583. package/src/io/time/date.js +1 -1
  584. package/src/io/timing/clock.js +1 -1
  585. package/src/io/timing/rateLimit.js +1 -1
  586. package/src/io/timing/scheduler.js +1 -1
  587. package/src/io/utils/errors.js +1 -1
  588. package/src/io/utils/eventBus.js +1 -1
  589. package/src/io/utils/signal.js +1 -1
  590. package/src/io/utils/valid.js +1 -1
  591. package/src/main.js +1 -1
  592. package/src/process/message.js +1 -1
  593. package/src/process/rpc.js +7 -3
  594. package/src/process/workerPool.js +11 -4
  595. package/src/sanity/base.js +85 -39
  596. package/src/sanity/lockdown-apply.js +3 -3
  597. package/src/sanity/lockdown.js +58 -32
  598. package/src/sanity/wasm-gate.js +2 -2
  599. package/src/typed.js +7 -3
  600. package/third-party/NOTICE-brotli-dictionary.txt +69 -0
  601. package/third-party/NOTICE-fw-wasm-crypto.txt +576 -0
  602. package/third-party/NOTICE-whatwg-entities.txt +44 -0
  603. package/types/registry.generated.d.ts +7 -1
  604. package/types/typed.d.ts +7 -3
  605. package/dist/types/crypto/utils/aes_ctr.d.ts +0 -84
  606. package/dist/types/crypto/utils/aes_ctr.d.ts.map +0 -1
  607. package/docs/api/crypto/utils/aes_ctr.md +0 -71
  608. package/src/crypto/utils/aes_ctr.acvp.md +0 -67
  609. package/src/crypto/utils/aes_ctr.js +0 -134
@@ -1,574 +1,600 @@
1
- // Copyright (c) 2026 AwaCloud SAS
2
- // Author: Matthieu Bouilloux
3
- // SPDX-License-Identifier: Apache-2.0
4
-
5
- /**
6
- * @description
7
- * Keyboard shortcut manager supporting simple bindings (`'Ctrl+S'`),
8
- * chord keys (`'Ctrl+K Ctrl+P'` - two sequential keystrokes),
9
- * stackable contexts (`pushContext('modal')` → exclusive bindings),
10
- * per-binding priority (conflict resolution),
11
- * and inspection (`list`, `match`).
12
- *
13
- * Key strategy: `event.code` for alpha-numeric keys (keyboard layout
14
- * independent, e.g. `KeyA` always maps to the physical A key), and `event.key`
15
- * for named keys (`'Escape'`, `'F1'`, `'Tab'`, etc.).
16
- *
17
- * Out of MVP scope: persistent user-side remapping.
18
- * Worker-safe: no - consumes DOM keyboard events.
19
- *
20
- * @example
21
- * const keybindings = runtime.resolve('keybindings');
22
- * const kb = keybindings.create({ target: document });
23
- * kb.attach();
24
- * const unbind = kb.bind('Ctrl+S', () => save(), { preventDefault: true });
25
- * kb.bind('Ctrl+K Ctrl+P', () => openPalette());
26
- * // …
27
- * unbind(); // unregisters
28
- */
29
- import { events } from '../query/events.js';
30
- import { eventBus } from '../../io/utils/eventBus.js';
31
-
32
- /**
33
- * Public surface returned by the keybindings factory.
34
- * @typedef {object} KeybindingsAPI
35
- * @property {(opts?: { target?: EventTarget, layout?: string, chordTimeout?: number }) => object} create - Create a keybindings manager instance (bind/unbind/contexts/attach/detach/...).
36
- * @property {(combo: string) => ({ modifiers: object, key: string } | Array<{ modifiers: object, key: string }>)} parse - Parse a combo string into a single segment (simple) or an array of segments (chord).
37
- */
38
-
39
- export const keybindings = {
40
- name: 'keybindings',
41
- version: '1.0.0',
42
- type: 'fw.dom.utils',
43
- dependencies: ['events', 'eventBus'],
44
- deps: [events, eventBus],
45
-
46
- /**
47
- * @param {Object} events - Module events (fw)
48
- * @param {Object} eventBus - Module eventBus (fw)
49
- * @returns {KeybindingsAPI}
50
- */
51
- factory(events, eventBus) {
52
-
53
- // ── Key mapping constants ────────────────────────────────────────────
54
-
55
- /** Special keys → expected event.key */
56
- const NAMED_KEYS = new Set([
57
- 'Escape', 'Tab', 'Enter', 'Space', 'Backspace', 'Delete', 'Insert',
58
- 'Home', 'End', 'PageUp', 'PageDown',
59
- 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight',
60
- 'F1', 'F2', 'F3', 'F4', 'F5', 'F6',
61
- 'F7', 'F8', 'F9', 'F10', 'F11', 'F12',
62
- ]);
63
-
64
- /** Accepted key aliases (case-insensitive) → normalised key */
65
- const KEY_ALIASES = {
66
- esc: 'Escape',
67
- escape: 'Escape',
68
- return: 'Enter',
69
- enter: 'Enter',
70
- tab: 'Tab',
71
- space: 'Space',
72
- backspace: 'Backspace',
73
- del: 'Delete',
74
- delete: 'Delete',
75
- insert: 'Insert',
76
- home: 'Home',
77
- end: 'End',
78
- pageup: 'PageUp',
79
- pagedown: 'PageDown',
80
- up: 'ArrowUp',
81
- down: 'ArrowDown',
82
- left: 'ArrowLeft',
83
- right: 'ArrowRight',
84
- arrowup: 'ArrowUp',
85
- arrowdown: 'ArrowDown',
86
- arrowleft: 'ArrowLeft',
87
- arrowright: 'ArrowRight',
88
- };
89
-
90
- /** Accepted modifier names (lowercase) */
91
- const MODIFIER_NAMES = new Set(['ctrl', 'shift', 'alt', 'meta', 'cmd', 'super']);
92
-
93
- // ── Parser ─────────────────────────────────────────────────────────
94
-
95
- /**
96
- * Parse a single combo segment (e.g. `'Ctrl+Shift+P'`).
97
- * @param {string} segment
98
- * @returns {{ modifiers: {ctrl, shift, alt, meta}, key: string }}
99
- */
100
- function _parseSegment(segment) {
101
- const parts = segment.split('+');
102
- const modifiers = { ctrl: false, shift: false, alt: false, meta: false };
103
- let key = null;
104
-
105
- for (const raw of parts) {
106
- const lower = raw.toLowerCase();
107
- if (MODIFIER_NAMES.has(lower)) {
108
- if (lower === 'cmd' || lower === 'super') {
109
- modifiers.meta = true;
110
- } else {
111
- modifiers[lower] = true;
112
- }
113
- } else if (raw.length === 0) {
114
- // double `+` (e.g. 'Ctrl++')
115
- throw new Error('keybindings: invalid combo segment "' + segment + '"');
116
- } else {
117
- if (key !== null) {
118
- throw new Error('keybindings: multiple non-modifier keys in segment "' + segment + '"');
119
- }
120
- // Try alias, then NAMED_KEYS, then letter/digit
121
- const alias = KEY_ALIASES[lower];
122
- if (alias) {
123
- key = alias;
124
- } else if (NAMED_KEYS.has(raw)) {
125
- key = raw;
126
- } else if (/^[a-zA-Z0-9]$/.test(raw)) {
127
- key = raw.toLowerCase();
128
- } else {
129
- throw new Error('keybindings: unknown key "' + raw + '" in segment "' + segment + '"');
130
- }
131
- }
132
- }
133
-
134
- if (key === null) {
135
- throw new Error('keybindings: no key specified in segment "' + segment + '"');
136
- }
137
-
138
- return { modifiers, key };
139
- }
140
-
141
- /**
142
- * Parse a full combo string.
143
- * - simple (`'Ctrl+S'`) → `{modifiers, key}`
144
- * - chord (`'Ctrl+K Ctrl+P'`) → `[{modifiers, key}, {modifiers, key}]`
145
- *
146
- * @param {string} combo
147
- * @returns {{ modifiers: Object, key: string } | Array<{ modifiers: Object, key: string }>}
148
- */
149
- function parse(combo) {
150
- if (typeof combo !== 'string' || combo.trim().length === 0) {
151
- throw new TypeError('keybindings: combo must be a non-empty string');
152
- }
153
- const segments = combo.trim().split(' ').filter(s => s.length > 0);
154
- if (segments.length === 1) {
155
- return _parseSegment(segments[0]);
156
- }
157
- return segments.map(s => _parseSegment(s));
158
- }
159
-
160
- // ── event.key normalisation ──────────────────────────────────────────
161
-
162
- /**
163
- * Normalise a KeyboardEvent to a key comparable to the one produced by `parse`.
164
- * For alpha-numeric keys, uses `event.code` (e.g. 'KeyA' → 'a').
165
- * For named keys, uses `event.key`.
166
- * @param {KeyboardEvent} event
167
- * @returns {string|null}
168
- */
169
- function _normalizeEventKey(event) {
170
- // Named keys via event.key
171
- const key = event.key;
172
- if (NAMED_KEYS.has(key)) return key;
173
- // Alias via event.key
174
- const aliased = KEY_ALIASES[key.toLowerCase()];
175
- if (aliased) return aliased;
176
- // Alpha-numeric via event.code (layout-independent)
177
- const code = event.code;
178
- if (code && /^Key[A-Z]$/.test(code)) return code.slice(3).toLowerCase();
179
- if (code && /^Digit[0-9]$/.test(code)) return code.slice(5);
180
- // Fallback: event.key lowercased if a single character
181
- if (key.length === 1) return key.toLowerCase();
182
- return null;
183
- }
184
-
185
- /**
186
- * Test whether a KeyboardEvent matches a parsed segment.
187
- * @param {KeyboardEvent} event
188
- * @param {{ modifiers: Object, key: string }} seg
189
- * @returns {boolean}
190
- */
191
- function _matchesSegment(event, seg) {
192
- const { modifiers, key } = seg;
193
- // Windows merges `Ctrl+Alt` into `AltGr`; Firefox then reports
194
- // `getModifierState('AltGraph') === true` while `ctrlKey`/`altKey`
195
- // are `false`. Normalise: AltGr active ⇒ Ctrl and Alt both effective.
196
- // This makes `Ctrl+Alt+X` match both AltGr (Firefox) and the legacy
197
- // ctrl+alt (Chrome) without false positives on combos that only
198
- // require one of the two modifiers.
199
- const altGr = typeof event.getModifierState === 'function'
200
- && event.getModifierState('AltGraph');
201
- const evCtrl = event.ctrlKey || altGr;
202
- const evAlt = event.altKey || altGr;
203
- if (evCtrl !== modifiers.ctrl) return false;
204
- if (event.shiftKey !== modifiers.shift) return false;
205
- if (evAlt !== modifiers.alt) return false;
206
- if (event.metaKey !== modifiers.meta) return false;
207
- return _normalizeEventKey(event) === key;
208
- }
209
-
210
- // ── Instance factory ─────────────────────────────────────────────────
211
-
212
- /**
213
- * Create a keyboard shortcut manager instance.
214
- * @param {Object} [opts={}]
215
- * @param {EventTarget} [opts.target] - Listening target. Defaults to `document`.
216
- * @param {string} [opts.layout] - Keyboard layout: 'us'|'fr'|'auto' (reserved for future use).
217
- * @param {number} [opts.chordTimeout=1500] - Chord timeout in ms.
218
- * @returns {Object} keybindings instance
219
- */
220
- function create(opts = {}) {
221
- const target = opts.target || document;
222
- const chordTimeout = typeof opts.chordTimeout === 'number' ? opts.chordTimeout : 1500;
223
-
224
- const _bus = eventBus.create();
225
-
226
- // Bindings list: { combo, parsed, context, priority, preventDefault, repeat, fn }
227
- const _bindings = [];
228
-
229
- // Context stack
230
- const _contextStack = [];
231
-
232
- // Pending chord state
233
- let _chordPending = null; // { parsed: Array, matched: number, timer: id }
234
-
235
- let _attached = false;
236
-
237
- // ── Bindings management ──────────────────────────────────────────
238
-
239
- /**
240
- * Registers a keyboard shortcut.
241
- *
242
- * **Chord priority tiebreaker.** When multiple chord bindings share
243
- * the same prefix and identical `priority`, only the first registered
244
- * candidate fires (deterministic by definition order). Plain
245
- * (non-chord) bindings at equal max priority all fire - chord
246
- * arbitration is single-winner by design.
247
- *
248
- * @param {string} combo
249
- * @param {Function} fn
250
- * @param {Object} [opts2={}]
251
- * @param {string} [opts2.context]
252
- * @param {number} [opts2.priority=0]
253
- * @param {boolean} [opts2.preventDefault=true]
254
- * @param {boolean} [opts2.repeat=false]
255
- * @returns {Function} unbind
256
- */
257
- function bind(combo, fn, opts2 = {}) {
258
- if (typeof combo !== 'string') throw new TypeError('keybindings.bind: combo must be a string');
259
- if (typeof fn !== 'function') throw new TypeError('keybindings.bind: fn must be a function');
260
-
261
- const parsed = parse(combo);
262
- const context = opts2.context || null;
263
- const priority = typeof opts2.priority === 'number' ? opts2.priority : 0;
264
- const prev = opts2.preventDefault !== false; // true by default
265
- const repeat = opts2.repeat === true; // false by default
266
-
267
- const entry = { combo, parsed, context, priority, preventDefault: prev, repeat, fn };
268
- _bindings.push(entry);
269
-
270
- return function unbind() {
271
- const idx = _bindings.indexOf(entry);
272
- if (idx !== -1) _bindings.splice(idx, 1);
273
- };
274
- }
275
-
276
- /**
277
- * Unregister a combo (all handlers when `fn` is omitted).
278
- * @param {string} combo
279
- * @param {Function} [fn]
280
- */
281
- function unbind(combo, fn) {
282
- for (let i = _bindings.length - 1; i >= 0; i--) {
283
- if (_bindings[i].combo === combo) {
284
- if (!fn || _bindings[i].fn === fn) {
285
- _bindings.splice(i, 1);
286
- }
287
- }
288
- }
289
- }
290
-
291
- // ── Context ──────────────────────────────────────────────────────
292
-
293
- /**
294
- * Push a context onto the stack.
295
- * @param {string} name
296
- */
297
- function pushContext(name) {
298
- _contextStack.push(name);
299
- }
300
-
301
- /**
302
- * Pops the current context.
303
- * @returns {string} Popped context name.
304
- * @throws {RangeError} If the context stack is empty.
305
- */
306
- function popContext() {
307
- if (_contextStack.length === 0) {
308
- throw new RangeError('keybindings: context stack underflow');
309
- }
310
- return _contextStack.pop();
311
- }
312
-
313
- /**
314
- * Return a copy of the context stack.
315
- * @returns {string[]}
316
- */
317
- function currentContext() {
318
- return [..._contextStack];
319
- }
320
-
321
- // ── Inspection ───────────────────────────────────────────────────
322
-
323
- /**
324
- * Return the list of all registered bindings.
325
- * @returns {Array<{combo, context, priority, fn}>}
326
- */
327
- function list() {
328
- return _bindings.map(b => ({
329
- combo: b.combo,
330
- context: b.context,
331
- priority: b.priority,
332
- fn: b.fn,
333
- }));
334
- }
335
-
336
- /**
337
- * Return the bindings that would be triggered by this event.
338
- * @param {KeyboardEvent} event
339
- * @returns {Array<{combo, context, priority, fn}>}
340
- */
341
- function match(event) {
342
- return _bindings
343
- .filter(b => {
344
- const parsed = b.parsed;
345
- if (Array.isArray(parsed)) {
346
- // chord: only the first segment can be matched here
347
- return _matchesSegment(event, parsed[0]);
348
- }
349
- return _matchesSegment(event, parsed);
350
- })
351
- .map(b => ({ combo: b.combo, context: b.context, priority: b.priority, fn: b.fn }));
352
- }
353
-
354
- // ── Dispatch logic ───────────────────────────────────────────────
355
-
356
- /**
357
- * Filter bindings by the current context.
358
- * Rule: when a context is active (non-empty stack), only bindings
359
- * whose `context === top of stack` are allowed.
360
- * In practice: when the stack is non-empty, only bindings from the
361
- * current context fire; context-less bindings are ignored while a
362
- * context is active.
363
- *
364
- * @param {Array} candidates
365
- * @returns {Array}
366
- */
367
- function _filterByContext(candidates) {
368
- const ctx = _contextStack.length > 0 ? _contextStack[_contextStack.length - 1] : null;
369
- if (ctx === null) {
370
- // No active context: only context-less bindings
371
- return candidates.filter(b => b.context === null);
372
- }
373
- // Active context: only bindings for that context
374
- return candidates.filter(b => b.context === ctx);
375
- }
376
-
377
- /**
378
- * Execute the bindings with the highest priority (ties → all of them).
379
- * @param {Array} matched - bindings filtered by context
380
- * @param {KeyboardEvent} event
381
- */
382
- function _dispatch(matched, event) {
383
- if (matched.length === 0) return;
384
-
385
- // Maximum priority
386
- const maxPriority = matched.reduce((m, b) => Math.max(m, b.priority), -Infinity);
387
- const toRun = matched.filter(b => b.priority === maxPriority);
388
-
389
- for (const b of toRun) {
390
- if (b.preventDefault) event.preventDefault();
391
- try {
392
- b.fn(event);
393
- } catch (e) {
394
-
395
- console.error('keybindings handler error:', e);
396
- }
397
- _bus.emit('keybindings:matched', { combo: b.combo, context: b.context, fn: b.fn });
398
- }
399
- }
400
-
401
- /**
402
- * Main keydown handler.
403
- * @param {KeyboardEvent} event
404
- */
405
- function _onKeyDown(event) {
406
- // Filter event.repeat when binding.repeat === false.
407
- // Note: filtering happens per binding below, but if all candidates
408
- // reject repeat we can exit early.
409
-
410
- // ── Phase 1: handle a pending chord ──────────────────────────
411
- if (_chordPending) {
412
- const { parsed, matched, timer, binding } = _chordPending;
413
- clearTimeout(timer);
414
- _chordPending = null;
415
-
416
- const nextIdx = matched + 1;
417
- if (_matchesSegment(event, parsed[nextIdx])) {
418
- if (nextIdx === parsed.length - 1) {
419
- // Chord complet
420
- const b = binding;
421
- if (b.repeat || !event.repeat) {
422
- if (b.preventDefault) event.preventDefault();
423
- try {
424
- b.fn(event);
425
- } catch (e) {
426
-
427
- console.error('keybindings chord handler error:', e);
428
- }
429
- _bus.emit('keybindings:matched', { combo: b.combo, context: b.context, fn: b.fn });
430
- }
431
- } else {
432
- // More segments still to come
433
- _chordPending = {
434
- parsed,
435
- matched: nextIdx,
436
- binding,
437
- timer: setTimeout(() => { _chordPending = null; }, chordTimeout),
438
- };
439
- }
440
- return; // Ne pas traiter comme binding simple
441
- }
442
- // Second keystroke does not match → cancel the chord
443
- // and continue normal processing
444
- }
445
-
446
- // ── Phase 2: look for chord candidates ───────────────────────
447
- const chordCandidates = _bindings.filter(b => {
448
- if (!Array.isArray(b.parsed)) return false;
449
- if (!_matchesSegment(event, b.parsed[0])) return false;
450
- // Check context
451
- const ctx = _contextStack.length > 0 ? _contextStack[_contextStack.length - 1] : null;
452
- if (ctx === null) return b.context === null;
453
- return b.context === ctx;
454
- });
455
-
456
- if (chordCandidates.length > 0) {
457
- // Start the chord with the first candidate (when several, take the highest priority)
458
- const best = chordCandidates.reduce((a, b) => b.priority > a.priority ? b : a, chordCandidates[0]);
459
- _chordPending = {
460
- parsed: best.parsed,
461
- matched: 0,
462
- binding: best,
463
- timer: setTimeout(() => { _chordPending = null; }, chordTimeout),
464
- };
465
- // Do not trigger a simple binding immediately
466
- return;
467
- }
468
-
469
- // ── Phase 3: simple bindings ──────────────────────────────────
470
- const simpleCandidates = _bindings.filter(b => {
471
- if (Array.isArray(b.parsed)) return false;
472
- return _matchesSegment(event, b.parsed);
473
- });
474
-
475
- const contextFiltered = _filterByContext(simpleCandidates);
476
- const repeatFiltered = contextFiltered.filter(b => b.repeat || !event.repeat);
477
-
478
- _dispatch(repeatFiltered, event);
479
- }
480
-
481
- // ── Attach / detach ───────────────────────────────────────────────
482
-
483
- /**
484
- * Enable keyboard event listening.
485
- */
486
- function attach() {
487
- if (_attached) return;
488
- _attached = true;
489
- target.addEventListener('keydown', _onKeyDown);
490
- }
491
-
492
- /**
493
- * Disable keyboard event listening.
494
- */
495
- function detach() {
496
- if (!_attached) return;
497
- _attached = false;
498
- target.removeEventListener('keydown', _onKeyDown);
499
- if (_chordPending) {
500
- clearTimeout(_chordPending.timer);
501
- _chordPending = null;
502
- }
503
- }
504
-
505
- /**
506
- * Dispose the instance (detach listeners and clear all bindings).
507
- */
508
- function dispose() {
509
- detach();
510
- _bindings.length = 0;
511
- _contextStack.length = 0;
512
- }
513
-
514
- /**
515
- * Create a scoped sub-controller. Every `bind(...)` called through
516
- * the returned scope is tracked ; calling `scope.dispose()` (or
517
- * `scope.clear()`) unbinds them all at once **without** disposing
518
- * the parent instance.
519
- *
520
- * Intended for `ui.mount(blockId, null, () => kb.scope())` so a
521
- * modal/component's keybindings are auto-detached when the block
522
- * is cleared.
523
- *
524
- * @returns {{
525
- * bind: Function, unbind: Function,
526
- * pushContext: Function, popContext: Function,
527
- * dispose: Function, clear: Function
528
- * }}
529
- */
530
- function scope() {
531
- const unbinders = new Set();
532
-
533
- function scopeBind(...args) {
534
- // @ts-ignore - spread forwarding of variadic handler args
535
- const off = bind(...args);
536
- unbinders.add(off);
537
- return off;
538
- }
539
-
540
- function clear() {
541
- for (const off of unbinders) {
542
- try { off(); } catch { /* swallow */ }
543
- }
544
- unbinders.clear();
545
- }
546
-
547
- return {
548
- bind: scopeBind,
549
- unbind,
550
- pushContext,
551
- popContext,
552
- dispose: clear,
553
- clear,
554
- };
555
- }
556
-
557
- return {
558
- bind,
559
- unbind,
560
- pushContext,
561
- popContext,
562
- currentContext,
563
- list,
564
- match,
565
- attach,
566
- detach,
567
- dispose,
568
- scope,
569
- };
570
- }
571
-
572
- return { create, parse };
573
- }
574
- };
1
+ // Copyright (c) 2026 AwaCloud SAS
2
+ // Author: Matthieu Bouilloux
3
+ // SPDX-License-Identifier: Apache-2.0
4
+
5
+ /**
6
+ * @description
7
+ * Keyboard shortcut manager supporting simple bindings (`'Ctrl+S'`),
8
+ * chord keys (`'Ctrl+K Ctrl+P'` - two sequential keystrokes),
9
+ * stackable contexts (`pushContext('modal')` → exclusive bindings),
10
+ * per-binding priority (conflict resolution),
11
+ * and inspection (`list`, `match`).
12
+ *
13
+ * Key strategy: `event.code` for alpha-numeric keys (keyboard layout
14
+ * independent, e.g. `KeyA` always maps to the physical A key), and `event.key`
15
+ * for named keys (`'Escape'`, `'F1'`, `'Tab'`, etc.).
16
+ * Punctuation keys (`Plus`, `Minus`, `Equal`) match on `event.key` (the typed
17
+ * character, numpad included) and ignore the Shift modifier.
18
+ *
19
+ * Out of MVP scope: persistent user-side remapping.
20
+ * Worker-safe: no - consumes DOM keyboard events.
21
+ *
22
+ * @example
23
+ * const keybindings = runtime.resolve('keybindings');
24
+ * const kb = keybindings.create({ target: document });
25
+ * kb.attach();
26
+ * const unbind = kb.bind('Ctrl+S', () => save(), { preventDefault: true });
27
+ * kb.bind('Ctrl+K Ctrl+P', () => openPalette());
28
+ * // …
29
+ * unbind(); // unregisters
30
+ */
31
+ import { events } from '../query/events.js';
32
+ import { eventBus } from '../../io/utils/eventBus.js';
33
+
34
+ /**
35
+ * Public surface returned by the keybindings factory.
36
+ * @typedef {object} KeybindingsAPI
37
+ * @property {(opts?: { target?: EventTarget, layout?: string, chordTimeout?: number }) => object} create - Create a keybindings manager instance (bind/unbind/contexts/attach/detach/...).
38
+ * @property {(combo: string) => ({ modifiers: object, key: string } | Array<{ modifiers: object, key: string }>)} parse - Parse a combo string into a single segment (simple) or an array of segments (chord).
39
+ */
40
+
41
+ export const keybindings = {
42
+ name: 'keybindings',
43
+ version: '1.0.0',
44
+ type: 'fw.dom.utils',
45
+ dependencies: ['events', 'eventBus'],
46
+ deps: [events, eventBus],
47
+
48
+ /**
49
+ * @param {Object} events - Module events (fw)
50
+ * @param {Object} eventBus - Module eventBus (fw)
51
+ * @returns {KeybindingsAPI}
52
+ */
53
+ factory(events, eventBus) {
54
+
55
+ // ── Key mapping constants ────────────────────────────────────────────
56
+
57
+ /** Special keys → expected event.key */
58
+ const NAMED_KEYS = new Set([
59
+ 'Escape', 'Tab', 'Enter', 'Space', 'Backspace', 'Delete', 'Insert',
60
+ 'Home', 'End', 'PageUp', 'PageDown',
61
+ 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight',
62
+ 'F1', 'F2', 'F3', 'F4', 'F5', 'F6',
63
+ 'F7', 'F8', 'F9', 'F10', 'F11', 'F12',
64
+ ]);
65
+
66
+ /** Accepted key aliases (case-insensitive) → normalised key */
67
+ const KEY_ALIASES = {
68
+ esc: 'Escape',
69
+ escape: 'Escape',
70
+ return: 'Enter',
71
+ enter: 'Enter',
72
+ tab: 'Tab',
73
+ space: 'Space',
74
+ backspace: 'Backspace',
75
+ del: 'Delete',
76
+ delete: 'Delete',
77
+ insert: 'Insert',
78
+ home: 'Home',
79
+ end: 'End',
80
+ pageup: 'PageUp',
81
+ pagedown: 'PageDown',
82
+ up: 'ArrowUp',
83
+ down: 'ArrowDown',
84
+ left: 'ArrowLeft',
85
+ right: 'ArrowRight',
86
+ arrowup: 'ArrowUp',
87
+ arrowdown: 'ArrowDown',
88
+ arrowleft: 'ArrowLeft',
89
+ arrowright: 'ArrowRight',
90
+ plus: 'Plus',
91
+ minus: 'Minus',
92
+ equal: 'Equal',
93
+ equals: 'Equal',
94
+ '-': 'Minus',
95
+ '=': 'Equal',
96
+ };
97
+
98
+ /** Punctuation keys matched on event.key (the typed character, layout-independent by construction). */
99
+ const PUNCTUATION_KEYS = { '+': 'Plus', '-': 'Minus', '=': 'Equal' };
100
+ const PUNCTUATION_NAMES = new Set(Object.values(PUNCTUATION_KEYS));
101
+
102
+ /** Accepted modifier names (lowercase) */
103
+ const MODIFIER_NAMES = new Set(['ctrl', 'shift', 'alt', 'meta', 'cmd', 'super']);
104
+
105
+ // ── Parser ─────────────────────────────────────────────────────────
106
+
107
+ /**
108
+ * Parse a single combo segment (e.g. `'Ctrl+Shift+P'`).
109
+ * @param {string} segment
110
+ * @returns {{ modifiers: {ctrl, shift, alt, meta}, key: string }}
111
+ */
112
+ function _parseSegment(segment) {
113
+ const parts = segment.split('+');
114
+ const modifiers = { ctrl: false, shift: false, alt: false, meta: false };
115
+ let key = null;
116
+
117
+ for (const raw of parts) {
118
+ const lower = raw.toLowerCase();
119
+ if (MODIFIER_NAMES.has(lower)) {
120
+ if (lower === 'cmd' || lower === 'super') {
121
+ modifiers.meta = true;
122
+ } else {
123
+ modifiers[lower] = true;
124
+ }
125
+ } else if (raw.length === 0) {
126
+ // double `+` (e.g. 'Ctrl++')
127
+ throw new Error('keybindings: invalid combo segment "' + segment + '"');
128
+ } else {
129
+ if (key !== null) {
130
+ throw new Error('keybindings: multiple non-modifier keys in segment "' + segment + '"');
131
+ }
132
+ // Try alias, then NAMED_KEYS, then letter/digit
133
+ const alias = KEY_ALIASES[lower];
134
+ if (alias) {
135
+ key = alias;
136
+ } else if (NAMED_KEYS.has(raw)) {
137
+ key = raw;
138
+ } else if (/^[a-zA-Z0-9]$/.test(raw)) {
139
+ key = raw.toLowerCase();
140
+ } else {
141
+ throw new Error('keybindings: unknown key "' + raw + '" in segment "' + segment + '"');
142
+ }
143
+ }
144
+ }
145
+
146
+ if (modifiers.shift && key !== null && PUNCTUATION_NAMES.has(key)) {
147
+ throw new Error('keybindings: Shift cannot qualify punctuation key "' + key + '" in segment "' + segment + '"');
148
+ }
149
+
150
+ if (key === null) {
151
+ throw new Error('keybindings: no key specified in segment "' + segment + '"');
152
+ }
153
+
154
+ return { modifiers, key };
155
+ }
156
+
157
+ /**
158
+ * Parse a full combo string.
159
+ * - simple (`'Ctrl+S'`) → `{modifiers, key}`
160
+ * - chord (`'Ctrl+K Ctrl+P'`) → `[{modifiers, key}, {modifiers, key}]`
161
+ *
162
+ * @param {string} combo
163
+ * @returns {{ modifiers: Object, key: string } | Array<{ modifiers: Object, key: string }>}
164
+ */
165
+ function parse(combo) {
166
+ if (typeof combo !== 'string' || combo.trim().length === 0) {
167
+ throw new TypeError('keybindings: combo must be a non-empty string');
168
+ }
169
+ const segments = combo.trim().split(' ').filter(s => s.length > 0);
170
+ if (segments.length === 1) {
171
+ return _parseSegment(segments[0]);
172
+ }
173
+ return segments.map(s => _parseSegment(s));
174
+ }
175
+
176
+ // ── event.key normalisation ──────────────────────────────────────────
177
+
178
+ /**
179
+ * Normalise a KeyboardEvent to a key comparable to the one produced by `parse`.
180
+ * For alpha-numeric keys, uses `event.code` (e.g. 'KeyA' → 'a').
181
+ * For named keys, uses `event.key`.
182
+ * @param {KeyboardEvent} event
183
+ * @returns {string|null}
184
+ */
185
+ function _normalizeEventKey(event) {
186
+ // Named keys via event.key
187
+ const key = event.key;
188
+ if (NAMED_KEYS.has(key)) return key;
189
+ // Alias via event.key
190
+ const aliased = KEY_ALIASES[key.toLowerCase()];
191
+ if (aliased) return aliased;
192
+ // Punctuation via event.key (typed character, Shift/numpad agnostic)
193
+ if (PUNCTUATION_KEYS[key]) return PUNCTUATION_KEYS[key];
194
+ // Alpha-numeric via event.code (layout-independent)
195
+ const code = event.code;
196
+ if (code && /^Key[A-Z]$/.test(code)) return code.slice(3).toLowerCase();
197
+ if (code && /^Digit[0-9]$/.test(code)) return code.slice(5);
198
+ // Fallback: event.key lowercased if a single character
199
+ if (key.length === 1) return key.toLowerCase();
200
+ return null;
201
+ }
202
+
203
+ /**
204
+ * Test whether a KeyboardEvent matches a parsed segment.
205
+ * @param {KeyboardEvent} event
206
+ * @param {{ modifiers: Object, key: string }} seg
207
+ * @returns {boolean}
208
+ */
209
+ function _matchesSegment(event, seg) {
210
+ const { modifiers, key } = seg;
211
+ // Windows merges `Ctrl+Alt` into `AltGr`; Firefox then reports
212
+ // `getModifierState('AltGraph') === true` while `ctrlKey`/`altKey`
213
+ // are `false`. Normalise: AltGr active ⇒ Ctrl and Alt both effective.
214
+ // This makes `Ctrl+Alt+X` match both AltGr (Firefox) and the legacy
215
+ // ctrl+alt (Chrome) without false positives on combos that only
216
+ // require one of the two modifiers.
217
+ const altGr = typeof event.getModifierState === 'function'
218
+ && event.getModifierState('AltGraph');
219
+ const evCtrl = event.ctrlKey || altGr;
220
+ const evAlt = event.altKey || altGr;
221
+ if (evCtrl !== modifiers.ctrl) return false;
222
+ if (!PUNCTUATION_NAMES.has(key) && event.shiftKey !== modifiers.shift) return false;
223
+ if (evAlt !== modifiers.alt) return false;
224
+ if (event.metaKey !== modifiers.meta) return false;
225
+ return _normalizeEventKey(event) === key;
226
+ }
227
+
228
+ // ── Instance factory ─────────────────────────────────────────────────
229
+
230
+ /**
231
+ * Create a keyboard shortcut manager instance.
232
+ * @param {Object} [opts={}]
233
+ * @param {EventTarget} [opts.target] - Listening target. Defaults to `document`.
234
+ * @param {string} [opts.layout] - Keyboard layout: 'us'|'fr'|'auto' (reserved for future use).
235
+ * @param {number} [opts.chordTimeout=1500] - Chord timeout in ms.
236
+ * @returns {Object} keybindings instance
237
+ */
238
+ function create(opts = {}) {
239
+ const target = opts.target || document;
240
+ const chordTimeout = typeof opts.chordTimeout === 'number' ? opts.chordTimeout : 1500;
241
+
242
+ const _bus = eventBus.create();
243
+
244
+ // Bindings list: { combo, parsed, context, priority, preventDefault, repeat, fn }
245
+ const _bindings = [];
246
+
247
+ // Context stack
248
+ const _contextStack = [];
249
+
250
+ // Pending chord state
251
+ let _chordPending = null; // { candidates: Binding[], matched: number, timer: id }
252
+
253
+ let _attached = false;
254
+
255
+ // ── Bindings management ──────────────────────────────────────────
256
+
257
+ /**
258
+ * Registers a keyboard shortcut.
259
+ *
260
+ * **Chord priority tiebreaker.** When multiple chord bindings share
261
+ * the same prefix and identical `priority`, only the first registered
262
+ * candidate fires (deterministic by definition order). Plain
263
+ * (non-chord) bindings at equal max priority all fire - chord
264
+ * arbitration is single-winner by design.
265
+ *
266
+ * @param {string} combo
267
+ * @param {Function} fn
268
+ * @param {Object} [opts2={}]
269
+ * @param {string} [opts2.context]
270
+ * @param {number} [opts2.priority=0]
271
+ * @param {boolean} [opts2.preventDefault=true]
272
+ * @param {boolean} [opts2.repeat=false]
273
+ * @returns {Function} unbind
274
+ */
275
+ function bind(combo, fn, opts2 = {}) {
276
+ if (typeof combo !== 'string') throw new TypeError('keybindings.bind: combo must be a string');
277
+ if (typeof fn !== 'function') throw new TypeError('keybindings.bind: fn must be a function');
278
+
279
+ const parsed = parse(combo);
280
+ const context = opts2.context || null;
281
+ const priority = typeof opts2.priority === 'number' ? opts2.priority : 0;
282
+ const prev = opts2.preventDefault !== false; // true by default
283
+ const repeat = opts2.repeat === true; // false by default
284
+
285
+ const entry = { combo, parsed, context, priority, preventDefault: prev, repeat, fn };
286
+ _bindings.push(entry);
287
+
288
+ return function unbind() {
289
+ const idx = _bindings.indexOf(entry);
290
+ if (idx !== -1) _bindings.splice(idx, 1);
291
+ };
292
+ }
293
+
294
+ /**
295
+ * Unregister a combo (all handlers when `fn` is omitted).
296
+ * @param {string} combo
297
+ * @param {Function} [fn]
298
+ */
299
+ function unbind(combo, fn) {
300
+ for (let i = _bindings.length - 1; i >= 0; i--) {
301
+ if (_bindings[i].combo === combo) {
302
+ if (!fn || _bindings[i].fn === fn) {
303
+ _bindings.splice(i, 1);
304
+ }
305
+ }
306
+ }
307
+ }
308
+
309
+ // ── Context ──────────────────────────────────────────────────────
310
+
311
+ /**
312
+ * Push a context onto the stack.
313
+ * @param {string} name
314
+ */
315
+ function pushContext(name) {
316
+ _contextStack.push(name);
317
+ }
318
+
319
+ /**
320
+ * Pops the current context.
321
+ * @returns {string} Popped context name.
322
+ * @throws {RangeError} If the context stack is empty.
323
+ */
324
+ function popContext() {
325
+ if (_contextStack.length === 0) {
326
+ throw new RangeError('keybindings: context stack underflow');
327
+ }
328
+ return _contextStack.pop();
329
+ }
330
+
331
+ /**
332
+ * Return a copy of the context stack.
333
+ * @returns {string[]}
334
+ */
335
+ function currentContext() {
336
+ return [..._contextStack];
337
+ }
338
+
339
+ // ── Inspection ───────────────────────────────────────────────────
340
+
341
+ /**
342
+ * Return the list of all registered bindings.
343
+ * @returns {Array<{combo, context, priority, fn}>}
344
+ */
345
+ function list() {
346
+ return _bindings.map(b => ({
347
+ combo: b.combo,
348
+ context: b.context,
349
+ priority: b.priority,
350
+ fn: b.fn,
351
+ }));
352
+ }
353
+
354
+ /**
355
+ * Return the bindings that would be triggered by this event.
356
+ * @param {KeyboardEvent} event
357
+ * @returns {Array<{combo, context, priority, fn}>}
358
+ */
359
+ function match(event) {
360
+ return _bindings
361
+ .filter(b => {
362
+ const parsed = b.parsed;
363
+ if (Array.isArray(parsed)) {
364
+ // chord: only the first segment can be matched here
365
+ return _matchesSegment(event, parsed[0]);
366
+ }
367
+ return _matchesSegment(event, parsed);
368
+ })
369
+ .map(b => ({ combo: b.combo, context: b.context, priority: b.priority, fn: b.fn }));
370
+ }
371
+
372
+ // ── Dispatch logic ───────────────────────────────────────────────
373
+
374
+ /**
375
+ * Filter bindings by the current context.
376
+ * Rule: when a context is active (non-empty stack), only bindings
377
+ * whose `context === top of stack` are allowed.
378
+ * In practice: when the stack is non-empty, only bindings from the
379
+ * current context fire; context-less bindings are ignored while a
380
+ * context is active.
381
+ *
382
+ * @param {Array} candidates
383
+ * @returns {Array}
384
+ */
385
+ function _filterByContext(candidates) {
386
+ const ctx = _contextStack.length > 0 ? _contextStack[_contextStack.length - 1] : null;
387
+ if (ctx === null) {
388
+ // No active context: only context-less bindings
389
+ return candidates.filter(b => b.context === null);
390
+ }
391
+ // Active context: only bindings for that context
392
+ return candidates.filter(b => b.context === ctx);
393
+ }
394
+
395
+ /**
396
+ * Execute the bindings with the highest priority (ties → all of them).
397
+ * @param {Array} matched - bindings filtered by context
398
+ * @param {KeyboardEvent} event
399
+ */
400
+ /** The highest-priority binding of `list` (the first registered on a tie). */
401
+ function _highest(list) {
402
+ return list.reduce((a, b) => b.priority > a.priority ? b : a, list[0]);
403
+ }
404
+
405
+ function _dispatch(matched, event) {
406
+ if (matched.length === 0) return;
407
+
408
+ // Maximum priority
409
+ const maxPriority = matched.reduce((m, b) => Math.max(m, b.priority), -Infinity);
410
+ const toRun = matched.filter(b => b.priority === maxPriority);
411
+
412
+ for (const b of toRun) {
413
+ if (b.preventDefault) event.preventDefault();
414
+ try {
415
+ b.fn(event);
416
+ } catch (e) {
417
+
418
+ console.error('keybindings handler error:', e);
419
+ }
420
+ _bus.emit('keybindings:matched', { combo: b.combo, context: b.context, fn: b.fn });
421
+ }
422
+ }
423
+
424
+ /**
425
+ * Main keydown handler.
426
+ * @param {KeyboardEvent} event
427
+ */
428
+ function _onKeyDown(event) {
429
+ // Filter event.repeat when binding.repeat === false.
430
+ // Note: filtering happens per binding below, but if all candidates
431
+ // reject repeat we can exit early.
432
+
433
+ // ── Step 1: handle a pending chord ──────────────────────────
434
+ // Every candidate whose segments so far matched is kept, so two
435
+ // chords sharing a prefix (`g a`, `g h`) can both complete.
436
+ if (_chordPending) {
437
+ const { candidates, matched, timer } = _chordPending;
438
+ clearTimeout(timer);
439
+ _chordPending = null;
440
+
441
+ const nextIdx = matched + 1;
442
+ const survivors = candidates.filter(b => _matchesSegment(event, b.parsed[nextIdx]));
443
+ if (survivors.length > 0) {
444
+ const complete = survivors.filter(b => b.parsed.length - 1 === nextIdx);
445
+ if (complete.length > 0) {
446
+ // A chord that completes on this key wins over a longer
447
+ // one sharing its prefix; among them the highest
448
+ // priority fires (the first registered on a tie).
449
+ const b = _highest(complete);
450
+ if (b.repeat || !event.repeat) {
451
+ if (b.preventDefault) event.preventDefault();
452
+ try {
453
+ b.fn(event);
454
+ } catch (e) {
455
+
456
+ console.error('keybindings chord handler error:', e);
457
+ }
458
+ _bus.emit('keybindings:matched', { combo: b.combo, context: b.context, fn: b.fn });
459
+ }
460
+ } else {
461
+ // More segments still to come
462
+ _chordPending = {
463
+ candidates: survivors,
464
+ matched: nextIdx,
465
+ timer: setTimeout(() => { _chordPending = null; }, chordTimeout),
466
+ };
467
+ }
468
+ return; // Ne pas traiter comme binding simple
469
+ }
470
+ // The key matches no candidate → cancel the chord
471
+ // and continue normal processing
472
+ }
473
+
474
+ // ── Step 2: look for chord candidates ───────────────────────
475
+ const chordCandidates = _bindings.filter(b => {
476
+ if (!Array.isArray(b.parsed)) return false;
477
+ if (!_matchesSegment(event, b.parsed[0])) return false;
478
+ // Check context
479
+ const ctx = _contextStack.length > 0 ? _contextStack[_contextStack.length - 1] : null;
480
+ if (ctx === null) return b.context === null;
481
+ return b.context === ctx;
482
+ });
483
+
484
+ if (chordCandidates.length > 0) {
485
+ // Start the chord with every candidate; the next keys narrow the set.
486
+ _chordPending = {
487
+ candidates: chordCandidates,
488
+ matched: 0,
489
+ timer: setTimeout(() => { _chordPending = null; }, chordTimeout),
490
+ };
491
+ // Do not trigger a simple binding immediately
492
+ return;
493
+ }
494
+
495
+ // ── Step 3: simple bindings ──────────────────────────────────
496
+ const simpleCandidates = _bindings.filter(b => {
497
+ if (Array.isArray(b.parsed)) return false;
498
+ return _matchesSegment(event, b.parsed);
499
+ });
500
+
501
+ const contextFiltered = _filterByContext(simpleCandidates);
502
+ const repeatFiltered = contextFiltered.filter(b => b.repeat || !event.repeat);
503
+
504
+ _dispatch(repeatFiltered, event);
505
+ }
506
+
507
+ // ── Attach / detach ───────────────────────────────────────────────
508
+
509
+ /**
510
+ * Enable keyboard event listening.
511
+ */
512
+ function attach() {
513
+ if (_attached) return;
514
+ _attached = true;
515
+ target.addEventListener('keydown', _onKeyDown);
516
+ }
517
+
518
+ /**
519
+ * Disable keyboard event listening.
520
+ */
521
+ function detach() {
522
+ if (!_attached) return;
523
+ _attached = false;
524
+ target.removeEventListener('keydown', _onKeyDown);
525
+ if (_chordPending) {
526
+ clearTimeout(_chordPending.timer);
527
+ _chordPending = null;
528
+ }
529
+ }
530
+
531
+ /**
532
+ * Dispose the instance (detach listeners and clear all bindings).
533
+ */
534
+ function dispose() {
535
+ detach();
536
+ _bindings.length = 0;
537
+ _contextStack.length = 0;
538
+ }
539
+
540
+ /**
541
+ * Create a scoped sub-controller. Every `bind(...)` called through
542
+ * the returned scope is tracked ; calling `scope.dispose()` (or
543
+ * `scope.clear()`) unbinds them all at once **without** disposing
544
+ * the parent instance.
545
+ *
546
+ * Intended for `ui.mount(blockId, null, () => kb.scope())` so a
547
+ * modal/component's keybindings are auto-detached when the block
548
+ * is cleared.
549
+ *
550
+ * @returns {{
551
+ * bind: Function, unbind: Function,
552
+ * pushContext: Function, popContext: Function,
553
+ * dispose: Function, clear: Function
554
+ * }}
555
+ */
556
+ function scope() {
557
+ const unbinders = new Set();
558
+
559
+ function scopeBind(...args) {
560
+ // @ts-ignore - spread forwarding of variadic handler args
561
+ const off = bind(...args);
562
+ unbinders.add(off);
563
+ return off;
564
+ }
565
+
566
+ function clear() {
567
+ for (const off of unbinders) {
568
+ try { off(); } catch { /* swallow */ }
569
+ }
570
+ unbinders.clear();
571
+ }
572
+
573
+ return {
574
+ bind: scopeBind,
575
+ unbind,
576
+ pushContext,
577
+ popContext,
578
+ dispose: clear,
579
+ clear,
580
+ };
581
+ }
582
+
583
+ return {
584
+ bind,
585
+ unbind,
586
+ pushContext,
587
+ popContext,
588
+ currentContext,
589
+ list,
590
+ match,
591
+ attach,
592
+ detach,
593
+ dispose,
594
+ scope,
595
+ };
596
+ }
597
+
598
+ return { create, parse };
599
+ }
600
+ };