@sudajs/cli 0.18.9 → 0.18.11

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

@@ -0,0 +1,270 @@
+# Component Authoring
+
+Read this guide before changing sections, fields, defaults, navigation data,
+icons, AI metadata, or block slots. The root `AGENTS.md` rules still apply.
+
+## Naming and organization
+
+- Group editor components by page role when using `pageConfig.categories`.
+  Category titles, component labels, and field labels must use `t(...)`.
+- Use short, concrete PascalCase public keys that describe visitor-facing
+  patterns: `HeroImage`, `FeatureCards`, `PricingTable`, `ContactUs`.
+- Avoid theme names, implementation details, and filler suffixes such as
+  `Section`, `Component`, `Block`, `New`, or `Custom`.
+- Prefer semantic variants such as `FeatureCards` and `FeatureList`. Numbered
+  variants are a fallback and need distinct `ai.instructions` explaining their
+  visual or business difference.
+- A top-level `content[].type` is a public component key. A concrete instance's
+  `content[].props.id` is separate and must be stable.
+- Keep one page section per kebab-case `.tsx` file under `src/sections/`, with
+  a small `src/sections/index.ts` registry/export module.
+
+## Field source of truth
+
+Type props first. Use `SudaComponentConfig<Props>`, `SudaFields<Props>`, and
+`defineSudaPageData(pageConfig, data)` to catch shape mismatches. Do not invent a
+parallel Zod schema for theme fields.
+
+Keep these four structures aligned:
+
+1. TypeScript props.
+2. `fields` or local-block fields.
+3. `defaultProps`.
+4. `render`.
+
+Every normal field needs a matching serializable value in `defaultProps`.
+Block-slot props are the exception: their initial composition belongs in the
+slot's `defaultBlocks`, not the host component's `defaultProps`.
+
+All normal prop defaults belong only in `defaultProps`. Starter/CMS data is
+authored instance content, not component defaults. Render props directly; do
+not use `||`, `??`, ternaries, default parameters, or destructuring defaults to
+invent display values. Conditional rendering may remove intentionally optional
+UI, but must not substitute content.
+
+## Field selection
+
+Use the most specific supported field:
+
+- `text`: short labels, headings, slugs, and names.
+- `textarea`: multi-sentence plain copy.
+- `richtext`: authored rich HTML content.
+- `url`: routes, anchors, `mailto:`, and external links.
+- `image`, `video`, `media`: media according to the accepted kind.
+- `icon`: canonical Suda icon names.
+- `color`, `range`, `spacing`: editor-facing design values.
+- `number`, `checkbox`: numeric and boolean values.
+- `select`, `radio`: stable serializable choices.
+- `object`, `array`: grouped and repeatable structured values.
+- `posts`: one dynamic post query on an ordinary page section.
+
+Rules:
+
+- Never use `text` for URLs, media, colors, icons, or structured navigation.
+- Use localized option labels and short stable option values.
+- Add localized labels to nested `arrayFields`, `objectFields`, and local blocks.
+- Add `description` and `placeholder` only when they help editor decisions.
+- Use `visibleIf` for pure synchronous sibling-dependent visibility. Reserve
+  `resolveFields` for heavier changes that `visibleIf` cannot express.
+- Add `ai.instructions`, `ai.required`, `ai.exclude`, `ai.stream`, or `ai.bind`
+  when a field needs generation guidance. Set `ai.stream: false` for atomic
+  values such as URLs.
+- Multi-column grids, lists, pricing tables, galleries, and logo walls expose a
+  `columns` prop with a `range` or `select` field and a sensible default.
+
+Representative field configuration:
+
+```ts
+fields: {
+  title: { type: "text", label: t("common.fields.title") },
+  body: { type: "textarea", label: t("common.fields.description") },
+  href: { type: "url", label: t("common.fields.link") },
+  image: { type: "image", label: t("common.fields.image") },
+  icon: { type: "icon", label: t("common.fields.icon") },
+  columns: {
+    type: "range",
+    label: t("common.fields.columns"),
+    min: 2,
+    max: 4,
+    step: 1,
+  },
+  align: {
+    type: "radio",
+    label: t("common.fields.align"),
+    options: [
+      { label: t("common.options.left"), value: "left" },
+      { label: t("common.options.center"), value: "center" },
+    ],
+  },
+  cards: {
+    type: "array",
+    label: t("common.fields.cards"),
+    defaultItemProps: { title: "Card title", href: "/" },
+    arrayFields: {
+      title: { type: "text", label: t("common.fields.title") },
+      href: { type: "url", label: t("common.fields.link") },
+    },
+  },
+},
+defaultProps: {
+  title: "Welcome",
+  body: "Describe the offer.",
+  href: "/contact",
+  image: themeAsset("assets/hero.jpg"),
+  icon: "sparkles",
+  columns: 3,
+  align: "left",
+  cards: [{ title: "Fast setup", href: "/features" }],
+},
+```
+
+## Navigation and footer menus
+
+Navigation and footer menus are typed arrays. Do not use a legacy menu field,
+textarea, or newline-delimited string. Every destination uses a `url` field.
+TypeScript props, fields, `defaultItemProps`, and component `defaultProps` must
+have exactly the same structure.
+
+Navigation supports at most two levels:
+
+- `navItems[]`
+- `navItems[].submenu[]`
+
+Submenu items contain only label/link fields. Their schema must make a third
+level impossible. An empty `submenu` means an ordinary top-level link.
+
+```ts
+type NavItem = {
+  label: string;
+  href: string;
+  submenu: { label: string; href: string }[];
+};
+
+const navItemsField = {
+  type: "array",
+  label: t("common.fields.navigationItems"),
+  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"),
+      defaultItemProps: { label: "About", href: "/about" },
+      arrayFields: {
+        label: { type: "text", label: t("common.fields.label") },
+        href: { type: "url", label: t("common.fields.link") },
+      },
+    },
+  },
+};
+```
+
+Footer grouped menus use exactly two array levels: `columns[]` and
+`columns[].links[]`. A column has a title and links; a link has text and URL.
+Do not add another nested group.
+
+## Icons
+
+Interaction and UI-state icons may be fixed when their identity is intrinsic to
+the control: menu, close, previous/next, expand/collapse, loading.
+
+Icons that communicate authored content are props:
+
+- Declare `{ type: "icon" }` and type values as `SudaIconName`.
+- Put initial icon selections in `defaultProps`, including nested array/object
+  values.
+- Render the value with `SudaIcon` from `@sudajs/theme-engine/icons`.
+- Do not hardcode content icon names or icon components inside `render`.
+
+Use canonical Lucide names such as `"rocket"` or `"mouse-pointer-click"`, not
+`"lucide-rocket"`. Use namespaced Simple Icons brand names such as
+`"simple-icons:github"`. The engine supports Lucide Icons and Simple Icons; do
+not add another icon library unless neither can represent a required icon. Do
+not create theme-local icon maps, emoji switches, SVG registries, or custom icon
+systems unless the theme genuinely needs a bespoke graphic.
+
+## AI metadata
+
+Every page and layout component declares useful `ai.instructions`. Missing
+component-level instructions fail `suda theme check` and block publishing.
+Instructions should cover:
+
+- purpose and business role;
+- use/avoid conditions;
+- normal placement;
+- expected frequency;
+- composition or neighboring sections when relevant.
+
+Use `ai.exclude: true` only for structural/editor-only components, and explain
+why AI must not generate them. `PageOutlet` is the standard example.
+
+## Block slots
+
+Use `blockSlots` when a section owns controlled local content such as actions,
+pricing cards, feature rows, stats, timeline items, or contact methods.
+
+- Type the slot prop as Puck `Slot` and use the same prop key in `blockSlots`.
+- Do not create native `fields.<key>.type = "slot"` entries.
+- Define allowed local kinds under `blockSlots.<slotName>.blocks`.
+- Every local block needs a localized `label`, typed fields, `defaultProps`,
+  `render`, and useful AI instructions when applicable.
+- Local blocks belong only to their owning section and cannot contain nested
+  block slots.
+- Initial composition belongs in `defaultBlocks`; do not put the slot prop in
+  host `defaultProps`.
+- Never put `id` in local block `defaultProps`, `defaultBlocks[].props`, or
+  authored nested items. The editor/runtime owns local ids.
+
+```tsx
+type HeroProps = { title?: string; actions?: Slot };
+
+export const Hero: SudaComponentConfig<HeroProps> = {
+  label: t("sections.hero.label"),
+  ai: { instructions: "Primary landing-page introduction. Use once near the top." },
+  fields: {
+    title: { type: "text", label: t("sections.hero.fields.title") },
+  },
+  blockSlots: {
+    actions: {
+      label: t("sections.hero.blocks.actions"),
+      blocks: {
+        button: {
+          label: t("sections.hero.blocks.button"),
+          fields: {
+            label: { type: "text", label: t("sections.hero.blocks.buttonLabel") },
+            href: { type: "url", label: t("sections.hero.blocks.buttonHref") },
+          },
+          defaultProps: { label: "Get started", href: "/contact" },
+          render: ({ label, href }) => <a href={href}>{label}</a>,
+        },
+      },
+      defaultBlocks: [{ kind: "button" }],
+    },
+  },
+  defaultProps: { title: "Build with SudaCloud" },
+  render: ({ title, actions: Actions }) => (
+    <section>
+      <h1>{title}</h1>
+      <Actions />
+    </section>
+  ),
+};
+```
+
+Authored page data uses the public host type and short local kind:
+
+```ts
+{
+  type: "Hero",
+  props: {
+    id: "Hero-1",
+    title: "Welcome",
+    actions: [{ type: "button", props: { label: "Contact us", href: "/contact" } }],
+  },
+}
+```
+
+Never write internal types such as
+`__suda_local_block__/Hero/actions/button`; those are generated only for Puck
+internals.

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

@@ -0,0 +1,170 @@
+# Design and Runtime
+
+Read this guide before changing the theme contract, manifest, layout, design
+tokens, CSS, assets, contact forms, or runtime metadata. The root `AGENTS.md`
+rules still apply.
+
+## Theme contract
+
+- Keep `renderMode: "ssr"` in `src/manifest.ts`.
+- Keep source entries at `src/index.tsx` and `src/styles.css`.
+- Export a complete `ThemeModule`: `manifest`, `pageConfig`, `layoutConfig`,
+  `defaultLayout`, `starterPages`, and `cmsTemplates`.
+- Keep page sections in `pageConfig`; keep the root, Header, PageOutlet, Footer,
+  and necessary global chrome in `layoutConfig`.
+- If browser-only setup is required, export `clientHooks` from `src/client.ts`.
+  Do not export theme config there and do not add `src/runtime.client.ts(x)`;
+  the CLI generates `dist/runtime.client.js`.
+- React, React DOM, Puck, and `@sudajs/theme-engine` are host-provided peers.
+  Do not bundle private copies into the runtime.
+- Keep persisted props JSON-serializable. Never persist functions, React nodes,
+  class instances, media database ids, or absolute local paths.
+- Do not edit generated files under `dist/`.
+
+Starter routes in `suda theme dev` are site-like root routes such as `/index`
+and `/contact-us`, never `/pages/...`.
+
+## Layout
+
+- Render Header and Footer exactly once from `defaultLayout`, with PageOutlet
+  between them and stable top-level ids.
+- Do not include layout chrome in starter pages or CMS templates.
+- Root config renders layout children. PageOutlet reads the page slot through
+  `getPageSlot(puck?.metadata)`.
+- Native Puck slots are limited to engine layout/container primitives and theme
+  layout components. Page sections use Suda `blockSlots` for controlled nested
+  content.
+- Read platform-owned values such as white-label and ICP/public-security
+  records from runtime metadata helpers. Do not copy them into static props.
+- Read public language links from `getSiteLocale(puck?.metadata)` and render the
+  provided label/href instead of constructing locale URLs.
+
+Read `editor-compatibility.md` as well whenever layout positioning or client
+behavior changes.
+
+## Design system
+
+Build the entire theme from one editable design system. Sections, CMS views,
+block slots, and starter pages must not invent independent palettes, type
+scales, radii, shadows, or spacing.
+
+- Define `sourceManifest.designSystem` in `src/manifest.ts` with `version`,
+  `defaultPresetId`, and complete named presets.
+- Use stable engine token keys. At minimum define every color token the theme
+  consumes (`background`, `foreground`, `primary`, `primaryForeground`,
+  `secondary`, `secondaryForeground`, `accent`, `accentForeground`, `muted`,
+  `mutedForeground`) and consumed radius tokens (`card`, `button`, `input`).
+- Do not invent platform-facing token names without checking generated types.
+- Expose `designSystemField(...)` only at the layout root and initialize it with
+  `createThemeDesignDefault(sourceManifest.designSystem)`.
+- Resolve tokens once in the root with
+  `resolveThemeDesignTokens(sourceManifest.designSystem, props.designSystem)`
+  and apply `createThemeDesignCssVariables(tokens)` there. Sections consume CSS
+  variables; they do not resolve presets independently.
+
+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 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:
+
+```css
+.my-theme-root {
+  --my-theme-primary-hover: color-mix(in srgb, var(--suda-color-primary) 84%, black);
+}
+
+.my-theme-button:hover {
+  background: var(--my-theme-primary-hover);
+}
+```
+
+Build/check/publish reject hand-written consumption of Suda-backed Tailwind
+aliases.
+
+## Visual consistency
+
+- Centralize typography and spacing scales in `src/styles.css`.
+- Reuse container, section padding, heading, eyebrow, body, card, button, input,
+  and media-frame patterns.
+- Section props expose semantic decisions such as `tone`, `variant`, `columns`,
+  `mediaPosition`, `showImage`, or `spacing`, then map them to shared tokens and
+  classes.
+- Do not expose raw color, typography, spacing, radius, or shadow fields merely
+  because CSS contains a value. Expose a design control only when editors should
+  intentionally customize it per instance.
+- Use `color` and `spacing` fields only for real editor-facing controls; use
+  `select`/`radio` for named design-system variants.
+- Local blocks inherit their host section's design system and should not define
+  independent palettes, type scales, radii, shadows, or spacing.
+- CMS sections and ordinary post sections use the same containers, typography,
+  cards, media ratios, pagination, and states as the rest of the theme.
+- Starter pages demonstrate one coherent design system. Vary content, order,
+  media, and semantic variants rather than hardcoding unrelated styles.
+- Add a shared utility/token when multiple sections need it or the theme needs
+  a named pattern, not for one-off styling.
+
+## Styling and assets
+
+- Tailwind v4 starts in `src/styles.css` with `@import "tailwindcss";` and
+  `@source "./**/*.{ts,tsx}";`.
+- Scope theme CSS with generated theme-key classes. Avoid global resets that
+  affect the host editor or other themes.
+- Theme-local assets live in top-level `assets/` and are copied to
+  `dist/assets/` during build.
+- Use `themeAsset("assets/...")` for bundled assets in `defaultProps`, starter
+  pages, CMS templates, and AI examples.
+- Do not import theme-local images from React code or hand-write
+  `themes/<themeKey>/<version>/...` paths. Full external CDN URLs are valid.
+- Resolve user-selected media with `resolveAsset(puck?.metadata, value)` before
+  rendering.
+- Required preview screenshots are `assets/preview/desktop.png`,
+  `assets/preview/tablet.png`, and `assets/preview/mobile.png`; generate them
+  with `suda theme capture`.
+- Customize Vite, PostCSS, and Tailwind configuration only when necessary.
+- Do not modify minified vendor CSS. Use precise scoped overrides unless an
+  explicitly maintained vendor patch is unavoidable.
+
+## Contact forms
+
+When a theme offers a contact section, render the host-provided form from
+`metadata.contactForm`. The platform owns field configuration, validation,
+submissions, notifications, webhooks, permissions, and limits; the theme owns
+public presentation only.
+
+- Read the form through `getContactForm(puck?.metadata)` from
+  `@sudajs/theme-engine/runtime`.
+- `suda theme dev` passes a default form through `metadata.contactForm` for
+  local preview.
+- If no valid enabled form exists, render nothing for the form area. Do not
+  show a public unavailable/error fallback panel.
+- Support and style `text`, `textarea`, `checkbox`, `radio`, and `select` fields.
+- Render labels, keyboard focus, submit state, success state, validation errors,
+  and mobile layout accessibly.
+- Use only placeholders supplied by form settings. Do not invent placeholders,
+  including an empty select option.
+- Submit field values to `contactForm.endpoint`.
+- Never hardcode notification channels, recipients, webhook URLs, ICP records,
+  or white-label branding in the section.
+- Render hidden platform fields, including
+  `name={contactForm.honeypotField}`, as bare `<input type="hidden" />` nodes.
+  Do not wrap hidden inputs in labels, layout rows, grids, or visual field
+  components.
+
+## Verification
+
+Before handoff:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm build
+pnpm validate
+suda theme check
+```
+
+Run `suda theme capture` after visual changes and compare desktop, tablet, and
+mobile output in editor preview and on the public site.

package/templates/theme/docs/agent-guides/editor-compatibility.md

@@ -0,0 +1,231 @@
+# Editor Compatibility
+
+Read this guide before changing Header, Footer, PageOutlet, sticky/fixed UI,
+transparent navigation, carousels, dropdowns, editor CSS, or client behavior.
+Every public component must render consistently on the public site, in the Puck
+Editor iframe, and in editor preview mode.
+
+## Stable roots and Puck mutation
+
+Puck may attach selection/drag attributes and inline positioning directly to
+the first real 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>`.
+- Every public component should return one stable semantic real DOM root when
+  it controls spacing, background, sizing, stacking, positioning, or selection.
+- Do not use a Fragment or `display: contents` for roots with those jobs.
+- `PageOutlet` needs a real element when it owns overlap, negative margin,
+  positioning, or sizing.
+- `:has(.component-root)` does not match an element that is itself the root.
+  Cover both shapes when either can occur:
+
+```css
+.component-root[data-puck-component],
+[data-puck-component]:has(.component-root) {
+  /* compatibility rule */
+}
+```
+
+Puck's inline `position: relative` beats ordinary CSS. If the actual root must
+remain `sticky`, `fixed`, or `absolute`, use a precise editor-scoped rule with
+`!important`. Never apply `position: relative !important` to every editor
+component; it breaks navigation, overlays, and floating controls.
+
+## Editor scope and iframe height
+
+Derive editor state from `puck?.metadata?.isEditor === true` and expose a stable
+theme-root marker:
+
+```tsx
+<div className="theme-root" data-suda-editor={isEditor ? "true" : undefined}>
+  {children}
+</div>
+```
+
+Keep editor-only fixes below `.theme-root[data-suda-editor="true"]`. Do not
+globally override `.navbar`, `.section`, `[data-puck-component]`, or public-site
+layout to repair the editor.
+
+The editable page scrolls inside a same-origin iframe. The outer canvas/frame
+may be only one viewport tall, so the iframe document must remain content-height
+driven:
+
+- Use `height: auto`, `min-height: 100vh`, and `overflow: visible` on the editor
+  theme root unless the theme requires a different proven arrangement.
+- Ensure Puck's `#frame-root` and root `[data-puck-dropzone]` can grow with
+  content. Avoid `height: 100%` when it collapses the page to one viewport.
+- Be careful with global `html`, `body`, `iframe`, `.hidden`, `img`, `button`,
+  `input`, and Tailwind preflight rules.
+- Put third-party compatibility overrides in scoped `src/styles.css`; do not
+  change public behavior globally or patch minified vendor CSS.
+- Scroll through every starter page in edit mode. All components must be
+  reachable without selecting them from the outline first.
+
+## Sticky and fixed positioning
+
+Before implementing Header, announcement bars, floating CTAs, or any
+sticky/fixed element, identify:
+
+1. The real positioned root and whether Puck mutates it.
+2. The actual scroll element in the public site and editor iframe.
+3. The intended sticky containing block.
+4. Every ancestor with `overflow`, `transform`, `filter`, `perspective`, or
+   `contain` that may change positioning.
+5. Whether the sticky parent is taller than the sticky element.
+6. Explicit `top` and `z-index` values.
+7. Whether iframe and outer-canvas coordinate systems differ.
+
+For a layout Header, put sticky behavior on its real root. If that node receives
+`data-puck-component`, correct Puck's inline position on that same node. Site and
+editor may use different mechanics only when their visual result remains
+equivalent.
+
+Example covering both possible DOM shapes:
+
+```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;
+}
+```
+
+## Transparent navigation
+
+Transparent navigation is coordinated state and layout, not only a transparent
+background. Handle all of these together:
+
+- background and shadow;
+- logo, menu text, and button colors;
+- Hero/PageOutlet overlap beneath Header;
+- transition to the solid state after a scroll threshold;
+- Puck root-position mutation;
+- identical SSR-first-frame and hydrated state.
+
+Never render white logo/text above an accidentally white Header. Prefer React
+Context for a page's transparency request, an SSR-readable DOM marker for the
+first frame, and a real PageOutlet element for editor overlap. The public site
+may use a spacer or equivalent layout strategy. Keep shared measurements in a
+theme CSS variable such as `--theme-navigation-height`.
+
+## Scroll detection
+
+Do not rely only on `window.scrollY` or a window scroll listener. The source may
+be `document.scrollingElement`, the iframe document, or a nested
+`overflow: auto/scroll` element, and scroll does not bubble.
+
+- Find the nearest scrollable ancestor for each navigation instance and read
+  that element's `scrollTop`.
+- Listen on the document with capture and passive mode:
+
+```ts
+document.addEventListener("scroll", handler, { capture: true, passive: true });
+```
+
+- Keep a window listener for public-site compatibility.
+- Never assume site and editor use the same scroll element.
+
+## Client lifecycle
+
+Runtime code must tolerate editor remounts, live prop updates, HMR, React Strict
+Mode effect replay, frequent `MutationObserver` callbacks, and scripts loading
+after `DOMContentLoaded`.
+
+- Make initialization and event binding idempotent.
+- Observe components inserted later and only relevant attribute changes.
+- Do not use a permanent `window.__xxxBound` flag that blocks HMR reinitialization.
+- Clean up effects, observers, timers, and listeners.
+- Keep SSR markers and client state synchronized.
+- Put optional browser setup in `clientHooks` from `src/client.ts`; never add
+  `src/runtime.client.ts(x)`.
+
+## Editor interactions
+
+Edit mode may effectively disable descendant interaction:
+
+```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 bug. Never globally restore descendant pointer events because that
+breaks selection and drag behavior. Test visitor interaction in editor preview
+and on 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 from the layout; do not repeat them in
+  starter pages or CMS templates.
+- When moving chrome into the layout, remove duplicates from starter pages,
+  CMS templates, page categories, and AI examples.
+- Give Header, PageOutlet, and Footer stable ids, with PageOutlet between Header
+  and Footer.
+- Read white-label, ICP, and other footer metadata from runtime metadata; do not
+  persist duplicated platform values in component data.
+
+## Vendor CSS
+
+Do not modify original third-party minified CSS unless the task explicitly
+requires a maintained vendor patch. Prefer precise selectors in scoped
+`src/styles.css`. If a patch is unavoidable, document the reproducible problem
+and why an override cannot solve it.
+
+## Completion checklist
+
+For a new theme, verify:
+
+- stable real roots and an editor root marker;
+- layout-owned Header, PageOutlet, and Footer with stable ids;
+- Header sticky behavior in editor and site modes;
+- transparent navigation first frame and scrolled state;
+- correct scrollable-ancestor detection;
+- idempotent runtime setup and cleanup;
+- real-element PageOutlet overlap behavior;
+- responsive behavior; and
+- editor preview versus public-site parity.
+
+Whenever Header, Footer, PageOutlet, transparent navigation, sticky/fixed UI,
+carousel, dropdown/mobile menu, or a `100vh` Hero changes, test:
+
+- public SSR first frame and post-hydration state;
+- editor desktop, tablet, and mobile;
+- edit and preview modes;
+- top state and state after crossing scroll thresholds;
+- HMR and live prop updates;
+- exactly one Header and one Footer; and
+- intact Puck selection and dragging.
+
+## Debugging order
+
+When editor and site differ, inspect in this order before changing CSS:
+
+1. The component's actual root.
+2. The node receiving `data-puck-component`.
+3. Inline styles on that node.
+4. Computed `position`, `background`, `z-index`, and ancestor `overflow`.
+5. The actual scroll element and its `scrollTop`.
+6. Iframe versus outer-canvas coordinates.
+7. Whether client runtime initialized.
+8. Transparent-state context and SSR DOM markers.
+9. Stylesheet loading and cascade order.
+
+Do not guess selectors repeatedly before confirming DOM and computed styles.