@botiverse/porthole 0.10.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/annotate/types.d.ts +18 -6
- package/dist/annotate/validate.d.ts +11 -1
- package/dist/annotate/validate.js +18 -1
- 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.d.ts +2 -0
- package/dist/check/files.js +71 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +116 -0
- package/dist/check/scroll.js +1485 -0
- 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/conformance/runtime.js +6 -0
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +30 -3
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +2 -1
- 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 +10 -1
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +41 -4
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +2 -1
- package/dist/shell/annotate.js +29 -12
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +106 -5
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +741 -2
- package/docs/DESIGN.md +38 -9
- package/docs/THREAT_MODEL.md +146 -19
- package/package.json +1 -1
- package/src/annotate/types.ts +19 -6
- package/src/annotate/validate.ts +20 -1
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +72 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1825 -0
- package/src/config/capabilities.ts +16 -3
- package/src/conformance/runtime.ts +9 -0
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +38 -3
- package/src/host/types.ts +13 -0
- package/src/index.ts +2 -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 +12 -1
- package/src/runtime/requests.ts +50 -6
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +29 -12
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +20 -6
|
@@ -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" } },
|
|
@@ -588,6 +588,15 @@ export function defineRuntimeConformance(
|
|
|
588
588
|
"open",
|
|
589
589
|
);
|
|
590
590
|
expect(typeof opened === "boolean", "comments.open answers a boolean");
|
|
591
|
+
// A draft (P108): the handler takes the new field (a strict schema of its own must not refuse it).
|
|
592
|
+
const drafted = ok(
|
|
593
|
+
await as(handlers, viewers.view)("comments", {
|
|
594
|
+
anchor: { name: "slide-3" },
|
|
595
|
+
draft: "Approved",
|
|
596
|
+
}),
|
|
597
|
+
"open with a draft",
|
|
598
|
+
);
|
|
599
|
+
expect(typeof drafted === "boolean", "comments.open with a draft answers a boolean");
|
|
591
600
|
});
|
|
592
601
|
}
|
|
593
602
|
return cases;
|
package/src/guide/guide.ts
CHANGED
|
@@ -253,6 +253,7 @@ function widget(c: Context): string {
|
|
|
253
253
|
),
|
|
254
254
|
`- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`,
|
|
255
255
|
`- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`,
|
|
256
|
+
`- It scrolls as a document: unless it's meant to fit one screen (a game, a canvas), don't hold html, body or the element that holds it all to one screen (height: 100% or 100vh with overflow: hidden, or position: fixed), or what's below the first screen can't be reached. A box that scrolls by itself takes the wheel while the pointer is over it: keep those to parts of the ${noun} (a wide table, a long list), never the whole of it.`,
|
|
256
257
|
"- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).",
|
|
257
258
|
"- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.",
|
|
258
259
|
fills
|
package/src/guide/runtime.ts
CHANGED
|
@@ -28,7 +28,7 @@ import { sizeWords } from "./limits.ts";
|
|
|
28
28
|
/** How each method is called, as the manual writes it. */
|
|
29
29
|
const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, string>>>> = {
|
|
30
30
|
user: { get: "user.get()" },
|
|
31
|
-
comments: { open: "comments.open({ name, label, quote })" },
|
|
31
|
+
comments: { open: "comments.open({ name, label, quote }, { draft })" },
|
|
32
32
|
clipboard: { copy: "clipboard.copy(text)" },
|
|
33
33
|
links: { open: "links.open(url)" },
|
|
34
34
|
downloads: { save: "downloads.save({ name, text | data })" },
|
|
@@ -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); the person
|
|
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
|
@@ -4,7 +4,13 @@ import {
|
|
|
4
4
|
type AnnotationMark,
|
|
5
5
|
type AnnotationReport,
|
|
6
6
|
} from "../annotate/types.ts";
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
annotateMode,
|
|
9
|
+
checkMarks,
|
|
10
|
+
clampRect,
|
|
11
|
+
hasMarker,
|
|
12
|
+
parseReport,
|
|
13
|
+
} from "../annotate/validate.ts";
|
|
8
14
|
import {
|
|
9
15
|
createBridge,
|
|
10
16
|
onceConsent,
|
|
@@ -23,6 +29,7 @@ import { locateServed } from "./locate.ts";
|
|
|
23
29
|
import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
|
|
24
30
|
import type { FrameSource } from "../isolation/types.ts";
|
|
25
31
|
import { webPlatform } from "../platform/web.ts";
|
|
32
|
+
import { TAKES } from "../platform/focus-guard.ts";
|
|
26
33
|
import type { Surface } from "../platform/types.ts";
|
|
27
34
|
import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
|
|
28
35
|
import {
|
|
@@ -253,7 +260,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
253
260
|
/**
|
|
254
261
|
* A report from the frame: checked, taken only while the host asked for it (a selection
|
|
255
262
|
* only in select mode, results only for its own marks, a marker's click only for a mark it
|
|
256
|
-
* shows with one, within a gesture), then through the bridge's gates.
|
|
263
|
+
* shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
|
|
257
264
|
*/
|
|
258
265
|
const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
|
|
259
266
|
if (
|
|
@@ -310,7 +317,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
310
317
|
}
|
|
311
318
|
case "activated": {
|
|
312
319
|
const { id } = report;
|
|
313
|
-
if (!marks.some((mark) => mark.id === id && mark
|
|
320
|
+
if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
314
321
|
return;
|
|
315
322
|
}
|
|
316
323
|
// A marker's real click gives the host's page transient activation (measured on all
|
|
@@ -489,6 +496,29 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
489
496
|
})
|
|
490
497
|
: framed;
|
|
491
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
|
+
});
|
|
492
522
|
const watch = watchOutcome({
|
|
493
523
|
surface: created,
|
|
494
524
|
source,
|
|
@@ -524,6 +554,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
524
554
|
...(options.show === undefined ? {} : { show: options.show }),
|
|
525
555
|
...(options.cached === undefined ? {} : { cached: options.cached }),
|
|
526
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?.(),
|
|
527
559
|
onEvent: onBridge,
|
|
528
560
|
...(declaration === null ? {} : { declaration }),
|
|
529
561
|
...(viewer === undefined ? {} : { viewer }),
|
|
@@ -645,6 +677,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
645
677
|
restarts = 0;
|
|
646
678
|
run();
|
|
647
679
|
},
|
|
680
|
+
focus() {
|
|
681
|
+
surface?.focus?.();
|
|
682
|
+
},
|
|
648
683
|
destroy() {
|
|
649
684
|
destroyed = true;
|
|
650
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,
|
|
@@ -333,6 +334,7 @@ export {
|
|
|
333
334
|
type AnnotateMode,
|
|
334
335
|
type AnnotationAnchor,
|
|
335
336
|
type AnnotationMark,
|
|
337
|
+
type AnnotationMarkKind,
|
|
336
338
|
type AnnotationRect,
|
|
337
339
|
type AnnotationReport,
|
|
338
340
|
type AnnotationSelector,
|