@open-artifact/protocol 0.9.2 → 0.10.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/package.json +1 -1
- package/src/shell.d.ts +78 -2
- package/src/shell.js +17 -1
package/package.json
CHANGED
package/src/shell.d.ts
CHANGED
|
@@ -88,9 +88,31 @@ export interface ChromeFormat {
|
|
|
88
88
|
* Shell draws `saved` hides its own save badge; one whose Shell does not
|
|
89
89
|
* (an older Shell sends no `draws`) keeps drawing it.
|
|
90
90
|
*/
|
|
91
|
-
export type ChromeDraw = 'saved' | 'actions' | 'formats' | 'shareNotice';
|
|
91
|
+
export type ChromeDraw = 'saved' | 'actions' | 'formats' | 'shareNotice' | 'peers';
|
|
92
92
|
/** What the Shell draws, in the order it sends them. */
|
|
93
93
|
export declare const CHROME_DRAWS: readonly ChromeDraw[];
|
|
94
|
+
/** A {@link ChromePeer} key: the peer's id in the page's room. */
|
|
95
|
+
export declare const CHROME_PEER_KEY: RegExp;
|
|
96
|
+
/** Most peers a report lists. */
|
|
97
|
+
export declare const MAX_CHROME_PEERS = 24;
|
|
98
|
+
/**
|
|
99
|
+
* Someone else viewing the artifact, as the page knows them (another tab
|
|
100
|
+
* of the viewer's own counts too). The Shell draws them beside History and
|
|
101
|
+
* Share; where the page offers following (`following` in the report), each
|
|
102
|
+
* has Follow, or Stop while this view follows them.
|
|
103
|
+
*/
|
|
104
|
+
export interface ChromePeer {
|
|
105
|
+
/** The peer's key ({@link CHROME_PEER_KEY}), e.g. its room peer id: what `follow` names. */
|
|
106
|
+
key: string;
|
|
107
|
+
/** The name to show (at most 80 characters). */
|
|
108
|
+
name: string;
|
|
109
|
+
/** Their colour on the page (`#rrggbb`), e.g. of their selection. */
|
|
110
|
+
color?: string;
|
|
111
|
+
/** Another view (tab) of the viewer themself. */
|
|
112
|
+
self?: boolean;
|
|
113
|
+
/** They follow this view. */
|
|
114
|
+
followsYou?: boolean;
|
|
115
|
+
}
|
|
94
116
|
/**
|
|
95
117
|
* What became of an `export_format` request:
|
|
96
118
|
* `started` (the page took it), `done` (the file was saved), `busy`
|
|
@@ -100,6 +122,17 @@ export declare const CHROME_DRAWS: readonly ChromeDraw[];
|
|
|
100
122
|
*/
|
|
101
123
|
export type ChromeExportState = 'started' | 'done' | 'busy' | 'unsupported' | 'declined' | 'failed';
|
|
102
124
|
export declare const CHROME_REQUEST: RegExp;
|
|
125
|
+
/**
|
|
126
|
+
* Formats the Shell writes to the clipboard for the page. A browser that
|
|
127
|
+
* keeps the clipboard from framed pages (whatever the frame's `allow`) still
|
|
128
|
+
* lets the top window write it right after a press in the frame; the page then
|
|
129
|
+
* sends `clipboard_write` and the Shell writes in its place.
|
|
130
|
+
*/
|
|
131
|
+
export declare const CLIPBOARD_TYPES: readonly string[];
|
|
132
|
+
/** A `clipboard_write` id. */
|
|
133
|
+
export declare const CLIPBOARD_ID: RegExp;
|
|
134
|
+
/** Largest clipboard content, all formats together, the Shell writes for the page. */
|
|
135
|
+
export declare const MAX_CLIPBOARD_BYTES: number;
|
|
103
136
|
/** What the page reports to the Shell. Every part is optional. */
|
|
104
137
|
export interface ChromeReport {
|
|
105
138
|
/** Current document title in a type-server shell. */
|
|
@@ -144,6 +177,14 @@ export interface ChromeReport {
|
|
|
144
177
|
};
|
|
145
178
|
/** `false`: the page is empty, so there is nothing to export yet. */
|
|
146
179
|
hasContent?: boolean;
|
|
180
|
+
/** Who else views the artifact (at most {@link MAX_CHROME_PEERS}); absent where the page does not know. */
|
|
181
|
+
peers?: ChromePeer[];
|
|
182
|
+
/**
|
|
183
|
+
* The page offers following someone's view (the Shell sends `follow`):
|
|
184
|
+
* the key of the peer this view follows, or `null` for nobody. Absent
|
|
185
|
+
* where the page does not offer it.
|
|
186
|
+
*/
|
|
187
|
+
following?: string | null;
|
|
147
188
|
}
|
|
148
189
|
/** One export entry shown by the Shell's Export tab. */
|
|
149
190
|
export interface ChromeExportItem {
|
|
@@ -195,6 +236,14 @@ export type ChromeCommand = {
|
|
|
195
236
|
request: string;
|
|
196
237
|
format: string;
|
|
197
238
|
variant?: string;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Follows the view of the peer with this key (one the report lists), or
|
|
242
|
+
* stops following with `null`. Only sent where the report has `following`.
|
|
243
|
+
*/
|
|
244
|
+
| {
|
|
245
|
+
cmd: 'follow';
|
|
246
|
+
key: string | null;
|
|
198
247
|
};
|
|
199
248
|
/** Version of the capability broker protocol. */
|
|
200
249
|
export declare const CAP_PROTOCOL = 1;
|
|
@@ -286,10 +335,14 @@ export type CapToShell =
|
|
|
286
335
|
};
|
|
287
336
|
/** Shell → page. */
|
|
288
337
|
export type ShellToPage =
|
|
289
|
-
/**
|
|
338
|
+
/**
|
|
339
|
+
* `draws`: what this Shell draws for the page (absent from older Shells).
|
|
340
|
+
* `clipboard`: the Shell takes `clipboard_write` (absent from older Shells).
|
|
341
|
+
*/
|
|
290
342
|
{
|
|
291
343
|
openArtifact: 'chrome_hello';
|
|
292
344
|
draws?: ChromeDraw[];
|
|
345
|
+
clipboard?: boolean;
|
|
293
346
|
} | ({
|
|
294
347
|
openArtifact: 'chrome_cmd';
|
|
295
348
|
} & ChromeCommand)
|
|
@@ -297,6 +350,12 @@ export type ShellToPage =
|
|
|
297
350
|
| {
|
|
298
351
|
openArtifact: 'files_changed';
|
|
299
352
|
paths: string[];
|
|
353
|
+
}
|
|
354
|
+
/** What became of a `clipboard_write`: written, or the reason it was not. */
|
|
355
|
+
| {
|
|
356
|
+
openArtifact: 'clipboard_done';
|
|
357
|
+
id: string;
|
|
358
|
+
error?: string;
|
|
300
359
|
} | CapToPage;
|
|
301
360
|
/** Page → Shell. */
|
|
302
361
|
export type PageToShell = {
|
|
@@ -337,6 +396,23 @@ export type PageToShell = {
|
|
|
337
396
|
/** The page applied `files_changed` itself; the Shell does not reload it. */
|
|
338
397
|
| {
|
|
339
398
|
openArtifact: 'files_changed_ok';
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Write these formats ({@link CLIPBOARD_TYPES}) to the clipboard. Sent at
|
|
402
|
+
* once on the person's press, while the Shell may still write; the content
|
|
403
|
+
* follows in `clipboard_data` (an image can take a while to draw).
|
|
404
|
+
*/
|
|
405
|
+
| {
|
|
406
|
+
openArtifact: 'clipboard_write';
|
|
407
|
+
id: string;
|
|
408
|
+
types: string[];
|
|
409
|
+
}
|
|
410
|
+
/** The content of a `clipboard_write`, one Blob per format, or why there is none. */
|
|
411
|
+
| {
|
|
412
|
+
openArtifact: 'clipboard_data';
|
|
413
|
+
id: string;
|
|
414
|
+
items?: Record<string, Blob>;
|
|
415
|
+
error?: string;
|
|
340
416
|
} | CapToShell;
|
|
341
417
|
/** What the host can do for the Shell. */
|
|
342
418
|
export interface HostCaps {
|
package/src/shell.js
CHANGED
|
@@ -44,8 +44,24 @@ export const DOC_FRAGMENT = /^#[0-9a-f]{8}-[0-9a-f]{4}(?:\.[^\s#]{1,500})?$/;
|
|
|
44
44
|
/** Version of the chrome protocol. */
|
|
45
45
|
export const CHROME_PROTOCOL = 1;
|
|
46
46
|
/** What the Shell draws, in the order it sends them. */
|
|
47
|
-
export const CHROME_DRAWS = ['saved', 'actions', 'formats', 'shareNotice'];
|
|
47
|
+
export const CHROME_DRAWS = ['saved', 'actions', 'formats', 'shareNotice', 'peers'];
|
|
48
|
+
/** A {@link ChromePeer} key: the peer's id in the page's room. */
|
|
49
|
+
export const CHROME_PEER_KEY = /^[A-Za-z0-9_.:-]{1,128}$/;
|
|
50
|
+
/** Most peers a report lists. */
|
|
51
|
+
export const MAX_CHROME_PEERS = 24;
|
|
48
52
|
export const CHROME_REQUEST = /^[A-Za-z0-9_-]{16,64}$/;
|
|
53
|
+
// ---- clipboard relay: page → Shell -------------------------------------------------------------------------------
|
|
54
|
+
/**
|
|
55
|
+
* Formats the Shell writes to the clipboard for the page. A browser that
|
|
56
|
+
* keeps the clipboard from framed pages (whatever the frame's `allow`) still
|
|
57
|
+
* lets the top window write it right after a press in the frame; the page then
|
|
58
|
+
* sends `clipboard_write` and the Shell writes in its place.
|
|
59
|
+
*/
|
|
60
|
+
export const CLIPBOARD_TYPES = ['text/plain', 'text/html', 'image/png', 'image/svg+xml'];
|
|
61
|
+
/** A `clipboard_write` id. */
|
|
62
|
+
export const CLIPBOARD_ID = /^[A-Za-z0-9_-]{1,64}$/;
|
|
63
|
+
/** Largest clipboard content, all formats together, the Shell writes for the page. */
|
|
64
|
+
export const MAX_CLIPBOARD_BYTES = 64 * 1024 * 1024;
|
|
49
65
|
// ---- capability broker: page → Shell → backend ------------------------------------------------------------------
|
|
50
66
|
/** Version of the capability broker protocol. */
|
|
51
67
|
export const CAP_PROTOCOL = 1;
|