@botiverse/porthole 0.14.12 → 0.14.14
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 +46 -0
- package/dist/annotate/types.d.ts +10 -4
- package/dist/annotate/types.js +4 -1
- package/dist/annotate/validate.js +19 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -1
- package/dist/host/types.d.ts +9 -0
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/web.js +6 -1
- package/dist/react/frame.d.ts +4 -1
- package/dist/shell/annotate.d.ts +12 -1
- package/dist/shell/annotate.js +39 -5
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +53 -4
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +454 -4
- package/docs/DESIGN.md +21 -5
- package/docs/THREAT_MODEL.md +51 -8
- package/package.json +1 -1
- package/src/annotate/types.ts +10 -4
- package/src/annotate/validate.ts +23 -4
- package/src/host/create-host.ts +2 -1
- package/src/host/types.ts +9 -0
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +4 -1
- package/src/shell/annotate.ts +40 -5
- package/src/shell/frame.ts +45 -5
package/docs/DECISIONS.md
CHANGED
|
@@ -7597,7 +7597,7 @@ control: nothing here is a defense; the bound is `parseRect`'s, which existing p
|
|
|
7597
7597
|
box, and its scroll), the scroll without following a mark (a page with no marks the host follows),
|
|
7598
7598
|
or a host draws from `documentRect` inside the frame's own area and wants Porthole to clip for it.
|
|
7599
7599
|
|
|
7600
|
-
## P133 · 2026-11-06 · Markers are labelled buttons, a posted comment's sits at its paragraph's end, and reports say where the last line is · Accepted; amended by P134
|
|
7600
|
+
## P133 · 2026-11-06 · Markers are labelled buttons, a posted comment's sits at its paragraph's end, and reports say where the last line is · Accepted; amended by P134, P137
|
|
7601
7601
|
|
|
7602
7602
|
Amends P104 (its point 6, and its "Revisit when" on a keyboard inside the frame) and P105 (its
|
|
7603
7603
|
point 3, for posted text marks, and P2-B's click listener on each marker). Three follow-ups for
|
|
@@ -7734,7 +7734,7 @@ it didn't focus is missed, or reported as the marker that has the focus, so the
|
|
|
7734
7734
|
end should be on its left (P105's places aren't direction-aware either); paragraphs split by `<br>`
|
|
7735
7735
|
should count as many; or a host wants a picked paragraph's marker at its end.
|
|
7736
7736
|
|
|
7737
|
-
## P134 · 2026-11-06 · The keyboard back on a marker after the host's card closes, and a marker's name without an element's tag · Accepted
|
|
7737
|
+
## P134 · 2026-11-06 · The keyboard back on a marker after the host's card closes, and a marker's name without an element's tag · Accepted; amended by P135, P137
|
|
7738
7738
|
|
|
7739
7739
|
Amends P133 (its point 1, the name) and adds to P104's host API. Two follow-ups for comment markers,
|
|
7740
7740
|
from a host (Raft web): a person who pressed Enter on a marker reads the host's card, presses
|
|
@@ -7748,7 +7748,7 @@ anchor's marker is read out as "1 comment on p Paragraph 3. Filler…", the tag
|
|
|
7748
7748
|
is `focus(id)`'s, for the mark's marker: `focus` scrolls to a mark and lights it, and moves no DOM
|
|
7749
7749
|
focus. The shell moves the DOM focus to that mark's marker button, with the platform's `focus`
|
|
7750
7750
|
kept before content runs and `preventScroll`: the focus listener P133 added lights the words and
|
|
7751
|
-
brings it into view, as for a Tab. **It is for the Esc path only
|
|
7751
|
+
brings it into view, as for a Tab. **It is for the Esc path only** (widened the same day: a Tab past the view's ends closes it the same way, the same word, for the same reason; the shell doesn't change, and `THREAT_MODEL` §6 says so): after Escape closed the host's
|
|
7752
7752
|
own view of that mark. Nothing else needs a host to move the keyboard into a frame, and P109 and
|
|
7753
7753
|
§6 spend a good deal on keeping it out.
|
|
7754
7754
|
2. **No content, and nothing new back.** An id the host already sent in `show`; no report, no field,
|
|
@@ -7806,7 +7806,8 @@ nothing. The shell is the content server's: upgrade that.
|
|
|
7806
7806
|
after P112's): a page can time a forged `activated` and put the person's next keys in that view.
|
|
7807
7807
|
All three conditions are the host's: the signal read on its own page, focus only on a container
|
|
7808
7808
|
that takes no input, and its own gate on every control there that can write, so a forged opening
|
|
7809
|
-
and the keys after it can't submit
|
|
7809
|
+
and the keys after it can't submit (and on the key handlers and shortcuts that can write while the
|
|
7810
|
+
focus is there, P137). Porthole can't do that for it.
|
|
7810
7811
|
|
|
7811
7812
|
**Tested.** `test/annotate.test.ts`: what `createHost` sends and for which ids, kept for no later
|
|
7812
7813
|
frame, the throw without `annotate`; the kept `focus` and no `tell` in the shell's; every name
|
|
@@ -7837,3 +7838,452 @@ focusMark…". Reports are found by what they say, and a control's own follow-up
|
|
|
7837
7838
|
**Revisit when** a host needs to return focus somewhere other than after Escape; a host's card has a
|
|
7838
7839
|
reason to stay open while the keyboard goes back; or a platform's guard should take a host's own word
|
|
7839
7840
|
for a move into a frame it can't make itself.
|
|
7841
|
+
|
|
7842
|
+
## P135 · 2026-11-06 · A parked `focusMark` lands only while the focus is in the frame's document · Accepted; amended by P136, P137
|
|
7843
|
+
|
|
7844
|
+
Amends P134 (its points 3 and 4: a `focusMark` that waits, and the host's `display.focus()`).
|
|
7845
|
+
|
|
7846
|
+
**Context.** The shell parks `focusMark` while the marks are being found (`settling()`: about 150 ms
|
|
7847
|
+
after a change of the content or a `show`, up to 1 s on a page that keeps changing, and for as long as
|
|
7848
|
+
the content isn't in). It then landed in the anchor timer with nothing asked of the focus: nothing but
|
|
7849
|
+
`clear` cancelled it, and it didn't expire. A marker's kept `focus()` takes the keyboard with no
|
|
7850
|
+
gesture on Chromium and WebKit (P109, P134), and the focus guard defends only the host's text fields.
|
|
7851
|
+
So a word parked as a card closed, landing after the person had moved on to a host's button or link,
|
|
7852
|
+
pulled the keyboard into the page.
|
|
7853
|
+
|
|
7854
|
+
**Found: an unparked call has no such test.** `focusMark` read nothing of the focus when this was
|
|
7855
|
+
written: the shell asked `settling()`, `mode.elements`, `isShown(id)` and for a marker, and
|
|
7856
|
+
`create-host.ts` asks only that a shown mark has a marker, the React handle nothing more. So an
|
|
7857
|
+
unparked call lands from wherever the focus is, and that is what the Esc path needs: after a card
|
|
7858
|
+
closes the focus is on the host's `<body>`, so the frame's `document.hasFocus()` is false at exactly
|
|
7859
|
+
the moment P134 is for.
|
|
7860
|
+
|
|
7861
|
+
**Decision.**
|
|
7862
|
+
|
|
7863
|
+
1. **Where `pendingMarker` lands, it is dropped unless `document.hasFocus()` is true**, asked in the
|
|
7864
|
+
anchor timer, at the landing, not when the word came: where the focus was when it was parked says
|
|
7865
|
+
nothing of where the person is now. Dropped is dropped: not parked again, and nothing is told.
|
|
7866
|
+
2. **The test is on the parked path only** (P137 adds a word the frame took late: not parked says
|
|
7867
|
+
nothing of a word's age, and what follows held only for a calm page). It sits at the landing, not
|
|
7868
|
+
in `focusMark`, so an unparked call is as P134 left it. In `focusMark` it would refuse every call
|
|
7869
|
+
of P134's normal flow on a calm page, and Escape would stop reaching the marker. The two paths
|
|
7870
|
+
differ in what the word is: fresh, it is the host's word of this moment, about a focus the host
|
|
7871
|
+
can see on its own page; parked, it is up to a second old, and the frame can't know what happened
|
|
7872
|
+
on the host's page since. All the shell can ask then is whether the focus is still its own.
|
|
7873
|
+
3. **That is the intended logic, with this consequence: no focus, no grab.** In the normal flow the
|
|
7874
|
+
focus is on the host's body, so a first `focusMark` that happens to park is dropped, and a host
|
|
7875
|
+
that sends a `show` as its card closes (P134's point 3 says many do) parks every time. Only a call
|
|
7876
|
+
after the focus is in the frame lands: **a host calls `focusMark` again after its own move of the
|
|
7877
|
+
focus into the frame** (`display.focus()`). This is the host's fallback P134's point 4 didn't need,
|
|
7878
|
+
and that point stands for a calm page: `focusMark` first, on its own. The word can't be parked for
|
|
7879
|
+
the host to know, and nothing says it was dropped, so the host reads its own page a moment later:
|
|
7880
|
+
the frame not `document.activeElement`, and the focus still on the body (the person hasn't moved
|
|
7881
|
+
on), is when to move and ask again (ADOPTING has the code). Asking again is cheap: a second word
|
|
7882
|
+
after a landing moves nothing, and one sent while the first waits takes its place. If the host's
|
|
7883
|
+
move comes while the first word waits, the first lands by itself.
|
|
7884
|
+
4. **The kept `hasFocus`.** `Document.prototype.hasFocus`, taken before content runs beside the kept
|
|
7885
|
+
`focus`, and called with `callOf` (the kept `Reflect.apply`), as `marker-originals` keeps a press's
|
|
7886
|
+
readers, so neither a patched `hasFocus` nor a patched `Function.prototype.call` answers.
|
|
7887
|
+
|
|
7888
|
+
**What gets worse for a host that adds no second call.** The trade is the accuracy of "back on the
|
|
7889
|
+
marker" against never pulling the keyboard into the page. Read against the shell's anchor timer and
|
|
7890
|
+
Raft's `backToMark` (`focusMark` once, then after 150 ms, from `<body>` only, the frame's own
|
|
7891
|
+
`focus()`, and no second call). A call that doesn't wait is unchanged (on a calm page: P137). A call
|
|
7892
|
+
that waits meets the
|
|
7893
|
+
timer, which fires 150 ms after the last change or `show`, or at its run's one-second deadline
|
|
7894
|
+
whichever is first, so on a page still changing too, and a change after the call pushes it later:
|
|
7895
|
+
- **Normal frame, the timer fires before the host's fallback:** dropped, since the focus is on the
|
|
7896
|
+
body. The fallback then gives the frame the focus and not the marker; before this decision it
|
|
7897
|
+
landed on the marker. This is what gets worse.
|
|
7898
|
+
- **Normal frame, the timer fires after the fallback:** the focus is in the frame by then, and it
|
|
7899
|
+
lands, as before. A word parked by a `show` sent with it starts a 150 ms timer of its own, so
|
|
7900
|
+
against a 150 ms fallback the two are within a post of each other and either can come first.
|
|
7901
|
+
(Raft's marks don't change as a card closes, so there it is the page's changes that park it.)
|
|
7902
|
+
- **Nested page that had the focus (until P136):** the page's `hasFocus` stays false after the host's move (below),
|
|
7903
|
+
so a call that waits is dropped whenever the timer fires, whatever parked it, where it used to land.
|
|
7904
|
+
A nested page that never had the focus isn't measured. Raft has no nested pages today.
|
|
7905
|
+
|
|
7906
|
+
**Compatibility.** No API, message or report changes. A host that only ever calls on a calm page sees
|
|
7907
|
+
no change. A host whose first call parks stops getting the landing it got by luck: that landing was
|
|
7908
|
+
the bug, on a page the person may have left. Its fallback is the second call. An older shell lands
|
|
7909
|
+
as it did, and a second call there is harmless. The shell is the content server's: upgrade that. Hosts whose fallback already moves the focus into the frame (Raft: "within
|
|
7910
|
+
150 ms if the marker didn't take it") must add the second `focusMark`, or the keyboard stops at the
|
|
7911
|
+
frame's document and not on the marker.
|
|
7912
|
+
|
|
7913
|
+
**Threat.**
|
|
7914
|
+
- A page that patches `hasFocus` to say yes gets no landing the platform's answer refuses (control
|
|
7915
|
+
`marker-has-focus`; `marker-late` takes the test out). A page saying no only loses its own marker.
|
|
7916
|
+
- A page can make the true answer true: it may `focus()` its own element from anywhere but a host's
|
|
7917
|
+
text field (P109), and a parked word then lands. That gives it nothing: it already has the keyboard,
|
|
7918
|
+
and it can forge the message and focus a marker itself (P134).
|
|
7919
|
+
- A page can make a word park, by changing its content as the word comes, and so get it dropped. It
|
|
7920
|
+
reads the message anyway, and can take the focus back at once: failing is fine (P134), and the
|
|
7921
|
+
host's fallback then asks again.
|
|
7922
|
+
- `hasFocus` says the focus is in this document (or a frame of its own), not where. A parked word can
|
|
7923
|
+
still move the focus off the page's own field onto a marker. That stays inside the frame, is no
|
|
7924
|
+
keyboard taken from the host, and a page's own focus order is not the host's to defend (P133).
|
|
7925
|
+
- It still doesn't expire. Nothing here bounds a word parked while the content isn't in: it is only
|
|
7926
|
+
held to the same test when it lands, however late.
|
|
7927
|
+
- A fresh call lands from anywhere on the host's page, a host's button too, as in P134: it is the
|
|
7928
|
+
host's own word, for one moment, and calling it after the person moved on is the host's mistake.
|
|
7929
|
+
(This said "an unparked call", which was wrong: a busy page takes one late, with no mistake of the
|
|
7930
|
+
host's, and that landing took the keyboard from a person who had moved on. P137.)
|
|
7931
|
+
The fallback above must look before it moves. The focus guard is unchanged.
|
|
7932
|
+
|
|
7933
|
+
**Known gap: a nested page (#proj-workspace:#214; closed by P136, which also found the explanation
|
|
7934
|
+
below wrong on every engine).** Measured by CI on Chromium with frames in and
|
|
7935
|
+
out of process, WebKit and Firefox (Playwright 1.63): after a nested page had the focus and the
|
|
7936
|
+
person moved to a host's button, `display.focus()` leaves the page's `hasFocus` false, so this
|
|
7937
|
+
decision's fallback doesn't work there for a call that waits. The host's `activeElement` is the
|
|
7938
|
+
frame. On Chromium and WebKit the shell's is still the page's frame, so `frame.ts`'s focus listener
|
|
7939
|
+
doesn't pass the move on (`document.activeElement !== frame`). On Firefox the shell's isn't, so that
|
|
7940
|
+
listener's test doesn't explain it, and why isn't known. No focus goes to the page, so nothing leaks,
|
|
7941
|
+
and a call that doesn't wait lands (tested). This is an older path than P135, in `frame.ts`, which
|
|
7942
|
+
this decision doesn't change; `nested.spec.ts` marks the one step `test.fail` until #214 closes.
|
|
7943
|
+
|
|
7944
|
+
**Tested.** Measured by CI's run of these specs, on the engines as Playwright builds them.
|
|
7945
|
+
`leak/annotate.spec.ts`, three engines: "document.hasFocus() in a frame says where a host's moves leave the focus…" (the probe:
|
|
7946
|
+
a host's field, the body, the host's move in, the page's field, a host's button, the move back, an
|
|
7947
|
+
unparked landing); "a parked focusMark doesn't land once the person has moved on…" (`marker-late`),
|
|
7948
|
+
parked by a `show` with the person already gone; "a focusMark parked with the focus in the frame…"
|
|
7949
|
+
(`marker-late`), on a page that keeps changing, the person gone before it lands; "a parked focusMark
|
|
7950
|
+
with the focus on the host's body is dropped; after the host's own move…" (`marker-late`), the second
|
|
7951
|
+
parked too, and Enter on it reporting that mark; "a page that patched hasFocus…" (`marker-has-focus`, `marker-late`). P134's
|
|
7952
|
+
"focusMark puts the focus on that mark's marker…" is the unparked call from the body, on a calm page,
|
|
7953
|
+
unchanged; "focusMark right after a show…" now moves the focus in first. `leak/served/nested.spec.ts`:
|
|
7954
|
+
"a parked focusMark lands on a nested page's marker while the focus is in the page…", "a focusMark that
|
|
7955
|
+
doesn't wait lands on a nested page that had the focus…", and "a page that had the focus gets it back
|
|
7956
|
+
by the host's own move…", the known gap, `test.fail` from that step on. `test/annotate.test.ts`: the kept function, the
|
|
7957
|
+
landing's test, and no read of the focus in `focusMark`. CI's WebKit is Playwright's build, not
|
|
7958
|
+
Safari; Safari and iOS are unmeasured. Playwright emulates a focused window on every engine, so
|
|
7959
|
+
`hasFocus` false for a window behind another app (dropped, by the standard) is unmeasured too.
|
|
7960
|
+
|
|
7961
|
+
**Rejected.**
|
|
7962
|
+
- The test in `focusMark`: see point 2.
|
|
7963
|
+
- A time limit on the parked word: how long a word has waited says nothing of where the person is;
|
|
7964
|
+
a word 100 ms old can land on a person who moved on at 90.
|
|
7965
|
+
- Reading the host's focus from the host: `focusMark` sent only if the frame holds the focus, or a
|
|
7966
|
+
host-side recheck when the frame settles. The first is the Esc path again, the second a new report
|
|
7967
|
+
and a round trip for a moment where failing is fine.
|
|
7968
|
+
- `activeElement` in the frame (dropped unless on `<body>` or the layer): stricter inside the page, and
|
|
7969
|
+
the page writes that document; the wall here is the frame's edge.
|
|
7970
|
+
- Parking the word and landing it when focus next comes into the frame: a word with no end, landing
|
|
7971
|
+
at a moment nobody asked for.
|
|
7972
|
+
|
|
7973
|
+
**Revisit when** a host needs a parked word to land without moving the focus in first; CI or a real
|
|
7974
|
+
Safari shows `hasFocus` disagreeing with the host's `activeElement` after `display.focus()`; or a
|
|
7975
|
+
word must expire by itself (a host that sends many, or content that stays out for long).
|
|
7976
|
+
|
|
7977
|
+
## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own · Accepted
|
|
7978
|
+
|
|
7979
|
+
Amends P111 and closes P135's known gap (#proj-workspace:#214). Tenny's requirement, #proj-workspace:#211:
|
|
7980
|
+
`marker-late` covers the nested case.
|
|
7981
|
+
|
|
7982
|
+
**Context.** On a nested page that had the focus, `display.focus()` left the page's `hasFocus` false.
|
|
7983
|
+
P135 explained that from snapshots and `frame.ts`: the shell's `activeElement` was still the page's
|
|
7984
|
+
frame, so its listener didn't pass the move on; on Firefox, unexplained. Nobody had seen the listener
|
|
7985
|
+
fire. So this measured first (CI on #112, runs 42281836768 and 42284603904, on `frame.ts` as main had
|
|
7986
|
+
it: each frame logging its own focus events, its `focus()` and `blur()` calls, and where a key landed,
|
|
7987
|
+
from an init script over the console, nothing evaluated in the shell or the page).
|
|
7988
|
+
|
|
7989
|
+
**Measured: the explanation was wrong, on every engine, and the bug is wider.**
|
|
7990
|
+
- **Chromium (headless shell and full, frames out of process) and WebKit.** The listener fires. The
|
|
7991
|
+
shell's `activeElement` is `BODY` then, not the frame: focus leaving a frame clears each document's
|
|
7992
|
+
on the way out. So the test P135 named passes, and `frame.focus()` is called. It sets the shell's
|
|
7993
|
+
`activeElement` and fires the element's `focus`, and the focused frame doesn't move: no `blur` on the
|
|
7994
|
+
shell's window, nothing in the page, the next key at the shell. The frame in P135's snapshots was
|
|
7995
|
+
that failed call's effect, not its cause. From a later task the same call goes through.
|
|
7996
|
+
- **Firefox.** From a focused element of the host's, the shell's document gets `focus` and its window
|
|
7997
|
+
doesn't, so the listener never runs and `frame.focus()` is never called: not refused, not asked. A
|
|
7998
|
+
later task's call goes through with no gesture. From the host's `<body>` both get it, and the
|
|
7999
|
+
listener's own call goes through inside the event: why `had-body` was fine there.
|
|
8000
|
+
- **Not only a page that had the focus.** A page that never had it fails the same way (P135 hadn't
|
|
8001
|
+
measured that). And with the focus already in the page, Chromium and WebKit move it out to the
|
|
8002
|
+
shell: the host's move took the keyboard from the page, and the next key went nowhere. Firefox leaves
|
|
8003
|
+
it in the page.
|
|
8004
|
+
- **Why inside the event, a reading not a measurement:** Chromium's and WebKit's focus controllers
|
|
8005
|
+
ignore a change of the focused frame while one is in progress. What is measured is the behaviour.
|
|
8006
|
+
- **Firefox's key rule** (Gecko's `IsHandlingKeyBoardEvent`, no focus into a cross-origin frame while
|
|
8007
|
+
a key is handled) had nothing to do with this: there is no key in that case. It is a separate limit,
|
|
8008
|
+
under Residual.
|
|
8009
|
+
|
|
8010
|
+
**Decision.**
|
|
8011
|
+
1. **`display.focus()` tells the shell** (`porthole/shell/focus`, no params): for a nested frame, after
|
|
8012
|
+
the guard's move and only if it landed (the frame is the host's `activeElement`). It is a message, so
|
|
8013
|
+
it runs as a task of the shell's own, outside the focus event.
|
|
8014
|
+
2. **The shell acts on it only while the focus is on its own document** (`holds`: set by a `focus` on
|
|
8015
|
+
its window or, for Firefox, its document, cleared by its window's `blur`), and `document.hasFocus()`
|
|
8016
|
+
agrees: it blurs its frame (a failed call left it active, and `focus()` on the active element does
|
|
8017
|
+
nothing), then focuses it. Not holding the focus, it moves nothing, so a page that has the focus
|
|
8018
|
+
hears no blur from the word (the host's own call is another matter: "After its review"), and a word
|
|
8019
|
+
that came late takes nothing from where the host went on to.
|
|
8020
|
+
3. **A word ahead of its focus waits 250 ms, once.** The two cross processes; a word that comes first
|
|
8021
|
+
is kept that long, and spent on the next focus, in a task. In the one trace read per engine the
|
|
8022
|
+
focus came first; this is for an order nothing promises, and it hasn't been seen to run.
|
|
8023
|
+
4. **The listener and the focus guard stay as they were.** `focus-guard.ts` isn't touched: the host's
|
|
8024
|
+
move is judged as before, and handing on inside the frame leaves the host's `activeElement` on the
|
|
8025
|
+
frame, so the guard reads no change. Only the listener's comment changes: it spoke of a Tab, which
|
|
8026
|
+
doesn't land there (Residual).
|
|
8027
|
+
|
|
8028
|
+
**Compatibility.** An older shell drops a word in its namespace, and an older host sends none: either
|
|
8029
|
+
way as before. The shell is the content server's: upgrade both.
|
|
8030
|
+
|
|
8031
|
+
**Threat.** Nothing widens: no CSP, sandbox, gate or guard rule changes.
|
|
8032
|
+
- **Who can start it.** The shell takes the word from its parent, on a host origin, as P120's ask. A
|
|
8033
|
+
page's message comes from its own window, goes down the other branch and is dropped by namespace;
|
|
8034
|
+
said to the host's window, it is one more word the transport drops. So a focus reaches the page by
|
|
8035
|
+
this path only as the host's own move, which P111 and P120 already allow.
|
|
8036
|
+
- **`comments.open`.** The guard's `earned` for a host's move is what it was, so the gate already
|
|
8037
|
+
passed after `display.focus()`; a page that holds the focus adds no gesture to it.
|
|
8038
|
+
- **What a host gets.** The move does now put the keyboard in the page, which is what it was documented
|
|
8039
|
+
to do. Calling it after the person moved on takes the keyboard from them, as §6 says: that duty is
|
|
8040
|
+
the host's, and it now bites on a nested page too.
|
|
8041
|
+
- **A stale read.** Out of process, the shell's `hasFocus` can lag the host's move on by a moment. A word
|
|
8042
|
+
that passes then gives the page the focus the host just asked it to have. The case the shell can see
|
|
8043
|
+
is held (control); this one is the width of a process hop after a host's own call.
|
|
8044
|
+
|
|
8045
|
+
**Rejected.**
|
|
8046
|
+
- **Blur first, in the listener** (the first candidate): inside the event it is the failing call with a
|
|
8047
|
+
no-op before it, and on Firefox from a button the listener doesn't run.
|
|
8048
|
+
- **`hasFocus` for `activeElement` in the listener** (the second): the test never was what stopped it.
|
|
8049
|
+
- **Passing on from the listener, a task later, for any focus.** It would also fix the frame's own
|
|
8050
|
+
`focus()`, so the React step, with no message and no host change. But it passes on any focus into
|
|
8051
|
+
the shell, and a page can make one with `parent.focus()`: a new way for a page to start the shell's
|
|
8052
|
+
own move. Modelled in the shell, measured: on Chromium it gave the page the focus; on Firefox and
|
|
8053
|
+
WebKit it didn't (Firefox's window hears nothing, and `parent.focus()` moves nothing on WebKit). That
|
|
8054
|
+
buys a page nothing it hasn't: with no gesture, its own `field.focus()` puts the focus in the page on
|
|
8055
|
+
all four (Firefox: in its document, not on the field; at odds with P120's note that WebKit refuses
|
|
8056
|
+
one, a case not looked at again here). So this is no measured hole. It is left out because P111 and
|
|
8057
|
+
P120 name the host's move and not a page's, and the word is enough for what was asked. If React hosts
|
|
8058
|
+
of nested pages come up, this or a `focus()` on the handle is the choice to make.
|
|
8059
|
+
|
|
8060
|
+
**Residual.**
|
|
8061
|
+
- **The frame's own `focus()` stops at the shell** (no word): on Chromium and WebKit from anywhere, on
|
|
8062
|
+
Firefox from a focused element of the host's. ADOPTING's React step is that. React has no `focus()` on
|
|
8063
|
+
its handle, and adding one is an API decision this doesn't take.
|
|
8064
|
+
- **Firefox: `display.focus()` inside a key's own handler moves nothing**: the host's own `frame.focus()`
|
|
8065
|
+
leaves its `activeElement` where it was, so there is no move to pass on. Consistent with Gecko's rule;
|
|
8066
|
+
measured once on a nested page, not on others. ADOPTING's fallback runs in a timer, and isn't hit.
|
|
8067
|
+
`test.fail` on Firefox alone holds it.
|
|
8068
|
+
- **Where the focus lands.** In the page's document, not on its old element: focus leaving a frame
|
|
8069
|
+
clears its `activeElement`, so after the move it is `<body>` on all four. WebKit puts it back on the
|
|
8070
|
+
field at the next key.
|
|
8071
|
+
- **A Tab** was never the shell's: from the host's button it goes straight into the page on all four
|
|
8072
|
+
(measured), with no focus on the shell, so nothing here touches it.
|
|
8073
|
+
|
|
8074
|
+
**The control Tenny asked for.** "The person has moved on" on a nested page had none, and it wasn't
|
|
8075
|
+
only unrun, it couldn't have failed well: the case waited a fixed 600 ms, asked only the host's
|
|
8076
|
+
`activeElement` and the page's `hasFocus` (an engine that lands a marker inside a frame without the
|
|
8077
|
+
host's focus would pass), and `marker-late` didn't reach a nested page at all: its edit is to
|
|
8078
|
+
`annotate.ts`, which there is in the served shell, so it has to be in `weakenings.ts`'s `SERVED`. Now
|
|
8079
|
+
the case is its own test, starts with no marker holding the page's focus, waits for the `anchored`
|
|
8080
|
+
report naming the mark, and asks the page's `activeElement` first. `marker-late` runs `nested.spec.ts`
|
|
8081
|
+
and must fail it on Chromium, WebKit and Firefox. `chromium-oopif` runs the case, but no control: the
|
|
8082
|
+
registry's engines are those three (`controls.ts`).
|
|
8083
|
+
|
|
8084
|
+
**Tested.** `test/nested.test.ts`: the word, told as each engine tells it; moving nothing without the
|
|
8085
|
+
focus; a word ahead of its focus, once, and too old; a page saying it. `leak/served/nested.spec.ts`:
|
|
8086
|
+
"a page that had the focus gets it back by the host's own move, and a parked focusMark then lands…"
|
|
8087
|
+
(P135's step, no `test.fail`), "a page that never had the focus…", "the host's move into a page that
|
|
8088
|
+
holds the focus leaves it there", "the host's move from its own text field reaches the page, and the
|
|
8089
|
+
focus guard takes nothing back", "the host's move takes no keyboard from where the host's page went on
|
|
8090
|
+
to in the same task" (control `shell-focus-held`), "the host's move from inside a key's own handler…"
|
|
8091
|
+
(`test.fail` on Firefox), the page saying the word in "the shell's words are the shell's alone…". The
|
|
8092
|
+
keyboard's cases and `nested-fight` run unchanged. Static checks only where this was written: CI is
|
|
8093
|
+
the run. CI's WebKit is Playwright's build, not Safari; Safari and iOS are unmeasured.
|
|
8094
|
+
|
|
8095
|
+
**After its review** (Tenny, #112). Every case began from a press, where the shell never held the
|
|
8096
|
+
focus. If an engine's shell window got no `blur` during a handover, `holds` would stay true, `hasFocus`
|
|
8097
|
+
would be true with the focus in its child, and a second `display.focus()` would blur and refocus the
|
|
8098
|
+
page, which would lose its field. UX, not security; Firefox the likeliest.
|
|
8099
|
+
- **Measured (CI on #113, run 42297050666): it doesn't happen.** After a move in from a host's button,
|
|
8100
|
+
with the page's field then focused by the page, a second `display.focus()` left no `blur` in the page
|
|
8101
|
+
and the next key in its field, on Chromium, full Chromium, WebKit and Firefox. So the shell doesn't
|
|
8102
|
+
change. It agrees with the traces of #112: the window's `blur` fires in the handover on all four.
|
|
8103
|
+
- **That case is now held.** "a second host's move into a page it just handed the focus to…", and
|
|
8104
|
+
`shell-focus-held` has to fail it too: that the page's blurs are heard at all is what that shows.
|
|
8105
|
+
- **A correction: a page can still hear a blur from `display.focus()`, from the host's own call.** With
|
|
8106
|
+
the focus in the page by the person's press, Chromium and WebKit answer the host's `frame.focus()` by
|
|
8107
|
+
moving the focus out to the shell: `blur` on the page's field and window, before any word (the
|
|
8108
|
+
`in-page` trace of run 42281836768, on `frame.ts` before the word). The word then brings it back, so
|
|
8109
|
+
the page has the focus again, but it heard a blur and its field is no longer its `activeElement`.
|
|
8110
|
+
This case differs in how the page got the focus. Why that decides it is a reading, not a measurement:
|
|
8111
|
+
after a host's own move the host's document already holds the frame as its focused element, so a
|
|
8112
|
+
second `focus()` is no move, and after a press it doesn't. No word could stop that blur, the shell
|
|
8113
|
+
hasn't heard of the move yet, so it would be the host's change (no `frame.focus()` for a nested frame
|
|
8114
|
+
that is already its `activeElement`, the word alone). Not done here: nothing asked for it, and it
|
|
8115
|
+
isn't known that a host calls `display.focus()` with the person already in the page. Firefox doesn't
|
|
8116
|
+
do this: it leaves the focus in the page.
|
|
8117
|
+
|
|
8118
|
+
**Revisit when** a host of nested pages uses React; a host calls `display.focus()` with the person in
|
|
8119
|
+
the page and the blur shows; Firefox's key rule moves; or an engine lets a frame move inside the focus
|
|
8120
|
+
event that made it the focused one (then the word can go).
|
|
8121
|
+
|
|
8122
|
+
## P137 · 2026-11-07 · A `focusMark` is judged by when the host sent it, not by whether it was parked; a last line comes with its scroll; a host's shortcuts are under the second focus exception · Accepted
|
|
8123
|
+
|
|
8124
|
+
Amends P134 and P135. From the audit of 0.14.11 to 0.14.13, #proj-workspace:#215.
|
|
8125
|
+
|
|
8126
|
+
**Context.** P135 asks where the focus is only of a word parked while the marks are found, and
|
|
8127
|
+
whether a word is parked is decided as the frame takes it, not as the host sends it. A page busy with
|
|
8128
|
+
something that changes no DOM isn't settling, so the word comes late, unparked, and lands unasked.
|
|
8129
|
+
A frame out of process doesn't stop the host's page, so the person goes on meanwhile. If the same
|
|
8130
|
+
page changes the DOM as it wakes, the word is parked and dropped: the page's last act decided, not
|
|
8131
|
+
the word's age. So what P135 and §7 said of a word that doesn't wait ("the host's word of this
|
|
8132
|
+
moment", a late landing "the host's mistake") and what 0.14.13's changelog promised ("takes no
|
|
8133
|
+
keyboard from a person who moved on") held only on a calm page.
|
|
8134
|
+
|
|
8135
|
+
**Measured.** `leak/nested-late-word.spec.ts` and the new case in `served/nested.spec.ts`, against
|
|
8136
|
+
main's shell, CI runs 42330653613 and 42331677092 (Playwright 1.63). With a real click on a host's
|
|
8137
|
+
button 200 ms into 1 s of page work, on `chromium-oopif` the host's `activeElement` was that button
|
|
8138
|
+
after the click, the frame once the page was done, and the marker held the frame's focus. With the
|
|
8139
|
+
focus moved to that button in the task that sends the word, the word landed on all four projects,
|
|
8140
|
+
a nested page's too.
|
|
8141
|
+
The real click passes on the three in-process projects: the host's page freezes with the frame, and
|
|
8142
|
+
the click comes after the landing. From a host's text field the focus guard takes the move back (the
|
|
8143
|
+
audit's measure, not repeated here), so this is about buttons, links and a host's own lists.
|
|
8144
|
+
|
|
8145
|
+
**Decision.**
|
|
8146
|
+
|
|
8147
|
+
1. **`createHost` stamps the word**: `{ id, at: Date.now() }`, as it is sent.
|
|
8148
|
+
2. **A word 100 ms old or more is held to P135's test where it comes**: dropped unless the shell's
|
|
8149
|
+
document has the focus. The test is the same function, through the kept `hasFocus`, so a word that
|
|
8150
|
+
passes lands as a parked one does, and one that doesn't is dropped and nothing is told. A word
|
|
8151
|
+
the shell parks is still asked at its landing, whatever its age, and only there.
|
|
8152
|
+
3. **Below that, nothing is asked**, as P134 needs: the focus is on the host's `<body>` on a calm
|
|
8153
|
+
page's Esc path, so a test there would stop Escape reaching the marker. A second word after the
|
|
8154
|
+
host's own move (Raft's `backToMark`, 150 ms on) is fresh and lands; if the page is still busy
|
|
8155
|
+
it is late, the focus is in the frame by then, and it lands too.
|
|
8156
|
+
4. **The clock.** `Date.now`, on both sides: one machine's wall clock, the only clock two realms can
|
|
8157
|
+
compare (`performance.now()` counts from each realm's start). The shell's is `Date.now` taken
|
|
8158
|
+
before content runs, called with `callOf`, as the kept `hasFocus` is. Comparing is all it does with
|
|
8159
|
+
the numbers, and nothing there can be patched.
|
|
8160
|
+
5. **What counts as old.** No stamp, or one that makes no number, is old: it can't be known fresh.
|
|
8161
|
+
A stamp ahead of the shell's clock gets the same 100 ms: two processes can read a clock a little
|
|
8162
|
+
apart, and past that the clock was set back and the age says nothing. A word dropped by a clock
|
|
8163
|
+
that moved is a word dropped, and the fallback asks again.
|
|
8164
|
+
|
|
8165
|
+
**The number.** It has to clear what a calm page's word takes to arrive, and it has to end before a
|
|
8166
|
+
host's own fallback looks, since a word landing after that look can pull back a person the host
|
|
8167
|
+
just saw move on.
|
|
8168
|
+
- **Measured from below.** How old a word is as a page takes it, on CI's four-core runners with the
|
|
8169
|
+
suite's other workers running, from the host's `Date.now()` to the page's in its `message`
|
|
8170
|
+
listener (a probe in run 42330653613, not kept): 8,400 words, 2,100 on each of `chromium`,
|
|
8171
|
+
`chromium-oopif`, `webkit` and `firefox`, on a plain frame, a nested page (two hops) and a page
|
|
8172
|
+
drawing to a canvas for 8 ms of every animation frame, posted from a timer and from a real
|
|
8173
|
+
Escape's `keydown`.
|
|
8174
|
+
|
|
8175
|
+
| | median, worst round | 99th, worst round | most |
|
|
8176
|
+
| --- | --- | --- | --- |
|
|
8177
|
+
| Plain frame or nested page, from a timer | 0 to 1 ms | 1 to 3 ms | 10 ms |
|
|
8178
|
+
| The same, from a real Escape | 0 to 10 ms | 1 to 17 ms | 17 ms |
|
|
8179
|
+
| The page drawing every frame | 0 to 2 ms | 7 to 13 ms | 30 ms (WebKit) |
|
|
8180
|
+
|
|
8181
|
+
No word was read ahead of its stamp, and the shell reads it before the page does.
|
|
8182
|
+
- **From above.** Raft's fallback looks at 150 ms, ADOPTING's sample at 200.
|
|
8183
|
+
- **So 100 ms**: over three times the worst of those 8,400, for machines slower than CI's, and clear
|
|
8184
|
+
of the first fallback. A person who moves on inside it isn't defended, and P135's objection stands
|
|
8185
|
+
(a word 100 ms old can land on a person who moved on at 90). This narrows that, it doesn't end it.
|
|
8186
|
+
How soon people go on after a close isn't measured, nor what these numbers are on a person's busy
|
|
8187
|
+
machine: 100 ms is taken as faster than a person from an Escape to a click, not shown to be.
|
|
8188
|
+
|
|
8189
|
+
**Compatibility.** An older shell ignores `at`, and behaves as it did. **An older host with a newer
|
|
8190
|
+
shell loses the calm landing**: its word has no stamp, so from `<body>` it is dropped. That is the
|
|
8191
|
+
choice in point 5. Taking no stamp as fresh would keep that landing and leave this bug for every
|
|
8192
|
+
such host. Failing is fine here (P134), and pulling the keyboard is what P135 set out to end; a host
|
|
8193
|
+
with P135's fallback still lands, the frame focused by then. A shell is the content server's, so
|
|
8194
|
+
upgrade the two together. Nothing a host stores or reads changes.
|
|
8195
|
+
|
|
8196
|
+
**What gets worse for a host.** A word delayed past the bound with the person still on `<body>` used
|
|
8197
|
+
to land and is now dropped: on a busy page, and, where the frame shares the host's thread (as CI's
|
|
8198
|
+
headless shell and Firefox do, and WebKit by the click's result), when the host's own task runs on
|
|
8199
|
+
past 100 ms after the call (a heavy render as its card closes). The host's fallback picks that up.
|
|
8200
|
+
Hosts should call `focusMark` as their close runs. How long a real host's close takes wasn't measured.
|
|
8201
|
+
|
|
8202
|
+
**Threat.**
|
|
8203
|
+
- A page that stops or replaces `Date.now` gets nothing: the kept clock is what's read (control
|
|
8204
|
+
`marker-clock`). A page that patches `hasFocus` gets no landing here either (`marker-has-focus`, now
|
|
8205
|
+
on both tests through one function).
|
|
8206
|
+
- The word's stamp is the host's clock, and the page reads it. It tells the page how late it took the
|
|
8207
|
+
word, which it could tell from its own work, and the time, which it has.
|
|
8208
|
+
- A page can forge the word with a fresh stamp, or patch `MessageEvent`'s `data` so a real word reads
|
|
8209
|
+
fresh (the shell reads `event.data` live, as for every word here). It then lands its own marker,
|
|
8210
|
+
which P134 accepts: it can `focus()` an element of its own. P137 protects the person from a page
|
|
8211
|
+
that is only busy, not from one that means it: `focus()` was never closed to a page, off the host's
|
|
8212
|
+
text fields (P109).
|
|
8213
|
+
- A page can get a word dropped by staying busy past the bound, as P135's page can by changing its
|
|
8214
|
+
content. Failing is fine, and it reads the message anyway.
|
|
8215
|
+
- A person's move inside the bound isn't caught, above. The focus guard is unchanged, and still
|
|
8216
|
+
all that defends a host's text field.
|
|
8217
|
+
|
|
8218
|
+
**Controls.** `marker-busy` takes the new test out, and must fail, by `probe:`, on Chromium, WebKit and
|
|
8219
|
+
Firefox: "a focusMark a busy page takes late doesn't land once the host's page has moved on", its
|
|
8220
|
+
`Date.now` and `hasFocus` cases, and the nested case. Those move the focus in the task that sends the
|
|
8221
|
+
word, since an engine with one thread for the frames can't show a click in that wait. The real click
|
|
8222
|
+
is its own case, for `chromium-oopif`, which no control runs (P136). `marker-clock` reads the live clock
|
|
8223
|
+
and must fail the `Date.now` case. `marker-late` still takes out only the parked test: the landing
|
|
8224
|
+
calls `focusMark` as not late, or that control would go blind behind the new test.
|
|
8225
|
+
|
|
8226
|
+
**Tested.** `test/annotate.test.ts`: the stamp; the kept clock and the handler's read; the rule itself
|
|
8227
|
+
at its bounds and with no usable stamp (`WORD_LATE`, spliced as `MARKER_HIT` is, and run); one read of
|
|
8228
|
+
`hasFocus`. `leak/nested-late-word.spec.ts`, in a `nested*` file so `chromium-oopif` runs it, though
|
|
8229
|
+
its frames aren't nested: the click; the moved-on case, with a patched `Date.now` and `hasFocus`; a
|
|
8230
|
+
late word with the focus in the frame lands; five calm closes from the `<body>` land; Raft's fallback
|
|
8231
|
+
lands, with the first word 130 ms late. `leak/served/nested.spec.ts`: the word through the shell.
|
|
8232
|
+
Written on a host where test runs are paused: CI is the run. CI's WebKit is Playwright's build, not
|
|
8233
|
+
Safari; Safari and iOS are unmeasured.
|
|
8234
|
+
|
|
8235
|
+
**Rejected.**
|
|
8236
|
+
- Asking `hasFocus` of every word: Escape stops reaching the marker (P135's point 2).
|
|
8237
|
+
- The message's own `event.timeStamp`: the frame's, made after the wait this is about, and nothing of
|
|
8238
|
+
when the host sent it.
|
|
8239
|
+
- `performance.timeOrigin + performance.now()` on both sides, to survive a clock set back: two more
|
|
8240
|
+
originals to keep, for a case where a word is only dropped.
|
|
8241
|
+
- A time limit that drops a word (P135's rejected one): age here doesn't drop a word, it decides
|
|
8242
|
+
whether to ask. A parked word still doesn't expire.
|
|
8243
|
+
- A round trip (the frame asks the host if the word still stands): a report and a wait, for a moment
|
|
8244
|
+
where failing is fine (P135).
|
|
8245
|
+
|
|
8246
|
+
### A last line comes with its scroll
|
|
8247
|
+
|
|
8248
|
+
The shell sends `lastLineDocumentRect` and the `scroll` it was read at together (`placeOf`, P133), and
|
|
8249
|
+
ADOPTING's sample reads `report.scroll.x` wherever the line is set. `parseReport` checked each alone, so
|
|
8250
|
+
a forged `selected` or `tracked` with the line and no scroll got through, and that sample threw in
|
|
8251
|
+
the host's listener. `emit` doesn't catch a listener's throw, so the listeners after it missed that
|
|
8252
|
+
report. A page can stop a composer opening by not reporting a selection, so that is all it gained.
|
|
8253
|
+
|
|
8254
|
+
**Decision.** `parseReport` drops a report with a last line and no scroll, as one malformed part drops
|
|
8255
|
+
the whole. On `selected` the two are a strict pair. On `tracked` and `anchored` the rule goes one
|
|
8256
|
+
way, since **the scroll alone is a shell's own**: 0.14.10's `tracked` and `anchored` have it with no
|
|
8257
|
+
last line (P132 came a release before P133), and a newer shell's `tracked` and results have it where
|
|
8258
|
+
`lastLineOf` finds nothing drawn. A strict pair there would have dropped those two, every report of
|
|
8259
|
+
a 0.14.10 shell, and left a host following a mark with nothing. `anchored` wasn't in the audit: a
|
|
8260
|
+
result's last line is read with its report's `scroll` the same way, so it has the same hole.
|
|
8261
|
+
|
|
8262
|
+
**Older shells, read from their tags.** 0.14.9: `selected` and `tracked` with `rect` alone. 0.14.10: the
|
|
8263
|
+
same `selected`; `tracked` and `anchored` with `documentRect` and `scroll`. 0.14.11 on: as now. None
|
|
8264
|
+
sends a last line without a scroll, so an honest shell of any age loses no report (`test/annotate.test.ts`).
|
|
8265
|
+
|
|
8266
|
+
**Compatibility.** Only a forged report goes, so a host reads what it read. Raft's `selectionPlace`
|
|
8267
|
+
reads these two; its source wasn't in reach here, and nothing a real shell sends changes for it.
|
|
8268
|
+
|
|
8269
|
+
**Not done.** `documentRect` on `tracked` and on results, without `scroll`, still passes: ADOPTING tells
|
|
8270
|
+
a host to test for `scroll` there, and its sample does.
|
|
8271
|
+
|
|
8272
|
+
### The second exception names keys
|
|
8273
|
+
|
|
8274
|
+
P134's second exception to "takes no focus" lists "every control in that view that can write". Once the
|
|
8275
|
+
focus is on that `tabindex="-1"` container, the person's next keys go to the host's document: the
|
|
8276
|
+
container's key handlers and the host's page-wide shortcuts, neither of them a control in that view.
|
|
8277
|
+
Before P134 keys typed in the frame stayed in the frame. With the exception a page can forge `activated`
|
|
8278
|
+
while the person types in its own field and move their keys to the host, and a host whose single key
|
|
8279
|
+
writes (an `r` that resolves, Cmd+Enter that posts) could meet all three conditions as worded and still
|
|
8280
|
+
act on keys meant for the page.
|
|
8281
|
+
|
|
8282
|
+
**Decision.** §6 and ADOPTING's "Key or pointer" say so: a key handler or page-wide shortcut that can
|
|
8283
|
+
write while the focus is in that view needs the same gate. The third condition's purpose already
|
|
8284
|
+
covered it, and its list didn't. By reading: no host with such shortcuts was built to show it. A duty
|
|
8285
|
+
of the host's, like the rest of the exception. No code changes.
|
|
8286
|
+
|
|
8287
|
+
**Revisit when** a host's calm closes are seen dropped (the word's age on a real machine); people are
|
|
8288
|
+
seen moving on inside 100 ms; a platform gives frames a clock that is shared and monotonic; or the
|
|
8289
|
+
parked word's own age should count.
|
package/docs/DESIGN.md
CHANGED
|
@@ -1003,6 +1003,7 @@ for that to lapse and click with raw input.
|
|
|
1003
1003
|
| 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) |
|
|
1004
1004
|
| 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) |
|
|
1005
1005
|
| 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) |
|
|
1006
|
+
| A nested page's shell passes the focus on at the host's word (P136) | `display.focus()` sends `porthole/shell/focus`, only a move that landed; the shell acts only while the focus is on its own document, blurring its frame first, and a page's message in its namespace never reaches that code | `test/nested.test.ts` "the host's word that it moved the focus into a nested page's frame"; `leak/served/nested.spec.ts`: "a page that had the focus gets it back by the host's own move…", "a page that never had the focus…", "a second host's move into a page it just handed the focus to…", "the host's move into a page that holds the focus…", "the host's move from its own text field…", "the host's move takes no keyboard…", "the host's move from inside a key's own handler…" (`test.fail` on Firefox) | `shell-focus-held` |
|
|
1006
1007
|
| 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) |
|
|
1007
1008
|
| 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`) |
|
|
1008
1009
|
| 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) | — |
|
|
@@ -1047,13 +1048,13 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1047
1048
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1048
1049
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1049
1050
|
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1050
|
-
| host → frame | `porthole/annotate.focusMark` | `{ id }
|
|
1051
|
-
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two: P133, below); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1051
|
+
| host → frame | `porthole/annotate.focusMark` | `{ id, at }`, `at` the host's `Date.now()` as it sent it (P137): the DOM focus goes to that mark's marker (the DOM's own `focus`, taken before content runs), once the marks of a `show` are found; a call that had to wait for them is dropped unless the focus is in the frame's document as it lands (the DOM's own `hasFocus`, taken before content runs; P135), and so is one the frame takes 100 ms or more after `at` by its own clock (the DOM's own `Date.now`, taken before content runs) or with no `at` (P137); a fresh one isn't asked; nothing is reported back, and with no such marker, or while elements are picked, nothing happens. For after the keyboard closed the host's view: Escape, or a Tab past its ends (P134); a host calls it again after its own `display.focus()` |
|
|
1052
|
+
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two, only as a pair: P133, below, P137); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1052
1053
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1053
1054
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
1054
|
-
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below; `lastLineDocumentRect`: P133): every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1055
|
+
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below; `lastLineDocumentRect`: P133, never without `scroll`, P137): every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1055
1056
|
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
|
|
1056
|
-
| frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, lastLineDocumentRect?, scroll? }`: the followed mark's box at an animation frame where it moved, at most one every 16 ms; the host takes 60 a second, for that mark only (P112); a newer shell adds its place in the document and the document's scroll (P132), and its last line's (P133) |
|
|
1057
|
+
| frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, lastLineDocumentRect?, scroll? }`: the followed mark's box at an animation frame where it moved, at most one every 16 ms; the host takes 60 a second, for that mark only (P112); a newer shell adds its place in the document and the document's scroll (P132), and its last line's (P133, never without the scroll, P137) |
|
|
1057
1058
|
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker, or pressed Enter or Space on it (P133); `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
|
|
1058
1059
|
|
|
1059
1060
|
- **Anchors** are W3C Web Annotation selectors, at most one of each:
|
|
@@ -1192,7 +1193,17 @@ too (P133: a button in reading order and named for what it is, Enter and Space
|
|
|
1192
1193
|
reported once, a key held down once, none of it heard, nothing while elements are
|
|
1193
1194
|
picked; `marker-key`, `marker-click` too), brought into view by the focus and keeping
|
|
1194
1195
|
it through redraws, reached by the host's `focusMark` after its card closed and left
|
|
1195
|
-
alone where there's no such marker, by the kept `focus` (P134, `marker-focus`),
|
|
1196
|
+
alone where there's no such marker, by the kept `focus` (P134, `marker-focus`), a call parked meanwhile
|
|
1197
|
+
dropped once the person has moved on or the focus is on the host's body, and a second after the
|
|
1198
|
+
host's `display.focus()` landing (P135, `marker-late`), by the kept
|
|
1199
|
+
`hasFocus`, which a page's patch can't answer (`marker-has-focus`), a word a busy page takes late
|
|
1200
|
+
held to the same test, by the host's stamp and the kept clock, a calm close landing, and a second
|
|
1201
|
+
word after the host's move landing (P137, `marker-busy`, `marker-clock`, in
|
|
1202
|
+
`nested-late-word.spec.ts` so that full Chromium runs it, where a person's click comes before the
|
|
1203
|
+
word); on a nested page a parked call lands while the focus is in the page, not once the person has
|
|
1204
|
+
moved on (`marker-late`), a late word not either (`marker-busy`), and after
|
|
1205
|
+
the host's move, which the shell passes on (P136, `shell-focus-held`; on Firefox not from inside a
|
|
1206
|
+
key's own handler, `test.fail`), at its paragraph's end past the last word, a nested block's
|
|
1196
1207
|
words not its own, a draft's by its words; focus and
|
|
1197
1208
|
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1198
1209
|
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
@@ -1535,6 +1546,10 @@ control the tables above name to the registry):
|
|
|
1535
1546
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1536
1547
|
| `marker-key` | `annotate.spec.ts` | `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)` | — | — |
|
|
1537
1548
|
| `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
|
|
1549
|
+
| `marker-late` | `annotate.spec.ts`, `served/nested.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a parked focusMark doesn't land on a nested page once the person has moved on to the host's button (P135)` | — | — |
|
|
1550
|
+
| `marker-busy` | `nested-late-word.spec.ts`, `served/nested.spec.ts` | `a focusMark a busy page takes late doesn't land once the host's page has moved on (P137)`, `a page that stopped Date.now gets no landing for a word it took late (P137)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)`, `a focusMark a busy nested page takes late doesn't land once the host's page has moved on (P137)` | — | — |
|
|
1551
|
+
| `marker-clock` | `nested-late-word.spec.ts` | `a page that stopped Date.now gets no landing for a word it took late (P137)` | — | — |
|
|
1552
|
+
| `marker-has-focus` | `annotate.spec.ts`, `nested-late-word.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
|
|
1538
1553
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1539
1554
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1540
1555
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
@@ -1579,6 +1594,7 @@ control the tables above name to the registry):
|
|
|
1579
1594
|
| `door-opaque` | `served/siblings-status.spec.ts` | `[door-reach]` | — | — |
|
|
1580
1595
|
| `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
|
|
1581
1596
|
| `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` | — | — |
|
|
1597
|
+
| `shell-focus-held` | `served/nested.spec.ts` | `the host's move takes no keyboard from where the host's page went on to in the same task (P136)`, `a second host's move into a page it just handed the focus to leaves it there: no blur, and its field keeps the keyboard (P136)` | — | — |
|
|
1582
1598
|
| `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
|
|
1583
1599
|
| `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
|
|
1584
1600
|
| `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`) |
|