@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.
- package/dist/bridge/bridge.d.ts +8 -1
- package/dist/bridge/bridge.js +7 -0
- package/dist/bridge/unseen.d.ts +8 -0
- package/dist/bridge/unseen.js +17 -0
- package/dist/check/files.js +14 -10
- package/dist/check/lint.js +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +29 -13
- package/dist/check/scroll.js +74 -18
- package/dist/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.js +27 -0
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/platform/focus-guard.d.ts +143 -0
- package/dist/platform/focus-guard.js +445 -0
- package/dist/platform/types.d.ts +18 -0
- package/dist/platform/web.js +22 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.js +34 -12
- package/dist/runtime/types.generated.js +1 -1
- package/docs/ADOPTING.md +85 -6
- package/docs/DECISIONS.md +355 -5
- package/docs/DESIGN.md +9 -2
- package/docs/THREAT_MODEL.md +121 -29
- package/package.json +1 -1
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +14 -10
- package/src/check/lint.ts +1 -1
- package/src/check/scroll.ts +106 -38
- package/src/config/capabilities.ts +16 -3
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +29 -0
- package/src/host/types.ts +13 -0
- package/src/index.ts +1 -0
- package/src/platform/focus-guard.ts +572 -0
- package/src/platform/types.ts +17 -0
- package/src/platform/web.ts +22 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/types/runtime/v1/comments.d.ts +8 -4
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -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.
|
|
9
|
-
|
|
10
|
-
conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
|
-
a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
|
157
|
-
|
|
158
|
-
|
|
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)
|
|
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
|
|
632
|
-
an anchor or a rect decides where something is drawn, never who may
|
|
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.
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
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.
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
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
|
|
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
|
|
706
|
-
|
|
707
|
-
|
|
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.
|
|
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": {
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -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
|
|
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;
|
package/src/bridge/unseen.ts
CHANGED
|
@@ -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, ""));
|
package/src/check/files.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
//
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
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);
|
package/src/check/scroll.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
|
|
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
|
|
879
|
-
type Found =
|
|
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
|
-
/**
|
|
983
|
-
|
|
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
|
|
1012
|
+
return null;
|
|
986
1013
|
}
|
|
987
|
-
const
|
|
988
|
-
if (this.bytes +
|
|
989
|
-
return
|
|
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 +=
|
|
993
|
-
return
|
|
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
|
-
/**
|
|
1150
|
-
|
|
1151
|
-
|
|
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(
|
|
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
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
}
|
|
1378
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
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(
|
|
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 =
|
|
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
|
}
|