@botiverse/porthole 0.9.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 +21 -7
- package/dist/annotate/validate.d.ts +18 -3
- package/dist/annotate/validate.js +29 -5
- package/dist/bridge/bridge.js +1 -51
- package/dist/bridge/unseen.d.ts +18 -0
- package/dist/bridge/unseen.js +71 -0
- 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/behavior.js +107 -68
- package/dist/conformance/clipboard.js +16 -14
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/limits.js +117 -64
- package/dist/conformance/probes.js +66 -49
- package/dist/conformance/runtime.js +6 -0
- package/dist/conformance/served.js +66 -63
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +46 -4
- package/dist/index.d.ts +1 -1
- package/dist/platform/types.d.ts +4 -2
- 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 +6 -3
- package/dist/shell/annotate.js +474 -104
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +99 -1
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +764 -14
- package/docs/DESIGN.md +192 -42
- package/docs/THREAT_MODEL.md +109 -27
- package/package.json +1 -1
- package/src/annotate/types.ts +22 -7
- package/src/annotate/validate.ts +32 -6
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- 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/behavior.ts +221 -69
- package/src/conformance/clipboard.ts +44 -14
- package/src/conformance/limits.ts +169 -76
- package/src/conformance/probes.ts +97 -49
- package/src/conformance/runtime.ts +9 -0
- package/src/conformance/served.ts +112 -63
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +50 -4
- package/src/index.ts +1 -0
- package/src/platform/types.ts +4 -2
- 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 +474 -104
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +14 -4
package/dist/annotate/types.d.ts
CHANGED
|
@@ -44,7 +44,9 @@ export interface AnnotationAnchor {
|
|
|
44
44
|
/**
|
|
45
45
|
* A box in the frame's viewport, CSS px: add the frame element's position to place it on the page.
|
|
46
46
|
* The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
|
|
47
|
-
* outside is a box of no size on the nearest edge. A positioning hint only.
|
|
47
|
+
* outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
|
|
48
|
+
* own layout px: a host that scales or transforms the frame maps it through that transform too
|
|
49
|
+
* (P105).
|
|
48
50
|
*/
|
|
49
51
|
export interface AnnotationRect {
|
|
50
52
|
readonly x: number;
|
|
@@ -71,10 +73,21 @@ export interface AnnotationMark {
|
|
|
71
73
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
72
74
|
* `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
|
|
73
75
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
74
|
-
* `activated`. The content can read the number; give one only where the page may know it.
|
|
76
|
+
* `activated`. The content can read the number; give one only where the page may know it. A
|
|
77
|
+
* draft's is dropped (P107): its marker has no number.
|
|
75
78
|
*/
|
|
76
79
|
readonly count?: number;
|
|
80
|
+
/**
|
|
81
|
+
* What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
|
|
82
|
+
* author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
|
|
83
|
+
* number) and has a marker whether or not it has a count; its count is dropped before the mark
|
|
84
|
+
* goes to the frame. The content can read that a mark is a draft: send drafts only to their
|
|
85
|
+
* author's own frame.
|
|
86
|
+
*/
|
|
87
|
+
readonly kind?: AnnotationMarkKind;
|
|
77
88
|
}
|
|
89
|
+
/** A posted comment's mark, or an unsubmitted draft's (P107). */
|
|
90
|
+
export type AnnotationMarkKind = "posted" | "draft";
|
|
78
91
|
/** Whether a mark's anchor was found in the content as it is now. */
|
|
79
92
|
export type AnchorState = "attached" | "orphaned";
|
|
80
93
|
export interface AnchorResult {
|
|
@@ -101,7 +114,8 @@ export type AnnotationReport =
|
|
|
101
114
|
}
|
|
102
115
|
/**
|
|
103
116
|
* Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
|
|
104
|
-
* every mark when the content changed one's state, and, while any mark has a `count`,
|
|
117
|
+
* every mark when the content changed one's state, and, while any mark has a marker (a `count`,
|
|
118
|
+
* or a draft, P107), once a
|
|
105
119
|
* scroll, a resize or a change of the content has settled, only the marks that moved since the
|
|
106
120
|
* host was last told, at most once a second (P104).
|
|
107
121
|
*/
|
|
@@ -110,10 +124,10 @@ export type AnnotationReport =
|
|
|
110
124
|
readonly results: readonly AnchorResult[];
|
|
111
125
|
}
|
|
112
126
|
/**
|
|
113
|
-
* The person clicked the marker of a mark the host shows with a `count` (P104)
|
|
114
|
-
* marker's box, to open the host's own UI beside it. The content can fake
|
|
115
|
-
* host shows with a
|
|
116
|
-
* mark, never act on it.
|
|
127
|
+
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
128
|
+
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
129
|
+
* it for any mark the host shows with a marker, and can tell a real one happened: open the
|
|
130
|
+
* host's own view of that mark, never act on it.
|
|
117
131
|
*/
|
|
118
132
|
| {
|
|
119
133
|
readonly type: "activated";
|
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport } from "./types.ts";
|
|
2
|
-
/**
|
|
2
|
+
/**
|
|
3
|
+
* An anchor, rebuilt from its known fields; null if any part is malformed or too large. Its label
|
|
4
|
+
* is text for the person, so what they couldn't see is taken out of it (P105: a wordless element's
|
|
5
|
+
* `alt`, `aria-label` or `title`, which the page never shows, can carry bidi controls or zero-width
|
|
6
|
+
* characters); its selectors' words are kept as they are, to be found again.
|
|
7
|
+
*/
|
|
3
8
|
export declare function parseAnchor(value: unknown): AnnotationAnchor | null;
|
|
4
9
|
/** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
|
|
5
10
|
export declare function parseRect(value: unknown): AnnotationRect | null;
|
|
@@ -12,10 +17,20 @@ export declare function parseRect(value: unknown): AnnotationRect | null;
|
|
|
12
17
|
export declare function clampRect(rect: AnnotationRect, viewport: {
|
|
13
18
|
readonly width: number;
|
|
14
19
|
readonly height: number;
|
|
15
|
-
} | undefined): AnnotationRect;
|
|
20
|
+
} | null | undefined): AnnotationRect;
|
|
16
21
|
/** A report from the frame, checked; null if malformed (it is then dropped). */
|
|
17
22
|
export declare function parseReport(value: unknown): AnnotationReport | null;
|
|
18
23
|
/** What the host may start with: elements, text, or both (default both). */
|
|
19
24
|
export declare function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode>;
|
|
20
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
|
|
27
|
+
* every draft (P107).
|
|
28
|
+
*/
|
|
29
|
+
export declare const hasMarker: (mark: AnnotationMark) => boolean;
|
|
30
|
+
/**
|
|
31
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one. Each is
|
|
32
|
+
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
33
|
+
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
34
|
+
* told one).
|
|
35
|
+
*/
|
|
21
36
|
export declare function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[];
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { ANNOTATION_LIMITS as LIMITS, } from "./types.js";
|
|
2
|
+
import { withoutUnseen } from "../bridge/unseen.js";
|
|
2
3
|
/**
|
|
3
4
|
* The host's checks on what a frame says about annotations (P053), and on anchors a host stores
|
|
4
5
|
* and sends back. Each rebuilds what it accepts from known fields only, within `ANNOTATION_LIMITS`,
|
|
@@ -40,7 +41,12 @@ function selector(value) {
|
|
|
40
41
|
return null;
|
|
41
42
|
}
|
|
42
43
|
}
|
|
43
|
-
/**
|
|
44
|
+
/**
|
|
45
|
+
* An anchor, rebuilt from its known fields; null if any part is malformed or too large. Its label
|
|
46
|
+
* is text for the person, so what they couldn't see is taken out of it (P105: a wordless element's
|
|
47
|
+
* `alt`, `aria-label` or `title`, which the page never shows, can carry bidi controls or zero-width
|
|
48
|
+
* characters); its selectors' words are kept as they are, to be found again.
|
|
49
|
+
*/
|
|
44
50
|
export function parseAnchor(value) {
|
|
45
51
|
if (!isRecord(value) || (value.kind !== "element" && value.kind !== "text")) {
|
|
46
52
|
return null;
|
|
@@ -65,7 +71,7 @@ export function parseAnchor(value) {
|
|
|
65
71
|
if (value.kind === "text" ? !quote : !css && !quote) {
|
|
66
72
|
return null;
|
|
67
73
|
}
|
|
68
|
-
return { kind: value.kind, selectors, label: value.label };
|
|
74
|
+
return { kind: value.kind, selectors, label: withoutUnseen(value.label) };
|
|
69
75
|
}
|
|
70
76
|
const coordinate = (value) => typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= LIMITS.coordinate;
|
|
71
77
|
/** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
|
|
@@ -89,8 +95,9 @@ export function parseRect(value) {
|
|
|
89
95
|
* box of no size at the frame's corner. The page still chooses any point inside its own frame.
|
|
90
96
|
*/
|
|
91
97
|
export function clampRect(rect, viewport) {
|
|
92
|
-
const
|
|
93
|
-
const
|
|
98
|
+
const known = viewport !== null && typeof viewport === "object";
|
|
99
|
+
const width = known && Number.isFinite(viewport.width) ? viewport.width : 0;
|
|
100
|
+
const height = known && Number.isFinite(viewport.height) ? viewport.height : 0;
|
|
94
101
|
const within = (value, most) => Math.min(Math.max(value, 0), Math.max(0, most));
|
|
95
102
|
const left = within(rect.x, width);
|
|
96
103
|
const top = within(rect.y, height);
|
|
@@ -159,7 +166,17 @@ export function annotateMode(mode) {
|
|
|
159
166
|
}
|
|
160
167
|
return { elements, text: words };
|
|
161
168
|
}
|
|
162
|
-
/**
|
|
169
|
+
/**
|
|
170
|
+
* Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
|
|
171
|
+
* every draft (P107).
|
|
172
|
+
*/
|
|
173
|
+
export const hasMarker = (mark) => mark.count !== undefined || mark.kind === "draft";
|
|
174
|
+
/**
|
|
175
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one. Each is
|
|
176
|
+
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
177
|
+
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
178
|
+
* told one).
|
|
179
|
+
*/
|
|
163
180
|
export function checkMarks(marks) {
|
|
164
181
|
if (!Array.isArray(marks) || marks.length > LIMITS.marks) {
|
|
165
182
|
throw new TypeError(`annotations.show: at most ${LIMITS.marks} marks`);
|
|
@@ -173,7 +190,14 @@ export function checkMarks(marks) {
|
|
|
173
190
|
if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
|
|
174
191
|
throw new TypeError(`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`);
|
|
175
192
|
}
|
|
193
|
+
const kind = mark.kind;
|
|
194
|
+
if (kind !== undefined && kind !== "posted" && kind !== "draft") {
|
|
195
|
+
throw new TypeError(`annotations.show: mark ${index}'s kind is "posted" or "draft"`);
|
|
196
|
+
}
|
|
176
197
|
seen.add(mark.id);
|
|
198
|
+
if (kind === "draft") {
|
|
199
|
+
return { id: mark.id, anchor, kind };
|
|
200
|
+
}
|
|
177
201
|
return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
|
|
178
202
|
});
|
|
179
203
|
}
|
package/dist/bridge/bridge.js
CHANGED
|
@@ -3,6 +3,7 @@ import { parseReport } from "../annotate/validate.js";
|
|
|
3
3
|
import { callGates, effectiveGates } from "../compile/policy.js";
|
|
4
4
|
import { boundedText } from "./bounded-text.js";
|
|
5
5
|
import { isJsonData } from "./json-data.js";
|
|
6
|
+
import { unseen } from "./unseen.js";
|
|
6
7
|
import { blockedNavigationMessage, cutText, withoutSealedAddresses } from "./navigation.js";
|
|
7
8
|
import { RUNTIME_HOST_FUNCTIONS, familyOf, methodGates, methodLevel, methodOf, methodsOfCall, assetCodeRuns, rosterOf, runtimeCapability, } from "../runtime/contract.js";
|
|
8
9
|
import { declaredMatch, } from "../runtime/declaration.js";
|
|
@@ -45,57 +46,6 @@ function resourceUri(args) {
|
|
|
45
46
|
}
|
|
46
47
|
/** The most text blocks one model context update holds. */
|
|
47
48
|
const MAX_CONTEXT_BLOCKS = 100;
|
|
48
|
-
/**
|
|
49
|
-
* What a person can't see but a model reads (the review of P100): format characters (zero-width
|
|
50
|
-
* ones, bidi controls, the tags U+E0000–E007F, a soft hyphen, a byte-order mark), variation
|
|
51
|
-
* selectors (U+FE00–FE0F, U+E0100–E01EF), private-use characters, lone surrogates, every
|
|
52
|
-
* default-ignorable code point (the re-check: U+034F, Mongolian's free variation selectors, the
|
|
53
|
-
* Hangul fillers, Khmer's inherent vowels), and controls other than a new line and a tab. An update with any is refused, never escaped: an escaped one
|
|
54
|
-
* reads to the model differently from what the person was shown.
|
|
55
|
-
*/
|
|
56
|
-
const UNSEEN = /[\p{Cf}\p{Co}\p{Cs}\p{Default_Ignorable_Code_Point}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]|[^\P{Cc}\n\t]/u;
|
|
57
|
-
/**
|
|
58
|
-
* The parts of real emoji that draw as nothing alone, allowed only where an emoji has them (the
|
|
59
|
-
* re-review of P100): U+FE0E or U+FE0F directly after a pictograph, or after a keycap base
|
|
60
|
-
* (`[0-9#*]`) that U+20E3 follows; U+200D only between two pictographs, a selector or a skin tone
|
|
61
|
-
* after the first. Each carries at most one choice beside a visible emoji (a selector there or
|
|
62
|
-
* not, a joiner there or not), never letters a model would read. Tag characters stay refused:
|
|
63
|
-
* subdivision flags too.
|
|
64
|
-
*/
|
|
65
|
-
const EMOJI_PARTS = "(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)|(?<=\\p{Extended_Pictographic}[\\uFE0F\\p{Emoji_Modifier}]?)\\u200D(?=\\p{Extended_Pictographic})";
|
|
66
|
-
/**
|
|
67
|
-
* The scripts whose letters U+200C and U+200D shape (Unicode's notes on the joiners: the cursive
|
|
68
|
-
* scripts, where they break or make a join, and the Indic ones and Myanmar, where they choose a
|
|
69
|
-
* conjunct, a half form or a ligature), by Script_Extensions.
|
|
70
|
-
*/
|
|
71
|
-
const SHAPING_SCRIPTS = [
|
|
72
|
-
"Arabic",
|
|
73
|
-
"Syriac",
|
|
74
|
-
"Nko",
|
|
75
|
-
"Mongolian",
|
|
76
|
-
"Devanagari",
|
|
77
|
-
"Bengali",
|
|
78
|
-
"Gurmukhi",
|
|
79
|
-
"Gujarati",
|
|
80
|
-
"Oriya",
|
|
81
|
-
"Tamil",
|
|
82
|
-
"Telugu",
|
|
83
|
-
"Kannada",
|
|
84
|
-
"Malayalam",
|
|
85
|
-
"Sinhala",
|
|
86
|
-
"Myanmar",
|
|
87
|
-
];
|
|
88
|
-
const SHAPED = `[${SHAPING_SCRIPTS.map((name) => `\\p{scx=${name}}`).join("")}]`;
|
|
89
|
-
/**
|
|
90
|
-
* A joiner or non-joiner between two letters or marks of those scripts (Persian's میخواهم, a
|
|
91
|
-
* Hindi half form): the shape it chooses is what the person sees. One at a letter boundary, never
|
|
92
|
-
* doubled, first or last, or beside a letter of another script.
|
|
93
|
-
*/
|
|
94
|
-
const SHAPING_JOINERS = `(?<=[\\p{L}\\p{M}])(?<=${SHAPED})[\\u200C\\u200D](?=[\\p{L}\\p{M}])(?=${SHAPED})`;
|
|
95
|
-
/** What may be invisible alone and is allowed where it is seen: one pass, on the text as sent. */
|
|
96
|
-
const SEEN_IN_PLACE = new RegExp(`${EMOJI_PARTS}|${SHAPING_JOINERS}`, "gu");
|
|
97
|
-
/** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
|
|
98
|
-
const unseen = (text) => UNSEEN.test(text.replace(SEEN_IN_PLACE, ""));
|
|
99
49
|
/** Whether any string in `value`, a key or a value, holds what can't be seen (bounded JSON data). */
|
|
100
50
|
function holdsUnseen(value) {
|
|
101
51
|
if (typeof value === "string") {
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a person can't see in text that a model or a host's UI reads (P100; P105 for labels): one
|
|
3
|
+
* definition, for the bridge's check of a model context update and the annotation labels' strip.
|
|
4
|
+
*/
|
|
5
|
+
/** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
|
|
6
|
+
export declare const unseen: (text: string) => boolean;
|
|
7
|
+
/**
|
|
8
|
+
* `text` without anything a person can't see (P105), for text Porthole only shows, never matches,
|
|
9
|
+
* as a wordless element's label is (an `alt`, `aria-label` or `title` the person never sees on the
|
|
10
|
+
* page): every format character (bidi controls and the zero-width ones among them), every
|
|
11
|
+
* default-ignorable code point, variation selector, private-use character and lone surrogate, and
|
|
12
|
+
* every control but a new line and a tab. No exceptions: not the parts of emoji, nor the joiners
|
|
13
|
+
* between shaped letters that `unseen` lets by, whose surroundings a page can fake (the review of
|
|
14
|
+
* P105: a Mongolian variation selector beside each joiner carried 48 of them through, a payload
|
|
15
|
+
* of six bytes). An emoji may lose its joiners (a family shows as its faces). Nothing `unseen`
|
|
16
|
+
* refuses is left.
|
|
17
|
+
*/
|
|
18
|
+
export declare function withoutUnseen(text: string): string;
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a person can't see in text that a model or a host's UI reads (P100; P105 for labels): one
|
|
3
|
+
* definition, for the bridge's check of a model context update and the annotation labels' strip.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* What a person can't see but a model reads (the review of P100): format characters (zero-width
|
|
7
|
+
* ones, bidi controls, the tags U+E0000–E007F, a soft hyphen, a byte-order mark), variation
|
|
8
|
+
* selectors (U+FE00–FE0F, U+E0100–E01EF), private-use characters, lone surrogates, every
|
|
9
|
+
* default-ignorable code point (the re-check: U+034F, Mongolian's free variation selectors, the
|
|
10
|
+
* Hangul fillers, Khmer's inherent vowels), and controls other than a new line and a tab. An update with any is refused, never escaped: an escaped one
|
|
11
|
+
* reads to the model differently from what the person was shown.
|
|
12
|
+
*/
|
|
13
|
+
const UNSEEN = /[\p{Cf}\p{Co}\p{Cs}\p{Default_Ignorable_Code_Point}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]|[^\P{Cc}\n\t]/u;
|
|
14
|
+
/**
|
|
15
|
+
* The parts of real emoji that draw as nothing alone, allowed only where an emoji has them (the
|
|
16
|
+
* re-review of P100): U+FE0E or U+FE0F directly after a pictograph, or after a keycap base
|
|
17
|
+
* (`[0-9#*]`) that U+20E3 follows; U+200D only between two pictographs, a selector or a skin tone
|
|
18
|
+
* after the first. Each carries at most one choice beside a visible emoji (a selector there or
|
|
19
|
+
* not, a joiner there or not), never letters a model would read. Tag characters stay refused:
|
|
20
|
+
* subdivision flags too.
|
|
21
|
+
*/
|
|
22
|
+
const EMOJI_PARTS = "(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)|(?<=\\p{Extended_Pictographic}[\\uFE0F\\p{Emoji_Modifier}]?)\\u200D(?=\\p{Extended_Pictographic})";
|
|
23
|
+
/**
|
|
24
|
+
* The scripts whose letters U+200C and U+200D shape (Unicode's notes on the joiners: the cursive
|
|
25
|
+
* scripts, where they break or make a join, and the Indic ones and Myanmar, where they choose a
|
|
26
|
+
* conjunct, a half form or a ligature), by Script_Extensions.
|
|
27
|
+
*/
|
|
28
|
+
const SHAPING_SCRIPTS = [
|
|
29
|
+
"Arabic",
|
|
30
|
+
"Syriac",
|
|
31
|
+
"Nko",
|
|
32
|
+
"Mongolian",
|
|
33
|
+
"Devanagari",
|
|
34
|
+
"Bengali",
|
|
35
|
+
"Gurmukhi",
|
|
36
|
+
"Gujarati",
|
|
37
|
+
"Oriya",
|
|
38
|
+
"Tamil",
|
|
39
|
+
"Telugu",
|
|
40
|
+
"Kannada",
|
|
41
|
+
"Malayalam",
|
|
42
|
+
"Sinhala",
|
|
43
|
+
"Myanmar",
|
|
44
|
+
];
|
|
45
|
+
const SHAPED = `[${SHAPING_SCRIPTS.map((name) => `\\p{scx=${name}}`).join("")}]`;
|
|
46
|
+
/**
|
|
47
|
+
* A joiner or non-joiner between two letters or marks of those scripts (Persian's میخواهم, a
|
|
48
|
+
* Hindi half form): the shape it chooses is what the person sees. One at a letter boundary, never
|
|
49
|
+
* doubled, first or last, or beside a letter of another script.
|
|
50
|
+
*/
|
|
51
|
+
const SHAPING_JOINERS = `(?<=[\\p{L}\\p{M}])(?<=${SHAPED})[\\u200C\\u200D](?=[\\p{L}\\p{M}])(?=${SHAPED})`;
|
|
52
|
+
/** What may be invisible alone and is allowed where it is seen: one pass, on the text as sent. */
|
|
53
|
+
const SEEN_IN_PLACE = new RegExp(`${EMOJI_PARTS}|${SHAPING_JOINERS}`, "gu");
|
|
54
|
+
/** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
|
|
55
|
+
export const unseen = (text) => UNSEEN.test(text.replace(SEEN_IN_PLACE, ""));
|
|
56
|
+
/** Every code point `UNSEEN` names, each on its own. */
|
|
57
|
+
const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
|
|
58
|
+
/**
|
|
59
|
+
* `text` without anything a person can't see (P105), for text Porthole only shows, never matches,
|
|
60
|
+
* as a wordless element's label is (an `alt`, `aria-label` or `title` the person never sees on the
|
|
61
|
+
* page): every format character (bidi controls and the zero-width ones among them), every
|
|
62
|
+
* default-ignorable code point, variation selector, private-use character and lone surrogate, and
|
|
63
|
+
* every control but a new line and a tab. No exceptions: not the parts of emoji, nor the joiners
|
|
64
|
+
* between shaped letters that `unseen` lets by, whose surroundings a page can fake (the review of
|
|
65
|
+
* P105: a Mongolian variation selector beside each joiner carried 48 of them through, a payload
|
|
66
|
+
* of six bytes). An emoji may lose its joiners (a family shows as its faces). Nothing `unseen`
|
|
67
|
+
* refuses is left.
|
|
68
|
+
*/
|
|
69
|
+
export function withoutUnseen(text) {
|
|
70
|
+
return text.replace(UNSEEN_EACH, "");
|
|
71
|
+
}
|
package/dist/check/files.d.ts
CHANGED
|
@@ -13,6 +13,8 @@ export interface FileFinding extends Omit<Finding, "rule"> {
|
|
|
13
13
|
}
|
|
14
14
|
/** A set's files, by path: text, or bytes. */
|
|
15
15
|
export type FileContents = Readonly<Record<string, string | Uint8Array>>;
|
|
16
|
+
/** The most pages the scroll-lock rule reads in a version: its entry, and 7 more (P106). */
|
|
17
|
+
export declare const SCROLL_PAGES = 8;
|
|
16
18
|
/**
|
|
17
19
|
* Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
|
|
18
20
|
* `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
|
package/dist/check/files.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { checkFileSet, DEFAULT_ENTRY, fileLimits, lookupFile, servesFiles, } from "../files/paths.js";
|
|
2
2
|
import { fileTypeOf, knownType } from "../files/types.js";
|
|
3
3
|
import { sizeWords } from "../guide/limits.js";
|
|
4
|
-
import {
|
|
4
|
+
import { lintPage } from "./lint.js";
|
|
5
|
+
import { attributesOf } from "./markup.js";
|
|
6
|
+
import { scrollBudget, scrollLock } from "./scroll.js";
|
|
5
7
|
/** A text's line numbers by offset: its line starts found once, each line then a binary search. */
|
|
6
8
|
function linesOf(text) {
|
|
7
9
|
const starts = [0];
|
|
@@ -45,54 +47,6 @@ const REFERENCE_ATTRIBUTES = {
|
|
|
45
47
|
};
|
|
46
48
|
/** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
|
|
47
49
|
const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
|
|
48
|
-
const isSpace = (code) => code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
49
|
-
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
50
|
-
function attributesOf(text) {
|
|
51
|
-
const out = [];
|
|
52
|
-
let at = 0;
|
|
53
|
-
while (at < text.length) {
|
|
54
|
-
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
55
|
-
at += 1;
|
|
56
|
-
}
|
|
57
|
-
const nameStart = at;
|
|
58
|
-
while (at < text.length &&
|
|
59
|
-
!isSpace(text.charCodeAt(at)) &&
|
|
60
|
-
text[at] !== "=" &&
|
|
61
|
-
text[at] !== "/") {
|
|
62
|
-
at += 1;
|
|
63
|
-
}
|
|
64
|
-
const name = text.slice(nameStart, at).toLowerCase();
|
|
65
|
-
if (name === "") {
|
|
66
|
-
at += 1;
|
|
67
|
-
continue;
|
|
68
|
-
}
|
|
69
|
-
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
70
|
-
at += 1;
|
|
71
|
-
}
|
|
72
|
-
if (text[at] !== "=") {
|
|
73
|
-
continue;
|
|
74
|
-
}
|
|
75
|
-
at += 1;
|
|
76
|
-
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
77
|
-
at += 1;
|
|
78
|
-
}
|
|
79
|
-
const quote = text[at];
|
|
80
|
-
if (quote === '"' || quote === "'") {
|
|
81
|
-
const close = text.indexOf(quote, at + 1);
|
|
82
|
-
const end = close < 0 ? text.length : close;
|
|
83
|
-
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
84
|
-
at = end + 1;
|
|
85
|
-
}
|
|
86
|
-
else {
|
|
87
|
-
const start = at;
|
|
88
|
-
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
89
|
-
at += 1;
|
|
90
|
-
}
|
|
91
|
-
out.push({ name, value: text.slice(start, at), at: start });
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
return out;
|
|
95
|
-
}
|
|
96
50
|
/** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
|
|
97
51
|
function markupReferences(text) {
|
|
98
52
|
const found = [];
|
|
@@ -179,6 +133,8 @@ function resolve(directory, reference) {
|
|
|
179
133
|
return out.join("/");
|
|
180
134
|
}
|
|
181
135
|
const directoryOf = (path) => path.slice(0, path.lastIndexOf("/") + 1);
|
|
136
|
+
/** The most pages the scroll-lock rule reads in a version: its entry, and 7 more (P106). */
|
|
137
|
+
export const SCROLL_PAGES = 8;
|
|
182
138
|
/**
|
|
183
139
|
* Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
|
|
184
140
|
* `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
|
|
@@ -255,7 +211,30 @@ export function lintFiles(config, files, options = {}) {
|
|
|
255
211
|
}
|
|
256
212
|
}
|
|
257
213
|
};
|
|
214
|
+
// A stylesheet a page links or a stylesheet imports, found in the set by its path (P106).
|
|
215
|
+
const decoded = new Map();
|
|
216
|
+
const stylesheet = (href, from) => {
|
|
217
|
+
if (href === "" || elsewhere(href) || href.startsWith("/")) {
|
|
218
|
+
return null;
|
|
219
|
+
}
|
|
220
|
+
const target = resolve(directoryOf(from), href);
|
|
221
|
+
const sheet = target === null || !has(target) ? undefined : files[target];
|
|
222
|
+
if (sheet === undefined || target === null) {
|
|
223
|
+
return null;
|
|
224
|
+
}
|
|
225
|
+
// Decoded once for the whole set, however many pages link it.
|
|
226
|
+
let text = decoded.get(target);
|
|
227
|
+
if (text === undefined) {
|
|
228
|
+
text = textOf(sheet).slice(0, SCANNED);
|
|
229
|
+
decoded.set(target, text);
|
|
230
|
+
}
|
|
231
|
+
return { path: target, text };
|
|
232
|
+
};
|
|
233
|
+
const it = config.mode === "mcp-app" ? "view" : config.mode === "inline" ? "widget" : "page";
|
|
258
234
|
const maxPage = config.limits.maxBytes;
|
|
235
|
+
// The version's pages, read, for the scroll-lock rule after the rest (P106). A page over its
|
|
236
|
+
// limit isn't read at all: its error says so.
|
|
237
|
+
const pages = new Set();
|
|
259
238
|
for (const [path, body] of Object.entries(files)) {
|
|
260
239
|
const { role } = fileTypeOf(path);
|
|
261
240
|
if (!knownType(path)) {
|
|
@@ -280,9 +259,12 @@ export function lintFiles(config, files, options = {}) {
|
|
|
280
259
|
continue;
|
|
281
260
|
}
|
|
282
261
|
const text = textOf(body);
|
|
283
|
-
|
|
262
|
+
// The scroll-lock rule apart, with the stylesheets the page links (P106).
|
|
263
|
+
for (const finding of lintPage(config, text, { scrollLock: false })) {
|
|
284
264
|
findings.push({ ...finding, path });
|
|
285
265
|
}
|
|
266
|
+
// Its path only: the few the rule reads are decoded again there, one at a time.
|
|
267
|
+
pages.add(path);
|
|
286
268
|
const lines = linesOf(text);
|
|
287
269
|
check(path, lines, markupReferences(text), directory, "error");
|
|
288
270
|
check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
|
|
@@ -301,6 +283,41 @@ export function lintFiles(config, files, options = {}) {
|
|
|
301
283
|
check(path, lines, patternReferences(text, PAGE_REFERENCES), directoryOf(entry), "warning", directory);
|
|
302
284
|
}
|
|
303
285
|
}
|
|
286
|
+
// Its own styles holding a page to one screen (P106): the entry first, then the others in path
|
|
287
|
+
// order, at most SCROLL_PAGES, within one budget for them all. A warning: past either, the pages
|
|
288
|
+
// left aren't checked, and it says how many.
|
|
289
|
+
const budget = scrollBudget();
|
|
290
|
+
const order = [
|
|
291
|
+
...(pages.has(entry) ? [entry] : []),
|
|
292
|
+
...[...pages].filter((path) => path !== entry).sort(),
|
|
293
|
+
];
|
|
294
|
+
let checked = 0;
|
|
295
|
+
for (const path of order.slice(0, SCROLL_PAGES)) {
|
|
296
|
+
const body = files[path];
|
|
297
|
+
const text = body === undefined ? "" : textOf(body);
|
|
298
|
+
const held = scrollLock(text, { noun: it, path, sheet: stylesheet, budget });
|
|
299
|
+
if (budget.spent) {
|
|
300
|
+
break;
|
|
301
|
+
}
|
|
302
|
+
checked += 1;
|
|
303
|
+
if (held !== null) {
|
|
304
|
+
findings.push({
|
|
305
|
+
rule: "scroll-lock",
|
|
306
|
+
severity: "warning",
|
|
307
|
+
message: held.message,
|
|
308
|
+
path: held.path ?? path,
|
|
309
|
+
line: held.line,
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
const unchecked = pages.size - checked;
|
|
314
|
+
if (unchecked > 0) {
|
|
315
|
+
findings.push({
|
|
316
|
+
rule: "scroll-lock",
|
|
317
|
+
severity: "warning",
|
|
318
|
+
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.`,
|
|
319
|
+
});
|
|
320
|
+
}
|
|
304
321
|
return findings;
|
|
305
322
|
}
|
|
306
323
|
/** Where a finding is, for the agent: `about.html line 3: `. */
|
package/dist/check/lint.d.ts
CHANGED
|
@@ -4,7 +4,7 @@ import type { PortholeConfig } from "../config/schema.ts";
|
|
|
4
4
|
* the agent fixes it before anyone sees it. Pure: any runtime. Errors are only what certainly
|
|
5
5
|
* fails or is cut (`refuseOn: "error"` refuses those); the rest are warnings.
|
|
6
6
|
*/
|
|
7
|
-
export type LintRule = "size" | "document" | "nested-frame" | "document-write" | "clipboard" | "dialog" | "form" | "egress" | "unpinned" | "position-fixed" | "new-window";
|
|
7
|
+
export type LintRule = "size" | "document" | "nested-frame" | "document-write" | "clipboard" | "dialog" | "form" | "egress" | "unpinned" | "position-fixed" | "scroll-lock" | "new-window";
|
|
8
8
|
export interface Finding {
|
|
9
9
|
readonly rule: LintRule;
|
|
10
10
|
readonly severity: "error" | "warning";
|
|
@@ -19,3 +19,10 @@ export interface Finding {
|
|
|
19
19
|
*/
|
|
20
20
|
export declare function fragmentOf(content: string): string | null;
|
|
21
21
|
export declare function lintContent(config: PortholeConfig, content: string): Finding[];
|
|
22
|
+
/**
|
|
23
|
+
* `lintContent`, with or without the scroll-lock rule: `lintFiles` reads that one itself, once,
|
|
24
|
+
* with the stylesheets the page links.
|
|
25
|
+
*/
|
|
26
|
+
export declare function lintPage(config: PortholeConfig, content: string, options: {
|
|
27
|
+
readonly scrollLock: boolean;
|
|
28
|
+
}): Finding[];
|
package/dist/check/lint.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { anyHttps, declaredCapabilities, egressOrigins, librarySources, } from "../compile/policy.js";
|
|
2
2
|
import { sizeWords } from "../guide/limits.js";
|
|
3
3
|
import { originMatchesSource } from "../isolation/served.js";
|
|
4
|
+
import { scrollLock } from "./scroll.js";
|
|
4
5
|
const lineOf = (text, index) => text.slice(0, index).split("\n").length;
|
|
5
6
|
const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
6
7
|
/** A whole document's markers: what a fragment must not have. */
|
|
@@ -71,6 +72,13 @@ const OWN_CDN = [
|
|
|
71
72
|
{ name: "Plotly", host: /^https:\/\/cdn\.plot\.ly\/plotly/u, pinned: /\d+\.\d+\.\d+/u },
|
|
72
73
|
];
|
|
73
74
|
export function lintContent(config, content) {
|
|
75
|
+
return lintPage(config, content, { scrollLock: true });
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* `lintContent`, with or without the scroll-lock rule: `lintFiles` reads that one itself, once,
|
|
79
|
+
* with the stylesheets the page links.
|
|
80
|
+
*/
|
|
81
|
+
export function lintPage(config, content, options) {
|
|
74
82
|
if (config.mode === "url") {
|
|
75
83
|
return [];
|
|
76
84
|
}
|
|
@@ -159,6 +167,16 @@ export function lintContent(config, content) {
|
|
|
159
167
|
add("position-fixed", "warning", `No position: fixed: the frame grows with the ${it}'s content, so a fixed element covers it. Use position: sticky or normal flow.`, fixed.index);
|
|
160
168
|
}
|
|
161
169
|
}
|
|
170
|
+
// Its own styles holding it to one screen (P106): a warning, as a one-screen app means it.
|
|
171
|
+
const held = options.scrollLock ? scrollLock(content, { noun: it }) : null;
|
|
172
|
+
if (held !== null) {
|
|
173
|
+
findings.push({
|
|
174
|
+
rule: "scroll-lock",
|
|
175
|
+
severity: "warning",
|
|
176
|
+
message: held.message,
|
|
177
|
+
line: held.line,
|
|
178
|
+
});
|
|
179
|
+
}
|
|
162
180
|
const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);
|
|
163
181
|
if (opens !== null && !declared.has("openLink")) {
|
|
164
182
|
add("new-window", "warning", "Nothing opens a new window here (window.open returns null, target=_blank does nothing): show it inline.", opens.index);
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Reading markup without parsing it: what the checks share. Linear, however it was written. */
|
|
2
|
+
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
3
|
+
export declare function attributesOf(text: string): {
|
|
4
|
+
name: string;
|
|
5
|
+
value: string;
|
|
6
|
+
at: number;
|
|
7
|
+
}[];
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/** Reading markup without parsing it: what the checks share. Linear, however it was written. */
|
|
2
|
+
const isSpace = (code) => code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
3
|
+
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
4
|
+
export function attributesOf(text) {
|
|
5
|
+
const out = [];
|
|
6
|
+
let at = 0;
|
|
7
|
+
while (at < text.length) {
|
|
8
|
+
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
9
|
+
at += 1;
|
|
10
|
+
}
|
|
11
|
+
const nameStart = at;
|
|
12
|
+
while (at < text.length &&
|
|
13
|
+
!isSpace(text.charCodeAt(at)) &&
|
|
14
|
+
text[at] !== "=" &&
|
|
15
|
+
text[at] !== "/") {
|
|
16
|
+
at += 1;
|
|
17
|
+
}
|
|
18
|
+
const name = text.slice(nameStart, at).toLowerCase();
|
|
19
|
+
if (name === "") {
|
|
20
|
+
at += 1;
|
|
21
|
+
continue;
|
|
22
|
+
}
|
|
23
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
24
|
+
at += 1;
|
|
25
|
+
}
|
|
26
|
+
if (text[at] !== "=") {
|
|
27
|
+
continue;
|
|
28
|
+
}
|
|
29
|
+
at += 1;
|
|
30
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
31
|
+
at += 1;
|
|
32
|
+
}
|
|
33
|
+
const quote = text[at];
|
|
34
|
+
if (quote === '"' || quote === "'") {
|
|
35
|
+
const close = text.indexOf(quote, at + 1);
|
|
36
|
+
const end = close < 0 ? text.length : close;
|
|
37
|
+
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
38
|
+
at = end + 1;
|
|
39
|
+
}
|
|
40
|
+
else {
|
|
41
|
+
const start = at;
|
|
42
|
+
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
43
|
+
at += 1;
|
|
44
|
+
}
|
|
45
|
+
out.push({ name, value: text.slice(start, at), at: start });
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
return out;
|
|
49
|
+
}
|