@akanjs/cli 3.0.0-alpha.3 → 3.0.0-alpha.4

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -1,108 +0,0 @@
-# Akan SSR Rule Guideline
-
-## Purpose
-Use this when writing or reviewing any `.tsx` file. Akan is SSR-first: an element rendered on the server ships as
-HTML and costs nothing to hydrate, while an element behind `"use client"` ships twice — as markup and as bundled JS
-that re-runs in the browser. The boundary question is never "may this file be client", it is **how little ends up
-on the client side**.
-
-## When A Client Boundary Is Earned
-- A component earns `"use client"` only by using a client-only capability: a React hook, a JSX event handler, the
-  store (`st.use.*` / `st.do.*`), a browser global (`window`, `document`, `navigator`, `localStorage`, …), or a
-  client-only third-party package.
-- Rendering markup, mapping over data, reading a route param, and calling `l()` are server work. `usePage()` and
-  `getSelf()` are legal in server components and never force a boundary.
-- In domain UI the file role fixes the directive: `Template`, `Zone`, and `Util` are client; `Unit` and `View` are
-  server. That decides *where* the boundary sits, not how much markup sits behind it — a `Zone` that hoards markup
-  is still an SSR regression.
-- Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and
-  lib as server-rendered JSX elements over total. Treat **50% server share as the floor** and a falling share as a
-  regression to justify or revert.
-
-## Quality Rules
-- `akan.ssr.unnecessary-use-client` — the directive is present but nothing in the file needs it. Delete it. If the
-  file exists only to wrap one client child, drop the wrapper and use the child directly.
-- `akan.ssr.client-static-component` — a component inside a client file renders real markup with zero client-only
-  capability. Move it to a server file: a `<Model>.Unit.tsx` / `<Model>.View.tsx` for a module, or a `ui/` file with
-  no directive.
-- `akan.ssr.client-static-markup` — a large subtree wraps one or two interactive touches. Keep the interactive
-  element in the client component and hoist the static subtree into a server component received as `children`.
-- `akan.ssr.client-mount-load` — a `useEffect(…, [])` loads server data. Fetch it in the route and pass the
-  init/view object down.
-- `akan.ssr.module-missing-server-view` — a module renders only from `Template`/`Zone`/`Util` and declares no
-  `Unit`/`View`. Add them and have the `Zone` delegate.
-- `akan.ssr.template-client-state` — a `Template` holds form state in `useState`. Bind to the store instead:
-  `value={xForm.field}` with `onChange={st.do.setFieldOnX}`.
-
-A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundary both justify the directive and are
-not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are,
-because those are the ones the server could have performed.
-
-## Implementation Playbook
-
-**① Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
-`children` untouched, so the markup inside never reaches the bundle.
-
-```tsx
-"use client";
-export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => <div onClick={onPick}>{children}</div>;
-```
-
-`libs/shared/ui/Only/User.tsx` is the same shape: it reads auth state on the client and returns `{children}`.
-
-**② Split compound components so panels stay on the server.** A tab, accordion, or disclosure needs client state
-only for *which* part is visible, never for what the parts contain. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`
-in `akanjs/ui` is the reference: only the provider and menu hold state, and `<Tab.Panel>` renders its children
-as-is, so a server `Unit`/`View` passed in stays server-rendered.
-
-```tsx
-<Tab defaultMenu="detail">
-  <Tab.Menus>
-    <Tab.Menu menu="detail">{l("post.detail")}</Tab.Menu>
-    <Tab.Menu menu="history">{l("post.history")}</Tab.Menu>
-  </Tab.Menus>
-  <Tab.Panel menu="detail">
-    <Post.View.General post={post} />
-  </Tab.Panel>
-</Tab>
-```
-
-Never collapse this into one client file with a mode `useState` and every panel body inlined.
-
-**③ Sync state instead of fetching it.** A server component cannot hold state, so render the initial data on the
-server and hand it across as a serializable object. The route calls `fetch.initXInY(...)` / `fetch.viewX(...)` and
-passes the result into a `Zone`; `Load.Units` / `Load.View` hydrate the store from it. A `useEffect(…, [])` that
-fetches on mount renders an empty shell, hydrates, then round-trips for data the server already had.
-
-**④ Push the boundary down to the leaf that needs it.** A store-reading `Zone` should hold zero markup and delegate
-to a server `View` — `User.Zone.Self` is one line, `st.use.self()` into `<User.View.General user={self} />`, so the
-whole detail surface renders server-side wherever a route uses the `View` directly.
-
-**⑤ Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
-route may pass an unawaited `fetch.initX(...)` and `Load.*` resolves it behind a skeleton. `await` blocks the shell
-for data the page needs immediately; the promise streams the rest. Independent fetches still go through one
-`Promise.all`.
-
-**⑥ Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` accepts `title`, `back`, `left`, `right`,
-and `children`, so a client shell composes server-rendered content in five places instead of absorbing it.
-
-**⑦ Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>` (`isNew()`,
-`canWrite(user?)`, `formatTimes()`), and enum→class lookups belong in a module-scope `as const` map. Both sides call
-the same method, so a client component that exists only to compute a label is markup in the wrong place.
-
-**⑧ Gate auth on the server.** `getSelf({ unauthorize: "/signin" })` in `_layout.tsx` redirects before any HTML is
-sent. A client-side check costs a hydration round-trip and flashes the wrong UI first.
-
-**⑨ Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants (see
-`libs/util/ui/Grid/*`) or `<details>`/`<summary>` keeps both branches server-rendered. Reach for `useState` when the
-state is real, not when a Tailwind variant would do.
-
-**⑩ Keep the heavy island out of the first load.** A large client-only widget goes behind the
-`ui/<Folder>/index_.tsx` + `lazy()` pair so the server renders the page around it.
-
-## Review Checklist
-- Does every `"use client"` in the diff name a capability that requires it?
-- Does each client component hold only interaction, with markup delegated to `children`, a slot prop, or a
-  `Unit`/`View`?
-- Is initial data fetched in the route and passed as `init`/`view`, with no mount-only load effect?
-- Did `akan quality ssr` hold or improve the server share for every touched app and lib?

package/templates/workspaceRoot/.cursor/rules/ssr-first.mdc.template

@@ -1,59 +0,0 @@
----
-description: SSR-first rendering rules — keep JSX on the server and justify every "use client"
-globs: apps/**/*.tsx,libs/**/*.tsx
-alwaysApply: false
----
-
-# SSR First — Server Rendering Is The Default
-
-Akan is SSR-first. A JSX element rendered on the server ships as HTML and costs nothing to hydrate; an element
-behind `"use client"` ships twice — as markup and as bundled JS that re-runs in the browser. The boundary question
-is not which file *may* be client, it is **how little** ends up on the client side.
-
-- **The default is server. `"use client"` is a cost you justify per component, not a habit.** A component earns the
-  directive only by using a client-only capability: a React hook, a JSX event handler, the store (`st.use.*` /
-  `st.do.*`), a browser global, or a client-only third-party package. Rendering markup, mapping over data, reading a
-  route param, and calling `l()` are server work — `usePage()` and `l()` never force a boundary.
-- The file role decides *where* the boundary sits (`Template`/`Zone`/`Util` are client, `Unit`/`View` are server);
-  it does not decide how much markup sits behind it. A `Zone` that hoards markup is still an SSR regression.
-- Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and lib.
-  Treat **50% server share as the floor** and a falling share as a regression to justify or revert.
-
-## What `akan quality ssr` Flags
-
-- `akan.ssr.unnecessary-use-client` — the directive is there but nothing in the file needs it. Delete it.
-- `akan.ssr.client-static-component` — a component in a client file renders real markup with zero client-only
-  capability: pure server work sitting in the bundle.
-- `akan.ssr.client-static-markup` — a large subtree wraps one or two interactive touches. Split it.
-- `akan.ssr.client-mount-load` — a `useEffect(…, [])` loads server data the page could fetch first.
-- `akan.ssr.module-missing-server-view` — a module renders only from `Template`/`Zone`/`Util`, with no `Unit`/`View`.
-- `akan.ssr.template-client-state` — a `Template` holds form state in `useState` instead of the store.
-
-A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundary both justify the directive and are
-not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are.
-
-## Server-Side Implementation Playbook
-
-1. **Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
-   `children` untouched, so the markup inside never reaches the bundle:
-   `export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => <div onClick={onPick}>{children}</div>;`
-2. **Split compound components so panels stay on the server.** A tab or accordion needs client state only for
-   *which* part is visible. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel` from `akanjs/ui` is the shape: only the
-   provider and menu hold state, and `<Tab.Panel>` renders children as-is, so a server `Unit`/`View` passed in stays
-   server-rendered. Never one client file with a mode `useState` and every panel body inlined.
-3. **Sync state instead of fetching it.** The page calls `fetch.initTaskInTodo()` / `fetch.viewTask(id)` and passes
-   the serializable result into a `Zone`; `Load.Units` / `Load.View` hydrate the store from it. Never a
-   `useEffect(…, [])` that fetches on mount.
-4. **Push the boundary down to the leaf that needs it.** A store-reading `Zone` holds zero markup and delegates to a
-   server `View`: `export const Self = () => <Task.View.General task={st.use.task()} />;`
-5. **Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
-   page may pass an unawaited `fetch.initTaskInTodo()` and `Load.*` resolves it behind a skeleton.
-6. **Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` takes `title`, `back`, `left`, `right`, and
-   `children`, so a client shell composes server content in five places.
-7. **Let the server do the derived work.** Display and predicate logic lives on `LightTask` (`isNew()`,
-   `canWrite(user?)`); enum→class lookups live in a module-scope `as const` map.
-8. **Gate auth on the server.** Check the session in `_layout.tsx` and redirect there, before any HTML is sent.
-9. **Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
-   `<details>`/`<summary>`, keeps both branches server-rendered.
-10. **Keep the heavy island out of the first load.** Put a large client-only widget behind the
-    `ui/<Folder>/index_.tsx` + `lazy()` pair.