@botiverse/porthole 0.13.0 → 0.14.1

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 (77) hide show
  1. package/CHANGELOG.md +770 -0
  2. package/dist/annotate/types.d.ts +36 -4
  3. package/dist/annotate/types.js +6 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +30 -6
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +7 -0
  8. package/dist/compile/policy.js +13 -1
  9. package/dist/config/schema.d.ts +11 -0
  10. package/dist/config/validate.js +19 -0
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/displays/displays.js +3 -1
  13. package/dist/guide/limits.js +1 -1
  14. package/dist/host/create-host.d.ts +2 -0
  15. package/dist/host/create-host.js +78 -3
  16. package/dist/host/pass-on.d.ts +15 -0
  17. package/dist/host/pass-on.js +65 -0
  18. package/dist/host/types.d.ts +29 -0
  19. package/dist/index.d.ts +4 -1
  20. package/dist/index.js +4 -1
  21. package/dist/isolation/types.d.ts +8 -0
  22. package/dist/isolation/types.js +8 -0
  23. package/dist/platform/focus-guard.d.ts +71 -2
  24. package/dist/platform/focus-guard.js +187 -12
  25. package/dist/platform/types.d.ts +8 -1
  26. package/dist/platform/web.js +60 -4
  27. package/dist/presets/presets.d.ts +2 -0
  28. package/dist/presets/presets.js +1 -0
  29. package/dist/react/frame.d.ts +4 -3
  30. package/dist/server/files.js +19 -3
  31. package/dist/server/index.d.ts +1 -0
  32. package/dist/server/index.js +5 -0
  33. package/dist/server/naming.js +4 -0
  34. package/dist/server/nested.d.ts +59 -0
  35. package/dist/server/nested.js +96 -0
  36. package/dist/server/server.js +193 -23
  37. package/dist/server/types.d.ts +5 -0
  38. package/dist/shell/annotate.d.ts +4 -3
  39. package/dist/shell/annotate.js +179 -9
  40. package/dist/shell/frame.d.ts +45 -0
  41. package/dist/shell/frame.js +250 -0
  42. package/dist/shell/plan.js +2 -1
  43. package/dist/shell/runtime.d.ts +6 -0
  44. package/dist/shell/runtime.js +60 -15
  45. package/docs/ADOPTING.md +85 -2
  46. package/docs/ARCHITECTURE.md +28 -0
  47. package/docs/DECISIONS.md +416 -1
  48. package/docs/DESIGN.md +21 -4
  49. package/docs/THREAT_MODEL.md +102 -5
  50. package/package.json +6 -5
  51. package/src/annotate/types.ts +32 -4
  52. package/src/annotate/validate.ts +34 -8
  53. package/src/compile/policy.ts +14 -1
  54. package/src/config/schema.ts +11 -0
  55. package/src/config/validate.ts +23 -0
  56. package/src/displays/displays.ts +3 -1
  57. package/src/guide/limits.ts +1 -1
  58. package/src/host/create-host.ts +81 -4
  59. package/src/host/pass-on.ts +73 -0
  60. package/src/host/types.ts +27 -0
  61. package/src/index.ts +4 -1
  62. package/src/isolation/types.ts +12 -0
  63. package/src/platform/focus-guard.ts +258 -15
  64. package/src/platform/types.ts +8 -1
  65. package/src/platform/web.ts +81 -9
  66. package/src/presets/presets.ts +3 -0
  67. package/src/react/frame.tsx +4 -3
  68. package/src/server/files.ts +19 -3
  69. package/src/server/index.ts +14 -0
  70. package/src/server/naming.ts +4 -0
  71. package/src/server/nested.ts +116 -0
  72. package/src/server/server.ts +224 -21
  73. package/src/server/types.ts +5 -0
  74. package/src/shell/annotate.ts +179 -9
  75. package/src/shell/frame.ts +268 -0
  76. package/src/shell/plan.ts +2 -1
  77. package/src/shell/runtime.ts +61 -15
@@ -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
  }
@@ -71,7 +76,8 @@ export interface AnnotationMark {
71
76
  readonly anchor: AnnotationAnchor;
72
77
  /**
73
78
  * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
74
- * `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
79
+ * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
80
+ * the bubble alone) at the end of a
75
81
  * text anchor and the top right of an element. The person can click it: the frame reports
76
82
  * `activated`. The content can read the number; give one only where the page may know it. A
77
83
  * draft's is dropped (P107): its marker has no number.
@@ -95,6 +101,12 @@ export interface AnchorResult {
95
101
  readonly state: AnchorState;
96
102
  /** Where it is now, when attached. */
97
103
  readonly rect?: AnnotationRect;
104
+ /**
105
+ * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
106
+ * marks included, for a host that lists marks in reading order. The content's word: an order to
107
+ * sort by, never a fact.
108
+ */
109
+ readonly order?: number;
98
110
  }
99
111
  /** What the frame reports, once the host has checked it. */
100
112
  export type AnnotationReport =
@@ -108,7 +120,11 @@ export type AnnotationReport =
108
120
  | {
109
121
  readonly type: "unselected";
110
122
  }
111
- /** The person pressed Escape while picking an element. */
123
+ /**
124
+ * The person pressed Escape while picking an element (the pick ends), or while selecting text
125
+ * (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
126
+ * send it, and the host takes it only while it asked for a pick or for text.
127
+ */
112
128
  | {
113
129
  readonly type: "cancelled";
114
130
  }
@@ -123,6 +139,16 @@ export type AnnotationReport =
123
139
  readonly type: "anchored";
124
140
  readonly results: readonly AnchorResult[];
125
141
  }
142
+ /**
143
+ * The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
144
+ * an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
145
+ * frame. The content's word: where to put a card beside it, nothing more.
146
+ */
147
+ | {
148
+ readonly type: "tracked";
149
+ readonly id: string;
150
+ readonly rect: AnnotationRect;
151
+ }
126
152
  /**
127
153
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
128
154
  * (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
@@ -153,6 +179,12 @@ export declare const ANNOTATE_METHODS: {
153
179
  readonly anchored: "porthole/annotate.anchored";
154
180
  /** Frame → host: a mark's marker was clicked (P104). */
155
181
  readonly activated: "porthole/annotate.activated";
182
+ /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
183
+ readonly track: "porthole/annotate.track";
184
+ /** Frame → host: the followed mark's box, as it moves (P112). */
185
+ readonly tracked: "porthole/annotate.tracked";
186
+ /** Host → frame: take the page's text selection away, telling nothing back (P115). */
187
+ readonly clearSelection: "porthole/annotate.clearSelection";
156
188
  };
157
189
  /** The most of each part of an anchor or report the host takes. */
158
190
  export declare const ANNOTATION_LIMITS: {
@@ -30,6 +30,12 @@ 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",
37
+ /** Host → frame: take the page's text selection away, telling nothing back (P115). */
38
+ clearSelection: "porthole/annotate.clearSelection",
33
39
  };
34
40
  /** The most of each part of an anchor or report the host takes. */
35
41
  export const ANNOTATION_LIMITS = {
@@ -28,7 +28,8 @@ export declare function annotateMode(mode: AnnotateMode | undefined): Required<A
28
28
  */
29
29
  export declare const hasMarker: (mark: AnnotationMark) => boolean;
30
30
  /**
31
- * The host's marks, checked before they go to the frame; throws on the first bad one. Each is
31
+ * The host's marks, checked before they go to the frame; throws on the first bad one (a count above
32
+ * `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
32
33
  * rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
33
34
  * `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
34
35
  * told one).
@@ -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 };
@@ -172,7 +189,8 @@ export function annotateMode(mode) {
172
189
  */
173
190
  export const hasMarker = (mark) => mark.count !== undefined || mark.kind === "draft";
174
191
  /**
175
- * The host's marks, checked before they go to the frame; throws on the first bad one. Each is
192
+ * The host's marks, checked before they go to the frame; throws on the first bad one (a count above
193
+ * `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
176
194
  * rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
177
195
  * `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
178
196
  * told one).
@@ -187,8 +205,10 @@ export function checkMarks(marks) {
187
205
  if (!markId(mark?.id) || seen.has(mark.id) || anchor === null) {
188
206
  throw new TypeError(`annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`);
189
207
  }
190
- if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
191
- throw new TypeError(`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`);
208
+ // A count above the limit is clamped to it (P116): the marker reads "99+" either way, and a
209
+ // count is data anyone can grow (a thread's replies), so it mustn't reject the whole list.
210
+ if (mark.count !== undefined && !count(mark.count, Infinity)) {
211
+ throw new TypeError(`annotations.show: mark ${index}'s count is a whole number, 0 or more`);
192
212
  }
193
213
  const kind = mark.kind;
194
214
  if (kind !== undefined && kind !== "posted" && kind !== "draft") {
@@ -198,6 +218,10 @@ export function checkMarks(marks) {
198
218
  if (kind === "draft") {
199
219
  return { id: mark.id, anchor, kind };
200
220
  }
201
- return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
221
+ return {
222
+ id: mark.id,
223
+ anchor,
224
+ ...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
225
+ };
202
226
  });
203
227
  }