Layout widgets

A layout widget renders no content of its own. It declares named slots, the customer binds other widgets into them, and the platform hands your component the already-rendered children as renderedSlots. A layout can also replace the platform’s own page layout on a server-rendered page.

Layouts exist only in the suite (multi-widget) manifest shape. resolvePluginWidget hardcodes category: "content" for every v1 single-widget manifest (packages/homerunner-widget-core/src/manifest.ts), so a single-widget plugin can never ship a layout — and the shape is frozen at first publish. See The two manifest shapes.

Everything on this page needs widget-core 0.11.0+, except pages (0.12.0+) and slots[].prefill (0.12.1+).

Enforcement levels used below — publish ERROR, publish warning, silent runtime truncation, advisory (unvalidated) — are defined once in Limits and error index.

Requirements at a glance

A layout is not allowed to nest inside another layout, and its shell can never be interactive on a server-rendered page. Both are covered below.

Manifest: category

At resolve time the rule is summary.category === "layout" ? "layout" : "content" — anything that is not the literal layout silently becomes a content widget, taking slots and pages with it (both resolve to undefined on content widgets).

Rendering a layout through the content path is refused:

// packages/homerunner-renderer/lib/render-utils.tsx — console.warn, then a failure node
[plugin] "plugin:my-suite:frame" is a layout widget — it must render as a layout entry (with slots), not content. Skipping.
// failure-node reason:
plugin layout widget rendered as content — needs a layout entry with slots

Manifest: slots[]

slots is layouts-only. Declare one entry per region your component renders.

// pdp-suite 1.3.3 (the reference suite) — manifest.json, the pdp-frame summary
{
  "slug": "pdp-frame",
  "name": "PDP Frame",
  "category": "layout",
  "slots": [
    { "name": "hero",    "prefill": ["property-title", "gallery"] },
    { "name": "main",    "prefill": ["property-meta", "bednbath", "description", "amenities", "calendar"] },
    { "name": "sidebar", "prefill": ["booking"] },
    { "name": "bottom",  "prefill": ["reviews"] }
  ],
  "ssr": { "url": "dist/pdp-frame/pdp-frame-ssr.umd.js" },
  "assets": {
    "js": "dist/pdp-frame/pdp-frame.iife.js",
    "css": "dist/pdp-frame/pdp-frame.css",
    "fonts": ["https://fonts.googleapis.com/css2?family=Playfair+Display:wght@600;700&display=swap"]
  },
  "manifest": "widgets/pdp-frame.manifest.json",
  "pages": ["pdp", "misc"],
  "icon": "media/pdp-frame.svg",
  "readme": "media/widgets/pdp-frame.md"
}

The name check breaks out of the slot loop on the first bad entry, so a manifest with two problems reports one error per audit run — fix and re-run.

A slot the manifest declares is not automatically a slot that renders. What renders is derived from the customer’s stored bindings; see settings.slots and Page assignment.

slots[].accepts

accepts is read by exactly one consumer: the playground’s slot editor. A candidate widget is offered when accepts contains its category (content / layout) or its exact keyword (gallery, plugin:acme:hero). The layout’s own keyword is always excluded, so a layout can never bind another instance of itself.

// src/app/(protected)/feeds/[id]/widgets/[widgetId]/[widgetName]/playground/PlayGround.tsx
const accepts = slot.accepts?.length ? slot.accepts : ["content"];
const filterFn = (keyword: string) =>
  typeof keyword !== "string" ||
  (keyword !== widget.keyword &&
    (accepts.includes(categoryOf(keyword)) || accepts.includes(keyword)));

Not supported yet. accepts: ["layout"] can never admit anything. The same picker is always rendered with excludeLayouts, which drops every layout-category row before the accepts predicate runs — and even a hand-crafted binding is skipped by both render paths, because layouts cannot nest.

accepts is not validated at publish and is not read by the renderer. Treat it as a hint to the customer, never as a guarantee about what your slot will contain.

slots[].prefill

(widget-core 0.12.1+) prefill lists the system widget keywords a slot expects. When a customer creates the layout, the dashboard binds the feed’s existing widget for each keyword so the layout opens populated instead of empty.

What the dashboard does at creation time, in order:

1. Union every slot’s prefill keywords, in declared order.
2. Create the ones the feed has no active widget for, with the platform’s own defaults. A keyword this platform cannot create is reported in a toast as {keyword}: not a widget this platform can create and skipped.
3. Bind the feed’s oldest active widget per keyword (status === false widgets are skipped), in declared order, deduped within a slot.
4. Merge the result into the new widget’s settings.slots. Slots that resolved to no ids are omitted entirely — the key never appears.

Prefill is creation-time only. It is never re-applied to an existing layout, and the renderer never reads it.

Not supported yet. prefill keywords are shape-validated only. Nothing checks them against the real system-widget keyword list, so a typo publishes cleanly and silently prefills nothing.

The mandatory slots config field

The dashboard’s slot editor is injected into your own config form. For each manifest slot it writes a SlotWidgetArrayContainer of WidgetSelect rows under the form’s slots object field. If your zod config does not declare that field, there is nowhere to store bindings and the customer’s edits are dropped on save.

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/config.ts
export const configZod = widgetSchema.extend({
  showSlotLabels: z.boolean().default(false).describe("Show slot region labels"),
  stickyRail: z.boolean().default(true).describe("Keep the sidebar rail pinned"),
  // Keys MUST match the manifest summary's slot names, exactly.
  slots: z
    .object({
      hero: z.array(z.string()).default([]),
      main: z.array(z.string()).default([]),
      sidebar: z.array(z.string()).default([]),
      bottom: z.array(z.string()).default([]),
    })
    .default({})
    .describe("Widgets bound into each region"),
});

export const configSchema = zodToManifestSchema(configZod);

Rules:

• The object keys must equal the manifest slot names, character for character. A key with no matching manifest slot gets no editor; a manifest slot with no key has nowhere to save.
• Use z.array(z.string()).default([]) per slot and .default({}) on the object. Both defaults matter: the field must survive configZod.parse({}) at creation time.
• Do not add a uiSchema entry for slots. The dashboard replaces the whole slots key with its own panel: label Slot Configuration, description “Assign the widgets that render inside this layout’s slots”, order: -50 (it sorts to the top). Each row is titled {slot} slot with the description accepts: {list}. See Config schema and UI schema for why a plugin entry replaces a top-level key wholesale.

settings.slots: the stored bindings

Bindings are stored on the layout widget instance, not in the manifest:

// Read by packages/homerunner-widget-core/src/runtime/layout-csr-renderer.tsx (CSR)
// and packages/homerunner-renderer/lib/render-utils.tsx (SSR), out of widget.settings
"slots": {
  "hero":    ["cuid-of-a-widget", "cuid-of-another"],
  "sidebar": ["cuid-of-a-third"]
}

Record<slotName, widgetId[]>. Array order is render order.

• CSR reads it structurally out of the widget’s settings and resolves each id to its keyword.
• SSR converts the ids to slot bindings and drops ids whose widget no longer exists on the feed (nothing prunes a slot when a widget is deleted).
• On an assigned page, the slot names the PDP renders are the keys present in the stored settings.slots — a slot the customer never bound simply does not appear. See Page assignment.

Settings arrive at your component raw — never zod-parsed for plugins, on either path. Parse them yourself; see Settings and options.

The component contract

Import the real type rather than hand-rolling it:

// packages/homerunner-widget-core/src/contracts.ts
export interface LayoutWidgetProps<
  T extends WidgetSchemaType = WidgetSchemaType,
  D extends Record<string, any> | undefined = undefined,
> extends WidgetProps<T, D> {
  /** Pre-rendered React nodes for each slot. Keys are slot names. */
  renderedSlots: Record<string, ReactNode>;
}
// import type { LayoutWidgetProps } from "@homerunner-next/widget-core/contracts";

What each path actually passes:

LayoutWidgetProps declares widgetType as required, but the SSR path does not supply it. Reading it during render is a hydration-mismatch trap — treat both widgetType and target as optional in a layout.

renderedSlots differs between the paths for an empty slot:

• SSR: the key is present only when at least one child actually rendered. An unbound slot, or one whose every binding was dropped, is undefined.
• CSR: every key of the stored settings.slots is present; an empty slot is [] — truthy, and renders nothing.

Write renderedSlots?.[name] ?? null and never assume a key exists.

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/widget.tsx
import React, { type ReactNode } from "react";
import { parseWidgetConfig } from "@homerunner-next/widget-core/schema";
import { configZod } from "./config";
import "./pdp-frame.css";

export default function PdpFrame(props: {
  options?: Record<string, unknown>;
  renderedSlots?: Record<string, ReactNode>;
}) {
  const cfg = parseWidgetConfig(configZod, props.options ?? {});
  const slots = props.renderedSlots ?? {};

  const region = (name: string, node: ReactNode) => (
    <section className={`pdpf-region pdpf-${name}`} data-testid={`pdpf-${name}`}>
      {cfg.showSlotLabels ? <span className="pdpf-label">{name}</span> : null}
      {node ?? (cfg.showSlotLabels ? <div className="pdpf-empty">empty “{name}” slot</div> : null)}
    </section>
  );

  return (
    <div className={`pdpf${cfg.stickyRail ? " pdpf-sticky-rail" : ""}`} data-testid="pdp-frame">
      {region("hero", slots.hero)}
      {region("main", slots.main)}
      {region("sidebar", slots.sidebar)}
      {region("bottom", slots.bottom)}
    </div>
  );
}

The SSR entry is one line — a layout needs no getInitialData, dehydrateState or getStaticAssets:

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/ssr-entry.ts
// SSR entry — the renderer hands `renderedSlots` to the default export.
export { default } from "./widget";

Those three hooks are still supported on a layout and run before the shell renders, inside the same try/catch. A throw in any of them replaces the whole layout with a failure node. See Component and SSR module.

Registration and mount

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/index.tsx
import { mount } from "@homerunner-next/widget-core/runtime";
import { registerPluginWidget } from "@homerunner-next/widget-core/globals";
import PdpFrame from "./widget";
import "./pdp-frame.css";

registerPluginWidget("pdp-suite", "pdp-frame", PdpFrame, { category: "layout" });

function doMount() {
  document
    .querySelectorAll<HTMLElement>("[data-hr-widget-container]")
    .forEach((container) => {
      if (container.querySelector('[data-hr-widget="plugin:pdp-suite:pdp-frame"]')) {
        mount(container, {
          widget: PdpFrame,
          widgetType: "plugin:pdp-suite:pdp-frame",
          category: "layout",
        });
      }
    });
}

if (document.readyState === "loading") {
  document.addEventListener("DOMContentLoaded", doMount);
} else {
  doMount();
}

registerPluginWidget(plugin, widget, Component, { category: "layout" }) writes

// packages/homerunner-widget-core/src/globals.ts
window.HRPlugins["{pluginSlug}:{widgetSlug}"] = { component, category: "layout" };

category is omitted from the registry entry when you do not pass meta.category.

mount derives an effective category for plugin keywords as config.category ?? getRegisteredWidget(widgetType)?.category. The registry write sits in the same IIFE and therefore always precedes the mount, so a bootstrap that forgets category on the mount() call still routes correctly. Pass it anyway — it is the documented contract and it makes the file readable. See Runtime, mount and the DOM contract for the full MountConfig.

Omitting it in both places is the one genuinely destructive mistake here. Without an effective category, mount treats the shell as a content widget: the SSR no-op guard never fires, and because a layout shell carries no data-hr-ssr-id and no props-registry entry there is nothing to hydrate — so it takes the client-render path and replaces the server’s shell, slot children and all, with an empty client render.

How a layout renders

SSR: the server composes your children

On a server-rendered page the renderer:

1. Collects every binding across every slot. A binding whose widget is missing from the feed is logged [layout] Slot "{name}" references missing widget {id} and skipped.
2. Renders all slot children concurrently. Each child is a full island with its own SSR id, its own Declarative Shadow DOM template, its own props-registry entry and its own assets.
3. Reassembles each slot in binding order into renderedSlots[slotName] = <>{nodes}</>.
4. Loads your layout’s SSR bundle last, runs the optional data hooks, renders the shell, and unshifts the layout’s CSS and JS in front of every child’s assets.

The shell is emitted as static light DOM:

// packages/homerunner-renderer/lib/render-utils.tsx
<div
  data-hr-widget={widgetConfig.type}
  data-hr-widget-category="layout"
  id={`${widgetConfig.id}:${widgetConfig.feed.id}`}
  {...layoutHostThemeAttrs(/* data-hr-scheme="auto" or data-hr-theme="light|dark" */)}
>
  <LayoutComponent {...props} />   {/* no <template shadowrootmode>, no shadow root */}
</div>

Three consequences that look like bugs and are not:

• No shadow root, no DSD template. Your layout stylesheet is loaded document-level, at page scope. See Layout CSS.
• No data-hr-ssr-id and no props-registry entry. Only slot children get those.
• The client mount is a deliberate no-op. mount returns early when the effective category is layout and the root already has server-rendered children. Running the CSR path there would discard the server’s slots and re-fetch everything client-side.

Not supported yet. Because of the three points above, a plugin layout shell can never be interactive on a server-rendered page: no React tree is ever attached to it. Its slot children each hydrate themselves normally. Put interactivity in a content widget and bind it into a slot.

CSR: the layout composes its own children

In a single-snippet embed the shell does get a shadow root, and LayoutCsrRenderer rebuilds the slot tree at runtime:

1. Fetch the layout widget + feed, read settings.slots.
2. Per child id: fetch its widget row to learn its keyword, skip nested layouts, load the child’s IIFE so it self-registers, then wait for registration (hard 10 s timeout, per child: [widget-core] widget "{keyword}" did not register within 10000ms → that slot child stays empty, the rest render).
3. Render your component with renderedSlots = arrays of childless host divs ([data-hr-widget-container] > [data-hr-widget={keyword}][data-hr-options]).
4. After commit, imperatively mount each child into its host.

Child script URLs come from config.resolveChildJsUrl or, by default, window.HRWidgetRuntime.resolveChildJsUrl — supplied by the host runtime bundle. Plugin builds carry no URL rules and you never script-tag children yourself.

The layout pushes two things onto every child: the reserved __parentColorScheme key (which only affects children whose own colorScheme is global) and, when the layout resolves one, filter.property. Reading the pushed property is covered in Composing a page.

Failure semantics

Parse defensively and default every slot. A content widget that throws costs one widget; a layout that throws costs the customer’s whole page.

Every failure reason a layout can produce, verbatim:

// packages/homerunner-renderer/lib/render-utils.tsx
// Content path — a layout keyword rendered as a plain content entry.
keyword does not resolve against the plugin manifest
plugin layout widget rendered as content — needs a layout entry with slots

// Layout path — every throw is wrapped as `layout SSR data prep failed: {message}`.
layout SSR data prep failed: keyword does not resolve against the plugin manifest
layout SSR data prep failed: "plugin:{slug}:{widget}" is not a layout widget (category: content)
layout SSR data prep failed: plugin layout widgets require an SSR bundle (`ssr: false` is content-only)
layout SSR data prep failed: SSR bundle failed to load from {url}

// A slot child that is itself a SYSTEM layout.
layout-in-layout nesting not allowed

A slot child that is a plugin layout produces no breadcrumb at all — it is dropped with a console line and the rest of the slot renders.

Layouts cannot nest

Refused on both paths, before anything renders:

// packages/homerunner-renderer/lib/render-utils.tsx — SSR, checked against the summary's category
[layout] Plugin layout widgets are not supported in slots yet. Slot "{name}" references "{keyword}". Skipping.

// packages/homerunner-widget-core/src/runtime/layout-csr-renderer.tsx — CSR, checked against the registration
[layout-csr] Skipping nested plugin layout child "{keyword}" — layouts cannot nest.

System layouts are caught separately by their -layout keyword suffix. Nothing in the manifest expresses “this layout may nest”.

Layout CSS

A layout stylesheet must work in two environments:

• Document level, unisolated, on every server-rendered page (the shell is light DOM and your CSS is appended to the page <head>).
• Inside a shadow root, on a CSR embed.

The rules that follow from that:

Your layout’s CSS is unshifted ahead of the slot children’s stylesheets in the page’s CSS list, so a child’s rules win on source order at equal specificity.

/* pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/pdp-frame.css */
/* Light-DOM-safe shell: class-based rules only, no :host-only styles, no
   painted background (the same CSS also runs inside a shadow root on CSR
   embeds). */
.pdpf {
  display: grid;
  grid-template-columns: minmax(0, 1fr) 360px;
  grid-template-areas:
    "hero sidebar"
    "main sidebar"
    "bottom bottom";
  gap: 28px 32px;
  align-items: start;
}
.pdpf-hero { grid-area: hero; }
.pdpf-main { grid-area: main; }
.pdpf-sidebar { grid-area: sidebar; }
.pdpf-bottom { grid-area: bottom; }
.pdpf-sticky-rail .pdpf-sidebar { position: sticky; top: 24px; }

@media (max-width: 860px) {
  .pdpf {
    grid-template-columns: 1fr;
    grid-template-areas: "hero" "sidebar" "main" "bottom";
  }
  .pdpf-sticky-rail .pdpf-sidebar { position: static; }
}

Plugin layouts do not inherit the platform’s slotSpacing / gap settings — declare your own spacing fields. See Styling and theming.

pages and page assignment

(widget-core 0.12.0+) pages declares the server-rendered pages a layout may be assigned to. Being assignable is an explicit declaration, never an accident.

// packages/homerunner-widget-core/src/manifest.ts
export const PLUGIN_PAGE_KEYS = ["pdp", "listings", "checkout", "confirmation", "collection", "misc"] as const;

At resolve time unknown keys are dropped and an absent or empty list becomes ["misc"] — silent, not an error. Content widgets always resolve pages: undefined.

Not supported yet. collection is declared vocabulary with no assignment surface. The collection-route picker only offers instances of the system listings-layout keyword, so a plugin layout declaring collection cannot be chosen anywhere.

What the customer does

Feed → Page URLs → Page layouts: one row per server-rendered page, each a picker of Automatic plus every eligible layout on the feed. Your layout appears there when its plugin is approved and enabled on the feed, the widget is not kill-switched, and its summary declares that page. The assignment is stored on the feed at:

// src/lib/homerunner/reverse-proxy-routes.ts + packages/homerunner-renderer/lib/page-layouts.ts
feeds.additional_info.reverseProxy.pageLayouts = { pdp?, listings?, checkout?, confirmation? }

Absent or null means Automatic (the feed’s base system layout for that page).

What the renderer does with an assignment

An assigned plugin layout renders with backfill: false — stored bindings only. Unlike a system layout, nothing is backfilled from the platform’s default slot map, so a slot the customer never bound simply does not appear. Bindings pointing at deleted widgets are dropped first.

The slot names the page renders differ by page, and this is the sharpest edge in the whole contract:

So a layout that declares listings, checkout or confirmation must name one of its slots exactly content and the customer must bind at least one widget into it. Every other slot you declare receives nothing on those three pages. Their handlers return {"error":"Explorer widget not found for this feed"}, {"error":"Checkout widget not found for this feed"} and {"error":"Confirmation widget not found for this feed"} respectively, with HTTP 404 — the page does not degrade, it fails.

For the property page, mirror the system layout’s slot vocabulary — hero, main, sidebar, bottom — so the platform’s own widgets drop straight in.

Degrading to Automatic

Anything the renderer cannot honour falls back to Automatic and never 404s the page. Each reason is logged once:

// packages/homerunner-renderer/lib/page-layouts.ts
[page-layouts] feed {feedId} {page}: {reason} — using Automatic

// reasons:
assigned layout {id} is not on the feed (deleted or paused)
assigned widget {id} ({keyword}) is not a layout for "{page}"
assigned plugin layout {id} ({keyword}) is not live (plugin suspended, widget disabled, or not enabled on the feed)
assigned plugin widget {id} ({keyword}) does not declare the "{page}" page

Not supported yet. The dashboard and the renderer disagree about deprecated. The dashboard drops a deprecated layout from the picker and flags a stored assignment as an error (“{display name}” cannot render the property page.), but the renderer does not check deprecated at all — an already-assigned deprecated layout keeps being server-rendered. Deprecating a layout does not take it off a page; ask the customer to switch back to Automatic.

Presets

(widget-core 0.11.0+) A preset is a root-level, one-click composition: the widget picker offers it as its own entry that creates the layout, its children, and the slot bindings — atomically.

// pdp-suite 1.3.3 (the reference suite) — manifest.json, root level
"presets": [
  {
    "name": "PDP Starter",
    "layout": "pdp-frame",
    "slots": {
      "hero":    ["stay-hero", "property-title", "gallery"],
      "main":    ["stay-facts", "description", "amenities", "calendar"],
      "sidebar": ["booking", "booking-cta"],
      "bottom":  ["reviews"]
    }
  }
]

A single slot array may freely mix your own slugs with system keywords, as PDP Starter does.

What one click creates, in order:

1. System-keyword children: the feed’s oldest active widget per keyword, creating the missing ones with platform defaults first. Never duplicated per preset.
2. One instance of each referenced own content slug, display-named {typed name} — {widget name} (the name the customer entered for the preset, then the widget’s own name), with settings = schema defaults + the feed’s branding + filter.feed_id.
3. The layout, with settings = { ...layoutDefaults, slots } mapping each preset slot name to the created/ensured ids.
4. A redirect to the new layout’s playground.

A failure part-way through best-effort deletes the children it just created, then surfaces the original error.

In the picker the entry is labelled {plugin name}: {preset name}, described “One click creates the “{layout}” layout with its slot widgets bound.“, and carries a chip listing the layout and its children. See Composing a page.

Not supported yet. Preset slot keys are never validated against the layout’s declared slot names. A typo (sidbar) publishes cleanly and creates a binding your layout never renders — the widget is created, bound, and invisible. Check your keys by hand against slots[].name.

The customer-facing surface

• The widget picker lists every non-deprecated widget of an enabled plugin, layouts included. A layout’s description gets (layout — hosts other widgets in its slots) appended and it takes a Layers glyph instead of the Puzzle glyph. Per-widget icon falls back to the plugin icon, then to the glyph.
• deprecated: true removes the widget from the picker and disables Create widget on the plugin page. Existing placements keep rendering — see Manifest: widget summary.
• Slot bindings are edited in the layout’s playground under Slot Configuration.

Known gaps, collected

Not supported yet. Each of these is repeated in context above.

• accepts: ["layout"] can never match: the slot picker excludes layouts first, and both render paths refuse a nested layout.
• Preset slot keys are not validated against the layout’s declared slot names.
• prefill keywords are shape-validated only, never checked against the real system-widget keyword list.
• A plugin layout on a server-rendered page can never be interactive — no data-hr-ssr-id, no registry entry, and the client mount is a no-op.
• collection is reserved vocabulary with no assignment surface.
• The renderer keeps server-rendering an assigned layout that is deprecated, which the dashboard reports as an error.
• No local harness composes a layout’s slots. dev:ssr -- --widget {layout} previews the shell with every slot empty, because renderPluginSSR builds the props itself and passes no renderedSlots (widget-core 0.12.2). See Previewing SSR locally.

Checklist

• Suite manifest (widgets[]), not the v1 shape.
• "category": "layout" on the summary.
• "ssr": { "url": … } — never false.
• slots[] with unique names ≤ 64 chars; prefill ≤ 8 system keywords per slot.
• pages only if you want the layout assignable; include a slot named content if you declare listings, checkout or confirmation.
• A slots zod object in config.ts whose keys match the manifest slot names exactly.
• ssr-entry.ts = export { default } from "./widget";.
• registerPluginWidget(…, { category: "layout" }) and mount(…, { category: "layout" }).
• parseWidgetConfig(configZod, props.options ?? {}) in the component.
• renderedSlots?.[name] ?? null everywhere — never assume a key exists.
• Class-namespaced CSS, no :host, no background on the shell.
• The component cannot throw. A layout throw 500s the customer’s page.

A step-by-step build of exactly this is in Add a layout widget.