@botiverse/porthole 0.14.8 → 0.14.10
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/CHANGELOG.md +46 -0
- package/dist/annotate/types.d.ts +33 -2
- package/dist/annotate/validate.d.ts +6 -1
- package/dist/annotate/validate.js +31 -3
- package/dist/bridge/bridge.d.ts +6 -0
- package/dist/bridge/bridge.js +5 -0
- package/dist/check/page-source.js +1 -1
- package/dist/config/capabilities.d.ts +16 -2
- package/dist/config/capabilities.js +8 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/find/types.d.ts +83 -0
- package/dist/find/types.js +29 -0
- package/dist/find/validate.d.ts +17 -0
- package/dist/find/validate.js +82 -0
- package/dist/guide/guide.js +2 -1
- package/dist/host/create-host.js +219 -3
- package/dist/host/pass-on.js +3 -2
- package/dist/host/types.d.ts +54 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -1
- package/dist/react/frame.d.ts +45 -1
- package/dist/react/frame.js +107 -3
- package/dist/react/view.js +2 -0
- package/dist/runtime/contract.d.ts +1 -1
- package/dist/runtime/contract.js +1 -1
- package/dist/shell/annotate.d.ts +5 -1
- package/dist/shell/annotate.js +41 -107
- package/dist/shell/document.d.ts +3 -3
- package/dist/shell/document.js +5 -3
- package/dist/shell/find.d.ts +82 -0
- package/dist/shell/find.js +725 -0
- package/dist/shell/runtime.js +4 -1
- package/dist/shell/text.d.ts +17 -0
- package/dist/shell/text.js +140 -0
- package/docs/ADOPTING.md +112 -0
- package/docs/ARCHITECTURE.md +10 -3
- package/docs/DECISIONS.md +284 -1
- package/docs/DESIGN.md +48 -2
- package/docs/THREAT_MODEL.md +61 -5
- package/docs/insertion-entry-points.md +17 -0
- package/package.json +1 -1
- package/src/annotate/types.ts +43 -4
- package/src/annotate/validate.ts +34 -3
- package/src/bridge/bridge.ts +7 -0
- package/src/config/capabilities.ts +13 -1
- package/src/find/types.ts +86 -0
- package/src/find/validate.ts +101 -0
- package/src/guide/guide.ts +3 -1
- package/src/host/create-host.ts +235 -3
- package/src/host/pass-on.ts +3 -2
- package/src/host/types.ts +55 -1
- package/src/index.ts +14 -1
- package/src/react/frame.tsx +162 -2
- package/src/react/view.tsx +3 -0
- package/src/runtime/contract.ts +1 -1
- package/src/shell/annotate.ts +42 -107
- package/src/shell/document.ts +5 -3
- package/src/shell/find.ts +731 -0
- package/src/shell/runtime.ts +4 -1
- package/src/shell/text.ts +140 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,52 @@
|
|
|
4
4
|
section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
|
|
5
5
|
P-numbers below.
|
|
6
6
|
|
|
7
|
+
## 0.14.10
|
|
8
|
+
|
|
9
|
+
- **Annotations: a mark's place in the document (P132).** Each attached result of an `anchored`
|
|
10
|
+
report now has a `documentRect` (its box in the document: it stays put as the page scrolls, and
|
|
11
|
+
says where a mark scrolled out of the frame is), and the report a `scroll` (`{ x, y }`, how far
|
|
12
|
+
the document was scrolled as the boxes were read); `rect` is `documentRect` less `scroll`, then
|
|
13
|
+
clamped as before. `tracked` (P112) carries both too, so following one mark tells the document's
|
|
14
|
+
scroll at every animation frame where it changed, whether that mark is in view or not: a host
|
|
15
|
+
places every mark from one report and keeps them placed as the page scrolls, without asking
|
|
16
|
+
again. New exports: `AnnotationScroll`, `parseScroll`. Both fields are optional: an older shell
|
|
17
|
+
sends neither (test for `scroll`), and an older host drops them. Upgrade the content server (the
|
|
18
|
+
shell) for them.
|
|
19
|
+
- **Security (P132):** `documentRect` is the page's word and isn't clamped to the frame (a clamp
|
|
20
|
+
would erase the offscreen places it is for); Porthole checks it as any box (finite, within
|
|
21
|
+
`ANNOTATION_LIMITS.coordinate`, sizes not negative; a malformed one, or a malformed `scroll`,
|
|
22
|
+
drops the report). Clip what you draw from it to the frame's box, or to your own region beside
|
|
23
|
+
it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before. No CSP, sandbox, egress or gate
|
|
24
|
+
changes.
|
|
25
|
+
|
|
26
|
+
## 0.14.9
|
|
27
|
+
|
|
28
|
+
- **Find in page (P131):** a host's own find bar over a display. Declare `find`
|
|
29
|
+
(`capabilities: { find: {} }`; in no preset by default) and use `display.find`: `query(query, {
|
|
30
|
+
direction, caseSensitive })` finds the query in the page's text (case-insensitive, any spacing,
|
|
31
|
+
what is drawn only, at most 1,000), highlights every match and the current one in a layer of the
|
|
32
|
+
shell's own, brings the current one into view, and resolves with `{ total, active, capped?,
|
|
33
|
+
rect? }` or `"unsupported"` (no `find`, an older shell, no answer in 3 s, superseded by a later
|
|
34
|
+
query: the shell searches only the latest of a burst); `clear()`;
|
|
35
|
+
`takeShortcut(true)` makes Cmd+F or Ctrl+F in the frame open the host's bar (`findRequested`)
|
|
36
|
+
instead of the browser's, unless the page handles the key itself. `findUpdated` tells new numbers
|
|
37
|
+
when the page changes. A query holds only for the content it was asked of: a reload, a restart
|
|
38
|
+
after a navigation away, or other content forgets it (clear the host's find bar then), as does
|
|
39
|
+
the React handle for another `content`, `generation`, `document`, `instance` or `config`. Hosts
|
|
40
|
+
should send queries on a pause or Enter, not at every key (ADOPTING). React: `onFindRequested`,
|
|
41
|
+
`onFindUpdated`, and `find`/`clearFind` on the frame's handle. New exports: `FIND_METHODS`,
|
|
42
|
+
`FIND_LIMITS`, `parseFindResult`, `parseFindReport` and their types. The manual tells the agent people may search the page's words.
|
|
43
|
+
- **Security (P131):** the page reads every query the host sends (the search runs in its
|
|
44
|
+
document), so declare `find` only where it may learn what the person searches for; P131 records
|
|
45
|
+
that exposure as accepted. What the frame says back is the page's word; the host
|
|
46
|
+
takes `findRequested` only with the page's focus in the frame (negative control
|
|
47
|
+
`find-requested-focus`). No CSP, sandbox or egress changes. A host must upgrade its content
|
|
48
|
+
server (the shell) for find to work; an older one answers `"unsupported"`. The find runtime and
|
|
49
|
+
the text index it shares with annotations call only built-ins captured before content runs,
|
|
50
|
+
through `callOf` (P129), and the find layer's nodes go in only through the guarded insertion
|
|
51
|
+
methods (P130; listed in [docs/insertion-entry-points.md](docs/insertion-entry-points.md)).
|
|
52
|
+
|
|
7
53
|
## 0.14.8
|
|
8
54
|
|
|
9
55
|
- **Frame guard: broader coverage of DOM insertion and parsing entry points (P130),** listed in
|
package/dist/annotate/types.d.ts
CHANGED
|
@@ -46,7 +46,8 @@ export interface AnnotationAnchor {
|
|
|
46
46
|
* The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
|
|
47
47
|
* outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
|
|
48
48
|
* own layout px: a host that scales or transforms the frame maps it through that transform too
|
|
49
|
-
* (P105).
|
|
49
|
+
* (P105). A result's `documentRect` (P132) is the same shape in the document's coordinates, and
|
|
50
|
+
* isn't clamped.
|
|
50
51
|
*/
|
|
51
52
|
export interface AnnotationRect {
|
|
52
53
|
readonly x: number;
|
|
@@ -54,6 +55,16 @@ export interface AnnotationRect {
|
|
|
54
55
|
readonly width: number;
|
|
55
56
|
readonly height: number;
|
|
56
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* How far the frame's document is scrolled when the boxes beside it were read (P132), CSS px: the
|
|
60
|
+
* top left of the document's root element (`<html>`), from the viewport's, negated (`window.scrollX`
|
|
61
|
+
* and `window.scrollY` on a page whose root has no margin). A box in the viewport is its
|
|
62
|
+
* `documentRect` less this. The page's word, as every box is.
|
|
63
|
+
*/
|
|
64
|
+
export interface AnnotationScroll {
|
|
65
|
+
readonly x: number;
|
|
66
|
+
readonly y: number;
|
|
67
|
+
}
|
|
57
68
|
/** What the person may point at while the host is asking. */
|
|
58
69
|
export interface AnnotateMode {
|
|
59
70
|
/**
|
|
@@ -101,6 +112,14 @@ export interface AnchorResult {
|
|
|
101
112
|
readonly state: AnchorState;
|
|
102
113
|
/** Where it is now, when attached. */
|
|
103
114
|
readonly rect?: AnnotationRect;
|
|
115
|
+
/**
|
|
116
|
+
* Where it is in the document (P132): `rect` as the shell read it, before the host clamped it,
|
|
117
|
+
* plus the report's `scroll`; so it stays where it is as the document scrolls, and says where a
|
|
118
|
+
* mark scrolled out of the frame is. Not clamped to the frame's viewport (an offscreen mark's is
|
|
119
|
+
* outside it: that is its point): a host places its own UI from it only clipped to the frame's
|
|
120
|
+
* box, or to its own region beside the frame. Absent from an older shell. The page's word.
|
|
121
|
+
*/
|
|
122
|
+
readonly documentRect?: AnnotationRect;
|
|
104
123
|
/**
|
|
105
124
|
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
106
125
|
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
@@ -138,16 +157,28 @@ export type AnnotationReport =
|
|
|
138
157
|
| {
|
|
139
158
|
readonly type: "anchored";
|
|
140
159
|
readonly results: readonly AnchorResult[];
|
|
160
|
+
/**
|
|
161
|
+
* How far the document was scrolled as the boxes were read (P132); with it, each attached
|
|
162
|
+
* result has its `documentRect`. Absent from an older shell: its results have no
|
|
163
|
+
* `documentRect` either, and only `rect` says where marks are.
|
|
164
|
+
*/
|
|
165
|
+
readonly scroll?: AnnotationScroll;
|
|
141
166
|
}
|
|
142
167
|
/**
|
|
143
168
|
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
144
169
|
* an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
|
|
145
|
-
* frame. The content's word: where to put a card beside it, nothing more.
|
|
170
|
+
* frame. The content's word: where to put a card beside it, nothing more. A newer shell (P132)
|
|
171
|
+
* adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
|
|
172
|
+
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
173
|
+
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
174
|
+
* `documentRect` for (an `anchored` report's) without asking again.
|
|
146
175
|
*/
|
|
147
176
|
| {
|
|
148
177
|
readonly type: "tracked";
|
|
149
178
|
readonly id: string;
|
|
150
179
|
readonly rect: AnnotationRect;
|
|
180
|
+
readonly documentRect?: AnnotationRect;
|
|
181
|
+
readonly scroll?: AnnotationScroll;
|
|
151
182
|
}
|
|
152
183
|
/**
|
|
153
184
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport } from "./types.ts";
|
|
1
|
+
import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationScroll } from "./types.ts";
|
|
2
2
|
/**
|
|
3
3
|
* An anchor, rebuilt from its known fields; null if any part is malformed or too large. Its label
|
|
4
4
|
* is text for the person, so what they couldn't see is taken out of it (P105: a wordless element's
|
|
@@ -8,6 +8,11 @@ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type Ann
|
|
|
8
8
|
export declare function parseAnchor(value: unknown): AnnotationAnchor | null;
|
|
9
9
|
/** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
|
|
10
10
|
export declare function parseRect(value: unknown): AnnotationRect | null;
|
|
11
|
+
/**
|
|
12
|
+
* How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
|
|
13
|
+
* may be negative: an engine's overscroll); null for anything else.
|
|
14
|
+
*/
|
|
15
|
+
export declare function parseScroll(value: unknown): AnnotationScroll | null;
|
|
11
16
|
/**
|
|
12
17
|
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
13
18
|
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
@@ -88,6 +88,16 @@ export function parseRect(value) {
|
|
|
88
88
|
}
|
|
89
89
|
return { x, y, width, height };
|
|
90
90
|
}
|
|
91
|
+
/**
|
|
92
|
+
* How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
|
|
93
|
+
* may be negative: an engine's overscroll); null for anything else.
|
|
94
|
+
*/
|
|
95
|
+
export function parseScroll(value) {
|
|
96
|
+
if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
|
|
97
|
+
return null;
|
|
98
|
+
}
|
|
99
|
+
return { x: value.x, y: value.y };
|
|
100
|
+
}
|
|
91
101
|
/**
|
|
92
102
|
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
93
103
|
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
@@ -123,7 +133,9 @@ function results(value) {
|
|
|
123
133
|
return null;
|
|
124
134
|
}
|
|
125
135
|
const rect = each.rect === undefined ? undefined : parseRect(each.rect);
|
|
126
|
-
|
|
136
|
+
// Where it is in the document (P132): a box as `rect` is, never clamped.
|
|
137
|
+
const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
|
|
138
|
+
if (rect === null || documentRect === null) {
|
|
127
139
|
return null;
|
|
128
140
|
}
|
|
129
141
|
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
@@ -136,6 +148,7 @@ function results(value) {
|
|
|
136
148
|
id: each.id,
|
|
137
149
|
state: "attached",
|
|
138
150
|
...(rect === undefined ? {} : { rect }),
|
|
151
|
+
...(documentRect === undefined ? {} : { documentRect }),
|
|
139
152
|
...(order === undefined ? {} : { order }),
|
|
140
153
|
});
|
|
141
154
|
}
|
|
@@ -158,7 +171,10 @@ export function parseReport(value) {
|
|
|
158
171
|
return { type: "cancelled" };
|
|
159
172
|
case "anchored": {
|
|
160
173
|
const checked = results(value.results);
|
|
161
|
-
|
|
174
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
175
|
+
return checked === null || scroll === null
|
|
176
|
+
? null
|
|
177
|
+
: { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
|
|
162
178
|
}
|
|
163
179
|
case "activated": {
|
|
164
180
|
const rect = parseRect(value.rect);
|
|
@@ -166,7 +182,19 @@ export function parseReport(value) {
|
|
|
166
182
|
}
|
|
167
183
|
case "tracked": {
|
|
168
184
|
const rect = parseRect(value.rect);
|
|
169
|
-
|
|
185
|
+
// A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
|
|
186
|
+
const documentRect = value.documentRect === undefined ? undefined : parseRect(value.documentRect);
|
|
187
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
188
|
+
if (!markId(value.id) || rect === null || documentRect === null || scroll === null) {
|
|
189
|
+
return null;
|
|
190
|
+
}
|
|
191
|
+
return {
|
|
192
|
+
type: "tracked",
|
|
193
|
+
id: value.id,
|
|
194
|
+
rect,
|
|
195
|
+
...(documentRect === undefined ? {} : { documentRect }),
|
|
196
|
+
...(scroll === undefined ? {} : { scroll }),
|
|
197
|
+
};
|
|
170
198
|
}
|
|
171
199
|
default:
|
|
172
200
|
return null;
|
package/dist/bridge/bridge.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type CapabilityName } from "../config/capabilities.ts";
|
|
2
2
|
import type { AnnotationReport } from "../annotate/types.ts";
|
|
3
|
+
import type { FindReport } from "../find/types.ts";
|
|
3
4
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
4
5
|
import { type PageDeclaration } from "../runtime/declaration.ts";
|
|
5
6
|
import { type ViewerInfo } from "../runtime/levels.ts";
|
|
@@ -34,6 +35,11 @@ export type BridgeEvent = {
|
|
|
34
35
|
} | {
|
|
35
36
|
readonly type: "annotation";
|
|
36
37
|
readonly report: AnnotationReport;
|
|
38
|
+
}
|
|
39
|
+
/** What the frame said of find in page unasked (P131), checked. */
|
|
40
|
+
| {
|
|
41
|
+
readonly type: "find";
|
|
42
|
+
readonly report: FindReport;
|
|
37
43
|
} | {
|
|
38
44
|
readonly type: "refused";
|
|
39
45
|
readonly capability: CapabilityName;
|
package/dist/bridge/bridge.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { MAX_CONTEXT_CHARS, MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
|
|
2
2
|
import { parseReport } from "../annotate/validate.js";
|
|
3
|
+
import { parseFindReport } from "../find/validate.js";
|
|
3
4
|
import { callGates, effectiveGates } from "../compile/policy.js";
|
|
4
5
|
import { boundedText } from "./bounded-text.js";
|
|
5
6
|
import { isJsonData } from "./json-data.js";
|
|
@@ -178,6 +179,7 @@ const VALIDATORS = {
|
|
|
178
179
|
: null;
|
|
179
180
|
},
|
|
180
181
|
annotate: (args) => parseReport(args),
|
|
182
|
+
find: (args) => parseFindReport(args),
|
|
181
183
|
// The runtime's own (P088-P090): their shapes and limits, before any gate.
|
|
182
184
|
user: (args) => (args === undefined || isRecord(args) ? {} : null),
|
|
183
185
|
comments: (args) => parseCommentRequest(args),
|
|
@@ -590,6 +592,9 @@ export function createBridge(options) {
|
|
|
590
592
|
else if (capability === "annotate") {
|
|
591
593
|
onEvent({ type: "annotation", report: args });
|
|
592
594
|
}
|
|
595
|
+
else if (capability === "find") {
|
|
596
|
+
onEvent({ type: "find", report: args });
|
|
597
|
+
}
|
|
593
598
|
else {
|
|
594
599
|
const report = args;
|
|
595
600
|
if (report.navigationBlocked !== undefined) {
|