@sudajs/cli 0.13.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -34,7 +34,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "5.1.0"
+    "@sudajs/theme-engine": "5.1.2"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -71,6 +71,28 @@ one pass:
 8. Run `pnpm typecheck`, `pnpm lint`, `pnpm build`, and `pnpm validate` before
    handoff.
 
+Rendering fallback rule:
+
+- Defaults belong in `defaultProps`, starter page data, or CMS template data.
+  During render, read values directly from props. Do not add fallback display
+  values with `||`, `??`, or ternaries unless the fallback is truly required for
+  runtime safety.
+- This is wrong because render invents content that is not in props:
+
+```tsx
+<div>{props.title || "title"}</div>
+```
+
+- This is correct because render only displays the authored prop value:
+
+```tsx
+<div>{props.title}</div>
+```
+
+- Conditional rendering is fine when absence intentionally removes optional UI,
+  such as hiding an optional image, button, or eyebrow. Do not use conditional
+  rendering to substitute placeholder copy, labels, links, or menu items.
+
 Configure ordinary fields like this:
 
 ```ts
@@ -143,6 +165,145 @@ Field source of truth:
   `range`, `spacing`, `media`, `image`, `video`, and `posts`. These are valid
   in `fields` and are normalized by `@sudajs/theme-engine`.
 
+## Navigation and footer menus
+
+Navigation and footer menus must be typed arrays. Do not use the legacy menu
+field type, multiline text areas, or newline-delimited strings to model menus.
+Every link destination must use a `url` field type, never a plain `text` field.
+The `fields`, TypeScript props, and `defaultProps` data structures must match
+exactly.
+
+Navigation supports at most two levels:
+
+- `navItems[]`
+- `navItems[].submenu[]`
+
+Submenu items may contain only text and link fields. Do not add another nested
+submenu field inside `navItems[].submenu[]`; the field shape must make third
+levels impossible. An empty `submenu` array means the item is an ordinary
+top-level link.
+
+The simplest Navigation field shape is:
+
+```ts
+type NavSubItem = {
+  label: string;
+  href: string;
+};
+
+type NavItem = {
+  label: string;
+  href: string;
+  submenu: NavSubItem[];
+};
+
+const navItemsField = {
+  type: "array",
+  label: t("common.fields.navigationItems"),
+  getItemSummary: (item: NavItem) => item.label || "Navigation item",
+  defaultItemProps: {
+    label: "Home",
+    href: "/",
+    submenu: [],
+  },
+  arrayFields: {
+    label: {
+      type: "text",
+      label: t("common.fields.label"),
+    },
+    href: {
+      type: "url",
+      label: t("common.fields.link"),
+    },
+    submenu: {
+      type: "array",
+      label: t("common.fields.submenu"),
+      getItemSummary: (item: NavSubItem) => item.label || "Submenu item",
+      arrayFields: {
+        label: {
+          type: "text",
+          label: t("common.fields.label"),
+        },
+        href: {
+          type: "url",
+          label: t("common.fields.link"),
+        },
+      },
+    },
+  },
+};
+
+const defaultNavItems: NavItem[] = [
+  {
+    label: "Home",
+    href: "/",
+    submenu: [],
+  },
+  {
+    label: "Company",
+    href: "/company",
+    submenu: [
+      {
+        label: "About",
+        href: "/about",
+      },
+    ],
+  },
+];
+```
+
+Footer grouped menus use two array levels:
+
+- `columns[]`
+- `columns[].links[]`
+
+Use this prop shape and mirror it exactly in the field config and defaults:
+
+```ts
+type FooterColumn = {
+  title: string;
+  links: {
+    text: string;
+    url: string;
+  }[];
+};
+
+const footerColumnsField = {
+  type: "array",
+  label: t("common.fields.columns"),
+  getItemSummary: (item: FooterColumn) => item.title || "Footer column",
+  defaultItemProps: {
+    title: "Company",
+    links: [{ text: "About", url: "/about" }],
+  },
+  arrayFields: {
+    title: {
+      type: "text",
+      label: t("common.fields.title"),
+    },
+    links: {
+      type: "array",
+      label: t("common.fields.links"),
+      getItemSummary: (item: FooterColumn["links"][number]) => item.text || "Footer link",
+      defaultItemProps: {
+        text: "About",
+        url: "/about",
+      },
+      arrayFields: {
+        text: {
+          type: "text",
+          label: t("common.fields.label"),
+        },
+        url: {
+          type: "url",
+          label: t("common.fields.link"),
+        },
+      },
+    },
+  },
+};
+```
+
 Use these field patterns:
 
 ```ts
@@ -236,8 +397,6 @@ defaultProps: {
   download: "",
   icon: "sparkles",
   accentColor: "#2563eb",
-  font: "system",
-  links: [{ label: "Home", url: "/" }],
   spacing: "md",
   postList: { strategy: "featured", limit: 3 },
   badge: { label: "New", tone: "primary" },
@@ -288,6 +447,32 @@ or AI examples.
 - React, React DOM, Puck, and `@sudajs/theme-engine` are host-provided peers. Do not bundle private copies into the theme runtime.
 - Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
 
+## Puck editor CSS isolation
+
+Puck renders the editable preview in a same-origin iframe. The outer
+`#puck-canvas-root` and `#preview-frame` may be only one viewport tall; the
+full page must scroll inside the iframe. Theme CSS must not collapse or disable
+that iframe document.
+
+- In editor mode, make the theme root content-height driven. A root marker such
+  as `[data-suda-editor="true"]` should use `height: auto`,
+  `min-height: 100vh`, and `overflow: visible` unless the theme has a stronger
+  reason not to.
+- If the theme root is rendered inside Puck's `#frame-root`, ensure
+  `#frame-root` can grow with content in editor mode. Do not leave it stuck at
+  a collapsed height when it contains the theme root.
+- Root `[data-puck-dropzone]` wrappers must be able to grow with page content.
+  Avoid forcing `height: 100%` on the root DropZone when that turns the page
+  into a single viewport-height box.
+- Keep public-site resets from leaking into Puck behavior. Be very careful with
+  global `html`, `body`, `iframe`, `.hidden`, `img`, `button`, `input`, and
+  Tailwind preflight rules; they can hide editor wrappers, change intrinsic
+  media sizing, or break iframe scrolling.
+- When importing third-party CSS, add editor-scoped overrides under the theme
+  root marker instead of changing public runtime behavior globally.
+- Verify the editor canvas by scrolling through every starter page. Components
+  must be visible and reachable without selecting them from the outline first.
+
 ## CMS and starter templates
 
 Suda CMS is a built-in fixed post system. Themes must provide exactly these
@@ -526,7 +711,8 @@ radius, shadows, or spacing.
 
 - Tailwind v4 starts in `src/styles.css` with `@import "tailwindcss";` and `@source "./**/*.{ts,tsx}";`.
 - Theme-local assets live in top-level `assets/`; the CLI copies them to `dist/assets/` during build.
-- Use `themeAsset("assets/...")` for theme-bundled assets in default props and starter pages. Do not import images from React code.
+- Import `themeAsset` from `./theme-asset.js` and use `themeAsset("assets/...")` for every theme-bundled asset in default props, starter pages, CMS templates, and AI examples.
+- Do not hand-write `themes/<themeKey>/<version>/...` paths and do not import theme-local images from React code. Full external URLs are allowed, for example CDN URLs such as jsDelivr.
 - Use `resolveAsset(puck?.metadata, value)` from `@sudajs/theme-engine/runtime` before rendering user-selected media fields.
 - Scope theme CSS with the generated theme key classes. Avoid global resets that could affect the host editor or other themes.
 - Preview screenshots are required at `assets/preview/desktop.png`, `assets/preview/tablet.png`, and `assets/preview/mobile.png`; run `suda theme capture` to generate them.
@@ -704,7 +890,7 @@ Starter page data should use the public host component type and a standard array
 - Do not put local block `id` values in starter pages. Only top-level page components need `props.id`.
 - Where practical, wrap authored data with `defineSudaPageData(pageConfig, data)` so TypeScript checks top-level component keys and block-slot nested `type` values.
 - Match starter page content to the theme's intended audience and category. The home page should show the theme's best composition, not just every component in order.
-- Use `themeAsset("assets/...")` for bundled starter media.
+- Use `themeAsset("assets/...")` for bundled starter media; never hand-write generated theme asset paths.
 
 ## Commands
 

package/templates/theme/src/theme-asset.ts

@@ -1,5 +1,8 @@
-import { createThemeAssetResolver } from "@sudajs/theme-engine/runtime";
+import { createThemeAsset } from "@sudajs/theme-engine/runtime";
 
 import { sourceManifest } from "./manifest.js";
 
-export const themeAsset = createThemeAssetResolver(sourceManifest.key, __SUDA_THEME_VERSION__);
+export const themeAsset = createThemeAsset({
+  ...sourceManifest,
+  version: __SUDA_THEME_VERSION__,
+});