# Frontend Components - Unit 1: Start migration and script step All paths are under `web/`. Interfaces for new files follow [component-methods.md](../../../inception/application-design/component-methods.md); this document fixes the details and records the additions (marked **new**). Rules: [business-rules.md](business-rules.md). Logic: [business-logic-model.md](business-logic-model.md). First-render values: [domain-entities.md § 3](domain-entities.md). ## 1. Component hierarchy ```mermaid graph TD Vite["vite.config.ts with Start plugin"] --> Router["src/router.tsx getRouter"] Client["src/client.tsx: Sentry, then hydrate"] --> Router Router --> Root["routes/__root.tsx shellComponent"] Root --> Html["html, HeadContent, ChakraProvider, Scripts"] Html --> App["AppShell"] App --> Nav["NavigationBar and MobileNav"] App --> Out["Outlet: page routes and catch-all"] App --> Foot["Footer"] App --> Top["BackToTop"] App --> Umami["UmamiAnalytics"] Out --> Pages["index, contact, portfolio, other pages"] Out --> NF["routes/$.tsx NotFound"] Pages --> Panel["ContactPanel and ContactFormGate"] Pages --> Details["ContactDetails"] Pages --> Tests["Testimonials"] Nav --> Hyd["useHydrated"] Foot --> Mail["useEmailAddress"] Details --> Mail Panel --> Mail NF --> Hyd Pages --> Hyd Mail --> Hyd Cfg["config: pageFiles, inlineScripts, externalizeInlineScripts, previewServer"] -.-> Vite classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef app fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; classDef hook fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef infra fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000; class Vite,Router,Client,Root,Html build; class App,Nav,Out,Foot,Top,Umami,Pages,NF,Panel,Details,Tests app; class Hyd,Mail hook; class Cfg infra; ``` Text alternative: the Start build and the browser entry both use getRouter; the root shell renders the document around AppShell, whose navigation, pages, footer and monitoring components use the hydration hooks (green = app components, yellow = hooks, blue = build and entry, orange = config tools). ## 2. Changed components "Contract" is what the component renders in the first render, on the server and in the browser (BR-HYD-01). ### Build, entry and document | Component | Status | Contract and behaviour | |---|---|---| | `vite.config.ts` | Changed | `tanstackStart` with prerender: pages from `sitePages` plus `/404` to `/404.html`, `autoSubfolderIndex: false`, no extra crawling. Start plugin only outside Vitest. `define` of `VITE_BUILD_YEAR`. `sitemapPlugin` emits in the client environment only. CSP headers for `server` and `preview` stay from `securityHeaders`. | | `src/router.tsx` | **new** | `getRouter()` and a shared options function (routeTree, `scrollRestoration: true`, `defaultErrorComponent: ErrorPage`). | | `src/routes/__root.tsx` | Changed | `shellComponent` renders ``, `HeadContent`, `ChakraProvider value={system}` around children, `Scripts` last. `head()` adds charset, viewport, `favicon.png` icon and `apple-touch-icon` besides `siteHead`. Fonts imported here. `component` stays `RootLayout` (without `HeadContent`, which moves to the shell). `notFoundComponent` and `errorComponent` stay. | | `src/client.tsx` | **new** | `startSentry()`, then hydrate inside `StrictMode`. Replaces `main.tsx`; `index.html` is removed. | | `src/routes/$.tsx` | **new** | Catch-all route, component `NotFound`. No `head()`. | | `config/inlineScripts.ts` | **new** | `externalizeInlineScripts`, `findExecutableInlineScripts` (signatures as in component-methods.md). | | `config/externalizeInlineScripts.ts` | **new** | `externalizeOutput(clientDir)`, plus exported `planExternalization(files, context)` (**new**, pure core). Runs as a script with Node type stripping like `writeServerConfig.ts`. | | `config/pageFiles.ts` | **new** | `pageFile`, `pagePath`, `NOT_FOUND_FILE`, `NOT_FOUND_PATH`. | | `config/previewServer.ts` | **new** | `resolveRequest`, `startPreviewServer`. `package.json` `preview` runs it. | | `config/sitemapPlugin.ts` | Changed | Emits `sitemap.xml` only when `this.environment.name` is the client environment (to verify V7). | | `src/test/renderApp.tsx` | Changed | Router from the shared options with memory history; no `` shell (V2). | | `e2e/` | **new** | Playwright tests of BR-TST-05 and BR-TST-06. | ### Hooks | Hook | Status | Interface and contract | |---|---|---| | `hooks/useHydrated.ts` | **new** | `useHydrated(): boolean`. `useSyncExternalStore(subscribeNoop, () => true, () => false)`. Same behaviour as the `useHydrated` that `@tanstack/react-router` exports (marked internal there), so the project owns its copy. | | `hooks/useEmailAddress.ts` | **new** | `useEmailAddress(email: EmailAddress): { available: boolean; address: string \| null }` (BR-MAIL-01). | | `hooks/usePageLoaded.ts` | Changed | Store-based (BR-HYD-04). Returns `false` while hydrating. | | `hooks/useInView.ts` | Changed | Same options and return `{ ref, inView }`. `inView = skip \|\| intersected \|\| unsupported` (BR-HYD-05). The "no observer counts as in view" contract is applied after the first render. | | `hooks/useReveal.ts` | Changed | `useMediaQuery` without `ssr: false`; first render `reducedMotion` is `false`. Returns `{ ref, visible }` as before; the visible-by-default rule is unit 2. | | `hooks/useScrolledPast.tsx` | Unchanged | Verified safe (BR-HYD-06). The application design lists it as changed; it needs no change. | | `Hero/useHeroSlider.ts` | Changed | `hidden` from a store, `useMediaQuery` without `ssr: false`; first render `autoplay` is `count > 1`. | ### Pages and components | Component | Status | Contract | |---|---|---| | `routes/index.tsx` | Changed | `pakket` passed to `ContactSection` is `hydrated ? search.pakket : undefined`. | | `routes/contact.tsx` | Changed | Same for `ContactPanel`; the tidy effect depends on the gated value. | | `routes/portfolio.tsx` | Changed | `shoot` passed to `PortfolioGallery` is `hydrated ? search.shoot : undefined`; navigation callback unchanged. | | `NavigationBar` | Changed | `useBreakpointValue` without `ssr: false` (first render `false`); all `NavLink`s get `activeOptions={{ exact: true, includeSearch: false }}`. Layout stays CSS-driven, so no visible jump. | | `MobileNav` | Changed | Top-level links get the same `activeOptions`. | | `IntroGallery` | Unchanged | `useBreakpointValue` already uses the default; first render `scrollable` is `true` (BR-HYD-08). | | `ContactSection` | Changed | `useMediaQuery` without `ssr: false`; effect unchanged. | | `TestimonialCarousel` | Changed | `useMediaQuery` without `ssr: false`. Only renders after hydration. | | `Testimonials` | Changed | `CarouselPlaceholder` renders every visible review (longest in flow, others `aria-hidden`, visually hidden, `inert`) so the texts are in the HTML (BR-LZY-02). | | `NotFound` | Changed | `hydrated && isShootSectionPath(pathname)` picks the buttons. Renders its own `