@botiverse/porthole 0.3.0 → 0.3.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 (51) hide show
  1. package/README.md +3 -2
  2. package/dist/check/check.d.ts +18 -1
  3. package/dist/check/check.js +84 -6
  4. package/dist/check/drivers.d.ts +25 -6
  5. package/dist/check/drivers.js +99 -28
  6. package/dist/check/index.d.ts +2 -2
  7. package/dist/check/index.js +1 -1
  8. package/dist/check/instrument.d.ts +71 -0
  9. package/dist/check/instrument.js +84 -0
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.d.ts +2 -40
  12. package/dist/check/page.js +63 -43
  13. package/dist/conformance/host-kit.d.ts +18 -5
  14. package/dist/conformance/host-kit.js +38 -21
  15. package/dist/conformance/index.d.ts +1 -1
  16. package/dist/conformance/reporter.d.ts +14 -0
  17. package/dist/conformance/reporter.js +28 -0
  18. package/dist/host/client.d.ts +33 -15
  19. package/dist/host/client.js +39 -24
  20. package/dist/node/index.d.ts +6 -2
  21. package/dist/node/index.js +53 -8
  22. package/dist/react/frame.d.ts +13 -5
  23. package/dist/react/frame.js +67 -27
  24. package/dist/react/index.d.ts +1 -1
  25. package/dist/react/view.js +6 -1
  26. package/dist/server/host.d.ts +5 -3
  27. package/dist/server/host.js +41 -12
  28. package/docs/ADOPTING.md +108 -25
  29. package/docs/DECISIONS.md +134 -0
  30. package/docs/DESIGN.md +36 -12
  31. package/examples/app.mjs +23 -17
  32. package/examples/conformance/playwright.config.mjs +2 -1
  33. package/examples/conformance/porthole.spec.mjs +2 -1
  34. package/examples/displays.mjs +2 -0
  35. package/examples/node/server.mjs +16 -34
  36. package/examples/workers/worker.mjs +19 -7
  37. package/package.json +5 -1
  38. package/src/check/check.ts +116 -8
  39. package/src/check/drivers.ts +137 -39
  40. package/src/check/index.ts +8 -1
  41. package/src/check/instrument.ts +138 -0
  42. package/src/check/page.ts +94 -68
  43. package/src/conformance/host-kit.ts +65 -19
  44. package/src/conformance/index.ts +1 -0
  45. package/src/conformance/reporter.ts +38 -0
  46. package/src/host/client.ts +65 -34
  47. package/src/node/index.ts +56 -10
  48. package/src/react/frame.tsx +89 -33
  49. package/src/react/index.ts +1 -0
  50. package/src/react/view.tsx +6 -1
  51. package/src/server/host.ts +53 -15
@@ -44,36 +44,45 @@ export interface PortholeClientOptions<N extends string> {
44
44
  readonly fetch?: typeof fetch;
45
45
  }
46
46
 
47
+ /**
48
+ * Every function is declared `this: void` (P074): each may be passed bare
49
+ * (`useSyncExternalStore(porthole.subscribe, porthole.meta)`), and none reads `this`.
50
+ */
47
51
  export interface PortholeClient<N extends string = string> extends InstanceLocator {
48
52
  readonly displays: Displays<N>;
53
+ /** Locates an instance's frame through `POST <base>/frames` (`InstanceLocator`). */
54
+ locate(this: void, instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
49
55
  /** The meta as last fetched, or null before it is known. */
50
- meta(): ContentClientMeta | null;
56
+ meta(this: void): ContentClientMeta | null;
51
57
  /** Called when the meta changes (frames served or not). */
52
- subscribe(listener: () => void): () => void;
58
+ subscribe(this: void, listener: () => void): () => void;
53
59
  /** Fetches the meta again. */
54
- refresh(): Promise<ContentClientMeta | null>;
60
+ refresh(this: void): Promise<ContentClientMeta | null>;
55
61
  /**
56
62
  * The config a kind shows under now: served while frames are served, else opaque (a url kind:
57
63
  * null). Null until the meta is known, so a frame never starts opaque and then restarts served.
58
64
  */
59
- config(kind: N): PortholeConfig | null;
65
+ config(this: void, kind: N): PortholeConfig | null;
60
66
  /** The same, for an instance's kind. */
61
- configFor(instance: InstanceRef): PortholeConfig | null;
67
+ configFor(this: void, instance: InstanceRef): PortholeConfig | null;
62
68
  /** An instance's clean address (`entry.pathOf` on the server), or null. */
63
- link(instance: InstanceRef): Promise<string | null>;
69
+ link(this: void, instance: InstanceRef): Promise<string | null>;
64
70
  /** The clean address if already known (from locating the instance), for rendering. */
65
- knownLink(instance: InstanceRef): string | null;
71
+ knownLink(this: void, instance: InstanceRef): string | null;
66
72
  /**
67
73
  * Opens an instance's clean address in a new tab: call it in the click (the tab opens at once,
68
74
  * then goes to the address).
69
75
  */
70
- openInTab(instance: InstanceRef): void;
76
+ openInTab(this: void, instance: InstanceRef): void;
71
77
  /** Hands the signed-in viewer to the authorize route (`entry.handoff`); true if it took. */
72
- handoff(): Promise<boolean>;
73
- /** `next` if it is this server's authorize route (after a sign-in), else null (`entryTarget`). */
74
- entryTarget(next: unknown): string | null;
78
+ handoff(this: void): Promise<boolean>;
79
+ /**
80
+ * `next` if it is this server's authorize route (after a sign-in), or with `{ app: true }` any
81
+ * address on the app's own origin; else null (`entryTarget`).
82
+ */
83
+ entryTarget(this: void, next: unknown, options?: { readonly app?: boolean }): string | null;
75
84
  /** Stops refreshing the handoff. */
76
- close(): void;
85
+ close(this: void): void;
77
86
  }
78
87
 
79
88
  const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -81,9 +90,18 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
81
90
 
82
91
  /**
83
92
  * Whether a sign-in's `next` is the app's authorize route (P072): the open-redirect guard a
84
- * single-page app runs before going on to it. Null for anything else.
93
+ * single-page app runs before going on to it. Null for anything else; with `{ app: true }`, also
94
+ * any path or address on the app's own origin (P074), so one check serves a sign-in that comes
95
+ * back to redirect entry or to the app's own pages. Never another origin.
96
+ *
97
+ * The authorize route is `<first app origin><prefix>/authorize` unless the server names another
98
+ * (`entry.authorizeUrl`): `https://app.example.com/porthole/authorize` by default.
85
99
  */
86
- export function entryTarget(next: unknown, authorizeUrl: string): string | null {
100
+ export function entryTarget(
101
+ next: unknown,
102
+ authorizeUrl: string,
103
+ options: { readonly app?: boolean } = {},
104
+ ): string | null {
87
105
  if (typeof next !== "string" || next.length > 8_192) {
88
106
  return null;
89
107
  }
@@ -95,10 +113,19 @@ export function entryTarget(next: unknown, authorizeUrl: string): string | null
95
113
  } catch {
96
114
  return null;
97
115
  }
98
- return target.origin === route.origin &&
116
+ if (
117
+ target.origin === route.origin &&
99
118
  target.pathname === route.pathname &&
100
119
  target.hash === "" &&
101
120
  target.searchParams.has("state")
121
+ ) {
122
+ return target.href;
123
+ }
124
+ // An app path: one leading slash, no backslash (`//evil.example` and `/\evil.example` are
125
+ // other sites to a browser), and still the app's origin once resolved.
126
+ const path = /^\/(?![/\\])/u.test(next) && !next.includes("\\");
127
+ const absolute = /^https?:\/\//iu.test(next);
128
+ return options.app === true && (path || absolute) && target.origin === route.origin
102
129
  ? target.href
103
130
  : null;
104
131
  }
@@ -245,30 +272,34 @@ export function portholeClient<N extends string>(
245
272
  document.addEventListener("visibilitychange", fresh);
246
273
  }
247
274
 
275
+ const link = async (instance: InstanceRef): Promise<string | null> => {
276
+ const key = keyOf(instance);
277
+ if (!links.has(key)) {
278
+ try {
279
+ await issue(instance);
280
+ } catch {
281
+ return null;
282
+ }
283
+ }
284
+ return links.get(key) ?? null;
285
+ };
286
+
248
287
  return {
249
288
  displays: options.displays,
250
289
  meta: () => meta,
251
- subscribe(listener) {
290
+ subscribe: (listener) => {
252
291
  listeners.add(listener);
253
- return () => listeners.delete(listener);
292
+ return () => {
293
+ listeners.delete(listener);
294
+ };
254
295
  },
255
296
  refresh,
256
297
  config: (kind) => configOf(kind),
257
298
  configFor: (instance) => configOf(options.displays.kindOf(instance)),
258
299
  locate: issue,
259
- async link(instance) {
260
- const key = keyOf(instance);
261
- if (!links.has(key)) {
262
- try {
263
- await issue(instance);
264
- } catch {
265
- return null;
266
- }
267
- }
268
- return links.get(key) ?? null;
269
- },
300
+ link,
270
301
  knownLink: (instance) => links.get(keyOf(instance)) ?? null,
271
- openInTab(instance) {
302
+ openInTab: (instance) => {
272
303
  // Opened inside the click (a popup blocker lets it), then sent to the address.
273
304
  const tab = typeof window === "undefined" ? null : window.open("about:blank", "_blank");
274
305
  if (tab === null) {
@@ -276,17 +307,17 @@ export function portholeClient<N extends string>(
276
307
  }
277
308
  tab.opener = null;
278
309
  void (async () => {
279
- const link = await this.link(instance);
280
- if (link === null) {
310
+ const found = await link(instance);
311
+ if (found === null) {
281
312
  tab.close();
282
313
  } else {
283
- tab.location.href = link;
314
+ tab.location.href = found;
284
315
  }
285
316
  })();
286
317
  },
287
318
  handoff,
288
- entryTarget: (next) => entryTarget(next, url("/authorize")),
289
- close() {
319
+ entryTarget: (next, given) => entryTarget(next, url("/authorize"), given),
320
+ close: () => {
290
321
  if (watching) {
291
322
  window.removeEventListener("focus", fresh);
292
323
  document.removeEventListener("visibilitychange", fresh);
package/src/node/index.ts CHANGED
@@ -292,8 +292,12 @@ export function nodeProbe(): HealthProbe {
292
292
  }
293
293
 
294
294
  export interface NodeServerOptions {
295
- /** The content host. */
296
- readonly content: ContentHost<unknown>;
295
+ /**
296
+ * The content host, or a function giving it when it exists: a host made after the server listens
297
+ * (its content domain names the port `listen(0)` chose, P074). Until it gives one, every request
298
+ * is the app's; the health gate starts when it first does.
299
+ */
300
+ readonly content: ContentHost<unknown> | (() => ContentHost<unknown> | null);
297
301
  /**
298
302
  * The app, fetch-style (Hono's `app.fetch`, or the app's own handler): every request that
299
303
  * isn't the content domain's. Or `request`, a Node listener (Express).
@@ -335,14 +339,56 @@ export function nodeServer(options: NodeServerOptions): Server {
335
339
  if (request === undefined) {
336
340
  throw new TypeError("nodeServer needs the app: app (fetch-style) or request (a Node listener)");
337
341
  }
338
- const porthole = nodeHost(options.content, {
339
- request,
340
- ...(options.upgrade === undefined ? {} : { upgrade: options.upgrade }),
341
- ...(options.appSocket === undefined ? {} : { appSocket: options.appSocket }),
342
+ const adapters = new WeakMap<ContentHost<unknown>, NodeHost>();
343
+ const started = new WeakSet<ContentHost<unknown>>();
344
+ let listening = false;
345
+ const given = options.content;
346
+ /** The host now (made once, adapted once), started once the server listens. */
347
+ const current = (): NodeHost | null => {
348
+ const host = typeof given === "function" ? given() : given;
349
+ if (host === null) {
350
+ return null;
351
+ }
352
+ let adapter = adapters.get(host);
353
+ if (adapter === undefined) {
354
+ adapter = nodeHost(host, {
355
+ request,
356
+ ...(options.upgrade === undefined ? {} : { upgrade: options.upgrade }),
357
+ ...(options.appSocket === undefined ? {} : { appSocket: options.appSocket }),
358
+ });
359
+ adapters.set(host, adapter);
360
+ }
361
+ if (listening && !started.has(host)) {
362
+ started.add(host);
363
+ host.start();
364
+ }
365
+ return adapter;
366
+ };
367
+ const server = createHttpServer((incoming, response) => {
368
+ const adapter = current();
369
+ if (adapter === null) {
370
+ request(incoming, response);
371
+ } else {
372
+ adapter.request(incoming, response);
373
+ }
374
+ });
375
+ server.on("upgrade", (incoming: IncomingMessage, socket: Duplex, head: Buffer) => {
376
+ const adapter = current();
377
+ if (adapter !== null) {
378
+ adapter.upgrade(incoming, socket, head);
379
+ } else if (options.upgrade !== undefined) {
380
+ options.upgrade(incoming, socket, head);
381
+ } else {
382
+ refuseSocket(socket);
383
+ }
384
+ });
385
+ server.on("listening", () => {
386
+ listening = true;
387
+ current();
388
+ });
389
+ server.on("close", () => {
390
+ const host = typeof given === "function" ? given() : given;
391
+ host?.close();
342
392
  });
343
- const server = createHttpServer(porthole.request);
344
- server.on("upgrade", porthole.upgrade);
345
- server.on("listening", () => options.content.start());
346
- server.on("close", () => options.content.close());
347
393
  return server;
348
394
  }
@@ -110,12 +110,11 @@ export interface PortholeProviderProps {
110
110
  /**
111
111
  * Draws the confirmation in the app's own dialog, for the request at the head of the queue:
112
112
  * Porthole keeps the queue (one question at a time), runs `accept` inside the click, and counts
113
- * declines. Omitted: Porthole's `ConfirmDialog`. (`confirm` replaces the whole mechanism.)
113
+ * declines. `redirect`: the person took it elsewhere (edited a prompt first, P074): the call
114
+ * doesn't go, and it neither counts toward muting the display nor resets the count. Omitted:
115
+ * Porthole's `ConfirmDialog`. (`confirm` replaces the whole mechanism.)
114
116
  */
115
- readonly renderConfirm?: (
116
- request: ConfirmRequest,
117
- answer: { readonly accept: () => void; readonly decline: () => void },
118
- ) => ReactNode;
117
+ readonly renderConfirm?: (request: ConfirmRequest, answer: ConfirmActions) => ReactNode;
119
118
  /**
120
119
  * Who confirms gated calls for every frame below. Omitted: the default dialog (`ConfirmDialog`).
121
120
  * Pass your own function to replace it.
@@ -138,6 +137,16 @@ export interface PortholeProviderProps {
138
137
  readonly children?: ReactNode;
139
138
  }
140
139
 
140
+ /** What an app's own confirmation dialog answers with (`renderConfirm`). */
141
+ export interface ConfirmActions {
142
+ /** Yes: the call goes, run inside this click. */
143
+ readonly accept: () => void;
144
+ /** No: the call doesn't go, and it counts toward muting the display. */
145
+ readonly decline: () => void;
146
+ /** Elsewhere (the person edits the prompt first): the call doesn't go, and doesn't count. */
147
+ readonly redirect: () => void;
148
+ }
149
+
141
150
  /** The page's own nonce: `<meta name="csp-nonce" content>`, else the first `script[nonce]`'s. */
142
151
  function pageNonce(): string | undefined {
143
152
  if (typeof document === "undefined") {
@@ -292,6 +301,10 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
292
301
  current.resolve("declined");
293
302
  setQueue((waiting) => waiting.slice(1));
294
303
  },
304
+ redirect: () => {
305
+ current.resolve("redirected");
306
+ setQueue((waiting) => waiting.slice(1));
307
+ },
295
308
  })
296
309
  : null}
297
310
  {props.confirm === undefined && props.renderConfirm === undefined ? (
@@ -477,12 +490,15 @@ function rememberedHeight(
477
490
 
478
491
  export function PortholeFrame(props: PortholeFrameProps): ReactElement {
479
492
  const page = useContext(Page);
493
+ // The provider's registry and heights: stable, unlike the context value, which a scheme flip
494
+ // or a new themeKey renews (an effect keyed on it would let the frame go and make it again, #9).
495
+ const { live, heights } = page;
480
496
  const key = useId();
481
497
  const box = useRef<HTMLDivElement>(null);
482
498
  const max = props.config.limits.maxLiveFrames;
483
499
  const state = useSyncExternalStore(
484
- (listener) => page.live.subscribe(listener),
485
- () => page.live.state(key),
500
+ (listener) => live.subscribe(listener),
501
+ () => live.state(key),
486
502
  (): FrameState => "waiting",
487
503
  );
488
504
  const { eager } = props;
@@ -493,9 +509,9 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
493
509
  return;
494
510
  }
495
511
  if (eager === true || typeof IntersectionObserver !== "function") {
496
- page.live.near(key, true);
497
- page.live.admit(key, max);
498
- return () => page.live.release(key);
512
+ live.near(key, true);
513
+ live.admit(key, max);
514
+ return () => live.release(key);
499
515
  }
500
516
  const observer = new IntersectionObserver(
501
517
  (entries) => {
@@ -503,9 +519,9 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
503
519
  if (entry === undefined) {
504
520
  return;
505
521
  }
506
- page.live.near(key, entry.isIntersecting);
522
+ live.near(key, entry.isIntersecting);
507
523
  if (entry.isIntersecting) {
508
- page.live.admit(key, max);
524
+ live.admit(key, max);
509
525
  }
510
526
  },
511
527
  { rootMargin: NEAR_SCREEN },
@@ -513,22 +529,22 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
513
529
  observer.observe(element);
514
530
  return () => {
515
531
  observer.disconnect();
516
- page.live.release(key);
532
+ live.release(key);
517
533
  };
518
- }, [page, key, max, eager]);
534
+ }, [live, key, max, eager]);
519
535
 
520
- const height = rememberedHeight(page.heights, props.displayId, props.aliases);
536
+ const height = rememberedHeight(heights, props.displayId, props.aliases);
521
537
  // A display renamed while it runs (its id settled) keeps its height under its new id.
522
538
  const previousId = useRef(props.displayId);
523
539
  useLayoutEffect(() => {
524
540
  const before = previousId.current;
525
541
  previousId.current = props.displayId;
526
- const kept = page.heights.get(before);
527
- if (before !== props.displayId && kept !== undefined && !page.heights.has(props.displayId)) {
528
- page.heights.set(props.displayId, kept);
542
+ const kept = heights.get(before);
543
+ if (before !== props.displayId && kept !== undefined && !heights.has(props.displayId)) {
544
+ heights.set(props.displayId, kept);
529
545
  }
530
- }, [page, props.displayId]);
531
- const run = () => page.live.admit(key, max);
546
+ }, [heights, props.displayId]);
547
+ const run = () => live.admit(key, max);
532
548
  const placeholder = props.renderPlaceholder ?? DefaultPlaceholder;
533
549
  return (
534
550
  <div
@@ -593,6 +609,18 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
593
609
 
594
610
  // The latest props, read when the display calls back (never during render).
595
611
  const latest = useEffectEvent(() => frame);
612
+ // The provider's scheme and theme, read when used: a flip or a new themeKey (a new context
613
+ // value) re-themes the running display, never makes it again (#9, P074). What a display is
614
+ // made with comes from the provider's stable parts below.
615
+ const latestPage = useEffectEvent(() => page);
616
+ const {
617
+ handlers: pageHandlers,
618
+ copyText: pageCopyText,
619
+ confirm: pageConfirm,
620
+ hostInfo,
621
+ locate,
622
+ nonce,
623
+ } = page;
596
624
  const notify = useEffectEvent(
597
625
  <E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]): void => {
598
626
  switch (event) {
@@ -662,23 +690,23 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
662
690
  const declared = new Set(Object.keys(config.capabilities));
663
691
  for (const name of new Set([
664
692
  ...Object.keys(first.handlers ?? {}),
665
- ...Object.keys(page.handlers?.() ?? {}).filter((each) => declared.has(each)),
693
+ ...Object.keys(pageHandlers?.() ?? {}).filter((each) => declared.has(each)),
666
694
  ])) {
667
695
  handlers[name] = (args, context) =>
668
696
  (
669
697
  (latest().handlers as Record<string, AnyHandler | undefined> | undefined)?.[name] ??
670
- (page.handlers?.() as Record<string, AnyHandler | undefined> | undefined)?.[name]
698
+ (pageHandlers?.() as Record<string, AnyHandler | undefined> | undefined)?.[name]
671
699
  )?.(args, named(context));
672
700
  }
673
701
  // Copy buttons without a handler of the host's: the provider's, which shows a toast.
674
702
  if (config.capabilities.copyText !== undefined && handlers.copyText === undefined) {
675
- const fallback = page.copyText;
703
+ const fallback = pageCopyText;
676
704
  if (fallback !== undefined) {
677
705
  handlers.copyText = (args, context) =>
678
706
  fallback(args as { readonly text: string }, named(context));
679
707
  }
680
708
  }
681
- const asks = first.confirm !== undefined || page.confirm !== undefined;
709
+ const asks = first.confirm !== undefined || pageConfirm !== undefined;
682
710
  let display: DisplayHandle;
683
711
  try {
684
712
  display = createHost(config, {
@@ -686,20 +714,20 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
686
714
  ...(asks
687
715
  ? {
688
716
  confirm: (request: ConfirmRequest, proceed: Proceed) =>
689
- (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))(
717
+ (latest().confirm ?? pageConfirm ?? (() => Promise.resolve(false)))(
690
718
  { ...request, display: { id: latest().displayId, title: latest().title } },
691
719
  proceed,
692
720
  ),
693
721
  }
694
722
  : {}),
695
- theme: (each) => (latest().theme ?? page.theme)?.(each) ?? {},
696
- ...(page.hostInfo === undefined ? {} : { hostInfo: page.hostInfo }),
697
- ...(page.locate === undefined ? {} : { locator: { locate: page.locate } }),
698
- ...(page.nonce === undefined ? {} : { nonce: page.nonce }),
723
+ theme: (each) => (latest().theme ?? latestPage().theme)?.(each) ?? {},
724
+ ...(hostInfo === undefined ? {} : { hostInfo }),
725
+ ...(locate === undefined ? {} : { locator: { locate } }),
726
+ ...(nonce === undefined ? {} : { nonce }),
699
727
  }).mount(container, {
700
728
  displayId: first.displayId,
701
729
  title: first.title,
702
- scheme: first.scheme ?? page.scheme ?? "light",
730
+ scheme: first.scheme ?? latestPage().scheme ?? "light",
703
731
  initialHeightPx: startHeight,
704
732
  ...(view === undefined ? {} : { document: view }),
705
733
  ...(instance === undefined ? {} : { instance }),
@@ -735,9 +763,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
735
763
  display.destroy();
736
764
  handle.current = null;
737
765
  };
738
- // A new display only for a new config, document, instance or page (or generation, by key);
739
- // content, theme, handlers, id and title are fed to the running one.
740
- }, [config, view, instance, page, startHeight, fills]);
766
+ // A new display only for a new config, document or instance, or what the provider makes
767
+ // displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
768
+ // key). Content, scheme, theme, handlers, id and title are fed to the running one.
769
+ }, [
770
+ config,
771
+ view,
772
+ instance,
773
+ startHeight,
774
+ fills,
775
+ pageHandlers,
776
+ pageCopyText,
777
+ pageConfirm,
778
+ hostInfo,
779
+ locate,
780
+ nonce,
781
+ ]);
741
782
 
742
783
  useEffect(() => {
743
784
  if (content !== undefined) {
@@ -803,6 +844,21 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
803
844
  handle.current?.refreshTheme();
804
845
  }
805
846
  }, [themeKey, mountThemeKey]);
847
+ // A new theme function (tokens a host passes inline): its values reach the running display
848
+ // where they changed for the scheme it shows (a flip re-reads them itself), P074.
849
+ const themeOf = frame.theme ?? page.theme;
850
+ const themed = useRef<string | null>(null);
851
+ useEffect(() => {
852
+ if (themeOf === undefined) {
853
+ return;
854
+ }
855
+ const now = `${scheme}\n${JSON.stringify(themeOf(scheme))}`;
856
+ const before = themed.current;
857
+ themed.current = now;
858
+ if (before !== null && before !== now && before.startsWith(`${scheme}\n`)) {
859
+ handle.current?.refreshTheme();
860
+ }
861
+ }, [themeOf, scheme]);
806
862
 
807
863
  return (
808
864
  <div
@@ -14,6 +14,7 @@ export {
14
14
  PortholeProvider,
15
15
  type PlaceholderProps,
16
16
  type PortholeFrameProps,
17
+ type ConfirmActions,
17
18
  type PortholeProviderProps,
18
19
  } from "./frame.tsx";
19
20
  export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
@@ -59,11 +59,16 @@ function useClient(): PortholeClient {
59
59
  }
60
60
 
61
61
  /** The client's meta, as a React value (re-renders when frames start or stop being served). */
62
+ /**
63
+ * The client's meta. On the server too (P074): a client made with the meta it will start with
64
+ * (`portholeClient({ meta })`) renders the frame's placeholder or the fallback there, and the
65
+ * page hydrates from the same.
66
+ */
62
67
  function useMeta(client: PortholeClient) {
63
68
  return useSyncExternalStore(
64
69
  (listener) => client.subscribe(listener),
65
70
  () => client.meta(),
66
- () => null,
71
+ () => client.meta(),
67
72
  );
68
73
  }
69
74
 
@@ -201,7 +201,8 @@ export interface EntryOptions<V> {
201
201
  request: Request,
202
202
  ) => Awaitable<InstanceRef | null | undefined>;
203
203
  /**
204
- * The app's own sign-in, which comes back to `returnTo` (the authorize URL) once signed in.
204
+ * The app's own sign-in, which comes back to `returnTo` (the authorize URL, as `authorizeUrl`
205
+ * names the app, with the entry's state) once signed in.
205
206
  * Only ever on a tab: in a frame, the person is asked to open a new tab instead. `entry` is the
206
207
  * address being opened, decoded (P070).
207
208
  */
@@ -218,9 +219,10 @@ export interface EntryOptions<V> {
218
219
  readonly spa?: { readonly route: string };
219
220
  /**
220
221
  * The clean path of an instance (the reverse of `at`), or null: `issue` then answers its clean
221
- * address as `link` (P072), for "open in a new tab" and "copy link".
222
+ * address as `link` (P072), for "open in a new tab" and "copy link". It may look it up (a
223
+ * promise, P074); where it fails, the frame comes without a link.
222
224
  */
223
- readonly pathOf?: (instance: InstanceRef) => string | null;
225
+ readonly pathOf?: (instance: InstanceRef, request: Request) => Awaitable<string | null>;
224
226
  /**
225
227
  * A viewer handoff, for an app whose page authenticates with a token rather than a cookie
226
228
  * (P072): `POST <prefix>/handoff`, made with the app's own credential, leaves a short-lived key
@@ -406,10 +408,19 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
406
408
  if (options.configs === undefined && options.displays === undefined) {
407
409
  throw new TypeError("createContentHost needs configs or displays");
408
410
  }
409
- const secret = typeof options.secret === "string" ? utf8(options.secret.trim()) : options.secret;
411
+ // The secret as given (an unset environment variable: none), checked with the domain below.
412
+ const secret: Uint8Array | null =
413
+ typeof options.secret === "string"
414
+ ? utf8(options.secret.trim())
415
+ : options.secret instanceof Uint8Array
416
+ ? options.secret
417
+ : null;
410
418
  const healthLabel = gate?.label ?? DEFAULT_HEALTH_LABEL;
411
419
  // The id Porthole's health check answers with: keyed, so another deployment's answer fails.
412
- const healthId = base64url(hmacSha256(secret, utf8("porthole/health"))).slice(0, 22);
420
+ const healthId =
421
+ secret === null || secret.byteLength < 32
422
+ ? ""
423
+ : base64url(hmacSha256(secret, utf8("porthole/health"))).slice(0, 22);
413
424
  const appReserved = reservedLabels(options.reserved);
414
425
 
415
426
  let domain: ContentDomainInfo | null = null;
@@ -423,6 +434,17 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
423
434
  ? options.domain
424
435
  : contentDomain(options.domain, { appOrigins: options.appOrigins });
425
436
  if (domain !== null) {
437
+ // Said plainly where it's missing, as where it's short (P074).
438
+ if (secret === null) {
439
+ throw new TypeError(
440
+ "createContentHost needs a secret: at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)",
441
+ );
442
+ }
443
+ if (secret.byteLength < 32) {
444
+ throw new TypeError(
445
+ "The secret must be at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)",
446
+ );
447
+ }
426
448
  if (options.entry !== undefined && options.name?.scopeOf === undefined) {
427
449
  throw new TypeError(
428
450
  "Redirect entry needs a naming that says which scope a label names (prefixedName)",
@@ -632,7 +654,9 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
632
654
 
633
655
  // The viewer handoff (P072): a key Porthole signs, naming the app's viewer until a time, in a
634
656
  // cookie only the prefix's routes get. Never the app's own credential.
635
- const handoffKey = hmacSha256(secret, utf8("porthole/handoff"));
657
+ // None where the secret can't sign (then nothing is served, and no handoff made or taken).
658
+ const handoffKey =
659
+ secret === null || secret.byteLength < 32 ? null : hmacSha256(secret, utf8("porthole/handoff"));
636
660
  const secureApp = (options.appOrigins[0] ?? "").startsWith("https:");
637
661
  const handoffName = secureApp ? "__Secure-porthole-handoff" : "porthole-handoff";
638
662
  const handoffCookie = (value: string, maxAge: number): string =>
@@ -644,14 +668,14 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
644
668
  `Max-Age=${maxAge}`,
645
669
  ...(secureApp ? ["Secure"] : []),
646
670
  ].join("; ");
647
- const signHandoff = (id: string, until: number): string => {
671
+ const signHandoff = (key: Uint8Array, id: string, until: number): string => {
648
672
  const payload = base64url(utf8(JSON.stringify({ h: 1, v: id, x: until })));
649
- return `${payload}.${base64url(hmacSha256(handoffKey, utf8(payload)))}`;
673
+ return `${payload}.${base64url(hmacSha256(key, utf8(payload)))}`;
650
674
  };
651
675
  /** The viewer a request's handoff cookie names, if it is good. */
652
676
  const handedOver = async (request: Request): Promise<V | null> => {
653
677
  const handoff = options.entry?.handoff;
654
- if (handoff === undefined) {
678
+ if (handoff === undefined || handoffKey === null) {
655
679
  return null;
656
680
  }
657
681
  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
@@ -690,18 +714,29 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
690
714
  }
691
715
  return null;
692
716
  };
717
+ /**
718
+ * Where the person comes back after signing in: the authorize route as the app is reached
719
+ * (`authorizeUrl`'s origin and path), with this request's query (its state). Never the request's
720
+ * own URL, whose origin behind a TLS edge or a dev proxy isn't the app's (P074).
721
+ */
722
+ const returnOf = (request: Request): string => {
723
+ const back = new URL(authorizeUrl);
724
+ back.search = new URL(request.url).search;
725
+ return back.href;
726
+ };
693
727
  /** The app's sign-in: its own `signIn`, or its single-page route with `next`. */
694
728
  const signInWith = async (
695
729
  entry: EntryOptions<V>,
696
730
  request: Request,
697
731
  context: EntryContext,
698
732
  ): Promise<Response> => {
733
+ const returnTo = returnOf(request);
699
734
  if (entry.signIn !== undefined) {
700
- return entry.signIn(request.url, request, context);
735
+ return entry.signIn(returnTo, request, context);
701
736
  }
702
737
  const route = entry.spa?.route ?? "/";
703
- const to = new URL(route, options.appOrigins[0]);
704
- to.searchParams.set("next", request.url);
738
+ const to = new URL(route, new URL(authorizeUrl).origin);
739
+ to.searchParams.set("next", returnTo);
705
740
  return new Response(null, {
706
741
  status: 303,
707
742
  headers: { location: to.href, "cache-control": "no-store", "referrer-policy": "no-referrer" },
@@ -807,10 +842,10 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
807
842
  } catch (error) {
808
843
  return refusal(409, "refused", error instanceof Error ? error.message : String(error));
809
844
  }
810
- // The clean address, where the app says the instance's path (P072).
811
- const path = options.entry?.pathOf?.(instance) ?? null;
845
+ // The clean address, where the app says the instance's path (P072, P074).
812
846
  let link: string | null = null;
813
847
  try {
848
+ const path = (await options.entry?.pathOf?.(instance, request)) ?? null;
814
849
  link = path === null ? null : server.urlOf(instance.scope, path);
815
850
  } catch {
816
851
  link = null;
@@ -910,7 +945,10 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
910
945
  if (typeof id !== "string" || id.length === 0 || id.length > 512) {
911
946
  return refusal(500, "failed", "entry.handoff.id gave no id (1 to 512 characters)");
912
947
  }
913
- const key = signHandoff(id, Date.now() + HANDOFF_SECONDS * 1_000);
948
+ if (handoffKey === null) {
949
+ return refusal(503, "unavailable", "The content domain isn't served");
950
+ }
951
+ const key = signHandoff(handoffKey, id, Date.now() + HANDOFF_SECONDS * 1_000);
914
952
  return new Response(null, {
915
953
  status: 204,
916
954
  headers: {