@botiverse/porthole 0.13.0 → 0.14.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.
- package/CHANGELOG.md +770 -0
- package/dist/annotate/types.d.ts +36 -4
- package/dist/annotate/types.js +6 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +30 -6
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.js +19 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +3 -1
- package/dist/guide/limits.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +78 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +29 -0
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +71 -2
- package/dist/platform/focus-guard.js +187 -12
- package/dist/platform/types.d.ts +8 -1
- package/dist/platform/web.js +60 -4
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +4 -3
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +5 -0
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +59 -0
- package/dist/server/nested.js +96 -0
- package/dist/server/server.js +193 -23
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +4 -3
- package/dist/shell/annotate.js +179 -9
- package/dist/shell/frame.d.ts +45 -0
- package/dist/shell/frame.js +250 -0
- package/dist/shell/plan.js +2 -1
- package/dist/shell/runtime.d.ts +6 -0
- package/dist/shell/runtime.js +60 -15
- package/docs/ADOPTING.md +85 -2
- package/docs/ARCHITECTURE.md +28 -0
- package/docs/DECISIONS.md +416 -1
- package/docs/DESIGN.md +21 -4
- package/docs/THREAT_MODEL.md +102 -5
- package/package.json +6 -5
- package/src/annotate/types.ts +32 -4
- package/src/annotate/validate.ts +34 -8
- package/src/compile/policy.ts +14 -1
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +23 -0
- package/src/displays/displays.ts +3 -1
- package/src/guide/limits.ts +1 -1
- package/src/host/create-host.ts +81 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +27 -0
- package/src/index.ts +4 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +258 -15
- package/src/platform/types.ts +8 -1
- package/src/platform/web.ts +81 -9
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +4 -3
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +14 -0
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +116 -0
- package/src/server/server.ts +224 -21
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +179 -9
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +61 -15
|
@@ -62,6 +62,50 @@ export const TAKES = {
|
|
|
62
62
|
any: { most: 5, withinMs: 2_000 },
|
|
63
63
|
} as const;
|
|
64
64
|
|
|
65
|
+
/**
|
|
66
|
+
* A nested page's shell (P111) says its own activation turned on: a press or key of the person's
|
|
67
|
+
* in that page (activation goes up to ancestors, never down, so nothing on the host's page turns
|
|
68
|
+
* it on). A move of focus into the frame within this long of it, with no press or key on the
|
|
69
|
+
* host's page since, is the person's; so is a `comments.open` the page sends within it.
|
|
70
|
+
*/
|
|
71
|
+
export const SHELL_GESTURE_MS = 1_000;
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* How long a move into a nested page's frame waits for its shell's word before it is taken for
|
|
75
|
+
* the page's: the shell says what it saw at its next animation frame, after the host's page
|
|
76
|
+
* already heard the move. A shell that says nothing in time (gone, stalled) has its frame's move
|
|
77
|
+
* taken back, as any page's.
|
|
78
|
+
*/
|
|
79
|
+
export const SHELL_WAIT_MS = 500;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* A shell's word that came this long before the host's page heard the move is about that move
|
|
83
|
+
* (the shell's frame can come first); one from before then is about an earlier one.
|
|
84
|
+
*/
|
|
85
|
+
export const SHELL_EARLY_MS = 150;
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* A shell that went this long without a look, or without a word to the host (its heartbeat is every
|
|
89
|
+
* 50 ms), was stalled (P111, after its review): where the page shares the shell's thread (WebKit,
|
|
90
|
+
* Firefox), a page that holds it from its own click handler pushes the moment the shell sees its
|
|
91
|
+
* activation turn on past the person's next keys on the host's page. An activation it saw then is
|
|
92
|
+
* uncertain: it is no one's gesture until it lapses.
|
|
93
|
+
*/
|
|
94
|
+
export const SHELL_STALL_MS = 100;
|
|
95
|
+
|
|
96
|
+
/** What a nested page's shell last said (P111), on the host's clock. */
|
|
97
|
+
export interface ShellWord {
|
|
98
|
+
/** Whether its engine tells activation at all (`navigator.userActivation`). */
|
|
99
|
+
readonly supported: boolean;
|
|
100
|
+
/** When its activation last turned on; -Infinity if it hasn't, or is off. */
|
|
101
|
+
readonly activatedAt: number;
|
|
102
|
+
/** Whether it last said the page's focus is in it, and when it last said focus came in. */
|
|
103
|
+
readonly focused: boolean;
|
|
104
|
+
readonly focusedAt: number;
|
|
105
|
+
/** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
|
|
106
|
+
readonly uncertain?: boolean;
|
|
107
|
+
}
|
|
108
|
+
|
|
65
109
|
/** One move of the keyboard the guard undid. */
|
|
66
110
|
export interface FocusTake {
|
|
67
111
|
/** The person pressed a key on the host's page within the last second. */
|
|
@@ -96,6 +140,11 @@ export interface FocusMove {
|
|
|
96
140
|
readonly activation: boolean | undefined;
|
|
97
141
|
/** The host moved focus into the frame itself (`DisplayHandle.focus()`), just now. */
|
|
98
142
|
readonly hostMoved: boolean;
|
|
143
|
+
/**
|
|
144
|
+
* A nested page's frame (P111): what its shell said, and when the host's page last had a
|
|
145
|
+
* trusted press or key of its own. Absent for any other frame.
|
|
146
|
+
*/
|
|
147
|
+
readonly shell?: { readonly word: ShellWord; readonly hostInputAt: number };
|
|
99
148
|
}
|
|
100
149
|
|
|
101
150
|
/**
|
|
@@ -122,6 +171,14 @@ export function personMoved(move: FocusMove): boolean {
|
|
|
122
171
|
if (move.lastKey !== null && move.lastKey.key === "Tab" && move.now - move.lastKey.at <= TAB_MS) {
|
|
123
172
|
return true;
|
|
124
173
|
}
|
|
174
|
+
// A nested page (P111): its shell's activation turned on within the last second, and the host's
|
|
175
|
+
// page had no press or key of its own since (the person went back to it); or, where the engine
|
|
176
|
+
// tells it, a press on the frame. Nothing else: no pointer over it, no host-wide activation.
|
|
177
|
+
if (move.shell !== undefined && move.shell.word.supported) {
|
|
178
|
+
return (
|
|
179
|
+
(move.seen && move.pressed) || shellGesture(move.shell.word, move.shell.hostInputAt, move.now)
|
|
180
|
+
);
|
|
181
|
+
}
|
|
125
182
|
if (
|
|
126
183
|
move.seen ? move.pressed : move.over && move.overSince > Math.max(move.typedAt, move.focusedAt)
|
|
127
184
|
) {
|
|
@@ -133,6 +190,19 @@ export function personMoved(move: FocusMove): boolean {
|
|
|
133
190
|
);
|
|
134
191
|
}
|
|
135
192
|
|
|
193
|
+
/**
|
|
194
|
+
* Whether a nested page's shell saw the person's gesture just now (P111): its activation turned on
|
|
195
|
+
* within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
|
|
196
|
+
*/
|
|
197
|
+
export function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean {
|
|
198
|
+
return (
|
|
199
|
+
word.supported &&
|
|
200
|
+
now - word.activatedAt <= SHELL_GESTURE_MS &&
|
|
201
|
+
now >= word.activatedAt &&
|
|
202
|
+
hostInputAt < word.activatedAt
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
|
|
136
206
|
/** Keys that type nothing on their own: they don't count as typing (a gesture still). */
|
|
137
207
|
const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "Fn"]);
|
|
138
208
|
|
|
@@ -169,8 +239,30 @@ function deepActive(document: Document): Element | null {
|
|
|
169
239
|
|
|
170
240
|
/** One page's guard, shared by every display's frame on it. */
|
|
171
241
|
export interface FocusGuard {
|
|
172
|
-
/**
|
|
173
|
-
|
|
242
|
+
/**
|
|
243
|
+
* Guards `frame`: `taken` hears each move into it that was undone. `nested`: it holds a nested
|
|
244
|
+
* page's shell (P111), whose word (`shell`) decides the moves into it.
|
|
245
|
+
*/
|
|
246
|
+
add(
|
|
247
|
+
frame: HTMLIFrameElement,
|
|
248
|
+
taken: (take: FocusTake) => void,
|
|
249
|
+
options?: { readonly nested?: boolean },
|
|
250
|
+
): () => void;
|
|
251
|
+
/** What a nested page's shell said (P111): its activation, its focus. */
|
|
252
|
+
shell(
|
|
253
|
+
frame: HTMLIFrameElement,
|
|
254
|
+
said: {
|
|
255
|
+
readonly supported: boolean;
|
|
256
|
+
readonly ago: number | null;
|
|
257
|
+
readonly focused: boolean;
|
|
258
|
+
/** How long the shell went without a look before this one (its own clock). */
|
|
259
|
+
readonly gap: number;
|
|
260
|
+
},
|
|
261
|
+
): void;
|
|
262
|
+
/** A nested page's shell's heartbeat (P111): it is looking. */
|
|
263
|
+
beat(frame: HTMLIFrameElement): void;
|
|
264
|
+
/** Whether a nested page's shell saw the person's gesture just now (`shellGesture`). */
|
|
265
|
+
gesture(frame: HTMLIFrameElement): boolean;
|
|
174
266
|
/** The host moves focus into `frame` itself. */
|
|
175
267
|
focus(frame: HTMLIFrameElement): void;
|
|
176
268
|
/**
|
|
@@ -185,6 +277,10 @@ export interface FocusGuard {
|
|
|
185
277
|
interface Guarded {
|
|
186
278
|
readonly taken: Set<(take: FocusTake) => void>;
|
|
187
279
|
overSince: number;
|
|
280
|
+
/** A nested page's shell's word (P111); null for any other frame. */
|
|
281
|
+
word: ShellWord | null;
|
|
282
|
+
/** When the host last heard the shell (a report or a heartbeat). */
|
|
283
|
+
heardAt: number;
|
|
188
284
|
}
|
|
189
285
|
|
|
190
286
|
const guards = new WeakMap<Window, FocusGuard>();
|
|
@@ -204,6 +300,20 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
204
300
|
let typedAt = -Infinity;
|
|
205
301
|
let gestureAt = -Infinity;
|
|
206
302
|
let pressAt = -Infinity;
|
|
303
|
+
/** The host's page's last trusted press or key (P111: a nested page's gesture must be later). */
|
|
304
|
+
let inputAt = -Infinity;
|
|
305
|
+
/**
|
|
306
|
+
* A move into a nested page's frame waiting for its shell's word (P111): from a text field
|
|
307
|
+
* (`field`: taken back unless the shell says the person's), or from anything else (null: only
|
|
308
|
+
* whether the frame is the person's for a gesture gate).
|
|
309
|
+
*/
|
|
310
|
+
let waiting: {
|
|
311
|
+
readonly field: HTMLElement | null;
|
|
312
|
+
readonly frame: HTMLIFrameElement;
|
|
313
|
+
readonly guarded: Guarded;
|
|
314
|
+
readonly since: number;
|
|
315
|
+
readonly failed: boolean;
|
|
316
|
+
} | null = null;
|
|
207
317
|
/** When focus last went into a guarded frame, and whether the person moved it there. */
|
|
208
318
|
let enteredAt = -Infinity;
|
|
209
319
|
let earned = false;
|
|
@@ -238,13 +348,17 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
238
348
|
}
|
|
239
349
|
};
|
|
240
350
|
|
|
241
|
-
/**
|
|
351
|
+
/**
|
|
352
|
+
* What the person's move would need, read now: see `personMoved`. Into a nested page's frame
|
|
353
|
+
* whose shell hasn't spoken of this move yet, `wait` (P111).
|
|
354
|
+
*/
|
|
242
355
|
const judge = (
|
|
243
356
|
frame: HTMLIFrameElement,
|
|
244
357
|
guarded: Guarded,
|
|
245
358
|
seen: boolean,
|
|
246
359
|
at: number,
|
|
247
|
-
): boolean => {
|
|
360
|
+
): boolean | "wait" => {
|
|
361
|
+
const word = guarded.word;
|
|
248
362
|
const moved = personMoved({
|
|
249
363
|
now: at,
|
|
250
364
|
seen,
|
|
@@ -257,11 +371,66 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
257
371
|
gestureAt,
|
|
258
372
|
activation: activation(),
|
|
259
373
|
hostMoved: hostMove !== null && hostMove.frame === frame && at - hostMove.at <= TAB_MS,
|
|
374
|
+
...(word === null ? {} : { shell: { word, hostInputAt: inputAt } }),
|
|
260
375
|
});
|
|
261
376
|
hostMove = null;
|
|
377
|
+
// The shell tells a move at its next frame, the host's page hears it first: until the shell
|
|
378
|
+
// said focus came in (around now), its activation may be on its way.
|
|
379
|
+
if (!moved && word !== null && word.supported && word.focusedAt < at - SHELL_EARLY_MS) {
|
|
380
|
+
return "wait";
|
|
381
|
+
}
|
|
262
382
|
return moved;
|
|
263
383
|
};
|
|
264
384
|
|
|
385
|
+
/** Waits for a nested page's shell's word on a move (P111): decided by `settle`. */
|
|
386
|
+
const wait = (
|
|
387
|
+
field: HTMLElement | null,
|
|
388
|
+
frame: HTMLIFrameElement,
|
|
389
|
+
guarded: Guarded,
|
|
390
|
+
at: number,
|
|
391
|
+
failed: boolean,
|
|
392
|
+
) => {
|
|
393
|
+
waiting = { field, frame, guarded, since: at, failed };
|
|
394
|
+
known = frame;
|
|
395
|
+
enteredAt = at;
|
|
396
|
+
earned = false;
|
|
397
|
+
schedule();
|
|
398
|
+
};
|
|
399
|
+
|
|
400
|
+
/**
|
|
401
|
+
* A waiting move, once its shell spoke or the wait is over: the person's (the frame keeps
|
|
402
|
+
* focus), or the page's (from a text field, taken back). A move elsewhere since ends it.
|
|
403
|
+
*/
|
|
404
|
+
const settle = (at: number) => {
|
|
405
|
+
const held = waiting;
|
|
406
|
+
if (held === null) {
|
|
407
|
+
return;
|
|
408
|
+
}
|
|
409
|
+
const { field, frame, guarded } = held;
|
|
410
|
+
if (deepActive(document) !== frame || !frames.has(frame)) {
|
|
411
|
+
// Moved on since: from the frame, as the next look judges it.
|
|
412
|
+
waiting = null;
|
|
413
|
+
known = frame;
|
|
414
|
+
return;
|
|
415
|
+
}
|
|
416
|
+
const word = guarded.word;
|
|
417
|
+
const theirs = word !== null && shellGesture(word, inputAt, at);
|
|
418
|
+
const spoke = word !== null && word.focusedAt >= held.since - SHELL_EARLY_MS;
|
|
419
|
+
if (theirs) {
|
|
420
|
+
waiting = null;
|
|
421
|
+
known = frame;
|
|
422
|
+
earned = true;
|
|
423
|
+
return;
|
|
424
|
+
}
|
|
425
|
+
if (!spoke && at - held.since < SHELL_WAIT_MS) {
|
|
426
|
+
return;
|
|
427
|
+
}
|
|
428
|
+
waiting = null;
|
|
429
|
+
if (field !== null && field.isConnected) {
|
|
430
|
+
takeBack(field, frame, guarded, at, held.failed);
|
|
431
|
+
}
|
|
432
|
+
};
|
|
433
|
+
|
|
265
434
|
/**
|
|
266
435
|
* Focus goes back to `field` once the engine has finished the move: given back inside its blur
|
|
267
436
|
* it stays with the frame on Chromium and WebKit, and Firefox takes it back only from a frame
|
|
@@ -339,12 +508,23 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
339
508
|
contest = null;
|
|
340
509
|
return false;
|
|
341
510
|
}
|
|
342
|
-
if (active === frame
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
511
|
+
if (active === frame) {
|
|
512
|
+
const verdict = judge(frame, guarded, seen, at);
|
|
513
|
+
if (verdict === true) {
|
|
514
|
+
contest = null;
|
|
515
|
+
known = frame;
|
|
516
|
+
enteredAt = at;
|
|
517
|
+
earned = true;
|
|
518
|
+
return true;
|
|
519
|
+
}
|
|
520
|
+
if (verdict === "wait") {
|
|
521
|
+
// A nested page's frame took it again (P111): its shell decides, as it would at first.
|
|
522
|
+
if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
|
|
523
|
+
contest = null;
|
|
524
|
+
wait(field, frame, guarded, at, true);
|
|
525
|
+
}
|
|
526
|
+
return true;
|
|
527
|
+
}
|
|
348
528
|
}
|
|
349
529
|
// Taken again once it was back (within `HELD_MS`), or not back yet after `GIVE_BACK_MS`: a
|
|
350
530
|
// take-back that failed, given again and counted.
|
|
@@ -358,6 +538,10 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
358
538
|
const look = (seen: boolean) => {
|
|
359
539
|
const active = deepActive(document);
|
|
360
540
|
const at = now();
|
|
541
|
+
if (waiting !== null) {
|
|
542
|
+
settle(at);
|
|
543
|
+
return;
|
|
544
|
+
}
|
|
361
545
|
if (watch(seen, active, at)) {
|
|
362
546
|
return;
|
|
363
547
|
}
|
|
@@ -393,7 +577,13 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
393
577
|
// From a text field it is judged below; from anything else it is let be, but only the
|
|
394
578
|
// person's own move makes the frame theirs for a gesture gate (`focused`).
|
|
395
579
|
enteredAt = at;
|
|
396
|
-
|
|
580
|
+
const verdict = takesText(was) || judge(active as HTMLIFrameElement, entered, seen, at);
|
|
581
|
+
if (verdict === "wait") {
|
|
582
|
+
// A nested page's (P111): theirs once its shell says so; nothing to take back.
|
|
583
|
+
wait(null, active as HTMLIFrameElement, entered, at, false);
|
|
584
|
+
return;
|
|
585
|
+
}
|
|
586
|
+
earned = verdict;
|
|
397
587
|
}
|
|
398
588
|
// Into a text field from a display's frame (the person pressed the composer while the frame
|
|
399
589
|
// had focus): watched as a take-back is, since a page that takes focus back on its own blur
|
|
@@ -414,7 +604,12 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
414
604
|
return;
|
|
415
605
|
}
|
|
416
606
|
const frame = active as HTMLIFrameElement;
|
|
417
|
-
|
|
607
|
+
const verdict = judge(frame, guarded, seen, at);
|
|
608
|
+
if (verdict === true) {
|
|
609
|
+
return;
|
|
610
|
+
}
|
|
611
|
+
if (verdict === "wait") {
|
|
612
|
+
wait(was, frame, guarded, at, false);
|
|
418
613
|
return;
|
|
419
614
|
}
|
|
420
615
|
takeBack(was, frame, guarded, at, false);
|
|
@@ -431,7 +626,7 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
431
626
|
schedule();
|
|
432
627
|
};
|
|
433
628
|
const schedule = () => {
|
|
434
|
-
if (polling === 0 && (frames.size > 0 || contest !== null)) {
|
|
629
|
+
if (polling === 0 && (frames.size > 0 || contest !== null || waiting !== null)) {
|
|
435
630
|
polling = view.requestAnimationFrame(poll);
|
|
436
631
|
}
|
|
437
632
|
};
|
|
@@ -441,6 +636,9 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
441
636
|
};
|
|
442
637
|
const press = (event: Event) => {
|
|
443
638
|
pressAt = now();
|
|
639
|
+
if (event.isTrusted) {
|
|
640
|
+
inputAt = pressAt;
|
|
641
|
+
}
|
|
444
642
|
gestureAt = pressAt;
|
|
445
643
|
const target = event.composedPath()[0];
|
|
446
644
|
pressed =
|
|
@@ -454,6 +652,9 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
454
652
|
const at = now();
|
|
455
653
|
gestureAt = at;
|
|
456
654
|
lastKey = { key: event.key, at };
|
|
655
|
+
if (event.isTrusted) {
|
|
656
|
+
inputAt = at;
|
|
657
|
+
}
|
|
457
658
|
if (event.key !== "Tab" && !MODIFIERS.has(event.key)) {
|
|
458
659
|
typedAt = at;
|
|
459
660
|
}
|
|
@@ -502,10 +703,18 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
502
703
|
);
|
|
503
704
|
|
|
504
705
|
const guard: FocusGuard = {
|
|
505
|
-
add(frame, taken) {
|
|
706
|
+
add(frame, taken, options) {
|
|
506
707
|
let guarded = frames.get(frame);
|
|
507
708
|
if (guarded === undefined) {
|
|
508
|
-
const entry: Guarded = {
|
|
709
|
+
const entry: Guarded = {
|
|
710
|
+
taken: new Set(),
|
|
711
|
+
overSince: -Infinity,
|
|
712
|
+
heardAt: -Infinity,
|
|
713
|
+
word:
|
|
714
|
+
options?.nested === true
|
|
715
|
+
? { supported: true, activatedAt: -Infinity, focused: false, focusedAt: -Infinity }
|
|
716
|
+
: null,
|
|
717
|
+
};
|
|
509
718
|
frame.addEventListener("pointerover", () => {
|
|
510
719
|
entry.overSince = now();
|
|
511
720
|
});
|
|
@@ -522,6 +731,40 @@ export function focusGuard(view: Window): FocusGuard {
|
|
|
522
731
|
}
|
|
523
732
|
};
|
|
524
733
|
},
|
|
734
|
+
shell(frame, said) {
|
|
735
|
+
const guarded = frames.get(frame);
|
|
736
|
+
const before = guarded?.word ?? null;
|
|
737
|
+
if (guarded === undefined || before === null) {
|
|
738
|
+
return;
|
|
739
|
+
}
|
|
740
|
+
const at = now();
|
|
741
|
+
// Off to on after a stall, the shell's or the host's (no word for longer than its beat
|
|
742
|
+
// allows): uncertain, and so until it goes off (P111, after its review).
|
|
743
|
+
const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
|
|
744
|
+
const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
|
|
745
|
+
const uncertain = said.ago !== null && (before.uncertain === true || (turnedOn && stalled));
|
|
746
|
+
guarded.heardAt = at;
|
|
747
|
+
guarded.word = {
|
|
748
|
+
supported: said.supported,
|
|
749
|
+
activatedAt: said.ago === null || uncertain ? -Infinity : at - said.ago,
|
|
750
|
+
focused: said.focused,
|
|
751
|
+
focusedAt: said.focused && !before.focused ? at : before.focusedAt,
|
|
752
|
+
...(uncertain ? { uncertain: true } : {}),
|
|
753
|
+
};
|
|
754
|
+
if (waiting?.frame === frame) {
|
|
755
|
+
settle(at);
|
|
756
|
+
}
|
|
757
|
+
},
|
|
758
|
+
beat(frame) {
|
|
759
|
+
const guarded = frames.get(frame);
|
|
760
|
+
if (guarded !== undefined && guarded.word !== null) {
|
|
761
|
+
guarded.heardAt = now();
|
|
762
|
+
}
|
|
763
|
+
},
|
|
764
|
+
gesture(frame) {
|
|
765
|
+
const word = frames.get(frame)?.word ?? null;
|
|
766
|
+
return word !== null && shellGesture(word, inputAt, now());
|
|
767
|
+
},
|
|
525
768
|
focus(frame) {
|
|
526
769
|
hostMove = { frame, at: now() };
|
|
527
770
|
frame.focus();
|
package/src/platform/types.ts
CHANGED
|
@@ -24,6 +24,12 @@ export interface SurfaceSpec {
|
|
|
24
24
|
readonly fill?: boolean;
|
|
25
25
|
/** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
|
|
26
26
|
readonly initialHeightPx: number;
|
|
27
|
+
/**
|
|
28
|
+
* The frame holds a nested page's shell (P111): the host's config says so, never the frame. What
|
|
29
|
+
* the shell says of itself (`porthole/shell/state`) decides moves of focus into it and the
|
|
30
|
+
* gesture its page's calls need; nothing else in that namespace reaches the transport.
|
|
31
|
+
*/
|
|
32
|
+
readonly nested?: boolean;
|
|
27
33
|
}
|
|
28
34
|
|
|
29
35
|
/** One isolated frame. */
|
|
@@ -49,7 +55,8 @@ export interface Surface {
|
|
|
49
55
|
/**
|
|
50
56
|
* Whether the embedding page's focus is in this frame now, once the platform's focus guard
|
|
51
57
|
* judged any move into it (P109); undefined, or absent, where the platform can't tell. A gesture
|
|
52
|
-
* gate that asks for the person in the calling frame (`comments`) reads it: false refuses.
|
|
58
|
+
* gate that asks for the person in the calling frame (`comments`) reads it: false refuses. A
|
|
59
|
+
* nested page's frame (P111) is the person's too while its shell saw their gesture just now.
|
|
53
60
|
*/
|
|
54
61
|
focused?(): boolean | undefined;
|
|
55
62
|
/**
|
package/src/platform/web.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
import type { ColorScheme } from "../config/schema.ts";
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
FRAME_STATUS_METHOD,
|
|
4
|
+
SHELL_BEAT_METHOD,
|
|
5
|
+
SHELL_METHOD_PREFIX,
|
|
6
|
+
SHELL_STATE_METHOD,
|
|
7
|
+
} from "../isolation/types.ts";
|
|
3
8
|
import { postMessageTransport } from "../transport/post-message.ts";
|
|
4
|
-
import { focusGuard, type FocusTake } from "./focus-guard.ts";
|
|
9
|
+
import { focusGuard, type FocusGuard, type FocusTake } from "./focus-guard.ts";
|
|
10
|
+
import type { Transport } from "../transport/types.ts";
|
|
5
11
|
import type { PlatformHost, Surface, SurfaceSpec } from "./types.ts";
|
|
6
12
|
|
|
7
13
|
/** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
|
|
@@ -11,6 +17,63 @@ const isFrameStatus = (data: unknown): boolean =>
|
|
|
11
17
|
(data as { jsonrpc?: unknown }).jsonrpc === "2.0" &&
|
|
12
18
|
(data as { method?: unknown }).method === FRAME_STATUS_METHOD;
|
|
13
19
|
|
|
20
|
+
/** A shell's own message (P111), by its namespace. */
|
|
21
|
+
const isShellWord = (data: unknown): data is { method: string; params?: unknown } =>
|
|
22
|
+
data !== null &&
|
|
23
|
+
typeof data === "object" &&
|
|
24
|
+
typeof (data as { method?: unknown }).method === "string" &&
|
|
25
|
+
(data as { method: string }).method.startsWith(SHELL_METHOD_PREFIX);
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* A nested page's transport (P111): the shell's state, checked, to the focus guard; the rest of
|
|
29
|
+
* the shell's namespace dropped; everything else as it came.
|
|
30
|
+
*/
|
|
31
|
+
function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGuard): Transport {
|
|
32
|
+
const listeners = new Set<(message: unknown) => void>();
|
|
33
|
+
opened.listen((message) => {
|
|
34
|
+
if (!isShellWord(message)) {
|
|
35
|
+
for (const listener of listeners) {
|
|
36
|
+
listener(message);
|
|
37
|
+
}
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
const params = message.params;
|
|
41
|
+
if (params === null || typeof params !== "object") {
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
const { supported, ago, focused, gap } = params as Record<string, unknown>;
|
|
45
|
+
const span = (value: unknown) =>
|
|
46
|
+
typeof value === "number" && Number.isFinite(value) && value >= 0;
|
|
47
|
+
if (message.method === SHELL_BEAT_METHOD) {
|
|
48
|
+
if (span(gap)) {
|
|
49
|
+
guard.beat(frame);
|
|
50
|
+
}
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
if (
|
|
54
|
+
message.method !== SHELL_STATE_METHOD ||
|
|
55
|
+
typeof supported !== "boolean" ||
|
|
56
|
+
typeof focused !== "boolean" ||
|
|
57
|
+
!(ago === null || span(ago)) ||
|
|
58
|
+
!span(gap)
|
|
59
|
+
) {
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
guard.shell(frame, { supported, ago: ago as number | null, focused, gap: gap as number });
|
|
63
|
+
});
|
|
64
|
+
return {
|
|
65
|
+
send: (message) => opened.send(message),
|
|
66
|
+
listen(listener) {
|
|
67
|
+
listeners.add(listener);
|
|
68
|
+
return () => listeners.delete(listener);
|
|
69
|
+
},
|
|
70
|
+
close() {
|
|
71
|
+
listeners.clear();
|
|
72
|
+
opened.close();
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
|
|
14
77
|
/**
|
|
15
78
|
* The web platform: an `<iframe>` whose policy attributes are set before its document is given,
|
|
16
79
|
* talking over `postMessage`. Its first load is the document it was given; any later load is the
|
|
@@ -67,15 +130,20 @@ export const webPlatform: PlatformHost = {
|
|
|
67
130
|
// fields that the person didn't make is undone.
|
|
68
131
|
const guard = focusGuard(view);
|
|
69
132
|
const taken = new Set<(take: FocusTake) => void>();
|
|
70
|
-
const
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
133
|
+
const nested = spec.nested === true && spec.source.kind === "url";
|
|
134
|
+
const unguard = guard.add(
|
|
135
|
+
frame,
|
|
136
|
+
(take) => {
|
|
137
|
+
for (const listener of taken) {
|
|
138
|
+
listener(take);
|
|
139
|
+
}
|
|
140
|
+
},
|
|
141
|
+
{ nested },
|
|
142
|
+
);
|
|
75
143
|
// A served frame may pass through the host's own pages (a redirect entry's, P068): what they
|
|
76
144
|
// say of the frame's status is heard too, and nothing else from there.
|
|
77
145
|
const own = view.origin;
|
|
78
|
-
const
|
|
146
|
+
const opened = postMessageTransport(
|
|
79
147
|
() => frame.contentWindow,
|
|
80
148
|
origin,
|
|
81
149
|
view,
|
|
@@ -83,6 +151,10 @@ export const webPlatform: PlatformHost = {
|
|
|
83
151
|
? undefined
|
|
84
152
|
: { origin: own, accept: isFrameStatus },
|
|
85
153
|
);
|
|
154
|
+
// A nested page's shell (P111): its own words go to the guard, by the frame's window and the
|
|
155
|
+
// content origin (the transport's checks); the page's pass on. The shell drops any page
|
|
156
|
+
// message in its namespace, so there none is the page's.
|
|
157
|
+
const transport = nested ? shellWords(opened, frame, guard) : opened;
|
|
86
158
|
return {
|
|
87
159
|
transport,
|
|
88
160
|
element: frame,
|
|
@@ -111,7 +183,7 @@ export const webPlatform: PlatformHost = {
|
|
|
111
183
|
return activation === undefined ? undefined : activation.isActive;
|
|
112
184
|
},
|
|
113
185
|
focused() {
|
|
114
|
-
return guard.focused(frame);
|
|
186
|
+
return guard.focused(frame) || (nested && guard.gesture(frame));
|
|
115
187
|
},
|
|
116
188
|
onFocusTaken(listener) {
|
|
117
189
|
taken.add(listener);
|
package/src/presets/presets.ts
CHANGED
|
@@ -56,6 +56,8 @@ export interface PresetOptions {
|
|
|
56
56
|
* be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
|
|
57
57
|
*/
|
|
58
58
|
readonly runtime?: RuntimeVersion;
|
|
59
|
+
/** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
|
|
60
|
+
readonly nested?: true;
|
|
59
61
|
}
|
|
60
62
|
|
|
61
63
|
/** What a live widget may say about a capability (P103): anything but origins of its own. */
|
|
@@ -241,6 +243,7 @@ function build(
|
|
|
241
243
|
...(options.storage === undefined ? {} : { storage: options.storage }),
|
|
242
244
|
...(options.errors === undefined ? {} : { errors: options.errors }),
|
|
243
245
|
...(options.runtime === undefined ? {} : { runtime: options.runtime }),
|
|
246
|
+
...(options.nested === undefined ? {} : { nested: options.nested }),
|
|
244
247
|
});
|
|
245
248
|
}
|
|
246
249
|
|
package/src/react/frame.tsx
CHANGED
|
@@ -500,10 +500,11 @@ export interface PortholeFrameProps {
|
|
|
500
500
|
readonly instance?: InstanceRef;
|
|
501
501
|
/**
|
|
502
502
|
* What the page declared (P086), as the host stored it with the artifact: the capabilities it
|
|
503
|
-
* reaches through `porthole.use`, and its pinned runtime.
|
|
504
|
-
*
|
|
503
|
+
* reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
|
|
504
|
+
* the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
|
|
505
|
+
* value: a change makes the display again.
|
|
505
506
|
*/
|
|
506
|
-
readonly declaration?: PageDeclaration;
|
|
507
|
+
readonly declaration?: PageDeclaration | null;
|
|
507
508
|
/**
|
|
508
509
|
* Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
|
|
509
510
|
* makes the display again.
|
package/src/server/files.ts
CHANGED
|
@@ -11,6 +11,7 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath, type FileLookup } from "../
|
|
|
11
11
|
import { fileTypeOf } from "../files/types.ts";
|
|
12
12
|
import { isCodeAsset } from "../runtime/requests.ts";
|
|
13
13
|
import { sha256, utf8 } from "./crypto.ts";
|
|
14
|
+
import { NESTED_FILE_HEADERS } from "./nested.ts";
|
|
14
15
|
import type { FileBody, StoredAsset, StoredFiles } from "./types.ts";
|
|
15
16
|
|
|
16
17
|
/**
|
|
@@ -226,6 +227,8 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
226
227
|
return nothing(serving, 404, method);
|
|
227
228
|
}
|
|
228
229
|
const { type, role } = fileTypeOf(found.path);
|
|
230
|
+
// A nested page (P111): in its shell's child, an opaque origin.
|
|
231
|
+
const nested = serving.compiled.config.nested === true;
|
|
229
232
|
// In a frame, the version's files are at a sealed address (P083), which their own loads of the
|
|
230
233
|
// artifact's assets carry as their `Referer` (P091): to this origin only, never another.
|
|
231
234
|
const referrer =
|
|
@@ -242,12 +245,18 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
242
245
|
// A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
|
|
243
246
|
// frame's sandbox, on a tab of its own too (P099); anything else runs nothing when opened on
|
|
244
247
|
// its own.
|
|
248
|
+
// A nested page's files are on its shell's origin (P111, after the review): every one carries a
|
|
249
|
+
// sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
|
|
250
|
+
// origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
|
|
251
|
+
// a script's gets one too).
|
|
245
252
|
const csp =
|
|
246
253
|
role === "file"
|
|
247
254
|
? INERT_FILE_CSP
|
|
248
255
|
: role === "page"
|
|
249
256
|
? servedDocumentCsp(serving.compiled.config, directives)
|
|
250
|
-
:
|
|
257
|
+
: nested
|
|
258
|
+
? `${serializeCsp(directives)}; sandbox`
|
|
259
|
+
: serializeCsp(directives);
|
|
251
260
|
const headers = new Headers({
|
|
252
261
|
"content-type": type,
|
|
253
262
|
"x-content-type-options": "nosniff",
|
|
@@ -263,7 +272,8 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
263
272
|
if (role === "page") {
|
|
264
273
|
// Every page of the set in the shell (P081): its hardening, its host functions, its theme.
|
|
265
274
|
const html = serving.compiled.shellDocument({
|
|
266
|
-
|
|
275
|
+
// A nested page hears its shell, on its own origin, never the host (P111).
|
|
276
|
+
origins: nested ? [serving.origin] : serving.hostOrigins,
|
|
267
277
|
document: await textOf(body),
|
|
268
278
|
cspMeta: false,
|
|
269
279
|
...(referrer === "same-origin" ? { referrer } : {}),
|
|
@@ -303,8 +313,14 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
303
313
|
serving.pinned ? `private, max-age=${YEAR}, immutable` : "private, no-cache",
|
|
304
314
|
);
|
|
305
315
|
// Only this origin's own pages load it: no other content origin (a sibling, same-site without
|
|
306
|
-
// the public suffix list) can embed it with the viewer's cookie.
|
|
316
|
+
// the public suffix list) can embed it with the viewer's cookie. A nested page's origin is
|
|
317
|
+
// opaque, and its files carry their access in their path, never a cookie (P111).
|
|
307
318
|
headers.set("cross-origin-resource-policy", "same-origin");
|
|
319
|
+
if (nested) {
|
|
320
|
+
for (const [name, value] of Object.entries(NESTED_FILE_HEADERS)) {
|
|
321
|
+
headers.set(name, value);
|
|
322
|
+
}
|
|
323
|
+
}
|
|
308
324
|
headers.set("accept-ranges", "bytes");
|
|
309
325
|
if (role === "file" && type === "application/octet-stream") {
|
|
310
326
|
headers.set("content-disposition", "attachment");
|
package/src/server/index.ts
CHANGED
|
@@ -70,6 +70,20 @@ export {
|
|
|
70
70
|
type D1StatementLike,
|
|
71
71
|
} from "./tickets.ts";
|
|
72
72
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
73
|
+
// A nested page (P111): Porthole's shell at the framed address, the page and its files below the
|
|
74
|
+
// sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
|
|
75
|
+
// config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
|
|
76
|
+
// pages").
|
|
77
|
+
export {
|
|
78
|
+
isNestedLabel,
|
|
79
|
+
NESTED_FILE_HEADERS,
|
|
80
|
+
NESTED_FILES_PREFIX,
|
|
81
|
+
nestedAncestors,
|
|
82
|
+
nestedLabelOf,
|
|
83
|
+
nestedShellCsp,
|
|
84
|
+
nestedShellResponse,
|
|
85
|
+
PORTHOLE_LABEL_PREFIX,
|
|
86
|
+
} from "./nested.ts";
|
|
73
87
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
74
88
|
// The page an app serves in conformance test mode (P071).
|
|
75
89
|
export { conformancePage } from "../conformance/page.ts";
|
package/src/server/naming.ts
CHANGED
|
@@ -42,6 +42,10 @@ export function prefixedName(prefix: string): Naming & {
|
|
|
42
42
|
"A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
|
|
43
43
|
);
|
|
44
44
|
}
|
|
45
|
+
// Porthole's own labels (a nested page's shell's, P114) are never a scope's.
|
|
46
|
+
if (prefix === "porthole-") {
|
|
47
|
+
throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
|
|
48
|
+
}
|
|
45
49
|
const name = (scope: string): string => {
|
|
46
50
|
const label = `${prefix}${scope}`;
|
|
47
51
|
if (!ID.test(scope) || !isHostLabel(label)) {
|