Skip to content

Commit 9777275

Browse files
refactor(mobile): showcase capture readiness is a tested pure model
The showcase capture coordinator decided scene, theme, and readiness inline, with no tests, and kept its ready marker in sync through effects: an effect copied threads and projects into a ref every render, and the readiness effect cleared the marker with setState after commit, so a stale marker survived one commit after readiness was lost. Move route-to-scene, theme-applied, and readiness rules into showcaseCaptureModel.ts with tests. The coordinator derives a readiness key from it; the marker remembers the key it settled for and is hidden in the same render once the key changes. Agent activity staging reads the latest entities through useEffectEvent instead of a ref mirrored by an effect. The render signal store counts reports so a redraw in the same scene and theme still restarts the settle delay. Effects in ShowcaseCaptureCoordinator.tsx: 11 -> 10 (entities ref mirror removed; the readiness effect stays because it owns the settle timer and animation frames, but no longer sets state to clear the marker). Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 96fc7b9 commit 9777275

4 files changed

Lines changed: 213 additions & 54 deletions

File tree

‎apps/mobile/src/features/showcase/ShowcaseCaptureCoordinator.tsx‎

Lines changed: 43 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { useEffect, useRef, useState, useSyncExternalStore } from "react";
1+
import { useEffect, useEffectEvent, useRef, useState, useSyncExternalStore } from "react";
22
import { Keyboard, View } from "react-native";
33
import { CommonActions, StackActions, useNavigation } from "@react-navigation/native";
44
import { AsyncResult } from "effect/reactivity";
@@ -25,31 +25,24 @@ import {
2525
SHOWCASE_PENDING_TASK_DEFINITIONS,
2626
} from "./showcasePendingTasks";
2727
import { buildShowcaseAgentActivity } from "./showcaseAgentActivity";
28+
import {
29+
isShowcaseThemeApplied,
30+
SHOWCASE_THREAD_ID,
31+
showcaseReadinessKey,
32+
showcaseSceneOnScreen,
33+
} from "./showcaseCaptureModel";
2834
import { retryShowcaseOperation } from "./showcaseRetry";
2935
import {
3036
clearShowcaseRenderSignal,
37+
getShowcaseRenderReports,
3138
getShowcaseRenderSignal,
32-
isShowcaseNativeContentReady,
3339
subscribeToShowcaseRenderSignal,
3440
} from "./showcaseRenderSignal";
3541
import { stageShowcaseAgentActivity } from "./stageShowcaseAgentActivity";
3642
import { openSettings } from "../settings/settings-navigation";
3743
import { selectWorkspaceDetail } from "../workspace/workspace-detail-selection";
3844

3945
const SHOWCASE_ENABLED = process.env.EXPO_PUBLIC_SHOWCASE === "1";
40-
const SHOWCASE_THREAD_ID = "remote-command-center";
41-
42-
function sceneFromPathname(pathname: string): ShowcaseScene | null {
43-
const routePath = pathname.split(/[?#]/u, 1)[0] ?? pathname;
44-
if (routePath === "/settings" || routePath.endsWith("/settings/environments")) {
45-
return "environments";
46-
}
47-
if (routePath.endsWith("/terminal")) return "terminal";
48-
if (routePath.endsWith("/review")) return "review";
49-
if (routePath.startsWith("/threads/")) return "thread";
50-
if (routePath === "/") return "threads";
51-
return null;
52-
}
5346

5447
export function ShowcaseCaptureCoordinator(props: { readonly pathname: string }) {
5548
if (!SHOWCASE_ENABLED) return null;
@@ -87,20 +80,25 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
8780
const [requestedScene, setRequestedScene] = useState<ShowcaseScene | null>(null);
8881
const [requestedTheme, setRequestedTheme] = useState<MobileThemeId | null>(null);
8982
const [themeRequestSettled, setThemeRequestSettled] = useState(false);
90-
const [readyScene, setReadyScene] = useState<ShowcaseScene | null>(null);
83+
const [marked, setMarked] = useState<{
84+
readonly key: string;
85+
readonly scene: ShowcaseScene;
86+
} | null>(null);
9187
const [orientationSettled, setOrientationSettled] = useState(false);
9288
const [agentActivityStaged, setAgentActivityStaged] = useState(false);
9389
const requestedSceneRef = useRef<ShowcaseScene | null>(null);
9490
// Read current entities without restarting on shell updates and re-entering open permission prompts.
95-
const entitiesRef = useRef({ threads, projects });
96-
useEffect(() => {
97-
entitiesRef.current = { threads, projects };
98-
}, [projects, threads]);
91+
const readFixtureEntities = useEffectEvent(() => ({ threads, projects }));
9992
const renderSignal = useSyncExternalStore(
10093
subscribeToShowcaseRenderSignal,
10194
getShowcaseRenderSignal,
10295
getShowcaseRenderSignal,
10396
);
97+
const renderReports = useSyncExternalStore(
98+
subscribeToShowcaseRenderSignal,
99+
getShowcaseRenderReports,
100+
getShowcaseRenderReports,
101+
);
104102

105103
useEffect(() => {
106104
if (pairingUrls.length > 0) return;
@@ -152,10 +150,11 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
152150
return () => clearInterval(interval);
153151
}, []);
154152

155-
const themeApplied =
156-
requestedTheme === null
157-
? themeRequestSettled
158-
: themeIds.light === requestedTheme && themeIds.dark === requestedTheme;
153+
const themeApplied = isShowcaseThemeApplied({
154+
launchRequestRead: themeRequestSettled,
155+
requestedTheme,
156+
themeIds,
157+
});
159158

160159
useEffect(() => {
161160
if (requestedTheme === null || themeApplied || !appearancePreferencesReady) {
@@ -184,9 +183,7 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
184183
};
185184
}, [connectPairingUrl, pairingUrls]);
186185

187-
const routeScene = sceneFromPathname(props.pathname);
188-
const scene =
189-
requestedScene === "agent-activity" && routeScene === "threads" ? "agent-activity" : routeScene;
186+
const scene = showcaseSceneOnScreen(requestedScene, props.pathname);
190187
const hasServerFixture =
191188
workspace.state.hasReadyEnvironment &&
192189
workspace.environments.length >= 3 &&
@@ -264,7 +261,7 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
264261
void retryShowcaseOperation(
265262
async () => {
266263
const now = Date.now();
267-
const { threads: latestThreads, projects: latestProjects } = entitiesRef.current;
264+
const { threads: latestThreads, projects: latestProjects } = readFixtureEntities();
268265
const activity = buildShowcaseAgentActivity(latestThreads, latestProjects, now);
269266
const outcome =
270267
activity === null
@@ -285,21 +282,23 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
285282
};
286283
}, [agentActivityStaged, hasFixture, scene]);
287284

285+
const readinessKey = showcaseReadinessKey({
286+
scene,
287+
requestedScene,
288+
hasFixture,
289+
orientationSettled,
290+
themeApplied,
291+
agentActivityStaged,
292+
themeId,
293+
renderSignal,
294+
renderReports,
295+
});
296+
// A marker belongs to the readiness it was settled for; any change hides it until it settles again.
297+
if (marked !== null && marked.key !== readinessKey) setMarked(null);
298+
const readyScene = marked?.scene ?? null;
299+
288300
useEffect(() => {
289-
if (
290-
scene === null ||
291-
requestedScene === null ||
292-
scene !== requestedScene ||
293-
!hasFixture ||
294-
!orientationSettled ||
295-
!themeApplied ||
296-
(scene === "agent-activity" && !agentActivityStaged) ||
297-
!isShowcaseNativeContentReady({ scene, themeId, renderSignal })
298-
) {
299-
// oxlint-disable-next-line react/set-state-in-effect -- Capture readiness clears while the scene, fixture, or native content is not ready.
300-
setReadyScene(null);
301-
return;
302-
}
301+
if (readinessKey === null || scene === null) return;
303302
if (scene === "terminal") Keyboard.dismiss();
304303

305304
let renderFrame: number | null = null;
@@ -308,7 +307,7 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
308307
renderFrame = requestAnimationFrame(() => {
309308
readyFrame = requestAnimationFrame(() => {
310309
markNativeShowcaseReady(scene);
311-
setReadyScene(scene);
310+
setMarked({ key: readinessKey, scene });
312311
});
313312
});
314313
}, 500);
@@ -317,19 +316,9 @@ function EnabledShowcaseCaptureCoordinator(props: { readonly pathname: string })
317316
if (renderFrame !== null) cancelAnimationFrame(renderFrame);
318317
if (readyFrame !== null) cancelAnimationFrame(readyFrame);
319318
};
320-
}, [
321-
agentActivityStaged,
322-
hasFixture,
323-
orientationSettled,
324-
renderSignal,
325-
requestedScene,
326-
scene,
327-
themeApplied,
328-
themeId,
329-
]);
319+
}, [readinessKey, scene]);
330320

331321
if (readyScene === null) return null;
332-
333322
return (
334323
<View
335324
pointerEvents="none"
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
import { describe, expect, it } from "vite-plus/test";
2+
3+
import {
4+
isShowcaseThemeApplied,
5+
showcaseReadinessKey,
6+
showcaseSceneOnScreen,
7+
type ShowcaseReadinessInput,
8+
} from "./showcaseCaptureModel";
9+
10+
const ready: ShowcaseReadinessInput = {
11+
scene: "thread",
12+
requestedScene: "thread",
13+
hasFixture: true,
14+
orientationSettled: true,
15+
themeApplied: true,
16+
agentActivityStaged: false,
17+
themeId: "t3-code",
18+
renderSignal: null,
19+
renderReports: 0,
20+
};
21+
22+
describe("showcaseSceneOnScreen", () => {
23+
it("treats the threads list as the agent activity scene only when that scene is requested", () => {
24+
expect(showcaseSceneOnScreen("agent-activity", "/")).toBe("agent-activity");
25+
expect(showcaseSceneOnScreen("threads", "/")).toBe("threads");
26+
expect(showcaseSceneOnScreen("agent-activity", "/threads/env/thread")).toBe("thread");
27+
expect(showcaseSceneOnScreen(null, "/threads/env/thread/review?x=1")).toBe("review");
28+
});
29+
});
30+
31+
describe("isShowcaseThemeApplied", () => {
32+
it("waits for the launch request when no theme is requested", () => {
33+
const themeIds = { light: "t3-code", dark: "t3-code" } as const;
34+
expect(
35+
isShowcaseThemeApplied({ launchRequestRead: false, requestedTheme: null, themeIds }),
36+
).toBe(false);
37+
expect(
38+
isShowcaseThemeApplied({ launchRequestRead: true, requestedTheme: null, themeIds }),
39+
).toBe(true);
40+
});
41+
42+
it("requires both appearances to use the requested theme", () => {
43+
expect(
44+
isShowcaseThemeApplied({
45+
launchRequestRead: true,
46+
requestedTheme: "t3-code",
47+
themeIds: { light: "t3-code", dark: "material-you" },
48+
}),
49+
).toBe(false);
50+
});
51+
});
52+
53+
describe("showcaseReadinessKey", () => {
54+
it("is null until every precondition holds", () => {
55+
expect(showcaseReadinessKey(ready)).not.toBeNull();
56+
expect(showcaseReadinessKey({ ...ready, requestedScene: "terminal" })).toBeNull();
57+
expect(showcaseReadinessKey({ ...ready, hasFixture: false })).toBeNull();
58+
expect(showcaseReadinessKey({ ...ready, orientationSettled: false })).toBeNull();
59+
expect(showcaseReadinessKey({ ...ready, themeApplied: false })).toBeNull();
60+
});
61+
62+
it("waits for agent activity to be staged", () => {
63+
const agentActivity = {
64+
...ready,
65+
scene: "agent-activity",
66+
requestedScene: "agent-activity",
67+
} as const;
68+
expect(showcaseReadinessKey(agentActivity)).toBeNull();
69+
expect(showcaseReadinessKey({ ...agentActivity, agentActivityStaged: true })).not.toBeNull();
70+
});
71+
72+
it("waits for review to report a draw in the current theme, and changes key when it redraws", () => {
73+
const review = { ...ready, scene: "review", requestedScene: "review" } as const;
74+
expect(showcaseReadinessKey(review)).toBeNull();
75+
expect(
76+
showcaseReadinessKey({
77+
...review,
78+
renderSignal: { scene: "review", themeId: "material-you" },
79+
}),
80+
).toBeNull();
81+
const drawn = { ...review, renderSignal: { scene: "review", themeId: "t3-code" } } as const;
82+
const firstDraw = showcaseReadinessKey({ ...drawn, renderReports: 1 });
83+
expect(firstDraw).not.toBeNull();
84+
expect(showcaseReadinessKey({ ...drawn, renderReports: 2 })).not.toBe(firstDraw);
85+
});
86+
});
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import type { MobileThemeId, MobileThemeIds } from "../../lib/mobileTheme";
2+
import type { ShowcaseScene } from "./nativeShowcaseScene";
3+
import { isShowcaseNativeContentReady, type ShowcaseRenderSignal } from "./showcaseRenderSignal";
4+
5+
export const SHOWCASE_THREAD_ID = "remote-command-center";
6+
7+
export function sceneFromPathname(pathname: string): ShowcaseScene | null {
8+
const routePath = pathname.split(/[?#]/u, 1)[0] ?? pathname;
9+
if (routePath === "/settings" || routePath.endsWith("/settings/environments")) {
10+
return "environments";
11+
}
12+
if (routePath.endsWith("/terminal")) return "terminal";
13+
if (routePath.endsWith("/review")) return "review";
14+
if (routePath.startsWith("/threads/")) return "thread";
15+
if (routePath === "/") return "threads";
16+
return null;
17+
}
18+
19+
/** Agent activity is staged on the threads list, so that route counts as the scene. */
20+
export function showcaseSceneOnScreen(
21+
requestedScene: ShowcaseScene | null,
22+
pathname: string,
23+
): ShowcaseScene | null {
24+
const routeScene = sceneFromPathname(pathname);
25+
return requestedScene === "agent-activity" && routeScene === "threads"
26+
? "agent-activity"
27+
: routeScene;
28+
}
29+
30+
export function isShowcaseThemeApplied(input: {
31+
readonly launchRequestRead: boolean;
32+
readonly requestedTheme: MobileThemeId | null;
33+
readonly themeIds: MobileThemeIds;
34+
}): boolean {
35+
if (input.requestedTheme === null) return input.launchRequestRead;
36+
return (
37+
input.themeIds.light === input.requestedTheme && input.themeIds.dark === input.requestedTheme
38+
);
39+
}
40+
41+
export interface ShowcaseReadinessInput {
42+
readonly scene: ShowcaseScene | null;
43+
readonly requestedScene: ShowcaseScene | null;
44+
readonly hasFixture: boolean;
45+
readonly orientationSettled: boolean;
46+
readonly themeApplied: boolean;
47+
readonly agentActivityStaged: boolean;
48+
readonly themeId: MobileThemeId;
49+
readonly renderSignal: ShowcaseRenderSignal | null;
50+
/** Counts render-signal changes; a redraw report restarts the settle delay. */
51+
readonly renderReports: number;
52+
}
53+
54+
/**
55+
* The capture key for a scene that is ready to be marked, or null while any
56+
* precondition is missing. A changed key restarts the settle delay.
57+
*/
58+
export function showcaseReadinessKey(input: ShowcaseReadinessInput): string | null {
59+
const { scene } = input;
60+
if (
61+
scene === null ||
62+
scene !== input.requestedScene ||
63+
!input.hasFixture ||
64+
!input.orientationSettled ||
65+
!input.themeApplied ||
66+
(scene === "agent-activity" && !input.agentActivityStaged) ||
67+
!isShowcaseNativeContentReady({
68+
scene,
69+
themeId: input.themeId,
70+
renderSignal: input.renderSignal,
71+
})
72+
) {
73+
return null;
74+
}
75+
return [scene, input.themeId, input.renderReports].join("|");
76+
}

‎apps/mobile/src/features/showcase/showcaseRenderSignal.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,32 @@ export type ShowcaseRenderSignal = Readonly<{
88

99
const listeners = new Set<() => void>();
1010
let renderSignal: ShowcaseRenderSignal | null = null;
11+
// A redraw can repeat the same scene and theme; counting reports lets it restart the settle delay.
12+
let renderReports = 0;
1113

1214
export function getShowcaseRenderSignal(): ShowcaseRenderSignal | null {
1315
return renderSignal;
1416
}
1517

18+
export function getShowcaseRenderReports(): number {
19+
return renderReports;
20+
}
21+
1622
export function subscribeToShowcaseRenderSignal(listener: () => void): () => void {
1723
listeners.add(listener);
1824
return () => listeners.delete(listener);
1925
}
2026

2127
export function reportShowcaseSceneRendered(signal: ShowcaseRenderSignal): void {
2228
renderSignal = signal;
29+
renderReports += 1;
2330
for (const listener of listeners) listener();
2431
}
2532

2633
export function clearShowcaseRenderSignal(): void {
2734
if (renderSignal === null) return;
2835
renderSignal = null;
36+
renderReports += 1;
2937
for (const listener of listeners) listener();
3038
}
3139

0 commit comments

Comments
 (0)