@botiverse/porthole 0.13.0 → 0.14.1
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 +770 -0
- package/dist/annotate/types.d.ts +36 -4
- package/dist/annotate/types.js +6 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +30 -6
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.js +19 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +3 -1
- package/dist/guide/limits.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +78 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +29 -0
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +71 -2
- package/dist/platform/focus-guard.js +187 -12
- package/dist/platform/types.d.ts +8 -1
- package/dist/platform/web.js +60 -4
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +4 -3
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +5 -0
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +59 -0
- package/dist/server/nested.js +96 -0
- package/dist/server/server.js +193 -23
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +4 -3
- package/dist/shell/annotate.js +179 -9
- package/dist/shell/frame.d.ts +45 -0
- package/dist/shell/frame.js +250 -0
- package/dist/shell/plan.js +2 -1
- package/dist/shell/runtime.d.ts +6 -0
- package/dist/shell/runtime.js +60 -15
- package/docs/ADOPTING.md +85 -2
- package/docs/ARCHITECTURE.md +28 -0
- package/docs/DECISIONS.md +416 -1
- package/docs/DESIGN.md +21 -4
- package/docs/THREAT_MODEL.md +102 -5
- package/package.json +6 -5
- package/src/annotate/types.ts +32 -4
- package/src/annotate/validate.ts +34 -8
- package/src/compile/policy.ts +14 -1
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +23 -0
- package/src/displays/displays.ts +3 -1
- package/src/guide/limits.ts +1 -1
- package/src/host/create-host.ts +81 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +27 -0
- package/src/index.ts +4 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +258 -15
- package/src/platform/types.ts +8 -1
- package/src/platform/web.ts +81 -9
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +4 -3
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +14 -0
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +116 -0
- package/src/server/server.ts +224 -21
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +179 -9
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +61 -15
package/dist/annotate/types.d.ts
CHANGED
|
@@ -56,8 +56,13 @@ export interface AnnotationRect {
|
|
|
56
56
|
}
|
|
57
57
|
/** What the person may point at while the host is asking. */
|
|
58
58
|
export interface AnnotateMode {
|
|
59
|
-
/**
|
|
60
|
-
|
|
59
|
+
/**
|
|
60
|
+
* Elements, picked with a click or tap (the one under the pointer is outlined); one pick. Or
|
|
61
|
+
* `"hold"` (P112): a finger held still on a block for 500 ms selects it (reported as `selected`,
|
|
62
|
+
* and the click its release makes never reaches the page); every other tap, and any mouse, is the
|
|
63
|
+
* page's; it lasts until the host stops it.
|
|
64
|
+
*/
|
|
65
|
+
readonly elements?: boolean | "hold";
|
|
61
66
|
/** Text, by selecting it: each settled selection is reported, and its clearing. */
|
|
62
67
|
readonly text?: boolean;
|
|
63
68
|
}
|
|
@@ -71,7 +76,8 @@ export interface AnnotationMark {
|
|
|
71
76
|
readonly anchor: AnnotationAnchor;
|
|
72
77
|
/**
|
|
73
78
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
74
|
-
* `ANNOTATION_LIMITS.count
|
|
79
|
+
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
|
|
80
|
+
* the bubble alone) at the end of a
|
|
75
81
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
76
82
|
* `activated`. The content can read the number; give one only where the page may know it. A
|
|
77
83
|
* draft's is dropped (P107): its marker has no number.
|
|
@@ -95,6 +101,12 @@ export interface AnchorResult {
|
|
|
95
101
|
readonly state: AnchorState;
|
|
96
102
|
/** Where it is now, when attached. */
|
|
97
103
|
readonly rect?: AnnotationRect;
|
|
104
|
+
/**
|
|
105
|
+
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
106
|
+
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
107
|
+
* sort by, never a fact.
|
|
108
|
+
*/
|
|
109
|
+
readonly order?: number;
|
|
98
110
|
}
|
|
99
111
|
/** What the frame reports, once the host has checked it. */
|
|
100
112
|
export type AnnotationReport =
|
|
@@ -108,7 +120,11 @@ export type AnnotationReport =
|
|
|
108
120
|
| {
|
|
109
121
|
readonly type: "unselected";
|
|
110
122
|
}
|
|
111
|
-
/**
|
|
123
|
+
/**
|
|
124
|
+
* The person pressed Escape while picking an element (the pick ends), or while selecting text
|
|
125
|
+
* (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
|
|
126
|
+
* send it, and the host takes it only while it asked for a pick or for text.
|
|
127
|
+
*/
|
|
112
128
|
| {
|
|
113
129
|
readonly type: "cancelled";
|
|
114
130
|
}
|
|
@@ -123,6 +139,16 @@ export type AnnotationReport =
|
|
|
123
139
|
readonly type: "anchored";
|
|
124
140
|
readonly results: readonly AnchorResult[];
|
|
125
141
|
}
|
|
142
|
+
/**
|
|
143
|
+
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
144
|
+
* 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.
|
|
146
|
+
*/
|
|
147
|
+
| {
|
|
148
|
+
readonly type: "tracked";
|
|
149
|
+
readonly id: string;
|
|
150
|
+
readonly rect: AnnotationRect;
|
|
151
|
+
}
|
|
126
152
|
/**
|
|
127
153
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
128
154
|
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
@@ -153,6 +179,12 @@ export declare const ANNOTATE_METHODS: {
|
|
|
153
179
|
readonly anchored: "porthole/annotate.anchored";
|
|
154
180
|
/** Frame → host: a mark's marker was clicked (P104). */
|
|
155
181
|
readonly activated: "porthole/annotate.activated";
|
|
182
|
+
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
183
|
+
readonly track: "porthole/annotate.track";
|
|
184
|
+
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
185
|
+
readonly tracked: "porthole/annotate.tracked";
|
|
186
|
+
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
187
|
+
readonly clearSelection: "porthole/annotate.clearSelection";
|
|
156
188
|
};
|
|
157
189
|
/** The most of each part of an anchor or report the host takes. */
|
|
158
190
|
export declare const ANNOTATION_LIMITS: {
|
package/dist/annotate/types.js
CHANGED
|
@@ -30,6 +30,12 @@ export const ANNOTATE_METHODS = {
|
|
|
30
30
|
anchored: "porthole/annotate.anchored",
|
|
31
31
|
/** Frame → host: a mark's marker was clicked (P104). */
|
|
32
32
|
activated: "porthole/annotate.activated",
|
|
33
|
+
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
34
|
+
track: "porthole/annotate.track",
|
|
35
|
+
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
36
|
+
tracked: "porthole/annotate.tracked",
|
|
37
|
+
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
38
|
+
clearSelection: "porthole/annotate.clearSelection",
|
|
33
39
|
};
|
|
34
40
|
/** The most of each part of an anchor or report the host takes. */
|
|
35
41
|
export const ANNOTATION_LIMITS = {
|
|
@@ -28,7 +28,8 @@ export declare function annotateMode(mode: AnnotateMode | undefined): Required<A
|
|
|
28
28
|
*/
|
|
29
29
|
export declare const hasMarker: (mark: AnnotationMark) => boolean;
|
|
30
30
|
/**
|
|
31
|
-
* The host's marks, checked before they go to the frame; throws on the first bad one
|
|
31
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one (a count above
|
|
32
|
+
* `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
|
|
32
33
|
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
33
34
|
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
34
35
|
* told one).
|
|
@@ -126,7 +126,18 @@ function results(value) {
|
|
|
126
126
|
if (rect === null) {
|
|
127
127
|
return null;
|
|
128
128
|
}
|
|
129
|
-
|
|
129
|
+
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
130
|
+
const order = each.order;
|
|
131
|
+
if (order !== undefined &&
|
|
132
|
+
!(typeof order === "number" && Number.isInteger(order) && order >= 0 && order < LIMITS.marks)) {
|
|
133
|
+
return null;
|
|
134
|
+
}
|
|
135
|
+
out.push({
|
|
136
|
+
id: each.id,
|
|
137
|
+
state: "attached",
|
|
138
|
+
...(rect === undefined ? {} : { rect }),
|
|
139
|
+
...(order === undefined ? {} : { order }),
|
|
140
|
+
});
|
|
130
141
|
}
|
|
131
142
|
return out;
|
|
132
143
|
}
|
|
@@ -153,6 +164,10 @@ export function parseReport(value) {
|
|
|
153
164
|
const rect = parseRect(value.rect);
|
|
154
165
|
return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
|
|
155
166
|
}
|
|
167
|
+
case "tracked": {
|
|
168
|
+
const rect = parseRect(value.rect);
|
|
169
|
+
return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
|
|
170
|
+
}
|
|
156
171
|
default:
|
|
157
172
|
return null;
|
|
158
173
|
}
|
|
@@ -161,7 +176,9 @@ export function parseReport(value) {
|
|
|
161
176
|
export function annotateMode(mode) {
|
|
162
177
|
const elements = mode?.elements ?? true;
|
|
163
178
|
const words = mode?.text ?? true;
|
|
164
|
-
if (typeof elements !== "boolean"
|
|
179
|
+
if ((typeof elements !== "boolean" && elements !== "hold") ||
|
|
180
|
+
typeof words !== "boolean" ||
|
|
181
|
+
(elements === false && !words)) {
|
|
165
182
|
throw new TypeError("annotations.start: elements, text, or both");
|
|
166
183
|
}
|
|
167
184
|
return { elements, text: words };
|
|
@@ -172,7 +189,8 @@ export function annotateMode(mode) {
|
|
|
172
189
|
*/
|
|
173
190
|
export const hasMarker = (mark) => mark.count !== undefined || mark.kind === "draft";
|
|
174
191
|
/**
|
|
175
|
-
* The host's marks, checked before they go to the frame; throws on the first bad one
|
|
192
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one (a count above
|
|
193
|
+
* `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
|
|
176
194
|
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
177
195
|
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
178
196
|
* told one).
|
|
@@ -187,8 +205,10 @@ export function checkMarks(marks) {
|
|
|
187
205
|
if (!markId(mark?.id) || seen.has(mark.id) || anchor === null) {
|
|
188
206
|
throw new TypeError(`annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`);
|
|
189
207
|
}
|
|
190
|
-
|
|
191
|
-
|
|
208
|
+
// A count above the limit is clamped to it (P116): the marker reads "99+" either way, and a
|
|
209
|
+
// count is data anyone can grow (a thread's replies), so it mustn't reject the whole list.
|
|
210
|
+
if (mark.count !== undefined && !count(mark.count, Infinity)) {
|
|
211
|
+
throw new TypeError(`annotations.show: mark ${index}'s count is a whole number, 0 or more`);
|
|
192
212
|
}
|
|
193
213
|
const kind = mark.kind;
|
|
194
214
|
if (kind !== undefined && kind !== "posted" && kind !== "draft") {
|
|
@@ -198,6 +218,10 @@ export function checkMarks(marks) {
|
|
|
198
218
|
if (kind === "draft") {
|
|
199
219
|
return { id: mark.id, anchor, kind };
|
|
200
220
|
}
|
|
201
|
-
return {
|
|
221
|
+
return {
|
|
222
|
+
id: mark.id,
|
|
223
|
+
anchor,
|
|
224
|
+
...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
|
|
225
|
+
};
|
|
202
226
|
});
|
|
203
227
|
}
|