@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.
- package/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +303 -2
- package/dist/bridge.d.ts +33 -0
- package/dist/bridge.d.ts.map +1 -0
- package/dist/bridge.js +92 -0
- package/dist/bridge.js.map +1 -0
- package/dist/channel.d.ts +26 -0
- package/dist/channel.d.ts.map +1 -0
- package/dist/channel.js +36 -0
- package/dist/channel.js.map +1 -0
- package/dist/contract.d.ts +110 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +9 -0
- package/dist/contract.js.map +1 -0
- package/dist/correlator.d.ts +37 -0
- package/dist/correlator.d.ts.map +1 -0
- package/dist/correlator.js +67 -0
- package/dist/correlator.js.map +1 -0
- package/dist/guestBridge.d.ts +63 -0
- package/dist/guestBridge.d.ts.map +1 -0
- package/dist/guestBridge.js +156 -0
- package/dist/guestBridge.js.map +1 -0
- package/dist/hostModel.d.ts +155 -0
- package/dist/hostModel.d.ts.map +1 -0
- package/dist/hostModel.generated.d.ts +1870 -0
- package/dist/hostModel.generated.d.ts.map +1 -0
- package/dist/hostModel.generated.js +1241 -0
- package/dist/hostModel.generated.js.map +1 -0
- package/dist/hostModel.js +168 -0
- package/dist/hostModel.js.map +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +12 -0
- package/dist/index.js.map +1 -0
- package/dist/protocol.d.ts +338 -0
- package/dist/protocol.d.ts.map +1 -0
- package/dist/protocol.js +135 -0
- package/dist/protocol.js.map +1 -0
- package/dist/service.d.ts +143 -0
- package/dist/service.d.ts.map +1 -0
- package/dist/service.js +179 -0
- package/dist/service.js.map +1 -0
- package/dist/signals.d.ts +21 -0
- package/dist/signals.d.ts.map +1 -0
- package/dist/signals.js +52 -0
- package/dist/signals.js.map +1 -0
- package/dist/tokens.d.ts +95 -0
- package/dist/tokens.d.ts.map +1 -0
- package/dist/tokens.js +158 -0
- package/dist/tokens.js.map +1 -0
- package/dist/watchers.d.ts +12 -0
- package/dist/watchers.d.ts.map +1 -0
- package/dist/watchers.js +18 -0
- package/dist/watchers.js.map +1 -0
- package/package.json +53 -4
- package/src/bridge.ts +112 -0
- package/src/channel.ts +48 -0
- package/src/contract.ts +130 -0
- package/src/correlator.ts +81 -0
- package/src/guestBridge.ts +261 -0
- package/src/hostModel.generated.ts +2649 -0
- package/src/hostModel.ts +209 -0
- package/src/index.ts +11 -0
- package/src/protocol.ts +475 -0
- package/src/service.ts +253 -0
- package/src/signals.ts +65 -0
- package/src/tokens.ts +165 -0
- 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"}
|
package/dist/watchers.js
ADDED
|
@@ -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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|
package/src/contract.ts
ADDED
|
@@ -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
|
+
}
|