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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 andall, 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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 pendingdiff --git a/site/src/cut/components/RequireSession.tsx b/site/src/cut/components/RequireSession.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsindex 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.tsindex 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. */