@botiverse/porthole 0.16.0 → 0.16.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 +12 -0
- package/dist/annotate/types.d.ts +15 -1
- package/dist/annotate/validate.js +19 -1
- package/dist/bridge/types.d.ts +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -1
- package/dist/platform/types.d.ts +1 -1
- package/dist/shell/annotate.d.ts +3 -0
- package/dist/shell/annotate.js +15 -5
- package/docs/ADOPTING.md +393 -980
- package/docs/DECISIONS.md +57 -0
- package/docs/DESIGN.md +1099 -1336
- package/docs/PRINCIPLES.md +85 -1
- package/docs/THREAT_MODEL.md +655 -997
- package/package.json +1 -1
- package/src/annotate/types.ts +12 -1
- package/src/annotate/validate.ts +23 -1
- package/src/bridge/types.ts +1 -1
- package/src/host/create-host.ts +2 -1
- package/src/platform/types.ts +1 -1
- package/src/shell/annotate.ts +15 -5
- package/docs/ARCHITECTURE.md +0 -326
- package/docs/OBJECTIVES.md +0 -116
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,18 @@
|
|
|
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.16.1
|
|
8
|
+
|
|
9
|
+
- **An element pick says where it was picked** (P150, amends P133). An element pick's
|
|
10
|
+
`selected` report carries an optional `pointDocument`: the click, tap or hold point, in
|
|
11
|
+
`documentRect`'s document coordinates, sent only beside `scroll`; a keyboard pick carries none,
|
|
12
|
+
and nor does a text selection. A host may place its own UI there, for an element larger than
|
|
13
|
+
most of the frame, clipping it to the frame as it does `documentRect`. It is the page's word and
|
|
14
|
+
grants nothing; no isolation wall changes. A report whose point is malformed, has no `scroll`,
|
|
15
|
+
or sits on a text selection is dropped (`annotate:invalid`).
|
|
16
|
+
**For a host:** nothing to change; read `pointDocument` if you place UI on a pick. The
|
|
17
|
+
annotation script every served page carries changed with it (its pinned hash, P145).
|
|
18
|
+
|
|
7
19
|
## 0.16.0
|
|
8
20
|
|
|
9
21
|
**Breaking.** What guessed at the person's intent is taken out (P149; supersedes P111, P114,
|
package/dist/annotate/types.d.ts
CHANGED
|
@@ -47,7 +47,8 @@ export interface AnnotationAnchor {
|
|
|
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
49
|
* (P105). A result's `documentRect` (P132) and a report's `lastLineDocumentRect` (P133) are the
|
|
50
|
-
* same shape in the document's coordinates, and aren't clamped
|
|
50
|
+
* same shape in the document's coordinates, and aren't clamped; nor is a pick's `pointDocument`
|
|
51
|
+
* (P150), a point there.
|
|
51
52
|
*/
|
|
52
53
|
export interface AnnotationRect {
|
|
53
54
|
readonly x: number;
|
|
@@ -168,6 +169,19 @@ export type AnnotationReport =
|
|
|
168
169
|
readonly rect: AnnotationRect;
|
|
169
170
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
170
171
|
readonly scroll?: AnnotationScroll;
|
|
172
|
+
/**
|
|
173
|
+
* Where the person picked the element (P150): the point a click, a tap or a held finger
|
|
174
|
+
* picked it at, in the coordinates of `documentRect` (the point in the frame's viewport plus
|
|
175
|
+
* `scroll`), unclamped. For a host's UI by what was pointed at, where the element is larger
|
|
176
|
+
* than most of the frame: its place in the frame's viewport is this less `scroll`, which a
|
|
177
|
+
* host clips to the frame's box. Element picks only (a text selection that carries one is
|
|
178
|
+
* dropped), never without `scroll` (P137), and absent from a pick from the keyboard and from
|
|
179
|
+
* an older shell. The page's word: where to put the host's own UI, nothing more.
|
|
180
|
+
*/
|
|
181
|
+
readonly pointDocument?: {
|
|
182
|
+
readonly x: number;
|
|
183
|
+
readonly y: number;
|
|
184
|
+
};
|
|
171
185
|
}
|
|
172
186
|
/** The text selection went away. */
|
|
173
187
|
| {
|
|
@@ -93,6 +93,13 @@ export function parseRect(value) {
|
|
|
93
93
|
* may be negative: an engine's overscroll); null for anything else.
|
|
94
94
|
*/
|
|
95
95
|
export function parseScroll(value) {
|
|
96
|
+
return parsePoint(value);
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* A point (a pick's `pointDocument`, P150): two finite numbers within the coordinate limit, as a
|
|
100
|
+
* scroll is; null for anything else.
|
|
101
|
+
*/
|
|
102
|
+
function parsePoint(value) {
|
|
96
103
|
if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
|
|
97
104
|
return null;
|
|
98
105
|
}
|
|
@@ -193,19 +200,30 @@ export function parseReport(value) {
|
|
|
193
200
|
? undefined
|
|
194
201
|
: parseRect(value.lastLineDocumentRect);
|
|
195
202
|
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
196
|
-
|
|
203
|
+
// Where an element was picked (P150), in the document as the last line is.
|
|
204
|
+
const pointDocument = value.pointDocument === undefined ? undefined : parsePoint(value.pointDocument);
|
|
205
|
+
if (anchor === null ||
|
|
206
|
+
rect === null ||
|
|
207
|
+
lastLineDocumentRect === null ||
|
|
208
|
+
scroll === null ||
|
|
209
|
+
pointDocument === null) {
|
|
197
210
|
return null;
|
|
198
211
|
}
|
|
199
212
|
// A pair, here (P137): a selection has never had one without the other.
|
|
200
213
|
if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
|
|
201
214
|
return null;
|
|
202
215
|
}
|
|
216
|
+
// A point only for an element, and with its scroll (P150, as P137): text has no point.
|
|
217
|
+
if (pointDocument !== undefined && (anchor.kind !== "element" || scroll === undefined)) {
|
|
218
|
+
return null;
|
|
219
|
+
}
|
|
203
220
|
return {
|
|
204
221
|
type: "selected",
|
|
205
222
|
anchor,
|
|
206
223
|
rect,
|
|
207
224
|
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
208
225
|
...(scroll === undefined ? {} : { scroll }),
|
|
226
|
+
...(pointDocument === undefined ? {} : { pointDocument }),
|
|
209
227
|
};
|
|
210
228
|
}
|
|
211
229
|
case "unselected":
|
package/dist/bridge/types.d.ts
CHANGED
|
@@ -5,7 +5,7 @@ import type { DeclaredData, DeclaredDb } from "../runtime/declaration.ts";
|
|
|
5
5
|
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
6
6
|
import type { RefusalReason } from "./refusal.ts";
|
|
7
7
|
/**
|
|
8
|
-
* The host-function bridge (
|
|
8
|
+
* The host-function bridge (DESIGN.md § Framework layer): carries a capability call from the
|
|
9
9
|
* frame to the host's handler and its result back, checking at the boundary that the capability
|
|
10
10
|
* is declared, that its arguments are well formed, and that every gate passes, in that order.
|
|
11
11
|
* Adapters decode protocol messages into calls; the bridge alone decides whether they run.
|