diff --git a/docs/frontend-first-screen-performance.md b/docs/frontend-first-screen-performance.md new file mode 100644 index 00000000..9d3e668c --- /dev/null +++ b/docs/frontend-first-screen-performance.md @@ -0,0 +1,58 @@ +# Frontend first-screen loading + +This change moves non-critical modules out of the eager application entry and +onto the chunks that actually render them. No page markup, interaction or +styling rule changed; only when a resource is fetched. + +## What left the first screen + +| Resource | Before | After | +| --------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- | +| `lucide-react` (`icons-vendor`) | Statically reachable from the entry through `Layout`, `Sidebar`, `PluginRouteGuard` and `UserBootstrapPanel`, so the entry preloaded the union of every icon used by all lazy pages. | The eager shell uses `src/components/shell-icons.tsx`; the icon vendor chunk is only requested when a route that imports lucide renders. | +| `Sidebar` (navigation JSX, supplier/users helpers) | Bundled in the entry and parsed on every first paint. | Dynamic `import("./Sidebar")`, warmed only when `droboticflow.currentUserId` already exists. | +| `src/styles/capture-workspace.css` | Imported by the global `src/index.css`, so every page downloaded the annotation workspace layout rules. | Imported by `CaptureAnnotationWorkbench`, emitted with the annotation route CSS. | +| `WorkforceStatisticsPanel` | Bundled in the lazy Dashboard chunk even though it only renders in the collapsed legacy overview. | Lazy import inside a local `Suspense` boundary. | + +The eager shell now contains only React, React DOM, React Router, the context +providers, the API client, `Layout`, the plugin guard and the login panel. + +## Measuring FCP/LCP + +Build once per revision and serve `dist/` (the Go SPA handler or any static +server that also answers `/api/*` for the auth check): + +```bash +npm run build:web +``` + +Capture both metrics in a Playwright page with a fresh browser context: + +```js +await page.addInitScript(() => { + window.__vitals = {}; + new PerformanceObserver((list) => { + for (const entry of list.getEntries()) window.__vitals.fcp = entry.startTime; + }).observe({ type: "paint", buffered: true }); + new PerformanceObserver((list) => { + const entries = list.getEntries(); + window.__vitals.lcp = entries[entries.length - 1].startTime; + }).observe({ type: "largest-contentful-paint", buffered: true }); +}); +await page.goto(origin, { waitUntil: "networkidle" }); +const vitals = await page.evaluate(() => window.__vitals); +``` + +Run the same script against the base commit and this branch with the same +network/CPU throttling and the same auth fixture. The first screen for an +unauthenticated session must not request `icons-vendor`, the `Sidebar` chunk or +the annotation workspace stylesheet. For a returning session the `Sidebar` +chunk is warmed as soon as the shell paints, concurrently with `/api/auth/me`, +instead of after the route starts rendering. + +## Verification commands + +```bash +npm run lint:web +npm run test:frontend:gate +npm run build:web +``` diff --git a/src/components/CaptureAnnotationWorkbench.tsx b/src/components/CaptureAnnotationWorkbench.tsx index 642a65df..a84181e6 100644 --- a/src/components/CaptureAnnotationWorkbench.tsx +++ b/src/components/CaptureAnnotationWorkbench.tsx @@ -1,4 +1,8 @@ import type { AnnotationTimelineFailure } from "../lib/annotation-source-validation"; +// Workbench-only layout rules. Loading them with this component (instead of +// the global entry stylesheet) keeps the annotation workspace CSS off the +// application's first screen. +import "../styles/capture-workspace.css"; import { createSliceEditSession, freezeSliceEditSession, diff --git a/src/components/Layout.tsx b/src/components/Layout.tsx index c32c29e8..f79d2c36 100644 --- a/src/components/Layout.tsx +++ b/src/components/Layout.tsx @@ -1,11 +1,10 @@ -import React, { useEffect, useRef, useState } from "react"; +import React, { Suspense, lazy, useEffect, useRef, useState } from "react"; import { useLocation } from "react-router-dom"; import { AnnotationWorkspaceLayoutContext, useAnnotationLayoutPreference, } from "../context/AnnotationWorkspaceLayoutContext"; -import { Loader2, Moon, Sun } from "lucide-react"; -import { Sidebar } from "./Sidebar"; +import { Loader2, Moon, Sun } from "./shell-icons"; import { UserBootstrapPanel } from "./UserBootstrapPanel"; import { useUser } from "../context/UserContext"; import { getActionErrorMessage } from "../lib/action-errors.js"; @@ -17,6 +16,26 @@ interface LayoutProps { children: React.ReactNode; } +// The sidebar is only mounted after the current user resolves, but it is not +// needed to paint the shell. Keeping it in its own chunk removes its icon set +// and API helpers from the entry bundle; a returning user starts the request +// as soon as the shell paints so the navigation is ready when auth completes. +const Sidebar = lazy(() => import("./Sidebar").then((module) => ({ default: module.Sidebar }))); + +const CURRENT_USER_STORAGE_KEY = "droboticflow.currentUserId"; + +function SidebarFallback({ collapsed }: { collapsed: boolean }) { + return ( +