@botiverse/porthole 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/annotate/types.d.ts +42 -4
  2. package/dist/annotate/types.js +6 -1
  3. package/dist/annotate/validate.d.ts +16 -1
  4. package/dist/annotate/validate.js +33 -3
  5. package/dist/bridge/bridge.js +1 -51
  6. package/dist/bridge/unseen.d.ts +18 -0
  7. package/dist/bridge/unseen.js +71 -0
  8. package/dist/check/page-source.js +1 -1
  9. package/dist/conformance/behavior.js +107 -68
  10. package/dist/conformance/clipboard.js +16 -14
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/conformance/limits.js +117 -64
  13. package/dist/conformance/probes.js +66 -49
  14. package/dist/conformance/served.js +66 -63
  15. package/dist/host/create-host.js +75 -3
  16. package/dist/platform/types.d.ts +12 -1
  17. package/dist/platform/web.js +8 -0
  18. package/dist/react/frame.d.ts +6 -2
  19. package/dist/shell/annotate.d.ts +10 -3
  20. package/dist/shell/annotate.js +610 -39
  21. package/docs/ADOPTING.md +76 -0
  22. package/docs/ARCHITECTURE.md +2 -1
  23. package/docs/DECISIONS.md +516 -1
  24. package/docs/DESIGN.md +178 -20
  25. package/docs/THREAT_MODEL.md +92 -9
  26. package/package.json +1 -1
  27. package/src/annotate/types.ts +39 -5
  28. package/src/annotate/validate.ts +39 -3
  29. package/src/bridge/bridge.ts +1 -60
  30. package/src/bridge/unseen.ts +82 -0
  31. package/src/conformance/behavior.ts +221 -69
  32. package/src/conformance/clipboard.ts +44 -14
  33. package/src/conformance/limits.ts +169 -76
  34. package/src/conformance/probes.ts +97 -49
  35. package/src/conformance/served.ts +112 -63
  36. package/src/host/create-host.ts +75 -3
  37. package/src/platform/types.ts +9 -1
  38. package/src/platform/web.ts +10 -0
  39. package/src/react/frame.tsx +6 -2
  40. package/src/shell/annotate.ts +610 -39
@@ -8,6 +8,7 @@ import {
8
8
  type AnnotationReport,
9
9
  type AnnotationSelector,
10
10
  } from "./types.ts";
11
+ import { withoutUnseen } from "../bridge/unseen.ts";
11
12
 
12
13
  /**
13
14
  * The host's checks on what a frame says about annotations (P053), and on anchors a host stores
@@ -60,7 +61,12 @@ function selector(value: unknown): AnnotationSelector | null {
60
61
  }
61
62
  }
62
63
 
63
- /** An anchor, rebuilt from its known fields; null if any part is malformed or too large. */
64
+ /**
65
+ * An anchor, rebuilt from its known fields; null if any part is malformed or too large. Its label
66
+ * is text for the person, so what they couldn't see is taken out of it (P105: a wordless element's
67
+ * `alt`, `aria-label` or `title`, which the page never shows, can carry bidi controls or zero-width
68
+ * characters); its selectors' words are kept as they are, to be found again.
69
+ */
64
70
  export function parseAnchor(value: unknown): AnnotationAnchor | null {
65
71
  if (!isRecord(value) || (value.kind !== "element" && value.kind !== "text")) {
66
72
  return null;
@@ -85,7 +91,7 @@ export function parseAnchor(value: unknown): AnnotationAnchor | null {
85
91
  if (value.kind === "text" ? !quote : !css && !quote) {
86
92
  return null;
87
93
  }
88
- return { kind: value.kind, selectors, label: value.label };
94
+ return { kind: value.kind, selectors, label: withoutUnseen(value.label) };
89
95
  }
90
96
 
91
97
  const coordinate = (value: unknown): value is number =>
@@ -106,6 +112,27 @@ export function parseRect(value: unknown): AnnotationRect | null {
106
112
  return { x, y, width, height };
107
113
  }
108
114
 
115
+ /**
116
+ * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
117
+ * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
118
+ * wholly outside becomes a box of no size on the nearest edge. Where the viewport isn't known, a
119
+ * box of no size at the frame's corner. The page still chooses any point inside its own frame.
120
+ */
121
+ export function clampRect(
122
+ rect: AnnotationRect,
123
+ viewport: { readonly width: number; readonly height: number } | null | undefined,
124
+ ): AnnotationRect {
125
+ const known = viewport !== null && typeof viewport === "object";
126
+ const width = known && Number.isFinite(viewport.width) ? viewport.width : 0;
127
+ const height = known && Number.isFinite(viewport.height) ? viewport.height : 0;
128
+ const within = (value: number, most: number) => Math.min(Math.max(value, 0), Math.max(0, most));
129
+ const left = within(rect.x, width);
130
+ const top = within(rect.y, height);
131
+ const right = within(rect.x + rect.width, width);
132
+ const bottom = within(rect.y + rect.height, height);
133
+ return { x: left, y: top, width: right - left, height: bottom - top };
134
+ }
135
+
109
136
  const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
110
137
 
111
138
  function results(value: unknown): AnchorResult[] | null {
@@ -152,6 +179,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
152
179
  const checked = results(value.results);
153
180
  return checked === null ? null : { type: "anchored", results: checked };
154
181
  }
182
+ case "activated": {
183
+ const rect = parseRect(value.rect);
184
+ return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
185
+ }
155
186
  default:
156
187
  return null;
157
188
  }
@@ -180,7 +211,12 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
180
211
  `annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
181
212
  );
182
213
  }
214
+ if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
215
+ throw new TypeError(
216
+ `annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
217
+ );
218
+ }
183
219
  seen.add(mark.id);
184
- return { id: mark.id, anchor };
220
+ return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
185
221
  });
186
222
  }
@@ -12,6 +12,7 @@ import type { PortholeConfig } from "../config/schema.ts";
12
12
  import { callGates, effectiveGates } from "../compile/policy.ts";
13
13
  import { boundedText } from "./bounded-text.ts";
14
14
  import { isJsonData } from "./json-data.ts";
15
+ import { unseen } from "./unseen.ts";
15
16
  import { blockedNavigationMessage, cutText, withoutSealedAddresses } from "./navigation.ts";
16
17
  import {
17
18
  RUNTIME_HOST_FUNCTIONS,
@@ -165,66 +166,6 @@ function resourceUri(args: unknown): { uri: string } | null {
165
166
  /** The most text blocks one model context update holds. */
166
167
  const MAX_CONTEXT_BLOCKS = 100;
167
168
 
168
- /**
169
- * What a person can't see but a model reads (the review of P100): format characters (zero-width
170
- * ones, bidi controls, the tags U+E0000–E007F, a soft hyphen, a byte-order mark), variation
171
- * selectors (U+FE00–FE0F, U+E0100–E01EF), private-use characters, lone surrogates, every
172
- * default-ignorable code point (the re-check: U+034F, Mongolian's free variation selectors, the
173
- * 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
174
- * reads to the model differently from what the person was shown.
175
- */
176
- const UNSEEN =
177
- /[\p{Cf}\p{Co}\p{Cs}\p{Default_Ignorable_Code_Point}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]|[^\P{Cc}\n\t]/u;
178
-
179
- /**
180
- * The parts of real emoji that draw as nothing alone, allowed only where an emoji has them (the
181
- * re-review of P100): U+FE0E or U+FE0F directly after a pictograph, or after a keycap base
182
- * (`[0-9#*]`) that U+20E3 follows; U+200D only between two pictographs, a selector or a skin tone
183
- * after the first. Each carries at most one choice beside a visible emoji (a selector there or
184
- * not, a joiner there or not), never letters a model would read. Tag characters stay refused:
185
- * subdivision flags too.
186
- */
187
- const EMOJI_PARTS =
188
- "(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)|(?<=\\p{Extended_Pictographic}[\\uFE0F\\p{Emoji_Modifier}]?)\\u200D(?=\\p{Extended_Pictographic})";
189
-
190
- /**
191
- * The scripts whose letters U+200C and U+200D shape (Unicode's notes on the joiners: the cursive
192
- * scripts, where they break or make a join, and the Indic ones and Myanmar, where they choose a
193
- * conjunct, a half form or a ligature), by Script_Extensions.
194
- */
195
- const SHAPING_SCRIPTS = [
196
- "Arabic",
197
- "Syriac",
198
- "Nko",
199
- "Mongolian",
200
- "Devanagari",
201
- "Bengali",
202
- "Gurmukhi",
203
- "Gujarati",
204
- "Oriya",
205
- "Tamil",
206
- "Telugu",
207
- "Kannada",
208
- "Malayalam",
209
- "Sinhala",
210
- "Myanmar",
211
- ] as const;
212
-
213
- const SHAPED = `[${SHAPING_SCRIPTS.map((name) => `\\p{scx=${name}}`).join("")}]`;
214
-
215
- /**
216
- * A joiner or non-joiner between two letters or marks of those scripts (Persian's می‌خواهم, a
217
- * Hindi half form): the shape it chooses is what the person sees. One at a letter boundary, never
218
- * doubled, first or last, or beside a letter of another script.
219
- */
220
- const SHAPING_JOINERS = `(?<=[\\p{L}\\p{M}])(?<=${SHAPED})[\\u200C\\u200D](?=[\\p{L}\\p{M}])(?=${SHAPED})`;
221
-
222
- /** What may be invisible alone and is allowed where it is seen: one pass, on the text as sent. */
223
- const SEEN_IN_PLACE = new RegExp(`${EMOJI_PARTS}|${SHAPING_JOINERS}`, "gu");
224
-
225
- /** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
226
- const unseen = (text: string): boolean => UNSEEN.test(text.replace(SEEN_IN_PLACE, ""));
227
-
228
169
  /** Whether any string in `value`, a key or a value, holds what can't be seen (bounded JSON data). */
229
170
  function holdsUnseen(value: unknown): boolean {
230
171
  if (typeof value === "string") {
@@ -0,0 +1,82 @@
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
+ /**
7
+ * What a person can't see but a model reads (the review of P100): format characters (zero-width
8
+ * ones, bidi controls, the tags U+E0000–E007F, a soft hyphen, a byte-order mark), variation
9
+ * selectors (U+FE00–FE0F, U+E0100–E01EF), private-use characters, lone surrogates, every
10
+ * default-ignorable code point (the re-check: U+034F, Mongolian's free variation selectors, the
11
+ * 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
12
+ * reads to the model differently from what the person was shown.
13
+ */
14
+ const UNSEEN =
15
+ /[\p{Cf}\p{Co}\p{Cs}\p{Default_Ignorable_Code_Point}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]|[^\P{Cc}\n\t]/u;
16
+
17
+ /**
18
+ * The parts of real emoji that draw as nothing alone, allowed only where an emoji has them (the
19
+ * re-review of P100): U+FE0E or U+FE0F directly after a pictograph, or after a keycap base
20
+ * (`[0-9#*]`) that U+20E3 follows; U+200D only between two pictographs, a selector or a skin tone
21
+ * after the first. Each carries at most one choice beside a visible emoji (a selector there or
22
+ * not, a joiner there or not), never letters a model would read. Tag characters stay refused:
23
+ * subdivision flags too.
24
+ */
25
+ const EMOJI_PARTS =
26
+ "(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)|(?<=\\p{Extended_Pictographic}[\\uFE0F\\p{Emoji_Modifier}]?)\\u200D(?=\\p{Extended_Pictographic})";
27
+
28
+ /**
29
+ * The scripts whose letters U+200C and U+200D shape (Unicode's notes on the joiners: the cursive
30
+ * scripts, where they break or make a join, and the Indic ones and Myanmar, where they choose a
31
+ * conjunct, a half form or a ligature), by Script_Extensions.
32
+ */
33
+ const SHAPING_SCRIPTS = [
34
+ "Arabic",
35
+ "Syriac",
36
+ "Nko",
37
+ "Mongolian",
38
+ "Devanagari",
39
+ "Bengali",
40
+ "Gurmukhi",
41
+ "Gujarati",
42
+ "Oriya",
43
+ "Tamil",
44
+ "Telugu",
45
+ "Kannada",
46
+ "Malayalam",
47
+ "Sinhala",
48
+ "Myanmar",
49
+ ] as const;
50
+
51
+ const SHAPED = `[${SHAPING_SCRIPTS.map((name) => `\\p{scx=${name}}`).join("")}]`;
52
+
53
+ /**
54
+ * A joiner or non-joiner between two letters or marks of those scripts (Persian's می‌خواهم, a
55
+ * Hindi half form): the shape it chooses is what the person sees. One at a letter boundary, never
56
+ * doubled, first or last, or beside a letter of another script.
57
+ */
58
+ const SHAPING_JOINERS = `(?<=[\\p{L}\\p{M}])(?<=${SHAPED})[\\u200C\\u200D](?=[\\p{L}\\p{M}])(?=${SHAPED})`;
59
+
60
+ /** What may be invisible alone and is allowed where it is seen: one pass, on the text as sent. */
61
+ const SEEN_IN_PLACE = new RegExp(`${EMOJI_PARTS}|${SHAPING_JOINERS}`, "gu");
62
+
63
+ /** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
64
+ export const unseen = (text: string): boolean => UNSEEN.test(text.replace(SEEN_IN_PLACE, ""));
65
+
66
+ /** Every code point `UNSEEN` names, each on its own. */
67
+ const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
68
+
69
+ /**
70
+ * `text` without anything a person can't see (P105), for text Porthole only shows, never matches,
71
+ * as a wordless element's label is (an `alt`, `aria-label` or `title` the person never sees on the
72
+ * page): every format character (bidi controls and the zero-width ones among them), every
73
+ * default-ignorable code point, variation selector, private-use character and lone surrogate, and
74
+ * every control but a new line and a tab. No exceptions: not the parts of emoji, nor the joiners
75
+ * between shaped letters that `unseen` lets by, whose surroundings a page can fake (the review of
76
+ * P105: a Mongolian variation selector beside each joiner carried 48 of them through, a payload
77
+ * of six bytes). An emoji may lose its joiners (a family shows as its faces). Nothing `unseen`
78
+ * refuses is left.
79
+ */
80
+ export function withoutUnseen(text: string): string {
81
+ return text.replace(UNSEEN_EACH, "");
82
+ }