@botiverse/porthole 0.14.2 → 0.14.3
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 +16 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/shell/annotate.d.ts +9 -0
- package/dist/shell/annotate.js +73 -8
- package/docs/DECISIONS.md +73 -0
- package/docs/DESIGN.md +10 -3
- package/docs/THREAT_MODEL.md +7 -2
- package/package.json +1 -1
- package/src/shell/annotate.ts +74 -8
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -1,3 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export declare const MARKER_HIT: string;
|
|
1
10
|
/**
|
|
2
11
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
12
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
package/dist/shell/annotate.js
CHANGED
|
@@ -1,3 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export const MARKER_HIT = String.raw `(count, boxAt, x, y, touch) => {
|
|
10
|
+
const TARGET = 44;
|
|
11
|
+
let best = -1;
|
|
12
|
+
let nearest = 0;
|
|
13
|
+
for (let i = count - 1; i >= 0; i -= 1) {
|
|
14
|
+
const rect = boxAt(i);
|
|
15
|
+
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
16
|
+
return i;
|
|
17
|
+
}
|
|
18
|
+
if (touch) {
|
|
19
|
+
const dx = x - (rect.x + rect.width / 2);
|
|
20
|
+
const dy = y - (rect.y + rect.height / 2);
|
|
21
|
+
const halfWidth = (rect.width > TARGET ? rect.width : TARGET) / 2;
|
|
22
|
+
const halfHeight = (rect.height > TARGET ? rect.height : TARGET) / 2;
|
|
23
|
+
if (dx >= -halfWidth && dx <= halfWidth && dy >= -halfHeight && dy <= halfHeight) {
|
|
24
|
+
const distance = dx * dx + dy * dy;
|
|
25
|
+
if (best === -1 || distance < nearest) {
|
|
26
|
+
best = i;
|
|
27
|
+
nearest = distance;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return best;
|
|
33
|
+
}`;
|
|
1
34
|
/**
|
|
2
35
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
36
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -376,7 +409,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
376
409
|
// layer inherits from the page could reach it, so each of those is set here). A draft
|
|
377
410
|
// (P107) is a comment not yet posted: its line is dashed (an element's outline too) and its
|
|
378
411
|
// marker hollow, a light bubble with a dashed edge and the glyph's outline, no number.
|
|
379
|
-
|
|
412
|
+
// While the last pointer was a finger or a pen (P119), each marker takes the pointer in a
|
|
413
|
+
// box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
|
|
414
|
+
// box, its border 1 px), so a tap a few px off still lands on the shell's layer.
|
|
415
|
+
const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
|
|
380
416
|
// Inline and important: the content's own style sheets can't hide, shrink or move it by
|
|
381
417
|
// accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
|
|
382
418
|
// content can still cover the layer, or move it with its ancestors, P104).
|
|
@@ -404,6 +440,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
404
440
|
// marker's node across draws, so a press that spans a redraw ends on the node it began on.
|
|
405
441
|
let markers = [];
|
|
406
442
|
const markerNodes = new Map();
|
|
443
|
+
// Whether the last pointer was a finger or a pen (P119): then each marker takes the pointer
|
|
444
|
+
// in a 44 px box around it (the markers' box has the class "touch"). Until a pointer is
|
|
445
|
+
// seen, whether the device has a coarse pointer at all (a phone, a tablet, a laptop with a
|
|
446
|
+
// touch screen): a mouse moves before it presses, and its first move turns it off.
|
|
447
|
+
const coarseQuery = typeof window.matchMedia === "function" ? window.matchMedia("(any-pointer: coarse)") : null;
|
|
448
|
+
let touch = coarseQuery !== null && coarseQuery.matches === true;
|
|
449
|
+
const markerHit = ${MARKER_HIT};
|
|
407
450
|
const MARKER_HEIGHT = 18;
|
|
408
451
|
const SVG = "http://www.w3.org/2000/svg";
|
|
409
452
|
const labelOf = (count) => (count === 0 ? "" : count > 99 ? "99+" : String(count));
|
|
@@ -714,6 +757,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
714
757
|
if (boxes.style.textContent !== STYLE) {
|
|
715
758
|
boxes.style.textContent = STYLE;
|
|
716
759
|
}
|
|
760
|
+
if (boxes.markers.className !== (touch ? "touch" : "")) {
|
|
761
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
762
|
+
}
|
|
717
763
|
return boxes;
|
|
718
764
|
};
|
|
719
765
|
const draw = () => {
|
|
@@ -1118,14 +1164,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1118
1164
|
const rect = callOf(elementRect, element, []);
|
|
1119
1165
|
return { x: callOf(leftOf, rect, []), y: callOf(topOf, rect, []), width: callOf(widthOf, rect, []), height: callOf(heightOf, rect, []) };
|
|
1120
1166
|
};
|
|
1167
|
+
// The marker a press at (x, y) is for: on a marker's own box, that one; after a finger or a
|
|
1168
|
+
// pen, also within the 44 px box around one, the nearest (P119).
|
|
1121
1169
|
const markerAt = (x, y) => {
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
1125
|
-
return markers[i];
|
|
1126
|
-
}
|
|
1127
|
-
}
|
|
1128
|
-
return null;
|
|
1170
|
+
const at = markerHit(markers.length, (i) => markerBox(markers[i].element), x, y, touch);
|
|
1171
|
+
return at < 0 ? null : markers[at];
|
|
1129
1172
|
};
|
|
1130
1173
|
const isShown = (id) => {
|
|
1131
1174
|
for (let i = 0; i < marks.length; i += 1) {
|
|
@@ -1170,6 +1213,28 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1170
1213
|
const CANCELLED = { mousedown: 1, mouseup: 1, click: 1, dblclick: 1, auxclick: 1, contextmenu: 1 };
|
|
1171
1214
|
// The pointer on a marker (1), or leaving the layer for the content (0).
|
|
1172
1215
|
const HOVERS = { pointerover: 1, pointermove: 1, pointerout: 0, pointerleave: 0 };
|
|
1216
|
+
// Which pointer the person uses (P119), from each real one that goes down or moves, before
|
|
1217
|
+
// the marker's listener (which stops a press on the layer): a finger or a pen gives every
|
|
1218
|
+
// marker its 44 px box, a mouse takes it away. A mouse moves before it presses, so its press
|
|
1219
|
+
// is hit-tested on the markers' own boxes. Read through the platform's getter, kept now; an
|
|
1220
|
+
// event the page makes up (isTrusted is false) changes nothing.
|
|
1221
|
+
const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
|
|
1222
|
+
const onPointer = (event) => {
|
|
1223
|
+
if (!event.isTrusted || pointerTypeOf === null) {
|
|
1224
|
+
return;
|
|
1225
|
+
}
|
|
1226
|
+
const kind = callOf(pointerTypeOf, event, []);
|
|
1227
|
+
const next = kind === "touch" || kind === "pen";
|
|
1228
|
+
if (next !== touch) {
|
|
1229
|
+
touch = next;
|
|
1230
|
+
if (boxes !== null) {
|
|
1231
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
1232
|
+
}
|
|
1233
|
+
}
|
|
1234
|
+
};
|
|
1235
|
+
for (const type of ["pointerdown", "pointermove"]) {
|
|
1236
|
+
window.addEventListener(type, onPointer, true);
|
|
1237
|
+
}
|
|
1173
1238
|
for (const type of ["pointerdown", "pointerup", "pointercancel", "mousedown", "mouseup", "click", "dblclick", "auxclick", "contextmenu", "touchstart", "touchend", "touchcancel", "pointerover", "pointerout", "pointerenter", "pointerleave", "pointermove", "mouseover", "mouseout", "mouseenter", "mouseleave", "mousemove"]) {
|
|
1174
1239
|
window.addEventListener(type, onMarker, true);
|
|
1175
1240
|
}
|
package/docs/DECISIONS.md
CHANGED
|
@@ -6299,3 +6299,76 @@ as the frame scrolls, none after `null`, again when set again, an unshown id tol
|
|
|
6299
6299
|
and "a ref's clearSelection takes the frame's selection away; nothing without a display (P118)"
|
|
6300
6300
|
(a text selection cleared, a frame not yet running and a config without `annotate`, the ref let
|
|
6301
6301
|
go on unmount).
|
|
6302
|
+
|
|
6303
|
+
## P119 · 2026-10-29 · On touch, a marker's hit area is at least 44 by 44 px · Accepted
|
|
6304
|
+
|
|
6305
|
+
**Context.** A marker is a bubble about 34 by 18 CSS px (18 by 18 without a number), and the shell
|
|
6306
|
+
took a press only on that box: a finger a few px off landed on the paragraph under it. Raft's QA
|
|
6307
|
+
found that on phones a tap on a comment's marker often opened nothing. 44 px is the usual touch
|
|
6308
|
+
target. This is the hit-area half of porthole#42; checking taps on a real iOS Safari (the hover
|
|
6309
|
+
redraw) stays open there.
|
|
6310
|
+
|
|
6311
|
+
**Decision.** While touch is in use, each marker also takes the pointer in a box of at least 44 by
|
|
6312
|
+
44 CSS px centred on its bubble (its own size where the bubble is larger). The bubble looks the same.
|
|
6313
|
+
|
|
6314
|
+
- **Where.** In the shell's own layer, as an invisible `::before` on each marker (`.touch>.marker`,
|
|
6315
|
+
`max(100% + 2px, 44px)` square, centred). The browser's own hit test then gives the press to the
|
|
6316
|
+
layer, so it follows the path a press on the bubble takes today, unchanged: stopped in the shell's
|
|
6317
|
+
first window listener, read through the platform's getters, and reported `activated` only for a
|
|
6318
|
+
trusted click with the main button whose target is the layer, with the bubble's own box as
|
|
6319
|
+
`rect`. Nothing the page draws or sends can make a box like this, and the host's gate (transient
|
|
6320
|
+
activation, its own shown ids) is unchanged.
|
|
6321
|
+
- **When.** While the last trusted `pointerdown` or `pointermove` was a finger or a pen
|
|
6322
|
+
(`pointerType`, read through `PointerEvent.prototype`'s getter kept before content runs). Before
|
|
6323
|
+
any pointer is seen, while `(any-pointer: coarse)` matches (a phone, a tablet, a laptop with a touch
|
|
6324
|
+
screen). A mouse moves before it presses, so its first move takes the boxes away, and a mouse
|
|
6325
|
+
press is hit-tested on the bubbles alone, as before, even on a touch laptop. That is why
|
|
6326
|
+
`(pointer: coarse)` alone was not used: it describes the main pointer, so a touch laptop would
|
|
6327
|
+
never get the boxes. `(any-pointer: coarse)` alone was not used either: on that laptop a mouse
|
|
6328
|
+
would get them too. On Chromium, WebKit and Firefox under Playwright's `hasTouch`, both queries
|
|
6329
|
+
match (measured), so even the first tap gets the boxes.
|
|
6330
|
+
- **Which marker.** A point on a bubble is that bubble's (the topmost, as before). Otherwise, among
|
|
6331
|
+
the markers whose 44 px box holds the point, it is the one whose bubble's centre is nearest
|
|
6332
|
+
(`MARKER_HIT`, spliced into the runtime and unit-tested on its own). The CSS only decides whether
|
|
6333
|
+
the layer gets the press; the shell's own geometry decides which marker it is.
|
|
6334
|
+
|
|
6335
|
+
**Trade-off.** On touch, a tap within 13 px above or below a bubble (5 px beside a "1" bubble,
|
|
6336
|
+
13 px beside an empty one) is the marker's, not the page's. A marker in a line's gutter lies beside
|
|
6337
|
+
the line's end, so its box can cover a few px of the words on the lines above and below. A tap
|
|
6338
|
+
there opens the marker rather than reaching the paragraph. That is the point of a touch target.
|
|
6339
|
+
The page still gets every tap past the box (tested). A touch laptop's first finger after a mouse is
|
|
6340
|
+
hit-tested as the mouse left it (the boxes come with that finger's `pointerdown`, after the browser
|
|
6341
|
+
has already picked its target), so that one tap gets today's small target. A mouse resting
|
|
6342
|
+
unmoved over a box after a finger can click it: the boxes go with the mouse's next move.
|
|
6343
|
+
|
|
6344
|
+
**Rejected.** Taking the page's own events for a press near a marker (claiming a `pointerdown` on
|
|
6345
|
+
the paragraph, then its `click`). WebKit makes no click of a tap on an element without a click
|
|
6346
|
+
listener (P105), so the shell would have to report on `touchend` instead, a different path from a
|
|
6347
|
+
click's, and the page would already have heard the press begin. Enlarging the bubble itself: it
|
|
6348
|
+
would cover more of the words for everyone, mouse users included.
|
|
6349
|
+
|
|
6350
|
+
**No negative control.** This opens nothing and closes nothing: the press is still the trusted
|
|
6351
|
+
click on the shell's own layer that P105's controls (`marker-click`, `marker-prevent`,
|
|
6352
|
+
`marker-originals`) already hold. A weakening "no 44 px box" would be a missing feature, not a
|
|
6353
|
+
broken defense, and the probes below fail without the boxes (checked by turning them off).
|
|
6354
|
+
|
|
6355
|
+
**Investigated with it (Raft QA, porthole#42).** (1) After the page scrolls itself
|
|
6356
|
+
(`window.scrollBy`) and settles, under Chromium's iPhone 13 and Pixel 5: a tap or a mouse click at
|
|
6357
|
+
the bubble's centre does report `activated`. A hover redraw replaces no marker's node (P105 keeps
|
|
6358
|
+
them across draws), and the marker's node is under its bubble. `document.elementFromPoint` in the
|
|
6359
|
+
frame answers the layer, not the marker, by design: the layer's shadow root is closed. (2) An
|
|
6360
|
+
element's marker pinned at the frame's top once the element's start has scrolled above it takes a
|
|
6361
|
+
mouse click and a tap at its drawn pixels, on all three engines and on main before this change.
|
|
6362
|
+
Neither reproduced in Porthole's reference host. What QA saw is to be looked for in the viewer: a
|
|
6363
|
+
host element over the frame's top edge, a tap's point not in the page's own coordinates, a
|
|
6364
|
+
nested page's offset, or the host's guard on its view.
|
|
6365
|
+
|
|
6366
|
+
Tested: `test/annotate.test.ts` (the hit rule: on a bubble, 44 by 44 on touch only, the edges, a
|
|
6367
|
+
bubble wider than 44, the nearest of two, a bubble over a nearer centre); `leak/annotate.spec.ts`
|
|
6368
|
+
on Chromium, WebKit and Firefox (a touch screen, and Pixel 5 or iPhone 13): "on touch, a marker
|
|
6369
|
+
takes a tap a few px off its bubble (44 by 44), after the page scrolled itself…" (11 px below and
|
|
6370
|
+
above, 4 px beside, after a `scrollBy`, nothing heard by the content, 30 px off the page's own
|
|
6371
|
+
tap); "…two markers' 44 px boxes overlap, a tap is the nearest bubble's"; "a paragraph's marker
|
|
6372
|
+
pinned at the frame's top… takes a mouse click and a tap where it is drawn" (at its drawn
|
|
6373
|
+
pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
|
|
6374
|
+
with no touch and on a touch screen after a finger).
|
package/docs/DESIGN.md
CHANGED
|
@@ -1085,7 +1085,14 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1085
1085
|
moves over it, are stopped in the shell's first window listener, read through the
|
|
1086
1086
|
platform's own functions kept before content runs (P105), and a trusted click is
|
|
1087
1087
|
reported `activated`; a tap too, on WebKit as well, since each marker has a click
|
|
1088
|
-
listener of its own (WebKit makes a tap a click only on such an element, P105).
|
|
1088
|
+
listener of its own (WebKit makes a tap a click only on such an element, P105). On
|
|
1089
|
+
touch (P119), while the last pointer down or moved was a finger or a pen (before any,
|
|
1090
|
+
where `(any-pointer: coarse)` matches), each marker also takes the pointer in a box of
|
|
1091
|
+
at least 44 by 44 px centred on its bubble (an invisible `::before` in the layer), the
|
|
1092
|
+
bubble itself unchanged; a press there is a press on the marker, and where two such
|
|
1093
|
+
boxes overlap it is the marker whose bubble's centre is nearest (on a bubble, that
|
|
1094
|
+
bubble). A mouse's move takes the boxes away, so a mouse is hit-tested on bubbles
|
|
1095
|
+
alone. Against content that patches none of the built-ins, none of
|
|
1089
1096
|
its handlers, nor what is under the marker, gets them; content that patches others
|
|
1090
1097
|
can reach the layer's nodes (P105). Either way the content can tell a press
|
|
1091
1098
|
happened, by `:active`, `relatedTarget` and user activation. Markers step aside
|
|
@@ -1439,10 +1446,10 @@ control the tables above name to the registry):
|
|
|
1439
1446
|
| `annotation-activated` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1440
1447
|
| `annotation-activated-count` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1441
1448
|
| `marker-trusted` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1442
|
-
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same` | — | — |
|
|
1449
|
+
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same`, `on touch, a marker takes a tap a few px off its bubble (44 by 44), after the page scrolled itself; a tap past that is the page's (P119)`, `on touch, where two markers' 44 px boxes overlap, a tap is the nearest bubble's (P119)`, `a paragraph's marker pinned at the frame's top once its start scrolled away takes a mouse click and a tap where it is drawn (P119, porthole#42)` | — | — |
|
|
1443
1450
|
| `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
|
|
1444
1451
|
| `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)` | — | — |
|
|
1445
|
-
| `marker-tap` | `annotate.spec.ts` | nothing | WebKit: `a tap on a marker is reported on every engine, and the content hears none of it (P105)` | no probe can see it on Chromium and Firefox: they make a tap a click on the marker without a listener of its own (measured, P105) |
|
|
1452
|
+
| `marker-tap` | `annotate.spec.ts` | nothing | WebKit: `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `on touch, a marker takes a tap a few px off its bubble (44 by 44), after the page scrolled itself; a tap past that is the page's (P119)`, `on touch, where two markers' 44 px boxes overlap, a tap is the nearest bubble's (P119)`, `a paragraph's marker pinned at the frame's top once its start scrolled away takes a mouse click and a tap where it is drawn (P119, porthole#42)` | no probe can see it on Chromium and Firefox: they make a tap a click on the marker without a listener of its own (measured, P105) |
|
|
1446
1453
|
| `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)` | — | — |
|
|
1447
1454
|
| `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` | — | — |
|
|
1448
1455
|
| `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` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.3 (2026-10-29). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -679,7 +679,12 @@ own frame, below the shell, P111), so:
|
|
|
679
679
|
`marker-prevent`), so content can't act on it or cancel it; nor can it read or reach inside the
|
|
680
680
|
shell's layer (a closed shadow root). Content can still tell that a marker was pressed, and
|
|
681
681
|
roughly where: the pointer leaving its own element names the layer, the layer matches `:hover`
|
|
682
|
-
and `:active`, and the frame gets user activation.
|
|
682
|
+
and `:active`, and the frame gets user activation. On touch (P119), a marker is also the
|
|
683
|
+
44 by 44 px box around its bubble, drawn in that same layer: a tap there is a press on the
|
|
684
|
+
marker, with the same checks (a trusted click, the main button, on the layer), so the content
|
|
685
|
+
loses a tap within 13 px of a bubble (a few px of its words above and below it), as it loses
|
|
686
|
+
one on the bubble. Which pointer is used is read from trusted pointer events only; a page that
|
|
687
|
+
makes its own up changes nothing, and a real `activated` still needs a real click.
|
|
683
688
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
684
689
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
685
690
|
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.3",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/shell/annotate.ts
CHANGED
|
@@ -1,3 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
|
|
10
|
+
const TARGET = 44;
|
|
11
|
+
let best = -1;
|
|
12
|
+
let nearest = 0;
|
|
13
|
+
for (let i = count - 1; i >= 0; i -= 1) {
|
|
14
|
+
const rect = boxAt(i);
|
|
15
|
+
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
16
|
+
return i;
|
|
17
|
+
}
|
|
18
|
+
if (touch) {
|
|
19
|
+
const dx = x - (rect.x + rect.width / 2);
|
|
20
|
+
const dy = y - (rect.y + rect.height / 2);
|
|
21
|
+
const halfWidth = (rect.width > TARGET ? rect.width : TARGET) / 2;
|
|
22
|
+
const halfHeight = (rect.height > TARGET ? rect.height : TARGET) / 2;
|
|
23
|
+
if (dx >= -halfWidth && dx <= halfWidth && dy >= -halfHeight && dy <= halfHeight) {
|
|
24
|
+
const distance = dx * dx + dy * dy;
|
|
25
|
+
if (best === -1 || distance < nearest) {
|
|
26
|
+
best = i;
|
|
27
|
+
nearest = distance;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return best;
|
|
33
|
+
}`;
|
|
34
|
+
|
|
1
35
|
/**
|
|
2
36
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
37
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -376,7 +410,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
376
410
|
// layer inherits from the page could reach it, so each of those is set here). A draft
|
|
377
411
|
// (P107) is a comment not yet posted: its line is dashed (an element's outline too) and its
|
|
378
412
|
// marker hollow, a light bubble with a dashed edge and the glyph's outline, no number.
|
|
379
|
-
|
|
413
|
+
// While the last pointer was a finger or a pen (P119), each marker takes the pointer in a
|
|
414
|
+
// box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
|
|
415
|
+
// box, its border 1 px), so a tap a few px off still lands on the shell's layer.
|
|
416
|
+
const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
|
|
380
417
|
// Inline and important: the content's own style sheets can't hide, shrink or move it by
|
|
381
418
|
// accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
|
|
382
419
|
// content can still cover the layer, or move it with its ancestors, P104).
|
|
@@ -404,6 +441,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
404
441
|
// marker's node across draws, so a press that spans a redraw ends on the node it began on.
|
|
405
442
|
let markers = [];
|
|
406
443
|
const markerNodes = new Map();
|
|
444
|
+
// Whether the last pointer was a finger or a pen (P119): then each marker takes the pointer
|
|
445
|
+
// in a 44 px box around it (the markers' box has the class "touch"). Until a pointer is
|
|
446
|
+
// seen, whether the device has a coarse pointer at all (a phone, a tablet, a laptop with a
|
|
447
|
+
// touch screen): a mouse moves before it presses, and its first move turns it off.
|
|
448
|
+
const coarseQuery = typeof window.matchMedia === "function" ? window.matchMedia("(any-pointer: coarse)") : null;
|
|
449
|
+
let touch = coarseQuery !== null && coarseQuery.matches === true;
|
|
450
|
+
const markerHit = ${MARKER_HIT};
|
|
407
451
|
const MARKER_HEIGHT = 18;
|
|
408
452
|
const SVG = "http://www.w3.org/2000/svg";
|
|
409
453
|
const labelOf = (count) => (count === 0 ? "" : count > 99 ? "99+" : String(count));
|
|
@@ -714,6 +758,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
714
758
|
if (boxes.style.textContent !== STYLE) {
|
|
715
759
|
boxes.style.textContent = STYLE;
|
|
716
760
|
}
|
|
761
|
+
if (boxes.markers.className !== (touch ? "touch" : "")) {
|
|
762
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
763
|
+
}
|
|
717
764
|
return boxes;
|
|
718
765
|
};
|
|
719
766
|
const draw = () => {
|
|
@@ -1118,14 +1165,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1118
1165
|
const rect = callOf(elementRect, element, []);
|
|
1119
1166
|
return { x: callOf(leftOf, rect, []), y: callOf(topOf, rect, []), width: callOf(widthOf, rect, []), height: callOf(heightOf, rect, []) };
|
|
1120
1167
|
};
|
|
1168
|
+
// The marker a press at (x, y) is for: on a marker's own box, that one; after a finger or a
|
|
1169
|
+
// pen, also within the 44 px box around one, the nearest (P119).
|
|
1121
1170
|
const markerAt = (x, y) => {
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
1125
|
-
return markers[i];
|
|
1126
|
-
}
|
|
1127
|
-
}
|
|
1128
|
-
return null;
|
|
1171
|
+
const at = markerHit(markers.length, (i) => markerBox(markers[i].element), x, y, touch);
|
|
1172
|
+
return at < 0 ? null : markers[at];
|
|
1129
1173
|
};
|
|
1130
1174
|
const isShown = (id) => {
|
|
1131
1175
|
for (let i = 0; i < marks.length; i += 1) {
|
|
@@ -1170,6 +1214,28 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1170
1214
|
const CANCELLED = { mousedown: 1, mouseup: 1, click: 1, dblclick: 1, auxclick: 1, contextmenu: 1 };
|
|
1171
1215
|
// The pointer on a marker (1), or leaving the layer for the content (0).
|
|
1172
1216
|
const HOVERS = { pointerover: 1, pointermove: 1, pointerout: 0, pointerleave: 0 };
|
|
1217
|
+
// Which pointer the person uses (P119), from each real one that goes down or moves, before
|
|
1218
|
+
// the marker's listener (which stops a press on the layer): a finger or a pen gives every
|
|
1219
|
+
// marker its 44 px box, a mouse takes it away. A mouse moves before it presses, so its press
|
|
1220
|
+
// is hit-tested on the markers' own boxes. Read through the platform's getter, kept now; an
|
|
1221
|
+
// event the page makes up (isTrusted is false) changes nothing.
|
|
1222
|
+
const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
|
|
1223
|
+
const onPointer = (event) => {
|
|
1224
|
+
if (!event.isTrusted || pointerTypeOf === null) {
|
|
1225
|
+
return;
|
|
1226
|
+
}
|
|
1227
|
+
const kind = callOf(pointerTypeOf, event, []);
|
|
1228
|
+
const next = kind === "touch" || kind === "pen";
|
|
1229
|
+
if (next !== touch) {
|
|
1230
|
+
touch = next;
|
|
1231
|
+
if (boxes !== null) {
|
|
1232
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
1233
|
+
}
|
|
1234
|
+
}
|
|
1235
|
+
};
|
|
1236
|
+
for (const type of ["pointerdown", "pointermove"]) {
|
|
1237
|
+
window.addEventListener(type, onPointer, true);
|
|
1238
|
+
}
|
|
1173
1239
|
for (const type of ["pointerdown", "pointerup", "pointercancel", "mousedown", "mouseup", "click", "dblclick", "auxclick", "contextmenu", "touchstart", "touchend", "touchcancel", "pointerover", "pointerout", "pointerenter", "pointerleave", "pointermove", "mouseover", "mouseout", "mouseenter", "mouseleave", "mousemove"]) {
|
|
1174
1240
|
window.addEventListener(type, onMarker, true);
|
|
1175
1241
|
}
|