Skip to content

Open source CapCut alternative.

TypeScript

refactor(site): paint the Cut app shell before the session resolves

David Lee55e48b61c89
diff --git a/site/src/app/cut/app/(home)/library/page.tsx b/site/src/app/cut/app/(home)/library/page.tsx
index 8b965f25..2524cea6 100644
--- a/site/src/app/cut/app/(home)/library/page.tsx
+++ b/site/src/app/cut/app/(home)/library/page.tsx
@@ -1,12 +1,17 @@
import { Suspense } from "react";
import { LibraryView } from "@/cut/components/LibraryView";
+import { SessionGate } from "@/cut/components/SessionGate";
+
+export const unstable_instant = { prefetch: "static" };
// Suspense: the view reads the open folder from ?folder=…, and useSearchParams
// needs a boundary in a statically prerendered shell.
export default function LibraryPage() {
return (
<Suspense>
- <LibraryView />
+ <SessionGate>
+ <LibraryView />
+ </SessionGate>
</Suspense>
);
}
diff --git a/site/src/app/cut/app/(home)/onboarding/page.tsx b/site/src/app/cut/app/(home)/onboarding/page.tsx
index b2cf70ed..8e2abb05 100644
--- a/site/src/app/cut/app/(home)/onboarding/page.tsx
+++ b/site/src/app/cut/app/(home)/onboarding/page.tsx
@@ -4,6 +4,7 @@ import { Suspense, useEffect, useRef } from "react";
import { useRouter } from "next/navigation";
import { ProjectsHome } from "@/cut/components/ProjectsHome";
+import { SessionGate } from "@/cut/components/SessionGate";
import { cloudBackend } from "@/cut/lib/backend/cloud";
import { CUT_APP_BASE } from "@/cut/lib/nav";
import { starterProjectId } from "@/cut/lib/starter";
@@ -42,7 +43,9 @@ export default function OnboardingPage() {
return (
<Suspense>
- <ProjectsHome />
+ <SessionGate>
+ <ProjectsHome />
+ </SessionGate>
</Suspense>
);
}
diff --git a/site/src/app/cut/app/(home)/page.tsx b/site/src/app/cut/app/(home)/page.tsx
index 896bac70..e218d807 100644
--- a/site/src/app/cut/app/(home)/page.tsx
+++ b/site/src/app/cut/app/(home)/page.tsx
@@ -1,12 +1,19 @@
import { Suspense } from "react";
import { ProjectsHome } from "@/cut/components/ProjectsHome";
+import { SessionGate } from "@/cut/components/SessionGate";
+
+export const unstable_instant = { prefetch: "static" };
// Suspense: the view reads the open folder from ?folder=…, and useSearchParams
-// needs a boundary in a statically prerendered shell.
+// needs a boundary in a statically prerendered shell. SessionGate is what makes
+// that shell worth having: the sidebar and this pane's skeleton are the first
+// paint, and the shelf fills in when the account id lands.
export default function Home() {
return (
<Suspense>
- <ProjectsHome />
+ <SessionGate>
+ <ProjectsHome />
+ </SessionGate>
</Suspense>
);
}
diff --git a/site/src/app/cut/app/layout.tsx b/site/src/app/cut/app/layout.tsx
index 2ae5e794..50385f76 100644
--- a/site/src/app/cut/app/layout.tsx
+++ b/site/src/app/cut/app/layout.tsx
@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { Suspense, type ReactNode } from "react";
import { AppSurfaceBackground } from "@/components/AppSurfaceBackground";
import { NoSessionReplay } from "@/app/_components/NoSessionReplay";
@@ -6,33 +6,52 @@ import { ConnectGate } from "@/cut/components/ConnectGate";
import { ExportsDock } from "@/cut/components/ExportsDock";
import { CutOnboarding } from "@/cut/components/onboarding/CutOnboarding";
import { RequireSession } from "@/cut/components/RequireSession";
+import { SessionGate, SessionSkeleton } from "@/cut/components/SessionGate";
// The Cut app (projects home, library, editor) renders on the same white
// product surface as Donkey's /app, not the cream marketing background of the
// landing page that lives one segment up. AppSurfaceBackground paints the root
// html white so the cream does not show through the overscroll area, and
-// font-system matches the /app system font stack. RequireSession gates the
-// whole subtree on a signed-in session, redirecting signed-out visitors to
-// sign-in with their target URL as the callback. ConnectGate picks the backend
-// the app runs on — the engine on this Mac when it answers without raising the
-// browser's local-network prompt, the cloud otherwise — and owns the banner
-// that reports an engine this browser can no longer reach. CutOnboarding is the
-// welcome sequence a new account sees before any of it.
+// font-system matches the /app system font stack. RequireSession binds the
+// account and redirects signed-out visitors to sign-in with their target URL as
+// the callback. ConnectGate picks the backend the app runs on — the engine on
+// this Mac when it answers without raising the browser's local-network prompt,
+// the cloud otherwise — and owns the banner that reports an engine this browser
+// can no longer reach. CutOnboarding is the welcome sequence a new account sees
+// before any of it.
+//
+// The surface, the sidebar under it, and the banner are the shell: they render
+// with no session and no account, which is what a cold load paints. Everything
+// that reads the engine waits behind a SessionGate for the account id.
+
export default function CutAppLayout({ children }: { children: ReactNode }) {
return (
<div className="min-h-screen bg-white font-system text-foreground antialiased">
<AppSurfaceBackground />
<NoSessionReplay />
- <RequireSession>
- <ConnectGate>
- {children}
- {/* App-wide: exports keep showing as you move between projects. */}
- <ExportsDock />
- </ConnectGate>
- {/* Outside the gate so a first run covers the whole window, gate and
+ {/* A route whose address carries data — the editor's project id — can't be
+ in the prerendered shell, and the framework resolves that above the
+ client shell below. The boundary is here so it has somewhere to land:
+ the home routes suspend on nothing and prerender whole, and the editor
+ arrives as this skeleton on the app's own surface. */}
+ <Suspense fallback={<SessionSkeleton />}>
+ <RequireSession>
+ <ConnectGate>
+ {children}
+ {/* App-wide: exports keep showing as you move between projects. Both
+ overlays read the account, so they wait for it; neither has a
+ shape worth drawing before then. */}
+ <SessionGate fallback={null}>
+ <ExportsDock />
+ </SessionGate>
+ </ConnectGate>
+ {/* Outside the gate so a first run covers the whole window, gate and
all, and hands over to it when the last slide closes. */}
- <CutOnboarding />
- </RequireSession>
+ <SessionGate fallback={null}>
+ <CutOnboarding />
+ </SessionGate>
+ </RequireSession>
+ </Suspense>
</div>
);
}
diff --git a/site/src/app/cut/app/p/[id]/ProjectEditor.tsx b/site/src/app/cut/app/p/[id]/ProjectEditor.tsx
new file mode 100644
index 00000000..939be147
--- /dev/null
+++ b/site/src/app/cut/app/p/[id]/ProjectEditor.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import { useSearchParams } from "next/navigation";
+
+import { Editor } from "@/cut/components/Editor";
+import { SessionGate } from "@/cut/components/SessionGate";
+
+// `from` and `folder` record which tab (and folder within it) opened the
+// project so the editor's back button returns there; residency is resolved from
+// the id itself (lib/residency.ts). The id arrives as a plain string — the page
+// resolves the route param above this, inside its own boundary.
+export function ProjectEditor({ projectId }: { projectId: string }) {
+ const params = useSearchParams();
+ return (
+ <SessionGate>
+ <Editor
+ projectId={projectId}
+ from={params.get("from")}
+ folder={params.get("folder")}
+ />
+ </SessionGate>
+ );
+}
diff --git a/site/src/app/cut/app/p/[id]/page.tsx b/site/src/app/cut/app/p/[id]/page.tsx
index e2473f0f..2ee53783 100644
--- a/site/src/app/cut/app/p/[id]/page.tsx
+++ b/site/src/app/cut/app/p/[id]/page.tsx
@@ -1,25 +1,18 @@
-"use client";
-
import { Suspense } from "react";
-import { useParams, useSearchParams } from "next/navigation";
-import { Editor } from "@/cut/components/Editor";
-// Client-only: the id comes from the URL in the browser, so the hosted shell
-// carries no server-rendered data. `from` and `folder` record which tab (and
-// folder within it) opened the project so the editor's back button returns
-// there; residency is resolved from the id itself (lib/residency.ts).
-function ProjectEditor() {
- const { id } = useParams<{ id: string }>();
- const params = useSearchParams();
- return (
- <Editor projectId={id} from={params.get("from")} folder={params.get("folder")} />
- );
-}
+import { SessionSkeleton } from "@/cut/components/SessionGate";
+import { ProjectEditor } from "./ProjectEditor";
-export default function ProjectPage() {
+// The project id is in the URL, so it is request data and the editor can never
+// be part of the prerendered shell. Resolving the param here, inside this
+// boundary, is what keeps the rest of the app — surface, banner, sidebar — in
+// that shell: the page arrives painted with a skeleton where the editor lands.
+export default function ProjectPage({ params }: { params: Promise<{ id: string }> }) {
return (
- <Suspense>
- <ProjectEditor />
+ <Suspense fallback={<SessionSkeleton />}>
+ {params.then(({ id }) => (
+ <ProjectEditor projectId={id} />
+ ))}
</Suspense>
);
}
diff --git a/site/src/cut/components/ConnectGate.tsx b/site/src/cut/components/ConnectGate.tsx
index 24af24a7..f17b0a4d 100644
--- a/site/src/cut/components/ConnectGate.tsx
+++ b/site/src/cut/components/ConnectGate.tsx
@@ -22,7 +22,7 @@ import {
servedFromEngine,
} from "@/cut/lib/api";
import { announceLocalCompute, setCutMode } from "@/cut/lib/backend";
-import { useCutMode } from "@/cut/lib/backend/hooks";
+import { useCutMode, useEngineUser } from "@/cut/lib/backend/hooks";
import {
CONNECT_ACK_KEY,
ENGINE_CONNECTED_EVENT,
@@ -80,6 +80,7 @@ export function ConnectGate({ children }: { children: ReactNode }) {
// needs the app. Either one is what the banner is about.
const mode = useCutMode();
const needsApp = useNeedsApp();
+ const user = useEngineUser();
// Whether the engine on this Mac is reachable right now.
const [reached, setReached] = useState<boolean | null>(null);
// This browser has used the engine before, so an unreachable one is news.
@@ -138,10 +139,12 @@ export function ConnectGate({ children }: { children: ReactNode }) {
bindCloud();
}, [bindCloud, bindEngine]);
+ // The probe carries the account id like every other engine call, so it waits
+ // for one. The banner and the app around it paint before that.
useEffect(() => {
- if (onSettings) return;
+ if (onSettings || !user) return;
void check();
- }, [check, onSettings]);
+ }, [check, onSettings, user]);
// Keep probing behind the banner so the app connects the moment the engine
// appears. Both skips are permanent conditions, not slow ones: a pending
diff --git a/site/src/cut/components/RequireSession.tsx b/site/src/cut/components/RequireSession.tsx
index 86b6c415..64384254 100644
--- a/site/src/cut/components/RequireSession.tsx
+++ b/site/src/cut/components/RequireSession.tsx
@@ -12,26 +12,30 @@ import { authClient } from "@/lib/auth-client";
// navigation to an app URL the same way, sending the visitor to sign-in with
// the URL they wanted as the post-auth callback.
//
-// The app renders only once the session is known: every engine URL carries
-// the account id (the engine keeps each account's data separate), so a
-// component rendered earlier would build unscoped media URLs. Holding
-// children until the id is bound makes that impossible; the session check is
-// a fast same-origin cookie read, and the ConnectGate's own connect flow
-// covers the moment visually.
+// It binds the account id and never holds the tree: the chrome around the
+// content — the surface, the sidebar, the connect banner — is worth painting
+// before a session exists, and it is what a cold load shows. What must wait is
+// anything that reads the engine, because every engine URL carries the id, and
+// SessionGate is where each surface waits for it.
export function RequireSession({ children }: { children: ReactNode }) {
const { data: session, isPending } = authClient.useSession();
const signedOut = !isPending && !session;
+ const userId = session?.user.id;
useAppLoaded("cut", session?.user);
+ // Bound in an effect so the render stays free of side effects; SessionGate
+ // subscribes to it, so the surfaces redraw the moment the id lands.
+ useEffect(() => {
+ if (userId) setEngineUser(userId);
+ }, [userId]);
+
useEffect(() => {
if (!signedOut) return;
const here = window.location.pathname + window.location.search;
window.location.replace(authHrefFor("/sign-in", here));
}, [signedOut]);
- if (!session) return null;
- setEngineUser(session.user.id);
return <>{children}</>;
}
diff --git a/site/src/cut/components/SessionGate.tsx b/site/src/cut/components/SessionGate.tsx
new file mode 100644
index 00000000..a86f0ecc
--- /dev/null
+++ b/site/src/cut/components/SessionGate.tsx
@@ -0,0 +1,38 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { Skeleton } from "@/components/ui/skeleton";
+import { useEngineUser } from "@/cut/lib/backend/hooks";
+
+// The line between the app's chrome and its contents. The sidebar, the surface,
+// and the banner render from the first byte; everything that reads the engine
+// waits behind this, because every engine URL carries the account id (the `u`
+// param) and the id only exists once the browser has read the session cookie.
+//
+// Holding the surface here — rather than above the sidebar — is what lets the
+// app paint before the session resolves: the shell a visitor sees on a cold
+// load is the real navigation with a skeleton where the content will land.
+export function SessionGate({
+ children,
+ fallback,
+}: {
+ children: ReactNode;
+ /** Shown while the session resolves. Defaults to a page-sized skeleton. */
+ fallback?: ReactNode;
+}) {
+ const user = useEngineUser();
+ if (user) return <>{children}</>;
+ return <>{fallback ?? <SessionSkeleton />}</>;
+}
+
+/** The shape of a loading app surface: a title over a body that fills the
+ * column it was given, so it reads the same in the home panes and the editor. */
+export function SessionSkeleton() {
+ return (
+ <div className="h-full w-full p-10">
+ <Skeleton className="h-8 w-48" />
+ <Skeleton className="mt-6 h-[calc(100%-3.5rem)] w-full" />
+ </div>
+ );
+}
diff --git a/site/src/cut/components/onboarding/CutOnboarding.tsx b/site/src/cut/components/onboarding/CutOnboarding.tsx
index 982caa46..c7085fd5 100644
--- a/site/src/cut/components/onboarding/CutOnboarding.tsx
+++ b/site/src/cut/components/onboarding/CutOnboarding.tsx
@@ -61,7 +61,7 @@ const doneHere = (userId: string): boolean =>
// thing it writes is what it asks for: where the account heard about us.
export function CutOnboarding() {
const base = useCutBase();
- // Mounted inside RequireSession, so the session is already resolved.
+ // Mounted inside a SessionGate, so the session is already resolved.
const { data: session } = authClient.useSession();
const userId = session?.user.id ?? "";
const { data: state, isPending } = useOnboardingState();
diff --git a/site/src/cut/lib/api.ts b/site/src/cut/lib/api.ts
index e2417c7c..7acc0c0c 100644
--- a/site/src/cut/lib/api.ts
+++ b/site/src/cut/lib/api.ts
@@ -129,16 +129,23 @@ export function engineOrigin(): string {
return resolvedOrigin ?? "";
}
-// The signed-in Donkey account, set by RequireSession before the app renders.
-// Every engine URL carries it (the `u` param) — headers can't, because media
-// loads as plain <video>/<img> src. Local data is shared by every account on
-// the Mac, so current engines ignore the param; engines released before
-// 2026-08 refuse data requests without it, which is why the page keeps
+// The signed-in Donkey account, set by RequireSession once the session
+// resolves. Every engine URL carries it (the `u` param) — headers can't,
+// because media loads as plain <video>/<img> src. Local data is shared by every
+// account on the Mac, so current engines ignore the param; engines released
+// before 2026-08 refuse data requests without it, which is why the page keeps
// sending it.
+//
+// It is observable because the app shell paints before the session is known:
+// the surfaces that read the engine subscribe through useEngineUser and hold a
+// skeleton until an id is here, so an unscoped read has no moment to happen in.
let engineUser: string | null = null;
+const listeners = new Set<() => void>();
export function setEngineUser(id: string) {
+ if (engineUser === id) return;
engineUser = id;
+ for (const fn of listeners) fn();
}
/** The bound account, or null before the session resolves. Client-side caches
@@ -148,6 +155,12 @@ export function currentEngineUser(): string | null {
return engineUser;
}
+/** Called when the bound account changes; returns its own unsubscribe. */
+export function subscribeEngineUser(fn: () => void): () => void {
+ listeners.add(fn);
+ return () => listeners.delete(fn);
+}
+
const scopedPath = (path: string) =>
engineUser
? `${path}${path.includes("?") ? "&" : "?"}u=${encodeURIComponent(engineUser)}`
diff --git a/site/src/cut/lib/backend/hooks.ts b/site/src/cut/lib/backend/hooks.ts
index 61fca98c..ce52b97c 100644
--- a/site/src/cut/lib/backend/hooks.ts
+++ b/site/src/cut/lib/backend/hooks.ts
@@ -3,6 +3,7 @@
import { useQuery } from "@tanstack/react-query";
import { useSyncExternalStore } from "react";
+import { currentEngineUser, subscribeEngineUser } from "../api";
import { listedResidencies, type Residency } from "../residency";
import { cutMode, getBackend, hasLocalCompute, subscribeCutMode } from "./index";
import type { CutCaps, CutMode } from "./types";
@@ -11,6 +12,12 @@ export function useCutMode(): CutMode {
return useSyncExternalStore(subscribeCutMode, cutMode, () => "local" as const);
}
+/** The account every engine read is scoped to, or null before the session has
+ * resolved. Null on the server, so a prerendered shell holds its skeleton. */
+export function useEngineUser(): string | null {
+ return useSyncExternalStore(subscribeEngineUser, currentEngineUser, () => null);
+}
+
/** Whether this Mac's engine is reachable, as a subscription: the gate resolves
* it after the first paint, so a screen that offers local work has to redraw
* when the answer lands. */