@botiverse/porthole 0.8.0 → 0.9.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 +40 -4
- package/dist/annotate/types.js +6 -1
- package/dist/annotate/validate.d.ts +10 -0
- package/dist/annotate/validate.js +24 -1
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +33 -3
- package/dist/platform/types.d.ts +9 -0
- package/dist/platform/web.js +8 -0
- package/dist/react/frame.d.ts +6 -2
- package/dist/shell/annotate.d.ts +7 -2
- package/dist/shell/annotate.js +233 -15
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +155 -1
- package/docs/DESIGN.md +35 -5
- package/docs/THREAT_MODEL.md +39 -3
- package/package.json +1 -1
- package/src/annotate/types.ts +37 -5
- package/src/annotate/validate.ts +30 -1
- package/src/host/create-host.ts +35 -3
- package/src/platform/types.ts +6 -0
- package/src/platform/web.ts +10 -0
- package/src/react/frame.tsx +6 -2
- package/src/shell/annotate.ts +233 -15
package/dist/annotate/types.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Annotations (P053): a person points at part of a display (an element, or text they select) to
|
|
3
|
-
* comment on it, and the host marks the anchors already made
|
|
3
|
+
* comment on it, and the host marks the anchors already made, each with a clickable marker and a
|
|
4
|
+
* number where it gives a count (P104). The host drives the shell with
|
|
4
5
|
* Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
|
|
5
6
|
* are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
|
|
6
7
|
* content changes; finding it is best-effort, and says so (`orphaned`).
|
|
@@ -40,7 +41,11 @@ export interface AnnotationAnchor {
|
|
|
40
41
|
/** A short description for the host to show ("h2#revenue Revenue grew 12%"); the content's. */
|
|
41
42
|
readonly label: string;
|
|
42
43
|
}
|
|
43
|
-
/**
|
|
44
|
+
/**
|
|
45
|
+
* A box in the frame's viewport, CSS px: add the frame element's position to place it on the page.
|
|
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.
|
|
48
|
+
*/
|
|
44
49
|
export interface AnnotationRect {
|
|
45
50
|
readonly x: number;
|
|
46
51
|
readonly y: number;
|
|
@@ -54,10 +59,21 @@ export interface AnnotateMode {
|
|
|
54
59
|
/** Text, by selecting it: each settled selection is reported, and its clearing. */
|
|
55
60
|
readonly text?: boolean;
|
|
56
61
|
}
|
|
57
|
-
/**
|
|
62
|
+
/**
|
|
63
|
+
* An anchor the host marks in the frame, under its own id. Everything here is sent into the
|
|
64
|
+
* frame, so the content can read it: give ids that say nothing (never a person's name or the
|
|
65
|
+
* comment's words).
|
|
66
|
+
*/
|
|
58
67
|
export interface AnnotationMark {
|
|
59
68
|
readonly id: string;
|
|
60
69
|
readonly anchor: AnnotationAnchor;
|
|
70
|
+
/**
|
|
71
|
+
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
72
|
+
* `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
|
|
73
|
+
* 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.
|
|
75
|
+
*/
|
|
76
|
+
readonly count?: number;
|
|
61
77
|
}
|
|
62
78
|
/** Whether a mark's anchor was found in the content as it is now. */
|
|
63
79
|
export type AnchorState = "attached" | "orphaned";
|
|
@@ -83,10 +99,26 @@ export type AnnotationReport =
|
|
|
83
99
|
| {
|
|
84
100
|
readonly type: "cancelled";
|
|
85
101
|
}
|
|
86
|
-
/**
|
|
102
|
+
/**
|
|
103
|
+
* 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`, once a
|
|
105
|
+
* scroll, a resize or a change of the content has settled, only the marks that moved since the
|
|
106
|
+
* host was last told, at most once a second (P104).
|
|
107
|
+
*/
|
|
87
108
|
| {
|
|
88
109
|
readonly type: "anchored";
|
|
89
110
|
readonly results: readonly AnchorResult[];
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* The person clicked the marker of a mark the host shows with a `count` (P104); `rect` is the
|
|
114
|
+
* marker's box, to open the host's own UI beside it. The content can fake it for any mark the
|
|
115
|
+
* host shows with a count, and can tell a real one happened: open the host's own view of that
|
|
116
|
+
* mark, never act on it.
|
|
117
|
+
*/
|
|
118
|
+
| {
|
|
119
|
+
readonly type: "activated";
|
|
120
|
+
readonly id: string;
|
|
121
|
+
readonly rect: AnnotationRect;
|
|
90
122
|
};
|
|
91
123
|
/** Porthole's own messages for annotations (own-prefixed, P002). */
|
|
92
124
|
export declare const ANNOTATE_METHODS: {
|
|
@@ -105,6 +137,8 @@ export declare const ANNOTATE_METHODS: {
|
|
|
105
137
|
readonly unselected: "porthole/annotate.unselected";
|
|
106
138
|
readonly cancelled: "porthole/annotate.cancelled";
|
|
107
139
|
readonly anchored: "porthole/annotate.anchored";
|
|
140
|
+
/** Frame → host: a mark's marker was clicked (P104). */
|
|
141
|
+
readonly activated: "porthole/annotate.activated";
|
|
108
142
|
};
|
|
109
143
|
/** The most of each part of an anchor or report the host takes. */
|
|
110
144
|
export declare const ANNOTATION_LIMITS: {
|
|
@@ -117,4 +151,6 @@ export declare const ANNOTATION_LIMITS: {
|
|
|
117
151
|
readonly id: 128;
|
|
118
152
|
readonly position: 50000000;
|
|
119
153
|
readonly coordinate: 10000000;
|
|
154
|
+
/** The largest `count` a mark's marker takes (P104). */
|
|
155
|
+
readonly count: 999;
|
|
120
156
|
};
|
package/dist/annotate/types.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Annotations (P053): a person points at part of a display (an element, or text they select) to
|
|
3
|
-
* comment on it, and the host marks the anchors already made
|
|
3
|
+
* comment on it, and the host marks the anchors already made, each with a clickable marker and a
|
|
4
|
+
* number where it gives a count (P104). The host drives the shell with
|
|
4
5
|
* Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
|
|
5
6
|
* are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
|
|
6
7
|
* content changes; finding it is best-effort, and says so (`orphaned`).
|
|
@@ -27,6 +28,8 @@ export const ANNOTATE_METHODS = {
|
|
|
27
28
|
unselected: "porthole/annotate.unselected",
|
|
28
29
|
cancelled: "porthole/annotate.cancelled",
|
|
29
30
|
anchored: "porthole/annotate.anchored",
|
|
31
|
+
/** Frame → host: a mark's marker was clicked (P104). */
|
|
32
|
+
activated: "porthole/annotate.activated",
|
|
30
33
|
};
|
|
31
34
|
/** The most of each part of an anchor or report the host takes. */
|
|
32
35
|
export const ANNOTATION_LIMITS = {
|
|
@@ -39,4 +42,6 @@ export const ANNOTATION_LIMITS = {
|
|
|
39
42
|
id: 128,
|
|
40
43
|
position: 50_000_000,
|
|
41
44
|
coordinate: 10_000_000,
|
|
45
|
+
/** The largest `count` a mark's marker takes (P104). */
|
|
46
|
+
count: 999,
|
|
42
47
|
};
|
|
@@ -3,6 +3,16 @@ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type Ann
|
|
|
3
3
|
export declare function parseAnchor(value: unknown): AnnotationAnchor | null;
|
|
4
4
|
/** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
|
|
5
5
|
export declare function parseRect(value: unknown): AnnotationRect | null;
|
|
6
|
+
/**
|
|
7
|
+
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
8
|
+
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
9
|
+
* wholly outside becomes a box of no size on the nearest edge. Where the viewport isn't known, a
|
|
10
|
+
* box of no size at the frame's corner. The page still chooses any point inside its own frame.
|
|
11
|
+
*/
|
|
12
|
+
export declare function clampRect(rect: AnnotationRect, viewport: {
|
|
13
|
+
readonly width: number;
|
|
14
|
+
readonly height: number;
|
|
15
|
+
} | undefined): AnnotationRect;
|
|
6
16
|
/** A report from the frame, checked; null if malformed (it is then dropped). */
|
|
7
17
|
export declare function parseReport(value: unknown): AnnotationReport | null;
|
|
8
18
|
/** What the host may start with: elements, text, or both (default both). */
|
|
@@ -82,6 +82,22 @@ export function parseRect(value) {
|
|
|
82
82
|
}
|
|
83
83
|
return { x, y, width, height };
|
|
84
84
|
}
|
|
85
|
+
/**
|
|
86
|
+
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
87
|
+
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
88
|
+
* wholly outside becomes a box of no size on the nearest edge. Where the viewport isn't known, a
|
|
89
|
+
* box of no size at the frame's corner. The page still chooses any point inside its own frame.
|
|
90
|
+
*/
|
|
91
|
+
export function clampRect(rect, viewport) {
|
|
92
|
+
const width = viewport !== undefined && Number.isFinite(viewport.width) ? viewport.width : 0;
|
|
93
|
+
const height = viewport !== undefined && Number.isFinite(viewport.height) ? viewport.height : 0;
|
|
94
|
+
const within = (value, most) => Math.min(Math.max(value, 0), Math.max(0, most));
|
|
95
|
+
const left = within(rect.x, width);
|
|
96
|
+
const top = within(rect.y, height);
|
|
97
|
+
const right = within(rect.x + rect.width, width);
|
|
98
|
+
const bottom = within(rect.y + rect.height, height);
|
|
99
|
+
return { x: left, y: top, width: right - left, height: bottom - top };
|
|
100
|
+
}
|
|
85
101
|
const markId = (value) => text(value, LIMITS.id, 1);
|
|
86
102
|
function results(value) {
|
|
87
103
|
if (!Array.isArray(value) || value.length > LIMITS.marks) {
|
|
@@ -126,6 +142,10 @@ export function parseReport(value) {
|
|
|
126
142
|
const checked = results(value.results);
|
|
127
143
|
return checked === null ? null : { type: "anchored", results: checked };
|
|
128
144
|
}
|
|
145
|
+
case "activated": {
|
|
146
|
+
const rect = parseRect(value.rect);
|
|
147
|
+
return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
|
|
148
|
+
}
|
|
129
149
|
default:
|
|
130
150
|
return null;
|
|
131
151
|
}
|
|
@@ -150,7 +170,10 @@ export function checkMarks(marks) {
|
|
|
150
170
|
if (!markId(mark?.id) || seen.has(mark.id) || anchor === null) {
|
|
151
171
|
throw new TypeError(`annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`);
|
|
152
172
|
}
|
|
173
|
+
if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
|
|
174
|
+
throw new TypeError(`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`);
|
|
175
|
+
}
|
|
153
176
|
seen.add(mark.id);
|
|
154
|
-
return { id: mark.id, anchor };
|
|
177
|
+
return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
|
|
155
178
|
});
|
|
156
179
|
}
|