@botiverse/porthole 0.14.9 → 0.14.11

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.
@@ -313,7 +313,9 @@ export function createHost(config, options = {}) {
313
313
  };
314
314
  /**
315
315
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
316
- * places the host's own UI nowhere outside its frame.
316
+ * places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
317
+ * document's `scroll` (P132) pass as they were checked: where a mark is in the document,
318
+ * offscreen too, which a clamp would erase; the host clips what it draws from them.
317
319
  */
318
320
  const withinFrame = (report) => {
319
321
  const viewport = frameViewport();
@@ -324,7 +326,7 @@ export function createHost(config, options = {}) {
324
326
  return { ...report, rect: clampRect(report.rect, viewport) };
325
327
  case "anchored":
326
328
  return {
327
- type: "anchored",
329
+ ...report,
328
330
  results: report.results.map((result) => result.rect === undefined
329
331
  ? result
330
332
  : { ...result, rect: clampRect(result.rect, viewport) }),
@@ -408,7 +410,7 @@ export function createHost(config, options = {}) {
408
410
  if (results.length === 0) {
409
411
  return;
410
412
  }
411
- report = { type: "anchored", results };
413
+ report = { ...report, results };
412
414
  break;
413
415
  }
414
416
  case "activated": {
@@ -312,7 +312,9 @@ export interface AnnotationControls {
312
312
  * Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
313
313
  * `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
314
314
  * to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
315
- * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
315
+ * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
316
+ * shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
317
+ * following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
316
318
  */
317
319
  track(id: string | null): void;
318
320
  /** Removes every mark. */
package/dist/index.d.ts CHANGED
@@ -47,7 +47,7 @@ export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool
47
47
  export { writeClipboard } from "./host/clipboard.ts";
48
48
  export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
49
49
  export type { AnnotationControls, FindControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
50
- 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";
51
- export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
50
+ export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationScroll, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
51
+ export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.ts";
52
52
  export { FIND_LIMITS, FIND_METHODS, type FindDirection, type FindOptions, type FindReport, type FindResult, } from "./find/types.ts";
53
53
  export { parseFindReport, parseFindResult } from "./find/validate.ts";
package/dist/index.js CHANGED
@@ -52,7 +52,7 @@ export { writeClipboard } from "./host/clipboard.js";
52
52
  export { httpLocator, LocateError, servedOrOpaque, } from "./host/locator.js";
53
53
  // Annotations (P053): anchors, what a frame reports, and the host's checks on both.
54
54
  export { ANNOTATE_METHODS, ANNOTATION_LIMITS, } from "./annotate/types.js";
55
- export { parseAnchor, parseRect, parseReport } from "./annotate/validate.js";
55
+ export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.js";
56
56
  // Find in page (P131): the host's find bar, the frame's matches, and the host's checks on both.
57
57
  export { FIND_LIMITS, FIND_METHODS, } from "./find/types.js";
58
58
  export { parseFindReport, parseFindResult } from "./find/validate.js";
@@ -321,7 +321,8 @@ export interface PortholeFrameProps {
321
321
  } | null;
322
322
  /**
323
323
  * The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
324
- * `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
324
+ * `{ type: "tracked", id, rect }` at most once per animation frame, for it alone (from a newer
325
+ * shell with its `documentRect` and the document's `scroll`, P132). `null` (or
325
326
  * leaving it out once set) stops. By value: given when it changes, and when the display is made.
326
327
  * Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
327
328
  * `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
@@ -24,13 +24,21 @@ export declare const MARKER_HIT: string;
24
24
  * was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
25
25
  * shell's own (a closed shadow root), again whenever the content changes; what can't be found
26
26
  * is reported `orphaned`;
27
- * - markers (P104): a mark with a count gets a small bubble with the number beside its anchor's
28
- * last line (P105: in the line's gutter); a click on it is reported (`activated`), and the
29
- * content's own handlers never see it; a draft (P107) is drawn apart, a dashed line and a hollow
30
- * bubble with no number, and has a marker with or without a count;
27
+ * - markers (P104): a mark with a count gets a small button with the number, a bubble: a text
28
+ * anchor's at its paragraph's end (P133), a draft's (P107) beside its anchor's last line (P105:
29
+ * in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
30
+ * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
31
+ * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
32
+ * or without a count;
31
33
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
32
34
  * settles, the marks that moved since the host was last told are reported, at most once a
33
- * second, so the host's own UI beside a mark can follow.
35
+ * second, so the host's own UI beside a mark can follow;
36
+ * - places in the document (P132): each result's box also in the document's coordinates
37
+ * (`documentRect`), with how far the document was scrolled as it was read (`scroll`), and the
38
+ * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
39
+ * them placed as the document scrolls, from one report and the followed mark's scroll;
40
+ * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
41
+ * too (`lastLineDocumentRect`), so a host places its UI after them.
34
42
  *
35
43
  * It shares the realm with the content, which can interfere with all of it: the host takes its
36
44
  * reports as UI hints only.