@botiverse/porthole 0.14.0 → 0.14.2

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 (46) hide show
  1. package/CHANGELOG.md +782 -0
  2. package/dist/annotate/types.d.ts +4 -1
  3. package/dist/annotate/types.js +2 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +11 -4
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.js +2 -2
  8. package/dist/conformance/harness-source.js +1 -1
  9. package/dist/host/create-host.js +5 -0
  10. package/dist/host/types.d.ts +7 -0
  11. package/dist/react/frame.d.ts +30 -4
  12. package/dist/react/frame.js +69 -5
  13. package/dist/react/index.d.ts +1 -1
  14. package/dist/react/view.js +10 -4
  15. package/dist/server/index.d.ts +1 -1
  16. package/dist/server/index.js +4 -3
  17. package/dist/server/naming.js +4 -0
  18. package/dist/server/nested.d.ts +24 -2
  19. package/dist/server/nested.js +28 -2
  20. package/dist/server/server.js +145 -25
  21. package/dist/server/types.d.ts +5 -0
  22. package/dist/shell/annotate.d.ts +3 -2
  23. package/dist/shell/annotate.js +22 -2
  24. package/dist/shell/runtime.d.ts +6 -0
  25. package/dist/shell/runtime.js +11 -1
  26. package/docs/ADOPTING.md +55 -7
  27. package/docs/ARCHITECTURE.md +10 -5
  28. package/docs/DECISIONS.md +248 -1
  29. package/docs/DESIGN.md +18 -7
  30. package/docs/THREAT_MODEL.md +30 -3
  31. package/package.json +6 -5
  32. package/src/annotate/types.ts +4 -1
  33. package/src/annotate/validate.ts +11 -6
  34. package/src/compile/policy.ts +2 -2
  35. package/src/host/create-host.ts +5 -0
  36. package/src/host/types.ts +7 -0
  37. package/src/react/frame.tsx +114 -6
  38. package/src/react/index.ts +1 -0
  39. package/src/react/view.tsx +20 -2
  40. package/src/server/index.ts +6 -2
  41. package/src/server/naming.ts +4 -0
  42. package/src/server/nested.ts +32 -2
  43. package/src/server/server.ts +168 -24
  44. package/src/server/types.ts +5 -0
  45. package/src/shell/annotate.ts +22 -2
  46. package/src/shell/runtime.ts +12 -1
@@ -7,6 +7,7 @@ import {
7
7
  useEffect,
8
8
  useEffectEvent,
9
9
  useId,
10
+ useImperativeHandle,
10
11
  useLayoutEffect,
11
12
  useMemo,
12
13
  useRef,
@@ -15,6 +16,7 @@ import {
15
16
  type CSSProperties,
16
17
  type ReactElement,
17
18
  type ReactNode,
19
+ type Ref,
18
20
  } from "react";
19
21
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
20
22
  import type {
@@ -480,6 +482,21 @@ export interface PlaceholderProps {
480
482
  readonly run: () => void;
481
483
  }
482
484
 
485
+ /**
486
+ * What a `ref` on `PortholeFrame` or `PortholeView` holds (P118): the display's few imperative
487
+ * calls, never the display itself. The same handle for the frame's whole life: its calls do
488
+ * nothing while no display runs (waiting to near the screen, stopped, a fallback drawn).
489
+ */
490
+ export interface PortholeFrameHandle {
491
+ /**
492
+ * Takes the page's text selection away, and its highlight (`annotations.clearSelection()`,
493
+ * P115), once the host has used it (a comment posted, a draft added). No `unselected` follows.
494
+ * Nothing runs: nothing happens. A config without `annotate`: `onHostError`, kind
495
+ * `"annotations"` (the core's call throws; this never does).
496
+ */
497
+ clearSelection(): void;
498
+ }
499
+
483
500
  export interface PortholeFrameProps {
484
501
  /** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
485
502
  readonly config: PortholeConfig;
@@ -500,10 +517,11 @@ export interface PortholeFrameProps {
500
517
  readonly instance?: InstanceRef;
501
518
  /**
502
519
  * What the page declared (P086), as the host stored it with the artifact: the capabilities it
503
- * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
504
- * again.
520
+ * reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
521
+ * the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
522
+ * value: a change makes the display again.
505
523
  */
506
- readonly declaration?: PageDeclaration;
524
+ readonly declaration?: PageDeclaration | null;
507
525
  /**
508
526
  * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
509
527
  * makes the display again.
@@ -605,6 +623,17 @@ export interface PortholeFrameProps {
605
623
  | string
606
624
  | { readonly id: string; readonly key: string | number }
607
625
  | null;
626
+ /**
627
+ * The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
628
+ * `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
629
+ * leaving it out once set) stops. By value: given when it changes, and when the display is made.
630
+ * Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
631
+ * `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
632
+ * stop the following, as the core's `show` does; it starts again once they have it back.
633
+ */
634
+ readonly trackedAnnotation?: string | null;
635
+ /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
636
+ readonly ref?: Ref<PortholeFrameHandle>;
608
637
  /**
609
638
  * What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
610
639
  * pick, where marks are (again once a scroll settles: those that moved), a marker clicked
@@ -673,7 +702,29 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
673
702
  () => live.state(key),
674
703
  (): FrameState => "waiting",
675
704
  );
676
- const { eager } = props;
705
+ const { eager, ref: handleRef } = props;
706
+ // The running display (the Mount's), for the handle's calls; null while none runs.
707
+ const display = useRef<DisplayHandle | null>(null);
708
+ const running = useCallback((each: DisplayHandle | null) => {
709
+ display.current = each;
710
+ }, []);
711
+ // The props as of the last render, read when the handle is called (never during render).
712
+ const own = useRef(props);
713
+ useLayoutEffect(() => {
714
+ own.current = props;
715
+ });
716
+ useImperativeHandle(
717
+ handleRef,
718
+ (): PortholeFrameHandle => ({
719
+ clearSelection() {
720
+ const now = display.current;
721
+ if (now !== null) {
722
+ attempt(() => now.annotations.clearSelection(), own.current);
723
+ }
724
+ },
725
+ }),
726
+ [],
727
+ );
677
728
 
678
729
  useEffect(() => {
679
730
  const element = box.current;
@@ -742,6 +793,7 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
742
793
  key={String(props.generation ?? 0)}
743
794
  frame={props}
744
795
  page={page}
796
+ running={running}
745
797
  initialHeightPx={height}
746
798
  placeholder={placeholder}
747
799
  run={run}
@@ -756,6 +808,8 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
756
808
  interface MountProps {
757
809
  readonly frame: PortholeFrameProps;
758
810
  readonly page: PageState;
811
+ /** Tells the frame which display runs now (null: none), for its handle. */
812
+ readonly running: (display: DisplayHandle | null) => void;
759
813
  readonly initialHeightPx: number;
760
814
  readonly placeholder: (props: PlaceholderProps) => ReactNode;
761
815
  readonly run: () => void;
@@ -764,9 +818,19 @@ interface MountProps {
764
818
  type AnyHandler = (args: unknown, context: CallContext) => unknown;
765
819
 
766
820
  /** One running display: created when mounted, torn down when unmounted, fed as props change. */
767
- function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps): ReactElement {
821
+ function Mount({
822
+ frame,
823
+ page,
824
+ running,
825
+ initialHeightPx,
826
+ placeholder,
827
+ run,
828
+ }: MountProps): ReactElement {
768
829
  const holder = useRef<HTMLDivElement>(null);
769
830
  const handle = useRef<DisplayHandle | null>(null);
831
+ // The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
832
+ const following = useRef<string | null>(null);
833
+ const asked = useRef<string | null>(null);
770
834
  const [ready, setReady] = useState(false);
771
835
  // The height this display started at: later reports don't make it start again.
772
836
  const [startHeight] = useState(initialHeightPx);
@@ -968,6 +1032,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
968
1032
  return;
969
1033
  }
970
1034
  handle.current = display;
1035
+ running(display);
971
1036
  const events: (keyof DisplayEvents)[] = [
972
1037
  "initialized",
973
1038
  "resize",
@@ -988,12 +1053,24 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
988
1053
  if (config.capabilities.annotate !== undefined) {
989
1054
  applyAnnotations(display, first);
990
1055
  }
1056
+ // The followed mark, once the marks are shown; without `annotate`, the core's error.
1057
+ following.current = null;
1058
+ const wanted = first.trackedAnnotation ?? null;
1059
+ asked.current = wanted;
1060
+ if (wanted !== null) {
1061
+ attempt(() => {
1062
+ display.annotations.track(wanted);
1063
+ following.current = wanted;
1064
+ }, first);
1065
+ }
991
1066
  if (first.content !== undefined) {
992
1067
  display.setContent(first.content, { partial: first.partial === true });
993
1068
  }
994
1069
  return () => {
995
1070
  display.destroy();
996
1071
  handle.current = null;
1072
+ running(null);
1073
+ following.current = null;
997
1074
  };
998
1075
  // A new display only for a new config, document or instance, or what the provider makes
999
1076
  // displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
@@ -1016,6 +1093,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
1016
1093
  hostInfo,
1017
1094
  locate,
1018
1095
  nonce,
1096
+ running,
1019
1097
  ]);
1020
1098
 
1021
1099
  useEffect(() => {
@@ -1056,9 +1134,34 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
1056
1134
  useEffect(() => {
1057
1135
  const display = handle.current;
1058
1136
  if (annotates && display !== null) {
1059
- attempt(() => display.annotations.show(annotations ?? []), latest());
1137
+ attempt(() => {
1138
+ display.annotations.show(annotations ?? []);
1139
+ // A show without the followed mark stops the following (the core's own).
1140
+ if (following.current !== null && !shown(annotations, following.current)) {
1141
+ following.current = null;
1142
+ }
1143
+ }, latest());
1060
1144
  }
1061
1145
  }, [annotates, annotations]);
1146
+ // The followed mark follows its prop (after the marks above, so the two can change together).
1147
+ const trackedAnnotation = frame.trackedAnnotation ?? null;
1148
+ useEffect(() => {
1149
+ const display = handle.current;
1150
+ const changed = trackedAnnotation !== asked.current;
1151
+ asked.current = trackedAnnotation;
1152
+ if (display === null || trackedAnnotation === following.current) {
1153
+ return;
1154
+ }
1155
+ // Its mark was taken off (the error, if any, was told when the prop said it): followed again
1156
+ // once the marks have it back.
1157
+ if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
1158
+ return;
1159
+ }
1160
+ attempt(() => {
1161
+ display.annotations.track(trackedAnnotation);
1162
+ following.current = trackedAnnotation;
1163
+ }, latest());
1164
+ }, [trackedAnnotation, annotations]);
1062
1165
  useEffect(() => {
1063
1166
  const display = handle.current;
1064
1167
  const id = focusOf(latest().focusedAnnotation);
@@ -1160,6 +1263,11 @@ function useByValue<T>(value: T): T {
1160
1263
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
1161
1264
  }
1162
1265
 
1266
+ /** Whether `marks` has a mark `id`. */
1267
+ function shown(marks: readonly AnnotationMark[] | undefined, id: string): boolean {
1268
+ return (marks ?? []).some((mark) => mark.id === id);
1269
+ }
1270
+
1163
1271
  /** The id `focusedAnnotation` names, if any. */
1164
1272
  function focusOf(value: PortholeFrameProps["focusedAnnotation"]): string | null {
1165
1273
  return typeof value === "string"
@@ -13,6 +13,7 @@ export {
13
13
  PortholeFrame,
14
14
  PortholeProvider,
15
15
  type PlaceholderProps,
16
+ type PortholeFrameHandle,
16
17
  type PortholeFrameProps,
17
18
  type ConfirmActions,
18
19
  type PortholeProviderProps,
@@ -2,6 +2,8 @@ import {
2
2
  useCallback,
3
3
  useContext,
4
4
  useEffect,
5
+ useImperativeHandle,
6
+ useRef,
5
7
  useState,
6
8
  useSyncExternalStore,
7
9
  type ReactElement,
@@ -11,7 +13,12 @@ import type { ColorScheme } from "../config/schema.ts";
11
13
  import { frameFallback, type FrameFallback, type PortholeClient } from "../host/client.ts";
12
14
  import type { FrameOutcome } from "../host/types.ts";
13
15
  import type { InstanceRef } from "../isolation/types.ts";
14
- import { PortholeFrame, PortholeContext, type PortholeFrameProps } from "./frame.tsx";
16
+ import {
17
+ PortholeFrame,
18
+ PortholeContext,
19
+ type PortholeFrameHandle,
20
+ type PortholeFrameProps,
21
+ } from "./frame.tsx";
15
22
 
16
23
  /**
17
24
  * The host kit's React side (P072): a display by its kind, served or opaque as the server says
@@ -91,7 +98,17 @@ function DefaultFallback({ title, message, link }: PortholeFallbackProps): React
91
98
  export function PortholeView(props: PortholeViewProps): ReactElement | null {
92
99
  const client = useClient();
93
100
  const meta = useMeta(client);
94
- const { display, instance, content, fallback, pending, onOutcome, ...frame } = props;
101
+ const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
102
+ // The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
103
+ // the frame's display when one runs, and do nothing otherwise.
104
+ const shown = useRef<PortholeFrameHandle>(null);
105
+ useImperativeHandle(
106
+ ref,
107
+ (): PortholeFrameHandle => ({
108
+ clearSelection: () => shown.current?.clearSelection(),
109
+ }),
110
+ [],
111
+ );
95
112
  const [failed, setFailed] = useState<FrameFallback | null>(null);
96
113
  const [generation, setGeneration] = useState(0);
97
114
  const [link, setLink] = useState<string | null>(null);
@@ -145,6 +162,7 @@ export function PortholeView(props: PortholeViewProps): ReactElement | null {
145
162
  return (
146
163
  <PortholeFrame
147
164
  {...frame}
165
+ ref={shown}
148
166
  config={config}
149
167
  generation={(frame.generation ?? 0) + generation}
150
168
  {...(instance === undefined ? {} : { instance })}
@@ -71,14 +71,18 @@ export {
71
71
  } from "./tickets.ts";
72
72
  export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
73
73
  // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
74
- // sealed prefix. `/server` serves them for a config with `nested`; a content Worker of its own
75
- // answers the same (docs/ADOPTING.md, "Nested pages").
74
+ // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
75
+ // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
76
+ // pages").
76
77
  export {
78
+ isNestedLabel,
77
79
  NESTED_FILE_HEADERS,
78
80
  NESTED_FILES_PREFIX,
79
81
  nestedAncestors,
82
+ nestedLabelOf,
80
83
  nestedShellCsp,
81
84
  nestedShellResponse,
85
+ PORTHOLE_LABEL_PREFIX,
82
86
  } from "./nested.ts";
83
87
  export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
84
88
  // The page an app serves in conformance test mode (P071).
@@ -42,6 +42,10 @@ export function prefixedName(prefix: string): Naming & {
42
42
  "A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
43
43
  );
44
44
  }
45
+ // Porthole's own labels (a nested page's shell's, P114) are never a scope's.
46
+ if (prefix === "porthole-") {
47
+ throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
48
+ }
45
49
  const name = (scope: string): string => {
46
50
  const label = `${prefix}${scope}`;
47
51
  if (!ID.test(scope) || !isHostLabel(label)) {
@@ -2,14 +2,44 @@ import type { CompiledConfig } from "../compile/compile.ts";
2
2
  import { servedPermissionsPolicy, serializeCsp, type CspDirective } from "../compile/policy.ts";
3
3
  import { frameShellDocument, frameShellScript, type FrameShellOptions } from "../shell/frame.ts";
4
4
  import { sha256, utf8 } from "./crypto.ts";
5
+ import { base32 } from "./keys.ts";
5
6
 
6
7
  /**
7
8
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
8
9
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
9
10
  * (`nestedAncestors`, `NESTED_FILE_HEADERS`). `/server` serves both for a config with `nested`;
10
11
  * a host serving its own content origin (its own Worker) answers the same.
12
+ *
13
+ * All of it is served on the shell's own label (P114, `nestedLabelOf`), never on the scope's: every
14
+ * other display of the scope runs agent-made content on the scope's origin with
15
+ * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
16
+ * address.
11
17
  */
12
18
 
19
+ /**
20
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
21
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
22
+ */
23
+ export const PORTHOLE_LABEL_PREFIX = "porthole-";
24
+
25
+ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
26
+
27
+ /**
28
+ * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
29
+ * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
30
+ * content label is ever one (a keyed label has no hyphen, a host's is refused the prefix), so
31
+ * nothing but a nested page's shell, its opaque page, that page's files and Porthole's status pages
32
+ * is ever served on it: no other display's content runs there with `allow-same-origin`. Not a
33
+ * secret: anyone who knows the scope's label may work it out. A content Worker of a host's own
34
+ * serves its nested pages on it too.
35
+ */
36
+ export function nestedLabelOf(label: string): string {
37
+ return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
38
+ }
39
+
40
+ /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
41
+ export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
42
+
13
43
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
14
44
  export const NESTED_FILES_PREFIX = "/__porthole/f/";
15
45
 
@@ -68,8 +98,8 @@ export function nestedShellResponse(
68
98
  }
69
99
 
70
100
  /**
71
- * Who may frame a nested page and its files' answers: its shell (the content origin) and, above
72
- * it, the host origins (`frame-ancestors` names every ancestor).
101
+ * Who may frame a nested page and its files' answers: its shell (the shell's own origin, P114) and,
102
+ * above it, the host origins (`frame-ancestors` names every ancestor).
73
103
  */
74
104
  export const nestedAncestors = (origin: string, frameAncestors: string): string =>
75
105
  `${origin} ${frameAncestors}`;