@botiverse/porthole 0.12.0 → 0.13.0

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.
Files changed (47) hide show
  1. package/dist/bridge/bridge.d.ts +8 -1
  2. package/dist/bridge/bridge.js +7 -0
  3. package/dist/bridge/unseen.d.ts +8 -0
  4. package/dist/bridge/unseen.js +17 -0
  5. package/dist/check/files.js +14 -10
  6. package/dist/check/lint.js +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/scroll.d.ts +29 -13
  9. package/dist/check/scroll.js +74 -18
  10. package/dist/config/capabilities.d.ts +16 -3
  11. package/dist/config/capabilities.js +1 -0
  12. package/dist/conformance/harness-source.js +1 -1
  13. package/dist/guide/runtime.js +1 -1
  14. package/dist/host/create-host.js +27 -0
  15. package/dist/host/types.d.ts +15 -0
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.js +1 -0
  18. package/dist/platform/focus-guard.d.ts +143 -0
  19. package/dist/platform/focus-guard.js +445 -0
  20. package/dist/platform/types.d.ts +18 -0
  21. package/dist/platform/web.js +22 -0
  22. package/dist/react/frame.d.ts +8 -0
  23. package/dist/react/frame.js +4 -0
  24. package/dist/runtime/requests.js +34 -12
  25. package/dist/runtime/types.generated.js +1 -1
  26. package/docs/ADOPTING.md +85 -6
  27. package/docs/DECISIONS.md +355 -5
  28. package/docs/DESIGN.md +9 -2
  29. package/docs/THREAT_MODEL.md +121 -29
  30. package/package.json +1 -1
  31. package/src/bridge/bridge.ts +17 -1
  32. package/src/bridge/unseen.ts +24 -0
  33. package/src/check/files.ts +14 -10
  34. package/src/check/lint.ts +1 -1
  35. package/src/check/scroll.ts +106 -38
  36. package/src/config/capabilities.ts +16 -3
  37. package/src/guide/runtime.ts +1 -1
  38. package/src/host/create-host.ts +29 -0
  39. package/src/host/types.ts +13 -0
  40. package/src/index.ts +1 -0
  41. package/src/platform/focus-guard.ts +572 -0
  42. package/src/platform/types.ts +17 -0
  43. package/src/platform/web.ts +22 -0
  44. package/src/react/frame.tsx +10 -0
  45. package/src/runtime/requests.ts +36 -14
  46. package/src/runtime/types.generated.ts +1 -1
  47. package/types/runtime/v1/comments.d.ts +8 -4
@@ -5,13 +5,18 @@ 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.12.0 (2026-10-26). A review on 2026-10-19 found gaps, and every
9
- decision it led to has merged. P096 changed the negative-control runner and CI, and the shipped
10
- conformance probes' messages and timing, not what they check. P104 (0.9.0's annotation markers) had
11
- a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 adds draft marks (P107, §7
12
- "Drafts": what a page learns from them and who may receive them) and an advisory lint (P106, no
13
- change to isolation). 0.12.0 lets `comments.open` carry a draft (P108, §7: visible text only, and
14
- the host's duties around it). [§8](#8-fixes-in-flight) lists the decisions.
8
+ **Status.** This describes Porthole 0.13.0 (2026-10-27). A review on 2026-10-19 found gaps, and every decision it led to
9
+ has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
+ and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
+ annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
12
+ never published (its release stopped at the CI gate), and 0.12.0 carries all of it: draft marks
13
+ (P107, §7 "Drafts": what a page learns from them and who may receive them), an advisory lint
14
+ (P106, no change to isolation), and `comments.open` with a draft (P108, §7: the host's duties
15
+ around it). The review of 0.12.0's drafts led to P109, in 0.13.0: a display can take the keyboard, which
16
+ `createHost` now gives back (§6, §7 "The keyboard"); `comments.open` needs the person in the
17
+ calling frame; a page's draft text is stricter, and the composer it fills is the person's to act
18
+ on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P110, no change to
19
+ isolation).
15
20
 
16
21
  ## 1. Two layers
17
22
 
@@ -153,10 +158,19 @@ Whatever the use:
153
158
  second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
154
159
  appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
155
160
  themselves on a release), ignores a press that began before that, opens beside the frame rather
156
- than over the report's box where the layout allows, takes no focus when it opens, and puts no
157
- destructive action (resolve, delete) one click away. Its menus and popovers are part of it,
158
- portaled ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it
159
- arms).
161
+ than over the report's box where the layout allows, takes no focus when it opens, and puts
162
+ nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
163
+ included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
164
+ ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
165
+ - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
166
+ likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
167
+ `createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
168
+ fields for a frame without the person's press on the frame or a Tab, tells the display
169
+ (`focusTaken`), and stops a display that keeps doing it (§7 "The keyboard", P109). Move focus
170
+ into a display yourself with `display.focus()`, never the frame's own `focus()`; move it into
171
+ your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
172
+ a fighting frame holds focus); and with a platform of your own, implement its focus guard
173
+ (`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
160
174
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
161
175
  and only those are checked against the content domain for a shared site.
162
176
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -548,7 +562,8 @@ its realm with the content, so:
548
562
  where the content can listen: each mark's id, anchor and, where given, `count` (the number on
549
563
  its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
550
564
  a count only where the page may know how many there are. Who commented and what they wrote stay
551
- in the host's own UI, outside the frame.
565
+ in the host's own UI, outside the frame, and so does what the person types there, within the
566
+ keyboard's limits below (P109).
552
567
  - *Drafts* (P107). A mark with `kind: "draft"` (a comment its author hasn't posted) is drawn apart,
553
568
  a dashed line and a hollow marker with no number, so the page also learns which of its marks are
554
569
  drafts: that the person viewing it is writing a comment there, before they post it. That is new
@@ -566,7 +581,9 @@ its realm with the content, so:
566
581
  app runtime below). A host that sends drafts to such a page accepts that its author and other viewers can
567
582
  learn of them. A draft carries nothing else: the host drops its count before the frame (control
568
583
  `draft-count`), so a page can't read how many drafts are at an anchor unless the host sends a
569
- mark per draft, and its id is the host's, as any mark's (random, never the draft's words). A host
584
+ mark per draft, and its id is the host's, as any mark's (random, never the draft's words); the
585
+ draft's words are typed into the host's composer, which the page can try to take the keyboard
586
+ from ("The keyboard" below). A host
570
587
  that sends drafts into a frame others see (a shared screen, a frame several viewers share) tells
571
588
  that page, and anything it draws for them, what its author hasn't posted.
572
589
  - *What content can fake.* Any report: a selection while the host asks for one, where marks are,
@@ -628,8 +645,53 @@ its realm with the content, so:
628
645
  follow-up reports, of the marks (while one has a marker) and of the person's selection after a
629
646
  scroll, share one clock: at most one a second together, each only when its box moved (P105).
630
647
  - So `activated` opens the host's own view of a mark it already shows, placed within the frame's
631
- box (better: beside it), guarded as §6 says, and never acts on it (no resolve, delete or reply);
632
- an anchor or a rect decides where something is drawn, never who may see or do anything.
648
+ box (better: beside it), guarded as §6 says, and never acts on it (no post, submit, discard,
649
+ resolve, delete or reply); an anchor or a rect decides where something is drawn, never who may
650
+ see or do anything.
651
+
652
+ **The keyboard** (P109). Any display, of any kind and any version, can move the keyboard into its
653
+ frame: `element.focus()` runs in the content's realm, where nothing of Porthole can stop it, and on
654
+ Chromium and WebKit it needs no gesture. What the person goes on typing then goes to the page,
655
+ which can keep it (`db`) or send it out through any egress it has. The page knows when it matters:
656
+ its shell reports `selected` when the host opens a composer on it, and draft marks (P107) say
657
+ where the person is writing. P107 and P108 didn't make this possible; they put the person's
658
+ unposted words beside the frame and tell the page when.
659
+
660
+ - *What holds* (the web platform's focus guard, in every `createHost` display): when focus leaves
661
+ one of the host page's text fields (a text area, an `<input>` that takes text, an editable region,
662
+ in open shadow roots too) for a display's frame, and the person didn't move it there, focus goes
663
+ back to the field once the engine has finished the move, the guard watches that it stays there
664
+ (a page that takes it again on its own blur, which the take-back fires, is caught, as is focus
665
+ left on nothing), and the display hears `focusTaken`. Three such moves within 10 s that came while
666
+ the person typed or that kept focus from staying back, or five within 2 s, stop the display. The
667
+ person moved it if they pressed Tab just before; pressed the frame (on Chromium and WebKit the
668
+ frame element is `:active` as focus moves; on Firefox, which doesn't blur the window or show the
669
+ press, the pointer came over the frame after the field got focus and after the person last
670
+ typed); made a gesture the host's own events don't explain (the page has activation, but no
671
+ key, press or click of its own for longer than activation lasts, and the field has had focus that
672
+ long: a press or an assistive technology's activation in a frame); or the host moved it
673
+ (`display.focus()`).
674
+ Measured on all three engines: a page calling `focus()` every 700 ms down to a busy loop, or
675
+ taking focus back on its own blur, while the person types a sentence gets no key of it on
676
+ Chromium and WebKit and at most one on Firefox before it is stopped or gives up (negative
677
+ controls `focus-guard`, and `focus-guard-watch` on Firefox); a press on the page's own field, a
678
+ Tab into the frame, and an activation in the frame that sends the host no event keep the
679
+ keyboard there. `comments.open` needs that focus in the calling frame, moved there by the
680
+ person, and not just after a press on the host's page (the app runtime, below).
681
+ - *What doesn't*: a page gets the keys typed before focus is back (on Firefox, the keys of an
682
+ animation frame: one in a sentence, measured on a slowed machine too; a few more can be lost to
683
+ nothing while a take-back is fought, and the composer then has focus again); on Firefox a host's plain
684
+ `focus()` doesn't move focus from a frame that holds it with the person's gesture and takes it
685
+ back on its blur (no focus event: the keys go to the frame), so a composer that opens focused
686
+ must use `focusField`; on Firefox a page keeps the keyboard if the pointer came over its frame after
687
+ the person last typed and after the field got focus (a person who typed, moved the pointer over
688
+ the frame, and types on without clicking); moves between two frames, or from what isn't a text
689
+ field, aren't judged (a frame beside another: S7); and a platform of the host's own has no guard
690
+ unless it implements one. The guard can take a person's own move for the page's (a press on
691
+ Firefox with the pointer resting over the frame since before the field got focus; an assistive
692
+ technology's activation within 5 s of their key or press on the page): focus goes back, and
693
+ their next press once the pointer has left the frame and come back, a Tab, or an activation 5 s
694
+ later keeps it.
633
695
 
634
696
  ### The app runtime
635
697
 
@@ -662,10 +724,19 @@ section.
662
724
  code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
663
725
  only while the config still lets uploaded code run, asked at every load, in bearer mode too
664
726
  (where every artifact config must; P103); anything else is a download.
665
- - `comments` is write-only: the page learns only whether the composer opened. A draft it gives
666
- (P108) is at most 2,000 characters of text a person can see: no zero-width, bidi or tag
667
- characters, no controls but a new line and a tab (P100's `unseen`); anything else is refused
668
- before the handler.
727
+ - `comments` is write-only: the page learns only whether the composer opened. It opens only from
728
+ a gesture with the host page's focus in the calling frame (P109: a press in it or a Tab into it;
729
+ not the person typing in the host's UI, nor a gesture in another display; negative control
730
+ `comments-in-frame`). A draft it gives (P108) is at most 2,000 characters of text a person can
731
+ see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
732
+ new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
733
+ Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
734
+ emoji sequence; a variation selector after a pictograph is fine), no line or paragraph
735
+ separator, not blank-looking, at most 32 blanks in a row and two blank lines in a row; anything
736
+ else is refused before the handler. A joiner between two letters that shapes nothing still
737
+ draws as nothing (about a bit per letter boundary, measured): accepted, as P100 accepts it. The anchor's
738
+ label and quote reach the handler without what a person can't see, and are refused if nothing
739
+ visible is left.
669
740
  - `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
670
741
  `artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
671
742
 
@@ -682,11 +753,28 @@ section.
682
753
  (`Refused("conflict")`).
683
754
  - Handle abuse on shared pages (S4).
684
755
  - Show a comment's draft (P108) whole, as the person's editable plain text in its own composer,
685
- and post it only on the person's own Send, never on the page's word. A composer that opens with
686
- a draft is a view the content brought (§6's guard): it takes no press, and no Enter that sends,
687
- for 500 ms after it opens, doesn't focus Send, and opens beside the frame where it can. Once
688
- posted, the comment is the person's: mentions in it act as theirs, which is why they must see
689
- it all first.
756
+ and post it only on the person's own Send, never on the page's word. Once posted, the comment is
757
+ the person's: mentions in it act as theirs, which is why they must see it all first. So (P109;
758
+ ADOPTING.md has the code):
759
+ - An open never replaces, appends to or moves what the person has typed, or the place they
760
+ chose: while the composer holds their words, answer `false`, or show the page's words as a
761
+ separate suggestion that takes no focus. (The page knows they are writing anyway: its
762
+ `selected`, and draft marks.)
763
+ - A composer the page filled takes no focus when it opens (keys stay where the person was
764
+ typing: what they type for the page must not land in a postable comment), and doesn't send on
765
+ Enter until the person has focused or edited it themselves: Send is a click until then. It is
766
+ a view the content brought (§6's guard): no press for 500 ms after it opens, Send not focused,
767
+ beside the frame where it can.
768
+ - It says the text is the page's ("Suggested by this page", or the page's name), drawn by the
769
+ host outside the frame, until the person edits it, and never shows it as one of their own
770
+ drafts: the host's own list of drafts is how a person finds theirs, not the frame's markers,
771
+ which a page can draw too.
772
+ - The draft's view (P107) and the composer put nothing one click away that posts, submits or
773
+ discards.
774
+ - Render a page-drafted comment as plain text, or show the person before Send what readers will
775
+ see: markup a markdown renderer hides (an HTML comment, a link definition) is still read by an
776
+ agent. Show the anchor's label and quote as isolated text (`<bdi>`, `dir="auto"`), and hand
777
+ them to a model only as the page's words.
690
778
 
691
779
  **Not guaranteed**
692
780
 
@@ -697,14 +785,18 @@ section.
697
785
  - In bearer mode, assets are served by id alone, without the host's check.
698
786
  - A draft is the page's words in the person's composer: a person who posts it without reading
699
787
  posts what the page chose, and an agent that reads the comment takes it as theirs. Porthole
700
- bounds what can hide in it (visible text, 2,000 characters, a click to open); reading it is the
701
- person's.
788
+ bounds what can hide in it (visible text, 2,000 characters) and when it opens (a gesture with the
789
+ person in the calling frame, P109: before P109, any gesture on the host's page in the last 5 s,
790
+ typing in its own composer included); reading it is the person's. A page can still open the
791
+ composer on the person's own press in its frame, at a moment it chooses (the second click of a
792
+ double click, a field it asked them to type into): the composer's duties above are the bound.
702
793
 
703
794
  ## 8. Fixes in flight
704
795
 
705
- The decisions below come from the 2026-10-19 review. "Planned" means not in 0.9.0: the gap its
706
- row names exists today, and the sections it cites say "open until" that decision. Each merged row
707
- says what was wrong, what holds now, and the limit its decision accepts, if any.
796
+ The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
797
+ what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
798
+ are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
799
+ of 0.12.0's drafts).
708
800
 
709
801
  | Decision | State | What it closes | Sections |
710
802
  | --- | --- | --- | --- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
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": {
@@ -71,7 +71,8 @@ import type {
71
71
  * every capability its host function's own rate (P091, P095) → arguments well formed and within
72
72
  * their limits → who may (P087: the level of each method the call runs for the viewer, a page's
73
73
  * named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
74
- * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so → the
74
+ * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
75
+ * for `comments`, the host page's focus in the calling frame: P109) → the
75
76
  * viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
76
77
  * shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
77
78
  * gave for it, or for a stale-allowed one the host's cache).
@@ -106,6 +107,12 @@ export interface BridgeOptions {
106
107
  readonly cached?: DataCache;
107
108
  /** Whether the embedding page has user activation now; undefined where it can't tell. */
108
109
  readonly userActivation?: () => boolean | undefined;
110
+ /**
111
+ * Whether the embedding page's focus is in this display's frame now (P109); undefined where it
112
+ * can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
113
+ * without it.
114
+ */
115
+ readonly focused?: () => boolean | undefined;
109
116
  readonly onEvent: (event: BridgeEvent) => void;
110
117
  /** The clock, in milliseconds (tests pass their own). */
111
118
  readonly now?: () => number;
@@ -125,6 +132,10 @@ export interface BridgeOptions {
125
132
  const isRecord = (value: unknown): value is Record<string, unknown> =>
126
133
  value !== null && typeof value === "object" && !Array.isArray(value);
127
134
 
135
+ /** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
136
+ const inFrame = (capability: CapabilityName): boolean =>
137
+ capabilitySpec(capability).inFrame === true;
138
+
128
139
  const MAX_URL = 4_096;
129
140
 
130
141
  /**
@@ -653,6 +664,11 @@ export function createBridge(options: BridgeOptions): DisplayBridge {
653
664
  if (activated === false) {
654
665
  return refuse<Result>(capability, "no-user-activation");
655
666
  }
667
+ // A gesture in this frame, not anywhere on the host's page (P109): the person typing in
668
+ // the host's composer gives its page activation, which a frame's call would borrow.
669
+ if (inFrame(capability) && options.focused?.() === false) {
670
+ return refuse<Result>(capability, "no-user-activation");
671
+ }
656
672
  }
657
673
  if (gates.includes("consent")) {
658
674
  const consent = options.consent;
@@ -80,3 +80,27 @@ const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
80
80
  export function withoutUnseen(text: string): string {
81
81
  return text.replace(UNSEEN_EACH, "");
82
82
  }
83
+
84
+ /** A variation selector where an emoji has one: after a pictograph, or in a keycap. */
85
+ const EMOJI_SELECTORS = new RegExp(
86
+ "(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)",
87
+ "gu",
88
+ );
89
+
90
+ /**
91
+ * A joiner or non-joiner with a letter or mark on each side (P109): how Persian separates its
92
+ * letters (می‌خواهم) and the Indic scripts choose a half form or a conjunct (क्‍ष, എന്‍റെ). Never
93
+ * first or last, doubled, beside a space, punctuation or a pictograph: there it shapes nothing, and
94
+ * hides text or makes a blank-looking draft.
95
+ */
96
+ const LETTER_JOINERS = /(?<=[\p{L}\p{M}])[\u200C\u200D](?=[\p{L}\p{M}])/gu;
97
+
98
+ /**
99
+ * Whether `text` holds what a person can't see, for text a page puts in the person's own words (a
100
+ * comment's draft, P109): `unseen`'s list, with only a joiner or non-joiner between two letters or
101
+ * marks let by (in any script: a person's text needs them, and one that draws as nothing there is
102
+ * a bit at most), and a variation selector right after a pictograph or in a keycap (❤️, 1️⃣). A
103
+ * joiner between pictographs (an emoji sequence) is refused: it can join any two.
104
+ */
105
+ export const unseenStrict = (text: string): boolean =>
106
+ UNSEEN.test(text.replace(LETTER_JOINERS, "").replace(EMOJI_SELECTORS, ""));
@@ -272,8 +272,10 @@ export function lintFiles(
272
272
  }
273
273
  }
274
274
  };
275
- // A stylesheet a page links or a stylesheet imports, found in the set by its path (P106).
276
- const decoded = new Map<string, string>();
275
+ // A stylesheet a page links or a stylesheet imports, found in the set by its path (P106). The
276
+ // fewest characters it may hold first: the rule decodes its text only where it may read it, and
277
+ // nothing keeps it after (P110: kept for the set, one page linking 400 sheets of 240 KB held
278
+ // them all, 200 MB, for the 4 MiB the rule reads).
277
279
  const stylesheet: LinkedSheet = (href, from) => {
278
280
  if (href === "" || elsewhere(href) || href.startsWith("/")) {
279
281
  return null;
@@ -283,13 +285,15 @@ export function lintFiles(
283
285
  if (sheet === undefined || target === null) {
284
286
  return null;
285
287
  }
286
- // Decoded once for the whole set, however many pages link it.
287
- let text = decoded.get(target);
288
- if (text === undefined) {
289
- text = textOf(sheet).slice(0, SCANNED);
290
- decoded.set(target, text);
291
- }
292
- return { path: target, text };
288
+ // As bytes, at most 3 a character (after a BOM's 3): its fewest characters, and the bytes that
289
+ // hold its first SCANNED.
290
+ return typeof sheet === "string"
291
+ ? { path: target, least: sheet.length, text: () => sheet }
292
+ : {
293
+ path: target,
294
+ least: Math.max(0, Math.ceil(sheet.byteLength / 3) - 1),
295
+ text: () => textOf(sheet.subarray(0, 3 * SCANNED + 3)),
296
+ };
293
297
  };
294
298
  const it = config.mode === "mcp-app" ? "view" : config.mode === "inline" ? "widget" : "page";
295
299
  const maxPage = config.limits.maxBytes;
@@ -378,7 +382,7 @@ export function lintFiles(
378
382
  severity: "warning",
379
383
  message: held.message,
380
384
  path: held.path ?? path,
381
- line: held.line,
385
+ ...(held.line === undefined ? {} : { line: held.line }),
382
386
  });
383
387
  }
384
388
  }
package/src/check/lint.ts CHANGED
@@ -295,7 +295,7 @@ export function lintPage(
295
295
  rule: "scroll-lock",
296
296
  severity: "warning",
297
297
  message: held.message,
298
- line: held.line,
298
+ ...(held.line === undefined ? {} : { line: held.line }),
299
299
  });
300
300
  }
301
301
  const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);
@@ -12,7 +12,9 @@ import { attributesOf } from "./markup.ts";
12
12
  * - body with overflow-y hidden or clip, where html's overflow is visible (body's then becomes the
13
13
  * viewport's) or body is one screen tall;
14
14
  * - the root with overflow-y hidden or clip and one screen tall;
15
- * - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing);
15
+ * - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing), and
16
+ * body fixed whatever its height, unless it scrolls itself (where html's overflow is visible,
17
+ * body's is the viewport's and body itself doesn't: P110);
16
18
  * and nothing in the page's markup below body that scrolls itself: no element there with style=""
17
19
  * or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
18
20
  * that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
@@ -28,7 +30,8 @@ import { attributesOf } from "./markup.ts";
28
30
  * and bottom set (`inset: 0`).
29
31
  *
30
32
  * What it reads: the page's `<style>` elements, the stylesheets it links that the caller finds
31
- * (a version's own files) and what they `@import`, in document order; style="" on the three; the
33
+ * (a version's own files) and what they `@import`, in document order; style="" on body and the
34
+ * root (not html's: the shell drops it, P110); the
32
35
  * class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
33
36
  * Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
34
37
  * order, !important and cascade layers decide between rules, so a later override is seen.
@@ -43,7 +46,8 @@ import { attributesOf } from "./markup.ts";
43
46
  *
44
47
  * Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
45
48
  * rule it is in, a rule's selectors one at a time), at most `SHEETS` of them and `READ` bytes in
46
- * all, its own `<style>` included; past that, the rest isn't read. At most `MOST_LAYERS` layers a
49
+ * all, its own `<style>` included; past that, the rest isn't read, nor asked for, and a sheet is
50
+ * decoded only once its size is taken (P110). At most `MOST_LAYERS` layers a
47
51
  * page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
48
52
  * element keeps, per property, only each layer's winner so far, and a compound is matched against
49
53
  * an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
@@ -57,19 +61,25 @@ import { attributesOf } from "./markup.ts";
57
61
  * selector).
58
62
  */
59
63
 
60
- /** A stylesheet the page links, as the caller finds it from `from` (a path), or null. */
64
+ /**
65
+ * A stylesheet the page links, as the caller finds it from `from` (a path), or null: its path, the
66
+ * fewest characters it may hold (`least`: a string's length; as bytes, a third of them, less a
67
+ * BOM's), and its text (at least its first `SCANNED` characters), decoded only where the rule may
68
+ * read it (P110: one page linking 400 sheets decoded and kept all of them, though the rule reads at
69
+ * most `SHEETS`, `READ` characters in all).
70
+ */
61
71
  export type LinkedSheet = (
62
72
  href: string,
63
73
  from: string,
64
- ) => { readonly path: string; readonly text: string } | null;
74
+ ) => { readonly path: string; readonly least: number; readonly text: () => string } | null;
65
75
 
66
76
  export interface ScrollLock {
67
77
  /** What to change, for the agent. */
68
78
  readonly message: string;
69
79
  /** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
70
80
  readonly path?: string;
71
- /** Its line (1-based). */
72
- readonly line: number;
81
+ /** Its line (1-based); none where the page couldn't be checked (P110). */
82
+ readonly line?: number;
73
83
  }
74
84
 
75
85
  /** How much of one stylesheet is read: its first 2 MiB. */
@@ -575,7 +585,11 @@ function identAt(text: string, at: number): { value: string; end: number } | nul
575
585
  if (code === "\\") {
576
586
  const hex = /^[0-9a-f]{1,6}\s?/iu.exec(text.slice(index + 1, index + 8));
577
587
  if (hex !== null) {
578
- value += String.fromCodePoint(Number.parseInt(hex[0].trim(), 16) || 0xfffd);
588
+ // CSS Syntax's "consume an escaped code point": 0, a surrogate or past U+10FFFF is U+FFFD
589
+ // (six hex digits reach 0xFFFFFF, which String.fromCodePoint throws on: P110).
590
+ const point = Number.parseInt(hex[0].trim(), 16);
591
+ const valid = point !== 0 && point <= 0x10ffff && (point < 0xd800 || point > 0xdfff);
592
+ value += String.fromCodePoint(valid ? point : 0xfffd);
579
593
  index += 1 + hex[0].length;
580
594
  } else if (index + 1 < text.length) {
581
595
  value += text[index + 1];
@@ -875,8 +889,8 @@ const tooDeep = (name: string): string | null => {
875
889
  return null;
876
890
  };
877
891
 
878
- /** A stylesheet found for the page, once: its path and text. */
879
- type Found = { readonly path: string; readonly text: string } | null;
892
+ /** A stylesheet found for the page, once: its path, its fewest characters, its text when read. */
893
+ type Found = ReturnType<LinkedSheet>;
880
894
 
881
895
  /** The cascade over the chain: each declaration that matches, then the one that wins. */
882
896
  class Cascade {
@@ -979,18 +993,39 @@ class Cascade {
979
993
  return true;
980
994
  }
981
995
 
982
- /** Whether a stylesheet may still be read for this page (once, within the budget). */
983
- take(found: Found): found is { path: string; text: string } {
996
+ /**
997
+ * Whether nothing more may be read for this page: `SHEETS` read, `READ` spent, or the version's
998
+ * budget. Then no sheet is asked for (P110).
999
+ */
1000
+ full(): boolean {
1001
+ return this.read.size >= SHEETS || this.bytes >= READ || this.budget.spent;
1002
+ }
1003
+
1004
+ /**
1005
+ * A stylesheet's first `SCANNED` characters, if it may still be read for this page (once, within
1006
+ * the budget), else null. The caps count characters, whatever the caller gives: where even its
1007
+ * fewest are past what's left, it is refused before it is decoded (past the version's budget,
1008
+ * spent); else it is decoded, cut, and charged what it holds, or dropped if that doesn't fit.
1009
+ */
1010
+ take(found: Found): string | null {
984
1011
  if (found === null || this.read.has(found.path) || this.read.size >= SHEETS) {
985
- return false;
1012
+ return null;
986
1013
  }
987
- const size = Math.min(found.text.length, SCANNED);
988
- if (this.bytes + size > READ || !this.spend(size)) {
989
- return false;
1014
+ const least = Math.min(found.least, SCANNED);
1015
+ if (this.bytes + least > READ) {
1016
+ return null;
1017
+ }
1018
+ if (this.budget.spent || least > this.budget.bytes) {
1019
+ this.budget.spent = true;
1020
+ return null;
1021
+ }
1022
+ const text = found.text().slice(0, SCANNED);
1023
+ if (this.bytes + text.length > READ || !this.spend(text.length)) {
1024
+ return null;
990
1025
  }
991
1026
  this.read.add(found.path);
992
- this.bytes += size;
993
- return true;
1027
+ this.bytes += text.length;
1028
+ return text;
994
1029
  }
995
1030
 
996
1031
  /**
@@ -1146,12 +1181,19 @@ class Cascade {
1146
1181
  take(to);
1147
1182
  }
1148
1183
 
1149
- /** A stylesheet the page links or a sheet imports, if it may still be read. */
1150
- file(found: Found, layer: string | null) {
1151
- if (!this.take(found)) {
1184
+ /**
1185
+ * A stylesheet the page links or a sheet imports (`href`, from `from`), if it may still be read:
1186
+ * asked for only while the page may read more, decoded only once taken.
1187
+ */
1188
+ file(href: string, from: string, layer: string | null) {
1189
+ if (this.full()) {
1190
+ return;
1191
+ }
1192
+ const found = this.find(href, from);
1193
+ const text = this.take(found);
1194
+ if (found === null || text === null) {
1152
1195
  return;
1153
1196
  }
1154
- const text = found.text.slice(0, SCANNED);
1155
1197
  this.sheet(withoutComments(text), 0, text.length, {
1156
1198
  source: { path: found.path, text },
1157
1199
  base: 0,
@@ -1311,7 +1353,7 @@ class Cascade {
1311
1353
  return;
1312
1354
  }
1313
1355
  }
1314
- this.file(this.find(href, context.from), layer);
1356
+ this.file(href, context.from, layer);
1315
1357
  }
1316
1358
  }
1317
1359
 
@@ -1362,20 +1404,33 @@ interface Hold {
1362
1404
  readonly at: Value;
1363
1405
  }
1364
1406
 
1407
+ interface ScrollOptions {
1408
+ readonly noun: string;
1409
+ readonly path?: string;
1410
+ readonly sheet?: LinkedSheet;
1411
+ /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
1412
+ readonly budget?: ScrollBudget;
1413
+ }
1414
+
1365
1415
  /**
1366
1416
  * Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
1367
1417
  * don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
1418
+ * Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
1419
+ * line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
1420
+ * `admitFiles` in 0.11).
1368
1421
  */
1369
- export function scrollLock(
1370
- page: string,
1371
- options: {
1372
- readonly noun: string;
1373
- readonly path?: string;
1374
- readonly sheet?: LinkedSheet;
1375
- /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
1376
- readonly budget?: ScrollBudget;
1377
- },
1378
- ): ScrollLock | null {
1422
+ export function scrollLock(page: string, options: ScrollOptions): ScrollLock | null {
1423
+ try {
1424
+ return readScrollLock(page, options);
1425
+ } catch {
1426
+ return {
1427
+ message: `The ${options.noun} wasn't checked for scroll lock: its styles couldn't be read. If it holds html, body or its root to one screen (overflow: hidden with height: 100% or 100vh, or position: fixed), let it scroll as a document.`,
1428
+ ...(options.path === undefined ? {} : { path: options.path }),
1429
+ };
1430
+ }
1431
+ }
1432
+
1433
+ function readScrollLock(page: string, options: ScrollOptions): ScrollLock | null {
1379
1434
  const shared = options.budget ?? { bytes: Infinity, steps: Infinity, spent: false };
1380
1435
  if (shared.spent) {
1381
1436
  return null;
@@ -1400,7 +1455,9 @@ export function scrollLock(
1400
1455
  };
1401
1456
  };
1402
1457
  const chain: Node[] = [
1403
- nodeOf(scanned.html, "html", "html", false),
1458
+ // Not html's style="": the shell imports a page's html attributes but that one
1459
+ // (`renderDocument`), so it never applies in Porthole's frame (P110).
1460
+ { ...nodeOf(scanned.html, "html", "html", false), style: null },
1404
1461
  nodeOf(scanned.body, "body", "body", false),
1405
1462
  ];
1406
1463
  const rootTag =
@@ -1461,7 +1518,7 @@ export function scrollLock(
1461
1518
  ) {
1462
1519
  continue;
1463
1520
  }
1464
- cascade.file(find(href, from), null);
1521
+ cascade.file(href, from, null);
1465
1522
  }
1466
1523
  for (const node of chain) {
1467
1524
  if (node.style !== null) {
@@ -1604,7 +1661,10 @@ export function scrollLock(
1604
1661
  }
1605
1662
  const height = tall("height");
1606
1663
  const maxHeight = tall("max-height");
1607
- if (positioned && position !== undefined && (spanned || height || maxHeight)) {
1664
+ // A fixed body holds the page whatever its height (P110): a fixed box adds nothing to what the
1665
+ // frame scrolls, so `body { position: fixed; top: 0 }`, the scroll-lock libraries' way, does.
1666
+ const fixedBody = index === 1 && position?.value === "fixed";
1667
+ if (positioned && position !== undefined && (spanned || height || maxHeight || fixedBody)) {
1608
1668
  shown.unshift(position);
1609
1669
  }
1610
1670
  states.push({ screen: height || maxHeight || spanned, shown, position: position?.value ?? "" });
@@ -1628,11 +1688,16 @@ export function scrollLock(
1628
1688
  return found !== undefined && !CONTENT_HEIGHT.test(found) && !PARENT.test(found);
1629
1689
  });
1630
1690
  };
1691
+ // An element's own overflow-y: body's is the viewport's where html's overflow is visible, and
1692
+ // body's own is then visible (P110: `body { position: fixed; inset: 0; overflow: auto }` doesn't
1693
+ // scroll itself, the viewport takes its auto).
1694
+ const ownOverflowY = (index: number, node: Node): string =>
1695
+ index === 1 && htmlVisible ? "visible" : overflowY(node);
1631
1696
  const scrollBox = (index: number): boolean => {
1632
1697
  const node = chain[index];
1633
1698
  return (
1634
1699
  node !== undefined &&
1635
- SCROLLS.has(overflowY(node)) &&
1700
+ SCROLLS.has(ownOverflowY(index, node)) &&
1636
1701
  ((states[index]?.screen ?? false) || unread(index))
1637
1702
  );
1638
1703
  };
@@ -1649,7 +1714,10 @@ export function scrollLock(
1649
1714
  const overflow = value(node, "overflow-y");
1650
1715
  const clipped =
1651
1716
  clips && (index === 0 ? true : index === 1 ? state.screen || htmlVisible : state.screen);
1652
- const fixed = state.position === "fixed" && state.screen && !SCROLLS.has(overflowY(node));
1717
+ const fixed =
1718
+ state.position === "fixed" &&
1719
+ (state.screen || index === 1) &&
1720
+ !SCROLLS.has(ownOverflowY(index, node));
1653
1721
  if (!clipped && !fixed) {
1654
1722
  continue;
1655
1723
  }