@botiverse/porthole 0.13.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.
Files changed (68) hide show
  1. package/dist/annotate/types.d.ts +32 -3
  2. package/dist/annotate/types.js +4 -0
  3. package/dist/annotate/validate.js +19 -2
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +7 -0
  6. package/dist/compile/policy.js +13 -1
  7. package/dist/config/schema.d.ts +11 -0
  8. package/dist/config/validate.js +19 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/displays/displays.js +3 -1
  11. package/dist/guide/limits.js +1 -1
  12. package/dist/host/create-host.d.ts +2 -0
  13. package/dist/host/create-host.js +73 -3
  14. package/dist/host/pass-on.d.ts +15 -0
  15. package/dist/host/pass-on.js +65 -0
  16. package/dist/host/types.d.ts +22 -0
  17. package/dist/index.d.ts +4 -1
  18. package/dist/index.js +4 -1
  19. package/dist/isolation/types.d.ts +8 -0
  20. package/dist/isolation/types.js +8 -0
  21. package/dist/platform/focus-guard.d.ts +71 -2
  22. package/dist/platform/focus-guard.js +187 -12
  23. package/dist/platform/types.d.ts +8 -1
  24. package/dist/platform/web.js +60 -4
  25. package/dist/presets/presets.d.ts +2 -0
  26. package/dist/presets/presets.js +1 -0
  27. package/dist/server/files.js +19 -3
  28. package/dist/server/index.d.ts +1 -0
  29. package/dist/server/index.js +4 -0
  30. package/dist/server/nested.d.ts +37 -0
  31. package/dist/server/nested.js +70 -0
  32. package/dist/server/server.js +57 -7
  33. package/dist/shell/annotate.d.ts +1 -1
  34. package/dist/shell/annotate.js +157 -7
  35. package/dist/shell/frame.d.ts +45 -0
  36. package/dist/shell/frame.js +250 -0
  37. package/dist/shell/plan.js +2 -1
  38. package/dist/shell/runtime.js +49 -14
  39. package/docs/ADOPTING.md +56 -2
  40. package/docs/ARCHITECTURE.md +23 -0
  41. package/docs/DECISIONS.md +209 -0
  42. package/docs/DESIGN.md +9 -0
  43. package/docs/THREAT_MODEL.md +75 -5
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +28 -3
  46. package/src/annotate/validate.ts +23 -2
  47. package/src/compile/policy.ts +14 -1
  48. package/src/config/schema.ts +11 -0
  49. package/src/config/validate.ts +23 -0
  50. package/src/displays/displays.ts +3 -1
  51. package/src/guide/limits.ts +1 -1
  52. package/src/host/create-host.ts +76 -4
  53. package/src/host/pass-on.ts +73 -0
  54. package/src/host/types.ts +20 -0
  55. package/src/index.ts +4 -1
  56. package/src/isolation/types.ts +12 -0
  57. package/src/platform/focus-guard.ts +258 -15
  58. package/src/platform/types.ts +8 -1
  59. package/src/platform/web.ts +81 -9
  60. package/src/presets/presets.ts +3 -0
  61. package/src/server/files.ts +19 -3
  62. package/src/server/index.ts +10 -0
  63. package/src/server/nested.ts +86 -0
  64. package/src/server/server.ts +65 -6
  65. package/src/shell/annotate.ts +157 -7
  66. package/src/shell/frame.ts +268 -0
  67. package/src/shell/plan.ts +2 -1
  68. package/src/shell/runtime.ts +49 -14
@@ -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
- /** Elements, picked with a click or tap (the one under the pointer is outlined); one pick. */
60
- readonly elements?: boolean;
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
- /** The person pressed Escape while picking an element. */
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: {
@@ -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
- out.push({ id: each.id, state: "attached", ...(rect === undefined ? {} : { rect }) });
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" || typeof words !== "boolean" || (!elements && !words)) {
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 };