@open-artifact/protocol 0.0.0-stage → 0.1.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/src/refs.d.ts ADDED
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Identifiers: artifact and type URLs, artifact ids and Session Refs.
3
+ *
4
+ * These helpers are pure (no Node or DOM APIs) so the daemon, harness
5
+ * adapters, the Shell and pages can all share them.
6
+ */
7
+ /** Protocol version spoken by daemons, adapters and type servers. */
8
+ export declare const OPEN_ARTIFACT_PROTOCOL = 1;
9
+ /** An artifact id: `art_` + base36 time + random hex. */
10
+ export declare const ARTIFACT_ID: RegExp;
11
+ /** A type id: the type folder's name. */
12
+ export declare const TYPE_ID: RegExp;
13
+ /** A harness name, as an adapter says it in `hello`. */
14
+ export declare const HARNESS_NAME: RegExp;
15
+ /** `open-artifact://artifact/<id>`: how agents and tools name an artifact. */
16
+ export type ArtifactUrl = `open-artifact://artifact/${string}`;
17
+ /** `open-artifact://type/<id>`: how agents and tools name a type. */
18
+ export type TypeUrl = `open-artifact://type/${string}`;
19
+ /** The URL of an artifact id. */
20
+ export declare function artifactUrl(id: string): ArtifactUrl;
21
+ /** The URL of a type id. */
22
+ export declare function typeUrl(id: string): TypeUrl;
23
+ /** `open-artifact://artifact/<id>` or a bare id → the id, or `null` when it is neither. */
24
+ export declare function artifactIdOf(urlOrId: unknown): string | null;
25
+ /** `open-artifact://type/<id>` or a bare id → the id, or `null` when it is neither. */
26
+ export declare function typeIdOf(url: unknown): string | null;
27
+ /**
28
+ * A Session Ref: which agent session made or owns an artifact.
29
+ *
30
+ * `session` is the harness's own session id; `workspace` is the session's
31
+ * working folder. At least one of them is set for a usable ref.
32
+ */
33
+ export interface SessionRef {
34
+ /** The harness name (`dsh`, `codex`, `mcp`…). */
35
+ harness: string;
36
+ /** The harness's session id, when known. */
37
+ session: string | null;
38
+ /** The session's working folder (absolute), when known. */
39
+ workspace: string | null;
40
+ }
41
+ /**
42
+ * The string form of a {@link SessionRef}, as inbox file names and the
43
+ * daemon's session map use it:
44
+ *
45
+ * - `<harness>:<session>` when the session id is known;
46
+ * - `<harness>:ws:<hash>` when only the workspace is known, where `hash` is
47
+ * the first 12 hex digits of the SHA-1 of the resolved workspace path.
48
+ *
49
+ * Hashing needs a platform API, so the caller passes it in.
50
+ */
51
+ export declare function sessionKey(ref: Partial<SessionRef> | null | undefined, hashWorkspace: (workspace: string) => string): string | null;
package/src/refs.js ADDED
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Identifiers: artifact and type URLs, artifact ids and Session Refs.
3
+ *
4
+ * These helpers are pure (no Node or DOM APIs) so the daemon, harness
5
+ * adapters, the Shell and pages can all share them.
6
+ */
7
+ /** Protocol version spoken by daemons, adapters and type servers. */
8
+ export const OPEN_ARTIFACT_PROTOCOL = 1;
9
+ /** An artifact id: `art_` + base36 time + random hex. */
10
+ export const ARTIFACT_ID = /^art_[0-9a-z]{10,40}$/;
11
+ /** A type id: the type folder's name. */
12
+ export const TYPE_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
13
+ /** A harness name, as an adapter says it in `hello`. */
14
+ export const HARNESS_NAME = /^[a-z0-9][a-z0-9._-]{0,40}$/i;
15
+ /** The URL of an artifact id. */
16
+ export function artifactUrl(id) {
17
+ return `open-artifact://artifact/${id}`;
18
+ }
19
+ /** The URL of a type id. */
20
+ export function typeUrl(id) {
21
+ return `open-artifact://type/${id}`;
22
+ }
23
+ /** `open-artifact://artifact/<id>` or a bare id → the id, or `null` when it is neither. */
24
+ export function artifactIdOf(urlOrId) {
25
+ if (typeof urlOrId !== 'string')
26
+ return null;
27
+ const match = /^open-artifact:\/\/artifact\/([^/?#]+)/.exec(urlOrId.trim());
28
+ const id = match ? match[1] : urlOrId.trim();
29
+ return ARTIFACT_ID.test(id) ? id : null;
30
+ }
31
+ /** `open-artifact://type/<id>` or a bare id → the id, or `null` when it is neither. */
32
+ export function typeIdOf(url) {
33
+ if (typeof url !== 'string')
34
+ return null;
35
+ const match = /^open-artifact:\/\/type\/([^/?#]+)/.exec(url.trim());
36
+ if (match)
37
+ return match[1];
38
+ return TYPE_ID.test(url.trim()) ? url.trim() : null;
39
+ }
40
+ /**
41
+ * The string form of a {@link SessionRef}, as inbox file names and the
42
+ * daemon's session map use it:
43
+ *
44
+ * - `<harness>:<session>` when the session id is known;
45
+ * - `<harness>:ws:<hash>` when only the workspace is known, where `hash` is
46
+ * the first 12 hex digits of the SHA-1 of the resolved workspace path.
47
+ *
48
+ * Hashing needs a platform API, so the caller passes it in.
49
+ */
50
+ export function sessionKey(ref, hashWorkspace) {
51
+ if (!ref)
52
+ return null;
53
+ if (ref.session)
54
+ return `${ref.harness ?? 'unknown'}:${ref.session}`;
55
+ if (ref.workspace)
56
+ return `${ref.harness ?? 'unknown'}:ws:${hashWorkspace(ref.workspace)}`;
57
+ return null;
58
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * `~/.agents/open-artifact/settings.json`: settings shared by every
3
+ * harness on this computer. Only what the person changed is saved; the
4
+ * daemon merges the file over {@link DEFAULT_SETTINGS}.
5
+ */
6
+ /** A marketplace source. */
7
+ export type MarketplaceSource = {
8
+ source: 'github';
9
+ repo: string;
10
+ ref?: string;
11
+ } | {
12
+ source: 'git';
13
+ url: string;
14
+ ref?: string;
15
+ } | {
16
+ source: 'directory';
17
+ path: string;
18
+ };
19
+ /** Settings. */
20
+ export interface OpenArtifactSettings {
21
+ /** Where types are looked for. `~` is expanded. */
22
+ typeRoots: {
23
+ user: string;
24
+ project: string;
25
+ extra: string[];
26
+ };
27
+ marketplaces: Record<string, {
28
+ source: MarketplaceSource;
29
+ autoUpdate?: boolean;
30
+ }>;
31
+ /** When set, only these marketplaces may be added. */
32
+ allowedMarketplaces: string[] | null;
33
+ /** Type ids that are installed but turned off. */
34
+ disabledTypes: string[];
35
+ /** Feature flags by name, over each type's defaults. */
36
+ flags: Record<string, boolean>;
37
+ wake: {
38
+ /** What to do with a wake for a session nobody can reach. */
39
+ fallback: 'ask' | 'inbox';
40
+ };
41
+ /** Preferred daemon port. */
42
+ serverPort: number;
43
+ /** Folder under a workspace where new artifacts go. */
44
+ artifactsDir: string;
45
+ /** Workspace of artifacts made without a session (from the home page). */
46
+ homeWorkspace: string;
47
+ /** Project folders whose `.agents/artifact-types` may run code. */
48
+ trustedProjects: string[];
49
+ /** Type ids whose `openArtifact.offer` goes into the agent prompt: the agent may offer them unasked. */
50
+ offers: string[];
51
+ }
52
+ /** Defaults. */
53
+ export declare const DEFAULT_SETTINGS: OpenArtifactSettings;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * `~/.agents/open-artifact/settings.json`: settings shared by every
3
+ * harness on this computer. Only what the person changed is saved; the
4
+ * daemon merges the file over {@link DEFAULT_SETTINGS}.
5
+ */
6
+ /** Defaults. */
7
+ export const DEFAULT_SETTINGS = {
8
+ typeRoots: { user: '~/.agents/artifact-types', project: '.agents/artifact-types', extra: [] },
9
+ marketplaces: {
10
+ 'open-artifact': { source: { source: 'github', repo: 'JimLiu/open-artifact' }, autoUpdate: true },
11
+ },
12
+ allowedMarketplaces: null,
13
+ disabledTypes: [],
14
+ flags: {},
15
+ wake: { fallback: 'ask' },
16
+ serverPort: 4800,
17
+ artifactsDir: 'artifacts',
18
+ homeWorkspace: '~/OpenArtifact',
19
+ trustedProjects: [],
20
+ offers: [],
21
+ };
package/src/shell.d.ts ADDED
@@ -0,0 +1,357 @@
1
+ /**
2
+ * The Shell: the daemon's page at `/a/<id>` that frames an artifact page
3
+ * and draws the shared top bar (title, comments, share, export, ask agent).
4
+ *
5
+ * Two `postMessage` protocols meet in it, each keyed by an `open-artifact` field:
6
+ *
7
+ * - **chrome** (Shell ⇄ artifact page, in the iframe named
8
+ * {@link SHELL_FRAME_NAME}): the page reports what it can do and answers
9
+ * commands. The page side is `connectShell()` in `@open-artifact/runtime`.
10
+ * - **capability broker** (also Shell ⇄ page): `window.openartifact`
11
+ * calls travel to the Shell, which runs them against the page's backend
12
+ * and answers. This is the design of frame runtime
13
+ * (`__frame_cap*` messages): the page asks for a capability
14
+ * (`cap_want` → `cap_grant`, with per-capability config so some methods
15
+ * need no round trip), calls it (`cap` → `cap_r`), the Shell can ask for
16
+ * more time (`cap_ack`), pushes events (`cap_ev`), and cuts calls that a
17
+ * restarted broker may never have run (`cap_rewired`, keyed by `gen`).
18
+ * A page whose Shell does not answer `cap_want` falls back to its own
19
+ * backend, so older Shells keep working.
20
+ * - **host** (Shell ⇄ the host app that embeds the Shell, e.g. a harness's
21
+ * own artifact pane): the host offers sessions and a toolbar; the Shell
22
+ * asks it to start or open sessions.
23
+ *
24
+ * Messages only go to, and are only accepted from, the origin each side
25
+ * named.
26
+ */
27
+ /** Name of the iframe the Shell puts the artifact page in. */
28
+ export declare const SHELL_FRAME_NAME = "open-artifact-shell";
29
+ /** URL parameters the Shell adds to the page URL. */
30
+ export declare const SHELL_PARAMS: {
31
+ /** The Shell's origin. */
32
+ readonly shell: "open_artifact_shell";
33
+ /** The artifact id. */
34
+ readonly id: "open_artifact_id";
35
+ /** A comment thread to open on load. */
36
+ readonly comment: "comment";
37
+ /** A panel of the Shell to open on load: `share` (the Share panel) or `export` (its Export tab). */
38
+ readonly panel: "panel";
39
+ };
40
+ /** Version of the chrome protocol. */
41
+ export declare const CHROME_PROTOCOL = 1;
42
+ /** The page's save state. */
43
+ export type ChromeSaved = 'saved' | 'saving' | 'unsaved' | 'reconnecting' | 'readonly';
44
+ /** Why a page action or export format is disabled. */
45
+ export type ChromeWhy = 'older_version' | 'agent_working' | 'draft_open' | 'comments_on' | 'needs_agent' | 'unsaved' | 'other';
46
+ /**
47
+ * A page action the Shell offers (its menu, its save indicator). Built-in
48
+ * ids the Shell names itself: `save_now`, `open_find`, `undo`, `redo`,
49
+ * `edit_page`, `use_page`, `comment_selection`, `open_page_list`,
50
+ * `hand_off_code`; `chat_toggle` is not shown (the Shell has Ask).
51
+ * Other ids show `label`.
52
+ */
53
+ export interface ChromeAction {
54
+ /** `^[a-z][a-z0-9_-]{0,31}$` */
55
+ id: string;
56
+ label?: string;
57
+ disabled?: boolean;
58
+ why?: ChromeWhy;
59
+ }
60
+ /** An export format the Shell lists in its Export tab (run with `export_format`). */
61
+ export interface ChromeFormat {
62
+ /** `^[a-z0-9]{1,8}$`, e.g. `pdf`, `pptx`, `png`. */
63
+ format: string;
64
+ label?: string;
65
+ description?: string;
66
+ disabled?: boolean;
67
+ why?: ChromeWhy;
68
+ /** Why it is disabled, in the page's own words (at most 160 characters); wins over `why`. */
69
+ disabledReason?: string;
70
+ /** The page asks the person for options before exporting. */
71
+ interactive?: boolean;
72
+ /** The row opens something first (a dialog) instead of downloading at once: a chevron for the download arrow. `interactive` shows it too. */
73
+ more?: boolean;
74
+ /** Kinds of the format (e.g. one slide or all; at most 16); each is its own entry. */
75
+ variants?: {
76
+ id: string;
77
+ label?: string;
78
+ disabled?: boolean;
79
+ disabledReason?: string;
80
+ }[];
81
+ }
82
+ /**
83
+ * What the Shell draws for the page, sent with `chrome_hello`. A page whose
84
+ * Shell draws `saved` hides its own save badge; one whose Shell does not
85
+ * (an older Shell sends no `draws`) keeps drawing it.
86
+ */
87
+ export type ChromeDraw = 'saved' | 'actions' | 'formats' | 'shareNotice';
88
+ /** What the Shell draws, in the order it sends them. */
89
+ export declare const CHROME_DRAWS: readonly ChromeDraw[];
90
+ /**
91
+ * What became of an `export_format` request:
92
+ * `started` (the page took it), `done` (the file was saved), `busy`
93
+ * (another export is running, or the last was under 250 ms ago),
94
+ * `unsupported` (the format or variant is not offered, or is disabled),
95
+ * `declined` (the page refused or the person cancelled), `failed`.
96
+ */
97
+ export type ChromeExportState = 'started' | 'done' | 'busy' | 'unsupported' | 'declined' | 'failed';
98
+ export declare const CHROME_REQUEST: RegExp;
99
+ /** What the page reports to the Shell. Every part is optional. */
100
+ export interface ChromeReport {
101
+ comments?: {
102
+ available: boolean;
103
+ on: boolean;
104
+ open: boolean;
105
+ count: number;
106
+ pageButton: boolean;
107
+ };
108
+ agent?: {
109
+ available: boolean;
110
+ listening: boolean;
111
+ busy: boolean;
112
+ };
113
+ /** The page has a version history panel. */
114
+ history?: boolean;
115
+ /** The page can be shared. */
116
+ share?: boolean;
117
+ /** The page is currently shared on the LAN. */
118
+ shareOn?: boolean;
119
+ /** The page has export items (fetched with the `exports` command). */
120
+ exports?: boolean;
121
+ /** Save state; absent while the page has none (loading, or nothing to save). */
122
+ saved?: ChromeSaved;
123
+ /** Leaving now loses work: the Shell asks before closing. */
124
+ leaveLosesWork?: boolean;
125
+ /** Page actions (at most 18). */
126
+ actions?: ChromeAction[];
127
+ /**
128
+ * Export formats (at most 8, each with at most 16 variants). A Shell that
129
+ * draws `formats` lists these and runs them with `export_format`; older
130
+ * Shells use `exports`. The Shell adds the whole folder as a zip after
131
+ * them (`artifact.archive`) on any page that is not read-only.
132
+ */
133
+ formats?: ChromeFormat[];
134
+ /** A warning shown in the Share panel (at most 2000 characters). */
135
+ shareNotice?: {
136
+ text: string;
137
+ tone: 'warning';
138
+ };
139
+ /** `false`: the page is empty, so there is nothing to export yet. */
140
+ hasContent?: boolean;
141
+ }
142
+ /** One export entry shown by the Shell's Export tab. */
143
+ export interface ChromeExportItem {
144
+ label: string;
145
+ description?: string;
146
+ disabled?: boolean;
147
+ /** Why it is disabled, in the page's words. */
148
+ disabledReason?: string;
149
+ /** Asks something first instead of downloading at once (a chevron). */
150
+ more?: boolean;
151
+ }
152
+ /** Commands the Shell sends to the page. */
153
+ export type ChromeCommand = {
154
+ cmd: 'comments_mode';
155
+ on?: boolean;
156
+ } | {
157
+ cmd: 'comments_list';
158
+ open?: boolean;
159
+ } | {
160
+ cmd: 'history';
161
+ } | {
162
+ cmd: 'exports';
163
+ id: string;
164
+ } | {
165
+ cmd: 'export';
166
+ label: string;
167
+ }
168
+ /** Runs a declared, enabled action. */
169
+ | {
170
+ cmd: 'action';
171
+ id: string;
172
+ }
173
+ /**
174
+ * Exports a declared format (and variant). `request` matches
175
+ * {@link CHROME_REQUEST}; the page answers with `chrome_export`.
176
+ */
177
+ | {
178
+ cmd: 'export_format';
179
+ request: string;
180
+ format: string;
181
+ variant?: string;
182
+ };
183
+ /** Version of the capability broker protocol. */
184
+ export declare const CAP_PROTOCOL = 1;
185
+ /** Capability names: lower-case, like `__frame_cap_want` check. */
186
+ export declare const CAP_NAME: RegExp;
187
+ /** Message of a call the Shell refuses because it was sent under an older `gen`. */
188
+ export declare const STALE_MESSAGE = "not run: the artifact was updated";
189
+ /**
190
+ * Message of a call cut by `cap_rewired`. The call may or may not have
191
+ * reached the backend, so the page must re-read before retrying a write.
192
+ */
193
+ export declare const REWIRED_MESSAGE = "may not have run: the artifact was updated before this call was answered";
194
+ /** A rejected call, as `ArtifactError` fields. */
195
+ export interface CapError {
196
+ code: string;
197
+ message: string;
198
+ /** Conflicting paths of a `conflict`. */
199
+ paths?: unknown[];
200
+ }
201
+ /** Capability messages, Shell → page. */
202
+ export type CapToPage =
203
+ /**
204
+ * The answer to `cap_want`. `ok: false`: this view may not use the
205
+ * capability (`use()` resolves to `null`). `config` carries what the page
206
+ * may know without asking again (the artifact id, the viewer).
207
+ */
208
+ {
209
+ openArtifact: 'cap_grant';
210
+ cap: string;
211
+ ok: boolean;
212
+ gen: number;
213
+ config?: Record<string, unknown>;
214
+ }
215
+ /** The answer to `cap`: a result or an error. */
216
+ | {
217
+ openArtifact: 'cap_r';
218
+ id: string;
219
+ result?: unknown;
220
+ error?: CapError;
221
+ }
222
+ /** The call is alive but slow (consent, a large upload): suspend its timeout. */
223
+ | {
224
+ openArtifact: 'cap_ack';
225
+ id: string;
226
+ }
227
+ /** An event of a granted capability (`artifact`/`files`, `agent`/`status`, `room`/`peers`). */
228
+ | {
229
+ openArtifact: 'cap_ev';
230
+ cap: string;
231
+ event: string;
232
+ data: unknown;
233
+ }
234
+ /**
235
+ * The broker was rewired (a new backend, a new page base): calls sent
236
+ * under another `gen` will not be answered and reject with
237
+ * {@link REWIRED_MESSAGE}. `caps`, when present, lists the capabilities
238
+ * the broker still serves; pending calls to any other are cut too.
239
+ */
240
+ | {
241
+ openArtifact: 'cap_rewired';
242
+ gen: number;
243
+ caps?: string[];
244
+ };
245
+ /** Capability messages, page → Shell. */
246
+ export type CapToShell =
247
+ /**
248
+ * Asks for a capability. `base` is the page's own API base (its directory
249
+ * URL); the Shell only uses it when it is on the page frame's origin.
250
+ */
251
+ {
252
+ openArtifact: 'cap_want';
253
+ cap: string;
254
+ protocol: number;
255
+ base: string;
256
+ }
257
+ /**
258
+ * A call. Sent with `includeUserActivation` where the browser supports it,
259
+ * so the Shell can tell a click from a script (agent turns need a click).
260
+ */
261
+ | {
262
+ openArtifact: 'cap';
263
+ id: string;
264
+ cap: string;
265
+ method: string;
266
+ args: unknown[];
267
+ gen: number;
268
+ };
269
+ /** Shell → page. */
270
+ export type ShellToPage =
271
+ /** `draws`: what this Shell draws for the page (absent from older Shells). */
272
+ {
273
+ openArtifact: 'chrome_hello';
274
+ draws?: ChromeDraw[];
275
+ } | ({
276
+ openArtifact: 'chrome_cmd';
277
+ } & ChromeCommand)
278
+ /** Files of the artifact changed on disk (agent writes). */
279
+ | {
280
+ openArtifact: 'files_changed';
281
+ paths: string[];
282
+ } | CapToPage;
283
+ /** Page → Shell. */
284
+ export type PageToShell = {
285
+ openArtifact: 'chrome_report';
286
+ protocol: number;
287
+ report: ChromeReport;
288
+ } | {
289
+ openArtifact: 'chrome_exports';
290
+ id: string;
291
+ items: ChromeExportItem[];
292
+ }
293
+ /** What became of an `export_format` request (`started`, then `done` or `declined`; or at once `busy`/`unsupported`). */
294
+ | {
295
+ openArtifact: 'chrome_export';
296
+ request: string;
297
+ state: ChromeExportState;
298
+ reason?: string;
299
+ }
300
+ /** The page applied `files_changed` itself; the Shell does not reload it. */
301
+ | {
302
+ openArtifact: 'files_changed_ok';
303
+ } | CapToShell;
304
+ /** What the host can do for the Shell. */
305
+ export interface HostCaps {
306
+ /** The host can start and open agent sessions. */
307
+ sessions?: boolean;
308
+ /** The host draws its own toolbar: the Shell hides its close button. */
309
+ toolbar?: boolean;
310
+ }
311
+ /** Host → Shell. */
312
+ export type HostToShell = {
313
+ openArtifact: 'host_hello';
314
+ caps: HostCaps;
315
+ agentName?: string;
316
+ };
317
+ /** Shell → host. */
318
+ export type ShellToHost =
319
+ /** Sent to `*` on load when the Shell is framed; the host answers with `host_hello`. */
320
+ {
321
+ openArtifact: 'shell_hello';
322
+ version: string;
323
+ artifact: string;
324
+ id: string;
325
+ title: string;
326
+ type: string;
327
+ }
328
+ /** The Shell took `host_hello` (sent to the host's origin). */
329
+ | {
330
+ openArtifact: 'shell_ready';
331
+ artifact: string;
332
+ }
333
+ /** Start a new agent session with this prompt about the artifact. */
334
+ | {
335
+ openArtifact: 'new_session';
336
+ prompt: string;
337
+ artifact: string;
338
+ }
339
+ /** Show the session that owns the artifact. */
340
+ | {
341
+ openArtifact: 'open_session';
342
+ session: string | null;
343
+ harness: string;
344
+ }
345
+ /** Close the Shell's pane. */
346
+ | {
347
+ openArtifact: 'close';
348
+ }
349
+ /** A comment was sent to the agent; the host may show the session. */
350
+ | {
351
+ openArtifact: 'comment_summon';
352
+ text: string;
353
+ };
354
+ /** Any message of either Shell protocol. */
355
+ export type ShellMessage = ShellToPage | PageToShell | HostToShell | ShellToHost;
356
+ /** True for an object with a string `open-artifact` field. */
357
+ export declare function isShellMessage(value: unknown): value is ShellMessage;
package/src/shell.js ADDED
@@ -0,0 +1,60 @@
1
+ /**
2
+ * The Shell: the daemon's page at `/a/<id>` that frames an artifact page
3
+ * and draws the shared top bar (title, comments, share, export, ask agent).
4
+ *
5
+ * Two `postMessage` protocols meet in it, each keyed by an `open-artifact` field:
6
+ *
7
+ * - **chrome** (Shell ⇄ artifact page, in the iframe named
8
+ * {@link SHELL_FRAME_NAME}): the page reports what it can do and answers
9
+ * commands. The page side is `connectShell()` in `@open-artifact/runtime`.
10
+ * - **capability broker** (also Shell ⇄ page): `window.openartifact`
11
+ * calls travel to the Shell, which runs them against the page's backend
12
+ * and answers. This is the design of frame runtime
13
+ * (`__frame_cap*` messages): the page asks for a capability
14
+ * (`cap_want` → `cap_grant`, with per-capability config so some methods
15
+ * need no round trip), calls it (`cap` → `cap_r`), the Shell can ask for
16
+ * more time (`cap_ack`), pushes events (`cap_ev`), and cuts calls that a
17
+ * restarted broker may never have run (`cap_rewired`, keyed by `gen`).
18
+ * A page whose Shell does not answer `cap_want` falls back to its own
19
+ * backend, so older Shells keep working.
20
+ * - **host** (Shell ⇄ the host app that embeds the Shell, e.g. a harness's
21
+ * own artifact pane): the host offers sessions and a toolbar; the Shell
22
+ * asks it to start or open sessions.
23
+ *
24
+ * Messages only go to, and are only accepted from, the origin each side
25
+ * named.
26
+ */
27
+ /** Name of the iframe the Shell puts the artifact page in. */
28
+ export const SHELL_FRAME_NAME = 'open-artifact-shell';
29
+ /** URL parameters the Shell adds to the page URL. */
30
+ export const SHELL_PARAMS = {
31
+ /** The Shell's origin. */
32
+ shell: 'open_artifact_shell',
33
+ /** The artifact id. */
34
+ id: 'open_artifact_id',
35
+ /** A comment thread to open on load. */
36
+ comment: 'comment',
37
+ /** A panel of the Shell to open on load: `share` (the Share panel) or `export` (its Export tab). */
38
+ panel: 'panel',
39
+ };
40
+ /** Version of the chrome protocol. */
41
+ export const CHROME_PROTOCOL = 1;
42
+ /** What the Shell draws, in the order it sends them. */
43
+ export const CHROME_DRAWS = ['saved', 'actions', 'formats', 'shareNotice'];
44
+ export const CHROME_REQUEST = /^[A-Za-z0-9_-]{16,64}$/;
45
+ // ---- capability broker: page → Shell → backend ------------------------------------------------------------------
46
+ /** Version of the capability broker protocol. */
47
+ export const CAP_PROTOCOL = 1;
48
+ /** Capability names: lower-case, like `__frame_cap_want` check. */
49
+ export const CAP_NAME = /^[a-z][a-z0-9]{0,23}$/;
50
+ /** Message of a call the Shell refuses because it was sent under an older `gen`. */
51
+ export const STALE_MESSAGE = 'not run: the artifact was updated';
52
+ /**
53
+ * Message of a call cut by `cap_rewired`. The call may or may not have
54
+ * reached the backend, so the page must re-read before retrying a write.
55
+ */
56
+ export const REWIRED_MESSAGE = 'may not have run: the artifact was updated before this call was answered';
57
+ /** True for an object with a string `open-artifact` field. */
58
+ export function isShellMessage(value) {
59
+ return !!value && typeof value === 'object' && typeof value.openArtifact === 'string';
60
+ }