@sudajs/cli 0.13.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.13.0",
+  "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.1.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
@@ -526,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.
@@ -704,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/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__,
+});