@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 +3 -3
- package/src/app-bridge-protocol.ts +5 -0
- package/src/app-reveal.test.ts +84 -0
- package/src/app-reveal.ts +102 -0
- package/src/app-sandbox.tsx +68 -6
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crossworks/share-ui",
|
|
3
|
-
"version": "0.232.
|
|
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.
|
|
42
|
-
"@mantle/content-core": "npm:@crossworks/content-core@0.232.
|
|
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
|
+
}
|
package/src/app-sandbox.tsx
CHANGED
|
@@ -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
|
-
|
|
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'
|
|
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
|
-
{
|
|
445
|
+
{showLoader && (
|
|
394
446
|
<div
|
|
395
|
-
|
|
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
|
-
{
|
|
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>
|