@botiverse/porthole 0.12.0 → 0.13.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/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/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.js +27 -0
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/platform/focus-guard.d.ts +143 -0
- package/dist/platform/focus-guard.js +445 -0
- package/dist/platform/types.d.ts +18 -0
- package/dist/platform/web.js +22 -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/docs/ADOPTING.md +85 -6
- package/docs/DECISIONS.md +355 -5
- package/docs/DESIGN.md +9 -2
- package/docs/THREAT_MODEL.md +121 -29
- package/package.json +1 -1
- 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/config/capabilities.ts +16 -3
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +29 -0
- package/src/host/types.ts +13 -0
- package/src/index.ts +1 -0
- package/src/platform/focus-guard.ts +572 -0
- package/src/platform/types.ts +17 -0
- package/src/platform/web.ts +22 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/types/runtime/v1/comments.d.ts +8 -4
|
@@ -45,9 +45,14 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
45
45
|
/**
|
|
46
46
|
* What must hold before a call reaches the host's handler. A capability's gates all apply.
|
|
47
47
|
*
|
|
48
|
-
* - `user-activation`: the call follows a real user gesture
|
|
49
|
-
*
|
|
50
|
-
*
|
|
48
|
+
* - `user-activation`: the call follows a real user gesture. The shell refuses a call without one
|
|
49
|
+
* in its frame, but that check is the page's own (a page posts the call itself and skips it).
|
|
50
|
+
* The host checks its own page's transient activation, which a gesture in a child frame
|
|
51
|
+
* propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
|
|
52
|
+
* the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
|
|
53
|
+
* load, or on a timer while nobody does anything; it is not proof that the gesture was in this
|
|
54
|
+
* frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
|
|
55
|
+
* the person's composer), the host also asks that its page's focus be in the calling frame.
|
|
51
56
|
* - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
|
|
52
57
|
* goes only if they accept. No `confirm` function means the call is refused (fail closed).
|
|
53
58
|
* - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
|
|
@@ -82,6 +87,13 @@ export interface CapabilitySpec {
|
|
|
82
87
|
* Absent for what the shell does by itself (sizes, errors, annotations).
|
|
83
88
|
*/
|
|
84
89
|
readonly request?: { readonly method: string; readonly sdk?: string };
|
|
90
|
+
/**
|
|
91
|
+
* Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
|
|
92
|
+
* focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
|
|
93
|
+
* a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
|
|
94
|
+
* typing in its own composer included.
|
|
95
|
+
*/
|
|
96
|
+
readonly inFrame?: true;
|
|
85
97
|
}
|
|
86
98
|
|
|
87
99
|
const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
|
|
@@ -170,6 +182,7 @@ export const CAPABILITIES = {
|
|
|
170
182
|
defaultGates: ["user-activation", rate(30)],
|
|
171
183
|
served: "handler",
|
|
172
184
|
request: { method: "porthole/call" },
|
|
185
|
+
inFrame: true,
|
|
173
186
|
},
|
|
174
187
|
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
175
188
|
artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
|
package/src/guide/runtime.ts
CHANGED
|
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
|
|
|
61
61
|
const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
|
|
62
62
|
user: () => "who is viewing: { id, name, level }, as the app says",
|
|
63
63
|
comments: () =>
|
|
64
|
-
"opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width, bidi or tag characters; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
64
|
+
"opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
65
65
|
copyText: () =>
|
|
66
66
|
`copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
|
|
67
67
|
openLink: () =>
|
package/src/host/create-host.ts
CHANGED
|
@@ -29,6 +29,7 @@ import { locateServed } from "./locate.ts";
|
|
|
29
29
|
import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
|
|
30
30
|
import type { FrameSource } from "../isolation/types.ts";
|
|
31
31
|
import { webPlatform } from "../platform/web.ts";
|
|
32
|
+
import { TAKES } from "../platform/focus-guard.ts";
|
|
32
33
|
import type { Surface } from "../platform/types.ts";
|
|
33
34
|
import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
|
|
34
35
|
import {
|
|
@@ -495,6 +496,29 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
495
496
|
})
|
|
496
497
|
: framed;
|
|
497
498
|
surface = created;
|
|
499
|
+
// The focus guard undid a move of the keyboard into this frame (P109): heard each time,
|
|
500
|
+
// and a frame that keeps taking it is stopped, as one that keeps navigating away is.
|
|
501
|
+
const takes: { at: number; counts: boolean }[] = [];
|
|
502
|
+
created.onFocusTaken?.(({ typing, failed }) => {
|
|
503
|
+
const at = Date.now();
|
|
504
|
+
// While the person typed, or a take-back that failed (the keys then go to the frame and
|
|
505
|
+
// the page sees no typing): either counts toward the first rule.
|
|
506
|
+
takes.push({ at, counts: typing || failed });
|
|
507
|
+
const within = (ms: number) => takes.filter((take) => at - take.at <= ms);
|
|
508
|
+
emit("focusTaken", { typing });
|
|
509
|
+
if (
|
|
510
|
+
surface === created &&
|
|
511
|
+
(within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
|
|
512
|
+
TAKES.typing.most ||
|
|
513
|
+
within(TAKES.any.withinMs).length >= TAKES.any.most)
|
|
514
|
+
) {
|
|
515
|
+
stop();
|
|
516
|
+
contentError("The content kept taking the keyboard from the page; it was stopped.");
|
|
517
|
+
}
|
|
518
|
+
while (takes.length > 0 && at - (takes[0] as { at: number }).at > TAKES.typing.withinMs) {
|
|
519
|
+
takes.shift();
|
|
520
|
+
}
|
|
521
|
+
});
|
|
498
522
|
const watch = watchOutcome({
|
|
499
523
|
surface: created,
|
|
500
524
|
source,
|
|
@@ -530,6 +554,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
530
554
|
...(options.show === undefined ? {} : { show: options.show }),
|
|
531
555
|
...(options.cached === undefined ? {} : { cached: options.cached }),
|
|
532
556
|
userActivation: () => created.userActivation(),
|
|
557
|
+
// The person in this frame (P109): the page's focus in it, after the focus guard.
|
|
558
|
+
focused: () => created.focused?.(),
|
|
533
559
|
onEvent: onBridge,
|
|
534
560
|
...(declaration === null ? {} : { declaration }),
|
|
535
561
|
...(viewer === undefined ? {} : { viewer }),
|
|
@@ -651,6 +677,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
651
677
|
restarts = 0;
|
|
652
678
|
run();
|
|
653
679
|
},
|
|
680
|
+
focus() {
|
|
681
|
+
surface?.focus?.();
|
|
682
|
+
},
|
|
654
683
|
destroy() {
|
|
655
684
|
destroyed = true;
|
|
656
685
|
stop();
|
package/src/host/types.ts
CHANGED
|
@@ -201,6 +201,14 @@ export interface DisplayEvents {
|
|
|
201
201
|
readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
|
|
202
202
|
/** Too many declines: the display stops asking until it runs again. */
|
|
203
203
|
readonly muted: undefined;
|
|
204
|
+
/**
|
|
205
|
+
* The content moved the keyboard into its frame from one of the page's text fields without the
|
|
206
|
+
* person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
|
|
207
|
+
* person had pressed a key on the page within the last second. The content's doing. Three while
|
|
208
|
+
* typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
|
|
209
|
+
* runs it again).
|
|
210
|
+
*/
|
|
211
|
+
readonly focusTaken: { readonly typing: boolean };
|
|
204
212
|
/**
|
|
205
213
|
* What the frame reported about annotations (`annotate`, P053), checked and taken only while
|
|
206
214
|
* the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
|
|
@@ -242,6 +250,11 @@ export interface DisplayControls {
|
|
|
242
250
|
readonly annotations: AnnotationControls;
|
|
243
251
|
/** Runs the content again from the start, in a new frame. */
|
|
244
252
|
reload(): void;
|
|
253
|
+
/**
|
|
254
|
+
* Moves focus into the display's frame, as the host's own move: from one of the page's text
|
|
255
|
+
* fields, a frame's own `focus()` is taken for the content's and undone (P109).
|
|
256
|
+
*/
|
|
257
|
+
focus(): void;
|
|
245
258
|
/** Tears the view down and removes the frame. */
|
|
246
259
|
destroy(): void;
|
|
247
260
|
}
|
package/src/index.ts
CHANGED
|
@@ -275,6 +275,7 @@ export type {
|
|
|
275
275
|
DbContext,
|
|
276
276
|
} from "./bridge/types.ts";
|
|
277
277
|
export { createHost } from "./host/create-host.ts";
|
|
278
|
+
export { focusField } from "./platform/focus-guard.ts";
|
|
278
279
|
// The client half of the host kit, and the display registry (P072).
|
|
279
280
|
export {
|
|
280
281
|
entryTarget,
|