create-keboola-app 0.1.1 → 0.2.1

package/dist/template/src/components/SidebarModeMenu.tsx

@@ -9,14 +9,12 @@ const MODES: { value: SidebarMode; label: string }[] = [
 ];
 
 /**
- * Picks the left rail's mode. All three come from `SidebarProvider`.
+ * Picks the left rail's mode.
  *
- * - `expand-on-hover` is a mode of its own, not `collapsed` plus a hover handler: the
- *   rail reports `mode="expand-on-hover"` while its `state` flips on hover. Styling that
- *   distinguishes "the user collapsed this" from "collapsed until hovered" reads `mode`.
- * - A radio group, not a cycling button: three modes have no natural next, and the menu
- *   shows which is active without clicking through.
- * - `setMode` writes through `onLeftModeChange` into the app store, which persists it.
+ * - `expand-on-hover` is its own mode: `state` flips on hover, so styling that tells it from
+ *   `collapsed` reads `mode`.
+ * - A radio group, not a cycling button: three modes have no natural next.
+ * - `setMode` persists through `onLeftModeChange` into the app store.
  */
 export function SidebarModeMenu() {
   const { setMode, mode } = useSidebar('left');
@@ -25,8 +23,7 @@ export function SidebarModeMenu() {
     <Sidebar.MenuItem>
       <DropdownMenu>
         <DropdownMenu.Trigger asChild>
-          {/* `w-fit` keeps the trigger icon-sized rather than rail-wide, so it holds its
-              position when the rail collapses to icons. */}
+          {/* `w-fit` holds the trigger in place when the rail collapses. */}
           <Sidebar.MenuButton
             tooltip="Sidebar mode"
             className="tw:w-fit"
@@ -34,12 +31,10 @@ export function SidebarModeMenu() {
             aria-label="Sidebar mode"
           />
         </DropdownMenu.Trigger>
-        {/* `align="start"` — the trigger sits at the rail's left edge, so a centered
-            menu would hang off the viewport when the rail is collapsed. */}
+        {/* A centered menu would hang off the viewport when the rail is collapsed. */}
         <DropdownMenu.Content align="start">
           <DropdownMenu.Label>Sidebar mode</DropdownMenu.Label>
-          {/* `RadioGroup` is generic over its value: `value={mode}` pins it to
-              `SidebarMode`, so `setMode` slots in without a cast. */}
+          {/* `value={mode}` types the group as `SidebarMode`, so `setMode` needs no cast. */}
           <DropdownMenu.RadioGroup value={mode} onValueChange={setMode}>
             {MODES.map(({ value, label }) => (
               <DropdownMenu.RadioItem key={value} closeOnSelect indicatorAlign="end" value={value}>

package/dist/template/src/nav.ts

@@ -3,7 +3,7 @@ import type { ComponentType } from 'react';
 import { LayoutDashboard } from '@keboola/design/icons';
 
 // #region block:crud
-import { tokensNavItem } from './routes/tokens/-nav';
+import { tokensNavItem } from './tokens/nav';
 // #endregion block:crud
 
 export type NavItem = { to: string; label: string; icon: ComponentType };
@@ -11,12 +11,9 @@ export type NavItem = { to: string; label: string; icon: ComponentType };
 /**
  * The left rail's destinations, in render order.
  *
- * - `as const` keeps each `to` a literal. `Link`'s `to` is typed against the generated
- *   route tree, so a widened `string` fails type-check at the call site.
- * - `satisfies` checks the shape without erasing those literals.
- * - Icons render with no props (`<item.icon />`).
- * - Each block contributes its own entry from a module the block owns, so a deselected block
- *   takes its import with it.
+ * - `as const` keeps each `to` literal for `Link`'s route-typed `to`; `satisfies` won't widen it.
+ * - Icons render with no props.
+ * - Each block owns its entry, so a deselected block takes its import with it.
  */
 export const NAV = [
   { to: '/', label: 'Overview', icon: LayoutDashboard },
@@ -29,10 +26,8 @@ export const NAV = [
  * Whether `to` is the active destination for `pathname`.
  *
  * - The root matches exactly.
- * - Any other item stays active on its nested routes, matching Router's default
- *   non-exact `Link` behaviour.
- * - A sibling that merely shares the prefix (`/tokens-archive` under `/tokens`) is not
- *   nested — hence the `/` in the boundary check.
+ * - Others stay active on nested routes, like Router's non-exact `Link`.
+ * - The `/` boundary keeps `/tokens-archive` from matching `/tokens`.
  */
 export const isActive = (pathname: string, to: string) =>
   to === '/' ? pathname === '/' : pathname === to || pathname.startsWith(`${to}/`);

package/dist/template/src/{routes/-fixtures.ts → overview-fixtures.ts}

@@ -1,7 +1,5 @@
-// In-memory stand-in for a real overview endpoint. Swap `fetchOverview` for the
-// api-client call (e.g. `api.metrics.overview(signal)`) and delete this file.
-// The call takes an AbortSignal and honors it, so the query hook threads
-// cancellation exactly as it would against a real client — see -hooks.ts.
+// In-memory stand-in for an overview endpoint; swap `fetchOverview` for the api-client call.
+// It honors its AbortSignal like a real client — see overview-hooks.ts.
 
 export type Kpi = {
   label: string;
@@ -33,16 +31,10 @@ const OVERVIEW: Overview = {
     { label: 'Job success rate', value: '98.7%', deltaPct: 0.3 },
     { label: 'Storage used', value: '1.4 TB', deltaPct: 4.2 },
     { label: 'Active configurations', value: '312', deltaPct: 2.1 },
-    // No delta on purpose: `KpiCard` paints a rise green, which is the wrong
-    // signal for a cost. Leaving it off also exercises the optional branch.
+    // No delta: `KpiCard` paints a rise green, wrong for a cost.
     { label: 'Credits this month', value: '8,420' },
   ],
-  // Two series of the same order of magnitude, so they read against one linear
-  // axis. Pairing a ~60k series with a ~1k one renders the small one as a flat
-  // line on the floor — a chart that looks informative and isn't.
-  //
-  // Consumption climbs from a low base, so a zero baseline is honest *and* uses
-  // the plot: the story is the gap to the ceiling closing month over month.
+  // Same order of magnitude, so both read on one linear axis from zero.
   credits: [
     { month: 'Jan', used: 4200, budgeted: 8000 },
     { month: 'Feb', used: 5100, budgeted: 8000 },
@@ -51,9 +43,7 @@ const OVERVIEW: Overview = {
     { month: 'May', used: 7600, budgeted: 8500 },
     { month: 'Jun', used: 8420, budgeted: 8500 },
   ],
-  // The grid *is* the budget the chart plots: each month's column sums to that
-  // month's `budgeted` value above (8000 ×3, then 8500 ×3). Fixtures that don't
-  // reconcile are the fastest way to make a demo look fake.
+  // Each month's column sums to that month's `budgeted` above.
   budget: [
     {
       id: 'ex-db',
@@ -82,9 +72,7 @@ const OVERVIEW: Overview = {
   ],
 };
 
-// Simulates a network round-trip that resolves after `ms`, or rejects the moment
-// an AbortSignal fires — mirroring how a real fetch-based client aborts in-flight
-// when TanStack Query cancels the query.
+// Resolves after `ms`; rejects when the signal aborts, like a fetch-based client.
 const delay = (ms: number, signal?: AbortSignal): Promise<void> =>
   new Promise((resolve, reject) => {
     if (signal?.aborted) {

package/dist/template/src/{routes/-hooks.ts → overview-hooks.ts}

@@ -1,6 +1,6 @@
 import { useQuery } from '@tanstack/react-query';
 
-import { fetchOverview } from './-fixtures';
+import { fetchOverview } from './overview-fixtures';
 
 const queryKeys = {
   overview: ['overview'] as const,

package/dist/template/src/overview-sections.tsx

@@ -1,6 +1,5 @@
 import type { ReactNode } from 'react';
 
-import type { Overview } from './routes/-fixtures';
 // #region block:chart
 import { chartSection } from './sections/chart';
 // #endregion block:chart
@@ -10,6 +9,10 @@ import { gridSection } from './sections/grid';
 // #region block:kpi
 import { kpiSection } from './sections/kpi';
 // #endregion block:kpi
+// `simple-import-sort` orders a sibling path after every nested one, so this import belongs
+// past the final section region rather than inside it — the shell needs it whether or not a
+// scaffold keeps that block.
+import type { Overview } from './overview-fixtures';
 
 /**
  * One block's contribution to the overview.

package/dist/template/src/recipes/Chart.test.tsx

@@ -13,9 +13,7 @@ it('renders the chart card title and legend labels', () => {
         { month: 'Jan', mrr: 10 },
         { month: 'Feb', mrr: 12 },
       ]}
-      // recharts' <ResponsiveContainer> only renders once it measures a
-      // non-zero size via ResizeObserver, which jsdom never provides — an
-      // explicit width keeps the chart (and its legend) deterministic.
+      // jsdom never sizes recharts' <ResponsiveContainer>, so it would render nothing.
       width={400}
     />,
   );

package/dist/template/src/recipes/Chart.tsx

@@ -1,10 +1,8 @@
 import { Card } from '@keboola/design';
 import { type ChartColorToken, LineChart } from '@keboola/design/charts';
 
-// Token-aware chart recipe — colors come from CSS vars (semantic/brand tokens),
-// never hex, so it re-themes with the active brand. `LineChartCard` is a thin
-// app-level card wrapper over the DS `@keboola/design/charts` `LineChart`.
-// The chart palette slots the DS exposes; narrowed so a typo is a compile error.
+// Colors come from DS palette tokens, never hex, so the chart re-themes with the brand.
+// Narrowed so a typo is a compile error.
 type ChartTokenVar = '--chart-1' | '--chart-2' | '--chart-3' | '--chart-4' | '--chart-5';
 
 type Series = { key: string; label: string; tokenVar: ChartTokenVar };
@@ -14,16 +12,11 @@ type LineChartCardProps = {
   data: readonly Record<string, number | string>[];
   xKey: string;
   series: readonly Series[];
-  // Forwarded to the DS `LineChart` only when set; otherwise its responsive
-  // `width="100%"` default applies. Tests pass an explicit size — recharts'
-  // <ResponsiveContainer> only renders once it measures a non-zero size via
-  // ResizeObserver, which jsdom never provides.
+  // Unset → responsive `width="100%"`. Tests set it: jsdom never sizes <ResponsiveContainer>.
   width?: number;
 };
 
-// Maps a `--chart-N` token var name to the design system's `--color-chart-N`
-// palette slot (1–5). `LineChart` resolves colors from this slot internally —
-// it never accepts a raw CSS var or hex value.
+// `LineChart` takes a palette slot (1–5), never a raw CSS var or hex.
 const CHART_COLOR_SLOTS: Record<ChartTokenVar, ChartColorToken> = {
   '--chart-1': 1,
   '--chart-2': 2,

package/dist/template/src/recipes/DataGrid.test.tsx

@@ -2,7 +2,7 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { expect, it } from 'vitest';
 
-import type { BudgetRow } from '../routes/-fixtures';
+import type { BudgetRow } from '../overview-fixtures';
 
 import { CreditBudgetGrid } from './DataGrid';
 

package/dist/template/src/recipes/DataGrid.tsx

@@ -8,22 +8,17 @@ import {
 
 import { NumberInput, Table } from '@keboola/design';
 
-import type { BudgetRow } from '../routes/-fixtures';
-import { BUDGET_MONTHS } from '../routes/-fixtures';
+import type { BudgetRow } from '../overview-fixtures';
+import { BUDGET_MONTHS } from '../overview-fixtures';
 
-// Instantiates the DS editable-grid recipe (`Table.DataGridRecipe` story,
-// `EditableDataGrid`): TanStack Table v8 (headless) for the column/row model,
-// design `Table` for styling, design `NumberInput` as the editable cell, with a
-// live-computed row total column and footer grand total.
+// Instance of the DS editable-grid recipe (`Table.DataGridRecipe` story, `EditableDataGrid`).
 const sum = (xs: number[]) => xs.reduce((a, b) => a + b, 0);
 
 const columnHelper = createColumnHelper<BudgetRow>();
 
 export function CreditBudgetGrid({ rows }: { rows: BudgetRow[] }) {
-  // Server data seeds local edit state, re-seeding when a fetch returns new rows.
-  // Adjusted during render rather than in an effect: an effect would commit the
-  // stale rows first and repaint, and React documents this as the way to reset
-  // state on a prop change (design's own SidebarProvider does the same).
+  // Re-seeds edit state when `rows` changes.
+  // During render, not in an effect: an effect would paint the stale rows first.
   const [data, setData] = useState<BudgetRow[]>(rows);
   const [seed, setSeed] = useState<BudgetRow[]>(rows);
   if (seed !== rows) {
@@ -113,17 +108,8 @@ export function CreditBudgetGrid({ rows }: { rows: BudgetRow[] }) {
                     ? 'tw:min-w-52'
                     : cell.column.id === 'total'
                       ? 'tw:text-right tw:tabular-nums'
-                      : // Wide enough for the editor, not just the number. `NumberInput`
-                        // carries 16px of padding on each side, so a `w-20` (80px) cell
-                        // minus the `px-3` gutter left ~22px of text box — enough to
-                        // render "8" and silently hide the "00" of 800.
-                        //
-                        // `min-w`, not `w`: a width is only a hint, and a `w-full` table
-                        // squeezed by the assistant rail compresses past it and clips the
-                        // inputs again. A floor makes the table outgrow its container
-                        // instead, which the wrapper's `overflow-x-auto` then scrolls — a
-                        // single-line input can't be scrolled by eye, so its value has to
-                        // stay fully visible at any container width.
+                      : // Fits `NumberInput`'s 16px side padding; narrower clips "800" to "8".
+                        // `min-w`, not `w`: a squeezed table then scrolls instead of clipping.
                         'tw:min-w-28'
                 }
               >

package/dist/template/src/routes/__root.tsx

@@ -2,6 +2,9 @@ import { createRootRoute, Outlet } from '@tanstack/react-router';
 
 import { Toaster } from '@keboola/design';
 
+// #region block:auth
+import { useIsAuthRoute } from '../auth/session';
+// #endregion block:auth
 import { AppChrome } from '../components/AppChrome';
 
 export const Route = createRootRoute({
@@ -9,6 +12,24 @@ export const Route = createRootRoute({
 });
 
 function RootLayout() {
+  // #region block:auth
+  // The signed-out screen replaces the chrome instead of nesting in it.
+  // - No session → no rail, breadcrumb or history.
+  // - Nesting would duplicate AppChrome's `header`/`main` landmarks (axe).
+  // - Preflight is restated: `AuthScreen`'s own scope does not reach `Toaster` beside it.
+  // - The blank line before the closing marker must stay inside the region, or an app generated
+  //   without this block fails `oxfmt --check`.
+  const isAuthRoute = useIsAuthRoute();
+  if (isAuthRoute) {
+    return (
+      <div className="tailwindcss-preflight">
+        <Outlet />
+        <Toaster />
+      </div>
+    );
+  }
+
+  // #endregion block:auth
   return (
     <div className="tailwindcss-preflight">
       <AppChrome>

package/dist/template/src/routes/{-index.test.tsx → index.test.tsx}

@@ -6,9 +6,9 @@ import userEvent from '@testing-library/user-event';
 // #endregion block:assistant
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import * as fixtures from '../overview-fixtures';
 import { useAppStore } from '../store';
 
-import * as fixtures from './-fixtures';
 import { HomePage } from './index';
 
 const renderPage = () => {

package/dist/template/src/routes/index.tsx

@@ -7,12 +7,11 @@ import { ErrorState, PageHeader, PageLayout } from '@keboola/design';
 import { HomePrompt } from '../components/HomePrompt';
 import { SelectionFloater } from '../components/SelectionFloater';
 // #endregion block:assistant
+import type { Overview } from '../overview-fixtures';
+import { useOverview } from '../overview-hooks';
 import { OVERVIEW_SECTIONS } from '../overview-sections';
 import { useAppStore } from '../store';
 
-import type { Overview } from './-fixtures';
-import { useOverview } from './-hooks';
-
 export const Route = createFileRoute('/')({
   component: HomePage,
 });

package/dist/template/src/routes/signed-out.test.tsx

@@ -0,0 +1,56 @@
+import { createMemoryHistory, createRouter, RouterProvider } from '@tanstack/react-router';
+import { render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { keboola } from '@keboola/brand-registry';
+import { ThemeProvider } from '@keboola/design';
+
+import { routeTree } from '../routeTree.gen';
+
+// jsdom implements no scrolling, and Router's scroll restoration calls this on every navigation —
+// unstubbed it floods the run with `Not implemented: window.scrollTo`.
+beforeEach(() => {
+  vi.stubGlobal('scrollTo', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// The real tree, not a stub: the behaviour under test is the root layout choosing between
+// AppChrome and the bare outlet, and a hand-built tree would not exercise that choice.
+const renderAt = (path: string) => {
+  const router = createRouter({
+    routeTree,
+    history: createMemoryHistory({ initialEntries: [path] }),
+  });
+  return render(
+    <ThemeProvider brands={[keboola]} defaultBrandId={keboola.id} defaultScheme="light">
+      <RouterProvider router={router} />
+    </ThemeProvider>,
+  );
+};
+
+describe('/signed-out', () => {
+  it('renders without the app chrome', async () => {
+    renderAt('/signed-out');
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Sign in' })).toBeInTheDocument();
+    // The rail is the tell: a signed-out visitor must reach no destination in the app.
+    expect(screen.queryByRole('navigation', { name: 'Sections' })).not.toBeInTheDocument();
+  });
+
+  it('picks the state named by the search param', async () => {
+    renderAt('/signed-out?state=expired');
+
+    expect(
+      await screen.findByRole('heading', { level: 1, name: 'Session expired' }),
+    ).toBeInTheDocument();
+  });
+
+  it('falls back to the sign-in form for a state it does not know', async () => {
+    renderAt('/signed-out?state=nonsense');
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Sign in' })).toBeInTheDocument();
+  });
+});

package/dist/template/src/routes/signed-out.tsx

@@ -0,0 +1,31 @@
+import { createFileRoute, useNavigate } from '@tanstack/react-router';
+
+import { AuthScreen } from '../auth/AuthScreen';
+import type { AuthState } from '../auth/session';
+import { AUTH_ROUTE, AUTH_STATES, isAuthState } from '../auth/session';
+
+/**
+ * `/signed-out` — the pre-project screen.
+ *
+ * - `?state=` stands in for the session hook, so every state renders without a backend.
+ * - `validateSearch` narrows by hand: the block carries no validation dependency.
+ * - An unknown or missing `state` falls back to sign-in rather than throwing.
+ */
+export const Route = createFileRoute('/signed-out')({
+  validateSearch: (search: Record<string, unknown>): { state: AuthState } => ({
+    state: isAuthState(search.state) ? search.state : 'signed-out',
+  }),
+  component: SignedOutPage,
+});
+
+function SignedOutPage() {
+  const { state } = Route.useSearch();
+  const navigate = useNavigate();
+  const { title, body: Body } = AUTH_STATES[state];
+
+  return (
+    <AuthScreen title={title}>
+      <Body onRetry={() => void navigate({ to: AUTH_ROUTE, search: { state: 'signed-out' } })} />
+    </AuthScreen>
+  );
+}

package/dist/template/src/routes/tokens/$id.tsx

@@ -2,8 +2,8 @@ import { createFileRoute, Link } from '@tanstack/react-router';
 
 import { Breadcrumb, Button, ErrorState, PageHeader, PageLayout, Skeleton } from '@keboola/design';
 
-import { useToken } from './-hooks';
-import type { Token } from './-types';
+import { useToken } from '../../tokens/hooks';
+import type { Token } from '../../tokens/types';
 
 export const Route = createFileRoute('/tokens/$id')({
   component: TokenDetailPage,

package/dist/template/src/routes/tokens/{-index.test.tsx → index.test.tsx}

@@ -3,7 +3,7 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import type { Token } from './-types';
+import type { Token } from '../../tokens/types';
 
 // Render the page without a RouterProvider: mock the two router exports it uses
 // (`createFileRoute` returns the Route object; `Link` renders a plain anchor).
@@ -14,7 +14,7 @@ vi.mock('@tanstack/react-router', () => ({
 
 // Drive each async branch deterministically by mocking the query hook boundary.
 const { useTokensMock } = vi.hoisted(() => ({ useTokensMock: vi.fn() }));
-vi.mock('./-hooks', () => ({ useTokens: () => useTokensMock() }));
+vi.mock('../../tokens/hooks', () => ({ useTokens: () => useTokensMock() }));
 
 import { Route } from './index';
 

package/dist/template/src/routes/tokens/index.tsx

@@ -14,9 +14,8 @@ import {
 } from '@keboola/design';
 
 import { useAppStore } from '../../store';
-
-import { useTokens } from './-hooks';
-import type { Token } from './-types';
+import { useTokens } from '../../tokens/hooks';
+import type { Token } from '../../tokens/types';
 
 export const Route = createFileRoute('/tokens/')({
   component: TokensListPage,

package/dist/template/src/routes/tokens/new.tsx

@@ -13,8 +13,8 @@ import {
   toast,
 } from '@keboola/design';
 
-import { useCreateToken } from './-hooks';
-import { type CreateTokenInput, EXPIRY_OPTIONS, type TokenExpiry } from './-types';
+import { useCreateToken } from '../../tokens/hooks';
+import { type CreateTokenInput, EXPIRY_OPTIONS, type TokenExpiry } from '../../tokens/types';
 
 export const Route = createFileRoute('/tokens/new')({
   component: NewTokenPage,

package/dist/template/src/sections/kpi.tsx

@@ -6,11 +6,8 @@ import type { OverviewSection } from '../overview-sections';
 /** The overview's KPI row: one card per figure. */
 export const kpiSection: OverviewSection = {
   id: 'kpi',
-  // Reflows on this column's own width, not the viewport's. A `lg:grid-cols-4` here
-  // would keep four columns while the assistant rail squeezes the page to a third of
-  // it — the rail narrows content without changing the viewport, so viewport
-  // breakpoints lie. `auto-fit` + a `minmax` floor drops to three, two, then one
-  // column as room runs out.
+  // Reflows on column width, not viewport: the assistant rail narrows the page
+  // without changing the viewport, so `lg:` breakpoints would lie.
   render: (overview) => (
     <div
       data-section="kpi"
@@ -21,8 +18,7 @@ export const kpiSection: OverviewSection = {
       ))}
     </div>
   ),
-  // Four placeholders because four KPIs are coming — a skeleton that does not match
-  // the shape it stands in for makes the page jump on load.
+  // Four slots to match the four KPIs, so the page does not jump on load.
   renderSkeleton: () => (
     <div
       data-section-skeleton="kpi"

package/dist/template/src/slices/assistant.ts

@@ -9,11 +9,7 @@ type ChatMessage = {
 };
 
 export type AssistantSlice = {
-  /**
-   * One transcript for the whole app. The home page's prompt input and the rail's
-   * own composer both call `send`, so sending from the page is a handoff into the
-   * rail rather than a second, parallel conversation.
-   */
+  /** One app-wide transcript: the home prompt and the rail's composer both `send` into it. */
   messages: ChatMessage[];
   send: (text: string) => void;
   fullscreen: boolean;
@@ -53,10 +49,8 @@ export const createAssistantSlice: StateCreator<AppState, Mutators, [], Assistan
         messages: [
           ...s.messages,
           { id: crypto.randomUUID(), role: 'user', text },
-          // A canned reply, not a backend call — swap the whole branch for a
-          // real request. It answers in Markdown (including a ```mermaid fence)
-          // because that is what an assistant actually returns, and rendering
-          // that is the rail's job: see AssistantPanel.
+          // Canned stand-in for a backend call; Markdown with a ```mermaid fence,
+          // rendered by AssistantPanel.
           { id: crypto.randomUUID(), role: 'assistant', text: cannedReply(text) },
         ],
       }),

package/dist/template/src/slices/shell.ts

@@ -7,9 +7,7 @@ import type { AppState } from '../store';
 /**
  * The modes `sidebarMode` may hold, as a runtime value.
  *
- * - Keyed by `SidebarMode`, so adding a mode to the union fails the build here until
- *   it is listed — a hand-written array would silently start rejecting the new mode.
- * - The values carry nothing; the keys are the whole point.
+ * - Keyed by `SidebarMode`, so a new mode fails the build until it is listed here.
  */
 const SIDEBAR_MODES: Record<SidebarMode, true> = {
   expanded: true,
@@ -22,12 +20,8 @@ export const isSidebarMode = (value: unknown): value is SidebarMode =>
 
 export type ShellSlice = {
   /**
-   * The left rail's mode.
-   *
-   * - Lives here, not inside `SidebarProvider`, so it survives a reload; a layout
-   *   preference that resets reads as a broken control.
-   * - `AppChrome` drives the provider from it (`leftMode` + `onLeftModeChange`).
-   * - `SidebarModeMenu` is the UI that writes it.
+   * - Stored here, not in `SidebarProvider`, so it survives a reload.
+   * - `AppChrome` feeds it to the provider; `SidebarModeMenu` writes it.
    */
   sidebarMode: SidebarMode;
   setSidebarMode: (mode: SidebarMode) => void;
@@ -39,8 +33,7 @@ export type ShellSlice = {
 /**
  * The mutator tuple mirrors `store.ts`'s middleware stack, outside-in.
  *
- * - Without it `set` loses its third argument and every `set(partial, false, 'name')`
- *   call fails to type-check.
+ * - Without it `set(partial, false, 'name')` fails to type-check.
  */
 type Mutators = [['zustand/devtools', never], ['zustand/persist', unknown]];
 

package/dist/template/src/store.ts

@@ -16,18 +16,14 @@ export type AppState = ShellSlice &
   // #region block:assistant
   AssistantSlice &
   // #endregion block:assistant
-  // `unknown` is the identity for `&`, so the line above can go without leaving a dangling
-  // operator. The comment keeps this alias on three lines, which is what `oxfmt` expects of
-  // it in an app that dropped the middle term.
+  // - `unknown` is the identity for `&`, so the line above can go without a dangling operator.
+  // - This comment keeps the alias multi-line, as `oxfmt` expects once that line is gone.
   unknown;
 
 export const useAppStore = create<AppState>()(
   devtools(
-    // `persist` inside `devtools` so rehydration lands in the devtools timeline as an
-    // action. Only `sidebarMode` is written out — see `partialize`.
+    // `persist` inside `devtools` so rehydration shows in the devtools timeline.
     persist(
-      // Zustand's slice pattern: `(...a)` forwards `set`, `get` and the store API to
-      // each creator without naming the three of them per slice.
       (...a) => ({
         ...createShellSlice(...a),
         // #region block:assistant
@@ -36,26 +32,15 @@ export const useAppStore = create<AppState>()(
       }),
       {
         name: UI_SETTINGS_STORAGE_KEY,
-        // No `version` here on purpose. Zustand discards a record whose version does not
-        // match and no `migrate` covers, so a bare bump silently resets every returning
-        // visitor. If the stored shape ever changes, add `version` and `migrate` in the
-        // same change. A value that is merely unrecognised is `merge`'s job, below.
-        // The layout preference and nothing else. The default is the whole store, which
-        // would restore a stale transcript on reload and pin `fullscreen` open across
-        // sessions.
+        // - No `version`: a bump without `migrate` resets every stored record; add both together.
+        // - Layout only; the whole store would restore a stale transcript and pin `fullscreen`.
         partialize: (state) => ({ sidebarMode: state.sidebarMode }),
-        // Validate at the storage boundary instead of trusting what comes back.
-        // - `localStorage` is user-writable, and a value written by an older build
-        //   outlives the code that wrote it.
-        // - An unrecognised mode is not inert: `SidebarProvider` derives the rail's
-        //   `state` from it, no branch matches, so the rail sticks at icon width with
-        //   nothing checked in the mode menu — recoverable only by picking a mode.
-        // - Falling back to `current` means the in-memory default, so a junk value
-        //   reads exactly like a first visit.
+        // - Untrusted: `localStorage` is user-writable and outlives the build that wrote it.
+        // - An unknown mode sticks the rail at icon width, so junk falls back to the default.
         merge: (persisted, current) => {
           const stored: unknown =
-            typeof persisted === 'object' && persisted !== null
-              ? Reflect.get(persisted, 'sidebarMode')
+            typeof persisted === 'object' && persisted !== null && 'sidebarMode' in persisted
+              ? persisted.sidebarMode
               : undefined;
 
           return { ...current, sidebarMode: isSidebarMode(stored) ? stored : current.sidebarMode };

package/dist/template/src/{routes/tokens/-fixtures.test.ts → tokens/fixtures.test.ts}

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 
-import { createToken, fetchToken, fetchTokens, resetFixtures } from './-fixtures';
+import { createToken, fetchToken, fetchTokens, resetFixtures } from './fixtures';
 
 describe('fixtures', () => {
   beforeEach(() => {