@botiverse/porthole 0.12.0 → 0.14.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 +32 -3
- package/dist/annotate/types.js +4 -0
- package/dist/annotate/validate.js +19 -2
- package/dist/bridge/bridge.d.ts +8 -1
- package/dist/bridge/bridge.js +7 -0
- package/dist/bridge/unseen.d.ts +8 -0
- package/dist/bridge/unseen.js +17 -0
- package/dist/check/files.js +14 -10
- package/dist/check/lint.js +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +29 -13
- package/dist/check/scroll.js +74 -18
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- 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/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +100 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +37 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.js +5 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +212 -0
- package/dist/platform/focus-guard.js +620 -0
- package/dist/platform/types.d.ts +25 -0
- package/dist/platform/web.js +80 -2
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.js +34 -12
- package/dist/runtime/types.generated.js +1 -1
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +4 -0
- package/dist/server/nested.d.ts +37 -0
- package/dist/server/nested.js +70 -0
- package/dist/server/server.js +57 -7
- package/dist/shell/annotate.d.ts +1 -1
- package/dist/shell/annotate.js +157 -7
- 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.js +49 -14
- package/docs/ADOPTING.md +140 -7
- package/docs/ARCHITECTURE.md +23 -0
- package/docs/DECISIONS.md +564 -5
- package/docs/DESIGN.md +18 -2
- package/docs/THREAT_MODEL.md +192 -30
- package/package.json +1 -1
- package/src/annotate/types.ts +28 -3
- package/src/annotate/validate.ts +23 -2
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +14 -10
- package/src/check/lint.ts +1 -1
- package/src/check/scroll.ts +106 -38
- package/src/compile/policy.ts +14 -1
- package/src/config/capabilities.ts +16 -3
- 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/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +105 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +33 -0
- package/src/index.ts +5 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +815 -0
- package/src/platform/types.ts +24 -0
- package/src/platform/web.ts +96 -2
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +10 -0
- package/src/server/nested.ts +86 -0
- package/src/server/server.ts +65 -6
- package/src/shell/annotate.ts +157 -7
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +49 -14
- package/types/runtime/v1/comments.d.ts +8 -4
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
|
}
|
|
@@ -95,6 +100,12 @@ export interface AnchorResult {
|
|
|
95
100
|
readonly state: AnchorState;
|
|
96
101
|
/** Where it is now, when attached. */
|
|
97
102
|
readonly rect?: AnnotationRect;
|
|
103
|
+
/**
|
|
104
|
+
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
105
|
+
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
106
|
+
* sort by, never a fact.
|
|
107
|
+
*/
|
|
108
|
+
readonly order?: number;
|
|
98
109
|
}
|
|
99
110
|
/** What the frame reports, once the host has checked it. */
|
|
100
111
|
export type AnnotationReport =
|
|
@@ -108,7 +119,11 @@ export type AnnotationReport =
|
|
|
108
119
|
| {
|
|
109
120
|
readonly type: "unselected";
|
|
110
121
|
}
|
|
111
|
-
/**
|
|
122
|
+
/**
|
|
123
|
+
* The person pressed Escape while picking an element (the pick ends), or while selecting text
|
|
124
|
+
* (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
|
|
125
|
+
* send it, and the host takes it only while it asked for a pick or for text.
|
|
126
|
+
*/
|
|
112
127
|
| {
|
|
113
128
|
readonly type: "cancelled";
|
|
114
129
|
}
|
|
@@ -123,6 +138,16 @@ export type AnnotationReport =
|
|
|
123
138
|
readonly type: "anchored";
|
|
124
139
|
readonly results: readonly AnchorResult[];
|
|
125
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
143
|
+
* an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
|
|
144
|
+
* frame. The content's word: where to put a card beside it, nothing more.
|
|
145
|
+
*/
|
|
146
|
+
| {
|
|
147
|
+
readonly type: "tracked";
|
|
148
|
+
readonly id: string;
|
|
149
|
+
readonly rect: AnnotationRect;
|
|
150
|
+
}
|
|
126
151
|
/**
|
|
127
152
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
128
153
|
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
@@ -153,6 +178,10 @@ export declare const ANNOTATE_METHODS: {
|
|
|
153
178
|
readonly anchored: "porthole/annotate.anchored";
|
|
154
179
|
/** Frame → host: a mark's marker was clicked (P104). */
|
|
155
180
|
readonly activated: "porthole/annotate.activated";
|
|
181
|
+
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
182
|
+
readonly track: "porthole/annotate.track";
|
|
183
|
+
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
184
|
+
readonly tracked: "porthole/annotate.tracked";
|
|
156
185
|
};
|
|
157
186
|
/** The most of each part of an anchor or report the host takes. */
|
|
158
187
|
export declare const ANNOTATION_LIMITS: {
|
package/dist/annotate/types.js
CHANGED
|
@@ -30,6 +30,10 @@ 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",
|
|
33
37
|
};
|
|
34
38
|
/** The most of each part of an anchor or report the host takes. */
|
|
35
39
|
export const ANNOTATION_LIMITS = {
|
|
@@ -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 };
|
package/dist/bridge/bridge.d.ts
CHANGED
|
@@ -13,7 +13,8 @@ import type { CapabilityHandlers, Confirm, ConfirmDisplay, Consent, DataCache, H
|
|
|
13
13
|
* every capability its host function's own rate (P091, P095) → arguments well formed and within
|
|
14
14
|
* their limits → who may (P087: the level of each method the call runs for the viewer, a page's
|
|
15
15
|
* named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
|
|
16
|
-
* of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so
|
|
16
|
+
* of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
|
|
17
|
+
* for `comments`, the host page's focus in the calling frame: P109) → the
|
|
17
18
|
* viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
|
|
18
19
|
* shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
|
|
19
20
|
* gave for it, or for a stale-allowed one the host's cache).
|
|
@@ -60,6 +61,12 @@ export interface BridgeOptions {
|
|
|
60
61
|
readonly cached?: DataCache;
|
|
61
62
|
/** Whether the embedding page has user activation now; undefined where it can't tell. */
|
|
62
63
|
readonly userActivation?: () => boolean | undefined;
|
|
64
|
+
/**
|
|
65
|
+
* Whether the embedding page's focus is in this display's frame now (P109); undefined where it
|
|
66
|
+
* can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
|
|
67
|
+
* without it.
|
|
68
|
+
*/
|
|
69
|
+
readonly focused?: () => boolean | undefined;
|
|
63
70
|
readonly onEvent: (event: BridgeEvent) => void;
|
|
64
71
|
/** The clock, in milliseconds (tests pass their own). */
|
|
65
72
|
readonly now?: () => number;
|
package/dist/bridge/bridge.js
CHANGED
|
@@ -12,6 +12,8 @@ import { atLeast, higher } from "../runtime/levels.js";
|
|
|
12
12
|
import { isCodeAsset, parseArtifactRequest, parseAssetRequest, parseCommentRequest, } from "../runtime/requests.js";
|
|
13
13
|
import { defaultReason, isRefused, pendingReason, reasonOf, } from "./refusal.js";
|
|
14
14
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
15
|
+
/** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
|
|
16
|
+
const inFrame = (capability) => capabilitySpec(capability).inFrame === true;
|
|
15
17
|
const MAX_URL = 4_096;
|
|
16
18
|
/**
|
|
17
19
|
* The most confirmations one display has waiting at once (P095): past it a call is refused as
|
|
@@ -448,6 +450,11 @@ export function createBridge(options) {
|
|
|
448
450
|
if (activated === false) {
|
|
449
451
|
return refuse(capability, "no-user-activation");
|
|
450
452
|
}
|
|
453
|
+
// A gesture in this frame, not anywhere on the host's page (P109): the person typing in
|
|
454
|
+
// the host's composer gives its page activation, which a frame's call would borrow.
|
|
455
|
+
if (inFrame(capability) && options.focused?.() === false) {
|
|
456
|
+
return refuse(capability, "no-user-activation");
|
|
457
|
+
}
|
|
451
458
|
}
|
|
452
459
|
if (gates.includes("consent")) {
|
|
453
460
|
const consent = options.consent;
|
package/dist/bridge/unseen.d.ts
CHANGED
|
@@ -16,3 +16,11 @@ export declare const unseen: (text: string) => boolean;
|
|
|
16
16
|
* refuses is left.
|
|
17
17
|
*/
|
|
18
18
|
export declare function withoutUnseen(text: string): string;
|
|
19
|
+
/**
|
|
20
|
+
* Whether `text` holds what a person can't see, for text a page puts in the person's own words (a
|
|
21
|
+
* comment's draft, P109): `unseen`'s list, with only a joiner or non-joiner between two letters or
|
|
22
|
+
* marks let by (in any script: a person's text needs them, and one that draws as nothing there is
|
|
23
|
+
* a bit at most), and a variation selector right after a pictograph or in a keycap (❤️, 1️⃣). A
|
|
24
|
+
* joiner between pictographs (an emoji sequence) is refused: it can join any two.
|
|
25
|
+
*/
|
|
26
|
+
export declare const unseenStrict: (text: string) => boolean;
|
package/dist/bridge/unseen.js
CHANGED
|
@@ -69,3 +69,20 @@ const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
|
|
|
69
69
|
export function withoutUnseen(text) {
|
|
70
70
|
return text.replace(UNSEEN_EACH, "");
|
|
71
71
|
}
|
|
72
|
+
/** A variation selector where an emoji has one: after a pictograph, or in a keycap. */
|
|
73
|
+
const EMOJI_SELECTORS = new RegExp("(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)", "gu");
|
|
74
|
+
/**
|
|
75
|
+
* A joiner or non-joiner with a letter or mark on each side (P109): how Persian separates its
|
|
76
|
+
* letters (میخواهم) and the Indic scripts choose a half form or a conjunct (क्ष, എന്റെ). Never
|
|
77
|
+
* first or last, doubled, beside a space, punctuation or a pictograph: there it shapes nothing, and
|
|
78
|
+
* hides text or makes a blank-looking draft.
|
|
79
|
+
*/
|
|
80
|
+
const LETTER_JOINERS = /(?<=[\p{L}\p{M}])[\u200C\u200D](?=[\p{L}\p{M}])/gu;
|
|
81
|
+
/**
|
|
82
|
+
* Whether `text` holds what a person can't see, for text a page puts in the person's own words (a
|
|
83
|
+
* comment's draft, P109): `unseen`'s list, with only a joiner or non-joiner between two letters or
|
|
84
|
+
* marks let by (in any script: a person's text needs them, and one that draws as nothing there is
|
|
85
|
+
* a bit at most), and a variation selector right after a pictograph or in a keycap (❤️, 1️⃣). A
|
|
86
|
+
* joiner between pictographs (an emoji sequence) is refused: it can join any two.
|
|
87
|
+
*/
|
|
88
|
+
export const unseenStrict = (text) => UNSEEN.test(text.replace(LETTER_JOINERS, "").replace(EMOJI_SELECTORS, ""));
|
package/dist/check/files.js
CHANGED
|
@@ -211,8 +211,10 @@ export function lintFiles(config, files, options = {}) {
|
|
|
211
211
|
}
|
|
212
212
|
}
|
|
213
213
|
};
|
|
214
|
-
// A stylesheet a page links or a stylesheet imports, found in the set by its path (P106).
|
|
215
|
-
|
|
214
|
+
// A stylesheet a page links or a stylesheet imports, found in the set by its path (P106). The
|
|
215
|
+
// fewest characters it may hold first: the rule decodes its text only where it may read it, and
|
|
216
|
+
// nothing keeps it after (P110: kept for the set, one page linking 400 sheets of 240 KB held
|
|
217
|
+
// them all, 200 MB, for the 4 MiB the rule reads).
|
|
216
218
|
const stylesheet = (href, from) => {
|
|
217
219
|
if (href === "" || elsewhere(href) || href.startsWith("/")) {
|
|
218
220
|
return null;
|
|
@@ -222,13 +224,15 @@ export function lintFiles(config, files, options = {}) {
|
|
|
222
224
|
if (sheet === undefined || target === null) {
|
|
223
225
|
return null;
|
|
224
226
|
}
|
|
225
|
-
//
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
227
|
+
// As bytes, at most 3 a character (after a BOM's 3): its fewest characters, and the bytes that
|
|
228
|
+
// hold its first SCANNED.
|
|
229
|
+
return typeof sheet === "string"
|
|
230
|
+
? { path: target, least: sheet.length, text: () => sheet }
|
|
231
|
+
: {
|
|
232
|
+
path: target,
|
|
233
|
+
least: Math.max(0, Math.ceil(sheet.byteLength / 3) - 1),
|
|
234
|
+
text: () => textOf(sheet.subarray(0, 3 * SCANNED + 3)),
|
|
235
|
+
};
|
|
232
236
|
};
|
|
233
237
|
const it = config.mode === "mcp-app" ? "view" : config.mode === "inline" ? "widget" : "page";
|
|
234
238
|
const maxPage = config.limits.maxBytes;
|
|
@@ -306,7 +310,7 @@ export function lintFiles(config, files, options = {}) {
|
|
|
306
310
|
severity: "warning",
|
|
307
311
|
message: held.message,
|
|
308
312
|
path: held.path ?? path,
|
|
309
|
-
line: held.line,
|
|
313
|
+
...(held.line === undefined ? {} : { line: held.line }),
|
|
310
314
|
});
|
|
311
315
|
}
|
|
312
316
|
}
|
package/dist/check/lint.js
CHANGED
|
@@ -174,7 +174,7 @@ export function lintPage(config, content, options) {
|
|
|
174
174
|
rule: "scroll-lock",
|
|
175
175
|
severity: "warning",
|
|
176
176
|
message: held.message,
|
|
177
|
-
line: held.line,
|
|
177
|
+
...(held.line === undefined ? {} : { line: held.line }),
|
|
178
178
|
});
|
|
179
179
|
}
|
|
180
180
|
const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);
|