@webjsdev/cli 0.10.38 → 0.10.39

package/templates/AGENTS.md

@@ -14,34 +14,51 @@ now (`app/page.ts` printing "Hello from {{APP_NAME}}", the example `User`
 model in `db/schema.server.ts`, the `theme-toggle` component, the
 example users module in api/saas templates) are **starting-point
 references, not the final product**. Your job is to replace them with
-the app the user actually asked for. That includes adapting
-`app/layout.ts`, not just the page. Set the real brand, replace the
-example `Home` nav, and pick a content-width container that fits. The
-default `<main class="max-w-[760px]">` is a reading column for prose and
-forms, so for a full-bleed app, dashboard, or board, widen the cap or
-remove it (keep the theme tokens). A wide layout left in the 760px
-reading column overflows into a horizontal scrollbar. **Give the app a
-unique design, and redesign means more than recolor.** When it has a UI,
-choose its palette, typography, LAYOUT, and chrome from what the app IS.
-Recoloring the scaffold and swapping the logo while keeping its skeleton (a
-fixed top header with a Home link and a theme toggle, the centered ~760px
-reading column, the "Built with webjs" footer) is NOT a unique design.
-Decide from scratch whether this app even needs a header or footer, what nav
-(if any), and what layout fits (a centered board, a full-bleed dashboard, a
-split, a single card). Before finishing, self-audit that nothing still reads
-as the scaffold example (no "Built with webjs" footer, no leftover example
-nav, no default reading column unless it truly fits). The `api` template has
-no UI, so this does not apply there. The design tokens and theme wiring are
-infrastructure to keep and restyle on top of. Style with Tailwind utilities
-wherever they reach, and use custom CSS only for what utilities cannot
-express (@theme tokens, @keyframes, scrollbar, complex color-mix or
-gradients). This is ENFORCED:
+the app the user actually asked for. That includes designing
+`app/layout.ts`, not just the page. It ships as a MINIMAL shell (theme,
+design tokens, and Tailwind infra, then `${children}` in a bare padded
+container) with NO header, nav, footer, or reading column, so design the
+app's own chrome from scratch. `LAYOUT-REFERENCE.md` at the project root is
+a complete worked layout (fixed header, brand, nav, theme toggle, reading
+column, footer) to learn the patterns from, then build your own. **Give the
+app a unique design, and redesign means more than recolor.** When it has a
+UI, choose its palette, typography, LAYOUT, and chrome from what the app IS.
+Decide whether it needs a header at all, a nav (or none), a footer, a
+sidebar, a centered reading column, or a full-bleed canvas (a centered
+board, a full-bleed dashboard, a split, a single card). The `api` template
+has no UI, so this does not apply there. The design tokens and theme wiring
+are infrastructure to keep and set your own palette VALUES on. Style with
+Tailwind utilities wherever they reach, and use custom CSS only for what
+utilities cannot express (@theme tokens, @keyframes, scrollbar, complex
+color-mix or gradients). This is ENFORCED:
 the example `app/page.ts` and `app/layout.ts` carry a
 `webjs-scaffold-placeholder` marker comment, and `webjs check` fails
 while any marker remains, so this freshly scaffolded app fails the check
 until you replace the example content (or deliberately keep it) and
-delete the marker line. The delivered app must contain only what the
-user asked for, never leftover scaffold code.
+delete the marker line. To keep the gallery and clear every marker at
+once, run `webjs check --clear-placeholders` (it strips the marker lines
+and keeps the demo code), then delete any demo you do not want. The
+delivered app must contain only what the user asked for, never leftover
+scaffold code.
+
+**Render the app and LOOK before you call UI work done (every agent, not
+just one harness).** You write CSS blind, so a layout or design defect
+ships silently: `webjs check` and `webjs typecheck` pass even when a
+component collapses, grid cells are uneven, the layout resizes as it fills,
+or the app just kept the scaffold's colors. Static tools give no failure
+signal for this. The only thing that catches it is rendering the app and
+looking at the pixels. So for ANY page, layout, or component work: run it
+(`webjs dev`), open every route you changed in a real browser (drive it
+with your harness's browser tool or MCP if it has one, otherwise open it
+yourself and screenshot), and PLAY THROUGH every state (empty, filled, win,
+draw, reload, narrow and wide, light and dark). Confirm nothing collapses
+or reflows, that cells stay equal, that the design is the app's OWN, and
+that both themes read. Ship a real-browser test (`webjs test --browser`)
+for the mechanical floor (measure `getBoundingClientRect()` and assert
+cells stay equal across a move). Fix and re-render until it holds, then
+state what you rendered and confirmed. Claude Code additionally ENFORCES
+this via the `webjs-design-review` skill plus a Stop hook, but the
+discipline is harness-agnostic and applies to every agent.
 
 **Non-negotiables for every webjs app:**
 

package/templates/CONVENTIONS.md

@@ -365,32 +365,58 @@ When the user asks the agent to build their actual app:
    `app/features/` demos and the `app/examples/` app the real app uses,
    delete the rest (route + module + any table), and remove their links
    from `app/page.ts`.
-5. **Adapt `app/layout.ts` to the app, not just the page.** Set the real
-   brand, replace the example `Home` nav with the app's navigation, and
-   pick a content-width container that fits. The default
-   `<main class="max-w-[760px]">` is a reading column for prose, forms,
-   and marketing. Widen it or drop the cap for a full-bleed app,
-   dashboard, or board, or a wide layout overflows into an unnecessary
-   horizontal scrollbar. Keep the design tokens and theme setup, those
-   are infrastructure.
+5. **Design the layout in `app/layout.ts` (it ships MINIMAL on purpose).**
+   The root layout wires the theme, design tokens, and Tailwind (keep all of
+   that), then drops `${children}` into a bare padded `<main>` with NO chrome.
+   There is no header, nav, footer, or reading column to inherit: design the
+   app's own from what the app IS. Decide from scratch whether it needs a
+   header at all, a nav (or none), a footer, a sidebar, a centered reading
+   column, or a full-bleed canvas. `LAYOUT-REFERENCE.md` at the project root is
+   a complete worked layout (fixed header, brand, nav, theme toggle, reading
+   column, footer) to learn the patterns from, then build your own. Keep the
+   design tokens and theme apparatus, those are infrastructure.
 6. **Use a unique design, and redesign means more than recolor (UI apps).**
    Give the app a design of its own (palette, typography, LAYOUT, spacing,
-   and chrome) chosen from what the app IS. Recoloring the scaffold and
-   swapping the logo while keeping its skeleton (a fixed top header with a
-   Home link and a theme toggle, the centered ~760px reading column, the
-   "Built with webjs" footer) is NOT a unique design. Decide from scratch
-   whether this app even needs a header or footer, what nav (if any), and
-   what layout fits (a centered board, a full-bleed dashboard, a split, a
-   single card). The scaffold ships a `webjs-scaffold-placeholder` marker on
-   its footer, so `webjs check` fails until you remove or replace the
-   "Built with webjs" branding. Self-audit before finishing: nothing should
-   read as the scaffold example (no "Built with webjs" footer, no leftover
-   example nav, no default reading column unless it truly fits). The design
-   tokens and theme wiring in `app/layout.ts` are infrastructure to keep and
-   restyle on top of, not the example look to preserve. Style with Tailwind
-   utilities wherever they reach, and use custom CSS only for what utilities
-   cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix
-   or gradients). The `api` template has no UI, so this does not apply there.
+   and chrome) chosen from what the app IS. The layout ships MINIMAL (see item
+   5), so there is no scaffold skeleton to inherit: build the chrome the app
+   actually needs. Two things are gated by a `webjs-scaffold-placeholder`
+   marker, so `webjs check` fails until each is addressed: the minimal shell
+   carries a "design your layout from scratch" marker (delete it once you have
+   built a real layout), and the palette block carries its own marker (the
+   starter orange looks finished on purpose). The design token NAMES and theme
+   wiring (`--background`, `--primary`, `--card`, ... in `app/layout.ts`) are
+   infrastructure to keep, but their COLOR VALUES are yours: set a distinctive
+   palette that fits the app, in both the light and dark blocks. Keeping the
+   scaffold's token colors (or a light warm recolor of them) is NOT owning the
+   palette. To keep the starter palette deliberately, run
+   `webjs check --clear-placeholders`. Style with Tailwind utilities wherever
+   they reach, and use custom CSS only for what utilities cannot express (@theme
+   tokens, @keyframes, scrollbar, complex color-mix or gradients). The `api`
+   template has no UI, so this does not apply there.
+   **Size the component HOST, not just an inner wrapper.** A component's host
+   custom element is the box its parent lays out. Hosts default to
+   `display: block`, but a host that is a flex/grid item in a centering parent
+   (`flex justify-center`, `grid place-items-center`) is still sized to its
+   content unless it carries width itself. Put `w-full max-w-[...]` on the host,
+   not only on an inner `<div>` (an inner `w-full` resolves against a collapsed
+   host and the whole component renders tiny). If a board or card renders small
+   despite `w-full max-w-[400px]` on its inner grid, move that sizing to the host.
+   **Definition of done (design gate):** a UI app is NOT finished until you
+   have (a) given it a design of its own (layout AND palette) and removed the
+   scaffold shell, (b) run it and PLAYED THROUGH every state in a browser
+   (fill the board, win, draw, reload), confirming nothing resizes or shifts as
+   it fills (even, stable squares) and it does not resemble the scaffold, and
+   (c) confirmed it still reads AND looks right with JavaScript OFF (SSR +
+   progressive enhancement): content shows, links navigate, forms submit, and
+   the CSS is fully applied (the app links a static compiled `public/tailwind.css`,
+   so utilities resolve with no JS). A
+   glance at the empty first paint is not enough; the layout bugs show up
+   mid-interaction.
+   `webjs doctor` emits an advisory when `app/layout` still reproduces scaffold
+   design (the exact 760px reading column, the "Built with webjs" attribution, or
+   the unmodified starter palette values); the kept theme apparatus (theme-toggle,
+   `--header-h`) is infrastructure and does NOT trip it. Treat the advisory as a
+   to-do, not noise.
 7. **Keep:** the Drizzle setup, the test config, the agent config files
    (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
    `db/connection.server.ts` + `db/columns.server.ts`, the directory
@@ -406,7 +432,9 @@ freshly scaffolded app fails `webjs check` until you address each
 placeholder. The marker is acknowledge-and-remove: replace the example
 content, or deliberately keep it, and in either case delete the marker
 line. So the delivered app contains only what the user asked for, never
-leftover scaffold code.
+leftover scaffold code. To keep the gallery and clear every marker in one
+step (instead of one edit per file), run `webjs check --clear-placeholders`,
+then delete whichever demo routes/modules you do not want.
 
 The scaffold exists so the agent doesn't reinvent the directory layout,
 the Drizzle wiring, the test runner config, or the convention files. It
@@ -800,10 +828,13 @@ Both hydrate without flash on the client.
 
 <!-- OVERRIDE -->
 
-The scaffold ships with the **Tailwind CSS browser runtime** + `@theme`
-design tokens defined in the root layout. Every colour, font family,
-fluid type scale value, and motion duration is declared once in `@theme`
-and available everywhere via utility classes (`text-foreground`,
+The scaffold compiles a **static Tailwind stylesheet** (`css:build` builds
+`public/input.css` into the `public/tailwind.css` the layout links, so the
+app is styled with JavaScript off) + `@theme` design tokens. The token
+VALUES live on `:root` in the root layout (plain CSS, JS-off safe); the
+`@theme` maps live in `public/input.css`. Every colour, font family,
+fluid type scale value, and motion duration is declared once and
+available everywhere via utility classes (`text-foreground`,
 `bg-card`, `font-serif`, `duration-fast`, `text-display`).
 
 **One theme, canonical tokens.** The app has a SINGLE theme, defined

package/templates/LAYOUT-REFERENCE.md

@@ -0,0 +1,96 @@
+# Layout reference
+
+`app/layout.ts` ships as a **minimal shell**: it wires the theme, design tokens,
+and the linked static Tailwind stylesheet, then renders `${children}` in a bare full-height
+container with no chrome. That is on purpose. A delivered app should design its
+own layout from what the app IS, not inherit a generic header and footer.
+
+This file is the **reference** for how to build a real layout: read it to learn
+the patterns (a fixed header, a brand mark, a nav, a theme toggle, a reading
+column, a footer), then write the layout your app actually needs in
+`app/layout.ts`. Decide from scratch: does a tic-tac-toe game want a header at
+all? Does a dashboard want a sidebar instead? Does a landing page want a
+full-bleed hero? Keep only what fits.
+
+> **This is ONE example, not a template to reproduce.** Reproducing this exact
+> header (a slim bar with a mark on the left and a theme toggle on the right)
+> just recreates the old scaffold look under a new name. It is here to show the
+> mechanics (how a header, nav, theme toggle, or footer are wired), not the
+> design. Design a layout that fits what THIS app is: a game might be a
+> full-bleed centered stage with no header; a tool might have a compact command
+> bar; a reader might have a wide sidebar. Take the mechanics, invent the form.
+
+You do not import from this file. Copy the mechanics you want into
+`app/layout.ts`'s returned template, inside the `<main>` (or replacing it), and
+restyle them into your own design.
+
+## A complete worked layout
+
+This is the chrome the scaffold used to ship inline. It goes in the body of
+`RootLayout`, after the `<script>`/`<style>` infrastructure blocks. `navLink` is a
+small SSR helper you would declare above `RootLayout`.
+
+```ts
+// Declare above RootLayout: a nav-link helper (SSR-time, no client runtime).
+const navLink = (href: string, label: string) => html`
+  <a href=${href} class="text-muted-foreground no-underline font-medium text-[13px] leading-none tracking-[0.005em] transition-colors duration-fast hover:text-foreground">${label}</a>
+`;
+
+// Inside RootLayout's returned html``, in place of the minimal <main>:
+
+// A fixed header (NOT sticky: a sticky header flickers on iOS WebKit during a
+// client-router nav). --header-h reserves its height for the content below; the
+// header-measure script already in app/layout.ts sets --header-h to the real
+// height the moment a <header> exists.
+<header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--background)_75%,transparent)] backdrop-blur-[18px]">
+  <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-foreground font-semibold text-[15px] leading-none tracking-tight">
+    <!-- Your brand or logo mark goes here. A glyph, a wordmark, the real product name. -->
+    <span>{{APP_NAME}}</span>
+  </a>
+  <nav class="flex gap-4 items-center">
+    <!-- Your app's real navigation (or drop the nav entirely for a single-page app). -->
+    ${navLink('/', 'Home')}
+    <theme-toggle></theme-toggle>
+  </nav>
+</header>
+
+// A content shell. The max-w-[760px] cap is a comfortable READING width, right
+// for prose, forms, and marketing. For a full-bleed app, dashboard, or board,
+// widen the cap (for example max-w-[1400px]) or drop the cap and mx-auto for an
+// edge-to-edge layout. A wide layout left in the 760px column overflows into a
+// horizontal scrollbar.
+<div class="flex flex-col min-h-[calc(100dvh-var(--header-h))]">
+  <main class="flex-1 w-full max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12">
+    ${children}
+  </main>
+  <!-- Your footer. Do NOT ship a "Built with webjs" footer: write your app's own. -->
+  <footer class="border-t border-border">
+    <div class="max-w-[760px] mx-auto px-4 sm:px-6 py-6 flex items-center justify-center">
+      <span class="text-sm text-muted-foreground">Your footer</span>
+    </div>
+  </footer>
+</div>
+```
+
+## The `theme-toggle` element
+
+The scaffold ships `components/theme-toggle.ts` (already imported by
+`app/layout.ts` as a side effect, so the element is registered). Place
+`<theme-toggle></theme-toggle>` wherever you want the light/dark switch, or delete
+the import and the theme apparatus in `app/layout.ts` for a single-theme app.
+
+## What stays in `app/layout.ts` no matter what
+
+The infrastructure above the `<main>` is not chrome and should stay:
+
+- the theme-detection `<script>` (light/dark apparatus) and the header-measure
+  script,
+- the `<link rel="stylesheet" href="/public/tailwind.css">` (the STATIC stylesheet
+  compiled from `public/input.css` by `css:build`, so the app is styled with JS
+  off),
+- the `<style>` block of design-token VALUES (`:root` / dark / light), which
+  carries its own `webjs-scaffold-placeholder` marker, so own the colors. The
+  Tailwind `@theme` maps that turn those tokens into utilities live in
+  `public/input.css`.
+
+Design the chrome; keep the plumbing.