@botiverse/porthole 0.14.3 → 0.14.4

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/docs/DECISIONS.md CHANGED
@@ -6052,7 +6052,7 @@ takes it only while it asked for it. Each item below landed on its own, with its
6052
6052
  `comments` (the host's own UI; the composer is the person's, under the host's duties), and `user`
6053
6053
  (it only reads). Tested: `test/pass-on.test.ts`, each channel alone.
6054
6054
 
6055
- ## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted
6055
+ ## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted; amended by P121
6056
6056
 
6057
6057
  **Context.** In a comment mode (Raft's web app, Kirby) the person selects words, the host's
6058
6058
  composer opens beside them, and they post a comment or add a draft. The selection stays: the
@@ -6083,7 +6083,8 @@ There is no highlight of Porthole's own to remove: a settled selection is drawn
6083
6083
 
6084
6084
  **Trust.** Host to frame only. The host takes no `clearSelection` from a frame (it is no report);
6085
6085
  the shell takes it only from its frame's parent and the host's origins, as every host message
6086
- (a page that posts it to its own window is dropped). It gives the page nothing it hasn't: a page
6086
+ (a page that posts it to its own window is dropped). It gives the page no power it hasn't (but the
6087
+ page sees the clear, and so when the person was done with its selection: P121): a page
6087
6088
  can clear or select its own text at any time, and can select the words again right after (the
6088
6089
  host hears that as a selection, while it asked for text). A report the shell posted just before
6089
6090
  the clear arrived (a selection that settled in the same moment) still reaches the host after its
@@ -6372,3 +6373,312 @@ tap); "…two markers' 44 px boxes overlap, a tap is the nearest bubble's"; "a p
6372
6373
  pinned at the frame's top… takes a mouse click and a tap where it is drawn" (at its drawn
6373
6374
  pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
6374
6375
  with no touch and on a touch screen after a finger).
6376
+
6377
+ ## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Accepted; amended by P122
6378
+
6379
+ Amends P111. **Context.** The audit of P111's guard (2026-10-28, NG-1, P0 on Firefox; porthole#56):
6380
+ a nested page that focuses its field as it loads and focuses it again whenever it loses focus read
6381
+ the person's whole comment as they typed it in the host's composer, and was never stopped. Measured
6382
+ again on aedc412 with the probes below (Firefox, the audit's page; the person clicks the composer
6383
+ and types a 42-character sentence 70 ms a key): every key to the page, one `focusTaken`, not
6384
+ stopped, focus left in the frame, 5 runs of 5. The page started while the person was already
6385
+ typing: the rest of the sentence lost in 3 of 5 runs on Firefox, 2 of 5 on the headless shell and 1
6386
+ of 5 on full Chromium, where the page's `comments.open`, called on the first key it got, reached the
6387
+ handler.
6388
+
6389
+ What ended the guard's fight each time (traces of `src/platform/focus-guard.ts`): after a take-back
6390
+ the page took focus again, the guard waited for the shell's word (P111), and the person's next key,
6391
+ typed into the page, turned the page's and so the shell's activation on. The shell said its
6392
+ activation turned on with no press or key on the host's page since, and the guard took the frame
6393
+ for the person's. On the headless shell the first move itself ended so: the shell's first word, 11
6394
+ ms after the move, said both that focus came in and that its activation was on (the key landed
6395
+ before the shell's next frame). The audit's trace, a wait that gave up when focus left the frame
6396
+ for a moment and so let the frame be, ends the same way. Measured too: the shell gets no event as
6397
+ focus comes into or leaves its child frame (Chromium, Firefox), so it can only look; the host's page
6398
+ sees the pointer over a frame on Firefox and the headless shell (`pointerover` on its element,
6399
+ `:hover`), and on full Chromium nothing past the frame's edge, and the shell sees nothing of the
6400
+ pointer over its child there either. A key and a press look the same in `userActivation`.
6401
+
6402
+ **Decision.**
6403
+ 1. **A fight is judged as 0.13 judges it.** A take-back in progress is a fight when it undoes the
6404
+ page's own move: a take-back, `focusField`, a wait from a text field that moved on, or the person
6405
+ leaving a frame that took focus itself for a text field. In a fight, a nested page's frame that
6406
+ takes focus again is the person's only by a Tab, the host's own move, or a press the engine shows
6407
+ (P109's rules); its shell isn't asked. Otherwise it is taken back at once and counted as a
6408
+ take-back that failed (three within 10 s stop the display, whether or not the host's page saw
6409
+ typing). An activation the shell says turned on during a fight against its frame is uncertain
6410
+ (P111's word for a stall's): no one's gesture until it lapses, for `comments.open` too. The person
6411
+ leaving a nested page they moved into for the host's composer is no fight: going back in within
6412
+ 300 ms waits for the shell's word, as at first.
6413
+ 2. **A wait from a text field doesn't end with the frame let be.** If focus left the frame for
6414
+ nothing or for the field, with no press on the host's page since, it is the page's move still:
6415
+ watched as a take-back is, focus on nothing given back and counted.
6416
+ 3. **The host asks the shell to look.** As the guard starts waiting on a move into a nested page's
6417
+ frame it sends the shell `porthole/shell/look` (`{ n }`); the shell looks at once and answers
6418
+ with its state naming the ask (`asked: n`). An answer that says focus is in the frame decides the
6419
+ wait: its activation if a press could have made it, else the page's move, taken back. The shell
6420
+ passes no message of the host's in its own namespace to the page.
6421
+ 4. **A key is no press where the host's page sees the pointer.** Where it shows the pointer over its
6422
+ frames (Firefox; Chromium and WebKit where the frame is in their process, learned from a
6423
+ `pointerover` on one of the page's frames; full Chromium never), the shell's activation counts as
6424
+ a press only if the pointer is over the frame and came over it since the person last typed on
6425
+ the host's page, or that typing was more than a second before (`pressPossible`). Otherwise the
6426
+ move is the page's, taken back without waiting, and `comments.open`'s gesture isn't there.
6427
+
6428
+ **Measured** (Firefox 155, Chromium 153 full and headless shell, Playwright 1.63, on a box at load
6429
+ 15 to 20; the probes below, 6 runs each): the page from its load, Firefox: at most 2 keys of the
6430
+ sentence to the page and 2 lost, three take-backs, stopped every time; Chromium and full Chromium,
6431
+ no key lost (a page can't take focus back on its own blur there). The page started while the
6432
+ person types: at most 1 key to the page on every engine, Firefox stopped every time, no
6433
+ `comments.open` reaching the handler. Under load (two cores, four workers, 5 runs each), P109's
6434
+ keyboard cases and these: 35 of 35. The ask, measured on its own: full Chromium 24 of 24 with it
6435
+ (with or without the pointer over the page before), 3 of 4 without; the headless shell 12 of 12
6436
+ where the pointer had been over the page, 7 of 12 where it never was.
6437
+
6438
+ **Threat it re-opens.** None: no gate or default loosens; the keyboard rule and `comments.open` are
6439
+ stricter.
6440
+
6441
+ **Cost.** In a fight, a person who presses back into a nested page within 300 ms of focus landing in
6442
+ the host's field has it taken back on full Chromium (elsewhere a press the engine shows counts); a
6443
+ Tab, or a press once the fight is over, gets in. Where the pointer is seen, an assistive
6444
+ technology's activation in the page within a second of typing on the host's page, with the pointer
6445
+ elsewhere, is taken back; a Tab, or one a second later, keeps it. One message each way per wait.
6446
+
6447
+ **Residual.** On full Chromium neither the host's page nor the shell sees the pointer over the
6448
+ page: a key the person types into it before the shell answers the ask (the time a message takes
6449
+ between the processes) is taken for a press, and the page keeps the keyboard and gets
6450
+ `comments.open` (0 of 24 measured). Where Chromium keeps the page's frames in the host's process
6451
+ (the headless shell; a person's Chrome without full site isolation, Chrome on Android), the page's
6452
+ input runs before the ask: there the same holds until the host's page has seen the pointer over one
6453
+ of the page's frames (5 of 12 in the probe's timing, its first key 10 ms after the page's move; the
6454
+ review of P120: a `comments.open` 990 ms after the leaked key reached the handler 2 of 2). 0.13
6455
+ took such a move back (no press shown), so there nested is weaker than 0.13's guard; it has been
6456
+ since P111, and P120 narrows it. The guard is best effort on every engine (Raft, porthole#56): a
6457
+ page gets the keys typed before focus is back.
6458
+
6459
+ **Tested.** `test/nested.test.ts`: `pressPossible` and the rule with it; the shell, run against a
6460
+ stand-in of its window, answers an ask at once naming it and passes none of the host's words in its
6461
+ namespace to the page. `leak/served/nested.spec.ts` on full Chromium, the headless shell and
6462
+ Firefox: "a page that holds the keyboard from its load and takes it back on its own blur gets none
6463
+ of what the person types in the host's composer, and is stopped (P120)" (fails on aedc412 on
6464
+ Firefox, 5 of 5). `leak/served/nested-keyboard.spec.ts`: "a page that starts taking the keyboard
6465
+ back on its own blur while the person types in the host's composer gets none of the rest, opens no
6466
+ composer, and is stopped (P120)": a race (whether a key lands before the shell looks), so it is no
6467
+ control's probe and runs in a file of its own, as P111's stall race does. The nested suites and
6468
+ P109's keyboard cases (`leak/served/runtime.spec.ts`) pass on all three. Negative control
6469
+ `nested-fight` (a nested frame that takes focus back in a fight is let be) fails that probe on
6470
+ Firefox and nothing on Chromium. `shell-host-input` alone now fails nothing where the pointer is
6471
+ seen (the pointer rule holds its probe too); with `pointer-rule` (the rule out) it fails it on
6472
+ Chromium and Firefox, as it did alone before. (After its review, the pointer rule judges the
6473
+ activation as it turns on, a real press there: `shell-host-input` alone fails its probe again, as
6474
+ in P111, and `pointer-rule` is a control of its own, below.) WebKit wasn't run (its libraries are missing on this
6475
+ box); it refuses a cross-origin frame's `focus()` without a gesture of its own (P111, measured).
6476
+
6477
+ **Rejected.** Waiting for the shell in a fight (what failed). Taking every unjudged move back at
6478
+ once and giving focus to the frame if the shell then says it was a press: the page would hear a
6479
+ blur and a focus on every real click (a menu that closes on blur closes). The shell telling a press
6480
+ from a key: it gets no event as focus comes into its child, and `userActivation` doesn't say
6481
+ (measured). The host's pointer as a cue on full Chromium: it stops at the frame's edge, so a
6482
+ real click would be taken back.
6483
+
6484
+ **After its review** (2026-10-29, OK to merge: NG-1 fixed on Firefox, the headless shell and full
6485
+ Chromium, under load too; non-nested frames as in 0.13; the controls fail as they should).
6486
+ - **P120-2 (P3).** `pressPossible` was read when a move or a `comments.open` was judged, not when
6487
+ the activation turned on: one it refused (within a second of typing, the pointer elsewhere) was a
6488
+ gesture once that second was over, while its own second still ran (about a keystroke's time;
6489
+ shown by driving the guard directly). Now judged as it turns on, from the person's typing and the
6490
+ pointer then, and carried on the shell's word (`keyed`) while it stays on. Tested:
6491
+ `leak/served/nested.spec.ts` "an activation that came as the person typed, the pointer elsewhere,
6492
+ is no gesture a second on either (P120, after its review)" (the guard driven in the browser, every
6493
+ engine; it failed before), negative control `pointer-rule` (the rule out) on Chromium and
6494
+ Firefox.
6495
+ - **P120-1 (P2, since P111).** Chromium with the page's frames in the host's process: named in the
6496
+ Residual above and in THREAT_MODEL §7, the engines and when. Not redesigned here: the host can't
6497
+ tell such frames before the pointer has been over one from out-of-process ones, which never show
6498
+ it.
6499
+ - **P120-3 (P3, observed once, not reproduced in about 45 runs).** On Firefox under load, a page
6500
+ calling `focus()` every 520 ms kept the keyboard: a word went nowhere (focus on `<body>`), then
6501
+ the page took it from there, a move from `<body>` that the guard lets be. The same path is in
6502
+ 0.13's code. Suggested, not done: judge a move from `<body>` into a frame just after a text field
6503
+ lost focus, with no press since, as a move from that field.
6504
+ - **P120-4 (P3, docs).** THREAT_MODEL §7 said a page's `comments.open` on a key it got reaches no
6505
+ handler; that holds on Firefox and full Chromium, not on Chromium with frames in process. Now
6506
+ said so.
6507
+
6508
+ **Revisit when** an engine shows the host's page or a frame's parent the pointer over an
6509
+ out-of-process frame, says what turned activation on, or tells a frame's parent as focus comes
6510
+ into it; or a host can tell a frame in its own process from one out of it before the pointer has
6511
+ been over one (then a first move into a nested page there is judged as 0.13 judged it, P120-1).
6512
+
6513
+ ## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Accepted
6514
+
6515
+ Amends P114 and P115. From the audit of aedc412 (2026-10-29; no P0 or P1): two findings on nested
6516
+ pages (M1, P2; M2, P3) and two on annotations (AN-1, P2; AN-2, P3).
6517
+
6518
+ - **M1.** P114's rule, that a nested page's shell runs on a `porthole-` label of its own where
6519
+ nothing else is served, was held by `/server` alone. A content Worker of a host's own (ADOPTING
6520
+ "Nested pages") had it as a duty, with no check behind it: `nestedShellResponse` took any origin,
6521
+ the shell ran wherever it was served, and `createHost` framed a nested page located on any
6522
+ content origin. A Worker that kept 0.14.0's layout (the shell on its scope's label) rebuilt
6523
+ porthole#56 without an error.
6524
+ - **M2.** A Worker of a host's own had to write a nested page's CSP sandbox (`sandbox
6525
+ allow-scripts`) and its scripts' (`sandbox`) by hand; `/server` built them inside its own code.
6526
+ - **AN-1.** THREAT_MODEL §7 and P115 said the clear gives the page nothing new. It gives the page no
6527
+ power, but the page sees it: the message, and a `selectionchange` to nothing with no press of its
6528
+ own (the audit's probe, Chromium and Firefox). ADOPTING cleared when "the selection was used (a
6529
+ comment posted, a draft added)", so in a comment mode where a draft is added before anything is
6530
+ posted, the clear told the page that a draft exists on its words, and when: what ADOPTING's
6531
+ `mayPassOn` rule keeps from a page that can pass it on.
6532
+ - **AN-2.** `tracked` (P112) moves a host's card at the page's will, up to 60 times a second, but
6533
+ §6's guard (no press for 500 ms after a view appears or moves) didn't name it, and ADOPTING's
6534
+ React example (P118) moved the card without arming it again.
6535
+
6536
+ **Decision.**
6537
+ 1. **The shell on its own label, held where Porthole can hold it.** `isNestedLabel` and
6538
+ `PORTHOLE_LABEL_PREFIX` move to `isolation/served.ts` (re-exported from `/server` as before),
6539
+ with `onNestedLabel(origin)`. `createHost` refuses a nested config's location whose host's first
6540
+ label isn't a shell's (`checkFrameLocation(..., nested)`): no frame is made, a host error
6541
+ (`locate`) says why, the outcome is blocked (`locate`). The shell returns at once, framing
6542
+ nothing and saying nothing, on any origin whose first label isn't one. `nestedShellResponse`
6543
+ throws for such an origin, or a page on another origin, and `frameShellScript` for a page on
6544
+ one. What else a Worker of a host's own answers on that label stays its duty (THREAT_MODEL S3):
6545
+ Porthole can't see its routes.
6546
+ 2. **`nestedFileCsp(role, directives)`** (`/server`): a page's directives and `sandbox
6547
+ allow-scripts`, a script's and `sandbox`, any other file `default-src 'none'; sandbox`; then
6548
+ `frame-ancestors` (`nestedAncestors`). `/server` uses it for every nested page and file, and
6549
+ ADOPTING's table for a Worker names it.
6550
+ 3. **`clearSelection` is said to tell the page when.** THREAT_MODEL §7 and P115 say so. ADOPTING
6551
+ clears on every close of the composer (posted, a draft added, dismissed), or as it opens, or
6552
+ leaves it to the person's next click; never only when a draft is added, above all for a page
6553
+ `mayPassOn` says to keep drafts from.
6554
+ 4. **`tracked` is guarded.** §6 names it; ADOPTING arms a card that follows a mark again each time
6555
+ it moves more than a few px (re-arming on every report would let a page that keeps its mark
6556
+ moving keep the card inert, which only costs its own comments).
6557
+
6558
+ **Threat it re-opens.** None. A Worker of a host's own that served the shell on another label
6559
+ than `nestedLabelOf`'s now fails closed (the display is blocked) where it ran before.
6560
+
6561
+ **Tested.** `test/nested.test.ts`: `frameShellScript` and `nestedShellResponse` refuse the scope's
6562
+ origin and a page on another origin; `onNestedLabel` takes `nestedLabelOf`'s form only (not a
6563
+ shorter one, not one below another label); `checkFrameLocation` refuses a nested page's location on
6564
+ the scope's label, as before for a config that doesn't nest; the shell's script, moved to the
6565
+ scope's origin and run against a stand-in of its window, frames nothing and says nothing;
6566
+ `nestedFileCsp` per role, never `allow-same-origin`. `/server`'s nested answers are unchanged
6567
+ (its tests pass as they were). `leak/served/nested-siblings.spec.ts` on full Chromium, the headless
6568
+ shell and Firefox: "[nested-label] a nested page located on its scope's label, not a shell's own, is
6569
+ refused before a frame is made (P121)". Negative controls: `nested-host-label` (the host's check
6570
+ out) fails it on Chromium and Firefox; `nested-shell-origin` (the shell's out) fails nothing alone,
6571
+ the host's check holding first; `shell-label`, which serves the shell on its scope's label, now
6572
+ runs with both (`shell-label,nested-host-label,nested-shell-origin`) and fails `[nested-siblings]`
6573
+ and `[nested-label]` as `shell-label` alone did before. WebKit wasn't run (its libraries are
6574
+ missing on this box). AN-1 and AN-2 are documents only: the audit's probe of the clear is its own.
6575
+
6576
+ **Rejected.** A conformance case in `defineHostConformance` asking a host's content domain for a
6577
+ non-nested address on a shell label (the audit's suggestion): it needs a known scope label and a
6578
+ second display kind from the app under test, and what it would hold (a Worker's own routes) is the
6579
+ host's; left for when a host with its own Worker asks for one. Hiding the clear from the page:
6580
+ the `selectionchange` gives it away whatever the message says.
6581
+
6582
+ ## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Accepted
6583
+
6584
+ Amends P120. **Context.** CI on 0.14.4 (run 40822963445, `loopback (chromium-oopif)`): P120's
6585
+ case "a page that starts taking the keyboard back on its own blur while the person types…" failed
6586
+ on full Chromium with nothing taken back: the page read the whole secret, 35 keys. P120 measured 0
6587
+ of 24 on this box. On full Chromium neither the host's page nor the shell sees the pointer over the
6588
+ page, so the first move from a text field waits for the shell's word, and the host asks the shell to
6589
+ look at once (P120); on CI's runner the person's next key reached the page, and its activation the
6590
+ shell, before the ask did, and the guard took the activation for a press. That is the race P120
6591
+ named as residual, and the probe's timing (its first key a few ms after the page's move) sits in
6592
+ it. P120's bar was a frame in 0.13, which took such a move back.
6593
+
6594
+ CI on P120's pull request (run 40820197982) also showed the control `shell-host-input` blind on
6595
+ the headless shell and WebKit. P120 (after its review) judged whether the shell's activation could
6596
+ be a press as it turned on, from the person's typing then, but read that typing when the shell's
6597
+ report arrived: on a fast runner the person's first key in the composer, after their real press in
6598
+ the page, came before the report, and the press was taken for a key. And `navigate-guard` failed
6599
+ there because one of its probes errored ("Frame was detached") where the display it stood on
6600
+ restarted under the control, instead of failing by its verdict.
6601
+
6602
+ **Decision.**
6603
+ 1. **No press within `KEY_PRESS_MS` (250 ms) of the person's key** on the host's page: a move into
6604
+ a nested page's frame that soon after the person's last key is the page's (taken back at once,
6605
+ no wait for the shell), and a shell's activation that turned on that soon after a key typed
6606
+ before it is uncertain (no one's gesture until it lapses, `comments.open` included), on every
6607
+ engine. A hand on the keys doesn't reach the pointer and press that fast: the Keystroke-Level
6608
+ Model gives 400 ms to the hand's move from the keys to the mouse alone (Card, Moran and Newell,
6609
+ 1980). A page that takes the keyboard while the person types does it within one of their keys,
6610
+ so the race with the shell's answer no longer decides it.
6611
+ 2. **The pointer rule reads the typing before the activation.** The guard keeps the last two
6612
+ seconds of the person's typing; whether an activation could be a press (P120's `keyed`), and
6613
+ whether it came within 250 ms of a key, are judged from the last key before it, never one
6614
+ typed after. The shell sees its activation at a look, up to a look's gap (`gap`, at most
6615
+ `SHELL_STALL_MS`) after it turned on: only a key before the look before counts (CI's runner
6616
+ typed in the host's composer within that gap after its press in the page).
6617
+ *What this loosens* (added after the maintainer's review, porthole#81): P120's follow-up judged
6618
+ an activation by the latest key the host's page had seen; this judges it by the last key before
6619
+ it. A key the host's page sees after an activation turned on no longer counts toward calling
6620
+ that activation a keystroke, so fewer activations are marked as one. It has no control of its
6621
+ own; P123 accepts the keyboard as a risk instead of bounding it further.
6622
+ 3. **In-set link probes fail by their verdict**: their clicks in the frame are part of the verdict
6623
+ (`clickIn`), so a display that restarts under `navigate-guard` fails them as the wall seen to
6624
+ fail, not as an error.
6625
+
6626
+ **Cost.** A real press into a nested page within 250 ms of typing on the host's page is taken back
6627
+ (the person's next press gets in). The honest cases that type in the host's composer and then press
6628
+ the page now pause 400 ms between, as a hand does: Playwright pressed 45 ms after the last key.
6629
+
6630
+ **Residual.** On full Chromium, a person typing slower than one key in 250 ms: a key that lands
6631
+ in the page within the time a message takes between the processes after the page's move still
6632
+ passes for a press; on Chromium with frames in the host's process, until the pointer has been over
6633
+ one of the page's frames, within the time the page's input runs before the ask.
6634
+
6635
+ **Tested.** `test/nested.test.ts`: a move within `KEY_PRESS_MS` of the last key is the page's, a
6636
+ press the engine shows still counts. `leak/served/nested-key.spec.ts` (the guard driven directly,
6637
+ on a page that never saw the pointer, every engine): an activation 30 ms after the person's key is
6638
+ no gesture; a key typed after the press, before the shell's look saw it, changes nothing (that
6639
+ part failed on the first cut of this decision, as CI's `shell-host-input` showed). Negative control
6640
+ `key-press` (the window out) fails it on Chromium and Firefox; its own file, because the cases that
6641
+ race the shell's answer stand on the rule by chance and are no control's probes. P120's guard test
6642
+ puts its activation 300 ms after the key, so it stays `pointer-rule`'s alone. `shell-host-input`
6643
+ fails its probe again with the typing before the activation read (locally on Chromium and Firefox;
6644
+ CI's runners are the measure). The nested suites, P109's keyboard cases and the in-set link cases
6645
+ pass on full Chromium, the headless shell and Firefox; `navigate-guard`, `pointer-rule`,
6646
+ `nested-fight` fail exactly their probes on Chromium and Firefox. WebKit only in CI.
6647
+
6648
+ **Revisit when** an engine tells a frame's parent what turned activation on, or as focus comes into
6649
+ it (then the press itself can be told from a key, and the window can go).
6650
+
6651
+
6652
+ ## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Accepted
6653
+
6654
+ **Context.** P109, P120 and P122 built a guard that gives the keyboard back when a display moves
6655
+ focus into its frame while the person types in the host's page. P122's review (porthole#81) showed
6656
+ what it can't do on a nested page: a person typing slower than one key per 250 ms (most people,
6657
+ phones included) isn't covered, and the page chooses when to take focus, so it can wait out any
6658
+ window. The owner (xxchan) and the maintainer agreed on 2026-10-29 that this class isn't worth more
6659
+ work.
6660
+
6661
+ **Decision.** A display taking the keyboard (`focus()` and the like) is an accepted risk, listed in
6662
+ THREAT_MODEL §5 "Out of scope". The existing guard stays, as best effort: it takes the keyboard back
6663
+ and stops a display that keeps taking it, where it can tell. No new rule is added to cover more
6664
+ typists or timings.
6665
+
6666
+ **Why.**
6667
+ - **Browsers don't let a host prevent it.** Any frame the person can type into can take focus. Other
6668
+ hosts of untrusted pages live with the same property; on Chrome, a claude.ai Artifact that calls
6669
+ `focus()` in a loop takes the keyboard from the message box (Raft's test, porthole#56).
6670
+ - **The person sees it.** Their text stops appearing where they type.
6671
+ - **The walls that matter hold without it.** A page can't reach the host's origin, its storage or
6672
+ another display, and a nested page's sealed address stays in a shell no content shares (P114,
6673
+ P121). Those stay airtight requirements.
6674
+ - **More rules cost real use.** A wider window takes back real clicks: P122's 250 ms rule already
6675
+ takes back a press within 250 ms of a key and leaves `comments.open` refused until the person
6676
+ pauses. Enter and Escape count as keys there too.
6677
+
6678
+ **Known and not fixed** (porthole#81): typists slower than 250 ms per key on a nested page; the
6679
+ probe types at 70 ms per key, so CI doesn't measure them; the usability costs above; P122's
6680
+ looser reading of the typing before an activation.
6681
+
6682
+ **Revisit when** a browser gives a frame's parent a way to keep focus or to know what turned
6683
+ activation on, or a host reports a real loss the person didn't notice.
6684
+
package/docs/DESIGN.md CHANGED
@@ -998,8 +998,8 @@ for that to lapse and click with raw input.
998
998
  | The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
999
999
  | The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
1000
1000
  | The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
1001
- | A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three) |
1002
- | A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label` (the shell on the scope's label) → `[nested-siblings]` (all three) |
1001
+ | A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows), asking the shell to look as it hears the move; where the host's page sees the pointer over its frames, not with the pointer elsewhere within a second of typing; in a fight over a text field, a frame that takes focus again is judged without the shell and taken back at once, counted (P120); no press within 250 ms of the person's key on the host's page (P122) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three); `pointer-rule` (P120's pointer rule out) → "an activation that came as the person typed…" (all three); `key-press` (P122's 250 ms out) → "an activation that turned on within 250 ms of the person's key…" (all three); `nested-fight` (a frame that takes focus back in a fight let be) → "a page that holds the keyboard from its load…" (Firefox); `leak/served/nested-keyboard.spec.ts` (a page that takes the keyboard as the person types: a race, no control's probe) |
1002
+ | A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
1003
1003
  | The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
1004
1004
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
1005
1005
 
@@ -1489,10 +1489,15 @@ control the tables above name to the registry):
1489
1489
  | `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
1490
1490
  | `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
1491
1491
  | `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
1492
- | `shell-label` | `served/nested-siblings.spec.ts` | `[nested-siblings]` | — | — |
1492
+ | `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
1493
+ | `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
1494
+ | `nested-shell-origin` | `served/nested-siblings.spec.ts` | nothing | — | the host's mount refuses a shell located on any other label first, and /server serves none there (`shell-label,nested-host-label,nested-shell-origin`) |
1493
1495
  | `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
1496
+ | `nested-fight` | `served/nested.spec.ts` | nothing | Firefox: `a page that holds the keyboard from its load and takes it back on its own blur gets none of what the person types in the host's composer, and is stopped (P120)` | no probe can see it on Chromium and WebKit: a page can't take focus back from its own blur there, so no fight has a frame take focus again (measured) |
1494
1497
  | `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
1495
1498
  | `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
1499
+ | `key-press` | `served/nested-key.spec.ts` | `an activation that turned on within 250 ms of the person's key on the host's page is no gesture, where the pointer is never seen too (P122)` | — | — |
1500
+ | `pointer-rule` | `served/nested.spec.ts` | `an activation that came as the person typed, the pointer elsewhere, is no gesture a second on either (P120, after its review)` | — | — |
1496
1501
  | `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
1497
1502
  | `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
1498
1503
  | `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.14.3 (2026-10-29). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.4 (2026-10-29). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -121,6 +121,14 @@ Porthole does not protect against these.
121
121
  - **Deceptive content.** Content may draw anything in its frame, a fake sign-in form included.
122
122
  Porthole limits where what is typed into it can go and keeps the host's approvals outside the
123
123
  frame; it doesn't judge what content shows.
124
+ - **A display taking the keyboard** (accepted risk, P123). Content can move focus into its frame
125
+ (`focus()` and the like) while the person types in the host's page, and receive the keys typed
126
+ after it. Porthole's guard takes the keyboard back and stops a display that keeps taking it, but
127
+ only as best effort (§7 "The keyboard"): on a nested page it doesn't cover typing slower than one
128
+ key per 250 ms, which is most people, phones included. Browsers give a host no way to prevent it,
129
+ and the person sees their text stop appearing. The walls that hold regardless: content can't read
130
+ the host's page, its storage or another display, and a nested page's sealed address stays in a
131
+ shell no content shares.
124
132
  - **Wrong results.** A chart can plot the wrong numbers, and a report can say false things.
125
133
  - **Malicious prompts.** A gated `sendPrompt` hands the host's confirm function the whole text (the
126
134
  default dialog shows all of it); whether that text is hostile is not Porthole's call. Nor is text
@@ -158,8 +166,9 @@ Whatever the use:
158
166
  quoted text) only as text, never as HTML.
159
167
  - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
160
168
  as permissions, and put nothing in a mark the page may not know (§7).
161
- - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`: a
162
- comment's bubble, a composer). The content chooses when it appears and where, so it can bring it
169
+ - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
170
+ `tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
171
+ at will, up to 60 times a second). The content chooses when it appears and where, so it can bring it
163
172
  under a press the person meant for the content (a double click on the content's own button whose
164
173
  second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
165
174
  appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
@@ -349,6 +358,11 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
349
358
  shell's label with a one-time ticket); no host's naming makes a `porthole-` label. So no
350
359
  content, of any scope, can read the shell's realm (its word to the host, the page's sealed
351
360
  address) or drive it (`leak/served/nested-siblings.spec.ts`, negative control `shell-label`).
361
+ Porthole holds the shell to that label outside `/server` too (P121), for a content Worker of a
362
+ host's own: the host's mount refuses a nested page located on any other label before a frame
363
+ is made (a host error, `locate`; negative control `nested-host-label`), the shell frames
364
+ nothing and says nothing on any other origin, and `nestedShellResponse` and `frameShellScript`
365
+ refuse one. What else such a Worker serves on that label is its own (below).
352
366
  The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
353
367
  static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
354
368
  opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
@@ -387,7 +401,8 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
387
401
  - With nested pages, route the shell's label (`porthole-<…>.<domain>`) to the content server as
388
402
  every content label is (a wildcard needs nothing; a pattern of the host's own, `a-*`, must add
389
403
  it). A content Worker of the host's own serves nested pages on that label alone, and nothing
390
- else there (P114).
404
+ else there (P114): Porthole refuses the shell anywhere else (P121), but can't see what else a
405
+ Worker of the host's own answers on it. Its page's and files' CSPs come from `nestedFileCsp`.
391
406
 
392
407
  **Not guaranteed**
393
408
 
@@ -699,9 +714,15 @@ own frame, below the shell, P111), so:
699
714
  `clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
700
715
  told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
701
716
  takes no such message from a frame, and the shell takes it only from its frame's parent (a page
702
- that posts it to its own window is dropped). It gives the page nothing new: a page can clear or
703
- select its own text at any time, and can select the words again right after a clear (the host
704
- hears that as any selection, while it asked for text).
717
+ that posts it to its own window is dropped). It gives the page no power it lacks: a page can
718
+ clear or select its own text at any time, and can select the words again right after a clear
719
+ (the host hears that as any selection, while it asked for text). But the page sees the clear
720
+ (the message, and a `selectionchange` with no press of its own) and so learns when the person
721
+ was done with its selection (P121, after the audit of P115). A host that clears only when a
722
+ draft is added tells the page that a draft exists on its words, and when: clear when the
723
+ composer opens, or on every close, kept or dismissed, or leave it to the person's next click,
724
+ never only on a draft, above all for a page `mayPassOn` says to keep drafts from (ADOPTING.md
725
+ § Annotations).
705
726
  - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
706
727
  layer's style, lay elements over it, or transform the page it sits in), change its words so a
707
728
  mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
@@ -766,29 +787,61 @@ unposted words beside the frame and tell the page when.
766
787
  into its field is taken back every time there (the display stopped at the third), and
767
788
  `comments.open` from a real click is refused within 5 s of any input on the host's page
768
789
  (porthole#53). Nest it.
769
- - *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
770
- frame, whose transient activation turns on only from a press or key in the page (activation goes
771
- up, never down). A move into the frame is the person's if the shell's activation turned on within
772
- the last second and the host's page had no trusted press or key since; or a Tab, the host's own
773
- move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
774
- frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
775
- frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
776
- and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
777
- keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
778
- click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
779
- they pressed it and went back to the composer is taken back; what a page says in the shell's
780
- name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
781
- `shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
782
- activation on, so a second move into it after the person went back to the host's page is taken
783
- back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
784
- typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
790
+ - *A nested page* (P111, P120, P122): the guard asks the page's shell, a realm the page can't
791
+ reach above its frame, whose transient activation turns on only from a press or key in the page
792
+ (activation goes up, never down). A move into the frame is the person's if the shell's
793
+ activation turned on within the last second and the host's page had no trusted press or key
794
+ since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
795
+ else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
796
+ hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
797
+ `porthole/shell/look`), then is taken back. A key the person types into the page turns its
798
+ activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
799
+ host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
800
+ their process, once the pointer has been over one), an activation while the pointer isn't over
801
+ the frame, within a second of the person typing on the host's page, is no press; and in a fight
802
+ over a text field (a take-back, or the person leaving a frame that took focus itself), a frame
803
+ that takes focus again is judged as any frame is, its shell not asked: taken back at once and
804
+ counted, and an activation it reports then is no one's gesture until it lapses, for
805
+ `comments.open` too. Measured on full Chromium, the headless shell, WebKit and Firefox
806
+ (`leak/served/nested.spec.ts`): a real click into the page's field keeps the keyboard; the
807
+ page's `focus()` as it loads, on a timer while the person types, right after a click on the
808
+ host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after they pressed it
809
+ and went back to the composer is taken back; a page that holds the keyboard from its load, or
810
+ takes it while the person types, and takes it back on its own blur gets at most two keys of a
811
+ sentence on Firefox and is stopped (none on Chromium, where a page can't take focus back on its
812
+ blur), and its `comments.open` on a key it got reaches no handler on Firefox and full Chromium
813
+ (on Chromium with frames in process it can: below); what a page says in the shell's name, to its
814
+ parent or to the host's window, moves nothing (negative controls `shell-namespace`,
815
+ `shell-host-input`, `pointer-rule`, `nested-fight`). *What doesn't*: a press in the page within
816
+ 5 s of the last one turns no activation on, so a second move into it after the person went back
817
+ to the host's page is taken back until 5 s after their last press or key in the page, or they
818
+ Tab in; the page gets the keys typed while a move waits for the shell's word, or before focus is
819
+ back. No press of the person's comes within 250 ms of a key they typed on the host's page (a
820
+ hand goes from the keys to the pointer first): a move into the frame, or the shell's activation
821
+ turning on, that soon is their next key landing in the page, and is taken back, on every engine
822
+ (P122, after CI saw full Chromium let such a page keep the keyboard: its key outran the shell's
823
+ answer; negative control `key-press`). So a page that takes the keyboard while the person types
824
+ is taken back whatever the timing. *Still*: on full Chromium, where neither the host's page nor
825
+ the shell sees the pointer over the page, a key typed more than 250 ms after the person's last
826
+ one that reaches the page before the shell answers the host's ask (the time a message takes
827
+ between processes) is taken for a press, and the page keeps the keyboard and its `comments.open`
828
+ opens; and so, more often, where Chromium keeps the page's frames in the host's process (the
829
+ headless shell; a person's Chrome without full site isolation, Chrome on Android) until the
830
+ host's page has seen the pointer over one of the page's frames, since the page's input runs
831
+ before the ask there (measured in P122's review on the headless shell: a person typing one key
832
+ every 450 ms lost 34 of 36 keys to the page in 1 run of 8, and the page was not stopped). 0.13 took such a move back; a person typing slower than one key in 250 ms
833
+ is the case left, and only a key that lands within that message's time of the page's move
834
+ (P122); a press back into the page within 300 ms of a fight putting focus in the host's field is
835
+ taken back on full Chromium; where the pointer is seen, an assistive technology's activation in
836
+ the page within a second of typing on the host's page with the pointer elsewhere is taken back
837
+ (a Tab, or one a second later, keeps it); a shell without `navigator.userActivation` leaves
785
838
  0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
786
- where the frames share a process) from its own click handler would push the moment the shell sees
787
- its activation past the person's next keys on the host's page: so the shell looks and beats every
788
- 50 ms and says how long it went without a look, and an activation it reports after a stall of over
789
- 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
790
- negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
791
- the person's real click taken for uncertain until it is idle.
839
+ where the frames share a process) from its own click handler would push the moment the shell
840
+ sees its activation past the person's next keys on the host's page: so the shell looks and beats
841
+ every 50 ms and says how long it went without a look, and an activation it reports after a stall
842
+ of over 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its
843
+ review; negative control `shell-stall`). The cost: in those engines a page that keeps its thread
844
+ busy has the person's real click taken for uncertain until it is idle.
792
845
 
793
846
  ### The app runtime
794
847
 
@@ -828,7 +881,9 @@ section.
828
881
  person's gesture within the last second, with no press or key on the host's page since: a real
829
882
  click on the page's button a moment after typing in the host's composer opens it, on full
830
883
  Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
831
- name. A draft it gives (P108) is at most 2,000 characters of text a person can
884
+ name, and so is one on a key of the person's that reached the page while it fought for the
885
+ keyboard, or, where the host's page sees the pointer, while the pointer was elsewhere (P120). A
886
+ draft it gives (P108) is at most 2,000 characters of text a person can
832
887
  see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
833
888
  new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
834
889
  Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.3",
3
+ "version": "0.14.4",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -6,7 +6,7 @@ import { parseViewer } from "../runtime/levels.ts";
6
6
  /**
7
7
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
8
8
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
9
- * own site) before any frame is made.
9
+ * own site; a nested page's on a shell's own label, P121) before any frame is made.
10
10
  */
11
11
  export async function locateServed(
12
12
  locator: InstanceLocator,
@@ -16,7 +16,7 @@ export async function locateServed(
16
16
  signal?: AbortSignal,
17
17
  ): Promise<FrameSource> {
18
18
  const location = await locator.locate(instance, signal);
19
- checkFrameLocation(location, config.contentOrigins, hostOrigin);
19
+ checkFrameLocation(location, config.contentOrigins, hostOrigin, config.nested === true);
20
20
  // The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
21
21
  // error, never no viewer (after the review: a mount's own would take its place).
22
22
  const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);