@botiverse/porthole 0.10.0 → 0.12.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/annotate/types.d.ts +18 -6
- package/dist/annotate/validate.d.ts +11 -1
- package/dist/annotate/validate.js +18 -1
- package/dist/check/files.d.ts +2 -0
- package/dist/check/files.js +67 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +100 -0
- package/dist/check/scroll.js +1429 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/runtime.js +6 -0
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +2 -1
- package/dist/shell/annotate.js +29 -12
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +25 -3
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +391 -2
- package/docs/DESIGN.md +31 -9
- package/docs/THREAT_MODEL.md +42 -7
- package/package.json +1 -1
- package/src/annotate/types.ts +19 -6
- package/src/annotate/validate.ts +20 -1
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -0
- package/src/conformance/runtime.ts +9 -0
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +9 -3
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +29 -12
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +14 -4
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,11 +5,13 @@ 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.
|
|
8
|
+
**Status.** This describes Porthole 0.12.0 (2026-10-26). A review on 2026-10-19 found gaps, and every
|
|
9
9
|
decision it led to has merged. P096 changed the negative-control runner and CI, and the shipped
|
|
10
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.
|
|
12
|
-
|
|
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.
|
|
13
15
|
|
|
14
16
|
## 1. Two layers
|
|
15
17
|
|
|
@@ -539,7 +541,7 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
|
|
|
539
541
|
**The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
|
|
540
542
|
effects are its own), and group displays by page (S7).
|
|
541
543
|
|
|
542
|
-
**Annotations** (`annotate`, P053, P104). The shell that draws marks and reports anchors shares
|
|
544
|
+
**Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
|
|
543
545
|
its realm with the content, so:
|
|
544
546
|
|
|
545
547
|
- *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
|
|
@@ -547,9 +549,29 @@ its realm with the content, so:
|
|
|
547
549
|
its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
|
|
548
550
|
a count only where the page may know how many there are. Who commented and what they wrote stay
|
|
549
551
|
in the host's own UI, outside the frame.
|
|
552
|
+
- *Drafts* (P107). A mark with `kind: "draft"` (a comment its author hasn't posted) is drawn apart,
|
|
553
|
+
a dashed line and a hollow marker with no number, so the page also learns which of its marks are
|
|
554
|
+
drafts: that the person viewing it is writing a comment there, before they post it. That is new
|
|
555
|
+
information for the page, accepted where the page has no way out: drafts are the host's to send
|
|
556
|
+
only to their author's own frame (Porthole can't tell whose frame it is), the page is the one
|
|
557
|
+
being commented on and already sees where the person selects (`selected`), and closed egress
|
|
558
|
+
([§4](#4-two-lines-of-defense)) keeps it off the network. Closed egress doesn't cover the
|
|
559
|
+
channels the host itself opens, and through them a draft's existence, place and timing can
|
|
560
|
+
leave: a page with the runtime's `db` (writes) and `user` can call `user.get()`, read the marks
|
|
561
|
+
shown to it, and write "viewer A is drafting at section 3" where its author and other viewers
|
|
562
|
+
read it before A posts; once A posts, the page can tie that posted comment to A (the anchor and
|
|
563
|
+
the time match). Origins a config declares for egress (an MCP App's `connectDomains`, S5; an
|
|
564
|
+
`egress` a host opened in its own config; the `liveWidget` preset itself has none, P103), and a
|
|
565
|
+
host function that sends the page's words somewhere, are channels of the same kind (S4, and the
|
|
566
|
+
app runtime below). A host that sends drafts to such a page accepts that its author and other viewers can
|
|
567
|
+
learn of them. A draft carries nothing else: the host drops its count before the frame (control
|
|
568
|
+
`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
|
|
570
|
+
that sends drafts into a frame others see (a shared screen, a frame several viewers share) tells
|
|
571
|
+
that page, and anything it draws for them, what its author hasn't posted.
|
|
550
572
|
- *What content can fake.* Any report: a selection while the host asks for one, where marks are,
|
|
551
|
-
and a marker's click (`activated`) for any mark the host shows with a count,
|
|
552
|
-
it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
|
|
573
|
+
and a marker's click (`activated`) for any mark the host shows with a marker (a count, or a draft:
|
|
574
|
+
P107), without a click on it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
|
|
553
575
|
The host takes each report only for what it asked for and its own shown ids, rebuilt within
|
|
554
576
|
`ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
|
|
555
577
|
doesn't show, is dropped (negative control `annotation-activated`). `activated` is also taken
|
|
@@ -640,7 +662,10 @@ section.
|
|
|
640
662
|
code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
|
|
641
663
|
only while the config still lets uploaded code run, asked at every load, in bearer mode too
|
|
642
664
|
(where every artifact config must; P103); anything else is a download.
|
|
643
|
-
- `comments` is write-only: the page learns only whether the composer opened.
|
|
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.
|
|
644
669
|
- `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
|
|
645
670
|
`artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
|
|
646
671
|
|
|
@@ -656,6 +681,12 @@ section.
|
|
|
656
681
|
- Keep each person's data apart in its own stores, and refuse moved bases and versions
|
|
657
682
|
(`Refused("conflict")`).
|
|
658
683
|
- Handle abuse on shared pages (S4).
|
|
684
|
+
- 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.
|
|
659
690
|
|
|
660
691
|
**Not guaranteed**
|
|
661
692
|
|
|
@@ -664,6 +695,10 @@ section.
|
|
|
664
695
|
page's rules allow) can read it.
|
|
665
696
|
- `db` rewrites only paths: an id the page stores inside a document's data is returned as stored.
|
|
666
697
|
- In bearer mode, assets are served by id alone, without the host's check.
|
|
698
|
+
- A draft is the page's words in the person's composer: a person who posts it without reading
|
|
699
|
+
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.
|
|
667
702
|
|
|
668
703
|
## 8. Fixes in flight
|
|
669
704
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.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/annotate/types.ts
CHANGED
|
@@ -81,11 +81,23 @@ export interface AnnotationMark {
|
|
|
81
81
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
82
82
|
* `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
|
|
83
83
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
84
|
-
* `activated`. The content can read the number; give one only where the page may know it.
|
|
84
|
+
* `activated`. The content can read the number; give one only where the page may know it. A
|
|
85
|
+
* draft's is dropped (P107): its marker has no number.
|
|
85
86
|
*/
|
|
86
87
|
readonly count?: number;
|
|
88
|
+
/**
|
|
89
|
+
* What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
|
|
90
|
+
* author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
|
|
91
|
+
* number) and has a marker whether or not it has a count; its count is dropped before the mark
|
|
92
|
+
* goes to the frame. The content can read that a mark is a draft: send drafts only to their
|
|
93
|
+
* author's own frame.
|
|
94
|
+
*/
|
|
95
|
+
readonly kind?: AnnotationMarkKind;
|
|
87
96
|
}
|
|
88
97
|
|
|
98
|
+
/** A posted comment's mark, or an unsubmitted draft's (P107). */
|
|
99
|
+
export type AnnotationMarkKind = "posted" | "draft";
|
|
100
|
+
|
|
89
101
|
/** Whether a mark's anchor was found in the content as it is now. */
|
|
90
102
|
export type AnchorState = "attached" | "orphaned";
|
|
91
103
|
|
|
@@ -110,16 +122,17 @@ export type AnnotationReport =
|
|
|
110
122
|
| { readonly type: "cancelled" }
|
|
111
123
|
/**
|
|
112
124
|
* Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
|
|
113
|
-
* every mark when the content changed one's state, and, while any mark has a `count`,
|
|
125
|
+
* every mark when the content changed one's state, and, while any mark has a marker (a `count`,
|
|
126
|
+
* or a draft, P107), once a
|
|
114
127
|
* scroll, a resize or a change of the content has settled, only the marks that moved since the
|
|
115
128
|
* host was last told, at most once a second (P104).
|
|
116
129
|
*/
|
|
117
130
|
| { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
|
|
118
131
|
/**
|
|
119
|
-
* The person clicked the marker of a mark the host shows with a `count` (P104)
|
|
120
|
-
* marker's box, to open the host's own UI beside it. The content can fake
|
|
121
|
-
* host shows with a
|
|
122
|
-
* mark, never act on it.
|
|
132
|
+
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
133
|
+
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
134
|
+
* it for any mark the host shows with a marker, and can tell a real one happened: open the
|
|
135
|
+
* host's own view of that mark, never act on it.
|
|
123
136
|
*/
|
|
124
137
|
| { readonly type: "activated"; readonly id: string; readonly rect: AnnotationRect };
|
|
125
138
|
|
package/src/annotate/validate.ts
CHANGED
|
@@ -198,7 +198,19 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
|
|
|
198
198
|
return { elements, text: words };
|
|
199
199
|
}
|
|
200
200
|
|
|
201
|
-
/**
|
|
201
|
+
/**
|
|
202
|
+
* Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
|
|
203
|
+
* every draft (P107).
|
|
204
|
+
*/
|
|
205
|
+
export const hasMarker = (mark: AnnotationMark): boolean =>
|
|
206
|
+
mark.count !== undefined || mark.kind === "draft";
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one. Each is
|
|
210
|
+
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
211
|
+
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
212
|
+
* told one).
|
|
213
|
+
*/
|
|
202
214
|
export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
203
215
|
if (!Array.isArray(marks) || marks.length > LIMITS.marks) {
|
|
204
216
|
throw new TypeError(`annotations.show: at most ${LIMITS.marks} marks`);
|
|
@@ -216,7 +228,14 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
216
228
|
`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
|
|
217
229
|
);
|
|
218
230
|
}
|
|
231
|
+
const kind: unknown = mark.kind;
|
|
232
|
+
if (kind !== undefined && kind !== "posted" && kind !== "draft") {
|
|
233
|
+
throw new TypeError(`annotations.show: mark ${index}'s kind is "posted" or "draft"`);
|
|
234
|
+
}
|
|
219
235
|
seen.add(mark.id);
|
|
236
|
+
if (kind === "draft") {
|
|
237
|
+
return { id: mark.id, anchor, kind };
|
|
238
|
+
}
|
|
220
239
|
return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
|
|
221
240
|
});
|
|
222
241
|
}
|
package/src/check/files.ts
CHANGED
|
@@ -8,7 +8,9 @@ import {
|
|
|
8
8
|
} from "../files/paths.ts";
|
|
9
9
|
import { fileTypeOf, knownType } from "../files/types.ts";
|
|
10
10
|
import { sizeWords } from "../guide/limits.ts";
|
|
11
|
-
import {
|
|
11
|
+
import { lintPage, type Finding } from "./lint.ts";
|
|
12
|
+
import { attributesOf } from "./markup.ts";
|
|
13
|
+
import { scrollBudget, scrollLock, type LinkedSheet } from "./scroll.ts";
|
|
12
14
|
|
|
13
15
|
/**
|
|
14
16
|
* What can be told about a page that comes with files (P081), without running it: each page
|
|
@@ -82,58 +84,6 @@ const REFERENCE_ATTRIBUTES: Readonly<Record<string, readonly string[]>> = {
|
|
|
82
84
|
/** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
|
|
83
85
|
const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
|
|
84
86
|
|
|
85
|
-
const isSpace = (code: number): boolean =>
|
|
86
|
-
code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
87
|
-
|
|
88
|
-
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
89
|
-
function attributesOf(text: string): { name: string; value: string; at: number }[] {
|
|
90
|
-
const out: { name: string; value: string; at: number }[] = [];
|
|
91
|
-
let at = 0;
|
|
92
|
-
while (at < text.length) {
|
|
93
|
-
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
94
|
-
at += 1;
|
|
95
|
-
}
|
|
96
|
-
const nameStart = at;
|
|
97
|
-
while (
|
|
98
|
-
at < text.length &&
|
|
99
|
-
!isSpace(text.charCodeAt(at)) &&
|
|
100
|
-
text[at] !== "=" &&
|
|
101
|
-
text[at] !== "/"
|
|
102
|
-
) {
|
|
103
|
-
at += 1;
|
|
104
|
-
}
|
|
105
|
-
const name = text.slice(nameStart, at).toLowerCase();
|
|
106
|
-
if (name === "") {
|
|
107
|
-
at += 1;
|
|
108
|
-
continue;
|
|
109
|
-
}
|
|
110
|
-
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
111
|
-
at += 1;
|
|
112
|
-
}
|
|
113
|
-
if (text[at] !== "=") {
|
|
114
|
-
continue;
|
|
115
|
-
}
|
|
116
|
-
at += 1;
|
|
117
|
-
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
118
|
-
at += 1;
|
|
119
|
-
}
|
|
120
|
-
const quote = text[at];
|
|
121
|
-
if (quote === '"' || quote === "'") {
|
|
122
|
-
const close = text.indexOf(quote, at + 1);
|
|
123
|
-
const end = close < 0 ? text.length : close;
|
|
124
|
-
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
125
|
-
at = end + 1;
|
|
126
|
-
} else {
|
|
127
|
-
const start = at;
|
|
128
|
-
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
129
|
-
at += 1;
|
|
130
|
-
}
|
|
131
|
-
out.push({ name, value: text.slice(start, at), at: start });
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
return out;
|
|
135
|
-
}
|
|
136
|
-
|
|
137
87
|
/** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
|
|
138
88
|
function markupReferences(text: string): Reference[] {
|
|
139
89
|
const found: Reference[] = [];
|
|
@@ -225,6 +175,9 @@ function resolve(directory: string, reference: string): string | null {
|
|
|
225
175
|
|
|
226
176
|
const directoryOf = (path: string): string => path.slice(0, path.lastIndexOf("/") + 1);
|
|
227
177
|
|
|
178
|
+
/** The most pages the scroll-lock rule reads in a version: its entry, and 7 more (P106). */
|
|
179
|
+
export const SCROLL_PAGES = 8;
|
|
180
|
+
|
|
228
181
|
/**
|
|
229
182
|
* Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
|
|
230
183
|
* `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
|
|
@@ -319,7 +272,30 @@ export function lintFiles(
|
|
|
319
272
|
}
|
|
320
273
|
}
|
|
321
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>();
|
|
277
|
+
const stylesheet: LinkedSheet = (href, from) => {
|
|
278
|
+
if (href === "" || elsewhere(href) || href.startsWith("/")) {
|
|
279
|
+
return null;
|
|
280
|
+
}
|
|
281
|
+
const target = resolve(directoryOf(from), href);
|
|
282
|
+
const sheet = target === null || !has(target) ? undefined : files[target];
|
|
283
|
+
if (sheet === undefined || target === null) {
|
|
284
|
+
return null;
|
|
285
|
+
}
|
|
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 };
|
|
293
|
+
};
|
|
294
|
+
const it = config.mode === "mcp-app" ? "view" : config.mode === "inline" ? "widget" : "page";
|
|
322
295
|
const maxPage = config.limits.maxBytes;
|
|
296
|
+
// The version's pages, read, for the scroll-lock rule after the rest (P106). A page over its
|
|
297
|
+
// limit isn't read at all: its error says so.
|
|
298
|
+
const pages = new Set<string>();
|
|
323
299
|
for (const [path, body] of Object.entries(files)) {
|
|
324
300
|
const { role } = fileTypeOf(path);
|
|
325
301
|
if (!knownType(path)) {
|
|
@@ -344,9 +320,12 @@ export function lintFiles(
|
|
|
344
320
|
continue;
|
|
345
321
|
}
|
|
346
322
|
const text = textOf(body);
|
|
347
|
-
|
|
323
|
+
// The scroll-lock rule apart, with the stylesheets the page links (P106).
|
|
324
|
+
for (const finding of lintPage(config, text, { scrollLock: false })) {
|
|
348
325
|
findings.push({ ...finding, path });
|
|
349
326
|
}
|
|
327
|
+
// Its path only: the few the rule reads are decoded again there, one at a time.
|
|
328
|
+
pages.add(path);
|
|
350
329
|
const lines = linesOf(text);
|
|
351
330
|
check(path, lines, markupReferences(text), directory, "error");
|
|
352
331
|
check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
|
|
@@ -376,6 +355,41 @@ export function lintFiles(
|
|
|
376
355
|
);
|
|
377
356
|
}
|
|
378
357
|
}
|
|
358
|
+
// Its own styles holding a page to one screen (P106): the entry first, then the others in path
|
|
359
|
+
// order, at most SCROLL_PAGES, within one budget for them all. A warning: past either, the pages
|
|
360
|
+
// left aren't checked, and it says how many.
|
|
361
|
+
const budget = scrollBudget();
|
|
362
|
+
const order = [
|
|
363
|
+
...(pages.has(entry) ? [entry] : []),
|
|
364
|
+
...[...pages].filter((path) => path !== entry).sort(),
|
|
365
|
+
];
|
|
366
|
+
let checked = 0;
|
|
367
|
+
for (const path of order.slice(0, SCROLL_PAGES)) {
|
|
368
|
+
const body = files[path];
|
|
369
|
+
const text = body === undefined ? "" : textOf(body);
|
|
370
|
+
const held = scrollLock(text, { noun: it, path, sheet: stylesheet, budget });
|
|
371
|
+
if (budget.spent) {
|
|
372
|
+
break;
|
|
373
|
+
}
|
|
374
|
+
checked += 1;
|
|
375
|
+
if (held !== null) {
|
|
376
|
+
findings.push({
|
|
377
|
+
rule: "scroll-lock",
|
|
378
|
+
severity: "warning",
|
|
379
|
+
message: held.message,
|
|
380
|
+
path: held.path ?? path,
|
|
381
|
+
line: held.line,
|
|
382
|
+
});
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
const unchecked = pages.size - checked;
|
|
386
|
+
if (unchecked > 0) {
|
|
387
|
+
findings.push({
|
|
388
|
+
rule: "scroll-lock",
|
|
389
|
+
severity: "warning",
|
|
390
|
+
message: `${unchecked} page${unchecked === 1 ? "" : "s"} not checked for scroll lock: the check reads the entry and at most ${SCROLL_PAGES - 1} other pages, within one budget. If one of them 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.`,
|
|
391
|
+
});
|
|
392
|
+
}
|
|
379
393
|
return findings;
|
|
380
394
|
}
|
|
381
395
|
|
package/src/check/lint.ts
CHANGED
|
@@ -8,6 +8,7 @@ import {
|
|
|
8
8
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
9
9
|
import { sizeWords } from "../guide/limits.ts";
|
|
10
10
|
import { originMatchesSource } from "../isolation/served.ts";
|
|
11
|
+
import { scrollLock } from "./scroll.ts";
|
|
11
12
|
|
|
12
13
|
/**
|
|
13
14
|
* What can be told about content without running it (P073), worded as the manual words it, so
|
|
@@ -26,6 +27,7 @@ export type LintRule =
|
|
|
26
27
|
| "egress"
|
|
27
28
|
| "unpinned"
|
|
28
29
|
| "position-fixed"
|
|
30
|
+
| "scroll-lock"
|
|
29
31
|
| "new-window";
|
|
30
32
|
|
|
31
33
|
export interface Finding {
|
|
@@ -123,6 +125,18 @@ const OWN_CDN: readonly {
|
|
|
123
125
|
];
|
|
124
126
|
|
|
125
127
|
export function lintContent(config: PortholeConfig, content: string): Finding[] {
|
|
128
|
+
return lintPage(config, content, { scrollLock: true });
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* `lintContent`, with or without the scroll-lock rule: `lintFiles` reads that one itself, once,
|
|
133
|
+
* with the stylesheets the page links.
|
|
134
|
+
*/
|
|
135
|
+
export function lintPage(
|
|
136
|
+
config: PortholeConfig,
|
|
137
|
+
content: string,
|
|
138
|
+
options: { readonly scrollLock: boolean },
|
|
139
|
+
): Finding[] {
|
|
126
140
|
if (config.mode === "url") {
|
|
127
141
|
return [];
|
|
128
142
|
}
|
|
@@ -274,6 +288,16 @@ export function lintContent(config: PortholeConfig, content: string): Finding[]
|
|
|
274
288
|
);
|
|
275
289
|
}
|
|
276
290
|
}
|
|
291
|
+
// Its own styles holding it to one screen (P106): a warning, as a one-screen app means it.
|
|
292
|
+
const held = options.scrollLock ? scrollLock(content, { noun: it }) : null;
|
|
293
|
+
if (held !== null) {
|
|
294
|
+
findings.push({
|
|
295
|
+
rule: "scroll-lock",
|
|
296
|
+
severity: "warning",
|
|
297
|
+
message: held.message,
|
|
298
|
+
line: held.line,
|
|
299
|
+
});
|
|
300
|
+
}
|
|
277
301
|
const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);
|
|
278
302
|
if (opens !== null && !declared.has("openLink")) {
|
|
279
303
|
add(
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/** Reading markup without parsing it: what the checks share. Linear, however it was written. */
|
|
2
|
+
|
|
3
|
+
const isSpace = (code: number): boolean =>
|
|
4
|
+
code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
5
|
+
|
|
6
|
+
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
7
|
+
export function attributesOf(text: string): { name: string; value: string; at: number }[] {
|
|
8
|
+
const out: { name: string; value: string; at: number }[] = [];
|
|
9
|
+
let at = 0;
|
|
10
|
+
while (at < text.length) {
|
|
11
|
+
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
12
|
+
at += 1;
|
|
13
|
+
}
|
|
14
|
+
const nameStart = at;
|
|
15
|
+
while (
|
|
16
|
+
at < text.length &&
|
|
17
|
+
!isSpace(text.charCodeAt(at)) &&
|
|
18
|
+
text[at] !== "=" &&
|
|
19
|
+
text[at] !== "/"
|
|
20
|
+
) {
|
|
21
|
+
at += 1;
|
|
22
|
+
}
|
|
23
|
+
const name = text.slice(nameStart, at).toLowerCase();
|
|
24
|
+
if (name === "") {
|
|
25
|
+
at += 1;
|
|
26
|
+
continue;
|
|
27
|
+
}
|
|
28
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
29
|
+
at += 1;
|
|
30
|
+
}
|
|
31
|
+
if (text[at] !== "=") {
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
at += 1;
|
|
35
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
36
|
+
at += 1;
|
|
37
|
+
}
|
|
38
|
+
const quote = text[at];
|
|
39
|
+
if (quote === '"' || quote === "'") {
|
|
40
|
+
const close = text.indexOf(quote, at + 1);
|
|
41
|
+
const end = close < 0 ? text.length : close;
|
|
42
|
+
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
43
|
+
at = end + 1;
|
|
44
|
+
} else {
|
|
45
|
+
const start = at;
|
|
46
|
+
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
47
|
+
at += 1;
|
|
48
|
+
}
|
|
49
|
+
out.push({ name, value: text.slice(start, at), at: start });
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
return out;
|
|
53
|
+
}
|