@botiverse/porthole 0.14.13 → 0.14.15
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 +63 -2
- package/dist/annotate/types.d.ts +47 -4
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +17 -1
- package/dist/annotate/validate.js +74 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +52 -4
- package/dist/host/types.d.ts +21 -6
- package/dist/index.d.ts +1 -1
- 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 +13 -1
- package/dist/react/frame.js +37 -24
- package/dist/shell/annotate.d.ts +18 -4
- package/dist/shell/annotate.js +193 -22
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +69 -15
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +500 -18
- package/docs/DESIGN.md +44 -12
- package/docs/THREAT_MODEL.md +48 -22
- package/package.json +1 -1
- package/src/annotate/types.ts +44 -4
- package/src/annotate/validate.ts +90 -4
- package/src/host/create-host.ts +53 -3
- package/src/host/types.ts +26 -6
- package/src/index.ts +1 -0
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +59 -31
- package/src/shell/annotate.ts +194 -22
- package/src/shell/frame.ts +45 -5
package/docs/DECISIONS.md
CHANGED
|
@@ -5985,7 +5985,7 @@ answer needs its sandbox taken off for a worker, and none is: the narrowest fix
|
|
|
5985
5985
|
`Sec-Fetch-Dest: worker` answer) would fix nothing. The agent manual already teaches workers from
|
|
5986
5986
|
`blob:` URLs only.
|
|
5987
5987
|
|
|
5988
|
-
## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted
|
|
5988
|
+
## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted; amended by P138
|
|
5989
5989
|
|
|
5990
5990
|
**Context.** Raft's comment design (its modes A–C, a card that follows its mark, a list in document
|
|
5991
5991
|
order, block selection on touch) needs more from `annotate` than 0.13 has. Each addition is the
|
|
@@ -6260,7 +6260,7 @@ Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole
|
|
|
6260
6260
|
unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
|
|
6261
6261
|
after `<` draws neither).
|
|
6262
6262
|
|
|
6263
|
-
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131
|
|
6263
|
+
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131, P138
|
|
6264
6264
|
|
|
6265
6265
|
**Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
|
|
6266
6266
|
which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
|
|
@@ -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; amended by P135
|
|
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
|
|
@@ -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
|
|
@@ -7838,7 +7839,7 @@ focusMark…". Reports are found by what they say, and a control's own follow-up
|
|
|
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.
|
|
7840
7841
|
|
|
7841
|
-
## P135 · 2026-11-06 · A parked `focusMark` lands only while the focus is in the frame's document · Accepted
|
|
7842
|
+
## P135 · 2026-11-06 · A parked `focusMark` lands only while the focus is in the frame's document · Accepted; amended by P136, P137
|
|
7842
7843
|
|
|
7843
7844
|
Amends P134 (its points 3 and 4: a `focusMark` that waits, and the host's `display.focus()`).
|
|
7844
7845
|
|
|
@@ -7862,12 +7863,13 @@ the moment P134 is for.
|
|
|
7862
7863
|
1. **Where `pendingMarker` lands, it is dropped unless `document.hasFocus()` is true**, asked in the
|
|
7863
7864
|
anchor timer, at the landing, not when the word came: where the focus was when it was parked says
|
|
7864
7865
|
nothing of where the person is now. Dropped is dropped: not parked again, and nothing is told.
|
|
7865
|
-
2. **The test is on the parked path only
|
|
7866
|
-
|
|
7867
|
-
|
|
7868
|
-
|
|
7869
|
-
|
|
7870
|
-
|
|
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.
|
|
7871
7873
|
3. **That is the intended logic, with this consequence: no focus, no grab.** In the normal flow the
|
|
7872
7874
|
focus is on the host's body, so a first `focusMark` that happens to park is dropped, and a host
|
|
7873
7875
|
that sends a `show` as its card closes (P134's point 3 says many do) parks every time. Only a call
|
|
@@ -7886,7 +7888,8 @@ the moment P134 is for.
|
|
|
7886
7888
|
**What gets worse for a host that adds no second call.** The trade is the accuracy of "back on the
|
|
7887
7889
|
marker" against never pulling the keyboard into the page. Read against the shell's anchor timer and
|
|
7888
7890
|
Raft's `backToMark` (`focusMark` once, then after 150 ms, from `<body>` only, the frame's own
|
|
7889
|
-
`focus()`, and no second call). A call that doesn't wait is unchanged
|
|
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
|
|
7890
7893
|
timer, which fires 150 ms after the last change or `show`, or at its run's one-second deadline
|
|
7891
7894
|
whichever is first, so on a page still changing too, and a change after the call pushes it later:
|
|
7892
7895
|
- **Normal frame, the timer fires before the host's fallback:** dropped, since the focus is on the
|
|
@@ -7896,7 +7899,7 @@ whichever is first, so on a page still changing too, and a change after the call
|
|
|
7896
7899
|
lands, as before. A word parked by a `show` sent with it starts a 150 ms timer of its own, so
|
|
7897
7900
|
against a 150 ms fallback the two are within a post of each other and either can come first.
|
|
7898
7901
|
(Raft's marks don't change as a card closes, so there it is the page's changes that park it.)
|
|
7899
|
-
- **Nested page that had the focus:** the page's `hasFocus` stays false after the host's move (below),
|
|
7902
|
+
- **Nested page that had the focus (until P136):** the page's `hasFocus` stays false after the host's move (below),
|
|
7900
7903
|
so a call that waits is dropped whenever the timer fires, whatever parked it, where it used to land.
|
|
7901
7904
|
A nested page that never had the focus isn't measured. Raft has no nested pages today.
|
|
7902
7905
|
|
|
@@ -7921,11 +7924,14 @@ frame's document and not on the marker.
|
|
|
7921
7924
|
keyboard taken from the host, and a page's own focus order is not the host's to defend (P133).
|
|
7922
7925
|
- It still doesn't expire. Nothing here bounds a word parked while the content isn't in: it is only
|
|
7923
7926
|
held to the same test when it lands, however late.
|
|
7924
|
-
-
|
|
7927
|
+
- A fresh call lands from anywhere on the host's page, a host's button too, as in P134: it is the
|
|
7925
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.)
|
|
7926
7931
|
The fallback above must look before it moves. The focus guard is unchanged.
|
|
7927
7932
|
|
|
7928
|
-
**Known gap: a nested page (#proj-workspace:#214
|
|
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
|
|
7929
7935
|
out of process, WebKit and Firefox (Playwright 1.63): after a nested page had the focus and the
|
|
7930
7936
|
person moved to a host's button, `display.focus()` leaves the page's `hasFocus` false, so this
|
|
7931
7937
|
decision's fallback doesn't work there for a call that waits. The host's `activeElement` is the
|
|
@@ -7964,7 +7970,483 @@ Safari; Safari and iOS are unmeasured. Playwright emulates a focused window on e
|
|
|
7964
7970
|
- Parking the word and landing it when focus next comes into the frame: a word with no end, landing
|
|
7965
7971
|
at a moment nobody asked for.
|
|
7966
7972
|
|
|
7967
|
-
**Revisit when**
|
|
7968
|
-
on a nested page); a host needs a parked word to land without moving the focus in first; CI or a real
|
|
7973
|
+
**Revisit when** a host needs a parked word to land without moving the focus in first; CI or a real
|
|
7969
7974
|
Safari shows `hasFocus` disagreeing with the host's `activeElement` after `display.focus()`; or a
|
|
7970
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.
|
|
8290
|
+
|
|
8291
|
+
## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted
|
|
8292
|
+
|
|
8293
|
+
Amends P112 (`track` follows the selection too) and P118 (`trackedSelection`). From a Raft user's
|
|
8294
|
+
report, Kirby's design.
|
|
8295
|
+
|
|
8296
|
+
**Context.** A host opens its composer on `selected`, where the selection is at that moment. A pick
|
|
8297
|
+
ends with element mode, and its outline with it (`hover = null`), so after the click nothing in the
|
|
8298
|
+
page says which element the composer is for. `selected` is sent once for a pick, and for words again
|
|
8299
|
+
only once a scroll settles, at most a second apart (P105). So a composer drawn as a popover at the
|
|
8300
|
+
report's box stays where the element was as the page scrolls, resizes or lays itself out again, and
|
|
8301
|
+
covers whatever comes there. A posted comment's card has what the composer lacks: `track(id)` follows
|
|
8302
|
+
its mark at every animation frame (P112), with its place in the document (P132), and `anchored` says
|
|
8303
|
+
when it is orphaned. But it follows a mark by id, and the selection has none.
|
|
8304
|
+
|
|
8305
|
+
**Decision.**
|
|
8306
|
+
|
|
8307
|
+
1. **`annotations.track({ selection: true })`** follows the selection the frame last reported as
|
|
8308
|
+
`selected` (the element picked, by a click or a held block, or the words selected) instead of a
|
|
8309
|
+
mark. One followed thing at a time, as before: a mark's id, `null` or `clear` ends it; a `show`, a
|
|
8310
|
+
`stop` and a pick's end leave it. It is kept for a frame that runs later, as a followed mark is.
|
|
8311
|
+
On the wire it is `porthole/annotate.track` with `{ id: null, selection: true }`.
|
|
8312
|
+
2. **The shell keeps what each `selected` reported**: the element, or a copy of the range (the DOM's
|
|
8313
|
+
own `cloneRange`, taken before content runs), which the page's changes keep up to date and which
|
|
8314
|
+
outlives the page's own selection (a click elsewhere, the host's `clearSelection`, P115). A newer
|
|
8315
|
+
`selected` replaces it, and a followed selection follows the new one from the next frame. Taken
|
|
8316
|
+
out of the page (a re-render), it is found again by its anchor, as a mark is, at most twice a
|
|
8317
|
+
second while it is gone.
|
|
8318
|
+
3. **`porthole/annotate.selectionTracked`** reports it as `tracked` reports a mark, on the same clock
|
|
8319
|
+
(an animation frame where it moved, at most one every 16 ms), and also when the frame's viewport
|
|
8320
|
+
changed size: `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }`,
|
|
8321
|
+
or `{ state: "orphaned" }` once while it isn't in the page (or the frame has nothing to follow, a
|
|
8322
|
+
new frame after a reload). The first comes at the frame after the host asks. `inView` is whether
|
|
8323
|
+
any of its box is inside the viewport. It is a new method, not `tracked` with another shape, so
|
|
8324
|
+
that `tracked`'s `id: string` stays as hosts read it and an older host drops it unread (an unknown
|
|
8325
|
+
method is no report, and not a malformed one).
|
|
8326
|
+
4. **`createHost` takes it only while it follows the selection**, at most 60 a second together with
|
|
8327
|
+
`tracked` (one array: one followed thing, one rate), outside the bridge's rate as `tracked` is
|
|
8328
|
+
(P112). Its `rect` is clamped (P104); `documentRect` and `lastLineDocumentRect` are checked and
|
|
8329
|
+
left unclamped (P132, P133); `inView` is the page's word and the host's together: false unless
|
|
8330
|
+
its box as reported reaches the viewport as the host reads it (`inViewport`), so a page can't say
|
|
8331
|
+
"in view" of a box the clamp puts on an edge. Every field but the last line is required: the
|
|
8332
|
+
method is new with its shell, which always has them.
|
|
8333
|
+
5. **The followed selection is drawn** in the shell's layer while it is followed: an element in the
|
|
8334
|
+
picking outline (blue, lighter, without the tag that names it), words with a light blue fill and
|
|
8335
|
+
a line under them, apart from the marks' yellow, since no comment is there yet. In the layer's
|
|
8336
|
+
`aria-hidden` outlines, under the layer's `pointer-events: none`: no pointer, no Tab stop, no
|
|
8337
|
+
name. It goes when the following ends.
|
|
8338
|
+
6. **React**: `trackedSelection?: boolean`. While true the selection is followed in
|
|
8339
|
+
`trackedAnnotation`'s place; false gives that mark back. A separate prop, not a wider
|
|
8340
|
+
`trackedAnnotation`, so the composer's state and the open card's are each a host's own value and
|
|
8341
|
+
the precedence is Porthole's, once.
|
|
8342
|
+
|
|
8343
|
+
**How a host tells, and what an older shell does.** A shell that follows a selection answers at its
|
|
8344
|
+
next animation frame, `attached` or `orphaned`. An older shell reads `{ id: null, selection: true }`
|
|
8345
|
+
as `track(null)`: it follows nothing, sends nothing, and draws nothing, which is today's behaviour,
|
|
8346
|
+
and a host that places by `selected`'s boxes until a `selectionTracked` comes keeps it there. An
|
|
8347
|
+
older host never asks, so a newer shell never sends it; a page that sends it anyway to an older host
|
|
8348
|
+
sends a method that host doesn't know.
|
|
8349
|
+
|
|
8350
|
+
**Not a loosening.** No CSP, sandbox flag, egress, gate or allowlist changes, and no new budget:
|
|
8351
|
+
- *Frame to host.* The same boxes the frame already sends in `selected` and `tracked` (`rect`,
|
|
8352
|
+
`documentRect`, `lastLineDocumentRect`, `scroll`) and a boolean, through the same checks, the same
|
|
8353
|
+
clamp and the same 60 a second as `tracked`, which it shares, since one thing is followed at a
|
|
8354
|
+
time: a host that followed a card and now follows a composer takes what it took. No anchor, label
|
|
8355
|
+
or words go with it: those went with `selected`. The host takes it only after it asked.
|
|
8356
|
+
- *Host to frame.* The page reads the host's messages (it shares the shell's realm, P053). It learns
|
|
8357
|
+
that the host follows its selection, and when that ends: that a composer is open on it, and closed.
|
|
8358
|
+
That is P112's `track(id)` (which card is open) and P121's `clearSelection` (when the person was done)
|
|
8359
|
+
for the composer: end it on every close, posted or dismissed, so the end says nothing of what came
|
|
8360
|
+
of it, as P121 asks of the clear.
|
|
8361
|
+
- *What the page can do with it.* It moves the host's composer, within its frame, as often as 60
|
|
8362
|
+
times a second, and can say it is out of view or gone. P112 accepted that for a card that follows
|
|
8363
|
+
its mark, under THREAT_MODEL §6's guard of a view a report moves (no press for 500 ms after it
|
|
8364
|
+
appears or moves, beside the frame where it can, no focus but by §6's exceptions); a composer that
|
|
8365
|
+
follows is such a view, and a composer hidden for `inView: false` and shown again appears again.
|
|
8366
|
+
`selectionTracked` joins §6's list. A forged `orphaned` or `inView: false` is no more than a page
|
|
8367
|
+
that never reports a selection, which it can already do; a host keeps the person's words in the
|
|
8368
|
+
composer either way.
|
|
8369
|
+
- *The layer.* A closed shadow root the page can't read, as for marks; the highlight takes no
|
|
8370
|
+
pointer, so the page's clicks and selections reach it as before.
|
|
8371
|
+
|
|
8372
|
+
**Focus and keys.** Following reads boxes and draws; it calls no `focus()`, changes no selection,
|
|
8373
|
+
adds no listener, and prevents and stops no event. Markers' tab stops, `focusMark` and its tests
|
|
8374
|
+
(P134, P135, P137), `display.focus()` on a nested page (P136), the hold gesture (P112) and Escape (a
|
|
8375
|
+
pick's, and text mode's `cancelled`) are as they were. Escape in the frame doesn't end the following:
|
|
8376
|
+
the host ends it from its composer's own Escape, and a frame's Escape while text is selected is
|
|
8377
|
+
`cancelled` as before (P112).
|
|
8378
|
+
|
|
8379
|
+
**Rejected.**
|
|
8380
|
+
- *A draft mark for the composer* (`show` with `kind: "draft"` and `track` its id), which works today:
|
|
8381
|
+
a draft is a comment the author kept, drawn with a marker, a button in the page's Tab order and
|
|
8382
|
+
named "Draft comment" (P107, P133), anchored again from its selectors (best-effort, 150 ms after a
|
|
8383
|
+
change), and it reaches the page as a draft; the composer is none of those until the person keeps
|
|
8384
|
+
it.
|
|
8385
|
+
- *`selected` re-sent at every frame*: it carries the anchor and its words, which the bridge's rate
|
|
8386
|
+
is for, and an older host would open its composer again at each one.
|
|
8387
|
+
- *`tracked` with `selection: true` and no `id`*: `tracked`'s `id` is a string hosts read, and an
|
|
8388
|
+
older host would count each as a malformed report against the page.
|
|
8389
|
+
- *`inView` computed by the host alone*: the shell can say more (a box its page clips), and the
|
|
8390
|
+
host's test still bounds it.
|
|
8391
|
+
|
|
8392
|
+
**Tested.** `test/annotate.test.ts` "the followed selection (P138)": `parseReport` rebuilds it from
|
|
8393
|
+
known fields (an anchor, a label or an id a page adds are dropped), drops a malformed or incomplete
|
|
8394
|
+
one; `inViewport` and `followsSelection`; through `createHost`, the wire message, an older shell's
|
|
8395
|
+
reading of it, reports taken only while followed, a show leaving it, a mark's id, `null` and `clear`
|
|
8396
|
+
ending it, the clamp and `inView`, 60 a second, and the following kept for a new frame; the shell's
|
|
8397
|
+
runtime: only `selection === true` follows it, a mark's id wins, its tells carry no words and it
|
|
8398
|
+
calls no focus, selection or listener, the kept `cloneRange`, every `selected` kept, the highlight in
|
|
8399
|
+
the aria-hidden outlines. `leak/annotate.spec.ts` "a followed selection's place comes as it moves…"
|
|
8400
|
+
(three engines): a picked element followed and lit, out of view and back as the document scrolls,
|
|
8401
|
+
orphaned when the page takes it out and found again when it puts it back, a page's own word taken
|
|
8402
|
+
neither unasked nor after `track(null)` nor past 60 a second, the highlight gone with the following;
|
|
8403
|
+
"following the selection moves no focus…": with the page's field focused, nothing moves the focus,
|
|
8404
|
+
the page hears every key, Escape is `cancelled` as before, and the words stay followed after the
|
|
8405
|
+
host's `clearSelection`, where the layout moves them. `leak/react.spec.ts` "trackedSelection follows
|
|
8406
|
+
the picked element…": in `trackedAnnotation`'s place, and false gives the mark back;
|
|
8407
|
+
`test/react-ssr.test.ts` its type. Negative control `track-selection-checks` (taken unasked, at any
|
|
8408
|
+
rate).
|
|
8409
|
+
|
|
8410
|
+
*After Tenny's review (porthole#116), two changes, decided by the reviewer:*
|
|
8411
|
+
|
|
8412
|
+
- **No gap at pick time.** A pick's outline went with the pick, and the follow's highlight came only
|
|
8413
|
+
once the host's `track` arrived: a frame or two with nothing drawn. Now the element just picked (a
|
|
8414
|
+
click's, or a held block's) keeps an outline after `selected`, drawn as the follow's highlight is,
|
|
8415
|
+
until the host follows it (the follow takes it over in the same draw, so nothing changes on
|
|
8416
|
+
screen) or the pick ends as a selection does: the next pick, or a selection reported after it;
|
|
8417
|
+
the host's `clearSelection`; a mode started or stopped (`start`, `stop`); `clear`; Escape in the
|
|
8418
|
+
frame (the key is left as it was: nothing prevents or stops it); or the element leaving the page.
|
|
8419
|
+
There is no timer. Not `unselected`: a selection made after the pick already ended it as it was
|
|
8420
|
+
reported, so the only selection `unselected` can be about is one from before the pick, which the
|
|
8421
|
+
pick's own click takes away where text is selected too, and ending on it would take the outline
|
|
8422
|
+
away a moment after the pick. An older host never follows, so its people now see the picked
|
|
8423
|
+
element outlined until one of those, where before the outline went at once: the shell's change
|
|
8424
|
+
alone, bounded by the events that end a selection today.
|
|
8425
|
+
So the follow comes before a mode change that a host makes in the same moment (it ends picking
|
|
8426
|
+
as its composer opens), the React binding sends the following before the mode (the mode's effect
|
|
8427
|
+
now runs after the following's); a host on the core calls `track({ selection: true })` before
|
|
8428
|
+
`start` or `stop`. The other way round, the stop ends the outline and the follow draws it again a
|
|
8429
|
+
task later, which is the gap this removes.
|
|
8430
|
+
- **No re-sent `selected` while followed.** While the selection is followed, a scroll sets no
|
|
8431
|
+
follow-up for it (P105's re-send once a scroll settles): the follow's reports already say where it
|
|
8432
|
+
is, and the re-send spent the bridge's 120 reports a minute, which the person's clicks need. A new
|
|
8433
|
+
selection is still reported, as ever. Once the following ends, a scroll re-sends it as before (its
|
|
8434
|
+
box is compared with the one last told, so one that moved meanwhile is told then).
|
|
8435
|
+
|
|
8436
|
+
*Tested.* `test/annotate.test.ts` "a pick keeps its outline until the host follows it…", "without a
|
|
8437
|
+
follow, a pick's outline ends as a selection does…", "while the selection is followed, a scroll
|
|
8438
|
+
re-sends no selected…" (the shell's runtime, as its other tests read it), and the highlight test
|
|
8439
|
+
reads the outline drawn for either. `leak/annotate.spec.ts` "a pick keeps its outline until the host
|
|
8440
|
+
follows it, and without a follow it ends as a selection does…" (three engines: outlined after the
|
|
8441
|
+
pick and 1.5 s on, then gone at Escape, which the page still hears, at a mode started, at stop, at
|
|
8442
|
+
`clearSelection`, at the next pick, at a selection after a pick, at `clear`; lit as the follow takes
|
|
8443
|
+
over and gone at its end); "while the selection is followed a scroll re-sends no selected…" (no
|
|
8444
|
+
`selected` past the settle and the follow-ups' clock while `selectionTracked` comes, then a re-send
|
|
8445
|
+
once the following ends); the follow's test now finds the picked element outlined before the host
|
|
8446
|
+
follows it. No new negative control: neither is a defense.
|
|
8447
|
+
|
|
8448
|
+
**Revisit when** a host needs two things followed at once (a composer beside an open card); the
|
|
8449
|
+
selection inside a page's own scrolling box (its `inView` there is the viewport's, not the box's);
|
|
8450
|
+
Escape in the frame should end a composer by itself; `inView` on a followed mark's `tracked` too; or
|
|
8451
|
+
an older host's people are seen confused by a pick's outline that stays.
|
|
8452
|
+
|