@sudajs/cli 0.12.4 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.12.4",
+  "version": "0.13.1",
   "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.0.0"
+    "@sudajs/theme-engine": "5.1.1"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -288,6 +288,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
@@ -367,6 +393,12 @@ platform. In the section render function, call
 with the exact posts field key. Never import Prisma, call platform APIs, or
 query the database from theme code.
 
+When rendering posts returned by `getPostResource`, build links from the
+platform-provided `post.url` first. If it is missing, derive the URL only from
+`post.slug` as `/posts/${encodeURIComponent(post.slug)}`; if neither exists,
+use `#`. Do not guess alternate fields such as `href`, `path`, `permalink`,
+`postUrl`, or `canonicalUrl`.
+
 Do not add `resourceQuery: { type: "posts" }` or
 `resource_query: { type: "posts" }`. Do not assume the field must be named
 `query`. A section may have only one top-level posts field; do not nest posts
@@ -520,7 +552,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.
@@ -588,7 +621,7 @@ Good component instructions explain:
 - Frequency: whether it should appear once, multiple times, or only near another section.
 - Composition: required neighboring content or local blocks, when relevant.
 
-- For icons, expose props with `{ type: "icon" }`, type values as `SudaLucideIconName`, render them with `SudaLucideIcon` from `@sudajs/theme-engine/runtime`, and store canonical Lucide names such as `"rocket"` or `"mouse-pointer-click"` (not `"lucide-rocket"`). Do not keep theme-local icon maps, emoji/icon switch statements, or custom SVG icon registries unless the theme truly needs a bespoke non-Lucide graphic.
+- For icons, expose props with `{ type: "icon" }`, type values as `SudaLucideIconName`, render them with `SudaLucideIcon` from `@sudajs/theme-engine/icons`, and store canonical Lucide names such as `"rocket"` or `"mouse-pointer-click"` (not `"lucide-rocket"`). Do not keep theme-local icon maps, emoji/icon switch statements, or custom SVG icon registries unless the theme truly needs a bespoke non-Lucide graphic.
 - Add optional field-level `ai.instructions`, `ai.required`, or `ai.exclude` when a prop needs generation guidance beyond its label and type.
 - Use `ai.exclude: true` only for structural or editor-only components, and still provide instructions explaining why AI must not generate them. `PageOutlet` is the standard example.
 
@@ -698,7 +731,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/sections.tsx

@@ -1,8 +1,11 @@
-import type { SudaComponentConfig, SudaLucideIconName } from "@sudajs/theme-engine";
+import type { SudaComponentConfig } from "@sudajs/theme-engine";
+import {
+  SudaLucideIcon,
+  type SudaLucideIconName,
+} from "@sudajs/theme-engine/icons";
 import {
   getPostResource,
   resolveAsset,
-  SudaLucideIcon,
   type ThemePostResourceQuery,
   type ThemeRenderMetadata,
 } from "@sudajs/theme-engine/runtime";
@@ -245,6 +248,8 @@ export const FeaturedPosts: SudaComponentConfig<FeaturedPostsProps> = {
       fieldKey: "postList",
     });
     const posts = resource.posts;
+    const postHref = (post: (typeof posts)[number]) =>
+      post.url || (post.slug ? `/posts/${encodeURIComponent(post.slug)}` : "#");
     return (
       <section className="__SUDA_THEME_KEY__-section">
         <h2>{title}</h2>
@@ -258,7 +263,7 @@ export const FeaturedPosts: SudaComponentConfig<FeaturedPostsProps> = {
                 </p>
                 <h3>{post.title}</h3>
                 <p>{post.excerpt}</p>
-                <a href={post.url}>{post.title}</a>
+                <a href={postHref(post)}>{post.title}</a>
               </article>
             ))
           ) : (

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__,
+});