@ignite-ember/extension-bridge 0.0.0-stage → 0.2.1

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 +364 -2
  4. package/dist/bridge.d.ts +37 -0
  5. package/dist/bridge.d.ts.map +1 -0
  6. package/dist/bridge.js +96 -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 +137 -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 +75 -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 +159 -0
  25. package/dist/hostModel.d.ts.map +1 -0
  26. package/dist/hostModel.generated.d.ts +2373 -0
  27. package/dist/hostModel.generated.d.ts.map +1 -0
  28. package/dist/hostModel.generated.js +1746 -0
  29. package/dist/hostModel.generated.js.map +1 -0
  30. package/dist/hostModel.js +172 -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 +348 -0
  37. package/dist/protocol.d.ts.map +1 -0
  38. package/dist/protocol.js +145 -0
  39. package/dist/protocol.js.map +1 -0
  40. package/dist/service.d.ts +168 -0
  41. package/dist/service.d.ts.map +1 -0
  42. package/dist/service.js +196 -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 +101 -0
  49. package/dist/tokens.d.ts.map +1 -0
  50. package/dist/tokens.js +164 -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 +116 -0
  58. package/src/channel.ts +48 -0
  59. package/src/contract.ts +157 -0
  60. package/src/correlator.ts +88 -0
  61. package/src/guestBridge.ts +261 -0
  62. package/src/hostModel.generated.ts +3155 -0
  63. package/src/hostModel.ts +213 -0
  64. package/src/index.ts +11 -0
  65. package/src/protocol.ts +485 -0
  66. package/src/service.ts +278 -0
  67. package/src/signals.ts +65 -0
  68. package/src/tokens.ts +171 -0
  69. package/src/watchers.ts +18 -0
@@ -0,0 +1,101 @@
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 declare const PUBLISHED_TOKENS: {
36
+ /** Surfaces, back to front. */
37
+ readonly surface: readonly ["--bg", "--bg-inset", "--bg-surface", "--bg-raised"];
38
+ /** Text, in descending prominence. */
39
+ readonly text: readonly ["--fg", "--fg-muted", "--fg-faint"];
40
+ /** Lines between things. */
41
+ readonly line: readonly ["--border", "--border-soft"];
42
+ /** Meaning. ``*-text`` variants are the contrast-safe ones for type. */
43
+ readonly tone: readonly ["--success", "--warning", "--danger", "--danger-text", "--accent-blue", "--accent-blue-text", "--accent-green-text", "--accent-orange-text", "--accent-red-text"];
44
+ /** The product's own colour. Use sparingly; it means igni. */
45
+ readonly brand: readonly ["--igni-orange", "--igni-orange-hover", "--igni-red", "--igni-gradient"];
46
+ /** Shape. */
47
+ readonly form: readonly ["--radius-sm", "--radius", "--radius-lg", "--radius-pill", "--radius-circle", "--font-ui", "--font-mono", "--shadow-pop"];
48
+ /**
49
+ * The type scale. Nine steps, by role rather than by ratio.
50
+ *
51
+ * It replaced hardcoded sizes that included every half-step from
52
+ * 9px to 15px — 11.5px, 12px and 12.5px were one size written
53
+ * three ways. Build against the role, not the pixel.
54
+ */
55
+ readonly type: readonly ["--text-2xs", "--text-xs", "--text-sm", "--text-md", "--text-lg", "--text-xl", "--text-2xl", "--text-3xl", "--text-4xl"];
56
+ /**
57
+ * The spacing scale. Published so an extension's layout sits on the
58
+ * same rhythm as the app around it rather than next to it.
59
+ *
60
+ * These steps are the ones igni already used — they were written as
61
+ * literals in three hundred and seventy-five places, which is why
62
+ * adopting them changed nothing on screen.
63
+ */
64
+ readonly space: readonly ["--space-1", "--space-2", "--space-3", "--space-4", "--space-5", "--space-6", "--space-7", "--space-8", "--space-10", "--space-12", "--space-16"];
65
+ };
66
+ /**
67
+ * Every published token name, flat.
68
+ *
69
+ * Derived rather than listed. A second list would be a second place
70
+ * to forget — and the groups above are an object literal, where a
71
+ * repeated key silently keeps only the last one. That happened: the
72
+ * type scale was added as `text`, which was already the foreground
73
+ * colours, and `--fg` disappeared without a word.
74
+ */
75
+ export declare const TOKEN_NAMES: readonly string[];
76
+ /** Token name → current value. */
77
+ export type ThemeTokens = Record<string, string>;
78
+ /**
79
+ * Read the published tokens as they are right now.
80
+ *
81
+ * Computed values, not declared ones: a token defined in a media
82
+ * query or overridden by a `data-theme` attribute resolves here to
83
+ * what the user is actually looking at, which is the only answer
84
+ * worth sending.
85
+ *
86
+ * @param root — the element whose computed styles are read; the
87
+ * document's own root by default.
88
+ */
89
+ export declare function readThemeTokens(root?: Element): ThemeTokens;
90
+ /**
91
+ * Apply tokens inside the extension's own document.
92
+ *
93
+ * Called by the guest bridge. Separate from reading them so the two
94
+ * halves can be tested without a frame between them.
95
+ *
96
+ * @param tokens — what to apply: each published name and the value it
97
+ * takes.
98
+ * @param root — the element they are applied to.
99
+ */
100
+ export declare function applyThemeTokens(tokens: ThemeTokens, root: HTMLElement): void;
101
+ //# sourceMappingURL=tokens.d.ts.map
@@ -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;;;;;;OAMG;;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;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,GAAE,OAAkC,GACvC,WAAW,CAWb;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAM7E"}
package/dist/tokens.js ADDED
@@ -0,0 +1,164 @@
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 hardcoded sizes that included every half-step from
76
+ * 9px to 15px — 11.5px, 12px and 12.5px were one size written
77
+ * three ways. Build against the role, not the pixel.
78
+ */
79
+ type: [
80
+ "--text-2xs",
81
+ "--text-xs",
82
+ "--text-sm",
83
+ "--text-md",
84
+ "--text-lg",
85
+ "--text-xl",
86
+ "--text-2xl",
87
+ "--text-3xl",
88
+ "--text-4xl",
89
+ ],
90
+ /**
91
+ * The spacing scale. Published so an extension's layout sits on the
92
+ * same rhythm as the app around it rather than next to it.
93
+ *
94
+ * These steps are the ones igni already used — they were written as
95
+ * literals in three hundred and seventy-five places, which is why
96
+ * adopting them changed nothing on screen.
97
+ */
98
+ space: [
99
+ "--space-1",
100
+ "--space-2",
101
+ "--space-3",
102
+ "--space-4",
103
+ "--space-5",
104
+ "--space-6",
105
+ "--space-7",
106
+ "--space-8",
107
+ "--space-10",
108
+ "--space-12",
109
+ "--space-16",
110
+ ],
111
+ };
112
+ /**
113
+ * Every published token name, flat.
114
+ *
115
+ * Derived rather than listed. A second list would be a second place
116
+ * to forget — and the groups above are an object literal, where a
117
+ * repeated key silently keeps only the last one. That happened: the
118
+ * type scale was added as `text`, which was already the foreground
119
+ * colours, and `--fg` disappeared without a word.
120
+ */
121
+ export const TOKEN_NAMES = Object.values(PUBLISHED_TOKENS).flat();
122
+ /**
123
+ * Read the published tokens as they are right now.
124
+ *
125
+ * Computed values, not declared ones: a token defined in a media
126
+ * query or overridden by a `data-theme` attribute resolves here to
127
+ * what the user is actually looking at, which is the only answer
128
+ * worth sending.
129
+ *
130
+ * @param root — the element whose computed styles are read; the
131
+ * document's own root by default.
132
+ */
133
+ export function readThemeTokens(root = document.documentElement) {
134
+ const computed = getComputedStyle(root);
135
+ const out = {};
136
+ for (const name of TOKEN_NAMES) {
137
+ const value = computed.getPropertyValue(name).trim();
138
+ // A token the host has not defined is omitted rather than sent
139
+ // empty: the guest's stylesheet carries a fallback for each, and
140
+ // an empty string would override it with nothing.
141
+ if (value)
142
+ out[name] = value;
143
+ }
144
+ return out;
145
+ }
146
+ /**
147
+ * Apply tokens inside the extension's own document.
148
+ *
149
+ * Called by the guest bridge. Separate from reading them so the two
150
+ * halves can be tested without a frame between them.
151
+ *
152
+ * @param tokens — what to apply: each published name and the value it
153
+ * takes.
154
+ * @param root — the element they are applied to.
155
+ */
156
+ export function applyThemeTokens(tokens, root) {
157
+ for (const [name, value] of Object.entries(tokens)) {
158
+ // Only published names, even though the host is trusted: a typo
159
+ // on our side should not silently define something in theirs.
160
+ if (TOKEN_NAMES.includes(name))
161
+ root.style.setProperty(name, value);
162
+ }
163
+ }
164
+ //# 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;;;;;;OAMG;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;;;;;;;;;;GAUG;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;;;;;;;;;GASG;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.1",
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://igni.sh/)",
14
+ "homepage": "https://igni.sh/docs/sdk/extension-bridge",
15
+ "documentation": "https://igni.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,116 @@
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
+ * @param options — how long to wait for the host's `hello` before
40
+ * giving up: `timeoutMs`, in milliseconds, and thirty seconds by
41
+ * default.
42
+ */
43
+ export function connect<
44
+ P extends LaunchParams = LaunchParams,
45
+ S extends ExtensionSettings = ExtensionSettings,
46
+ >(options: { timeoutMs?: number } = {}): Promise<Bridge<P, S>> {
47
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
48
+ const host = window.parent;
49
+ if (host === window) {
50
+ return Promise.reject(
51
+ new Error(
52
+ "igni bridge: this page is not framed by a host, so there is nothing to connect to",
53
+ ),
54
+ );
55
+ }
56
+
57
+ return new Promise<Bridge<P, S>>((resolve, reject) => {
58
+ const timer = setTimeout(() => {
59
+ window.removeEventListener("message", onHello);
60
+ reject(
61
+ new Error(`igni bridge: no hello from the host within ${timeoutMs}ms`),
62
+ );
63
+ }, timeoutMs);
64
+
65
+ function onHello(event: MessageEvent) {
66
+ if (event.source !== host) return;
67
+ if (!isHostMessage(event.data) || event.data.kind !== "hello") return;
68
+ clearTimeout(timer);
69
+ window.removeEventListener("message", onHello);
70
+ const channel = new HostChannel(host, event.data.nonce);
71
+ const bridge = new GuestBridge<P, S>(channel, event.data);
72
+ window.addEventListener("message", (message: MessageEvent) => {
73
+ if (!channel.isFrom(message) || !isHostMessage(message.data)) return;
74
+ bridge.receive(message.data);
75
+ });
76
+ resolve(expose(bridge));
77
+ }
78
+
79
+ window.addEventListener("message", onHello);
80
+ });
81
+ }
82
+
83
+ /**
84
+ * The bridge as the page holds it: a plain object whose members close
85
+ * over the one that does the work. So `const { rpc } = bridge`,
86
+ * `onClick={bridge.close}` and `{ ...bridge }` behave as they did before
87
+ * the bridge was a class, and nothing the page did not ask for — the
88
+ * nonce, the requests in flight — is one of its properties.
89
+ */
90
+ function expose<P extends LaunchParams, S extends ExtensionSettings>(
91
+ bridge: GuestBridge<P, S>,
92
+ ): Bridge<P, S> {
93
+ return {
94
+ extensionId: bridge.extensionId,
95
+ host: bridge.host,
96
+ service: bridge.service,
97
+ on: (signal, fn, onRefused) => bridge.on(signal, fn, onRefused),
98
+ get params() {
99
+ return bridge.params;
100
+ },
101
+ settings: bridge.settings,
102
+ get theme() {
103
+ return bridge.theme;
104
+ },
105
+ get tokens() {
106
+ return bridge.tokens;
107
+ },
108
+ rpc: <T>(method: string, args?: RpcArgs, timeoutMs?: number) =>
109
+ bridge.rpc<T>(method, args, timeoutMs),
110
+ navigate: (to) => bridge.navigate(to),
111
+ close: () => bridge.close(),
112
+ onTheme: (fn) => bridge.onTheme(fn),
113
+ onParams: (fn) => bridge.onParams(fn),
114
+ setLocation: (state) => bridge.setLocation(state),
115
+ };
116
+ }
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
+ }