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

package/guidelines/cssRule/cssRule.instruction.md

@@ -55,6 +55,13 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 - Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
 - Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes).
 
+## Lib-Owned Tokens (`libs/<lib>/ui/tokens.css`)
+- A lib that needs colors of its own — vendor brand colors pinned by someone else's guide (Kakao `#fee500`, Naver `#1ec800`), fixed in-game surfaces — declares them **once** in `libs/<lib>/ui/tokens.css`. Never copy the block into each app's stylesheet.
+- The file is collected automatically: every app whose page graph reaches that lib compiles it, ordered **ahead of** the app's own stylesheets, so the app wins on any variable both declare. There is nothing to import and no sync step to remember; two libs both declaring one variable resolve in lib-name order, so do not rely on that.
+- Declare plain custom properties under `:root`, not a Tailwind `@theme` extension: the color vocabulary is closed per stylesheet, so `bg-kakao` would generate no CSS. Reference them as `bg-[var(--kakao)]` / `text-[var(--kakao-foreground)]`, which `no-arbitrary-color` allows by design (a `var()` reference is not an arbitrary color literal).
+- Theme-following colors still belong to the app: a lib token is for a color that must **not** change with `data-theme`.
+- An `@import` the CSS pipeline cannot resolve fails the build; it is never dropped. A stylesheet under `page/` that no route imports is compiled by nothing and warns at build time.
+
 ## Codegen Rules
 - Do not hardcode hex or raw-palette colors (`bg-red-500`, `#ff0000`); use semantic tokens.
 - Do not put inline color literals in `style={{ }}`; use token classes.

package/guidelines/framework/framework.instruction.md

@@ -26,6 +26,7 @@ Use this as the compact framework context for AI codegen. It should explain how
 When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
 
 - **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
+- **Lib tokens (`libs/<lib>/ui/tokens.css`).** Colors a lib's own components pin — a vendor brand color, a fixed surface — are declared once there as plain `:root` custom properties and compiled into every app that reaches the lib, ahead of the app's stylesheets. Reference them as `bg-[var(--kakao)]`; never copy the block into each app.
 - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
 
 ## Review Checklist

package/guidelines/ssrRule/ssrRule.generate.json

@@ -0,0 +1,31 @@
+{
+  "title": "SSR Rule",
+  "description": "Akan SSR-first rendering rules — keep JSX on the server and justify every client boundary",
+  "group": "core",
+  "codegenPriority": 3,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Client boundary shells that render server children untouched",
+      "path": "{apps,libs}/*/ui/**/*.tsx",
+      "sample": 4
+    },
+    {
+      "type": "example",
+      "description": "Module UI split across client Zone/Template/Util and server Unit/View",
+      "path": "{apps,libs}/*/lib/*/*.tsx",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./ssrRule.instruction.md",
+    "contents": ["purpose", "when a client boundary is earned", "quality rules", "implementation playbook"],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Name the akan.ssr.* rule ids the quality scanner emits",
+      "Ground every pattern in a file that exists in the workspace"
+    ]
+  }
+}

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -0,0 +1,108 @@
+# 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/guidelines/workspaceOnboarding/workspaceOnboarding.generate.json

@@ -0,0 +1,24 @@
+{
+  "title": "Workspace Onboarding",
+  "description": "Product-workspace orientation — layout, decision matrix, workflow recipes, and query gotchas",
+  "group": "core",
+  "codegenPriority": 2,
+  "deprecated": false,
+  "scans": [],
+  "update": {
+    "filePath": "./workspaceOnboarding.instruction.md",
+    "contents": [
+      "workspace layout and generated files",
+      "agent workflow and common commands",
+      "where-do-I-put-this decision matrix",
+      "workflow recipes",
+      "modeling and query gotchas"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Write for someone building a product on Akan, not for someone changing Akan",
+      "Refer to the app as <%= appName %>; the renderer substitutes the workspace's first app",
+      "Do not repeat a rule that the conventions guideline already states"
+    ]
+  }
+}