@crossworks/share-ui 0.232.245 → 0.232.252

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/share-ui",
3
- "version": "0.232.245",
3
+ "version": "0.232.252",
4
4
  "description": "The server-rendered share surface — the /s/<token> presenters, view-payload contract, mini-app sandbox, and the few primitives they need. Lives in MANTLE (the server renders these), published for jackdaw to consume; may depend only on @mantle/{client-types,content-core} (the jackdaw-repo-split boundary).",
5
5
  "exports": {
6
6
  "./app-presenter": "./src/app-presenter.tsx",
@@ -38,8 +38,8 @@
38
38
  "@dicebear/core": "^10.7.0",
39
39
  "@dicebear/styles": "^10.6.0",
40
40
  "@firecms/neat": "1.0.2",
41
- "@mantle/client-types": "npm:@crossworks/client-types@0.232.245",
42
- "@mantle/content-core": "npm:@crossworks/content-core@0.232.245",
41
+ "@mantle/client-types": "npm:@crossworks/client-types@0.232.252",
42
+ "@mantle/content-core": "npm:@crossworks/content-core@0.232.252",
43
43
  "@radix-ui/react-label": "^2.1.15",
44
44
  "@radix-ui/react-slot": "^1.3.3",
45
45
  "class-variance-authority": "^0.7.1",
@@ -31,7 +31,12 @@ export type HubNavTarget = 'chat' | { briefing: string } | { app: string };
31
31
 
32
32
  /** Fire-and-forget lifecycle events the app emits (no response expected). */
33
33
  export type BridgeEvt =
34
+ // Mounted AND painted once (the kit posts it after the first commit's frame).
34
35
  | { v: 1; kind: 'ready' }
36
+ // host.ui.holdReady() / host.ui.ready(): an app that loads what the host
37
+ // can't see keeps the host's loader up until it says so (see app-reveal.ts).
38
+ | { v: 1; kind: 'ready.hold' }
39
+ | { v: 1; kind: 'ready.release' }
35
40
  | { v: 1; kind: 'resize'; height: number }
36
41
  | { v: 1; kind: 'error'; message: string; stack?: string }
37
42
  // Inspect mode (host-injected overlay → host): the user locked/cleared a
@@ -0,0 +1,84 @@
1
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
2
+ import { RevealGate } from './app-reveal';
3
+
4
+ const opts = { quietMs: 150, maxMs: 8_000 };
5
+
6
+ describe('RevealGate', () => {
7
+ beforeEach(() => vi.useFakeTimers());
8
+ afterEach(() => vi.useRealTimers());
9
+
10
+ it('reveals a quiet app one quiet window after mount', () => {
11
+ const onReveal = vi.fn();
12
+ const g = new RevealGate(onReveal, opts);
13
+ g.mount();
14
+ vi.advanceTimersByTime(149);
15
+ expect(onReveal).not.toHaveBeenCalled();
16
+ vi.advanceTimersByTime(1);
17
+ expect(onReveal).toHaveBeenCalledTimes(1);
18
+ });
19
+
20
+ it('waits for in-flight bridge requests, including a chained one', () => {
21
+ const onReveal = vi.fn();
22
+ const g = new RevealGate(onReveal, opts);
23
+ g.requestStart(); // the app's mount effect fired before ready arrived
24
+ g.mount();
25
+ vi.advanceTimersByTime(1_000);
26
+ expect(onReveal).not.toHaveBeenCalled();
27
+ g.requestEnd();
28
+ vi.advanceTimersByTime(50);
29
+ g.requestStart(); // the next await in the chain
30
+ vi.advanceTimersByTime(500);
31
+ expect(onReveal).not.toHaveBeenCalled();
32
+ g.requestEnd();
33
+ vi.advanceTimersByTime(150);
34
+ expect(onReveal).toHaveBeenCalledTimes(1);
35
+ });
36
+
37
+ it('holds until the app releases, then reveals at once', () => {
38
+ const onReveal = vi.fn();
39
+ const g = new RevealGate(onReveal, opts);
40
+ g.hold();
41
+ g.mount();
42
+ vi.advanceTimersByTime(3_000);
43
+ expect(onReveal).not.toHaveBeenCalled();
44
+ g.release();
45
+ expect(onReveal).toHaveBeenCalledTimes(1);
46
+ });
47
+
48
+ it('a release that beats the ready signal reveals on mount', () => {
49
+ const onReveal = vi.fn();
50
+ const g = new RevealGate(onReveal, opts);
51
+ g.hold();
52
+ g.release();
53
+ expect(onReveal).not.toHaveBeenCalled();
54
+ g.mount();
55
+ expect(onReveal).toHaveBeenCalledTimes(1);
56
+ });
57
+
58
+ it('never keeps the loader up past the cap', () => {
59
+ const onReveal = vi.fn();
60
+ const g = new RevealGate(onReveal, opts);
61
+ g.hold();
62
+ g.requestStart();
63
+ g.mount();
64
+ vi.advanceTimersByTime(8_000);
65
+ expect(onReveal).toHaveBeenCalledTimes(1);
66
+ });
67
+
68
+ it('reveals once, and not at all after dispose', () => {
69
+ const onReveal = vi.fn();
70
+ const g = new RevealGate(onReveal, opts);
71
+ g.mount();
72
+ vi.advanceTimersByTime(150);
73
+ g.release();
74
+ vi.advanceTimersByTime(10_000);
75
+ expect(onReveal).toHaveBeenCalledTimes(1);
76
+
77
+ const late = vi.fn();
78
+ const g2 = new RevealGate(late, opts);
79
+ g2.mount();
80
+ g2.dispose();
81
+ vi.advanceTimersByTime(10_000);
82
+ expect(late).not.toHaveBeenCalled();
83
+ });
84
+ });
@@ -0,0 +1,102 @@
1
+ /**
2
+ * When a running mini app is ready to be SEEN, as opposed to merely mounted.
3
+ *
4
+ * `ready` from the frame means React committed and painted once. Most apps
5
+ * then load their data through the bridge (db.query / tool.call), which the
6
+ * host page brokers, so the host can see those requests in flight. The gate
7
+ * reveals the app once it has mounted AND:
8
+ *
9
+ * - the app is not holding (`host.ui.holdReady()`), and
10
+ * - no bridge request has been in flight for `quietMs` (chained awaits hand
11
+ * over within a microtask, so a short window covers them),
12
+ *
13
+ * or at once when a holding app calls `host.ui.ready()`, and in any case
14
+ * `maxMs` after mount, so a request that never settles can't pin the loader.
15
+ *
16
+ * Pure (timers injected via the global setTimeout, testable with fake timers);
17
+ * one gate per frame load. Calls `onReveal` at most once.
18
+ */
19
+
20
+ export const REVEAL_QUIET_MS = 150;
21
+ export const REVEAL_MAX_MS = 8_000;
22
+
23
+ export class RevealGate {
24
+ private inflight = 0;
25
+ private held = false;
26
+ private released = false;
27
+ private mounted = false;
28
+ private done = false;
29
+ private quiet: ReturnType<typeof setTimeout> | null = null;
30
+ private cap: ReturnType<typeof setTimeout> | null = null;
31
+
32
+ constructor(
33
+ private readonly onReveal: () => void,
34
+ private readonly opts: { quietMs: number; maxMs: number } = {
35
+ quietMs: REVEAL_QUIET_MS,
36
+ maxMs: REVEAL_MAX_MS,
37
+ },
38
+ ) {}
39
+
40
+ /** The frame posted `ready` (mounted and painted). */
41
+ mount(): void {
42
+ if (this.done || this.mounted) return;
43
+ this.mounted = true;
44
+ this.cap = setTimeout(() => this.reveal(), this.opts.maxMs);
45
+ if (this.released) this.reveal();
46
+ else this.check();
47
+ }
48
+
49
+ /** A bridge request left for the host. */
50
+ requestStart(): void {
51
+ this.inflight++;
52
+ this.clearQuiet();
53
+ }
54
+
55
+ /** A bridge request was answered (either way). */
56
+ requestEnd(): void {
57
+ this.inflight = Math.max(0, this.inflight - 1);
58
+ this.check();
59
+ }
60
+
61
+ /** The app asked the host to keep the loader up. */
62
+ hold(): void {
63
+ if (this.released) return;
64
+ this.held = true;
65
+ this.clearQuiet();
66
+ }
67
+
68
+ /** The app declared itself ready: reveal now (or at mount, if earlier). */
69
+ release(): void {
70
+ this.held = false;
71
+ this.released = true;
72
+ if (this.mounted) this.reveal();
73
+ }
74
+
75
+ get revealed(): boolean {
76
+ return this.done;
77
+ }
78
+
79
+ dispose(): void {
80
+ this.done = true;
81
+ this.clearQuiet();
82
+ if (this.cap) clearTimeout(this.cap);
83
+ this.cap = null;
84
+ }
85
+
86
+ private check(): void {
87
+ if (this.done || !this.mounted || this.held || this.inflight > 0) return;
88
+ this.clearQuiet();
89
+ this.quiet = setTimeout(() => this.reveal(), this.opts.quietMs);
90
+ }
91
+
92
+ private clearQuiet(): void {
93
+ if (this.quiet) clearTimeout(this.quiet);
94
+ this.quiet = null;
95
+ }
96
+
97
+ private reveal(): void {
98
+ if (this.done) return;
99
+ this.dispose();
100
+ this.onReveal();
101
+ }
102
+ }
@@ -20,7 +20,8 @@
20
20
  * frame URL and are baked into the document's <html>; later host theme
21
21
  * changes are pushed into the running app via the postMessage theme sync.
22
22
  */
23
- import { useCallback, useEffect, useRef, useState } from 'react';
23
+ import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
24
+ import { RevealGate } from './app-reveal';
24
25
  import {
25
26
  isFromApp,
26
27
  isHubNavTarget,
@@ -45,6 +46,7 @@ export function AppSandbox({
45
46
  apiBase: apiBaseOverride,
46
47
  fetcher,
47
48
  onLoadFailure,
49
+ loader,
48
50
  }: {
49
51
  appId: string;
50
52
  /** When set, render in share mode: the bundle + tool/db brokers are
@@ -93,6 +95,12 @@ export function AppSandbox({
93
95
  * The /team shell uses this to fall back to the built-in hub instead of
94
96
  * showing members a broken slot. */
95
97
  onLoadFailure?: () => void;
98
+ /** What covers the app until it is ready to be SEEN (mounted, painted, its
99
+ * first bridge requests answered; see app-reveal.ts), then cross-fades
100
+ * away. The host passes its own (the owner UI's thinking orb); absent ⇒ a
101
+ * plain "Loading…" line. Kept a slot so this package needs no animation
102
+ * dependency. */
103
+ loader?: ReactNode;
96
104
  }) {
97
105
  // Public share mode swaps the session-authed API base for the token-authed
98
106
  // public one; the route suffixes (bundle / tool-broker / db-broker) match.
@@ -112,6 +120,13 @@ export function AppSandbox({
112
120
  // Watchdog retry counter: bumping it re-runs the ticket effect (a fresh
113
121
  // ticket AND a fresh iframe — the old ticket may have expired by then).
114
122
  const [attempt, setAttempt] = useState(0);
123
+ // Mounted is not the same as ready to be seen: the gate keeps the loader up
124
+ // until the app's first bridge requests settle (or it says so, or a cap).
125
+ // One gate per frame load; `revealed` flips once per load.
126
+ const gateRef = useRef<RevealGate | null>(null);
127
+ const [revealed, setRevealed] = useState(false);
128
+ // The loader stays mounted through its fade-out, then leaves the DOM.
129
+ const [loaderGone, setLoaderGone] = useState(false);
115
130
  // One automatic retry before giving up (see the ready watchdog below).
116
131
  const retriedRef = useRef(false);
117
132
  // Whether THIS bundle load ever reached ready — distinguishes a boot crash
@@ -190,6 +205,7 @@ export function AppSandbox({
190
205
  return;
191
206
  }
192
207
  if (req.kind === 'tool.call') {
208
+ gateRef.current?.requestStart();
193
209
  const r = await doFetch(`${apiBase}/tool-broker`, {
194
210
  method: 'POST',
195
211
  headers: { 'content-type': 'application/json' },
@@ -210,6 +226,7 @@ export function AppSandbox({
210
226
  }
211
227
  // db.query | db.exec
212
228
  const op = req.kind === 'db.query' ? 'query' : 'exec';
229
+ gateRef.current?.requestStart();
213
230
  const r = await doFetch(`${apiBase}/db-broker`, {
214
231
  method: 'POST',
215
232
  headers: { 'content-type': 'application/json' },
@@ -218,6 +235,9 @@ export function AppSandbox({
218
235
  reply(await r.json());
219
236
  } catch (err) {
220
237
  reply({ ok: false, error: err instanceof Error ? err.message : String(err) });
238
+ } finally {
239
+ // Balanced with the requestStart above; hub.get never started one.
240
+ if (req.kind !== 'hub.get') gateRef.current?.requestEnd();
221
241
  }
222
242
  },
223
243
  [apiBase, doFetch],
@@ -230,8 +250,19 @@ export function AppSandbox({
230
250
  const m = e.data;
231
251
  if (!isFromApp(m)) return;
232
252
  if (m.kind === 'ready') {
233
- setStatus('ready');
253
+ // A render crash posts its error before this (the kit signals ready
254
+ // after the first commit's frame): keep showing the failure.
255
+ setStatus((s) => (s === 'error' ? s : 'ready'));
234
256
  everReadyRef.current = true;
257
+ gateRef.current?.mount();
258
+ return;
259
+ }
260
+ if (m.kind === 'ready.hold') {
261
+ gateRef.current?.hold();
262
+ return;
263
+ }
264
+ if (m.kind === 'ready.release') {
265
+ gateRef.current?.release();
235
266
  return;
236
267
  }
237
268
  if (m.kind === 'resize') {
@@ -298,6 +329,19 @@ export function AppSandbox({
298
329
  return () => clearTimeout(t);
299
330
  }, [status, frameSrc]);
300
331
 
332
+ // A fresh gate for every frame load (new app, reload, watchdog retry).
333
+ useEffect(() => {
334
+ setRevealed(false);
335
+ setLoaderGone(false);
336
+ if (frameSrc === null) return;
337
+ const gate = new RevealGate(() => setRevealed(true));
338
+ gateRef.current = gate;
339
+ return () => {
340
+ gate.dispose();
341
+ if (gateRef.current === gate) gateRef.current = null;
342
+ };
343
+ }, [frameSrc]);
344
+
301
345
  // A NEW load target (not a watchdog retry) gets its retry budget back.
302
346
  useEffect(() => {
303
347
  retriedRef.current = false;
@@ -348,6 +392,8 @@ export function AppSandbox({
348
392
  }, [apiBase, reloadKey, frame, doFetch, attempt]);
349
393
 
350
394
  const isViewport = frame === 'viewport';
395
+ const showApp = status === 'ready' && revealed;
396
+ const showLoader = (status === 'loading' || status === 'ready') && !loaderGone;
351
397
  return (
352
398
  <div
353
399
  className={
@@ -384,17 +430,33 @@ export function AppSandbox({
384
430
  title={isViewport ? 'App' : 'App preview'}
385
431
  sandbox="allow-scripts"
386
432
  src={frameSrc.url}
433
+ // Laid out (not display:none) while the loader covers it, so an app
434
+ // measuring itself on mount (charts, grids) gets real sizes.
387
435
  className={
388
- status === 'ready' ? (isViewport ? 'block h-full w-full' : 'block w-full') : 'hidden'
436
+ status === 'ready' || status === 'loading'
437
+ ? `${isViewport ? 'block h-full w-full' : 'block w-full'} transition-opacity duration-300 ${
438
+ showApp ? 'opacity-100' : 'pointer-events-none opacity-0'
439
+ }`
440
+ : 'hidden'
389
441
  }
390
442
  style={isViewport ? { border: '0' } : { height, border: '0', width: '100%' }}
391
443
  />
392
444
  )}
393
- {status === 'loading' && (
445
+ {showLoader && (
394
446
  <div
395
- className={`flex items-center justify-center p-6 text-sm text-muted-foreground ${isViewport ? 'h-full' : 'h-40'}`}
447
+ aria-busy={!showApp}
448
+ onTransitionEnd={() => showApp && setLoaderGone(true)}
449
+ className={`flex items-center justify-center bg-background transition-opacity duration-300 ${
450
+ // Over the (laid out, transparent) iframe once there is one; in
451
+ // flow before that, so a card has height while the ticket loads.
452
+ isViewport || frameSrc !== null ? 'absolute inset-0' : 'h-40'
453
+ } ${showApp ? 'pointer-events-none opacity-0' : 'opacity-100'}`}
396
454
  >
397
- {isViewport ? 'Loading…' : 'Loading preview…'}
455
+ {loader ?? (
456
+ <span className="p-6 text-sm text-muted-foreground">
457
+ {isViewport ? 'Loading…' : 'Loading preview…'}
458
+ </span>
459
+ )}
398
460
  </div>
399
461
  )}
400
462
  </div>