@ignite-ember/extension-bridge 0.0.0-stage → 0.2.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 (69) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +5 -0
  3. package/README.md +303 -2
  4. package/dist/bridge.d.ts +33 -0
  5. package/dist/bridge.d.ts.map +1 -0
  6. package/dist/bridge.js +92 -0
  7. package/dist/bridge.js.map +1 -0
  8. package/dist/channel.d.ts +26 -0
  9. package/dist/channel.d.ts.map +1 -0
  10. package/dist/channel.js +36 -0
  11. package/dist/channel.js.map +1 -0
  12. package/dist/contract.d.ts +110 -0
  13. package/dist/contract.d.ts.map +1 -0
  14. package/dist/contract.js +9 -0
  15. package/dist/contract.js.map +1 -0
  16. package/dist/correlator.d.ts +37 -0
  17. package/dist/correlator.d.ts.map +1 -0
  18. package/dist/correlator.js +67 -0
  19. package/dist/correlator.js.map +1 -0
  20. package/dist/guestBridge.d.ts +63 -0
  21. package/dist/guestBridge.d.ts.map +1 -0
  22. package/dist/guestBridge.js +156 -0
  23. package/dist/guestBridge.js.map +1 -0
  24. package/dist/hostModel.d.ts +155 -0
  25. package/dist/hostModel.d.ts.map +1 -0
  26. package/dist/hostModel.generated.d.ts +1870 -0
  27. package/dist/hostModel.generated.d.ts.map +1 -0
  28. package/dist/hostModel.generated.js +1241 -0
  29. package/dist/hostModel.generated.js.map +1 -0
  30. package/dist/hostModel.js +168 -0
  31. package/dist/hostModel.js.map +1 -0
  32. package/dist/index.d.ts +12 -0
  33. package/dist/index.d.ts.map +1 -0
  34. package/dist/index.js +12 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/protocol.d.ts +338 -0
  37. package/dist/protocol.d.ts.map +1 -0
  38. package/dist/protocol.js +135 -0
  39. package/dist/protocol.js.map +1 -0
  40. package/dist/service.d.ts +143 -0
  41. package/dist/service.d.ts.map +1 -0
  42. package/dist/service.js +179 -0
  43. package/dist/service.js.map +1 -0
  44. package/dist/signals.d.ts +21 -0
  45. package/dist/signals.d.ts.map +1 -0
  46. package/dist/signals.js +52 -0
  47. package/dist/signals.js.map +1 -0
  48. package/dist/tokens.d.ts +95 -0
  49. package/dist/tokens.d.ts.map +1 -0
  50. package/dist/tokens.js +158 -0
  51. package/dist/tokens.js.map +1 -0
  52. package/dist/watchers.d.ts +12 -0
  53. package/dist/watchers.d.ts.map +1 -0
  54. package/dist/watchers.js +18 -0
  55. package/dist/watchers.js.map +1 -0
  56. package/package.json +53 -4
  57. package/src/bridge.ts +112 -0
  58. package/src/channel.ts +48 -0
  59. package/src/contract.ts +130 -0
  60. package/src/correlator.ts +81 -0
  61. package/src/guestBridge.ts +261 -0
  62. package/src/hostModel.generated.ts +2649 -0
  63. package/src/hostModel.ts +209 -0
  64. package/src/index.ts +11 -0
  65. package/src/protocol.ts +475 -0
  66. package/src/service.ts +253 -0
  67. package/src/signals.ts +65 -0
  68. package/src/tokens.ts +165 -0
  69. package/src/watchers.ts +18 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IAC3B,+BAA+B;;IAE/B,sCAAsC;;IAEtC,4BAA4B;;IAE5B,wEAAwE;;IAYxE,8DAA8D;;IAO9D,aAAa;;IAWb;;;;;;;OAOG;;IAYH;;;;;;;OAOG;;CAcK,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EACD,CAAC;AAEzC,kCAAkC;AAClC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,GAAE,OAAkC,GACvC,WAAW,CAWb;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAM7E"}
package/dist/tokens.js ADDED
@@ -0,0 +1,158 @@
1
+ /**
2
+ * The design tokens an extension may rely on, and how they travel.
3
+ *
4
+ * An extension's page is a different origin, so it cannot read this
5
+ * app's stylesheet — and the CSP on its own origin would block
6
+ * fetching one. So the values are **pushed**, over the bridge, at
7
+ * handshake and again whenever they change.
8
+ *
9
+ * Pushed rather than copied into the package on purpose. A static
10
+ * copy is a second description of the theme, and a second description
11
+ * drifts: `theme.css` defines these across forty-five blocks — a
12
+ * ``:root``, a light override, and a ``prefers-color-scheme`` block
13
+ * per feature. Anything duplicating that is wrong within a release.
14
+ * This reads the live computed values instead, so an extension
15
+ * follows dark mode, light mode, and whatever a group's policy pack
16
+ * has branded, without knowing any of those exist.
17
+ *
18
+ * **This list is the floor.** A token named here is one an extension
19
+ * may build against, and removing or repurposing one is a breaking
20
+ * change under the compatibility policy. A token *not* named here is
21
+ * ours to change freely — which is why the list is curated rather
22
+ * than "every custom property in the stylesheet". Layout internals
23
+ * like ``--rail-width`` and ``--crumb-row-h`` are deliberately absent:
24
+ * they describe this app's chrome, and an extension that positioned
25
+ * itself against them would break the first time we moved something.
26
+ */
27
+ /**
28
+ * Published tokens, by what they are for.
29
+ *
30
+ * Grouped because the groups are how an author reads them: pick a
31
+ * surface, pick the text that goes on it, pick a tone for the
32
+ * meaning. Names match the app's own so a reader moving between the
33
+ * two is not translating.
34
+ */
35
+ export const PUBLISHED_TOKENS = {
36
+ /** Surfaces, back to front. */
37
+ surface: ["--bg", "--bg-inset", "--bg-surface", "--bg-raised"],
38
+ /** Text, in descending prominence. */
39
+ text: ["--fg", "--fg-muted", "--fg-faint"],
40
+ /** Lines between things. */
41
+ line: ["--border", "--border-soft"],
42
+ /** Meaning. ``*-text`` variants are the contrast-safe ones for type. */
43
+ tone: [
44
+ "--success",
45
+ "--warning",
46
+ "--danger",
47
+ "--danger-text",
48
+ "--accent-blue",
49
+ "--accent-blue-text",
50
+ "--accent-green-text",
51
+ "--accent-orange-text",
52
+ "--accent-red-text",
53
+ ],
54
+ /** The product's own colour. Use sparingly; it means igni. */
55
+ brand: [
56
+ "--igni-orange",
57
+ "--igni-orange-hover",
58
+ "--igni-red",
59
+ "--igni-gradient",
60
+ ],
61
+ /** Shape. */
62
+ form: [
63
+ "--radius-sm",
64
+ "--radius",
65
+ "--radius-lg",
66
+ "--radius-pill",
67
+ "--radius-circle",
68
+ "--font-ui",
69
+ "--font-mono",
70
+ "--shadow-pop",
71
+ ],
72
+ /**
73
+ * The type scale. Nine steps, by role rather than by ratio.
74
+ *
75
+ * It replaced twenty-two hardcoded sizes that included every
76
+ * half-step from 9px to 15px — 11.5px, 12px and 12.5px between
77
+ * them accounted for 272 declarations, which is one size written
78
+ * three ways. Build against the role, not the pixel.
79
+ */
80
+ type: [
81
+ "--text-2xs",
82
+ "--text-xs",
83
+ "--text-sm",
84
+ "--text-md",
85
+ "--text-lg",
86
+ "--text-xl",
87
+ "--text-2xl",
88
+ "--text-3xl",
89
+ "--text-4xl",
90
+ ],
91
+ /**
92
+ * The spacing scale. Published so an extension's layout sits on the
93
+ * same rhythm as the app around it rather than next to it.
94
+ *
95
+ * These steps are the ones igni already used — they were written as
96
+ * literals in three hundred and seventy-five places, which is why
97
+ * adopting them changed nothing on screen.
98
+ */
99
+ space: [
100
+ "--space-1",
101
+ "--space-2",
102
+ "--space-3",
103
+ "--space-4",
104
+ "--space-5",
105
+ "--space-6",
106
+ "--space-7",
107
+ "--space-8",
108
+ "--space-10",
109
+ "--space-12",
110
+ "--space-16",
111
+ ],
112
+ };
113
+ /**
114
+ * Every published token name, flat.
115
+ *
116
+ * Derived rather than listed. A second list would be a second place
117
+ * to forget — and the groups above are an object literal, where a
118
+ * repeated key silently keeps only the last one. That happened: the
119
+ * type scale was added as `text`, which was already the foreground
120
+ * colours, and `--fg` disappeared without a word.
121
+ */
122
+ export const TOKEN_NAMES = Object.values(PUBLISHED_TOKENS).flat();
123
+ /**
124
+ * Read the published tokens as they are right now.
125
+ *
126
+ * Computed values, not declared ones: a token defined in a media
127
+ * query or overridden by a `data-theme` attribute resolves here to
128
+ * what the user is actually looking at, which is the only answer
129
+ * worth sending.
130
+ */
131
+ export function readThemeTokens(root = document.documentElement) {
132
+ const computed = getComputedStyle(root);
133
+ const out = {};
134
+ for (const name of TOKEN_NAMES) {
135
+ const value = computed.getPropertyValue(name).trim();
136
+ // A token the host has not defined is omitted rather than sent
137
+ // empty: the guest's stylesheet carries a fallback for each, and
138
+ // an empty string would override it with nothing.
139
+ if (value)
140
+ out[name] = value;
141
+ }
142
+ return out;
143
+ }
144
+ /**
145
+ * Apply tokens inside the extension's own document.
146
+ *
147
+ * Called by the guest bridge. Separate from reading them so the two
148
+ * halves can be tested without a frame between them.
149
+ */
150
+ export function applyThemeTokens(tokens, root) {
151
+ for (const [name, value] of Object.entries(tokens)) {
152
+ // Only published names, even though the host is trusted: a typo
153
+ // on our side should not silently define something in theirs.
154
+ if (TOKEN_NAMES.includes(name))
155
+ root.style.setProperty(name, value);
156
+ }
157
+ }
158
+ //# sourceMappingURL=tokens.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,+BAA+B;IAC/B,OAAO,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,CAAC;IAC9D,sCAAsC;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,CAAC;IAC1C,4BAA4B;IAC5B,IAAI,EAAE,CAAC,UAAU,EAAE,eAAe,CAAC;IACnC,wEAAwE;IACxE,IAAI,EAAE;QACJ,WAAW;QACX,WAAW;QACX,UAAU;QACV,eAAe;QACf,eAAe;QACf,oBAAoB;QACpB,qBAAqB;QACrB,sBAAsB;QACtB,mBAAmB;KACpB;IACD,8DAA8D;IAC9D,KAAK,EAAE;QACL,eAAe;QACf,qBAAqB;QACrB,YAAY;QACZ,iBAAiB;KAClB;IACD,aAAa;IACb,IAAI,EAAE;QACJ,aAAa;QACb,UAAU;QACV,aAAa;QACb,eAAe;QACf,iBAAiB;QACjB,WAAW;QACX,aAAa;QACb,cAAc;KACf;IACD;;;;;;;OAOG;IACH,IAAI,EAAE;QACJ,YAAY;QACZ,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,YAAY;KACb;IACD;;;;;;;OAOG;IACH,KAAK,EAAE;QACL,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,YAAY;KACb;CACO,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC;AAKzC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,QAAQ,CAAC,eAAe;IAExC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,+DAA+D;QAC/D,iEAAiE;QACjE,kDAAkD;QAClD,IAAI,KAAK;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB,EAAE,IAAiB;IACrE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,gEAAgE;QAChE,8DAA8D;QAC9D,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}
@@ -0,0 +1,12 @@
1
+ /** Functions following one value: added, removed, and told of a change. */
2
+ export declare class Watchers<T> {
3
+ private readonly fns;
4
+ /**
5
+ * Follow the value. Returns an unsubscribe, which answers whether it
6
+ * stopped anything: true the first time, false after.
7
+ */
8
+ add(fn: (value: T) => void): () => void;
9
+ /** Tell every watcher the value is now `value`. */
10
+ emit(value: T): void;
11
+ }
12
+ //# sourceMappingURL=watchers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"watchers.d.ts","sourceRoot":"","sources":["../src/watchers.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;IAErD;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKvC,mDAAmD;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;CAGrB"}
@@ -0,0 +1,18 @@
1
+ /** Functions following one value: added, removed, and told of a change. */
2
+ export class Watchers {
3
+ fns = new Set();
4
+ /**
5
+ * Follow the value. Returns an unsubscribe, which answers whether it
6
+ * stopped anything: true the first time, false after.
7
+ */
8
+ add(fn) {
9
+ this.fns.add(fn);
10
+ return () => this.fns.delete(fn);
11
+ }
12
+ /** Tell every watcher the value is now `value`. */
13
+ emit(value) {
14
+ for (const fn of this.fns)
15
+ fn(value);
16
+ }
17
+ }
18
+ //# sourceMappingURL=watchers.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"watchers.js","sourceRoot":"","sources":["../src/watchers.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,OAAO,QAAQ;IACF,GAAG,GAAG,IAAI,GAAG,EAAsB,CAAC;IAErD;;;OAGG;IACH,GAAG,CAAC,EAAsB;QACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,mDAAmD;IACnD,IAAI,CAAC,KAAQ;QACX,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,GAAG;YAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}
package/package.json CHANGED
@@ -1,6 +1,55 @@
1
1
  {
2
2
  "name": "@ignite-ember/extension-bridge",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "The guest half of the bridge between an igni extension's page and igni: connect(), RPC, navigation, theme. The host imports the same protocol, so there is one description of the wire.",
5
+ "keywords": [
6
+ "igni",
7
+ "extension",
8
+ "bridge",
9
+ "iframe",
10
+ "postmessage"
11
+ ],
12
+ "license": "Apache-2.0",
13
+ "author": "Ignite Ember (https://ignite-ember.sh/)",
14
+ "homepage": "https://ignite-ember.sh/docs/sdk/extension-bridge",
15
+ "documentation": "https://ignite-ember.sh/docs/sdk/extension-bridge",
16
+ "bugs": {
17
+ "url": "https://github.com/ignite-ember/igni-sdk/issues"
18
+ },
19
+ "repository": {
20
+ "type": "git",
21
+ "url": "git+https://github.com/ignite-ember/igni-sdk.git",
22
+ "directory": "packages/extension-bridge"
23
+ },
24
+ "type": "module",
25
+ "main": "./dist/index.js",
26
+ "types": "./dist/index.d.ts",
27
+ "exports": {
28
+ ".": {
29
+ "types": "./dist/index.d.ts",
30
+ "node": "./dist/index.js",
31
+ "default": "./src/index.ts"
32
+ },
33
+ "./protocol": {
34
+ "types": "./dist/protocol.d.ts",
35
+ "node": "./dist/protocol.js",
36
+ "default": "./src/protocol.ts"
37
+ },
38
+ "./tokens": {
39
+ "types": "./dist/tokens.d.ts",
40
+ "node": "./dist/tokens.js",
41
+ "default": "./src/tokens.ts"
42
+ }
43
+ },
44
+ "files": [
45
+ "src",
46
+ "dist",
47
+ "!src/**/*.test.ts",
48
+ "README.md",
49
+ "LICENSE",
50
+ "NOTICE"
51
+ ],
52
+ "publishConfig": {
53
+ "access": "public"
54
+ }
55
+ }
package/src/bridge.ts ADDED
@@ -0,0 +1,112 @@
1
+ /**
2
+ * The guest half: what an extension's page imports to reach igni.
3
+ *
4
+ * This is the file that becomes a published package. Nothing in it
5
+ * imports from the rest of the app, and nothing in it is trusted by
6
+ * the host — every check is on the other side. What it owes an
7
+ * extension author is an object that behaves like the client they
8
+ * would have had if their panel were part of the app, so that porting
9
+ * one is not a rewrite.
10
+ *
11
+ * The shape it presents is `rpc(method, args, timeoutMs)`, which is
12
+ * the whole surface the first panel ported behind it used. Everything else here —
13
+ * navigate, close, theme, params — is what a panel needed from the
14
+ * app around it and used to get by being inside it.
15
+ */
16
+
17
+ import { HostChannel } from "./channel.js";
18
+ import type { Bridge } from "./contract.js";
19
+ import { DEFAULT_TIMEOUT_MS, GuestBridge } from "./guestBridge.js";
20
+ import {
21
+ type ExtensionSettings,
22
+ type LaunchParams,
23
+ type RpcArgs,
24
+ isHostMessage,
25
+ } from "./protocol.js";
26
+
27
+ /**
28
+ * Wait for the host's `hello`, then hand back the bridge.
29
+ *
30
+ * Connecting is asynchronous because the host issues the nonce, and
31
+ * without one there is nothing to say. An extension that renders
32
+ * before awaiting this is rendering before it knows which extension
33
+ * it is.
34
+ *
35
+ * `P` and `S` name the extension's own launch parameters and settings;
36
+ * the bridge passes on what the host sent without checking it against
37
+ * them.
38
+ */
39
+ export function connect<
40
+ P extends LaunchParams = LaunchParams,
41
+ S extends ExtensionSettings = ExtensionSettings,
42
+ >(options: { timeoutMs?: number } = {}): Promise<Bridge<P, S>> {
43
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
44
+ const host = window.parent;
45
+ if (host === window) {
46
+ return Promise.reject(
47
+ new Error(
48
+ "igni bridge: this page is not framed by a host, so there is nothing to connect to",
49
+ ),
50
+ );
51
+ }
52
+
53
+ return new Promise<Bridge<P, S>>((resolve, reject) => {
54
+ const timer = setTimeout(() => {
55
+ window.removeEventListener("message", onHello);
56
+ reject(
57
+ new Error(`igni bridge: no hello from the host within ${timeoutMs}ms`),
58
+ );
59
+ }, timeoutMs);
60
+
61
+ function onHello(event: MessageEvent) {
62
+ if (event.source !== host) return;
63
+ if (!isHostMessage(event.data) || event.data.kind !== "hello") return;
64
+ clearTimeout(timer);
65
+ window.removeEventListener("message", onHello);
66
+ const channel = new HostChannel(host, event.data.nonce);
67
+ const bridge = new GuestBridge<P, S>(channel, event.data);
68
+ window.addEventListener("message", (message: MessageEvent) => {
69
+ if (!channel.isFrom(message) || !isHostMessage(message.data)) return;
70
+ bridge.receive(message.data);
71
+ });
72
+ resolve(expose(bridge));
73
+ }
74
+
75
+ window.addEventListener("message", onHello);
76
+ });
77
+ }
78
+
79
+ /**
80
+ * The bridge as the page holds it: a plain object whose members close
81
+ * over the one that does the work. So `const { rpc } = bridge`,
82
+ * `onClick={bridge.close}` and `{ ...bridge }` behave as they did before
83
+ * the bridge was a class, and nothing the page did not ask for — the
84
+ * nonce, the requests in flight — is one of its properties.
85
+ */
86
+ function expose<P extends LaunchParams, S extends ExtensionSettings>(
87
+ bridge: GuestBridge<P, S>,
88
+ ): Bridge<P, S> {
89
+ return {
90
+ extensionId: bridge.extensionId,
91
+ host: bridge.host,
92
+ service: bridge.service,
93
+ on: (signal, fn, onRefused) => bridge.on(signal, fn, onRefused),
94
+ get params() {
95
+ return bridge.params;
96
+ },
97
+ settings: bridge.settings,
98
+ get theme() {
99
+ return bridge.theme;
100
+ },
101
+ get tokens() {
102
+ return bridge.tokens;
103
+ },
104
+ rpc: <T>(method: string, args?: RpcArgs, timeoutMs?: number) =>
105
+ bridge.rpc<T>(method, args, timeoutMs),
106
+ navigate: (to) => bridge.navigate(to),
107
+ close: () => bridge.close(),
108
+ onTheme: (fn) => bridge.onTheme(fn),
109
+ onParams: (fn) => bridge.onParams(fn),
110
+ setLocation: (state) => bridge.setLocation(state),
111
+ };
112
+ }
package/src/channel.ts ADDED
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The guest's line to the window it is framed in: who that window is,
3
+ * and the nonce every message to it must carry.
4
+ */
5
+
6
+ import { BRIDGE_VERSION, type GuestMessage } from "./protocol.js";
7
+
8
+ /** A guest message without the envelope `HostChannel` adds. */
9
+ export type GuestBody = {
10
+ [K in GuestMessage["kind"]]: Omit<
11
+ Extract<GuestMessage, { kind: K }>,
12
+ "igni" | "nonce"
13
+ >;
14
+ }[GuestMessage["kind"]];
15
+
16
+ export class HostChannel {
17
+ constructor(
18
+ private readonly host: Window,
19
+ private readonly nonce: string,
20
+ ) {}
21
+
22
+ /**
23
+ * Did this event come from the host? The host is the only window that
24
+ * can reach this frame's parent slot, so the source is the check that
25
+ * matters. The origin is not pinned: the guest does not know which
26
+ * origin the app is served from, and learning it from the message
27
+ * would make the check circular.
28
+ */
29
+ isFrom(event: MessageEvent): boolean {
30
+ return event.source === this.host;
31
+ }
32
+
33
+ post(body: GuestBody): void {
34
+ // Targeted at "*" deliberately: the guest does not know the host's
35
+ // origin, and guessing one would mean a message silently going
36
+ // nowhere the first time the app is served from somewhere else.
37
+ // Nothing secret travels in this direction — the host authorises,
38
+ // the guest only asks.
39
+ // `kind` before `nonce`, as the guest always posted them: the fields
40
+ // are the same either way, but a host or a log that compares the
41
+ // serialised message sees the order.
42
+ const { kind, ...rest } = body;
43
+ this.host.postMessage(
44
+ { igni: BRIDGE_VERSION, kind, nonce: this.nonce, ...rest },
45
+ "*",
46
+ );
47
+ }
48
+ }
@@ -0,0 +1,130 @@
1
+ /**
2
+ * What an extension's page is handed by `connect()`.
3
+ *
4
+ * `P` and `S` are the extension's own launch parameters and settings:
5
+ * the host sends whatever the extension's links and manifest put there,
6
+ * so the extension is the one that can name them.
7
+ */
8
+
9
+ import type { HostError, Signal } from "./hostModel.js";
10
+ import type { Host } from "./hostModel.generated.js";
11
+ import type {
12
+ ExtensionSettings,
13
+ LaunchParams,
14
+ LocationState,
15
+ RpcArgs,
16
+ } from "./protocol.js";
17
+ import type { ServiceBridge } from "./service.js";
18
+ import type { ThemeTokens } from "./tokens.js";
19
+
20
+ /** What an extension's page is handed. */
21
+ export interface Bridge<
22
+ P extends LaunchParams = LaunchParams,
23
+ S extends ExtensionSettings = ExtensionSettings,
24
+ > {
25
+ /** The id this frame is, as the host named it. */
26
+ readonly extensionId: string;
27
+ /** Launch parameters, as the host passed them. */
28
+ readonly params: P;
29
+ /**
30
+ * What `contributes.settings` is configured to.
31
+ *
32
+ * Fixed for the life of this frame — a change applies at the next
33
+ * mount, so there is no `onSettings`. Separate from {@link params}
34
+ * because that is *where you are* and this is *how you are set
35
+ * up*; one namespace for both would make a setting and a query
36
+ * key with the same name the same thing.
37
+ */
38
+ readonly settings: S;
39
+ /** The host's theme now. Use `onTheme` to follow it. */
40
+ readonly theme: string;
41
+ /**
42
+ * The published design tokens, already applied to this document's
43
+ * root. Here as a reading for anything that needs a value rather
44
+ * than a CSS variable — a canvas, a chart library.
45
+ */
46
+ readonly tokens: ThemeTokens;
47
+ /** Call a backend RPC. Rejects with the host's refusal, as a sentence. */
48
+ rpc<T = unknown>(
49
+ method: string,
50
+ args?: RpcArgs,
51
+ timeoutMs?: number,
52
+ ): Promise<T>;
53
+ /** Ask the host app to navigate. It decides whether to. */
54
+ navigate(to: string): void;
55
+ /** Tell the host this surface is finished. */
56
+ close(): void;
57
+ /** Follow the host's theme. Returns an unsubscribe. */
58
+ onTheme(fn: (theme: string) => void): () => void;
59
+ /**
60
+ * Follow the launch parameters.
61
+ *
62
+ * They arrive in `hello` and can change afterwards — a link
63
+ * resolved while this frame was already mounted, or the host
64
+ * restoring a saved location. Without this the host would have to
65
+ * rebuild the frame to deliver a changed parameter, losing
66
+ * whatever state it held.
67
+ *
68
+ * Fires only on change, never for the initial value; read
69
+ * {@link params} for that.
70
+ */
71
+ onParams(fn: (params: P) => void): () => void;
72
+ /**
73
+ * Tell the host where inside this extension the user now is.
74
+ *
75
+ * Not a navigation — {@link navigate} is that. This says "still
76
+ * here, and here is now this". The host folds it into its own URL
77
+ * and replays it in the next `hello`, which is the only way an
78
+ * extension can be linked to or restored: the frame cannot write
79
+ * the address bar, and its `localStorage` dies with the ephemeral
80
+ * port it was served from.
81
+ *
82
+ * Strings only, and keep it small — it ends up in the host's URL.
83
+ * Call it when the user lands somewhere worth returning to, not on
84
+ * every keystroke.
85
+ */
86
+ setLocation(state: LocationState): void;
87
+
88
+ /**
89
+ * igni, as this extension sees it: the host object model
90
+ * (`docs/HOST_OBJECT_MODEL.md` in igni). The same model the
91
+ * extension's process reaches as `ext.host`.
92
+ *
93
+ * const busy = await bridge.host.chat.processing.get();
94
+ * await bridge.host.chat.post("Two issues in the files you changed.");
95
+ *
96
+ * A page's `host.ui` is the window it is framed in. Every object needs
97
+ * its grant in the manifest's `permissions.host`; one that is not
98
+ * granted rejects with a `HostError` whose `code` is `not_granted`.
99
+ */
100
+ readonly host: Host;
101
+
102
+ /**
103
+ * Handle a host signal: `bridge.on(bridge.host.chat.run_completed, fn)`.
104
+ *
105
+ * The first handler of a signal subscribes to it; removing the last
106
+ * one unsubscribes. A signal whose object is not granted never
107
+ * arrives; the refusal goes to `onRefused`, or to the console when
108
+ * there is none. Returns an unsubscribe.
109
+ */
110
+ on<T>(
111
+ signal: Signal<T>,
112
+ fn: (value: T) => void,
113
+ onRefused?: (error: HostError) => void,
114
+ ): () => void;
115
+
116
+ /**
117
+ * The extension's own service, reached directly, as the signed-in
118
+ * person:
119
+ *
120
+ * const res = await bridge.service.fetch("/v1/notes");
121
+ * const socket = await bridge.service.websocket("/v1/rooms/a");
122
+ *
123
+ * The host fetches a token whose audience is this extension's service
124
+ * and nothing else; it is kept and renewed before it expires. No
125
+ * `permissions.host` grant: having a service is the grant — see
126
+ * `docs/HOST_OBJECT_MODEL.md` in igni. `url` is `null` when the
127
+ * extension has none.
128
+ */
129
+ readonly service: ServiceBridge;
130
+ }
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Requests the guest sent and is waiting on, matched to their replies by
3
+ * id.
4
+ *
5
+ * Each kind of request the guest makes — an RPC call, a host-model
6
+ * request, a service token — has its own `Correlator`, so a reply of
7
+ * one kind can never settle a request of another.
8
+ */
9
+
10
+ interface Waiter {
11
+ resolve: (value: unknown) => void;
12
+ reject: (error: Error) => void;
13
+ /** `undefined` for a request with no limit (one the person answers). */
14
+ timer: ReturnType<typeof setTimeout> | undefined;
15
+ }
16
+
17
+ export class Correlator {
18
+ private readonly waiting = new Map<string, Waiter>();
19
+
20
+ /**
21
+ * `prefix` tells this correlator's ids apart from another's in a log;
22
+ * `nextNumber` numbers them. A bridge's correlators share one counter,
23
+ * so its ids run 1, h2, s3 across every kind, as they always have.
24
+ */
25
+ constructor(
26
+ private readonly prefix: string,
27
+ private readonly nextNumber: () => number,
28
+ ) {}
29
+
30
+ /**
31
+ * Send one request and wait for its reply.
32
+ *
33
+ * `timeoutMs` null waits for as long as the reply takes; otherwise the
34
+ * request is given up on with `timedOut()` and a late reply is ignored.
35
+ */
36
+ send<T>(
37
+ timeoutMs: number | null,
38
+ timedOut: () => Error,
39
+ post: (id: string) => void,
40
+ ): Promise<T> {
41
+ const id = `${this.prefix}${this.nextNumber()}`;
42
+ return new Promise<T>((resolve, reject) => {
43
+ const timer =
44
+ timeoutMs === null
45
+ ? undefined
46
+ : setTimeout(() => {
47
+ this.waiting.delete(id);
48
+ reject(timedOut());
49
+ }, timeoutMs);
50
+ this.waiting.set(id, {
51
+ resolve: resolve as (value: unknown) => void,
52
+ reject,
53
+ timer,
54
+ });
55
+ post(id);
56
+ });
57
+ }
58
+
59
+ /** The reply to `id` succeeded. */
60
+ resolve(id: string, value: unknown): void {
61
+ this.take(id)?.resolve(value);
62
+ }
63
+
64
+ /** The reply to `id` refused. */
65
+ reject(id: string, error: Error): void {
66
+ this.take(id)?.reject(error);
67
+ }
68
+
69
+ /**
70
+ * Stop waiting on `id`. An id nobody is waiting on is either a late
71
+ * reply to something that timed out, or noise; either way there is no
72
+ * one to tell.
73
+ */
74
+ private take(id: string): Waiter | undefined {
75
+ const waiter = this.waiting.get(id);
76
+ if (waiter === undefined) return undefined;
77
+ this.waiting.delete(id);
78
+ clearTimeout(waiter.timer);
79
+ return waiter;
80
+ }
81
+ }