@sudajs/cli 0.13.2 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "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.2"
+    "@sudajs/theme-engine": "5.1.3"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -644,6 +644,238 @@ export const Hero: SudaComponentConfig<HeroProps> = {
 - If a page section needs controlled nested content, use Suda `blockSlots`, not a hand-written Puck slot field. `blockSlots` lets the theme define exactly which local block kinds are allowed inside that section.
 - Do not use legacy DropZone or `zones` patterns.
 
+## Puck Editor Compatibility Contract
+
+Every public page and layout component must render consistently in the public
+site, the Puck Editor iframe, and editor preview mode. Build this compatibility
+in when creating the theme; do not wait for an editor-only positioning bug.
+
+### Puck mutates the real component root
+
+In edit mode Puck may attach selection and drag attributes and an inline
+position directly to the first real DOM element returned by a component:
+
+```ts
+el.setAttribute("data-puck-component", id);
+el.setAttribute("data-puck-dnd", id);
+el.style.position = "relative";
+```
+
+- Never assume `[data-puck-component]` is an external wrapper. It may be the
+  component's own `<nav>`, `<header>`, `<section>`, or `<footer>`.
+- `:has(.component-root)` does not match an element that is itself
+  `.component-root`. When both DOM shapes are possible, cover both explicitly:
+
+```css
+.component-root[data-puck-component],
+[data-puck-component]:has(.component-root) {
+  /* compatibility override */
+}
+```
+
+- Puck's inline `position: relative` beats ordinary theme CSS. A component
+  whose real root must remain `sticky`, `fixed`, or `absolute` in the editor
+  needs a specific editor-scoped rule with `!important`.
+- Never apply `position: relative !important` to every editor component. That
+  destroys navigation, overlays, and floating controls.
+
+### Stable component roots
+
+- Every public page and layout component should return one stable, semantic,
+  real DOM root. Prefer `<header>` or `<nav>` for navigation, `<footer>` for the
+  footer, and `<section>` or an explicit container for ordinary sections.
+- Do not use a Fragment as the root of a component that controls positioning,
+  margin, size, stacking, background, or editor selection. Do not depend on
+  Puck to wrap a Fragment.
+- Do not use `display: contents` on a root that needs margin, padding,
+  positioning, sticky/fixed behavior, `z-index`, background, or a selection
+  outline.
+- `PageOutlet` must render a real DOM element when it needs negative margin,
+  overlap, positioning, or sizing.
+
+### Explicit editor scope
+
+The layout root must derive editor state from
+`puck?.metadata?.isEditor === true` and expose a stable marker:
+
+```tsx
+<div className="theme-root" data-suda-editor={isEditor ? "true" : undefined}>
+  {children}
+</div>
+```
+
+Keep every editor-only compatibility rule below
+`.theme-root[data-suda-editor="true"]`. Do not globally override `.navbar`,
+`.section`, or `[data-puck-component]`, change the public-site layout to repair
+the editor, use vague selectors that affect unrelated components, or edit
+third-party minified CSS. Put compatibility overrides in the theme's scoped
+`src/styles.css`.
+
+When the component itself may be the Puck root or may sit inside one, write and
+test both selectors. Keep later rules from overriding the correction:
+
+```css
+.theme-root[data-suda-editor="true"] .theme-navigation[data-puck-component],
+.theme-root[data-suda-editor="true"]
+  [data-puck-component]:has(.theme-navigation)
+  .theme-navigation {
+  position: sticky !important;
+  top: 0;
+  z-index: 30;
+}
+```
+
+### Sticky and fixed positioning
+
+Before implementing Header, announcement bar, floating CTA, or any
+sticky/fixed component, verify all of the following:
+
+- whether Puck writes `position: relative` on the actual positioned root;
+- which element really scrolls in the site and in the editor iframe;
+- that the sticky element is inside the intended scroll container;
+- whether any ancestor has `overflow: hidden`, `auto`, `scroll`, or `clip`, or
+  has `transform`, `filter`, `perspective`, or `contain`;
+- that the sticky parent is taller than the sticky element where required;
+- that `top` and `z-index` are explicit; and
+- that iframe scrolling and the outer editor canvas do not use incompatible
+  coordinate systems.
+
+For a layout Header, prefer putting sticky behavior on the Header's real root.
+If that root receives `data-puck-component`, override Puck's inline position on
+that same node. Do not force the Header root to `relative !important` and then
+expect a parent sticky rule to work. Site and editor may use different
+positioning strategies only when their visual result remains equivalent.
+
+### Transparent navigation is state plus layout
+
+Transparent navigation must coordinate all of these concerns, not merely set
+`background: transparent`:
+
+- transparent background and removed shadow;
+- logo, menu text, and button color changes;
+- Hero or `PageOutlet` overlap beneath the Header;
+- restoration of the solid state after the scroll threshold;
+- Puck's root-node positioning mutation in the editor; and
+- identical SSR-first-frame and hydrated state.
+
+Never render a white logo/text state above an accidentally white navigation
+background. Prefer React Context for a page's transparent-navigation request,
+an SSR-readable DOM marker for the first-frame fallback, and a real
+`PageOutlet` element with negative margin in the editor. The public site may use
+a spacer or equivalent layout strategy. Keep shared measurements in CSS
+variables, for example `--theme-navigation-height: 4.6rem`.
+
+### Editor scroll detection
+
+Do not rely only on `window.scrollY` or a `window` scroll listener. The active
+scroll source may be `document.scrollingElement`, the iframe document, or an
+inner `overflow: auto/scroll` container, and `scroll` does not bubble.
+
+- Find the nearest scrollable ancestor for each navigation instance and read
+  that element's own `scrollTop`.
+- Listen on the document with
+  `document.addEventListener("scroll", handler, { capture: true, passive: true })`
+  and keep a window listener for public-site compatibility.
+- Do not assume editor and site share the same scrolling element.
+
+### React and editor runtime lifecycle
+
+Runtime code must tolerate editor remounts, live prop changes, HMR, frequent
+`MutationObserver` callbacks, React Strict Mode effect replay, and loading after
+`DOMContentLoaded` has already fired.
+
+- Make event binding and initialization idempotent.
+- Observe components inserted later and relevant attribute changes.
+- Do not use a permanent `window.__xxxBound` flag that prevents required HMR
+  reinitialization.
+- Clean up component effects, observers, and listeners.
+- Keep SSR markers and client state synchronized instead of letting them fight.
+
+### Puck interaction styles
+
+Assume edit mode may apply rules equivalent to:
+
+```css
+[data-puck-component] * {
+  pointer-events: none;
+  user-select: none;
+}
+
+[data-puck-component] {
+  pointer-events: auto !important;
+}
+```
+
+An unclickable link, dropdown, carousel, or button in edit mode is not by
+itself a theme interaction bug. Distinguish edit mode from preview mode. Never
+globally restore descendant pointer events because that breaks selection and
+dragging; test visitor interactions in editor preview and the public site.
+
+### Layout ownership
+
+- Keep only `Header`, `PageOutlet`, `Footer`, and necessary global chrome such
+  as an announcement bar in `layoutConfig`.
+- Render Header and Footer exactly once per page from the layout. Do not repeat
+  them in starter pages.
+- If Footer or Header moves from page sections into the layout, remove duplicate
+  entries from `starterPages`, `cmsTemplates`, `pageConfig.categories`, and AI
+  examples.
+- Give Header, `PageOutlet`, and Footer stable `props.id` values, with
+  `PageOutlet` between Header and Footer.
+- Read platform white-label, ICP, and other footer metadata from runtime
+  metadata; do not persist it as duplicated static component data.
+
+### Vendor CSS
+
+Do not modify original third-party minified CSS unless the task explicitly
+requires a maintained vendor patch. Use precise selectors in the theme's own
+scoped `src/styles.css`. If a vendor file truly must change, document the
+reproducible problem and why an override cannot solve it.
+
+### New-theme completion checklist
+
+When creating a theme, complete all of these in the initial implementation:
+
+- editor root marker and stable real roots;
+- layout-owned Header / `PageOutlet` / Footer with stable ids;
+- Header sticky compatibility in the editor;
+- transparent navigation in editor and site modes;
+- scrollable-ancestor detection and an SSR state marker;
+- idempotent runtime setup and cleanup;
+- real-element `PageOutlet` overlap behavior;
+- responsive viewport behavior; and
+- editor preview versus public-site comparison.
+
+### Required regression matrix
+
+Whenever Header, transparent navigation, sticky/fixed positioning,
+`PageOutlet`, Footer, carousel, dropdown/mobile menu, or a `100vh` Hero changes,
+verify:
+
+- public-site SSR first frame and post-hydration state;
+- editor desktop, tablet, and mobile viewports;
+- editor edit mode and preview mode;
+- initial top state and state after crossing the scroll threshold;
+- state after HMR and live prop updates;
+- exactly one Header and one Footer; and
+- intact Puck selection and drag behavior.
+
+### Debugging order
+
+When editor and site differ, inspect in this order before changing CSS:
+
+1. The component's actual root node.
+2. The element that received `data-puck-component`.
+3. Inline styles written on that element.
+4. Computed `position`, `background`, `z-index`, and ancestor `overflow`.
+5. The real scrolling element and its `scrollTop`.
+6. Iframe versus outer-canvas coordinate systems.
+7. Whether the theme runtime initialized.
+8. Transparent-state Context and DOM markers.
+9. Stylesheet load and cascade order.
+
+Do not guess selectors repeatedly before confirming the DOM and computed style.
+
 ## Design system rules
 
 Build every theme from one theme-level design system. Do not let each section,