also looking at this
feat(bridge): let the page ask what native actually serves
#60
20 files
+1546
-37
| @@ -11,6 +11,7 @@ The Craft JavaScript Bridge provides a seamless interface for your web applicati | ||
| 11 | 11 | - [Global Shortcuts (macOS)](#global-shortcuts-macos) |
| 12 | 12 | - [Settings and Preferences (macOS)](#settings-and-preferences-macos) |
| 13 | 13 | - [Headless mode](#headless-mode) |
| 14 | - [Capabilities](#capabilities) | |
| 14 | 15 | - [Window API](#window-api) |
| 15 | 16 | - [App API](#app-api) |
| 16 | 17 | - [TypeScript Support](#typescript-support) |
| @@ -520,6 +521,58 @@ sockets at all — and `safaridriver` refuses to attach to anything that is not | ||
| 520 | 521 | Safari. Driving a craft page from another process needs a control channel craft |
| 521 | 522 | owns, which does not exist yet. |
| 522 | 523 | |
| 524 | ## Capabilities | |
| 525 | ||
| 526 | This script is one blob, `@embedFile`d into the binary and injected whole into | |
| 527 | every craft window — the same JavaScript whatever the native side behind it | |
| 528 | implements. So `typeof window.craft.tray.destroy === 'function'` has never been | |
| 529 | evidence that anything is behind it, and three shipped bugs came from assuming | |
| 530 | otherwise. Ask instead. | |
| 531 | ||
| 532 | ```javascript | |
| 533 | const caps = await window.craft.capabilities() | |
| 534 | ||
| 535 | caps.namespaces.updater.status // 'unavailable' | |
| 536 | caps.namespaces.updater.reason // 'the Sparkle framework is not linked into this build' | |
| 537 | caps.channels['craft:fs:change'] // false — you could subscribe, it would never fire | |
| 538 | ``` | |
| 539 | ||
| 540 | Or, for one surface: | |
| 541 | ||
| 542 | ```javascript | |
| 543 | if (window.craft.supports('tray.destroy')) { /* … */ } | |
| 544 | ``` | |
| 545 | ||
| 546 | ### Namespace status | |
| 547 | ||
| 548 | | status | means | | |
| 549 | |---|---| | |
| 550 | | `declared` | Audited. The action list is complete, and a conformance test fails the build if it stops matching what the dispatcher serves. | | |
| 551 | | `undeclared` | Routed, but craft has not audited it and **will not claim anything either way**. Treat as "try it and handle failure", not as "missing". | | |
| 552 | | `unavailable` | Reachable and known not to work. `reason` says why. | | |
| 553 | | `unrouted` | Implemented natively but absent from the dispatcher, so no message can reach it. | | |
| 554 | ||
| 555 | Most namespaces are `undeclared` today. Declaring one means refactoring its | |
| 556 | dispatch chain so each action name exists in exactly one place — roughly 279 | |
| 557 | names across 47 files — so it is being done in batches, and the conformance test | |
| 558 | holds a ceiling on how many may remain that only ever goes down. | |
| 559 | ||
| 560 | ### `channels` | |
| 561 | ||
| 562 | Every `craft:*` event, and whether anything native emits on it. This cannot be | |
| 563 | derived from the action tables — an emitter is a separate piece of code that may | |
| 564 | or may not have been written — so a channel is reported live only because the | |
| 565 | code that emits on it took out a permit at startup. Sixteen channels the JS | |
| 566 | surface subscribes to currently have no emitter at all. | |
| 567 | ||
| 568 | ### `supports()` fails open | |
| 569 | ||
| 570 | It returns `true` before capabilities have been fetched, and `true` for an | |
| 571 | `undeclared` namespace. A feature-detection mechanism that breaks working code | |
| 572 | when it cannot see itself would be worse than the gaps it describes. Only an | |
| 573 | `unavailable` or `unrouted` surface — or an unknown action inside a `declared` | |
| 574 | namespace — answers `false`. | |
| 575 | ||
| 523 | 576 | ## Window API |
| 524 | 577 | |
| 525 | 578 | Control the application window from JavaScript. |
| @@ -757,6 +810,7 @@ async function onComplete() { | ||
| 757 | 810 | | Global Shortcuts | ✅ | �� | �� | |
| 758 | 811 | | Settings… item | ✅ | �� | �� | |
| 759 | 812 | | Preferences | ✅ | �� | �� | |
| 813 | | Capabilities | ✅ | �� | �� | | |
| 760 | 814 | |
| 761 | 815 | ✅ Implemented | �� In Progress | ➖ Not Applicable |
| 762 | 816 | |