@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.
@@ -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
@@ -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
- 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}.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}";
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
- for (let i = markers.length - 1; i >= 0; i -= 1) {
1123
- const rect = markerBox(markers[i].element);
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). Against content that patches none of the built-ins, none of
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` | — | — |
@@ -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.2 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
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.2",
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": {
@@ -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
- 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}.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}";
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
- for (let i = markers.length - 1; i >= 0; i -= 1) {
1123
- const rect = markerBox(markers[i].element);
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
  }