@sudajs/cli 0.18.10 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.18.10",
+  "version": "0.19.0",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -24,7 +24,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "@puckeditor/core": "^0.22.4",
     "commander": "^12.1.0",
     "esbuild": "^0.25.12",
@@ -34,7 +33,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "6.5.0"
+    "@sudajs/theme-engine": "6.6.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -80,6 +80,11 @@ Extract shared code only when multiple sections genuinely reuse it.
   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`,
@@ -100,7 +105,8 @@ Default ownership is strict:
 <div>{val || "defaultValue"}</div>;
 
 // Correct: defaultProps owns the default.
-export const Example: SudaComponentConfig<ExampleProps> = {
+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>,
@@ -155,9 +161,71 @@ it must not substitute placeholder copy, labels, links, icons, or menu items.
 
 - Define one editable design system in `sourceManifest.designSystem`, expose it
   at the layout root, resolve it once there, and render components through the
-  resulting `--suda-*` CSS variables.
-- Tailwind token mappings use `@theme inline`. Hand-written CSS consumes
-  `--suda-*` variables directly, not `--color-*` or `--radius-*` aliases.
+  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" },
+  }
+  ```
+
+- 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
@@ -177,12 +245,14 @@ Before editing:
 When adding or changing a section:
 
 1. Define serializable props in its dedicated `.tsx` file.
-2. Add `label`, useful `ai.instructions`, typed `fields`, optional
+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`.
-3. Add all editor label keys to `src/locales/en.json`.
-4. Register it in `pageConfig` and the appropriate translated category.
-5. Add realistic usage to starter pages or CMS templates where appropriate.
-6. Verify public rendering plus editor desktop, tablet, and mobile behavior.
+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:
 
@@ -192,7 +262,17 @@ pnpm typecheck
 pnpm build
 pnpm validate
 suda theme check
+suda theme visual-check
 ```
 
-Run `suda theme capture` when visuals change. Do not use removed skip flags or
-bypass build, validation, AI metadata, locale, or screenshot checks.
+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.

package/templates/theme/README.md

@@ -34,6 +34,20 @@ pnpm build
 
 By default capture writes `assets/preview/desktop.png`, `assets/preview/tablet.png`, and `assets/preview/mobile.png`.
 
+Run a reusable visual audit after creating or substantially changing the theme:
+
+```bash
+suda theme visual-check
+```
+
+It renders every page component declared by the theme's `pageConfig.components`
+with every design preset at desktop, tablet, and mobile sizes. Screenshots and
+`report.json` are written to `.suda-build/visual-check/`; the command fails on
+token contrast, semantic surface-color, or page-overflow errors. Platform
+built-in sections are covered by theme-engine tests rather than being repeated
+for every theme. Use `--preset <id>`, `--device <device>`, or `--full-page` to
+narrow a review.
+
 Fields can use `visibleIf: ({ props }, { fields }) => boolean` for synchronous dynamic visibility. The starter hero shows this by hiding the Logo picker when `showLogo` is false. Suda converts `visibleIf` to Puck `resolveFields` during normalization, and the generated AI/MCP section schema marks those fields as dynamically visible.
 
 When adding fields, prefer purpose-built Suda field types over generic text inputs: use `url` for links, `image` / `video` / `media` for media, `color` for colors, `icon` for icon names, `range` for bounded numbers, `spacing` for spacing tokens, `menu` for navigation, `select` / `radio` for fixed choices, and `array` / `object` for structured values. Multi-column sections such as card grids should expose a `columns` prop.

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

@@ -21,10 +21,18 @@ icons, AI metadata, or block slots. The root `AGENTS.md` rules still apply.
 
 ## Field source of truth
 
-Type props first. Use `SudaComponentConfig<Props>`, `SudaFields<Props>`, and
+Type props first. Use `SudaSectionConfig<Props>`, `SudaFields<Props>`, and
 `defineSudaPageData(pageConfig, data)` to catch shape mismatches. Do not invent a
 parallel Zod schema for theme fields.
 
+Every page section must include `section` metadata. Its `motion` value is
+required: ordinary sections use `"reveal"`, sections with their own client-side
+animation use `"custom"`, and intentionally static sections use `"none"`.
+The rendered section root must also carry the matching
+`data-section-motion="reveal"`, `"custom"`, or `"none"` attribute. Do not rely
+on a class-name convention; TypeScript checks the metadata contract and the
+runtime uses the data attribute to avoid hiding content before hydration.
+
 Keep these four structures aligned:
 
 1. TypeScript props.
@@ -219,7 +227,8 @@ pricing cards, feature rows, stats, timeline items, or contact methods.
 ```tsx
 type HeroProps = { title?: string; actions?: Slot };
 
-export const Hero: SudaComponentConfig<HeroProps> = {
+export const Hero: SudaSectionConfig<HeroProps> = {
+  section: { category: "hero", variant: "centered", motion: "reveal" },
   label: t("sections.hero.label"),
   ai: { instructions: "Primary landing-page introduction. Use once near the top." },
   fields: {

package/templates/theme/docs/agent-guides/design-and-runtime.md

@@ -64,17 +64,30 @@ scales, radii, shadows, or spacing.
 
 For Tailwind, map Suda tokens through `@theme inline` and consume semantic
 utilities such as `bg-primary`, `text-primary-foreground`, and `rounded-card`.
-The `inline` keyword is required because Suda injects `--suda-*` variables on
+The `inline` keyword is required because Suda injects unprefixed variables on
 the rendered theme root.
 
-Hand-written CSS consumes `--suda-*` directly. Do not use Suda-backed aliases
-such as `var(--color-primary)`, `var(--color-background)`, or
-`var(--radius-card)` in hand-written rules. For derived values, declare a
-theme-prefixed variable on the root:
+Use the token meanings below rather than guessing from a theme's current
+palette. Foreground tokens always pair with the surface token actually used.
+
+| CSS variables                                          | Meaning and use                                                                                                                    |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `--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 readable content on it. It is not assumed light or dark.                                                  |
+| `--accent` / `--accent-foreground`                     | High-attention emphasis, selection, or decorative surface, plus readable content on it. Do not use it as a default CTA substitute. |
+| `--muted` / `--muted-foreground`                       | Low-emphasis surface and secondary text/icons.                                                                                     |
+| `--radius`                                             | Generic radius fallback.                                                                                                           |
+| `--radius-card` / `--radius-button` / `--radius-input` | Radius for cards, command buttons, and form controls.                                                                              |
+
+Hand-written CSS consumes these unprefixed variables directly. Do not use
+Tailwind aliases such as `var(--color-primary)` or `var(--color-background)`
+in hand-written rules. For derived values, declare a theme-prefixed variable on
+the root:
 
 ```css
 .my-theme-root {
-  --my-theme-primary-hover: color-mix(in srgb, var(--suda-color-primary) 84%, black);
+  --my-theme-primary-hover: color-mix(in srgb, var(--primary) 84%, black);
 }
 
 .my-theme-button:hover {
@@ -82,8 +95,10 @@ theme-prefixed variable on the root:
 }
 ```
 
-Build/check/publish reject hand-written consumption of Suda-backed Tailwind
-aliases.
+Theme authors decide which semantic surface each component uses. Do not alter
+built-in section styling to match one theme palette, and do not hardcode
+replacement colors in individual sections. Build/check/publish reject
+hand-written consumption of Suda-backed Tailwind aliases.
 
 ## Visual consistency
 

package/templates/theme/src/manifest.ts

@@ -35,6 +35,9 @@ export const sourceManifest: ThemeSourceManifest = {
             button: "8px",
             input: "8px",
           },
+          layout: {
+            contentWidth: "1280px",
+          },
         },
       },
       {
@@ -58,6 +61,9 @@ export const sourceManifest: ThemeSourceManifest = {
             button: "9999px",
             input: "10px",
           },
+          layout: {
+            contentWidth: "1280px",
+          },
         },
       },
     ],

package/templates/theme/src/sections.tsx

@@ -1,4 +1,4 @@
-import type { SudaComponentConfig } from "@sudajs/theme-engine";
+import type { SudaSectionConfig, SudaSectionMetadata } from "@sudajs/theme-engine";
 import {
   SudaIcon,
   type SudaIconName,
@@ -48,7 +48,8 @@ type FeaturedPostsProps = {
   postList?: ThemePostResourceQuery;
 } & PuckExtras;
 
-export const Hero: SudaComponentConfig<HeroProps> = {
+export const Hero: SudaSectionConfig<HeroProps> = {
+  section: { category: "hero", variant: "centered", motion: "reveal" } satisfies SudaSectionMetadata,
   label: t("sections.hero.label"),
   ai: {
     instructions:
@@ -98,7 +99,7 @@ export const Hero: SudaComponentConfig<HeroProps> = {
   }) => {
     const logoSrc = resolveAsset(puck?.metadata, logo);
     return (
-      <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-hero">
+      <section data-section-motion="reveal" className="w-full __SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-hero">
         {showLogo && logoSrc ? (
           <img className="__SUDA_THEME_KEY__-hero-logo" src={logoSrc} alt="" />
         ) : null}
@@ -113,7 +114,8 @@ export const Hero: SudaComponentConfig<HeroProps> = {
   },
 };
 
-export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
+export const FeatureGrid: SudaSectionConfig<FeatureGridProps> = {
+  section: { category: "features", variant: "feature-grid", motion: "reveal" } satisfies SudaSectionMetadata,
   label: t("sections.featureGrid.label"),
   ai: {
     instructions:
@@ -146,7 +148,7 @@ export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
     ],
   },
   render: ({ title, description, columns = 3, features = [] }) => (
-    <section className="__SUDA_THEME_KEY__-section">
+    <section data-section-motion="reveal" className="w-full __SUDA_THEME_KEY__-section">
       <h2>{title}</h2>
       <p>{description}</p>
       <div
@@ -165,7 +167,8 @@ export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
   ),
 };
 
-export const Testimonial: SudaComponentConfig<TestimonialProps> = {
+export const Testimonial: SudaSectionConfig<TestimonialProps> = {
+  section: { category: "social-proof", variant: "testimonial", motion: "reveal" } satisfies SudaSectionMetadata,
   label: t("sections.testimonial.label"),
   ai: {
     instructions:
@@ -184,7 +187,7 @@ export const Testimonial: SudaComponentConfig<TestimonialProps> = {
     role: "Founder",
   },
   render: ({ quote, author, role }) => (
-    <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-quote">
+    <section data-section-motion="reveal" className="w-full __SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-quote">
       <blockquote>{quote}</blockquote>
       <p>
         {author} · {role}
@@ -193,7 +196,8 @@ export const Testimonial: SudaComponentConfig<TestimonialProps> = {
   ),
 };
 
-export const CallToAction: SudaComponentConfig<CallToActionProps> = {
+export const CallToAction: SudaSectionConfig<CallToActionProps> = {
+  section: { category: "conversion", variant: "cta", motion: "reveal" } satisfies SudaSectionMetadata,
   label: t("sections.callToAction.label"),
   ai: {
     instructions:
@@ -214,7 +218,7 @@ export const CallToAction: SudaComponentConfig<CallToActionProps> = {
     buttonHref: "#contact",
   },
   render: ({ title, description, buttonLabel, buttonHref }) => (
-    <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-cta" id="contact">
+    <section data-section-motion="reveal" className="w-full __SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-cta" id="contact">
       <h2>{title}</h2>
       <p>{description}</p>
       <a className="__SUDA_THEME_KEY__-button" href={buttonHref}>
@@ -224,7 +228,8 @@ export const CallToAction: SudaComponentConfig<CallToActionProps> = {
   ),
 };
 
-export const FeaturedPosts: SudaComponentConfig<FeaturedPostsProps> = {
+export const FeaturedPosts: SudaSectionConfig<FeaturedPostsProps> = {
+  section: { category: "content", variant: "featured-posts", motion: "reveal" } satisfies SudaSectionMetadata,
   label: t("sections.featuredPosts.label"),
   ai: {
     instructions:
@@ -251,7 +256,7 @@ export const FeaturedPosts: SudaComponentConfig<FeaturedPostsProps> = {
     const postHref = (post: (typeof posts)[number]) =>
       post.url || (post.slug ? `/posts/${encodeURIComponent(post.slug)}` : "#");
     return (
-      <section className="__SUDA_THEME_KEY__-section">
+      <section data-section-motion="reveal" className="w-full __SUDA_THEME_KEY__-section">
         <h2>{title}</h2>
         <p>{description}</p>
         <div className="__SUDA_THEME_KEY__-grid" style={{ "--__SUDA_THEME_KEY__-columns": 3 }}>

package/templates/theme/src/styles.css

@@ -1,24 +1,44 @@
 @import "tailwindcss";
 @source "./**/*.{ts,tsx}";
 
+[data-suda-motion-ready] [data-section-motion="reveal"] {
+  opacity: 0;
+  transform: translateY(24px);
+  transition:
+    opacity 700ms ease,
+    transform 700ms ease;
+}
+[data-suda-motion-ready] [data-section-motion="reveal"][data-motion-visible="true"],
+[data-suda-motion-reduced] [data-section-motion="reveal"] {
+  opacity: 1;
+  transform: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-section-motion="reveal"] {
+    opacity: 1;
+    transform: none;
+    transition: none;
+  }
+}
+
 .__SUDA_THEME_KEY__-root {
   font-family: Inter, ui-sans-serif, system-ui, sans-serif;
-  color: var(--suda-color-foreground, #111827);
-  background: var(--suda-color-background, #ffffff);
+  color: var(--foreground, #111827);
+  background: var(--background, #ffffff);
 }
 .__SUDA_THEME_KEY__-header,
 .__SUDA_THEME_KEY__-footer {
   padding: 20px clamp(20px, 5vw, 64px);
-  border-bottom: 1px solid var(--suda-color-muted, #e5e7eb);
+  border-bottom: 1px solid var(--muted, #e5e7eb);
 }
 .__SUDA_THEME_KEY__-footer {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
   gap: 12px 20px;
-  border-top: 1px solid var(--suda-color-muted, #e5e7eb);
+  border-top: 1px solid var(--muted, #e5e7eb);
   border-bottom: 0;
-  color: var(--suda-color-muted-foreground, #6b7280);
+  color: var(--muted-foreground, #6b7280);
 }
 .__SUDA_THEME_KEY__-footer a {
   display: inline-flex;
@@ -35,19 +55,19 @@
   padding: 64px clamp(20px, 5vw, 64px);
 }
 .__SUDA_THEME_KEY__-hero {
-  background: var(--suda-color-accent, #f8fafc);
+  background: var(--accent, #f8fafc);
 }
 .__SUDA_THEME_KEY__-hero-logo {
   width: 64px;
   height: 64px;
-  border-radius: var(--suda-radius-card, 14px);
+  border-radius: var(--radius-card, 14px);
   margin-bottom: 24px;
 }
 .__SUDA_THEME_KEY__-eyebrow {
   text-transform: uppercase;
   letter-spacing: 0.08em;
   font-size: 12px;
-  color: var(--suda-color-primary, #2563eb);
+  color: var(--primary, #2563eb);
   font-weight: 700;
 }
 .__SUDA_THEME_KEY__-section h1 {
@@ -65,16 +85,16 @@
 .__SUDA_THEME_KEY__-section p {
   max-width: 680px;
   line-height: 1.7;
-  color: var(--suda-color-muted-foreground, #4b5563);
+  color: var(--muted-foreground, #4b5563);
 }
 .__SUDA_THEME_KEY__-button {
   display: inline-flex;
   align-items: center;
   min-height: 42px;
   padding: 0 18px;
-  border-radius: var(--suda-radius-button, 8px);
-  background: var(--suda-color-primary, #111827);
-  color: var(--suda-color-primary-foreground, #ffffff);
+  border-radius: var(--radius-button, 8px);
+  background: var(--primary, #111827);
+  color: var(--primary-foreground, #ffffff);
   text-decoration: none;
   font-weight: 700;
 }
@@ -85,14 +105,14 @@
   margin-top: 28px;
 }
 .__SUDA_THEME_KEY__-card {
-  border: 1px solid var(--suda-color-muted, #e5e7eb);
-  border-radius: var(--suda-radius-card, 8px);
+  border: 1px solid var(--muted, #e5e7eb);
+  border-radius: var(--radius-card, 8px);
   padding: 20px;
 }
 .__SUDA_THEME_KEY__-card-icon {
   width: 24px;
   height: 24px;
-  color: var(--suda-color-primary, #2563eb);
+  color: var(--primary, #2563eb);
 }
 .__SUDA_THEME_KEY__-quote blockquote {
   max-width: 780px;
@@ -101,15 +121,15 @@
   margin: 0 0 16px;
 }
 .__SUDA_THEME_KEY__-cta {
-  background: var(--suda-color-foreground, #111827);
-  color: var(--suda-color-background, #ffffff);
+  background: var(--foreground, #111827);
+  color: var(--background, #ffffff);
 }
 .__SUDA_THEME_KEY__-cta p {
-  color: var(--suda-color-muted, #d1d5db);
+  color: var(--muted, #d1d5db);
 }
 .__SUDA_THEME_KEY__-cta .__SUDA_THEME_KEY__-button {
-  background: var(--suda-color-background, #ffffff);
-  color: var(--suda-color-foreground, #111827);
+  background: var(--background, #ffffff);
+  color: var(--foreground, #111827);
 }
 @media (max-width: 760px) {
   .__SUDA_THEME_KEY__-grid {