@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.
Files changed (68) hide show
  1. package/dist/annotate/types.d.ts +18 -6
  2. package/dist/annotate/validate.d.ts +11 -1
  3. package/dist/annotate/validate.js +18 -1
  4. package/dist/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.d.ts +2 -0
  9. package/dist/check/files.js +71 -50
  10. package/dist/check/lint.d.ts +8 -1
  11. package/dist/check/lint.js +18 -0
  12. package/dist/check/markup.d.ts +7 -0
  13. package/dist/check/markup.js +49 -0
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/scroll.d.ts +116 -0
  16. package/dist/check/scroll.js +1485 -0
  17. package/dist/config/capabilities.d.ts +16 -3
  18. package/dist/config/capabilities.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/conformance/runtime.js +6 -0
  21. package/dist/guide/guide.js +1 -1
  22. package/dist/guide/runtime.js +2 -2
  23. package/dist/host/create-host.js +30 -3
  24. package/dist/host/types.d.ts +15 -0
  25. package/dist/index.d.ts +2 -1
  26. package/dist/index.js +1 -0
  27. package/dist/platform/focus-guard.d.ts +143 -0
  28. package/dist/platform/focus-guard.js +445 -0
  29. package/dist/platform/types.d.ts +18 -0
  30. package/dist/platform/web.js +22 -0
  31. package/dist/react/frame.d.ts +10 -1
  32. package/dist/react/frame.js +4 -0
  33. package/dist/runtime/requests.d.ts +5 -0
  34. package/dist/runtime/requests.js +41 -4
  35. package/dist/runtime/types.generated.js +1 -1
  36. package/dist/shell/annotate.d.ts +2 -1
  37. package/dist/shell/annotate.js +29 -12
  38. package/dist/shell/use.js +9 -1
  39. package/docs/ADOPTING.md +106 -5
  40. package/docs/ARCHITECTURE.md +2 -1
  41. package/docs/DECISIONS.md +741 -2
  42. package/docs/DESIGN.md +38 -9
  43. package/docs/THREAT_MODEL.md +146 -19
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +19 -6
  46. package/src/annotate/validate.ts +20 -1
  47. package/src/bridge/bridge.ts +17 -1
  48. package/src/bridge/unseen.ts +24 -0
  49. package/src/check/files.ts +72 -54
  50. package/src/check/lint.ts +24 -0
  51. package/src/check/markup.ts +53 -0
  52. package/src/check/scroll.ts +1825 -0
  53. package/src/config/capabilities.ts +16 -3
  54. package/src/conformance/runtime.ts +9 -0
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +38 -3
  58. package/src/host/types.ts +13 -0
  59. package/src/index.ts +2 -0
  60. package/src/platform/focus-guard.ts +572 -0
  61. package/src/platform/types.ts +17 -0
  62. package/src/platform/web.ts +22 -0
  63. package/src/react/frame.tsx +12 -1
  64. package/src/runtime/requests.ts +50 -6
  65. package/src/runtime/types.generated.ts +1 -1
  66. package/src/shell/annotate.ts +29 -12
  67. package/src/shell/use.ts +9 -1
  68. package/types/runtime/v1/comments.d.ts +20 -6
@@ -318,6 +318,12 @@ export function defineRuntimeConformance(options) {
318
318
  anchor: { name: "slide-3", label: "Slide 3" },
319
319
  }), "open");
320
320
  expect(typeof opened === "boolean", "comments.open answers a boolean");
321
+ // A draft (P108): the handler takes the new field (a strict schema of its own must not refuse it).
322
+ const drafted = ok(await as(handlers, viewers.view)("comments", {
323
+ anchor: { name: "slide-3" },
324
+ draft: "Approved",
325
+ }), "open with a draft");
326
+ expect(typeof drafted === "boolean", "comments.open with a draft answers a boolean");
321
327
  });
322
328
  }
323
329
  return cases;
@@ -158,7 +158,7 @@ function widget(c) {
158
158
  const smallest = Math.round(((13 * layout.minWidthPx) / viewBox) * 10) / 10;
159
159
  const largest = Math.round(((13 * 400) / viewBox) * 10) / 10;
160
160
  const textSize = themeDefault(config.theme.variables["--font-text-md-size"] ?? "14px", "light").replace(/^(\d+(?:\.\d+)?)px$/u, "$1 px");
161
- return lines(`# ${title}${tool}`, "", what, "", `Where it runs: ${fills ? `in a sandboxed frame that fills the app's viewer (often smaller than the window: toolbars and side panels take room), about ${layout.narrowWidthPx} px wide on a phone (${layout.minWidthPx} on a small one) and wider on a desktop` : `in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop`}; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the ${fills ? "frame's own innerWidth, again on resize" : "box's clientWidth, again from a ResizeObserver"}). ${said("layout")} ${said("theme")} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- 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).`, `- 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.`, "- 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, …).", "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.", fills
161
+ return lines(`# ${title}${tool}`, "", what, "", `Where it runs: ${fills ? `in a sandboxed frame that fills the app's viewer (often smaller than the window: toolbars and side panels take room), about ${layout.narrowWidthPx} px wide on a phone (${layout.minWidthPx} on a small one) and wider on a desktop` : `in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop`}; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the ${fills ? "frame's own innerWidth, again on resize" : "box's clientWidth, again from a ResizeObserver"}). ${said("layout")} ${said("theme")} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- 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).`, `- 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.`, `- 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.`, "- 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, …).", "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.", fills
162
162
  ? null
163
163
  : "- No position: fixed: the frame grows with its content, so a fixed element covers it.", "", "The sandbox:", ...stated.filter((limit) => limit.topic === "sandbox").map((limit) => `- ${limit.text}`), `Keep it under ${sizeWords(limits.maxBytes)}.`, servesFiles(config) ? "" : null, files(config), loadsScripts(config)
164
164
  ? "\nLibraries: pin an exact version at least two weeks old (chart.js@4.4.1 in its URL), never @latest or a range, so the code can't be swapped under you and draws the same every time."
@@ -17,7 +17,7 @@ import { sizeWords } from "./limits.js";
17
17
  /** How each method is called, as the manual writes it. */
18
18
  const CALLS = {
19
19
  user: { get: "user.get()" },
20
- comments: { open: "comments.open({ name, label, quote })" },
20
+ comments: { open: "comments.open({ name, label, quote }, { draft })" },
21
21
  clipboard: { copy: "clipboard.copy(text)" },
22
22
  links: { open: "links.open(url)" },
23
23
  downloads: { save: "downloads.save({ name, text | data })" },
@@ -48,7 +48,7 @@ const CALLS = {
48
48
  /** What each host function does, in a phrase, for its line. */
49
49
  const WHAT = {
50
50
  user: () => "who is viewing: { id, name, level }, as the app says",
51
- comments: () => "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 writes it in the app. True if it opened. Write-only: a page never reads comments",
51
+ comments: () => "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",
52
52
  copyText: () => `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`,
53
53
  openLink: () => "opens an http(s) link outside the page; a click on an <a href> does the same. True if it opened",
54
54
  downloadFile: () => "hands the person a file to save (<a download> doesn't work here). True if it started",
@@ -1,5 +1,5 @@
1
1
  import { ANNOTATE_METHODS, } from "../annotate/types.js";
2
- import { annotateMode, checkMarks, clampRect, parseReport } from "../annotate/validate.js";
2
+ import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.js";
3
3
  import { createBridge, onceConsent, } from "../bridge/bridge.js";
4
4
  import { compile } from "../compile/compile.js";
5
5
  import { servesFiles } from "../files/paths.js";
@@ -10,6 +10,7 @@ import { capabilitySpec } from "../config/capabilities.js";
10
10
  import { locateServed } from "./locate.js";
11
11
  import { watchOutcome } from "./outcome.js";
12
12
  import { webPlatform } from "../platform/web.js";
13
+ import { TAKES } from "../platform/focus-guard.js";
13
14
  import { MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
14
15
  import { shellAdapter } from "../protocol/shell-adapter.js";
15
16
  import { resolveTheme } from "../theme/variables.js";
@@ -197,7 +198,7 @@ export function createHost(config, options = {}) {
197
198
  /**
198
199
  * A report from the frame: checked, taken only while the host asked for it (a selection
199
200
  * only in select mode, results only for its own marks, a marker's click only for a mark it
200
- * shows with one, within a gesture), then through the bridge's gates.
201
+ * shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
201
202
  */
202
203
  const onAnnotation = (raw, through) => {
203
204
  if (!isRecord(raw) ||
@@ -250,7 +251,7 @@ export function createHost(config, options = {}) {
250
251
  }
251
252
  case "activated": {
252
253
  const { id } = report;
253
- if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
254
+ if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
254
255
  return;
255
256
  }
256
257
  // A marker's real click gives the host's page transient activation (measured on all
@@ -422,6 +423,27 @@ export function createHost(config, options = {}) {
422
423
  })
423
424
  : framed;
424
425
  surface = created;
426
+ // The focus guard undid a move of the keyboard into this frame (P109): heard each time,
427
+ // and a frame that keeps taking it is stopped, as one that keeps navigating away is.
428
+ const takes = [];
429
+ created.onFocusTaken?.(({ typing, failed }) => {
430
+ const at = Date.now();
431
+ // While the person typed, or a take-back that failed (the keys then go to the frame and
432
+ // the page sees no typing): either counts toward the first rule.
433
+ takes.push({ at, counts: typing || failed });
434
+ const within = (ms) => takes.filter((take) => at - take.at <= ms);
435
+ emit("focusTaken", { typing });
436
+ if (surface === created &&
437
+ (within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
438
+ TAKES.typing.most ||
439
+ within(TAKES.any.withinMs).length >= TAKES.any.most)) {
440
+ stop();
441
+ contentError("The content kept taking the keyboard from the page; it was stopped.");
442
+ }
443
+ while (takes.length > 0 && at - takes[0].at > TAKES.typing.withinMs) {
444
+ takes.shift();
445
+ }
446
+ });
425
447
  const watch = watchOutcome({
426
448
  surface: created,
427
449
  source,
@@ -456,6 +478,8 @@ export function createHost(config, options = {}) {
456
478
  ...(options.show === undefined ? {} : { show: options.show }),
457
479
  ...(options.cached === undefined ? {} : { cached: options.cached }),
458
480
  userActivation: () => created.userActivation(),
481
+ // The person in this frame (P109): the page's focus in it, after the focus guard.
482
+ focused: () => created.focused?.(),
459
483
  onEvent: onBridge,
460
484
  ...(declaration === null ? {} : { declaration }),
461
485
  ...(viewer === undefined ? {} : { viewer }),
@@ -571,6 +595,9 @@ export function createHost(config, options = {}) {
571
595
  restarts = 0;
572
596
  run();
573
597
  },
598
+ focus() {
599
+ surface?.focus?.();
600
+ },
574
601
  destroy() {
575
602
  destroyed = true;
576
603
  stop();
@@ -205,6 +205,16 @@ export interface DisplayEvents {
205
205
  };
206
206
  /** Too many declines: the display stops asking until it runs again. */
207
207
  readonly muted: undefined;
208
+ /**
209
+ * The content moved the keyboard into its frame from one of the page's text fields without the
210
+ * person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
211
+ * person had pressed a key on the page within the last second. The content's doing. Three while
212
+ * typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
213
+ * runs it again).
214
+ */
215
+ readonly focusTaken: {
216
+ readonly typing: boolean;
217
+ };
208
218
  /**
209
219
  * What the frame reported about annotations (`annotate`, P053), checked and taken only while
210
220
  * the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
@@ -241,6 +251,11 @@ export interface DisplayControls {
241
251
  readonly annotations: AnnotationControls;
242
252
  /** Runs the content again from the start, in a new frame. */
243
253
  reload(): void;
254
+ /**
255
+ * Moves focus into the display's frame, as the host's own move: from one of the page's text
256
+ * fields, a frame's own `focus()` is taken for the content's and undone (P109).
257
+ */
258
+ focus(): void;
244
259
  /** Tears the view down and removes the frame. */
245
260
  destroy(): void;
246
261
  }
package/dist/index.d.ts CHANGED
@@ -35,6 +35,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
35
35
  export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason, } from "./bridge/refusal.ts";
36
36
  export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, Show, SubscriptionContext, DbContext, } from "./bridge/types.ts";
37
37
  export { createHost } from "./host/create-host.ts";
38
+ export { focusField } from "./platform/focus-guard.ts";
38
39
  export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
39
40
  export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
40
41
  export { fragmentOf, lintContent, type Finding, type LintRule } from "./check/lint.ts";
@@ -43,5 +44,5 @@ export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool
43
44
  export { writeClipboard } from "./host/clipboard.ts";
44
45
  export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
45
46
  export type { AnnotationControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
46
- export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
47
+ export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
47
48
  export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
package/dist/index.js CHANGED
@@ -36,6 +36,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
36
36
  // Why a call was refused, as content is told it, and the host's own refusals (P080).
37
37
  export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
38
38
  export { createHost } from "./host/create-host.js";
39
+ export { focusField } from "./platform/focus-guard.js";
39
40
  // The client half of the host kit, and the display registry (P072).
40
41
  export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
41
42
  export { defineDisplays } from "./displays/displays.js";
@@ -0,0 +1,143 @@
1
+ /**
2
+ * The focus guard (P109): a display's frame can move the keyboard into itself whenever it likes
3
+ * (`element.focus()` in its own realm; on Chromium and WebKit with no gesture at all), and what the
4
+ * person goes on typing into the host's composer or chat box then goes to the page. Porthole can't
5
+ * stop the call, which runs in the content's realm, but the host's page can undo it: when focus
6
+ * leaves one of its text fields for a display's frame and the person didn't move it there, focus
7
+ * goes back once the engine has finished moving it, the guard watches that it stays back, and the
8
+ * display hears `focusTaken`; a display whose frame keeps doing it is stopped (`createHost`).
9
+ *
10
+ * What the host's page can see of a move into a frame, measured on Chromium, WebKit and Firefox
11
+ * (P109): Chromium and WebKit blur the host's window as it happens, and a press on the frame (a
12
+ * click, a tap, held or not) leaves the frame element `:active` then; a Tab is the host's own
13
+ * keydown just before. Firefox doesn't blur the window and shows no `:active` (a focusout on the
14
+ * field was seen in one review's runs, not in another's): its `document.activeElement` changes,
15
+ * which the guard reads at each animation frame while a frame is guarded, and the pointer over the
16
+ * frame (`:hover`, `pointerover`) is all it can tell of a press. A page that takes focus back on
17
+ * its own blur (which a take-back fires) leaves Firefox's focus on nothing (`<body>`) or in the
18
+ * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
+ * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
+ * (measured: 5.04 to 5.10 s).
21
+ */
22
+ /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
23
+ export declare const TAB_MS = 1000;
24
+ /**
25
+ * How long transient activation lasts after a gesture (measured: 5 s on all three engines): a
26
+ * host page with activation and no gesture of its own for longer had one in a frame.
27
+ */
28
+ export declare const ACTIVATION_SPAN_MS = 5000;
29
+ /** The person is typing: a key on the host's page within this long. */
30
+ export declare const TYPING_MS = 1000;
31
+ /**
32
+ * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
33
+ * text field this long: a page that takes it again at once (on its own blur, which the take-back
34
+ * fires) is caught as it does, on Firefox too (P109, after the review of the guard: GK-1).
35
+ */
36
+ export declare const HELD_MS = 300;
37
+ /** A take-back that hasn't put focus back in the field after this long failed: counted, and tried again. */
38
+ export declare const GIVE_BACK_MS = 50;
39
+ /**
40
+ * A frame that holds focus isn't the person's for this long after they press the host's page: the
41
+ * press gives the page activation before focus leaves the frame (on Firefox, a move between
42
+ * processes), and a call the frame sends in between would borrow it.
43
+ */
44
+ export declare const HOST_PRESS_MS = 1000;
45
+ /**
46
+ * When a display is stopped for taking the keyboard (P109): focus given back can't stop its frame
47
+ * calling `focus()` again (nothing the host sets on the frame does, `inert` included: measured),
48
+ * and each try leaves it the keys typed until focus is back. So three undone moves within 10 s
49
+ * that came while the person typed on the page or that kept focus from going back (a take-back that
50
+ * failed: the keys then go to the frame, and the page sees no typing to count), or five at all
51
+ * within 2 s, stop it. A person's own move never fails a take-back.
52
+ */
53
+ export declare const TAKES: {
54
+ readonly typing: {
55
+ readonly most: 3;
56
+ readonly withinMs: 10000;
57
+ };
58
+ readonly any: {
59
+ readonly most: 5;
60
+ readonly withinMs: 2000;
61
+ };
62
+ };
63
+ /** One move of the keyboard the guard undid. */
64
+ export interface FocusTake {
65
+ /** The person pressed a key on the host's page within the last second. */
66
+ readonly typing: boolean;
67
+ /**
68
+ * Focus didn't stay back in the field: the frame kept it, took it again within `HELD_MS`, or it
69
+ * landed nowhere.
70
+ */
71
+ readonly failed: boolean;
72
+ }
73
+ /** What the host's page knew when focus left one of its text fields for a display's frame. */
74
+ export interface FocusMove {
75
+ readonly now: number;
76
+ /** The engine told the host's page as it happened (its window blurred): Chromium, WebKit. */
77
+ readonly seen: boolean;
78
+ /** The frame element is `:active`: a press on it, pointer or touch (Chromium, WebKit). */
79
+ readonly pressed: boolean;
80
+ /** The pointer is over the frame element (`:hover`). */
81
+ readonly over: boolean;
82
+ /** When the pointer last came over the frame element (`pointerover`); -Infinity if never. */
83
+ readonly overSince: number;
84
+ /** The person's last key on the host's page, and when. */
85
+ readonly lastKey: {
86
+ readonly key: string;
87
+ readonly at: number;
88
+ } | null;
89
+ /** When the person last typed on the host's page (a key other than Tab and the modifiers). */
90
+ readonly typedAt: number;
91
+ /** When the text field focus left got it. */
92
+ readonly focusedAt: number;
93
+ /** When the host's page last saw a gesture of its own (a key, a press, a click, typed text). */
94
+ readonly gestureAt: number;
95
+ /** Whether the host's page has transient activation now; undefined where it can't tell. */
96
+ readonly activation: boolean | undefined;
97
+ /** The host moved focus into the frame itself (`DisplayHandle.focus()`), just now. */
98
+ readonly hostMoved: boolean;
99
+ }
100
+ /**
101
+ * Whether the person moved focus into the frame themselves:
102
+ * - the host did (`DisplayHandle.focus()`);
103
+ * - by the keyboard: their last key on the host's page was Tab (or Shift+Tab), just now;
104
+ * - by a press on the frame: where the engine tells the move as it happens (Chromium, WebKit),
105
+ * the frame element is `:active`; where it doesn't (Firefox), the pointer is over the frame and
106
+ * came over it after the text field got focus and after the person last typed in the host's page
107
+ * (a page can't move the pointer; a composer that opened beside the frame while the pointer
108
+ * rested over it, and a person typing with it there, keep their keys);
109
+ * - by a gesture the host's own events don't explain: the host's page has transient activation,
110
+ * and for longer than activation lasts it saw no gesture of its own and the text field has had
111
+ * focus, so the person pressed or activated something in a frame since (an assistive
112
+ * technology's activation, which moves no pointer and sends the host no key, is one). The
113
+ * gesture that opened a composer (a selection in the frame, `selected`) is older than the
114
+ * composer's focus, and doesn't count.
115
+ * Anything else is the page's: focus goes back.
116
+ */
117
+ export declare function personMoved(move: FocusMove): boolean;
118
+ /** Whether `element` takes the person's typed text: a text field, a text area, an editable region. */
119
+ export declare function takesText(element: Element | null): element is HTMLElement;
120
+ /** One page's guard, shared by every display's frame on it. */
121
+ export interface FocusGuard {
122
+ /** Guards `frame`: `taken` hears each move into it that was undone. */
123
+ add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void): () => void;
124
+ /** The host moves focus into `frame` itself. */
125
+ focus(frame: HTMLIFrameElement): void;
126
+ /**
127
+ * Whether the page's focus is in `frame` now, the person's own (once any move into it was
128
+ * judged; on an engine that tells the host's page nothing, here and then).
129
+ */
130
+ focused(frame: HTMLIFrameElement): boolean;
131
+ /** The host moves focus into one of its text fields: see `focusField`. */
132
+ field(field: HTMLElement): void;
133
+ }
134
+ /** The guard for `view`'s page, made on first use. */
135
+ export declare function focusGuard(view: Window): FocusGuard;
136
+ /**
137
+ * Moves focus into one of the host page's text fields (a composer that opens beside a display,
138
+ * P109): `field.focus()` for a host to call instead. Firefox doesn't move focus from a frame that
139
+ * holds it with a gesture of the person's and takes it back on its own blur (measured: the keys
140
+ * then go to the frame); this blurs the frame first, and the focus guard watches that focus lands,
141
+ * counting a frame that keeps it toward stopping its display. Elsewhere it is `field.focus()`.
142
+ */
143
+ export declare function focusField(field: HTMLElement): void;