@sudajs/cli 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -33,7 +33,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "6.7.0"
+    "@sudajs/theme-engine": "6.9.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -1,326 +1,21 @@
-# Suda Theme Agent Guide
+# Suda Theme Project Rules
 
 This repository is a standalone Vite + React + Tailwind Suda theme generated by
-`suda theme init`. Build a complete, publishable theme with theme-specific
-sections, realistic templates, scoped styling, assets, and AI metadata.
+`suda theme init`.
 
-## Required reading
+Install the reusable Suda theme development skill at the repository or
+monorepo root before implementing theme work:
 
-Read this file before every task. Then read the matching focused guide before
-editing that area. These guides are part of the contract, not optional
-background:
-
-| Task                                                                                                          | Required guide                               |
-| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| Sections, fields, defaults, menus, icons, AI metadata, or block slots                                         | `docs/agent-guides/component-authoring.md`   |
-| CMS, posts, starter pages, page data, or locales                                                              | `docs/agent-guides/templates-and-locales.md` |
-| Header, Footer, PageOutlet, sticky/fixed UI, transparent navigation, carousel, editor CSS, or client behavior | `docs/agent-guides/editor-compatibility.md`  |
-| Theme contract, layout, design tokens, CSS, assets, or contact forms                                          | `docs/agent-guides/design-and-runtime.md`    |
-
-Read every guide that applies when a change crosses concerns. Follow the
-generated types and installed package APIs when they are more specific than an
-example. Do not guess contracts from memory.
-
-## Non-negotiable rules
-
-- Keep `renderMode: "ssr"` and export a complete `ThemeModule` from
-  `src/index.tsx`: `manifest`, `pageConfig`, `layoutConfig`, `defaultLayout`,
-  `starterPages`, and `cmsTemplates`.
-- Keep page sections in `pageConfig` and shared chrome in `layoutConfig`.
-  Header and Footer render exactly once from the layout, with `PageOutlet`
-  between them.
-- Create theme-specific sections. Do not register `createEngineComponents()`,
-  `createBaseBlocks()`, or `createContainers()` as the theme's page sections.
-  Suda adds its generic content blocks separately.
-- Keep persisted props JSON-serializable. Never store functions, React nodes,
-  class instances, media database ids, or absolute local filesystem paths.
-- All normal field and prop defaults belong only in component `defaultProps`.
-  Never invent display defaults inside render code with `||`, `??`, a ternary,
-  a default function parameter, or a destructuring default.
-- Every editor-facing label must use `t(...)` and exist in
-  `src/locales/en.json`. Public content and `defaultProps` must not use the
-  editor translation helper.
-- Every page and layout component must declare useful `ai.instructions`.
-- Top-level page data types must be public keys from `pageConfig.components`,
-  and every top-level item must have a stable `props.id`.
-- Block-slot items use short local kinds such as `"button"`; never author
-  `__suda_local_block__/...` types or local-block ids.
-- Theme assets use `themeAsset("assets/...")` in authored data and
-  `resolveAsset(...)` when rendering editable media. Never hand-write published
-  theme asset URLs.
-- Keep theme CSS scoped. Do not use global resets or vendor edits that can
-  damage the Puck editor.
-- Do not edit `dist/`; regenerate it through the build.
-
-## Project structure
-
-Keep every page section in its own `.tsx` file. Do not collect multiple section
-configs and render implementations in a single `sections.tsx`, `config.tsx`, or
-other large module. Use kebab-case names and a small `src/sections/index.ts` to
-export configs or assemble the registry.
-
-```txt
-src/
-  sections/
-    hero.tsx
-    booking.tsx
-    values.tsx
-    faq-directory.tsx
-    review-marquee.tsx
-    index.ts
-```
-
-Keep section-specific prop types and tightly coupled helpers with their section.
-Extract shared code only when multiple sections genuinely reuse it.
-
-## Component fundamentals
-
-- Name public component keys with concise PascalCase visitor-facing patterns,
-  such as `HeroImage`, `FeatureCards`, or `TestimonialsCarousel`. Avoid theme
-  names and filler suffixes such as `Section`, `Component`, `New`, or `Custom`.
-- Prefer semantic variant names. Use numbered variants only when the variants
-  truly share a purpose and no concise name describes the difference.
-- Every page section must declare `section.motion`. Use `"reveal"` for ordinary
-  sections that use the shared viewport entrance animation. Use `"custom"` when
-  the section owns its own client animation (timeline, carousel, marquee, or
-  scroll-scrub), and use `"none"` when it must remain static. TypeScript will
-  report an error when the motion declaration is missing.
-- Keep `fields`, TypeScript props, `defaultProps`, and `render` aligned. Every
-  normal field needs a sensible serializable default.
-- Use the most specific field: `url`, `image`, `video`, `media`, `icon`,
-  `color`, `range`, `spacing`, `posts`, `select`, `radio`, `array`, or `object`.
-  Do not model structured or semantic values as generic text.
-- Use `visibleIf` for synchronous sibling-dependent visibility. Use
-  `resolveFields` only when `visibleIf` cannot express the behavior.
-- Expose a `columns` prop for multi-column grids and lists.
-- Use ordinary fields for scalar and structured props. Use `blockSlots` only
-  for controlled nested items editors and AI may add, remove, or reorder.
-- Native Puck slots are reserved for layout/container primitives. Page sections
-  must not declare native `slot` fields, legacy DropZones, or `zones`.
-
-Default ownership is strict:
-
-```tsx
-// Wrong: render invents content.
-<div>{val || "defaultValue"}</div>;
-
-// Correct: defaultProps owns the default.
-export const Example: SudaSectionConfig<ExampleProps> = {
-  section: { category: "features", variant: "example", motion: "reveal" },
-  fields: { val: { type: "text", label: t("sections.example.fields.val") } },
-  defaultProps: { val: "defaultValue" },
-  render: ({ val }) => <div>{val}</div>,
-};
+```bash
+suda theme skill add
 ```
 
-Conditional rendering is valid when absence intentionally removes optional UI;
-it must not substitute placeholder copy, labels, links, icons, or menu items.
-
-## Icons
-
-- Fixed icons are acceptable for interaction and UI-state semantics such as
-  menu, close, previous/next, expand/collapse, and loading controls.
-- Content icons such as feature, service, contact-method, and social-brand
-  icons are props. Expose `{ type: "icon" }`, type values as `SudaIconName`,
-  set initial selections in `defaultProps`, and render them with `SudaIcon` from
-  `@sudajs/theme-engine/icons`. Do not hardcode content icons in `render`.
-- Use canonical Lucide names such as `"rocket"` and namespaced Simple Icons
-  names such as `"simple-icons:github"`. The theme engine supports both; do not
-  add another icon library unless neither can represent a required icon.
-
-## Page data fundamentals
-
-- Wrap hand-authored page data with `defineSudaPageData(pageConfig, data)` when
-  practical so TypeScript checks public component keys and block-slot kinds.
-- Starter pages live in `src/templates.ts`, use `root: { props: {} }`, contain
-  realistic content, and include one home page with `isHome: true`.
-- Provide exactly the four CMS templates `posts`, `post`, `tags`, and `tag` as
-  `{ title, data }` entries. Do not invent CMS template variants.
-- CMS-only main sections read `getCmsContent(puck?.metadata)`. Ordinary page
-  post sections use one top-level `posts` field and `getPostResource(...)`.
-- Starter page slugs preview at root-like routes such as `/index` and
-  `/contact-us`; never use `/pages/...` as a preview prefix.
-
-## Editor and runtime fundamentals
-
-- Components return one stable semantic real DOM root when positioning,
-  selection, spacing, or background matters. Do not rely on a Fragment or
-  `display: contents` for such roots.
-- Derive editor state from `puck?.metadata?.isEditor === true`, expose a stable
-  theme-root marker, and scope editor fixes below it.
-- Puck may place `data-puck-component` and inline `position: relative` on the
-  component's actual root. Account for that before implementing sticky, fixed,
-  absolute, overlap, or transparent navigation behavior.
-- Do not restore pointer events globally in edit mode. Test interactions in
-  editor preview and on the public site.
-- Browser setup belongs in an optional `clientHooks` export from
-  `src/client.ts`. Do not create `src/runtime.client.ts(x)`; the CLI owns the
-  generated runtime.
-
-## Design and assets
-
-- Define one editable design system in `sourceManifest.designSystem`, expose it
-  at the layout root, resolve it once there, and render components through the
-  resulting unprefixed CSS variables. Do not add or consume `--suda-*` aliases.
-- Set `tokens.layout.contentWidth` in every preset in `src/manifest.ts`. Choose only
-  `"1024px"`, `"1200px"`, `"1280px"`, or `"1440px"`:
-
-  ```ts
-  tokens: {
-    colors: { /* ... */ },
-    radius: { /* ... */ },
-    layout: { contentWidth: "1280px" },
-  }
-  ```
+The installed `sudacloud-theme` skill contains the section, collection, CMS,
+design system, editor compatibility, localization, and verification guidance.
 
-- Configure the three font slots in every preset's `tokens`. Use font IDs, not
-  display names:
-
-  ```ts
-  typography: {
-    heading: "inter",
-    body: "noto-sans-sc",
-    mono: "jetbrains-mono",
-  },
-  ```
-
-  Read available IDs from `SUDA_THEME_FONT_FAMILIES`. System fonts such as
-  `system-sans`, `microsoft-yahei`, and `songti-sc` do not make network requests.
-
-- Connect the design system field in the layout root's `fields` and
-  `defaultProps`:
-
-  ```tsx
-  fields: {
-    designSystem: designSystemField(t("layout.root.fields.designSystem"), sourceManifest.designSystem),
-  },
-  defaultProps: {
-    designSystem: createThemeDesignDefault(sourceManifest.designSystem),
-  },
-  ```
-
-- Use the resolved CSS variables for theme typography:
-
-  ```css
-  .my-theme-root {
-    font-family: var(--font-sans);
-  }
-
-  .my-theme-root h1,
-  .my-theme-root h2,
-  .my-theme-root h3,
-  .my-theme-root h4,
-  .my-theme-root h5,
-  .my-theme-root h6 {
-    font-family: var(--font-heading);
-  }
-
-  .my-theme-root code,
-  .my-theme-root pre {
-    font-family: var(--font-mono);
-  }
-  ```
-
-- In the layout root, resolve the selected preset and apply its CSS variables
-  to the element that wraps `children`. Use this exact pattern:
-
-  ```tsx
-  render: ({ children, designSystem }) => {
-    const tokens = resolveThemeDesignTokens(sourceManifest.designSystem, designSystem);
-    return (
-      <div
-        className="my-theme-root"
-        style={createThemeDesignCssVariables(tokens)}
-      >
-        {children}
-      </div>
-    );
-  },
-  ```
-
-- Do not set `max-width` on the layout root or `PageOutlet`; doing so prevents
-  full-width sections. Apply `--content-max-width` only to inner content
-  containers. Wrap Header and Footer contents in that same container when they
-  must align with page sections.
-
-- Every page section root must include `w-full`. Put the section background,
-  border, and full-bleed media on this root. Do not set `max-width` on it.
-- Put normal section content inside one shared container class and define that
-  class once in `src/styles.css`:
-
-  ```css
-  .my-theme-container {
-    width: min(var(--content-max-width), 100%);
-    margin-inline: auto;
-  }
-  ```
-
-- Use the same container inside full-width Hero and band sections when their
-  text, buttons, cards, or navigation must align with ordinary sections. Omit
-  the inner container only when the section content itself must be edge to
-  edge. Do not repeat `1024px`, `1200px`, `1280px`, or `1440px` in section CSS.
-- `--background` / `--foreground`: default page surface and readable default
-  content. `--primary` / `--primary-foreground`: main brand and action surface
-  plus readable content on it. `--secondary` / `--secondary-foreground`:
-  supporting surface plus its content; it is not assumed light or dark.
-- `--accent` / `--accent-foreground`: high-attention emphasis, selection, or
-  decorative surface plus its content, not a default CTA substitute.
-  `--muted` / `--muted-foreground`: subdued surface and secondary text/icons.
-  Always pair a chosen surface with its corresponding foreground token.
-- `--radius` is the generic fallback; use `--radius-card`,
-  `--radius-button`, and `--radius-input` for cards, command buttons, and form
-  controls. Tailwind token mappings use `@theme inline`; hand-written CSS may
-  consume these variables directly.
-- The theme decides which semantic surface each of its components uses. Do not
-  alter built-in section styling to accommodate a single theme palette, and do
-  not hardcode replacement colors in individual sections.
-- Keep typography, spacing, containers, buttons, cards, forms, and media frames
-  consistent across ordinary sections, CMS sections, and starter pages.
-- Theme-local assets live under top-level `assets/`. Required preview images are
-  `assets/preview/desktop.png`, `tablet.png`, and `mobile.png`.
-- Contact sections render host-provided `metadata.contactForm`; the platform
-  owns configuration, validation, submission, notifications, and limits.
-
-## Workflow
-
-Before editing:
-
-1. Read the required focused guide(s).
-2. Inspect the existing source, generated types, and established theme helpers.
-3. Identify every affected contract: fields/defaults/render, locales, page data,
-   assets, editor behavior, and templates.
-
-When adding or changing a section:
-
-1. Define serializable props in its dedicated `.tsx` file.
-2. Add `section` metadata with `category`, semantic `variant`, and an explicit
-   `motion` mode (`reveal`, `custom`, or `none`).
-3. Add `label`, useful `ai.instructions`, typed `fields`, optional
-   `blockSlots`, `defaultProps`, and `render`.
-4. Add all editor label keys to `src/locales/en.json`.
-5. Register it in `pageConfig` and the appropriate translated category.
-6. Add realistic usage to starter pages or CMS templates where appropriate.
-7. Verify public rendering plus editor desktop, tablet, and mobile behavior.
-
-Before handoff:
-
-```bash
-pnpm lint
-pnpm typecheck
-pnpm build
-pnpm validate
-suda theme check
-suda theme visual-check
-```
+## Always required
 
-Run `suda theme visual-check` after developing or substantially changing a
-theme. It renders every page component declared by the theme's
-`pageConfig.components` with each declared design preset at desktop, tablet,
-and mobile sizes, writes screenshots and `report.json` to
-`.suda-build/visual-check/`, and fails on token contrast, semantic surface,
-or page-overflow errors. Fixed-header overlap is reported as a layout warning;
-solve it in the theme layout. Platform built-in sections are covered by
-theme-engine tests, not repeated for every theme. Run `suda theme capture` when
-publish-preview visuals change.
-Do not use removed skip flags or bypass build, validation, AI metadata, locale,
-visual, or screenshot checks.
+- Keep `renderMode: "ssr"` and export the complete `ThemeModule` contract.
+- Keep persisted props JSON-serializable and put normal field defaults only in
+  component `defaultProps`.
+- Do not edit generated files in `dist/`; regenerate them through the build.

package/templates/theme/CLAUDE.md

@@ -1,3 +1,5 @@
 # Claude Code
 
-Read `AGENTS.md` first. It is the canonical guide for this Suda theme project.
+Read `AGENTS.md` first. Then use the installed `sudacloud-theme` skill for
+theme development guidance. If it is missing, run `suda theme skill add` from
+the repository or monorepo root.

package/templates/theme/README.md

@@ -8,6 +8,19 @@ A standalone Vite + React + Tailwind Suda theme scaffolded with `suda theme init
 pnpm install
 ```
 
+## Theme development skill
+
+Install the shared Suda theme development guidance once at the repository or
+monorepo root:
+
+```bash
+suda theme skill add
+```
+
+The generated `AGENTS.md` keeps only project rules that must always apply. The
+installed `sudacloud-theme` skill provides the detailed section, collection,
+CMS, design system, editor, and localization guidance.
+
 ## Develop
 
 ```bash

package/templates/theme/docs/agent-guides/component-authoring.md

@@ -65,6 +65,9 @@ Use the most specific supported field:
 - `select`, `radio`: stable serializable choices.
 - `object`, `array`: grouped and repeatable structured values.
 - `posts`: one dynamic post query on an ordinary page section.
+- `collection`: a project-scoped dynamic collection binding with semantic role
+  mappings. The current contract resolves a published list and `limit`; do not
+  invent manual selection, filter/sort, or detail-route fields in PageData.
 
 Rules:
 
@@ -126,6 +129,38 @@ defaultProps: {
 },
 ```
 
+## Collection-backed sections
+
+The theme engine includes three platform-owned section families:
+
+- `SudaCollectionGrid` for multi-column cards;
+- `SudaCollectionList` for compact directories;
+- `SudaCollectionSpotlight` for one prominent entry and optional supporting entries.
+
+When a theme owns a custom collection layout, declare semantic roles instead of
+assuming every Collection has fields named `title`, `image`, or `featured`:
+
+```ts
+source: {
+  type: "collection",
+  roles: {
+    title: { types: ["text", "textarea"], required: true },
+    description: { types: ["text", "textarea", "richText"] },
+    image: { types: ["media"] },
+    href: { types: ["url"] },
+  },
+  defaultLimit: 6,
+  maxLimit: 12,
+}
+```
+
+Read resolved entries with `getCollectionResource(props.puck?.metadata, {
+componentId: props.id, fieldKey: "source" })` from
+`@sudajs/theme-engine/runtime`. The host runtime supplies published entries for
+the current locale and resolves media URLs. A theme must not access Prisma or
+filter project data in the browser. The platform documentation describes the
+complete contract and planned query/detail extensions.
+
 ## Navigation and footer menus
 
 Navigation and footer menus are typed arrays. Do not use a legacy menu field,

package/templates/theme-skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sudacloud-theme
+description: Use when building, editing, reviewing, validating, or publishing a SudaCloud Vite theme, including sections, collection bindings, CMS templates, design tokens, Puck editor compatibility, starter pages, and theme localization.
+---
+
+# SudaCloud Theme Development
+
+Use this skill for a standalone Suda theme created by `suda theme init`.
+It supplies the reusable development contract that should be installed once at
+the repository or monorepo root with `suda theme skill add`.
+
+## Read first
+
+Read the references that match the task before editing. Read more than one when
+a change crosses concerns.
+
+| Task                                                                                     | Required reference                    |
+| ---------------------------------------------------------------------------------------- | ------------------------------------- |
+| Sections, fields, defaults, menus, icons, AI metadata, block slots, or collections       | `references/component-authoring.md`   |
+| CMS templates, posts, starter pages, PageData, or locales                                | `references/templates-and-locales.md` |
+| Header, Footer, PageOutlet, sticky or fixed UI, carousel, editor CSS, or client behavior | `references/editor-compatibility.md`  |
+| Theme contract, manifest, design tokens, CSS, assets, contact forms, or runtime metadata | `references/design-and-runtime.md`    |
+
+Use generated TypeScript types and installed package APIs as the source of truth
+when they are more specific than these references. Do not guess contracts.
+
+## Non-negotiable requirements
+
+- Keep `renderMode: "ssr"` and export a complete `ThemeModule` with `manifest`,
+  `pageConfig`, `layoutConfig`, `defaultLayout`, `starterPages`, and
+  `cmsTemplates`.
+- Keep page sections in `pageConfig`; render shared chrome once from the layout
+  with `PageOutlet` between Header and Footer.
+- Persist only JSON-serializable props. Use `defaultProps` as the sole owner of
+  normal field defaults; render code must not invent fallback content.
+- Every editor-facing label uses `t(...)` and has an `en.json` entry. Public
+  content and `defaultProps` do not use the editor translation helper.
+- Authored PageData uses public component keys with stable top-level `props.id`.
+  Block slots use their short local kinds, never internal generated types.
+- Resolve theme assets with `themeAsset(...)` in authored data and
+  `resolveAsset(...)` for editable rendered media.
+- Keep CSS scoped to the theme root and preserve Puck editor compatibility.
+- Do not edit `dist/`; regenerate it with the theme build.
+
+## Collection sections
+
+Prefer the platform-owned `SudaCollectionGrid`, `SudaCollectionList`, and
+`SudaCollectionSpotlight` for standard collection displays. For a custom
+collection layout, declare semantic collection roles and read the published
+project-scoped resource through `getCollectionResource(...)`; do not query
+database data or implement client-side project filtering.
+
+## Verification
+
+Run the relevant theme checks before publishing:
+
+```bash
+pnpm lint:fix
+pnpm typecheck
+suda theme visual-check
+suda theme capture
+pnpm build
+```