HomeRunner plugin development

A HomeRunner plugin is a React component, an optional server-render module, and a manifest.json that tells the platform what you ship. You submit it as a source zip: you host nothing, and you never build the artifact a customer loads. A HomeRunner reviewer reads your source, runs your build, and publishes the result to the plugin CDN under an immutable version prefix. Customers then install it per feed and configure it in a dashboard form generated from your zod schema. From there your widget renders alongside first-party ones — server-rendered into Declarative Shadow DOM where the request supports it, hydrated by the platform’s shared runtime, or client-mounted on a CSR embed.

A plugin can carry a single widget or a whole suite of them under one version, one review and one publish — including layout widgets that host other widgets in named slots.

Start here

Building one widget? Read Install and versions, then Your first widget. npx create-hr-plugin my-plugin produces exactly this shape, and its dev sandbox and SSR preview both work out of the box.

Building a suite — several widgets, or a layout, or a one-click preset? Scaffold it directly with npx create-hr-plugin my-suite --template suite (create-hr-plugin 0.8.0+), which writes a working three-widget suite including a layout. Do the first-widget page anyway (the component, schema and build steps are identical), then Build a suite and Add a layout widget.

Choose deliberately: the manifest shape is frozen at your first publish, and changing it afterwards needs a brand-new plugin slug. Converting is free until then — but only until then. The two manifest shapes explains the decision and its cost.

How this book is organised

• Get started — a working toolchain and a widget on screen: Install and versions → Your first widget.
• Concepts — the mental model, in prose: what the files are (Anatomy of a plugin), which shape you picked, how a render actually happens (How a widget renders), where settings come from (Settings and options), and who does what between your laptop and a customer page (Lifecycle).
• Contracts — normative reference: every field, rule and error string, one owner per fact. Start at Manifest: root fields; every hard number and every message the platform can show you is indexed in Limits and error index.
• Recipes — task-shaped guides: Styling and theming, Fetching data, Portals and dialogs, Composing a page.
• Local development — drive every state offline with the dev sandbox, and verify server rendering with SSR preview.
• Ship — Preflight and submit, then Publishing, versions and rollback and Install, customers and kill switches.
• When something breaks — Troubleshooting is organised by symptom; unfamiliar words live in the Glossary.

At a glance

# derived from packages/create-hr-plugin/bin/create-hr-plugin.js and both templates' package.json
# non-interactive, argv only: [--template <single|suite>] [--author <name>] [--no-install]
npx create-hr-plugin my-plugin                   # one widget (the default)
npx create-hr-plugin my-suite --template suite   # several widgets + a layout
cd my-plugin

npm run dev        # Vite dev sandbox on http://localhost:3001, MSW-mocked by default
npm run build      # = npm run build:manifest && hr-widget-build
npm run dev:ssr    # SSR preview on http://localhost:3003 — run a build first.
                   #   A suite has no default widget, so name one:
                   #   npm run dev:ssr -- --widget intro-card
npm run preview    # = npm run build && node serve.js  →  http://localhost:3002

npm run build is two steps, not the three older versions of this guide described: your project’s scripts/inject-schema.mjs writes the config and UI schema into the manifest (or into per-widget sub-manifests), then the SDK’s hr-widget-build bin drives every Vite pass, hashes dist/, writes dist/manifest.json and stamps runtime.widgetCore. It rewrites tracked files, so expect manifest.json to be dirty in git afterwards — commit it.

npm run preview (create-hr-plugin 0.8.0+) serves dist/, /manifest.json, the /w/ hashed redirect and the /p/ asset-proxy path, and the page boots the built bundles against the real runtime IIFE. It runs with no mocks, so point its host ids at a real widget and feed first — Your first widget has the details.

SDK versions

You import from one package, @homerunner-next/widget-core. The build stamps the version it used into runtime.widgetCore, and that stamp is what the publish gate reads — never write it by hand.

This book documents widget-core 0.12.3 and create-hr-plugin 0.8.1, whose templates pin ^0.12.1 (--template single) and ^0.12.3 (--template suite).

Both are on npm as of 2026-09-08 — npx create-hr-plugin <slug> --template suite works straight from the registry. Install and versions owns the version matrix and what each release added.

Install and versions

Get a toolchain that works, then find out exactly which SDK you ended up with and what it can do. This page is the book’s normative home for two things: the runtime version pins your package.json must carry, and which SDK version each feature needs — see What each SDK version gives you before you decide whether to build a single widget or a suite, because that choice is frozen at your first publish.

Node

The 20.12 floor is the one that bites, because it fails silently. The SSR preview harness loads .env.local and .env itself — Vite is not involved — and swallows any failure:

// packages/create-hr-plugin/template/scripts/dev-ssr.mts:26-32 (verbatim)
// — byte-identical at template-suite/scripts/dev-ssr.mts:41-47
for (const file of [".env.local", ".env"]) {
  try {
    process.loadEnvFile(file);
  } catch {
    // file absent — fine
  }
}

On Node 20.0–20.11 process.loadEnvFile is not a function, the TypeError lands in that catch, and the script carries on with no env loaded at all — HR_SSR_HYDRATE, HR_RUNTIME_URL, PORT and your NEXT_PUBLIC_* keys are simply absent and every default silently applies. You get a working-looking server pointed at the wrong places (../local-dev/ssr-preview.md covers those keys). Nothing warns you either: the template declares no engines field, so npm install prints no EBADENGINE for the 20.12 requirement. Enforcement level: advisory (unvalidated) — see the legend in ../contracts/limits-and-errors.md.

Scaffold a project

# packages/create-hr-plugin/bin/create-hr-plugin.js:26-82 — the whole argv surface
npx create-hr-plugin acme-weather --author "Acme Corp"   # one widget (the default)
npx create-hr-plugin acme-suite --template suite         # several widgets + a layout
cd acme-weather

The CLI is entirely non-interactive. It asks nothing; everything comes from argv. --help, -h, or no arguments at all prints this and exits 0:

# packages/create-hr-plugin/bin/create-hr-plugin.js:29-47 — the help text, verbatim
  Usage: create-hr-plugin <plugin-name> [options]

  Creates a HomeRunner widget plugin project (vm.Script SSR + IIFE client).

  Arguments:
    plugin-name     Plugin slug — lowercase letters, digits and hyphens
                    (e.g. "acme-weather"). Becomes the plugin's manifest id.

  Options:
    --template <t>   Project shape: "single" (one widget, default) or
                     "suite" (several widgets + a layout, one publish).
                     --template=<t> works too.
    --author <name>  Author name (default: from git config)
    --no-install     Skip npm install
    --help, -h       Show this help

  Examples:
    npx create-hr-plugin acme-weather --author "Acme Corp"
    npx create-hr-plugin acme-suite --template suite

Every failure message the scaffolder can print is quoted verbatim in ../contracts/limits-and-errors.md.

--template single writes the single-widget project; --template suite writes a three-widget suite with a layout, a preset and a media/ folder. Both shapes run npm run dev, npm run dev:ssr, npm run build and npm run preview. See ../concepts/manifest-shapes.md for the choice you are making — it is frozen at your first publish — then 02-your-first-widget.md or 03-build-a-suite.md to run it.

The React-family pins

Pin these exactly, with no caret, in your plugin’s package.json:

Shape tag: Both. Pin only the ones you actually import — the real suite pdp-suite declares no React Query dependency at all. @types/react and @types/react-dom are caret-ranged (^19.1.3); only the runtime packages are exact.

Your client bundle does not ship React. viteHomerunnerWidget externalises react, react/jsx-runtime, react-dom and react-dom/client against the host page’s runtime IIFE, and the SSR sandbox hands your server bundle the renderer’s own copies. So the React you compile against and the React you execute against are different installs, and they must agree to the patch.

# pnpm-workspace.yaml:13-16 — the platform's own rationale, verbatim
# Why exact pins for react/react-dom: plugin client umds externalize react/react-dom/* against
# `window.HRWidgetRuntime` (= the runtime IIFE). Even patch drift between the renderer's
# server-side React and a plugin's bundled react-dom internals will trip the
# `Incompatible React versions` runtime check.

A caret is enough to break this. "react": "^19.2.5" resolves to whatever 19.x is newest the day you install, and react-dom asserts the two match exactly:

# node_modules/react-dom/cjs/react-dom-client.development.js:27934-27938
Incompatible React versions: The "react" and "react-dom" packages must have the exact same
version.

Two traps in that message. It is a development-build assertion, so a mismatch can pass a production build on your machine and misbehave on a customer page instead of throwing. And enforcement is advisory (unvalidated) — nothing at submit, review or publish reads your package.json, so a drifted pin ships.

What each SDK version gives you

runtime.widgetCore in your built manifest.json records the version you actually built with. The build writes it; never hand-write it — see ../contracts/manifest-root.md for the field and ../contracts/packaging-and-publishing.md for the gate it feeds.

create-hr-plugin tracks it:

Version-gate notes appear inline throughout the book as (0.11.0+). The full export inventory for 0.12.2 is ../contracts/sdk-exports.md.

Versions on npm

Both packages are published and current (checked 2026-09-08):

So npx create-hr-plugin <slug> and npx create-hr-plugin <slug> --template suite both work straight from the registry, and every feature in the table above is installable. Nothing in this book needs a tarball or a private build.

Two things are still worth checking rather than assuming:

• Which version you actually ran. npx caches. If a scaffold comes out single-widget after you asked for a suite, you ran a pre-0.8.0 CLI, which had no --template flag and silently ignored the argument — and the manifest shape is frozen at your first publish. Confirm with npx create-hr-plugin --help (it lists --template from 0.8.0) or npx create-hr-plugin@latest. Older CLIs also had no slug validation, so an invalid manifest.id went unreported until the publish audit.
• What an existing project pins. A project scaffolded before 0.8.0 pins an older widget-core and still uses the three-step build:manifest && build:iife && build:ssr build. Suites need 0.11.0+, and a suite’s npm run dev:ssr needs 0.12.3 — on 0.12.2 it previews unstyled, because the scaffolded widgets export no getStaticAssets. Bump the pin and switch build to build:manifest && hr-widget-build before following 03-build-a-suite.md.

Do not start a plugin as single-widget “for now” if you intend to ship a suite. The manifest shape is frozen at your first publish and changing it needs a brand-new plugin slug (../concepts/manifest-shapes.md). Converting is free before you publish and impossible after.

Check what you actually have

# run these in your plugin directory before you trust any version-gated instruction
node -v                                          # want 20.19+ or 22.12+
npm ls @homerunner-next/widget-core react react-dom
ls node_modules/.bin/hr-widget-build             # absent => widget-core < 0.11.0
npm view @homerunner-next/widget-core dist-tags  # what the registry serves right now

After a build, the authoritative answer is in your own manifest: runtime.widgetCore is the exact version the build ran with. Symptoms that trace back to a version mismatch are indexed in ../troubleshooting.md.

Your first widget

Twenty minutes, end to end: scaffold a project, run it against mocked data, change its settings schema and its component, build it, and read what the build produced.

This tutorial produces a single-widget plugin — --template single, the CLI’s default. The other shape, --template suite, is scaffolded the same way and covered in 03-build-a-suite.md; the component, schema and build steps below are identical in both. The choice is frozen at your first publish — the last section says what to do about that. This page also assumes a working toolchain; get one from 01-install-and-versions.md, which owns the Node floor, the React pins and the dated note on what npm serves versus what the template pins.

1. Scaffold

# packages/create-hr-plugin/bin/create-hr-plugin.js — the real flags
# --template defaults to "single"; pass it explicitly if you like being explicit
npx create-hr-plugin acme-weather --author "Acme Corp"
cd acme-weather

The CLI never prompts; the full argv surface and every failure mode are in 01-install-and-versions.md. What matters here is what it derives from the slug: the display name (Acme Weather), the component name (AcmeWeatherWidget), and the keyword your widget is addressed by everywhere — plugin:acme-weather. The manifest’s id is the slug; nothing re-slugifies it later.

The tree

acme-weather/
├── manifest.json           # plugin identity + the v1 widget fields; the build rewrites it
├── package.json            # scripts, and exact react / react-dom / react-query pins
├── vite.config.ts          # viteHomerunnerWidget({ slug, command }) + your overrides
├── tsconfig.json           # include is ["src/**/*", "vite.config.ts"] only
├── index.html              # DEV sandbox page — not a production artifact
├── serve.js                # zero-dep node:http static server (npm run serve / preview)
├── vercel.json + api/      # optional self-hosted demo shim; never needed to publish
├── mocks/fixtures.ts       # mock data for npm run dev AND npm run dev:ssr
├── public/                 # holds the MSW service worker
├── scripts/                # inject-schema.mjs (build:manifest), dev-ssr.mts (dev:ssr)
└── src/
    ├── index.tsx           # client IIFE entry — registerPlugin() + mount()
    ├── widget.tsx          # your React component (and getInitialData)
    ├── ssr.ts              # dehydrateState + getStaticAssets
    ├── ssr-entry.ts        # SSR bundle entry — re-exports widget.tsx + ssr.ts
    ├── config.ts           # zod schema → manifest configSchema + uiSchema
    ├── widget.css          # Tailwind entry + the .hr-widget-section styles
    ├── data.ts             # sample public-api fetcher + a query-key factory
    ├── components/ui/      # shadcn-style: you own these, edit them freely
    └── dev/                # dev sandbox entry + control bar — never published

Which of those are yours, which the build generates, and which never leave your laptop is laid out in ../concepts/anatomy-of-a-plugin.md.

2. Run the dev sandbox

npm run dev     # http://localhost:3001

npm run dev is mocked by default. src/dev/main.tsx starts an MSW worker bound to plugin:acme-weather, seeds the widget’s settings with configZod.parse({}) so every options.<field> read is defined, turns React Query retries off so the error scenario shows its error state instead of a long spinner, mounts every matching container, and renders a control bar along the bottom for scenario, theme, latency and a live settings JSON editor.

?scenario=empty|single|large|loading|error picks the fixture shape at boot and ?mock=off disables the worker. .env.local is optional — it is consulted only on the ?mock=off path (and by npm run dev:ssr), so you never need a live HomeRunner feed to build the widget. The full sandbox contract is in ../local-dev/dev-sandbox-and-mocking.md.

3. Add a setting

src/config.ts is the whole settings surface. You extend the shared base schema, and you export a JSON Schema built from it:

// packages/create-hr-plugin/template/src/config.ts — the scaffold, with one field added
import { z } from "zod";
import { widgetSchema } from "@homerunner-next/widget-core/schema";
import {
  zodToManifestSchema,
  type PluginUiSchema,
} from "@homerunner-next/widget-core/plugin-schema";

export const configZod = widgetSchema.extend({
  title: z.string().default("Acme Weather").describe("Widget title"),
  units: z.enum(["metric", "imperial"]).default("metric").describe("Units"),
});

/** Symbolic UI for plugin-specific fields only. */
export const uiSchema: PluginUiSchema = {
  title: { component: "TextInput" },
  units: {
    component: "Select",
    optionLabels: { metric: "Celsius", imperial: "Fahrenheit" },
  },
};

/** JSON Schema shipped in `manifest.configSchema`. */
export const configSchema = zodToManifestSchema(configZod);

export type PluginConfig = z.infer<typeof configZod>;

Three things are doing real work. widgetSchema brings in the base fields every widget shares — spacing, colour scheme, fonts, section header, custom CSS and the rest — so the dashboard renders those controls without you declaring anything. .default(...) and .describe(...) on your own fields are what make the customer’s form open clean and self-explaining. And uiSchema names only your fields: a plugin entry replaces a top-level key of the base UI schema wholesale, so re-declaring a base key destroys that panel.

The base field list, the component vocabulary, and which zod constructs survive the round trip to JSON Schema and back (versus which ones take the whole config panel down) are in ../contracts/config-and-ui-schema.md. Read the round-trip tables before you reach for a union, a tuple or z.any().

4. Edit the component

src/widget.tsx is the component the browser and the server both render. The scaffold already shows the two calls that are not optional:

// packages/create-hr-plugin/template/src/widget.tsx — the scaffold's real component,
// with <WidgetSection>, the new `units` setting, and the imported prop type
import React from "react";
import { parseWidgetConfig } from "@homerunner-next/widget-core/schema";
import { resolveWidgetSpacingStyle } from "@homerunner-next/widget-core/spacing";
import type { WidgetProps } from "@homerunner-next/widget-core/contracts";
import { configZod, type PluginConfig } from "./config";
import { cn, WidgetSection } from "./components/ui";
import "./widget.css";

type WeatherData = { message?: string };

export default function AcmeWeatherWidget(
  props: WidgetProps<PluginConfig, WeatherData>,
) {
  // `props.options` is the RAW stored settings blob on BOTH server and client:
  // parseWidgetConfig strips the dashboard's null/'' save artifacts, coerces
  // stringified scalars and applies your defaults. Never read it directly.
  const options = React.useMemo(
    () => parseWidgetConfig(configZod, props.options) as PluginConfig,
    [props.options],
  );

  const isDark = props.resolvedTheme === "dark";

  return (
    // The base schema's `spacing` renders on the outer element; the helper does
    // its own defaulting and repair, so raw or parsed options both work.
    <div style={resolveWidgetSpacingStyle(options)}>
      <WidgetSection show={options.section.show} title={options.section.title} />
      <div
        className={cn(
          "rounded-lg border p-4 font-sans",
          isDark ? "border-zinc-700 bg-zinc-900" : "border-zinc-200 bg-white",
        )}
      >
        <h3 className="mb-2 text-lg font-semibold">{options.title}</h3>
        <p className="text-sm text-zinc-500">
          {props.data?.message ?? "Loading…"} ({options.units})
        </p>
      </div>
    </div>
  );
}

WidgetSection comes from src/components/ui/ — shadcn-style components the scaffold copies into your project, not a package import. Its real props are {show, title, className}; it renders the heading only, is not a wrapper, takes no options, and returns null when show is false or title is empty.

props.options arriving raw is the rule that catches most first-time authors, and it applies to getInitialData and dehydrateState in src/ssr.ts too — parse there as well, or your server-side query keys will not match the ones your hydrated component builds.

Two corrections to the scaffold, both worth making now. The template declares its own WidgetProps interface inline; import the real one from @homerunner-next/widget-core/contracts instead, because the inline copy omits fields. And props.resolvedTheme is fine for a class swap after mount but is not something to key first paint on — dark at first paint has to come from CSS. See ../contracts/component-and-ssr-module.md for the full prop contract and the SSR module, and ../recipes/styling-and-theming.md for theming.

Save with npm run dev running: Vite hot-reloads the component, and the sandbox’s settings editor pushes new options at the mounted widget without a rebuild.

5. Build

npm run build

build is npm run build:manifest && hr-widget-build — two steps, not the three-step build:manifest → build:iife → build:ssr chain older documentation describes:

build:iife and build:ssr still exist in package.json, but build no longer calls them — they are single-widget escape hatches. On a suite, a bare vite build refuses to run at all. (hr-widget-build needs widget-core 0.11.0+.)

Expect manifest.json to be dirty in git after every build, and commit it. The build rewrites that tracked file twice: build:manifest injects the schemas, and the final Vite pass stamps runtime.widgetCore with the SDK version it built against. Never hand-write that stamp — but do commit it, because the publish audit gates on it. See ../contracts/packaging-and-publishing.md.

Read dist/

# a real built single-widget plugin (hr-plugins/featured-stays); .map files omitted here
dist/
├── featured-stays.iife.js            # client bundle
├── featured-stays.iife-cb11ab13.js   # its content-hashed twin
├── featured-stays.css
├── featured-stays-d4188b32.css
├── featured-stays-ssr.umd.js         # SSR bundle — CommonJS despite the name
├── featured-stays-ssr.umd-122b8a33.js
├── manifest.json                     # the BUILD manifest: {buildHash, generatedAt, files}
├── mockServiceWorker.js              # built by an OLD scaffold — see the note below
└── mockServiceWorker-7b2c8364.js

Three files are the plugin: the client IIFE named in assets.js, the stylesheet in assets.css, and the SSR bundle in ssr.url. The hashed twin beside each is what a customer page actually loads, and dist/manifest.json is the plain-name → hashed-name map the renderer and the asset proxy read (source maps are excluded from it but still ship). Filenames are fixed by the SDK; renaming an output is a publish error. All normative in ../contracts/assets-and-urls.md.

Your own dist/ will not have those last two files. public/mockServiceWorker.js — the dev-only MSW worker — used to be copied into dist/ by Vite on every production build, hashed and recorded in the build manifest. (create-hr-plugin 0.8.0+) both templates’ vite.config.ts pass publicDir: command === "build" ? false : "public", so the worker stays out of the build while npm run dev is untouched. featured-stays was built before that fix; if your scaffold predates 0.8.0, make the same one-line change.

6. Preview the server render

npm run build       # dev:ssr reads dist/, so build first
npm run dev:ssr     # http://localhost:3003 → redirects to /preview?scenario=default

scripts/dev-ssr.mts loads .env.local then .env, then runs your built SSR bundle through the same node:vm contract the production renderer uses, against the same mocks, with a scenario tab strip and an inspector showing the server HTML, the props and the dehydrated query cache. HR_SSR_HYDRATE=1 additionally runs real client hydration and surfaces mismatch warnings. Without a prior build it tells you the SSR bundle is missing.

It is close to production, not identical. What still differs is the environment around the sandbox — the envelope, the asset base, the pre-parsed settings — and each difference is enumerated in Where the preview differs from production.

npm run preview — the built bundles, no mocks

npm run preview is npm run build && node serve.js. serve.js is a zero-dependency node:http server on port 3002 (not Express, and not port 3000) that serves /manifest.json and /dist/* with Access-Control-Allow-Origin: *, answers /w/{file} with a 302 to the hashed twin, and answers /p/{slug}/{file} from dist/ — the plugin-asset proxy path your built IIFE resolves its stylesheet through.

(create-hr-plugin 0.8.0+) the page renders. index.html still loads the Vite dev entry /src/dev/main.tsx, which does not exist under serve.js; its onerror boots the preview path instead — the runtime IIFE first (your built bundle externalises React, React Query and widget-core against window.HRWidgetRuntime), then proxyBaseUrl pointed at the local server, then /dist/acme-weather.iife.js. Earlier scaffolds had no such fallback and rendered an empty mount div.

There are no mocks on this path — it talks to whichever Central the runtime IIFE points at. Before you use it, change the host div’s id="{widgetId}:{feedId}" in index.html to a real pair, and point HR_RUNTIME_URL at the environment you are testing against. For mocked visual work stay in npm run dev; for the server path use npm run dev:ssr.

curl -s localhost:3002/manifest.json | head -20
curl -sI localhost:3002/w/acme-weather.iife.js    # expect 302 → /dist/<hashed>

Next: choose your shape, while it is still free

You now have a widget that renders, a settings form the dashboard can draw, an SSR bundle and a built dist/. You have not created media/ (icons, cover, README — authored content nothing generates) and you have not submitted anything; both belong to ../ship/preflight-and-submit.md.

One decision is still open, and only until your first publish. A plugin is either the single-widget shape you just built or the modern suite shape — one plugin, many widgets, one version, one review, one publish. A suite may hold a single widget, so “suite” is not the same as “big”. That shape is frozen at first publish: flipping it later passes submit and even passes review, then dies at publish with a shape-change rejection, and the only remedy is a brand-new slug — losing every stored keyword and every embed URL a customer has copied. Today it costs you a re-scaffold, or a file move.

• Ever going to ship a second widget, a layout or a preset? Start over with npx create-hr-plugin <slug> --template suite, or convert the project you just built — both routes are in 03-build-a-suite.md.
• Want the decision spelled out with its costs on both sides: ../concepts/manifest-shapes.md.

Build a suite

A suite is one plugin that ships several widgets under one slug, one version, one review and one publish. The root manifest carries a widgets[] array instead of a single widget’s fields, each widget lives in its own folder, and each one gets a namespaced keyword plugin:{plugin}:{widget} instead of the bare plugin:{plugin}. Requires @homerunner-next/widget-core 0.11.0+ — see Install and versions.

There are two ways in, and the first is the one you want for a new plugin:

1. Scaffold one — npx create-hr-plugin <slug> --template suite (create-hr-plugin 0.8.0+). The next section.
2. Convert the single-widget project from Your first widget. The rest of the page — and also the field-by-field tour of what the scaffold wrote, if you took route 1.

The shape is frozen at your first publish — converting afterwards needs a new plugin slug — so do this before you submit, not after. See The two manifest shapes.

Scaffold one

# packages/create-hr-plugin/bin/create-hr-plugin.js — --template, 0.8.0+
npx create-hr-plugin acme-suite --template suite     # --template=suite works too (0.8.1+)
cd acme-suite

You get a suite that builds, publishes and passes both audits with zero errors and zero warnings as generated. It ships three widgets, one per surface you have to know about:

# packages/create-hr-plugin/template-suite/ — what `--template suite` writes
acme-suite/
├── manifest.json                  # widgets[] summaries + presets[] — the suite root
├── package.json · tsconfig.json · vite.config.ts · .env.example · .gitignore
├── scripts/
│   ├── inject-schema.mjs          # build:manifest — config.ts → widgets/{slug}.manifest.json
│   └── dev-ssr.mts                # npm run dev:ssr -- --widget {slug}
├── media/                         # AUTHORED: icon.svg, {slug}.svg, README.md, widgets/{slug}.md
├── index.html · src/dev/ · mocks/fixtures.ts · public/   # dev sandbox — never published
├── serve.js · vercel.json         # static hosting for the built output
└── src/
    ├── shared/property.ts         # code >1 widget uses, imported relatively
    └── widgets/
        ├── page-frame/            # config.ts · widget.tsx · index.tsx · page-frame.css
        │   └── ssr-entry.ts       #   present because the summary declares ssr.url
        ├── intro-card/            # …the same five files
        │   └── ssr-entry.ts
        └── quick-facts/           # …NO ssr-entry.ts — the summary says "ssr": false

widgets/{slug}.manifest.json is missing from that list because nothing has generated it yet; your first npm run build writes it, and you commit the result — step 4.

Two things this template deliberately does not ship, both of which the single-widget template does: a src/components/ui/ kit, and Tailwind. A layout’s stylesheet is loaded document-level and unisolated on a server-rendered page, so a CSS framework’s global reset would land on the customer’s whole document — see Styling and theming.

npm run dev                              # :3001 — all three widgets, MSW-mocked
npm run build                            # build:manifest && hr-widget-build
npm run dev:ssr -- --widget intro-card   # :3003 — ONE widget's built SSR bundle
npm run preview                          # build + serve.js on :3002, no mocks

npm run dev mounts all three: each widget’s own src/widgets/{slug}/index.tsx registers and auto-mounts it exactly as its built IIFE does, and the layout’s mocked settings carry slots, so page-frame resolves intro-card and quick-facts as real slot children through the client composition path. That works only because mocks/fixtures.ts overrides /widget/{id} with a factory answering each dev id with its own keyword — the mock worker’s built-in route answers every id with one keyword, and a layout would then refuse to render its own children. Full sandbox contract: Dev sandbox and mocking.

npm run dev:ssr (widget-core 0.12.2+, and create-hr-plugin 0.8.1+ for the script that drives it) has no default widget in a suite, so name one: --widget intro-card, --widget=intro-card, or HR_SSR_WIDGET=intro-card in .env.local. It renders dist/{widget}/{widget}-ssr.umd.js under plugin:{slug}:{widget} and seeds the mocked settings from that widget’s own configZod.parse({}). Naming nothing, naming a widget the manifest does not declare, or naming the CSR-only quick-facts exits 1 with a message listing the widgets that do work — the harness, its scenarios and its divergences from the renderer are in Previewing SSR locally.

The scaffold’s page-frame is a complete, working layout; Add a layout widget walks the same five files against the published reference suite so you can see which parts are layout-specific.

Or convert a single-widget project

The rest of this page converts the project from Your first widget into a suite. If you scaffolded one instead, read it as a tour of what --template suite already wrote — and as the procedure for adding a fourth widget.

What already understands a suite

Three parts of the scaffold branch on widgets[] by themselves and need no edits at all:

There is no rollup input map anywhere in a suite build. Multi-entry is driven entirely by two environment variables that the hr-widget-build CLI sets per pass:

// packages/homerunner-widget-core/src/vite/index.ts — build.lib.entry, abridged
entry: buildWidget                 // buildWidget = process.env.BUILD_WIDGET
  ? isSSR                          // isSSR      = process.env.BUILD_SSR === "1"
    ? `./src/widgets/${buildWidget}/ssr-entry.ts`
    : `./src/widgets/${buildWidget}/index.tsx`
  : isSSR
    ? "./src/ssr-entry.ts"
    : "./src/index.tsx",

fileName and the CSS asset name branch the same way, which is what nests the output under dist/{widget}/. With BUILD_WIDGET unset the config still resolves the flat entries, so a bare vite build on a suite would emit a plausible-looking, entirely broken dist/ — viteHomerunnerWidget reads your root manifest at config time and throws instead. The exact message is in Limits and error index. Always build with npm run build.

The conversion at a glance

A scaffolded suite’s package.json keeps six scripts: dev (vite), dev:ssr (tsx scripts/dev-ssr.mts), build (npm run build:manifest && hr-widget-build), build:manifest (tsx scripts/inject-schema.mjs), serve and preview. The published reference suite keeps only the first, third and fourth — a suite needs no sandbox to be publishable. --template suite pins @homerunner-next/widget-core ^0.12.2 (its npm run dev:ssr needs the 0.12.2 harness); --template single pins ^0.12.1. A converted project on ^0.11.0 builds and publishes, but has no assets.fonts, bundled assets, marketplace icons, layout pages or slot prefill. What the registry actually serves is in Install and versions.

1. Rewrite the manifest

Delete the v1 root fields — widgetType, ssr, assets, and the configSchema / uiSchema pair your last build injected — and add widgets[]. Nothing else at the root changes.

// The scaffolded plugin rewritten as a two-widget suite. Identity fields (id, version,
// name, description, author) carry over unchanged from the template's manifest.json;
// summary shapes follow the published reference suite's manifest.
{
  "id": "acme-weather",
  "version": "1.0.0",
  "name": "Acme Weather",
  "author": { "name": "Plugin Author" },
  "runtime": { "react": "^19.0.0" },  // build stamps "widgetCore" — never hand-write it
  "widgets": [
    {
      "slug": "forecast",
      "name": "Forecast",
      "ssr": { "url": "dist/forecast/forecast-ssr.umd.js" },
      "assets": { "js": "dist/forecast/forecast.iife.js",
                  "css": "dist/forecast/forecast.css" },
      "manifest": "widgets/forecast.manifest.json"   // written by build:manifest
    },
    {
      "slug": "snapshot",
      "name": "Snapshot",
      "ssr": false,                                   // CSR-only — see step 3
      "assets": { "js": "dist/snapshot/snapshot.iife.js",
                  "css": "dist/snapshot/snapshot.css" },
      "expectedHeight": 140,
      "manifest": "widgets/snapshot.manifest.json"
    }
  ]
}

Point assets and ssr.url at the logical filenames the build emits — never at a hashed twin. The manifest references are filled in for you by build:manifest.

Every field, its rule and its exact publish error live in Manifest: widget summary; the root fields are in Manifest: root fields.

2. Move the sources into src/widgets/{slug}/

acme-weather/
├── manifest.json · package.json · package-lock.json · tsconfig.json · vite.config.ts
├── scripts/inject-schema.mjs        # unchanged
├── widgets/                         # GENERATED by build:manifest — commit it
│   ├── forecast.manifest.json
│   └── snapshot.manifest.json
├── media/                           # authored by you; nothing generates it
└── src/
    ├── components/ui/               # optional shared code, imported relatively
    └── widgets/
        ├── forecast/                # index.tsx · widget.tsx · config.ts · forecast.css
        │   └── ssr-entry.ts         #   present ONLY because the summary declares ssr.url
        └── snapshot/                # index.tsx · widget.tsx · config.ts · snapshot.css
                                     #   NO ssr-entry.ts — the summary says "ssr": false

Two things break silently when you move files:

• Relative imports. The scaffold’s src/widget.tsx imports ./components/ui; from src/widgets/forecast/ that becomes ../../components/ui.
• The @/* alias is TypeScript-only. tsconfig.json maps @/* → ./src/*, but nothing adds the matching Vite resolve.alias, so @/components/ui type-checks and then fails to build. Keep relative paths.

A server-rendered widget’s ssr-entry.ts is one line — that is the entire file in the published reference suite (pdp-suite, src/widgets/stay-hero/ssr-entry.ts):

export { default } from "./widget";

Suite widgets typically export only default — no getInitialData, no dehydrateState, no getStaticAssets. What each optional export does, and the sandbox it runs in, is in Component and SSR module.

3. Add the second widget, CSR-only

The clearest way to internalise the SSR-entry rule is to make your second widget CSR-only: "ssr": false plus an expectedHeight in the summary, and no ssr-entry.ts in the folder.

• "ssr": false is a deliberate, explicit value. Omitting ssr entirely is a publish error — it is not the same as false.
• hr-widget-build skips the SSR pass for that widget, so dist/snapshot/ never gets a -ssr.umd.js, and an ssr-entry.ts left in the folder is simply never built. The reverse also fails: declare ssr.url with no ssr-entry.ts and the vite pass dies on a missing entry.
• On a server-rendered page the renderer emits an empty host div carrying data-hr-min-height from expectedHeight. Set it, or the page reserves nothing and shifts when your bundle paints (Manifest: widget summary).
• A category: "layout" widget must declare ssr.url. The publish audit accepts ssr: false on a layout, but the render then fails — Layout widgets and Add a layout widget.

Each widget registers and mounts itself. This is the one file that genuinely differs from the single-widget scaffold — registerPluginWidget(plugin, widget, Component) instead of registerPlugin(slug, Component), and a namespaced widgetType:

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

registerPluginWidget("pdp-suite", "stay-facts", StayFacts);

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

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

Copy it per widget. The only edits are the two imports, the two keyword strings — for the example above, registerPluginWidget("acme-weather", "snapshot", …) and plugin:acme-weather:snapshot — and, for a layout, a category on both calls. The registry keys, the [data-hr-widget-container] scan and the full MountConfig are specified in Runtime, mount and the DOM contract.

config.ts and widget.tsx keep the shape the scaffold gave you: extend widgetSchema, export configSchema from zodToManifestSchema, and parse props.options with parseWidgetConfig before reading a single field — options arrive RAW on both server and client. See Settings and options and Config schema and UI schema.

4. Regenerate the sub-manifests

A suite root carries no schemas. build:manifest writes one sub-manifest per widget and stamps the reference back onto the summary. This script lives in your project, not in the SDK — both templates ship the identical script, so you only need to know what it does:

// packages/create-hr-plugin/template/scripts/inject-schema.mjs — the multi-widget branch
// (byte-identical in template-suite/scripts/inject-schema.mjs)
if (Array.isArray(manifest.widgets) && manifest.widgets.length > 0) {
  const outDir = path.join(root, "widgets");
  fs.mkdirSync(outDir, { recursive: true });
  for (const widget of manifest.widgets) {
    const slug = widget.slug;
    const configPath = path.join(root, "src", "widgets", slug, "config.ts");
    if (!fs.existsSync(configPath)) {
      console.error(`  missing ${configPath} for widget "${slug}"`);
      process.exit(1);
    }
    const { configSchema, uiSchema } = await import(pathToFileURL(configPath).href);
    const sub = { slug, configSchema };
    if (uiSchema) sub.uiSchema = uiSchema;
    fs.writeFileSync(path.join(outDir, `${slug}.manifest.json`), JSON.stringify(sub, null, 2) + "\n");
    widget.manifest = `widgets/${slug}.manifest.json`;
  }
  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
}

widgets/*.manifest.json is generated but committed and shipped in both zips — the reviewer only runs your build, and a referenced sub-manifest missing from the zip is a publish error. Only the dashboard ever fetches these files, and only to draw a config form. Details in Config schema and UI schema.

5. Build

npm run build is still npm run build:manifest && hr-widget-build. The CLI is what turns one vite config into many bundles:

1. It validates every summary before any pass runs — slug shape, the reserved names dist / widgets / media, duplicate slugs, and the presence of src/widgets/{slug}/index.tsx. Each failure exits non-zero with its own message (Limits and error index).
2. It deletes dist/ once. Per-widget passes then run with emptyOutDir: false, so running a single pass by hand leaves stale output from a previous build.
3. It flattens the widgets into a (widget × pass) list — an iife pass for every widget, plus an SSR pass for every widget that does not declare ssr: false — and runs each with BUILD_WIDGET={slug} (and BUILD_SSR=1 on SSR passes).
4. It marks the last pass HR_BUILD_FINALIZE=1. Only that pass hashes dist/, writes the shared dist/manifest.json, and stamps runtime.widgetCore into your tracked root manifest. Expect manifest.json dirty in git after every build; commit it.

build:iife and build:ssr survive in the single-widget scaffold’s package.json as escape hatches. On a suite they are the bare vite build that fails by design — delete them if you converted. --template suite never ships them.

The dist/ a suite produces

One directory per widget, one shared build manifest, and a content-hashed twin beside every non-.map file:

# pdp-suite (the published reference suite) — dist/ after one `npm run build`
dist/
├── manifest.json
├── pdp-frame/     pdp-frame.iife.js  pdp-frame.iife-be6fddd4.js  pdp-frame.iife.js.map
│                  pdp-frame.css      pdp-frame-9992937d.css
│                  pdp-frame-ssr.umd.js  pdp-frame-ssr.umd-5872d9b8.js  …js.map
├── stay-hero/     … + hero-bg-Cr1v4Zys.png  hero-bg-Cr1v4Zys-1cc265f5.png
├── stay-facts/    iife + css only          ← "ssr": false
└── booking-cta/   iife + css only          ← "ssr": false

// pdp-suite — dist/manifest.json, abridged. Keys AND values are dist-relative.
{
  "buildHash": "77328e0a",
  "generatedAt": "2026-09-07T06:25:25.567Z",
  "files": {
    "pdp-frame/pdp-frame.iife.js":    "pdp-frame/pdp-frame.iife-be6fddd4.js",
    "stay-facts/stay-facts.css":      "stay-facts/stay-facts-945e0d55.css",
    "stay-hero/hero-bg-Cr1v4Zys.png": "stay-hero/hero-bg-Cr1v4Zys-1cc265f5.png"
  }
}

Bundled images emitted from a widget folder are keyed there too; sourcemaps are published but deliberately absent from the map. How these names become URLs is in Keywords, assets and URLs.

What a suite costs you today

Both of the tooling gaps this section used to list are closed: --template suite (create-hr-plugin 0.8.0+) generates a suite-aware dev sandbox, and npm run dev:ssr (widget-core 0.12.2+, and create-hr-plugin 0.8.1+ for the script that drives it) previews a named suite widget. Two real limits are left, and neither affects publishing, installing, rendering or SSR in production.

Not supported yet. The dev sandbox has one mock state for the whole page. Scenario, latency, feed branding and the widget settings object are a page singleton in npm run dev: src/dev/main.tsx seeds settings with the union of every widget’s schema defaults and each widget’s zod strips the keys that are not its own, which works only while no two widgets share a field name. Give two widgets a title and they share its value in the sandbox — and the control bar’s settings editor edits that one object and pushes it to every keyword. npm run dev:ssr renders one widget, so it seeds only that widget’s own defaults and has no such collision. Details in Dev sandbox and mocking.

Not supported yet. There is no server-side slot composition locally. npm run dev:ssr renders the one widget you named and nothing else, so a layout renders its shell with empty slots: on a server-rendered page the platform renders each bound child and hands the results to your layout as renderedSlots, and no local harness does that. npm run dev composes the layout the client way, which is the other half of the contract. Install the plugin on a real feed to exercise the server half — Previewing SSR locally and Layout widgets.

If you converted a project by hand and kept the single-widget harness, you have a third problem that is yours rather than the platform’s: src/dev/main.tsx statically imports the flat ../widget and ../config, index.html hardcodes one plugin:{slug} keyword, and the mock worker’s built-in /widget/{id} route answers every id with that one keyword — so a layout resolves its own keyword for each slot child and refuses to render it. Take the suite template’s index.html, src/dev/ and mocks/fixtures.ts instead; the fixture’s widget factory is the part that makes three widgets coexist. The dev CSS route also becomes /dist/{plugin}/{widget}/{widget}.css.

Before you zip

• npm run build is clean, dist/manifest.json exists, and manifest.json now carries a runtime.widgetCore stamp.
• Every declared assets.js / assets.css / ssr.url path matches what dist/ actually contains, including the {widget}/ directory.
• widgets/*.manifest.json is committed, and so is every media/ file you reference.
• No dist/, node_modules/ or .git/ in the zip; package-lock.json is present.
• Every widget declaring ssr.url has an ssr-entry.ts; every "ssr": false widget has none and has an expectedHeight.

The full preflight, the audits and what happens after upload are in Preflight and submit and Packaging and publishing rules.

Where to go next

• Add a layout widget — the capability only a suite has.
• Manifest: widget summary — every widgets[] field.
• Composing a page — presets, slots and page assignment.
• Troubleshooting — build failures, empty config panels, blank widgets.

Add a layout widget

A layout widget renders none of its own content. It declares named slots, the customer binds other widgets into them, and the platform hands your component the already-rendered children as renderedSlots. Assigned to a server-rendered page, your layout replaces the platform’s own page layout for that feed.

This page builds pdp-frame — the layout that ships in the real pdp-suite plugin — file by file, in the order you would write them. Every rule, cap and error string it touches is stated once in Layout widgets; this page is the build order, not the contract.

Two things to settle first. Layouts are suite-only: a v1 single-widget manifest resolves every widget as content, and the shape is frozen at first publish, so scaffold or convert to a suite before you start (Build a suite, The two manifest shapes). And layouts need widget-core 0.11.0+, pages needs 0.12.0+, slots[].prefill needs 0.12.1+ — npm’s latest is older than all three (Install and versions).

If you would rather start from a working layout than from this page, npx create-hr-plugin <slug> --template suite (create-hr-plugin 0.8.0+) scaffolds one: page-frame, a four-slot layout with prefill, pages, a preset and light-DOM-safe CSS. It is the same eight steps below, already written. Read this page either way — the scaffold shows you a layout, not why each part is shaped as it is.

What you are building

pdp-frame reuses the slot vocabulary of the platform’s own property-details layout — hero, main, sidebar, bottom — so system widgets drop straight in; what it remixes is the grid, lifting the sidebar rail beside the hero. Its folder (pdp-suite 1.3.3 — src/widgets/pdp-frame/):

config.ts       zod config — including the mandatory `slots` object
index.tsx       client entry: registerPluginWidget + mount, both with a category
pdp-frame.css   light-DOM-safe shell CSS
ssr-entry.ts    one line — a layout needs no data hooks
widget.tsx      the component: renders `renderedSlots`

That is the same five files a content widget uses inside a suite — a layout differs in what goes into them.

Step 1 — declare the summary

Add one entry to widgets[] in the root manifest.json:

// pdp-suite 1.3.3 (the reference suite) — manifest.json, the pdp-frame summary
// (trimmed: the summary's own "description" string is elided.)
{
  "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"
}

What the layout-specific fields buy you:

• category: "layout" is what routes the widget through the layout path at all. Anything that is not exactly that string silently becomes a content widget — and a layout keyword rendered as content then fails.
• slots[] names the regions. The names are yours; mirroring the system PDP vocabulary is a choice. See slots[] — and read the content-slot rule there before you put listings, checkout or confirmation in pages, because those pages ignore your vocabulary.
• slots[].prefill (0.12.1+) lists system widget keywords the dashboard binds when the customer creates the layout, so it opens populated. Creation-time only, never re-applied, and your own widgets cannot go here — that is what a preset is for (slots[].prefill).
• ssr: { "url": … } is mandatory: the server composes your children, then renders your shell. "ssr": false is not caught by the publish audit — it fails at render time (SSR).
• pages (0.12.0+) makes the layout assignable to a server-rendered page. Omit it and the layout still works as an embed and in the picker; it just never reaches the feed’s page-layout picker.
• assets.fonts (0.12.0+) carries the Playfair Display face the slot labels use; declared fonts load document-level, because @font-face is ignored inside a shadow root (Keywords, assets and URLs). icon / readme (0.12.0+) are media/ files you author and commit.

Note the absence of expectedHeight: it reserves space for a CSR-only host div and never applies to a layout. Every non-layout field belongs to Manifest: widget summary.

Step 2 — declare the mandatory slots config field

This is the step people skip, and its failure is silent. The dashboard does not render a separate slot editor — it injects one into your own config form under a field named slots, so without that field there is nowhere to persist and the customer’s bindings are dropped on save.

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/config.ts
// (trimmed: the shipped file also exports a `uiSchema`; a layout needs none.)
import { z } from "zod";
import { widgetSchema } from "@homerunner-next/widget-core/schema";
import { zodToManifestSchema } from "@homerunner-next/widget-core/plugin-schema";

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"),
  // One key per manifest slot name, character for character.
  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 type FrameConfig = z.infer<typeof configZod>;
export const configSchema = zodToManifestSchema(configZod);

Three things to get right, all covered in The mandatory slots config field: the keys equal the manifest slot names exactly; every slot is z.array(z.string()).default([]) with .default({}) on the object, so the field survives configZod.parse({}) at creation; and you do not write a uiSchema entry for slots, because the dashboard replaces that key with its own panel (Config schema and UI schema). Your project’s own pre-build script turns this into widgets/pdp-frame.manifest.json — see Build a suite.

Step 3 — write the component

The component reads two props: raw options, and renderedSlots. It renders regions and nothing else.

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/widget.tsx
// Corrected: the shipped file hand-rolls its props type. Import the SDK type instead.
import React, { type ReactNode } from "react";
import { parseWidgetConfig } from "@homerunner-next/widget-core/schema";
import type { LayoutWidgetProps } from "@homerunner-next/widget-core/contracts";
import { configZod, type FrameConfig } from "./config";
import "./pdp-frame.css";

// `options` arrives RAW on both paths, and SSR supplies neither `widgetType`
// nor `target` — so relax the SDK type at the boundary and parse it yourself.
type FrameProps = Omit<Partial<LayoutWidgetProps<FrameConfig>>, "options"> & {
  options?: Record<string, unknown>;
};

export default function PdpFrame(props: FrameProps) {
  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>
  );
}

Why it is written that way:

• parseWidgetConfig(configZod, props.options ?? {}) is not optional — settings reach a plugin raw on both server and client (Settings and options).
• props.renderedSlots ?? {}, then one lookup per region. Never assume a key exists: the two render paths disagree about what an empty slot looks like (The component contract), and the region() helper’s node ?? … fallback is the defensive shape you want.
• Nothing in here may throw. A content widget that throws costs one widget; a layout that throws during SSR costs the customer’s whole page (Failure semantics).

Step 4 — write the SSR entry

Because the summary declares ssr.url, the build runs an SSR pass for this widget, and that pass needs src/widgets/pdp-frame/ssr-entry.ts. For a layout it is one line:

// 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";

No getInitialData, no dehydrateState, no getStaticAssets: composition is the job, and the children fetch their own data. Those hooks still work if you need them — they run before the shell renders, inside the same try/catch (Component and SSR module).

Step 5 — register and mount with a category

// pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/index.tsx
// (trimmed: the container scan and DOMContentLoaded guard are the standard
//  suite bootstrap — see Build a suite. Only the category is layout-specific.)
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" });

// …then, for each matching [data-hr-widget-container] on the page:
mount(container, {
  widget: PdpFrame,
  widgetType: "plugin:pdp-suite:pdp-frame",
  category: "layout",
});

This is the standard suite bootstrap plus { category: "layout" } in two places. The registry write and the mount() call sit in the same IIFE, so passing it once is enough to route correctly — pass it twice anyway, and never omit it from both. Omitting it everywhere is the one destructive mistake in this file: the shell is then treated as content, and the client render wipes the server’s composed slot children. Mechanics in Registration and mount and Runtime, mount and the DOM contract.

Step 6 — write light-DOM-safe CSS

Your stylesheet has to survive two homes: document level and unisolated on every server-rendered page (the shell is light DOM there), and inside a shadow root on a CSR embed. So: class-namespace everything, never depend on :host, never paint a background on the shell. The reasoning and the rule table are in Layout CSS.

/* pdp-suite 1.3.3 (the reference suite) — src/widgets/pdp-frame/pdp-frame.css (trimmed) */
/* 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; }
.pdpf-region { position: relative; min-width: 0; }
.pdpf-label { font-family: "Playfair Display", serif; /* declared in assets.fonts */ }

/* …plus a max-width: 860px block that collapses the grid to one column and
   reorders the areas to "hero" "sidebar" "main" "bottom". */

Two habits worth copying: every selector is prefixed .pdpf, and the narrow breakpoint reorders sidebar above main so a bound booking rail stays reachable on a phone. Theming — including why a layout inherits none of the platform’s slot spacing — is in Styling and theming.

Step 7 — build

npm run build (your schema-inject pass, then hr-widget-build) loops every widget. Because pdp-frame declares ssr.url it gets two passes, and dist/pdp-frame/ holds pdp-frame.iife.js, pdp-frame.css and pdp-frame-ssr.umd.js, each with a content-hashed twin. If the SSR pass cannot resolve src/widgets/pdp-frame/ssr-entry.ts the build fails there — the fastest signal that you declared ssr.url without writing the entry. The pass loop and the shared build manifest belong to Build a suite and Keywords, assets and URLs.

Then preview the server render (widget-core 0.12.2+) — a suite has no default widget, so name this one:

npm run build
npm run dev:ssr -- --widget pdp-frame     # http://localhost:3003

That runs the layout’s built SSR bundle through the same vm contract the renderer uses, which is enough to catch an SSR-only crash, a disallowed import or an empty render in the shell itself. --widget=pdp-frame and HR_SSR_WIDGET=pdp-frame do the same thing.

Not supported yet. The preview renders the named widget and nothing else, so your layout renders with empty slots: on a server-rendered page the platform renders each bound child and hands the results to your component as renderedSlots, and no local harness does that. npm run dev composes the layout the client way instead, which exercises the other half of the contract. Install the plugin on a real feed for the server half — see Previewing SSR locally and Dev sandbox and mocking.

Step 8 — offer a one-click preset

A preset is a root-level entry that creates the layout, its children and every binding in one click. Its power is that a single slot array may mix your own widget slugs with system widget keywords:

// 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"]
    }
  }
]

stay-hero, stay-facts and booking-cta are this plugin’s own content widgets; the rest are system keywords the platform ensures or creates on the feed. That is the difference from prefill, which only takes system keywords — a preset is how you compose your suite into a finished page. What one click creates, in what order, and the referential rules that make it publishable are in Presets.

Not supported yet. Preset slot keys are never checked against your layout’s declared slot names. Write sidbar and the plugin publishes, the widget is created and bound, and it renders nowhere. Diff your preset keys against slots[].name by hand.

What the customer ends up seeing

• The widget picker lists your layout beside your content widgets, marked as a layout and carrying a Layers glyph instead of the content one — plus a separate entry per preset (The customer-facing surface).
• The layout’s playground shows the injected Slot Configuration panel at the top of your config form, one row per manifest slot.
• Feed → Page URLs → Page layouts offers the layout for every page its summary declares, next to Automatic; an assignment the renderer cannot honour degrades to Automatic rather than breaking the page (page assignment).
• Composing a page end to end, including the property a layout pushes down to its children, is in Composing a page.

Three things that look like bugs and are not

1. On a server-rendered page the shell is plain light DOM — no shadow root, no Declarative Shadow DOM template. Deliberate: each slot child is its own island, which is what keeps third-party payment fields working.
2. The client mount on that page is a no-op. Running the CSR path would discard the server’s composed children and re-fetch everything.
3. Layouts cannot nest — refused on both render paths, and the slot picker never offers one (Layouts cannot nest).

Not supported yet. Because of (1) and (2), a plugin layout shell can never be interactive on a server-rendered page — no React tree is ever attached to it. Its slot children hydrate themselves normally, so put interactivity in a content widget and bind it into a slot.

Before you submit

Walk the full checklist, then the packaging rules in Packaging and publishing rules — your media/ icon and readme must be committed, because the reviewer only runs your build. The submission flow itself is Preflight and submit.

Anatomy of a plugin

A plugin is three things wearing one directory: source you author, artifacts your build produces, and content nothing produces but the platform still expects. Every consumer downstream — the reviewer, central, the renderer, the dashboard, the browser — reads a different subset of those files. Once you know which file is which, the rest of this book is detail.

This page is a map, not a rule set. Field rules live on the contracts pages.

Two trees

The scaffold’s project and a real published plugin look surprisingly different. Roughly half of what create-hr-plugin gives you is a local sandbox that never reaches a customer, and the one real suite in the fleet ships none of it.

(a) The single-widget scaffold

# what `npx create-hr-plugin my-widget` writes — `--template single`, the
# default (create-hr-plugin 0.8.1)
my-widget/
├── manifest.json           # SHIPPED. Identity + the v1 single-widget fields. Rewritten by the build.
├── package.json            # SHIPPED (source zip). Pins react/react-dom/react-query exactly.
├── package-lock.json       # appears after `npm install`. Ship it — absent is a publish warning.
├── tsconfig.json           # SHIPPED (source zip), never published
├── vite.config.ts          # SHIPPED (source zip). Delegates to viteHomerunnerWidget().
├── README.md               # yours, developer-facing. NOT the marketplace readme — that is media/.
├── .env.example            # dev only. Copy to .env.local; consulted by `?mock=off` and dev:ssr.
├── .gitignore              # written from the template's `_gitignore` (npm strips real dotfiles)
├── index.html              # DEV ONLY — deletable. Loads /src/dev/main.tsx, falling back to
│                           #   the BUILT bundles when that 404s under `npm run preview`.
├── serve.js                # DEV/DEMO ONLY — deletable. Zero-dep node:http static server.
├── vercel.json             # DEMO ONLY — deletable. Self-hosted preview deploy config.
├── api/
│   └── widget-asset.ts     # DEMO ONLY — deletable. Vercel edge /w/ → hashed-dist redirect.
├── public/
│   └── mockServiceWorker.js  # DEV ONLY — kept out of `dist/` since 0.8.0; see below.
├── mocks/
│   └── fixtures.ts         # DEV ONLY — deletable. Overrides for the mock endpoints.
├── scripts/
│   ├── inject-schema.mjs   # YOURS, and required. zod → JSON Schema → manifest.json.
│   └── dev-ssr.mts         # DEV ONLY — deletable. Boots the local SSR preview.
└── src/
    ├── index.tsx           # SHIPPED. Client IIFE entry: registerPlugin() + mount().
    ├── widget.tsx          # SHIPPED. Your component (+ getInitialData in this template).
    ├── ssr.ts              # SHIPPED. dehydrateState + getStaticAssets.
    ├── ssr-entry.ts        # SHIPPED. Re-export barrel — the SSR bundle's entry point.
    ├── config.ts           # SHIPPED. widgetSchema.extend() + zodToManifestSchema().
    ├── widget.css          # SHIPPED. Tailwind import + your styles.
    ├── data.ts             # SHIPPED. Sample public-api fetcher + a query-key factory.
    ├── dev/                # DEV ONLY — deletable.
    │   ├── main.tsx        #   the entry index.html loads: mock worker → mount → panel
    │   └── DevPanel.ts     #   the bottom control bar
    └── components/ui/      # SHIPPED and yours. Vendored Button/Dialog/Carousel/Stylesheet/
                            #   WidgetSection/…; widget.tsx imports `cn` from here.

Everything marked DEV ONLY or DEMO ONLY can be deleted without affecting what customers load. You lose the local sandbox and the SSR preview, nothing else — see Dev sandbox and mocking and Previewing SSR locally.

serve.js, vercel.json and api/widget-asset.ts in particular imitate the platform’s own asset proxy for a self-hosted demo. The publish pipeline never touches them, because you host nothing: you submit source, and HomeRunner builds and serves the result. See From your laptop to a customer page.

(b) A real published suite (widget-core 0.11.0+)

# /Users/…/hr-plugins/pdp-suite — the published v1.3.3 source tree (50 zip entries, 82 KB)
pdp-suite/
├── manifest.json                    # root manifest: widgets[] (4) + presets[] + media refs
├── package.json                     # three scripts: dev, build, build:manifest
├── package-lock.json
├── tsconfig.json
├── vite.config.ts                   # 13 lines — identical in shape to the single-widget one
├── scripts/
│   └── inject-schema.mjs            # same script, multi-widget branch
├── widgets/                         # GENERATED by build:manifest, but COMMITTED and shipped
│   ├── pdp-frame.manifest.json
│   ├── stay-hero.manifest.json
│   ├── stay-facts.manifest.json
│   └── booking-cta.manifest.json
├── media/                           # AUTHORED. Nothing generates this directory.
│   ├── README.md                    #   declared as manifest.readme
│   ├── CHANGELOG.md                 #   picked up by filename convention, declared nowhere
│   ├── pdp-frame.svg                #   per-widget icons — flat, one level
│   ├── stay-hero.svg
│   ├── stay-facts.svg
│   ├── booking-cta.svg
│   └── widgets/
│       ├── pdp-frame.md             #   per-widget readmes — one nested level is allowed
│       └── …
└── src/
    ├── vite-env.d.ts
    └── widgets/
        ├── pdp-frame/               # the layout
        │   ├── index.tsx            #   registerPluginWidget(…, { category: "layout" }) + mount
        │   ├── widget.tsx           #   reads props.renderedSlots
        │   ├── config.ts            #   MUST declare a `slots` zod object
        │   ├── ssr-entry.ts         #   one line: export { default } from "./widget";
        │   └── pdp-frame.css
        ├── stay-hero/
        │   ├── … + hero-bg.png      #   a bundled asset, imported from the widget folder
        │   └── ssr-entry.ts         #   present, because this widget declares ssr.url
        ├── stay-facts/              #   "ssr": false → NO ssr-entry.ts at all
        └── booking-cta/             #   "ssr": false → NO ssr-entry.ts at all

No index.html, no src/dev/, no mocks/, no public/, no api/, no serve.js, no vercel.json, no src/components/ui/, and no root README.md. A suite’s public README is media/README.md.

npx create-hr-plugin my-suite --template suite (create-hr-plugin 0.8.0+) writes that same shape — three widgets under src/widgets/, media/, presets[], scripts/inject-schema.mjs — plus the dev-only files this real suite has dropped: index.html, src/dev/, mocks/fixtures.ts, public/mockServiceWorker.js, serve.js, vercel.json, .env.example and scripts/dev-ssr.mts (create-hr-plugin 0.8.1+, and widget-core 0.12.2+ to run it). Every one of those is deletable on the same terms as in tree (a). It also adds src/shared/, which is only a demonstration of relative cross-widget imports. It does not add Tailwind or a src/components/ui/ kit: a layout’s stylesheet is unisolated light DOM on a server-rendered page, so a framework reset would land on the customer’s whole document.

Build a suite covers both the scaffold and the hand conversion; The two manifest shapes is the decision, and it is permanent once you publish.

Who authored what

Three categories, and confusing them is the most common cause of a publish that fails after your submission was accepted.

Authored by you. Everything under src/, manifest.json, vite.config.ts, scripts/inject-schema.mjs (it lives in your project, not in the SDK — you can edit it), and all of media/.

Generated by the build, and committed anyway. widgets/{slug}.manifest.json (Suite). Your build:manifest step writes them from each widget’s config.ts, and they must be present in both zips because the dashboard fetches them from the CDN to draw the config form.

Generated by the build, and never committed. dist/. The scaffold’s .gitignore already excludes it, and a root-level dist/ in a source zip is rejected — the reviewer rebuilds it from your source. See Packaging and publishing rules.

media/ is content, not output

Nothing generates media/. You create the directory, you draw the icons, you write the README, and you commit them. The reviewer runs your build and nothing else, so a manifest that declares icon: "media/logo.svg" against a file that is not in your source zip passes the upload audit, passes review, and fails at publish. If media/ is in your .gitignore, or your icons live outside it, that is the failure you will hit.

Which paths each media field accepts is on Manifest: root fields; the commit rule and the exact publish errors are on Packaging and publishing rules.

What npm run build changes on disk

npm run build is npm run build:manifest && hr-widget-build. Between them they rewrite your tracked manifest.json twice:

1. build:manifest (scripts/inject-schema.mjs) injects the schemas. (Single-widget) it writes configSchema and uiSchema into the root manifest. (Suite) it writes one widgets/{slug}.manifest.json per summary and back-fills each summary’s manifest path — the root manifest never carries a schema.
2. The build’s finalize pass stamps runtime.widgetCore with the SDK version it built with, and logs runtime.widgetCore stamped: X.Y.Z.

So manifest.json is dirty in git after every build. That is correct — commit it. Never hand-write runtime.widgetCore; the publish audit gates on the stamped value.

The same pass walks dist/, writes a content-hashed twin next to every file, and emits dist/manifest.json — the build manifest, {buildHash, generatedAt, files}, keyed by dist-relative path. .map files and manifest.json itself are skipped by the hashing pass but sourcemaps are still published.

# /Users/…/hr-plugins/pdp-suite/dist — the real output of one `npm run build`
dist/
├── manifest.json                          # the build manifest — hashed twins, keyed dist-relative
├── pdp-frame/
│   ├── pdp-frame.iife.js  + …-be6fddd4.js # client bundle + hashed twin
│   ├── pdp-frame.css      + …-9992937d.css
│   ├── pdp-frame-ssr.umd.js + …-5872d9b8.js
│   └── pdp-frame.iife.js.map              # published, but absent from the build manifest
├── stay-hero/
│   └── … + hero-bg-Cr1v4Zys.png           # a bundled asset (widget-core 0.12.0+)
├── stay-facts/                            # iife + css only — "ssr": false
└── booking-cta/                           # iife + css only — "ssr": false

File-naming rules, the {env}/{slug}/{version}/ CDN key and how a URL is resolved live on Keywords, assets and URLs.

The MSW leak, and its fix. Both scaffolds put the mock service worker in public/, and Vite copies publicDir into outDir on every production build — so on scaffolds older than create-hr-plugin 0.8.0, mockServiceWorker.js and a hashed twin end up in your published assets and in dist/manifest.json. Harmless but pointless. 0.8.0’s vite.config.ts returns publicDir: command === "build" ? false : "public", which keeps it out of the build and leaves npm run dev untouched; add that line yourself if your project predates it. (The real suite has no public/, so it never had the leak.)

The artifacts, and who reads each one

After the reviewer builds and publishes, a handful of file kinds sit on the CDN under one immutable version prefix. They have almost disjoint audiences:

Two consequences worth designing around:

• Only the ROOT manifest is cached and shipped per render. Keep it small. That is the whole reason a suite’s schemas live in sub-manifests instead of inline — see Config schema and UI schema.
• The sub-manifest fetch is best-effort. If it is missing or slow the dashboard degrades to a schemaless panel rather than erroring — but a sub-manifest your manifest declares and your zip does not contain is a hard publish failure.

The end-to-end path — source zip, review, built zip, CDN, install — is From your laptop to a customer page. What each render path does with these bundles is How a widget renders.

TypeScript setup

The scaffold’s tsconfig.json is byte-identical to the real suite’s, so treat it as the platform baseline: jsx: "react-jsx", target: "ES2017", module: "ESNext", moduleResolution: "bundler", lib: ["ES2020", "DOM", "DOM.Iterable"], strict, noEmit, isolatedModules, and a @/* → ./src/* path alias.

include is ["src/**/*", "vite.config.ts"] only. mocks/, scripts/, serve.js and api/ sit outside the TS project, and there is no typecheck script — nothing type-checks your project unless you add "typecheck": "tsc --noEmit" yourself. Vite’s build does not type-check either.

Where to go next

• The two manifest shapes — the one decision you cannot undo after publishing.
• Your first widget — edit this tree until something renders.
• Build a suite — convert the flat tree into src/widgets/.
• Packaging and publishing rules — exactly what may be in each zip.

The two manifest shapes

Every HomeRunner plugin is one of two things, and you choose which on the day you write your first manifest.json:

• a single-widget plugin (the v1 shape) — one widget, described by root-level fields;
• a suite (the multi-widget shape) — up to 24 widgets under one version, one review and one publish, each described by an entry in widgets[]. (widget-core 0.11.0+)

Both shapes are supported forever, and neither is deprecated. But the shape is frozen at your first publish: the only way out of the wrong choice is a new plugin slug — a new marketplace listing your existing customers would have to install and re-configure. Most authors take the single-widget shape because it is the scaffold’s default, then discover six months later that they want a second widget, a layout, or a preset. It is one flag either way — decide on purpose. The short answer is in Which should I choose: start as a suite, even with one widget.

The discriminator is one line

// packages/homerunner-widget-core/src/manifest.ts — isMultiWidgetManifest
return Array.isArray(manifest.widgets) && manifest.widgets.length > 0;

That is the whole test. There is no version flag, no type field, no "shape" key. A manifest with a non-empty widgets array is a suite root; anything else — widgets absent, widgets: [], widgets: {} — is a v1 single-widget manifest.

The same predicate is re-implemented at every layer that touches your plugin, which is why one array reconfigures so much at once:

Central applies it too, comparing your new manifest against the live one — that is the freeze, and it is the subject of The one-shape rule below.

Side by side

Full field tables live in Manifest: root fields and Manifest: widget summary. This is the difference, not the reference.

A v1 root, from the scaffold:

// packages/create-hr-plugin/template/manifest.json (placeholders substituted)
{
  "id": "my-widget",
  "version": "1.0.0",
  "name": "My Widget",
  "widgetType": "my-widget",                 // required here; its VALUE is never read
  "ssr":    { "url": "dist/my-widget-ssr.umd.js" },
  "assets": { "js": "dist/my-widget.iife.js", "css": "dist/my-widget.css" },
  "runtime": { "react": "^19.0.0" }
  // the build injects "configSchema" and "uiSchema" at this level
}

The same plugin as a suite of one — note what moved and what disappeared:

// DERIVED: the manifest above rewritten in the shape of
// pdp-suite (reference plugin): manifest.json — widgets[] with one entry
{
  "id": "my-widget",
  "version": "1.0.0",
  "name": "My Widget",
  "runtime": { "react": "^19.0.0" },
  "widgets": [                               // presence => suite. No widgetType,
    {                                        // no root ssr/assets/configSchema.
      "slug": "hero",
      "name": "Hero",
      "ssr":    { "url": "dist/hero/hero-ssr.umd.js" },
      "assets": { "js": "dist/hero/hero.iife.js", "css": "dist/hero/hero.css" },
      "manifest": "widgets/hero.manifest.json"
    }
  ]
}

Every customer of the first manifest stores the keyword plugin:my-widget. Every customer of the second stores plugin:my-widget:hero. Those two strings are the whole reason the shape can never change.

Mixing the shapes is not an error

Mutual exclusivity is convention, not enforcement. A manifest that carries both widgets[] and the v1 root fields passes every validator: resolution takes the suite branch, silently ignores root widgetType / ssr / assets / configSchema, and the bare plugin:{slug} keyword stops resolving. Nothing tells you. Delete the root fields when you convert.

Shape mismatches fail closed

Resolution never guesses. When the stored keyword and the manifest disagree, the resolver returns null and the widget is removed — it is never rendered with defaults, and never falls back to another widget.

Keyword grammar is specified in Keywords, assets and URLs.

A null looks different on each of the three paths a plugin reaches a customer through:

• Server-rendered pages. The renderer replaces the widget with a hidden breadcrumb node carrying data-hr-widget-error="{keyword}" and an HTML comment whose reason is keyword does not resolve against the plugin manifest. The rest of the page renders normally, and the page is flagged degraded so it caches for a much shorter window. View-source and search for data-hr-widget-error. The full reason index is in Limits and error index.
• CSR embeds. Nothing errors, because nothing runs. The copied snippet’s script tag is derived from the keyword — /p/{slug}/{slug}.iife.js for v1, /p/{slug}/{widget}/{widget}.iife.js for a suite — and the proxy serves only files the live manifest declares, so a stale embed gets {"error":"Asset not in plugin manifest"} and the host <div> is left untouched.
• The dashboard. A keyword that no longer resolves against the manifest yields no schema, so the customer’s config form degrades to a schemaless panel rather than erroring.

Every one of those is silent from your side. Nobody is notified — not the customer, not you.

The one-shape rule

Before your first publish you can convert freely. The gate compares your new manifest against the plugin’s live one, and an unpublished plugin has none. Flip as often as you like while you are building.

After your first publish the shape is permanent. Central refuses a manifest that flips it with 422 MANIFEST_SHAPE_CHANGED, on publish and on rollback, so you cannot even roll back across a shape change. The dashboard mirrors the same check just before the reviewer uploads the built zip. Both messages are quoted verbatim in Limits and error index.

The trap is when it fires:

So a shape flip passes your own audit, passes submit, and passes review. You are told the submission looks fine, and days later the publish dies. Do not read “the reviewer approved it” as “the shape is acceptable”.

The reason is a serving contract, not a policy: customers’ widget rows store the keyword, customers’ web pages contain copied embed URLs built from that keyword, and neither survives a shape change. Both would resolve to null on the very next render, across every feed at once.

The only remedy is a new plugin slug. manifest.id is the slug, so a new shape means a new id, a new plugin row, a new marketplace listing and a new CDN prefix. Your existing customers keep running the old plugin, and reach the new one only by installing it and re-creating their widgets from it.

Not supported yet. There is no migration path, no alias, no “this plugin replaces that plugin” pointer. replacedBy exists in the widget summary type and is read by nothing. Inside a suite you can retire a widget with deprecated: true and keep every placement rendering — see Manifest: widget summary. There is no equivalent for retiring a whole shape.

Which should I choose

Start as a suite, even with one widget. A suite of one is legal, publishes normally, and costs you nothing you cannot get back. Choosing v1 costs you a decision you cannot revisit.

A suite used to cost you the dev tooling. It no longer does: --template suite generates a suite-aware sandbox (create-hr-plugin 0.8.0+) and a dev:ssr script (0.8.1+), and nothing in the build was ever single-widget-shaped — hr-widget-build branches on widgets[] itself, and the scaffold’s vite.config.ts and scripts/inject-schema.mjs handle both shapes with no edits. Two limits are left, and both are local-only:

Not supported yet. The dev sandbox holds one mock state for the whole page — scenario, latency, branding and the widget settings object are a page singleton, so two widgets with the same field name share its value. And there is no server-side slot composition locally: npm run dev:ssr renders the one widget you named, so a layout previews with empty slots. Details in Dev sandbox and mocking and Previewing SSR locally.

So the recommended path is now the short one:

1. Scaffold the shape you actually want: npx create-hr-plugin <slug> --template suite, even if it holds one widget. See Build a suite.
2. If you started single-widget and changed your mind, convert before you publish — rewrite manifest.json and move src/* under src/widgets/{slug}/. Same page.
3. Publish. From here the shape is fixed, but you can add widgets, a layout and presets in any later version.

Choose v1 deliberately only when all of these are true: the plugin is one widget, it will always be one widget, it server-renders, and you want the single-widget template’s Tailwind and src/components/ui/ kit more than you want the option to grow. A marketing badge or a one-off embed is a fair v1. Anything you expect to iterate on is a suite.

Suites need @homerunner-next/widget-core 0.11.0+ (layouts and presets too; assets.fonts and pages need 0.12.0+, slot prefill 0.12.1+, a suite’s npm run dev:ssr 0.12.2+), and the suite scaffold itself needs create-hr-plugin 0.8.0+ — 0.8.1+ for the dev:ssr script it writes. What npm currently serves, and how to get a newer SDK, is in Install and versions.

See also

• Manifest: root fields and Manifest: widget summary — every field, per shape.
• Layout widgets — the capability only a suite can have.
• Anatomy of a plugin — the two source trees side by side.
• Build a suite — the conversion checklist.

How a widget renders

Your plugin is React code that runs in two very different places: a server sandbox with no DOM, and a customer’s browser. Which of those actually run — and in which order — depends entirely on what your manifest declares. There are exactly three paths:

The field rules behind that table belong to Manifest: widget summary and Layout widgets. This page is about what each path does.

The page your widget lands on

A customer’s page is not “your widget”. It is a composed document that may carry a dozen widgets — first-party and plugin, in any mix — sharing one React Query cache and one runtime bundle.

customer's domain
  └─ Cloudflare worker (reverse proxy in front of the customer's site)
       └─ renderer  GET /api/render/{feedId}/property/{slug}
            ├─ resolves the page schema: which widgets, in what order
            ├─ renders every top-level entry CONCURRENTLY
            └─ returns JSON { html, assets, dehydratedState, meta }
       └─ worker splices that html + assets into the site shell
  → browser

The renderer never sends a whole page. It sends a fragment plus an asset list, and the worker composes. That is why your CSS and JS arrive as page-level <link> and <script> tags rather than anything you control, at URLs the platform derives — see Keywords, assets and URLs.

What reaches the browser, in document order:

<!-- Shape derived from packages/homerunner-renderer/lib/render-utils.tsx
     and src/lib/homerunner/cf-worker.ts (page composition). -->
<head>
  <link rel="stylesheet" href="…">          <!-- one per entry in assets.css -->
  <link rel="preload" as="script" href="…"> <!-- one per entry in assets.js -->
  <link rel="preconnect" href="{central api origin}" crossorigin>
</head>
<body>
  <div data-hr-page="…" data-hr-widget-container>
    <div data-hr-widget="plugin:pdp-suite:stay-hero" id="…" data-hr-ssr-id="…">…</div>
    <div data-hr-widget="plugin:pdp-suite:stay-facts" id="…" data-hr-min-height="140"></div>
  </div>
  <script>window.HRWidget.__WIDGET_PROPS__ = { "<ssr id>": { props, options, css } }</script>
  <script>window.HRWidget.__REACT_QUERY_STATE__ = { … }</script>
  <script src="…/w/runtime.iife.js" defer></script>
  <script src="…/p/pdp-suite/stay-hero/stay-hero.iife.js" defer></script>
</body>

Three page-level facts follow from that shape, and every path below depends on them:

1. Props travel in a registry, not in attributes. Each host carries a small data-hr-ssr-id key; one inline script holds every widget’s props, per-embed options and stylesheet list. If that script is blocked — a strict CSP, an ad blocker, an HTML-rewriting CDN — the markup is there but the props are not, and your widget falls through to the client-render path instead of hydrating.
2. One shared React Query cache. Everything the server prefetched is serialised once and rehydrated into a single browser-side client that every widget on the page shares. Namespace your query keys or you will read someone else’s data.
3. The runtime IIFE loads before yours. Since widget-core 0.10.0 your bundle contains no React, no React DOM, no React Query and no widget-core runtime — they resolve off window.HRWidgetRuntime at execution time. Your IIFE then registers your component and calls mount().

The complete attribute contract, the boot order and the registry lookup rules are in Runtime, mount and the DOM contract.

Path 1 — a content widget with SSR

What runs on the server

The renderer fetches your published SSR bundle, evaluates it once in a node:vm sandbox (cached afterwards), then, inside a single try:

# packages/homerunner-renderer/lib/render-utils.tsx (getWidgetMarkup)
getInitialData(ctx) → dehydrateState(sharedQueryClient, ctx) → getStaticAssets(settings)
  → renderToString(<WidgetHydrationTree><YourComponent {...props} /></WidgetHydrationTree>,
                   { identifierPrefix: ssrId })

Two things about that sandbox shape the code you can write. It is a bare V8 realm — only a short, fixed list of modules and globals is seeded, so crypto, TextEncoder and Buffer simply are not there. And window/document exist as inert stubs whose property reads return another truthy stub, so if (document) passes on the server. Only typeof window === "undefined" guards are rewritten and tree-shaken out of the SSR bundle. The exact module list, globals, externalFetch rules and execution bounds are in Component and SSR module.

The props you receive are raw — plugin settings are deliberately not parsed for you, on either side. parseWidgetConfig(configZod, props.options ?? {}) is mandatory in the component and in every SSR export. Why, and what raw actually looks like, is Settings and options.

What the customer’s page contains

Your rendered HTML goes inside one host <div>. When the request is Declarative-Shadow-DOM capable, the renderer wraps it in a shadow template instead of emitting it bare:

<!-- packages/homerunner-renderer/lib/render-utils.tsx — DSD-capable request -->
<div data-hr-widget="plugin:pdp-suite:stay-hero" id="{widgetId}:{feedId}" data-hr-ssr-id="…">
  <template shadowrootmode="open">
    <link rel="stylesheet" href="…">        <!-- your CSS, plus any declared fonts -->
    <div class="hr-react-root">…your markup…</div>
    <div class="hr-portal-container"></div>
  </template>
</div>

What runs in the browser

Your IIFE registers your component, then mount() finds the host, adopts the shadow root, and hydrates the existing DOM in place. Nothing re-renders from scratch and no data is re-fetched — the query cache already holds what the server prefetched.

Where your code can fail

Four distinct ways, and they behave very differently. A throw in any data hook or in your component during the server render is contained the same way: your widget is replaced by a hidden breadcrumb node, the rest of the page renders, and the page is marked degraded — its cache lifetime collapses at every layer so it re-renders soon rather than serving a broken version for a day. A rejected prefetch inside a queryFn is quieter still: it is swallowed by design, logged, and your widget ships whatever it renders with no data (if that is a spinner, crawlers see a spinner). A throw in the browser is caught by the render boundary, which marks the host and shows a neutral error card. And output that merely differs between the two passes does not throw at all — React silently discards your server DOM; see Hydration.

The full failure table, the breadcrumb markup and the log lines to grep are in Component and SSR module; the numbers are in Limits and error index.

Declarative Shadow DOM, conceptually

Every content widget renders inside a shadow root: it is what stops the customer’s site CSS from repainting your widget and your CSS from leaking into their page. The only question is when that root is created.

Without DSD, the browser parses your markup into the light DOM, and JavaScript creates the shadow root, moves the markup into it, attaches the stylesheets and waits for them. Your widget is briefly visible unstyled, or briefly hidden — the mount blink.

With DSD, the server ships a <template shadowrootmode="open"> and the browser attaches and styles the root while parsing. By the time your JavaScript runs there is nothing to build and nothing to wait for. No blink, correct paint on the very first frame, and — with the right CSS — correct dark mode before any script executes.

A plugin earns a DSD template only when all of these hold:

mount() then takes one of three branches, in order:

# packages/homerunner-widget-core/src/runtime/mount.tsx
1. ADOPT   host.shadowRoot already exists (native DSD) → already styled, hydrate now
2. ADOPT   an inert <template shadowrootmode> in light DOM → attach it, then wait for CSS
3. BUILD   no template at all → create the shadow root, move the server markup into it

Branch 3 is the migrate path: it moves nodes with appendChild rather than re-serialising through innerHTML, because hydration matches on node identity. That is one of several reasons you must never call hydrateRoot yourself.

Two conceptual traps worth carrying with you:

• Your manifest’s shadowDOM and what your bootstrap passes to mount() must agree. Declare shadow DOM and mount with shadowDOM: false and the browser attaches the server’s shadow root at parse while your code renders into the light DOM, which is never displayed: visible server content that never hydrates. Nothing checks this before you ship, and it looks fine on a browser that missed the DSD bucket. The full matrix is in Runtime, mount and the DOM contract.
• DSD is what makes correct dark-at-first-paint possible at all. The server cannot know the visitor’s colour scheme (resolvedTheme is effectively always light in production), so first-paint dark has to come from CSS inside that template. The recipe is in Styling and theming.

Path 2 — a CSR-only content widget

Suite only (widget-core 0.11.0+). Declaring "ssr": false on a widget summary opts it out of the server pipeline entirely. It has no ssr-entry.ts, no SSR bundle, and its component is never invoked on the server. This is a suite-shape feature: a single-widget manifest with no ssr.url is a failure, not a CSR-only widget — the renderer drops it.

What the renderer still does: emit an empty host div, add your JS and CSS to the page’s asset list, add a registry entry carrying the per-embed options, and — when the summary declares expectedHeight — stamp a minimum height on the host so the page does not jump when the widget finally paints.

<!-- packages/homerunner-renderer/lib/render-utils.tsx — the ssr:false branch -->
<div data-hr-widget="plugin:pdp-suite:stay-facts" id="{widgetId}:{feedId}"
     data-hr-ssr-id="…" data-hr-min-height="140"></div>

In the browser, mount() sees a childless host, takes the client-render path, and your component is rendered by a wrapper that first resolves settings: it fetches the feed and the widget row, merges feed branding, feed globals, the stored settings and the per-embed override, and hands you the result. So on this path your options are resolved in the browser from a live config fetch rather than baked into the HTML — still not schema-parsed, so parseWidgetConfig remains mandatory — widgetType is supplied (it is not on the SSR path), and data is undefined because no getInitialData ever ran.

On a server-rendered page that config query is pre-seeded by the renderer and travels in the dehydrated state, so it resolves from cache with no network round trip. In a hand-written CSR embed on a page the renderer never touched, it is two live API calls before anything paints.

Where your code can fail here: a render throw is caught by the render boundary and the host is marked; a failed config fetch renders the shared error state instead of your widget. Both markers, and the full vocabulary, are in Runtime, mount and the DOM contract.

Choose CSR-only deliberately. You lose server HTML (nothing for crawlers, a later first paint, a real CLS risk unless you set expectedHeight). You gain a much simpler build, no sandbox constraints, and live editing — the dashboard’s options-updated preview channel works on this path and does not work on a hydrated SSR widget.

Path 3 — a layout widget

Suite only (widget-core 0.11.0+). A layout does not render content; it renders regions, and the platform fills them with other widgets bound into named slots. Its render path is inverted relative to everything above.

# packages/homerunner-renderer/lib/render-utils.tsx (getLayoutWidgetMarkup) — SSR
1. collect every binding across every slot (a binding to a missing widget is logged, skipped)
2. render ALL slot children CONCURRENTLY
     each child is a complete island: own SSR id, own DSD template,
     own props-registry entry, own assets
3. reassemble each slot in binding order  →  renderedSlots[slotName] = <>{…children}</>
4. load YOUR layout bundle LAST, run its optional data hooks, render the shell
5. unshift the layout's CSS and JS ahead of every child's assets

Your component receives the finished children as React nodes in renderedSlots and simply places them. The shell is then emitted as static light DOM — no shadow root, no DSD template, no SSR id, no props-registry entry.

That has three consequences that consistently read as bugs and are not:

• Your layout CSS is document-level on every server-rendered page. Namespace every class, never write a :host-only rule for the shell, never paint a background. Details in Layout widgets and Styling and theming.
• The client mount is a deliberate no-op. Running the client path there would throw away the server’s slot children and re-fetch everything. Each child hydrates itself through its own IIFE.
• A layout that throws during render takes the whole page down. Content widgets render inside a try; a layout shell is returned as an un-rendered element and rendered later, in the page’s single renderToString, which has none. Parse defensively and default every slot.

Not supported yet. Because the shell has no SSR id, no registry entry and no mount, a plugin layout can never be interactive on a server-rendered page — no React tree is ever attached to it. Put interactivity in a content widget and bind it into a slot. See Layout widgets.

Not supported yet. Layouts cannot nest. A layout bound into another layout’s slot is refused on both render paths, before anything renders.

The same layout in a CSR embed is the mirror image

Drop a layout into a single-snippet embed and everything inverts: the shell does get a shadow root, and your layout mounts its own children — reading the stored slot bindings, fetching each child’s row, loading each child’s bundle, waiting for it to register, then mounting it into a host div after commit. It also pushes the parent colour scheme and, when it resolved one, the property filter onto every child.

So a layout stylesheet has to work document-level and inside a shadow root, and renderedSlots means two different things on the two paths — server-rendered nodes on one, childless host divs on the other. The shapes differ too: a slot that was never bound is absent from the object on the server but present as an empty array on the client, so slots.hero ?? fallback does not behave the same way in both places. The per-path prop table is in Layout widgets.

Hydration, in one idea

Hydration is React adopting DOM it did not create. It walks your component tree and the existing markup in lockstep and attaches event handlers to the nodes it finds. It works only while the two agree.

The platform makes them agree by rendering each widget as an isolated React root on the server, inside a fixed wrapper, with an identifier prefix derived from that widget instance — and by having mount() mirror the wrapper shape and the prefix exactly. React derives useId values from tree position plus that prefix, so any drift makes every useId consumer (Radix dialog and popover aria attributes, form ids) mismatch. React’s response is not a warning: it silently regenerates the tree and discards every byte of your server HTML.

Which gives you three rules — Both shapes, all runtime, nothing checks them before you ship:

1. Mount through widget-core’s mount(). Never call hydrateRoot yourself; you cannot reproduce the wrapper and prefix from outside.
2. Render deterministically. No Math.random(), no Date.now(), no reading window, and no reading props.widgetType — it is absent on the SSR/hydrate path and present on the CSR path, which makes it a hydration trap disguised as a prop.
3. Do not fetch by suspending during render. renderToString does not await; a suspended boundary ships its fallback into the HTML. Fetch in getInitialData or dehydrateState.

The wrapper, the prefix and the exact prop differences per path are in Component and SSR module.

Failure containment, end to end

One design rule explains most of the platform’s behaviour here: a plugin must not be able to break a customer’s page. Everything except one case is contained.

Every hidden breadcrumb stays in the page source, so curl plus view-source tells you which widget the platform dropped and why. Symptom-first diagnosis is in Troubleshooting.

Related

• Exports, props, the sandbox and the hydration contract: Component and SSR module
• mount(), DOM attributes, shadow-DOM lifecycle: Runtime, mount and the DOM contract
• Slots, renderedSlots, page assignment: Layout widgets
• Why options is raw and what merged it: Settings and options
• Dark mode at first paint, shadow-safe CSS: Styling and theming
• Running the server path on your machine: Previewing SSR locally

Settings and options

Every widget you ship has a settings blob. A customer edits it in the dashboard, central stores it, the platform merges it with the feed’s branding, and the result lands on your component as props.options. One thing to remember from all of that:

props.options arrives RAW — on the server and in the browser. Nothing schema-parses it for you. Call parseWidgetConfig(configZod, props.options ?? {}) yourself, in your component and in getInitialData, dehydrateState and getStaticAssets. Both shapes, widget-core 0.9.0+.

The rest of this page is the chain that makes that rule necessary — read it once and the storage artifacts, stringified numbers and colorScheme surprises stop surprising.

The chain

config.ts (zod) --zodToManifestSchema--> manifest.configSchema   build time, yours
   |
   v  "Create widget": schema defaults + feed branding (no colorScheme) + filter.feed_id
   v
   widget.settings  <--- the form autosaves the raw value on every change
   |                (opaque JSON on central: nullable|array, replaced wholesale)
   v
   getFinalSettings(widget, feed, optionsOverride?)
   |    feed branding -> feed globals -> widget.settings -> per-embed override
   v
   props.options  -- RAW, on the server and in the browser
   v
   parseWidgetConfig(configZod, props.options)   <-- your job, at every entry point

The chain runs in two places: server-side in the renderer for an SSR widget, client-side in the runtime for a CSR embed. Both call the same merge function and hand you the same unparsed object — see How a widget renders.

One setting, end to end

Take the simplest field in the reference suite — a heading with a default.

// pdp-suite (reference plugin): src/widgets/stay-facts/config.ts
export const configZod = widgetSchema.extend({
  heading: z.string().default("Key facts").describe("Section heading"),
  facts: z
    .array(z.string())
    .default(["Sleeps 6 in 3 bedrooms", "Fast wifi + workspace", "5 min to the beach"])
    .describe("Facts, one per line"),
});

zodToManifestSchema(configZod) turns that into JSON Schema and your build writes it into the manifest (single-widget shape) or the widget’s sub-manifest (suite shape); the dashboard reads it back and builds the form. Which zod constructs survive that round trip is normative in Config schema and UI schema.

1. Creation: your defaults become stored values

When a customer creates a widget from your plugin, the dashboard seeds widget.settings with your schema’s default values, layers the feed’s branding over them (minus colorScheme, so the widget keeps inheriting live), and forces filter.feed_id. The exact composition is in Config schema and UI schema. Both shapes.

• Branding wins over your default for the branding keys. If your schema defaults font.family, the feed’s value overwrites it at creation. Pick defaults for your own fields; treat the base theme fields as the customer’s.
• A default stops being a default the moment the row is written. Changing default() in a later version never reaches widgets that already exist. Migrate in your component (read the old shape, fall back) instead.

2. The dashboard form: live validation is cosmetic

The plugin config form validates on every keystroke and shows errors as path.to.field: message. It also autosaves on every change — including while the form is invalid.

// src/app/(protected)/feeds/[id]/widgets/[widgetId]/[widgetName]/playground/PlayGround.tsx
const handleChange = async (data: any) => {
  const cleaned = stripEmptySlotEntries(data);  // the ONLY transform on the plugin path
  await upsertWidget({ id: widget.id, feed_id: widget.feed_id,
    keyword: widget.keyword, status: widget.status, settings: cleaned });
};
// wired as:  <Form liveValidate onValueChange={handleChange} ... />

Central accepts the blob as 'settings' => 'nullable|array' and replaces it wholesale — no partial merge, no schema check, no 422 for a bad value.

Not supported yet. Nothing validates stored settings at any layer — advisory (unvalidated). Your own parseWidgetConfig call is the only real gate, and it runs on the customer’s page, not in the dashboard. A cross-field rule written with .refine() is erased by the manifest round trip and enforced nowhere.

The plugin save path runs stripEmptySlotEntries (blank slot bindings on a layout) and nothing else; the blank-row strippers system widgets get never run for plugins — see the Translations gap in Config schema and UI schema.

3. Storage: what central does to your JSON

Your blob makes two lossy trips: Laravel’s request middleware on the way in, and PHP’s array cast on the way out. Three artifacts reach production plugins.

You repair none of these by hand: parseWidgetConfig absorbs all three. See Config schema and UI schema for what it does to each, and in what order.

One consequence is worth designing around. A cleared text field is stored as null, and a null your schema rejects is stripped — so clearing a field that has a default() silently restores your default on the next render: an empty input in the dashboard, your placeholder text on the page. If “deliberately cleared” must be distinguishable from “never touched”, declare that field .nullable() so the null survives the strip and reaches you as a real value.

4. The merge: getFinalSettings

Stored settings are never handed to you alone. The runtime merges them first.

// packages/homerunner-widget-core/src/runtime/api.ts
getFinalSettings<T>(widget: Widget<T>, feed: Feed, optionsOverride?: Partial<T>): T

The widget comes first, then the feed. The old guide had these reversed, and so does anything copied from it. The signature is tabulated in SDK reference; the precedence below is this page’s.

Merge order, lowest priority first:

1. Feed branding — colorScheme, the light and dark accents, font.size, font.family.
2. Feed-wide globals — explorer and booking defaults. These never apply to a plugin: the scope test is on the widget’s keyword and yours is plugin:{slug}[:{widget}], so this step is always empty. Both shapes.
3. widget.settings — the stored blob.
4. optionsOverride — the per-embed data-hr-options payload, and how a layout pushes state onto its slot children. See Runtime, mount and the DOM contract.

Three behaviours that bite:

• Arrays replace wholesale. A higher-priority array is taken atomically, never merged by index. A stored facts: ["one"] replaces your three-item default outright — it does not leave entries two and three behind.
• __parentColorScheme is reserved. A layout pushes its own resolved scheme onto every slot child under this key. It is stripped before the merge and consulted only when the child chose no concrete scheme, so a child that picked dark keeps dark. Never declare it in your schema or read it as a setting; see Layout widgets.
• colorScheme always resolves to something concrete. global, null and absent all mean “inherit”: the pushed parent scheme wins, else feed branding, else the terminal default light — not auto. A visitor’s OS preference is honoured only when someone explicitly chose auto.

The merge finishes by lifting a legacy width: {maxWidth, unit} onto spacing and normalising customCss to "". That is all of it — no zod, and none of your configSchema defaults.

5. Your component: raw, on both sides

// pdp-suite (reference plugin): src/widgets/stay-facts/widget.tsx
export default function StayFacts(props: { options?: Record<string, unknown> }) {
  const cfg = parseWidgetConfig(configZod, props.options ?? {});
  return <h3 className="sfacts-heading">{cfg.heading}</h3>;
}

cfg.heading is a string. props.options.heading may be null, missing, or a value your schema rejects. Read the parsed object, never the raw one.

That includes fields the platform injects rather than the customer: because you built your schema with widgetSchema.extend({...}) the base filter is declared, so the filter.property a layout pushes into a slot child survives the parse and reads as cfg.filter?.property. Keys your schema does not declare are dropped, which is the point rather than a loss. The same rule applies to every server-side export:

// packages/create-hr-plugin/template/src/ssr.ts — scaffold guidance, made executable
export async function dehydrateState(
  queryClient: QueryClient,
  ctx: { options: Record<string, unknown>; feedId: number; widgetId: string },
) {
  const options = parseWidgetConfig(configZod, ctx.options);  // ctx.options is RAW too
  await queryClient.prefetchQuery({ /* ... uses options ... */ });
}

System widgets get a parsed object in those three hooks; plugins do not, and that is deliberate — your schema is a zod value the renderer has never seen.

A parse failure is not silent. parseWidgetConfig ends in schema.parse, so it throws: on the client the render boundary catches it and marks the host data-hr-error="render-failed"; on the server a content widget is dropped from the page while a layout shell takes the whole page down. Both the export contract and those failure semantics live in Component and SSR module.

What the platform does not apply for you

The base schema gives every widget theme fields. Merging them is the platform’s job, rendering them is yours — nothing in mount() or the renderer injects customCss, sets a font, or paints an accent colour. Both shapes.

// reviews-marquee (published plugin): src/widget.tsx
const accent = isDark ? options.darkModeColors.accent : options.lightModeColors.accent;
const themeCss = `
  :host {
    --hr-accent: ${accent};
    font-size: ${options.font.size}px;
    font-family: ${options.font.family}, ui-sans-serif, system-ui, sans-serif;
  }
  ${options.customCss ?? ""}   /* after your own rules, so the customer wins */
`;
// <WebFont family={options.font.family} /> <Stylesheet css={themeCss} />
// <div style={resolveWidgetSpacingStyle(options)}> ... </div>

spacing is the one field with a helper: resolveWidgetSpacingStyle(options) returns the style object for your outer container and absorbs legacy saves. Everything else — section, language, filter — is data you decide what to do with, and a customer who edits a field you never render sees nothing change with no way to know why. Styling and theming covers the full pattern.

Live edits in the dashboard preview

While the customer edits, the dashboard pushes the in-progress settings into the preview frame and the runtime dispatches them as an options-updated event on the mount root, routed back through getFinalSettings so colorScheme: "global" still resolves. It is wired on the CSR content and CSR layout paths only — a hydrated SSR widget has no listener, which is why the preview updates instantly while the same widget on a live page does not. See Runtime, mount and the DOM contract.

Corrections to earlier guidance

Three statements in older versions of this guide were wrong.

See also

• Config schema and UI schema — base widgetSchema fields, round-trip rules, parseWidgetConfig step by step.
• Component and SSR module — WidgetProps, the SSR exports, and what a parse throw does on each path.
• SDK reference — signatures for parseWidgetConfig, getFinalSettings and /spacing.
• Layout widgets — settings.slots and the pushed payload.
• Limits and error index — the enforcement-level legend used above, every hard number, and every message.
• Troubleshooting — “my widget renders blank”.

From your laptop to a customer page

You never publish anything. You submit a source zip; a HomeRunner administrator reads it, builds it on their machine, and publishes the result to the plugin CDN. Everything a customer loads was produced by that person, from your source, after a human decided to allow it.

That one fact shapes the whole pipeline and explains its two most surprising properties: your build output is audited after you have been told your submission was accepted, and nothing anywhere sends you a notification. This page is the map; every rule it mentions is stated normatively on another page, and linked.

The pipeline at a glance

ACTOR         STEP                                        ARTEFACT / STATE
──────────────────────────────────────────────────────────────────────────────────
you           npm run build                               dist/ + a stamped manifest.json
you           zip the project folder                      source zip
                │
your browser    ├─ source-zip audit                       a failure sends nothing at all
your browser    ├─ presigned PUT ────▶ PRIVATE BUCKET     submissions/{slug}/….zip
                │                                          (bytes never transit a server)
dashboard       └─ metadata leg ─────▶ CENTRAL            submission = pending
                │
admin           ├─ downloads the zip, reads your source
                │    changes_requested / rejected ────────▶ back to you, review notes only
                ▼    approved                              visibility fixed here
admin           ├─ runs YOUR build, zips the result       built zip
admin's browser ├─ built-zip audit                        fails = no publish, silently
admin's browser ├─ presigned PUTs ───▶ PLUGIN CDN         {env}/{slug}/{version}/…
                │    the root manifest.json uploads LAST   (the version prefix is immutable)
dashboard       ├─ fetches that manifest back             proves the CDN really serves it
dashboard       └─ publish call ─────▶ CENTRAL            one txn: manifest_url,
                                                           current_version, manifest_cache,
                                                           status = approved
                │
dashboard       └─ warm the renderer, purge every feed    live in seconds, not cache TTLs
                │
customer        ├─ feed ▸ Plugins ▸ Marketplace ▸ Install
customer        └─ Create widget from your plugin         the widget row stores the keyword
                                                           plugin:{slug}[:{widget}]
                │
renderer        resolves that keyword against the         your component renders on a
                cached ROOT manifest                       customer's page

Who acts, and where you watch it

Steps 3 through 7 are one machine sequence with exactly one human decision in it — step 4. After step 2 you cannot influence anything except by submitting again.

The eight steps, in words

1. You build

npm run build produces dist/ and stamps runtime.widgetCore into your tracked manifest.json. That stamp is the platform’s evergreen-runtime gate and the reason a build older than widget-core 0.10.0 cannot be published; it is written by the build and must never be hand-edited. See Install and versions.

2. You zip and upload

(Both shapes.) You zip the project without dist/ and node_modules/ — the reviewer rebuilds those. The uploader audits the archive in your browser first: if it fails, nothing is transmitted at all. On success your browser PUTs the bytes straight into a private bucket using a short-lived presigned URL, so the zip never passes through a dashboard server, and a second call registers the metadata with central.

Two consequences. First, media/ and (for suites) widgets/*.manifest.json must be committed — nothing but your build runs later, and nothing generates them. Second, the browser audit is convenience, not authority: central re-validates everything server-side and adds rules the browser cannot check. Both rule sets, with every limit and every verbatim message, live in Packaging and publishing rules.

3. Central records the submission

The submission lands on your plugin row: status pending, your version, your parsed manifest, your notes. A new slug creates the row and you own it; a slug owned by someone else, or a legacy admin-registered row with no owner, is refused — see the API codes in Packaging and publishing rules.

4. A human reviews it

An administrator downloads your zip, verifies its checksum, and reads your source; for an update they also see a diff of the live manifest against yours. Three outcomes:

Nothing is live yet. Approval is a decision, not a release.

5. The same administrator builds your source

They run your build however they like, zip the built project folder, and drop it into the publish card. A second, different audit now inspects what your build actually produced: declared assets and their hashed twins, the registration marker in every client bundle, sub-manifests, icons, screenshots and READMEs. This is the first moment anyone checks your build output, and it happens after you were told your submission was fine. A failure here does not reopen the review — it costs you a resubmission with a bumped version. Both audits are listed in full, with their exact messages, in Packaging and publishing rules.

6. The version prefix, verification, and the repoint

Files upload one by one into the immutable CDN key prefix {env}/{slug}/{version}/, root manifest.json last. That ordering makes a half-finished publish safe to retry: until the root manifest exists, nothing is live and the sentinel that would refuse a re-publish is absent.

The dashboard then fetches the published manifest back from its public URL and refuses to continue unless it serves and matches the submission — that is what “published” means here, not “we assume the bucket worked”. Only then does central repoint manifest_url, current_version and its cached copy of your root manifest, set the plugin to approved and clear the submission, in one transaction. Publishing therefore also un-suspends a suspended plugin.

Where those URLs resolve to is Keywords, assets and URLs; what a version buys you, and how to undo one, is Publishing, versions and rollback.

7. Warm and purge

Composed customer pages are cached aggressively, so publishing does not wait for TTLs to expire: the dashboard asks the renderer to load your new SSR bundle and purges the page caches of every feed that has your plugin installed. Both are best-effort and neither can fail the publish. Typical propagation is seconds; the documented worst case is the composed-page cache TTL for feeds the fan-out did not reach in its budget. The numbers are in Publishing, versions and rollback.

8. A customer installs it, per feed

Nothing is global. A customer opens a feed ▸ Plugins ▸ Marketplace, installs your plugin, activates it, and only then can create a widget from it. The widget row stores your keyword; the renderer resolves it against the root manifest central cached at publish and loads the bundles it names. Install, per-widget toggles, uninstall and the kill switches that can stop your plugin serving are in Install, customers and kill switches; the keyword and manifest side is Manifest: root fields.

The five states you can be in

Your row in Dashboard ▸ Plugins ▸ My plugins renders one of exactly five timelines.

Review notes are shown inline for the two failure states, followed by “— fix and re-submit the zip above.” A plugin that is live and has an update in review shows both at once: the liveness badge for what is serving, and a timeline sitting at In review.

Nobody will tell you

Not supported yet. There are no notifications of any kind. No email, no in-app alert, no webhook fires when your plugin is approved, rejected, published or suspended. Nothing in the pipeline sends one. The only channel is opening Dashboard ▸ Plugins ▸ My plugins and reading the badge, the timeline and the review notes yourself. Poll it.

Not supported yet. The built-zip audit’s warnings are visible only to the reviewer. A config schema that does not extend the base, an oversized bundle, a filename that cannot be published — none of them block the publish, and all of them are recorded in a browser you will never look at. Unless the reviewer copies them into review notes, you will never learn that your plugin shipped with an empty settings form. Run those checks yourself: Preflight and submit.

A third asymmetry to plan around: the one-shape rule is not enforced before upload. Flipping a live plugin between the single-widget and suite shapes passes the source audit and passes review, and only dies at publish. See The two manifest shapes for the decision and Packaging and publishing rules for the gate.

Re-submitting replaces whatever is in flight

(Both shapes.) Uploading a new zip for the same slug overwrites the in-flight submission from any state — pending, changes_requested, rejected, even approved-but-unpublished. The status returns to pending, the reviewer, notes and review timestamp are cleared, and the previously uploaded zip is deleted.

Your published version is never touched by this. A plugin that is live keeps serving its current version throughout review, rejection and resubmission — the only things that change what customers load are a publish and a rollback. So if an approved submission has not been published yet and you spot a bug, just submit the fix: you are not queue-jumping, you are replacing the artefact the reviewer was about to build.

You host nothing

Third-party plugins cannot be self-hosted. Registering a plugin by pointing central at a manifest URL you control still exists, but it is an administrator-only escape hatch for pre-pipeline plugins: it has no dashboard UI at all, and it refuses a slug that already exists. The zip pipeline is the only path open to you.

This matters because the scaffold looks like it disagrees. serve.js, vercel.json and api/ in a freshly generated project are local preview scaffolding — they serve dist/ on your own machine. They are not a deployment target, nothing on the platform consults them, and you can delete them.

Where each step’s rules live

Manifest: root fields

manifest.json sits at the root of your project, next to package.json. It is the only file the platform reads to learn that your plugin exists, what it ships, and how to serve it. It travels in both zips, is cached by the platform, and is handed to the renderer on every server render.

There are two shapes. A manifest is the suite (multi-widget) root if and only if widgets is a non-empty array; otherwise it is the single-widget (v1) shape. Nothing else distinguishes them — there is no version flag and no type field. See The two manifest shapes for how to choose, and Manifest: widget summary for every field inside a widgets[] entry.

This page is normative for every ROOT-level field. Per-widget fields live in widget-summary.md; layout semantics in layouts.md; every hard number and the full error index in limits-and-errors.md.

Where root fields are enforced

Three checkpoints read your root manifest. This page tags each rule with the one that catches it, because they happen days apart.

publish warning never blocks anything; warnings raised on the built zip are visible only to the reviewer. Enforcement-level vocabulary is defined once in limits-and-errors.md.

Always required (both shapes)

Required in the single-widget shape only

Present these three when widgets is absent or empty. A suite root must not carry them.

Two more root fields are read for v1 manifests but not declared in the PluginManifest TypeScript type, so your editor will not offer them: root-level mediaSafeAuto (strict true) and root-level externalFetch (string[]). Both resolve exactly like their widgets[] counterparts and neither is validated at publish. In a suite, declare them per widget.

Not supported yet. A v1 root has no category, no slots, no pages and no expectedHeight. A single-widget plugin can never be a layout and can never be CSR-only. Both need the suite shape.

Optional everywhere

A media/CHANGELOG.md in your zip becomes the plugin page’s Changelog tab by convention — it is not declared anywhere in the manifest.

Not supported yet. There is no root-level keywords, minPlatformVersion, permissions or dependencies field. Unknown root keys are ignored everywhere, so a typo like "screenshot" fails silently rather than erroring.

id

manifest.id is the plugin slug. Central stores it verbatim after checking /^[a-z0-9][a-z0-9-]*$/; there is no Str::slug normalisation, so My_Plugin is rejected rather than repaired.

The slug is permanent and globally unique across all authors:

• An existing row owned by someone else → 409 SLUG_TAKEN, The plugin id "acme-suite" already belongs to another author.
• An existing row with no owner (a legacy admin-registered plugin) → 409 SLUG_RESERVED, The plugin id "acme-suite" is reserved. Contact an administrator to claim it.

It also constrains your upload key: the submission object must live under submissions/{id}/…, else 422 INVALID_ZIP_KEY. Full submit flow in ship/preflight-and-submit.md.

Your id is the first half of every keyword the platform stores against a customer’s widget row (plugin:{id} or plugin:{id}:{widget}), which is why it can never change.

version

Three hard rules, in the order you will hit them:

1. Shape, in the browser. /^\d+\.\d+\.\d+(-…)?(\+…)?$/. 1.2 fails with manifest "version" ("1.2") is not valid semver (e.g. 1.2.0).
2. Three parts, at central. Composer’s parser would accept 1.0; central re-checks with its own regex and returns 422 INVALID_VERSION, Manifest "version" must be MAJOR.MINOR.PATCH semver: 1.0.
3. Strictly greater, at central. 422 VERSION_NOT_GREATER, Version 1.2.0 must be greater than the published 1.3.0.

One version number covers the whole suite. There is no per-widget version.

Published version prefixes on the CDN are immutable — re-publishing the same version is refused. See ship/publish-versions-and-rollback.md.

Not supported yet. Pre-release suffixes (1.0.0-rc.1) pass every validator, but each immutability detector in the fleet requires a bare X.Y.Z path segment. A pre-release publish silently loses direct content-addressed asset URLs, the life-of-instance build-manifest cache and the slug-keyed SSR bundle cache, falling back to short-TTL proxied serving everywhere. Ship plain X.Y.Z versions.

runtime

// packages/create-hr-plugin/template/manifest.json — the build adds `widgetCore`
{
  "runtime": { "react": "^19.0.0" }
}

After a build:

// /Users/.../hr-plugins/pdp-suite/manifest.json (real, published 1.3.3)
{
  "runtime": { "react": "^19.0.0", "widgetCore": "0.12.0" }
}

runtime.react is declarative metadata. Nothing in the renderer, the dashboard, the asset proxy or central reads its value, and no checkpoint requires it to be present — the build’s stamp pass creates the runtime object for you if it is missing. It documents intent for a reviewer; it does not gate anything. (The old guide claimed “the renderer rejects plugins whose runtime.react doesn’t match”. There is no such code.)

What actually controls which React you run against is the exact pin set in your package.json, because the platform externalises React and hands you its own copy at runtime. Patch drift trips react-dom’s own Incompatible React versions assertion. The canonical pins live in get-started/01-install-and-versions.md.

runtime.widgetCore is the enforced gate. It records the exact @homerunner-next/widget-core version your build ran with, and it is written for you by the build’s finalize pass — treat it as generated output, not a field you own. Expect manifest.json to come back dirty in git after npm run build; commit it.

The same gate runs on rollback, so you cannot roll back to a version built with a pre-0.10.0 SDK.

shadowDOM

// /Users/.../hr-plugins/pdp-suite/manifest.json
{ "shadowDOM": true }

A root-level flag governing the whole plugin — there is no per-widget override. Omit it (or set true) unless every one of your client bootstraps passes shadowDOM: false to mount().

It buys one thing: Declarative Shadow DOM for your server-rendered markup, which means your widget is styled at parse time with no mount blink. The renderer grants DSD only when both hold:

• manifest.shadowDOM !== false, and
• runtime.widgetCore parses to ≥ 0.10.0.

Nothing validates that the flag agrees with your bootstrap. When they disagree — the manifest says shadow, mount() says none — the server attaches a shadow root that your mount never adopts, and the SSR content is stranded: visible in view-source, invisible on screen. See runtime-and-mount.md for the mount side and recipes/styling-and-theming.md for the styling consequences.

Media references

Four fields point at files under media/. Their value rules are not the same, and the differences are load-bearing.

Exact patterns, from the SDK:

// packages/homerunner-widget-core/src/manifest.ts (isPluginMediaRef, isPluginReadmeRef)
/^media\/[^/\\]+$/            // icon, cover, widgets[].icon — flat, no subdirectory
/^https?:\/\/[^\s]+$/i        // …or an absolute URL, for those three only
/^media\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?\.md$/   // readme — one optional subdir

Violations:

Central re-checks the same shapes at submit and returns 422 INVALID_MANIFEST with its own wording, e.g. Manifest "icon" must be a "media/<file>" path or an absolute http(s) URL (max 2048 characters).

Three consequences worth internalising:

• media/ is authored content. Nothing generates it, and the reviewer only runs your build. A declared icon, screenshot or README that is not committed to your source zip makes the publish fail after you were told the submission looked fine. See packaging-and-publishing.md.
• A media/ reference resolves only after your first publish. It is resolved with new URL(ref, manifest_url), and an unpublished plugin has no manifest_url — so the resolver returns null and the icon falls back to a glyph. An absolute URL renders immediately, including in the review console. If you want your icon visible during first review, use a URL; if you want it version-immutable, use media/.
• Screenshots asymmetry is deliberate. Screenshot files publish under the same immutable version prefix as your bundles, so they may not point off-platform. The plugin page additionally drops any screenshot that is not media/…, and renders none at all before the first publish.

READMEs are rendered through a markdown sanitizer — no raw HTML, no scripts.

Presets

// /Users/.../hr-plugins/pdp-suite/manifest.json (root level, beside "widgets")
"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"]
    }
  }
]

presets?: Array<{ name: string; layout: string; slots: Record<string, string[]> }> — a root field, suite shape only (widget-core 0.11.0+). Presets on a v1 manifest are neither validated nor used, because a preset must reference a declared layout widget and only suite roots declare widgets.

Referential integrity is checked at publish, in both the browser audit and central:

A plugin: reference is never accepted as a slot child — name your own widget by its bare slug, and a system widget by its bare keyword.

Not supported yet. Preset slot keys are never checked against the layout’s declared slot names. A typo ("sidebar" vs "side-bar") passes every validator and creates a binding the layout never renders. Copy the slot names from your own slots[] and diff them by eye.

What one click on a preset actually creates — which children are created versus reused, the naming, the rollback on failure — is in layouts.md and recipes/composing-a-page.md.

Suite roots and v1 roots are not mixable

Mutual exclusivity is convention, not enforcement. If a manifest carries both widgets[] and the v1 root fields, resolution takes the multi branch, silently ignores root widgetType / ssr / assets / configSchema, and the bare plugin:{id} keyword stops resolving — every existing v1 placement breaks. Conversely, a widget slug resolved against a v1 manifest returns null.

Both failures are fail-closed: the widget is removed from the page and the renderer records the reason keyword does not resolve against the plugin manifest. The resolution table and the failure node it produces are in concepts/manifest-shapes.md.

The shape is frozen at first publish. Central refuses a manifest that flips shape with 422 MANIFEST_SHAPE_CHANGED:

This manifest changes the plugin between single-widget and multi-widget shapes. Existing
widget placements and embed URLs would stop resolving — publish the new shape under a new
plugin slug instead.

Note when this fires: submit and review do not check the shape. The gate runs at publish and at rollback only, and the dashboard mirrors it just before the reviewer uploads your built zip with:

This build changes {slug} between single-widget and multi-widget shapes. Existing
placements and embed URLs would stop resolving — publish the new shape under a new plugin
slug.

So a shape flip will pass your upload and pass review, and die at publish. The only remedy is a new plugin slug. If you might ever ship a second widget, start as a suite — a suite of one is legal.

How the manifest reaches the renderer

1. At publish, central stores your root manifest in manifest_cache and records manifest_url (the CDN URL of that exact manifest.json) and current_version.
2. The renderer asks central for a feed’s widgets. For every widget row whose keyword starts with plugin:, the join attaches two fields:

// what the renderer receives per widget row (suite keyword form)
{
  "id": "…",
  "keyword": "plugin:pdp-suite:stay-hero",
  "plugin_manifest": { /* your ROOT manifest.json, verbatim */ },
  "plugin_manifest_url": "https://plugins.homerunner.io/prod/pdp-suite/1.3.3/manifest.json"
}

The v1 keyword form is plugin:{id} with no widget segment.

3. The renderer parses the keyword, resolves it against plugin_manifest, and reads the resolved widget’s ssr.url and assets.*.

Four properties of that pipeline you should design around:

• Only the ROOT manifest is cached and shipped. A suite root deliberately carries no configSchema/uiSchema — those live in per-widget sub-manifests fetched on demand by the dashboard alone. Keep the root small; it rides along with every render.
• The manifest attached is the kill-switch-filtered one. Suspended plugins get no manifest at all, and widget summaries switched off platform-wide or on that feed are stripped before the renderer ever sees them. See ship/install-and-kill-switches.md.
• Path-only asset values resolve against plugin_manifest_url, preserving subpaths. dist/stay-hero/stay-hero.iife.js against https://…/prod/pdp-suite/1.3.3/manifest.json becomes https://…/prod/pdp-suite/1.3.3/dist/stay-hero/stay-hero.iife.js. Ship path-only values; absolute URLs bypass the whole mechanism and are a legacy shape.
• The hashed build manifest is preferred over the proxy. For a pipeline-published plugin the renderer reads your dist/manifest.json and emits the content-addressed file directly, so a cached page always loads the exact bundle its HTML was rendered with. The version-less /p/{slug}/{file} proxy is the fallback. Both are documented in assets-and-urls.md.

Full example — a real suite root

// /Users/.../hr-plugins/pdp-suite/manifest.json (published v1.3.3), widgets[] trimmed
{
  "id": "pdp-suite",                       // the slug; permanent, globally unique
  "version": "1.3.3",                      // MAJOR.MINOR.PATCH, strictly increasing
  "name": "PDP Suite",
  "description": "A remix of the platform's property-details layout…",
  "readme": "media/README.md",             // one nesting level allowed; <= 64 KB
  "author": { "name": "HomeRunner QA", "url": "https://homerunner.io" },
  "license": "MIT",
  "tags": ["pdp", "layout", "property"],   // first 12 shown
  "runtime": {
    "react": "^19.0.0",                    // metadata only — nothing reads it
    "widgetCore": "0.12.0"                 // STAMPED BY THE BUILD. Never hand-write.
  },
  "shadowDOM": true,                       // whole-plugin; must match every mount() call

  "widgets": [                             // presence => suite shape. Max 24.
    { "slug": "pdp-frame",  "name": "PDP Frame",  "category": "layout", "…": "…" },
    { "slug": "stay-hero",  "name": "Stay Hero",  "…": "…" },
    { "slug": "stay-facts", "name": "Stay Facts", "ssr": false, "…": "…" },
    { "slug": "booking-cta","name": "Booking CTA","ssr": false, "…": "…" }
  ],

  // Absolute URLs: these render in the marketplace and the review console BEFORE the
  // first publish. `media/…` values would resolve to null until manifest_url exists.
  "icon":  "https://picsum.photos/seed/pdp-suite-icon/256/256",
  "cover": "https://picsum.photos/seed/pdp-suite-cover/1200/400",

  "presets": [                             // max 8; slot children are own slugs or
    {                                      // bare system keywords, never plugin: refs
      "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"]
      }
    }
  ]
}

Every field inside widgets[] is specified in widget-summary.md.

Full example — a v1 root

// packages/create-hr-plugin/template/manifest.json (placeholders substituted)
{
  "id": "my-widget",
  "version": "1.0.0",
  "name": "My Widget",
  "description": "A HomeRunner widget plugin",
  "author": { "name": "Plugin Author" },
  "widgetType": "my-widget",               // required; its VALUE is never read
  "ssr":    { "url": "dist/my-widget-ssr.umd.js" },
  "assets": {
    "js":  "dist/my-widget.iife.js",
    "css": "dist/my-widget.css"            // optional
  },
  "runtime": { "react": "^19.0.0" }        // build adds "widgetCore"
  // build also injects "configSchema" and "uiSchema" here
}

See also

• Manifest: widget summary — every widgets[] field.
• Layout widgets — category, slots, prefill, pages, presets at creation time.
• Config schema and UI schema — what goes in configSchema.
• Keywords, assets and URLs — how assets.* values become URLs.
• Packaging and publishing rules — what must be in each zip.
• Limits and error index — every number, every message.

Manifest: widget summary

A widget summary is one object in the root manifest’s widgets[] array. It is the entire per-widget contract the platform stores: the slug that forms the keyword, the bundle paths, whether the widget server-renders, where its config schema lives, and how the dashboard presents it. Central caches the ROOT manifest and ships it with every render — your summary is the only per-widget record the renderer ever sees.

Shape: Suite only. widgets[] exists in the multi-widget (suite) manifest shape and nowhere else. In the single-widget (v1) shape the same information lives on root fields; see The two manifest shapes for the discriminator and Manifest: root fields for the root table. Requires @homerunner-next/widget-core 0.11.0+ (see Install and versions).

A summary’s keyword is plugin:{pluginSlug}:{widgetSlug}. Slugs only need to be unique inside your plugin. Keyword grammar and asset URL resolution live in Keywords, assets and URLs.

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

Field index

Error strings are quoted verbatim from the dashboard’s submission audit (src/lib/plugin-zip.ts); {slug} is your widget slug and widgets[N] the array index.

Maximum 24 widgets per plugin: manifest declares {n} widgets — the limit is 24 per plugin. (publish ERROR). Every hard number in the book is collected in Limits and error index.

Confined relative paths

assets.js, assets.css, relative assets.fonts entries, ssr.url and manifest must all be confined relative paths — paths that cannot escape the published version prefix {env}/{slug}/{version}/.

// src/lib/plugin-zip.ts — isConfinedRelativePath (the submission audit's rule)
function isConfinedRelativePath(value: unknown): value is string {
  if (typeof value !== "string" || value === "") return false;
  if (value.startsWith("/") || /^[a-z]+:/i.test(value)) return false;
  // WHATWG URL parsing treats "\\" as "/" for http(s) — a backslash segment
  // would otherwise slip past the "/"-only traversal check.
  if (value.includes("\\")) return false;
  return !value.split("/").some((segment) => segment === "..");
}

Four rejections, in order: an absolute path (/dist/hero.js), any scheme: prefix (https://cdn.example/hero.js, file:hero.js), any backslash, and any .. segment. An absolute http(s) URL is therefore not a legal value for these fields — only assets.fonts, icon and cover accept absolute URLs. Central applies the identical rule server-side.

Field notes

slug

The slug is a serving contract: it forms the keyword customers store on their widget rows, the dist/{slug}/ directory the build emits, and the /p/{plugin}/{slug}/{slug}.iife.js proxy path. dist, widgets and media are reserved because they are the published directory names under the version prefix.

When a summary’s slug fails the regex the audit stops checking that entry and moves to the next one — fix the slug first, then re-run to see the rest of that widget’s errors.

hr-widget-build enforces the same three rules before it runs a single Vite pass, so you hit them at build time, not at submission; the build’s own strings are in Build a suite.

name and description

name is required and non-empty at publish. Everything downstream still defends against an absent value: resolvePluginWidget falls back to the slug, and the picker falls back to the plugin name.

description is validated by nothing. When you omit it the widget picker substitutes the literal string Third-party plugin, and a layout gets (layout — hosts other widgets in its slots) appended to whatever description it shows.

// src/components/widget/CreateWidgetDialog.tsx — picker entry for a plugin widget
description:
  (entry.description ?? 'Third-party plugin') +
  (entry.category === 'layout' ? ' (layout — hosts other widgets in its slots)' : ''),
icon: entry.category === 'layout' ? Layers : Puzzle,

category

Only the two literals content and layout pass publish. At resolve time the check is one-sided: summary.category === "layout" ? "layout" : "content" — so an absent value, and any value that somehow reached the runtime without passing publish, is treated as content.

Choosing layout changes almost everything about how the widget renders and adds a mandatory slots field to your zod config. Read Layout widgets before you set it.

ssr

Three legal states, and the third one is a publish error:

A category: "layout" widget must declare ssr.url. A layout with ssr: false is accepted by the publish audit but fails at render time:

// packages/homerunner-renderer/lib/render-utils.tsx — layout SSR path
plugin layout widgets require an SSR bundle (`ssr: false` is content-only)

See Layout widgets.

For a v1 (single-widget) plugin ssr.url is unconditionally required — a v1 manifest that resolves to ssr: false produces the renderer failure reason no plugin SSR URL in manifest. Only suite summaries may opt out.

What the SSR bundle must export, and the sandbox it runs in, are in Component and SSR module.

assets

assets.js is the only required member. Point each path at the build’s logical filename — dist/{widget}/{widget}.iife.js — not at a content-hashed twin; the platform resolves the hashed file itself from dist/manifest.json. See Keywords, assets and URLs for the derived filenames and the two serving paths.

assets.fonts (widget-core 0.12.0+) is the only supported way to load web fonts, because @font-face declared inside a shadow root is ignored by the browser. Up to 8 stylesheets per widget; the client bundle injects them into document.head and the renderer appends them to the server-rendered page’s stylesheet list. At publish, more than 8 or a malformed entry is an ERROR; at resolve time the platform silently filters invalid entries and truncates to 8 (silent runtime truncation), so a manifest that reached the fleet another way degrades rather than breaking.

Not validated before upload. The dashboard’s browser audit checks assets.fonts only inside widgets[]. A v1 root-level assets.fonts is honoured by the resolver and validated by central on submit, but nothing checks it in your browser first.

The publish audit also emits size warnings (never blocking) per widget: over 1.5 MB for the client bundle, 512 KB for the stylesheet, and 1 MB for the SSR bundle — the last reading dist/{name} is {n} MB — over the renderer's 1 MB cache threshold (slower cold SSR).

manifest — the sub-manifest path

A suite root manifest carries no schemas. Each widget’s configSchema and uiSchema live in a separate file that the summary points at, conventionally widgets/{slug}.manifest.json:

// widgets/pdp-frame.manifest.json — written by your build:manifest step
{ "slug": "pdp-frame", "configSchema": { /* … */ }, "uiSchema": { /* … */ } }

Only the dashboard ever fetches this file, and only when it needs to draw a config form. The renderer never reads it. Consequences you should design around:

• Referenced but absent from the built zip → publish ERROR (see the table above).
• Present but with no configSchema → publish warning: widgets/{slug}.manifest.json has no configSchema — widget "{slug}"'s dashboard form will be empty.
• Omit the manifest field entirely and the widget is legal, installable and renderable — the customer just gets a schemaless config panel. That is a supported (if unhelpful) state, not an error.

Generate this file; never hand-write it. The generator, the round-trip rules and the publish warnings about extending widgetSchema are in Config schema and UI schema.

icon and readme

Both are marketplace surface, both (widget-core 0.12.0+), and their path rules differ:

media/ is authored content that nothing generates. It must be committed and present in your SOURCE zip, because the reviewer only runs your build — a declared icon missing from your source fails the PUBLISH, long after you were told the submission looked fine. See Packaging and publishing rules.

Two traps:

• A media/ reference resolves only after the first publish. It is resolved against the plugin’s published manifest_url; an unpublished submission has none, so media/ icons render as a fallback glyph in the review console while absolute-URL icons render immediately.
• Filename charset. The publishable surface allows only [A-Za-z0-9._-] per path segment. media/my icon.svg passes the icon-shape check but is dropped from the upload with the warning "media/my icon.svg" won't be published — file names may only use letters, digits, ".", "_" and "-". and then fails with Declared widget "{slug}" icon media/my icon.svg is missing from the zip.

When no per-widget icon resolves, the surface falls back to the plugin’s root icon, and then to a glyph — Layers for a layout, Puzzle for content.

expectedHeight

An anti-CLS hint in CSS pixels, 0 <= n <= 10000. It must be a JSON number — "140" as a string fails the browser audit even though central’s numeric check would accept it. It is used in exactly two places:

1. CSR-only widgets on server-rendered pages. The renderer emits data-hr-min-height="{n}" on the empty host div, and only when n > 0. A widget with ssr.url never gets the attribute from the renderer — its server markup is the reservation.
2. The embed snippet. The dashboard’s Embed Code dialog bakes the same value into the copied HTML for any plugin widget, SSR or not, and it takes precedence over the platform’s own keyword-based hint.

<!-- src/app/(protected)/feeds/[id]/widgets/[widgetId]/[widgetName]/playground/EmbedCodeDialog.tsx -->
<div data-hr-widget-container>
  <div id="{widgetId}" data-hr-widget="plugin:pdp-suite:stay-facts" data-hr-min-height="140"></div>
</div>

Set it on every ssr: false widget. Omitting it on a CSR-only widget means the page reserves nothing and shifts when your bundle paints. What consumes the attribute is described in Runtime, mount and the DOM contract.

mediaSafeAuto

Strict true only — the resolver reads summary.mediaSafeAuto === true, so "true", 1 and any other truthy value mean false. Declaring it opts the widget into parse-time auto colour-scheme resolution: on a Declarative-Shadow-DOM-capable request the renderer stamps data-hr-scheme="auto" on your host, so dark mode resolves at first paint with no JavaScript.

The stamp is applied only when all three hold: the widget’s resolved colorScheme is auto, the request emitted DSD, and this flag is true.

This is a promise about your CSS, and nothing validates it. The stamp assumes your stylesheet dual-emits every dark rule under both standard prefixes. Declaring it without the dual emission paints a dark host with light chrome. The exact selectors, and the two footguns in writing them, are in Styling and theming.

externalFetch

A list of hosts your SSR bundle is allowed to fetch from. The resolver keeps only the string entries and hands the list to the SSR bundle loader; the sandbox then permits HomeRunner’s public API plus these hosts and blocks everything else.

Nothing validates this field at publish — neither the browser audit nor central. A typo is not an error you will see at submission; it is a blocked fetch at render time. Host-vs-host:port matching, the redirect cap, the private-address denylist and the exact block messages are in Component and SSR module.

Client-side fetches are unaffected: externalFetch constrains the server sandbox only.

slots, accepts, pages

Layout-only fields. Declaring either slots or pages on a widget whose category is not layout is a publish ERROR with the strings in the field index. Everything about their meaning — slot-name rules, accepts filtering, prefill, page assignment, the mandatory slots field in your zod config — belongs to Layout widgets.

deprecated and replacedBy

deprecated: true is a soft retirement, and it is how you remove a widget from a suite. It:

• removes the widget from the dashboard’s widget picker for every feed,
• disables Create widget for it on the plugin page and shows a deprecated badge,
• leaves every existing placement rendering exactly as before, and
• is diffed at review, so the reviewer sees deprecated / un-deprecated on the summary.

Deleting a slug instead breaks every customer widget that stores that keyword. Prefer deprecated. This is not the same as a kill switch, which stops the assets serving — see Install, customers and kill switches.

Not supported yet. replacedBy is declared in the SDK type and read by nothing. Setting it is harmless and invisible — see Known gaps.

What the platform fills in for you

Every consumer normalizes a summary through one function before using it. These defaults apply at runtime whatever the manifest says:

// packages/homerunner-widget-core/src/manifest.ts — resolvePluginWidget, suite branch
const summary = manifest.widgets.find((w) => w.slug === widgetSlug);
if (!summary || !summary.assets?.js) return null;
return {
  pluginSlug: manifest.id,
  widgetSlug,
  name: summary.name ?? widgetSlug,
  category: summary.category === "layout" ? "layout" : "content",
  ssr: summary.ssr === false ? false : summary.ssr?.url ? { url: summary.ssr.url } : false,
  // …
  mediaSafeAuto: summary.mediaSafeAuto === true,
  icon: isPluginMediaRef(summary.icon) ? summary.icon : undefined,
  readme: isPluginReadmeRef(summary.readme) ? summary.readme : undefined,
};

Resolution fails closed. A null result — unknown slug, missing assets.js, or a keyword whose shape disagrees with the manifest’s — makes the renderer emit a hidden failure breadcrumb with the reason keyword does not resolve against the plugin manifest instead of rendering anything. The shape-mismatch table is in The two manifest shapes.

Where each rule is checked

Your summary passes three gates at three different moments. Knowing which is which saves a review cycle.

Two consequences worth internalising:

• widgets[].icon and widgets[].readme shapes are checked by central but not by the browser audit. A malformed per-widget media ref sails through the local audit and comes back as 422 INVALID_MANIFEST with, e.g., Manifest widget "{slug}" has an invalid "icon" (a "media/<file>" path or an absolute http(s) URL, max 2048 characters).
• File presence is only checked at publish. Everything in the field index that says “must ship in the built zip” is invisible until an admin builds your source. Commit media/ and widgets/*.manifest.json. See Preflight and submit.

Central also applies its own root-level caps that the browser audit does not: name and id ≤ 255 chars, version ≤ 64, description ≤ 4000, author.name / author.url ≤ 255. Those are root fields — see Manifest: root fields.

A complete summary, both kinds

// hr-plugins/pdp-suite/manifest.json — the shipped v1.3.3 manifest, widgets[] excerpt
"widgets": [
  {
    "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"
  },
  {
    "slug": "stay-facts",
    "name": "Stay Facts",
    "ssr": false,
    "assets": {
      "js": "dist/stay-facts/stay-facts.iife.js",
      "css": "dist/stay-facts/stay-facts.css"
    },
    "expectedHeight": 140,
    "manifest": "widgets/stay-facts.manifest.json"
  }
]

Read the two entries against the rules: the layout declares ssr.url because it must, pages because it wants to be assignable, and no expectedHeight because it server-renders. The CSR-only widget declares ssr: false explicitly, ships no ssr-entry.ts, and reserves 140 px.

Known gaps

One field of a summary does nothing at all:

Not supported yet. replacedBy is stored in the manifest, accepted by every validator and read by no runtime, UI or review code — not the renderer, not the dashboard, not the review diff. It surfaces nowhere. Name the successor in the widget’s readme instead.

Three more are honoured at runtime but never checked before you ship, so a mistake in them costs you a released version rather than a failed upload:

Not validated. externalFetch is checked by neither audit nor by central. A host you typo’d is not an error at submission; it is a blocked fetch at render time.

Not validated. mediaSafeAuto is a promise about your CSS that nothing can verify. Nothing inspects your stylesheet for the dual-emitted dark rules the flag requires, so a wrong declaration ships silently and paints a dark host with light chrome.

Not validated before publish. widgets[].icon and widgets[].readme shapes are checked by central on submit but not by the browser audit, and whether the declared media/ file actually exists is checked only by the built-zip audit at publish. A submission can be accepted and then fail to publish on media alone.

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.

Config schema and UI schema

Two JSON artifacts drive the settings form a customer sees in the dashboard:

• configSchema — a JSON Schema object describing every setting your widget accepts.
• uiSchema — an optional symbolic map naming which form control renders each field.

You never hand-write either. You write one zod schema that extends the shared base widgetSchema, and export zodToManifestSchema(configZod). Everything on this page is a consequence of that round-trip.

Enforcement levels used below (publish ERROR, publish warning, silent runtime truncation, advisory (unvalidated)) are defined once in limits-and-errors.md. Every rule on this page applies to both manifest shapes unless a row or heading says Single-widget or Suite.

Where the two artifacts live

In a suite, every widget owns its own src/widgets/{slug}/config.ts. See manifest-shapes.md for how the platform tells the shapes apart.

The pipeline

# traced through packages/homerunner-widget-core/src/plugin-schema.ts,
# packages/create-hr-plugin/template/scripts/inject-schema.mjs,
# src/lib/homerunner/plugin-widgets.ts and src/lib/plugin-ui-adapter.tsx

src/config.ts
  widgetSchema.extend({ ...your fields })            zod, in your project
        │
        ├─ zodToManifestSchema(configZod)            widget-core /plugin-schema
        │      → JSON Schema (refs inlined)
        │
        └─ uiSchema: PluginUiSchema                  string component names
        │
  scripts/inject-schema.mjs (yours, not the SDK's)
        → manifest.configSchema / manifest.uiSchema  (single-widget)
        → widgets/{slug}.manifest.json               (suite)
        │
  dashboard: @n8n/json-schema-to-zod                 JSON Schema → zod, in the browser
        + resolvePluginUiSchema()                    names → React components
        → the same <Form> system widgets use
        │
  autosaved to central as opaque JSON
        │
  props.options at runtime — RAW, unparsed, on BOTH server and client
        → parseWidgetConfig(configZod, props.options)

The round trip through JSON Schema is lossy. zodToManifestSchema runs zodToJsonSchema(schema, { $refStrategy: "none" }) and then strips $schema, $defs, definitions, $ref and the boolean additionalProperties: false marker, while preserving schema-valued additionalProperties so z.record(...) survives the trip back to zod. It recurses only into properties, items and additionalProperties — anyOf / allOf / oneOf subtrees pass through untouched. What survives is tabulated below.

The base schema: widgetSchema

Every widget, first-party or plugin, extends the same base. It has exactly nine top-level fields, in this order. All are defaulted, so the emitted JSON Schema carries no root required array.

There is no width field. spacing replaced the old width: {maxWidth, unit} pair (widget-core 0.9.0+ — see ../get-started/01-install-and-versions.md for which versions you can actually install). Old saved values are lifted onto spacing automatically by parseWidgetConfig. A plugin whose own schema still declares width keeps a compatibility Width Settings panel; a plugin that does not declare width never renders that entry.

Not supported yet. The platform applies none of customCss, font.size, font.family or the accent colours for you — not on the server and not in mount(). They arrive in options and your component must render them. See ../recipes/styling-and-theming.md.

Skipping the base is a publish warning, checked on the built zip:

# src/lib/plugin-zip.ts — warnIfSchemaSkipsBase()
{label}'s configSchema doesn't extend the base widgetSchema (no colorScheme/spacing) —
standard theme + spacing controls won't appear. Build config.ts as widgetSchema.extend({...})
and export zodToManifestSchema(configSchema).

{label} is the plugin for a single-widget manifest and widget "{slug}" for each suite widget. The check is literally “does properties contain both colorScheme and spacing”.

Writing config.ts

// packages/create-hr-plugin/template/src/config.ts — the scaffold, verbatim
import { z } from "zod";
import { widgetSchema } from "@homerunner-next/widget-core/schema";
import {
  zodToManifestSchema,
  type PluginUiSchema,
} from "@homerunner-next/widget-core/plugin-schema";

export const configZod = widgetSchema.extend({
  title: z.string().default("My Widget").describe("Widget title"),
});

/** Symbolic UI for plugin-specific fields only. */
export const uiSchema: PluginUiSchema = {
  title: { component: "TextInput" },
};

/** JSON Schema shipped in `manifest.configSchema`. */
export const configSchema = zodToManifestSchema(configZod);

export type PluginConfig = z.infer<typeof configZod>;

Rules that are not enforced anywhere but that you will regret ignoring — all advisory (unvalidated):

• .default(...) every field. A field with no default has no seed value, and the form live-validates on mount, so the customer opens the panel to a red error they did not cause.
• .describe(...) every field. The string becomes JSON Schema description and renders as the field’s help text. On an object it also becomes the auto-generated panel’s description.
• Use the narrowest zod type. z.number().int().min(1).max(20) emits {"type":"integer","minimum":1,"maximum":20}, which the number input honours.
• Group with z.object({...}).default({...}). Object fields become panels automatically.

Reading options back: parseWidgetConfig

props.options is the raw merged settings blob on both the server and the client. Nothing schema-parses it for you — plugins are handed the unparsed object in the component, in getInitialData, in dehydrateState and in getStaticAssets. Parsing is your job, in every one of those places:

// packages/create-hr-plugin/template/src/widget.tsx — the scaffold, verbatim
const options = React.useMemo(
  () => parseWidgetConfig(configZod, props.options) as PluginConfig,
  [props.options],
);

parseWidgetConfig(schema, options, pre = liftLegacySpacing) does four things in order:

1. stripNullSettingLeaves — drops a null or "" leaf only when that leaf’s own schema rejects it. Central runs Laravel’s ConvertEmptyStringsToNull, so any untouched optional field can come back null; older blobs carry "" on enum and number fields. A leaf that legitimately accepts null (.nullable() / .nullish()) keeps it, and "" stays on a plain z.string(). An empty array on a record- or object-typed field reads as {} (PHP serialises a cleared map as []). Anything else invalid — "abc" on a number — is left in place to fail loudly.
2. coerceScalarSettingLeaves — a string leaf whose schema is z.number() or z.boolean() is coerced when it parses unambiguously (font.size: "16" → 16).
3. pre — by default liftLegacySpacing, which folds a legacy width: {maxWidth, unit} (and top-level margin / padding) onto spacing without overwriting an existing value.
4. schema.parse(...) — applies your defaults and throws on anything still invalid.

A throw here blanks the widget: on the client it is caught by the render boundary and the host gets data-hr-error="render-failed"; on the server a content widget is dropped from the page while a layout shell takes the whole page down. See component-and-ssr-module.md for the failure semantics and ../concepts/settings-and-options.md for where the raw blob comes from.

Not supported yet. There is no server-side validation of stored settings. The dashboard validates live for display only and autosaves the raw form value on every keystroke, even while invalid; central stores settings as opaque JSON and replaces it wholesale. Your parseWidgetConfig call is the only real gate.

What survives the manifest round-trip

Verified by running zodToManifestSchema → @n8n/json-schema-to-zod (the exact pair the dashboard uses) over each construct. Enforcement for this whole section is advisory (unvalidated) — no audit inspects which zod constructs you used. Everything below fails in the customer’s browser, after publish, or not at all.

Safe

Degrades silently

Nothing warns. The form renders, the customer edits, and the result is wrong.

Breaks the whole panel

These make the dashboard’s default-value walker throw Unsupported schema type: [object Object]. That call is unguarded in three places in the plugin playground’s render, so the entire config page crashes — you do not get a broken field, you get no page.

Not supported yet. There is no guard around the walker and no error message — the panel simply does not render. Never ship any of the six constructs above. Model a variant with a z.enum() discriminator plus flat optional fields and a showIf per group.

The uiSchema

A manifest is JSON, so it cannot carry React components. You name them:

// property-picks/src/config.ts — a published plugin
export const uiSchema: PluginUiSchema = {
  title: { component: "TextInput", label: "Title" },
  limit: { component: "NumberInput" },
  showReviewQuote: { component: "Checkbox" },
  translations: {
    ui: { layout: "panel", label: "Translations" },
    viewDetails: { component: "Translations", label: "View details" },
    perNight: { component: "Translations", label: "/ night" },
  },
};

The types, from @homerunner-next/widget-core/plugin-schema:

// packages/homerunner-widget-core/src/plugin-schema.ts
export type PluginUiField =
  | {
      label?: string;
      description?: string;
      component?: /* one of the twelve tokens below */ string;
      optionLabels?: Record<string, string>;
      showIf?: { field: string; equals: unknown };
    }
  | PluginUiSchema;

export interface PluginUiSchema {
  [key: string]: PluginUiField | PluginUiLayoutSpec | undefined;
  ui?: PluginUiLayoutSpec;
}

export interface PluginUiLayoutSpec {
  layout?: "panel" | "collapsible";
  label?: string;
  description?: string;
  showIf?: { field: string; equals: unknown };
}

(component is a closed union of the twelve string literals in the real declaration; it is widened here only so the comment fits.)

PluginUiLayoutSpec has no fields key. A panel’s children are siblings of its ui key, mirroring the zod object’s shape. (A legacy {layout, label, fields: {...}} node is auto-normalised to the canonical form before the tree walk, so old manifests keep working. Do not write it in new code.)

Field keys the adapter honours

Exactly five. Everything else on a field entry is dropped or turned into an inert nested node.

Not supported yet. order, ui:group, placeholder and every other key are ignored. pdp-suite’s shipped {"ui:group": "Content"} entries are no-ops — they produce an empty nested node and change nothing. Plugins cannot influence field order; see Ordering.

Component tokens

Twelve names resolve. Any other string is ignored.

PlatformSelect, PropertySelect and WidgetSelect fetch the feed’s own data. WidgetSelect takes its feed from the form’s filter.feed_id, which the base filter block supplies and widget creation seeds — if you strip filter out of your schema, the combobox has no feed and stays empty.

Component ↔ zod pairing

The form dispatches on the zod type first and only then substitutes uiSchema.component into that type’s renderer slot. A token therefore receives the props of the branch the zod type routed to, not the props it was designed for.

Nothing validates any of this at publish time — advisory (unvalidated). Open the widget’s config panel in the dashboard before you submit.

The control you get with no uiSchema entry at all

Item-level UI for an array is declared under an element key on the array’s entry — the adapter forwards nested keys verbatim, and the array renderer reads element:

// derived from src/lib/plugin-ui-adapter.tsx + src/components/zod-form/libs/core/form.tsx
facts: { element: { component: "TextInput" } },

That is a structural passthrough rather than a declared feature — treat it as advisory (unvalidated).

Panels

Any object-typed property is wrapped in a nested panel automatically, recursively, whether or not you declare one. A panel renders as a clickable summary row; clicking it slides a stacked detail view in over the config sidebar. It is not an inline bordered fieldset and it is not a collapsible chevron.

• Panel title = your ui.label, else the JSON Schema title, else the raw key. zod never emits title, so an undeclared panel is titled translations, display, slots.
• Panel description = your ui.description, else the object’s .describe() text.
• A field with an explicit component is never auto-wrapped, which is how Translations on a record (also type: "object") keeps its own editor.
• The ui block is only read as a layout spec when it contains the layout key. A ui: { label: "Translations" } with no layout is discarded entirely — you lose the label and any showIf on it. Always write ui: { layout: "panel", label: "..." }.

Not supported yet. layout: "panel" and layout: "collapsible" are interchangeable. The value is only used as a marker that the node is a layout spec; it is never read, and both build the identical slide-in panel.

showIf

showIf: {field, equals} compiles to data => data?.[field] === equals, and that predicate is always invoked with the whole root form value.

// pattern verified against src/lib/plugin-ui-adapter.tsx + resolve-ui-schema-conds.ts
export const uiSchema: PluginUiSchema = {
  variant: { component: "Select", optionLabels: { grid: "Grid view", carousel: "Carousel" } },
  columns: { component: "NumberInput", showIf: { field: "variant", equals: "grid" } },
  advanced: {
    ui: { layout: "panel", label: "Advanced", showIf: { field: "mode", equals: "expert" } },
    retries: { component: "NumberInput", label: "Retries" },
  },
};

Ordering

Field order is the configSchema property order, stable-sorted by a numeric order that only the dashboard’s own base entries carry. widgetSchema.extend({...}) appends, so your fields always land after the base chrome:

# order values from src/app/(protected)/feeds/[id]/widgets/config/common-ui-schema.tsx
Section Header  (-55)
Filter Settings (-30)
spacing, colorScheme, lightModeColors, darkModeColors, font, language   (0, schema order)
…your fields…                                                          (0, schema order)
Custom CSS      (100)

Not supported yet. Plugins cannot reorder anything. PluginUiField has no order key and the adapter drops one if you add it, so uiSchema key order has no effect whatsoever. To move a field, move it in the zod schema.

The default label is the full dotted path

Every leaf renders label = uiSchema.label ?? name, where name is the full dotted form path. A field inside a panel with no label shows translations.viewDetails, not viewDetails. There is no humanisation. Declare label on every field you nest.

Never re-declare a base key

The adapter builds base = { ...commonWidgetUiSchema, width: <legacy panel> } and then, for each top-level key of your uiSchema, does base[key] = convert(value) — a wholesale replacement, not a deep merge. Re-declaring any of these destroys that panel’s layout, its components, its conditions and its order:

spacing · colorScheme · lightModeColors · darkModeColors · font · language · section · customCss · filter · width

Re-declaring filter, for example, loses PlatformSelect, PropertySelect and the hidden feed_id input. Re-declaring spacing loses the compound spacing control. If you genuinely need a custom leaf beside the built-ins, you must re-declare the entire panel and rebuild every entry yourself. A root ui key in a plugin uiSchema is skipped entirely.

Enforcement: advisory (unvalidated) — nothing warns, in the dashboard or at publish.

Layout widgets: the mandatory slots field

A layout widget must declare a slots object in its zod schema, with keys that match the manifest’s declared slot names exactly:

// pdp-suite/src/widgets/pdp-frame/config.ts
export const configZod = widgetSchema.extend({
  stickyRail: z.boolean().default(true).describe("Keep the sidebar rail pinned"),
  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"),
});

Do not write a uiSchema entry for slots. When the resolved widget has category: "layout" and a non-empty manifest slots[], the dashboard discards whatever you declared and injects its own panel — label Slot Configuration, order: -50, one row group per declared slot titled {name} slot and described accepts: {list}, each row a widget combobox filtered by that slot’s accepts. Empty rows are stripped on save.

Without the zod field there is nowhere to store the bindings, so the customer’s slot picks silently vanish. The stored shape is settings.slots: Record<slotName, widgetId[]>. Everything else about slots, accepts, prefill, presets and page assignment lives in layouts.md.

Not supported yet. Plugin layouts do not inherit slotSpacing or gap — those live on a private internal schema. Declare your own if you want per-slot spacing; the builders in sdk-exports.md (marginBoxSchema, paddingBoxSchema, widthSchema, maxWidthSchema, DEFAULT_SLOT_SPACING) let you rebuild the same shape.

Translations

Declare each translatable string as z.record(z.string(), z.string()) — locale code → text — and pair it with component: "Translations".

// property-picks/src/config.ts — a published plugin
translations: z
  .object({
    viewDetails: z
      .record(z.string(), z.string())
      .default({ en_US: "View details", fr_FR: "Voir les détails", es_ES: "Ver detalles" })
      .describe("View-details CTA"),
    perNight: z
      .record(z.string(), z.string())
      .default({ en_US: "/ night", fr_FR: "/ nuit", es_ES: "/ noche" })
      .describe("Price unit"),
  })
  .default({
    viewDetails: { en_US: "View details", fr_FR: "Voir les détails", es_ES: "Ver detalles" },
    perNight: { en_US: "/ night", fr_FR: "/ nuit", es_ES: "/ noche" },
  })
  .describe("Translations"),

Editor behaviour the customer sees, and you must design around:

• Edits are held in local state and only reach the form when the customer presses the editor’s own Save button. A customer who edits and navigates away loses the edit.
• Removing a locale row raises a browser confirm() dialog.
• The editor derives its i18n key from the last segment of the field path, so translations.viewDetails keys on viewDetails.

At runtime:

// property-picks/src/widget.tsx — a published plugin
const { detectedLocale } = useLocaleDetection(
  options.language.useAutoDetectedLocale,
  options.language.locale,
);
const { _t } = useTranslation(options.translations ?? {}, detectedLocale);
// …
_t("viewDetails", "View details")

_t(key, defaultValue = key) resolves store[key][currentLocale] || store[key]["en_US"] || defaultValue — an empty string falls through, so a blank row is treated as missing. useLocaleDetection seeds state with the configured locale so the server and the client’s first render agree, then switches to the browser locale one tick after mount when auto-detect is on. Both come from @homerunner-next/widget-core/utils.

Not supported yet. The plugin save path runs only the empty-slot stripper, not the blank-row strippers system widgets get — so a locale row the customer blanks is persisted forever as "". It is harmless as long as you always pass a defaultValue to _t and always keep a non-empty en_US entry in your schema default. Never rely on _t(key) alone.

Per-widget sub-manifests

(widget-core 0.11.0+, suites only.) Your project’s scripts/inject-schema.mjs writes one JSON file per widget and stamps the reference back onto the summary:

// packages/create-hr-plugin/template/scripts/inject-schema.mjs — the multi-widget branch
const { configSchema, uiSchema } = await import(pathToFileURL(configPath).href);
const sub = { slug, configSchema };
if (uiSchema) sub.uiSchema = uiSchema;
fs.writeFileSync(subPath, JSON.stringify(sub, null, 2) + "\n");
widget.manifest = `widgets/${slug}.manifest.json`;

That script lives in your project, not in the SDK. Only configSchema and uiSchema are ever read; slug is decorative (pdp-suite’s own copy omits it).

Operator-visible strings, so you can recognise a screenshot:

# src/app/(protected)/feeds/[id]/widgets/[widgetId]/[widgetName]/playground/PlayGround.tsx
Plugin "{slug}" not enabled for this feed.
Widget "{keyword}" is not declared by plugin "{slug}".
Loading plugin manifest...
No configSchema for this widget. Ask the plugin developer to ship one via
zodToManifestSchema(widgetSchema.extend({...})) in the widget's config.ts.

If your JSON Schema is present but the browser cannot rebuild a z.ZodObject from it, the failure is caught, logged as [plugin-playground] jsonSchemaToZod failed: and the same amber “No configSchema” banner appears.

Publish-time schema checks

All four run against the built zip, at publish, and are quoted verbatim above:

The audit also records each widget’s configSchema property keys so the reviewer can diff them against your previous version.

Not supported yet. The built-zip audit runs at publish, on the reviewer’s side. Its warnings are shown to the reviewer, never to you — you can be told your submission is fine and only learn about a schema warning if the reviewer relays it. Nothing in the source-zip audit you run in your browser looks at configSchema at all. See packaging-and-publishing.md and ../ship/preflight-and-submit.md.

Defaults at widget creation

When a customer creates a widget from your plugin, the seed settings are:

1. Every top-level default in your configSchema, recursing into object-typed properties that have no default of their own.
2. The feed’s branding, minus colorScheme — so the widget stays on the global inherit placeholder and follows the feed live.
3. filter.feed_id = <feed id>, always, merged over whatever your schema’s filter default held.

A sub-manifest fetch failure at this point degrades step 1 to {} — the widget is created carrying only the branding and filter.feed_id, and your schema’s own defaults are what parseWidgetConfig supplies at render time.

In the editor the form is seeded with your defaults merged under the stored settings. Because the whole seeded object is autosaved on the first edit, your defaults become explicitly stored values the moment a customer touches anything — a later change to a schema default will not reach widgets that already exist.

See also

• ../concepts/settings-and-options.md — where the raw options blob comes from and how it is merged.
• layouts.md — slots, accepts, prefill, presets, page assignment.
• widget-summary.md — the manifest field that points at a sub-manifest.
• sdk-exports.md — parseWidgetConfig, zodToManifestSchema, /spacing.
• limits-and-errors.md — every hard number and the full error index.
• ../troubleshooting.md — “my config panel is empty / blank”.

Component and SSR module

Everything your widget module exports, and everything it receives — on the renderer’s server sandbox and in the browser.

Two files carry the contract:

ssr-entry.ts exists if and only if the widget’s summary declares ssr.url. A widget declaring "ssr": false is CSR-only and has no SSR entry file at all — hr-widget-build skips its SSR pass entirely, so the file would never be compiled. See Manifest: widget summary for the ssr field.

How rules on this page are enforced. Almost all of them are enforced at runtime by the renderer, not at publish. The dashboard’s built-zip audit checks that your SSR file exists and has a hashed twin; it never opens the bundle or inspects its exports. Where a publish gate does exist it is named with the standard tags defined in Limits and error index. Runtime outcomes use these terms:

Props

Import the prop types; do not hand-write them. The scaffold’s inline WidgetProps interface is a simplification and omits fields.

// @homerunner-next/widget-core/src/contracts.ts — import from
// "@homerunner-next/widget-core/contracts"
export interface WidgetProps<
  T extends WidgetSchemaType = WidgetSchemaType,
  D extends Record<string, any> | undefined = undefined,
> {
  options: T;
  target?: HTMLElement;
  widgetId: string;
  feedId: number;
  widgetType: string;
  resolvedTheme?: "light" | "dark";
  data: D;
}

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>;
}

Type your component WidgetProps<PluginConfig> (or WidgetProps<PluginConfig, GetAwaitedFuncReturnType<typeof getInitialData>> when you export one) and a layout LayoutWidgetProps<PluginConfig>. Both types are exported from /contracts; WidgetSchemaType comes from /schema. See SDK reference.

Not supported yet. target is part of the exported WidgetProps type but no render path in the platform passes it — not the renderer, not mount()’s hydrate path, not its CSR path. Use useShadowHost() from @homerunner-next/widget-core/runtime if you need the host element. See SDK reference.

What each path actually passes

Three consequences worth internalising:

1. widgetType is a hydration trap. The server props object is {resolvedTheme, options, feedId, widgetId, data} — it has no widgetType key. The browser replays that same object verbatim when hydrating. Only the pure-CSR path adds widgetType. If your render output depends on it, the SSR HTML and the hydrated tree disagree and React discards the server DOM.
2. resolvedTheme is effectively always "light" in production. It derives from an hr:widget:system_theme cookie, and the Cloudflare worker in front of the renderer never forwards cookies. Dark-at-first-paint must come from CSS keyed off host attributes — see Styling and theming.
3. The hydrate path replays the server’s data. It travels as JSON in a page-level inline script. Non-JSON values do not survive.

Options arrive RAW

Plugin widgets deliberately receive unparsed merged settings on both the server and the client. The renderer parses settings only for first-party widgets:

// Platform source: homerunner-renderer/lib/render-utils.tsx
const parsedSettings = widgetConfig.type.startsWith('plugin:')
    ? finalSettings                                   // plugins: RAW
    : await parseSettingsForSsr(widgetConfig.type, finalSettings);

Raw settings contain artifacts your schema rejects: a cleared dashboard field arrives as null, an emptied map as [], numbers may arrive stringified, and pre-0.9.0 saves carry a legacy width object instead of spacing. Calling .parse() on that throws.

The rule (Both): call parseWidgetConfig(configZod, props.options ?? {}) in your component and in every SSR export before reading a single field. Enforcement: runtime — throws into your code, which then becomes widget removed on the server or data-hr-error="render-failed" in the browser.

// pdp-suite/src/widgets/stay-hero/widget.tsx (real, published)
import React from "react";
import { parseWidgetConfig } from "@homerunner-next/widget-core/schema";
import { configZod } from "./config";
import heroBg from "./hero-bg.png";
import "./stay-hero.css";

/** The property slug the platform injects when a parent layout resolves one. */
function injectedProperty(options?: Record<string, unknown>): string | null {
  const filter = (options as { filter?: { property?: unknown } } | undefined)?.filter;
  return typeof filter?.property === "string" && filter.property ? filter.property : null;
}

export default function StayHero(props: { options?: Record<string, unknown> }) {
  const cfg = parseWidgetConfig(configZod, props.options ?? {});
  const property = injectedProperty(props.options);
  // …
}

parseWidgetConfig(schema, options, pre?) strips null/'' leaves the schema rejects, coerces stringified scalars, lifts legacy width onto spacing, then parses. The full merge chain that produces those raw settings is described in Settings and options; the base schema fields are in Config schema and UI schema.

Memoise it in a component that re-renders (useMemo on props.options) — it is a full zod parse, not a cheap read.

The SSR module

The renderer fetches your built SSR bundle, evaluates it in a node:vm context, and reads exactly four exports off the resulting module:

// Platform source: homerunner-renderer/lib/plugin-federation.ts:317-322
interface PluginSSRModule {
  default: React.ComponentType<any>;
  getInitialData?: (ctx: any) => Promise<any>;
  dehydrateState?: (qc: any, ctx: any) => Promise<void>;
  getStaticAssets?: (settings: any) => Promise<{ css: string[]; js: string[] }>;
}

Nothing about these exports is checked before publish — see Packaging and publishing rules for what the audit does check. A bundle with no default export publishes cleanly and fails on the first customer page render.

The entry file

ssr-entry.ts is a re-export barrel. The build compiles exactly this path — nothing else — into the SSR bundle:

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

// create-hr-plugin template: src/ssr-entry.ts (single-widget shape, content widget)
export { default, getInitialData } from "./widget";
export { dehydrateState, getStaticAssets } from "./ssr";

Suite widgets in practice export only default — pdp-suite’s stay-hero and pdp-frame both do. Add the data hooks only when you need server-side data.

Call order and context

For every server-rendered widget the renderer runs, in this order, inside one try:

# Platform source: homerunner-renderer/lib/render-utils.tsx (getWidgetMarkup)
getInitialData(ctx) → dehydrateState(queryClient, ctx) → getStaticAssets(settings)
  → renderToString(<WidgetHydrationTree><Default {...props} /></WidgetHydrationTree>)

For a layout, all slot children are rendered first (concurrently, each a complete island), and only then does the layout’s own bundle load and run the same four steps. The whole pipeline, end to end, is drawn in How a widget renders; the slot rules are in Layout widgets.

ctx — for getInitialData and dehydrateState — is exactly three keys:

getStaticAssets receives only the settings object as its first positional argument — there is no ctx, no feedId, no widgetId.

Not supported yet. GetInitialDataCtx in @homerunner-next/widget-core/contracts declares widgetType, isSSR, cookies, headers and query in addition to the three keys above, and types options as parsed. For plugins the renderer populates none of the extra fields and never parses options. Type your ctx as the three-key object shown above; reading ctx.cookies or ctx.headers gets you undefined.

The shared query client

dehydrateState receives the page’s QueryClient — one instance shared by every widget on the page, first-party and plugin alike. The dehydrated cache is serialised into the HTML and rehydrated into one shared browser-side client.

• Namespace your query keys. A colliding key silently serves another widget’s data. Prefix with your plugin slug: ["pdp-suite", "stay-hero", feedId, …].
• Two keys are reserved and pre-seeded by the renderer before your hook runs: ["widget", <widgetId>] and ["widget", <feedId>, <widgetId>] (the widget + feed config pair that useFetchWidget reads). Do not write to them.
• Prefetch errors are swallowed by design; see Failure semantics.

Data-fetching patterns, the error taxonomy and retry helpers live in Fetching data; endpoint shapes in Public API.

getStaticAssets — prefer omitting it

When you do not export it, the renderer builds the asset list from your manifest instead: assets.js, assets.css and assets.fonts. That is almost always what you want.

When you do export it, every URL you return is rewritten. The renderer reduces each entry to its dist-relative name (https://cdn.example.com/dist/hero/hero.css → hero/hero.css, anything else → the basename) and re-resolves it against the published version’s build manifest, falling back to the /p/ proxy. Absolute URLs are not passed through.

The full resolution algorithm, the /p/ proxy and font rules belong to Keywords, assets and URLs.

// create-hr-plugin template: src/ssr.ts — corrected for the suite layout.
// A suite emits dist/{widget}/{widget}.css, not dist/{slug}.css.
export async function getStaticAssets(
  _options: Record<string, unknown>,
): Promise<{ css: string[]; js: string[] }> {
  return {
    css: ["dist/stay-hero/stay-hero.css"],
    js: ["dist/stay-hero/stay-hero.iife.js"],
  };
}

The server sandbox

Your SSR bundle is a CommonJS file (formats: ["cjs"], exports: "named", inlineDynamicImports: true) named dist/{widget}/{widget}-ssr.umd.js in a suite or dist/{slug}-ssr.umd.js in the single-widget shape, despite the .umd.js suffix. Every dynamic import() is inlined at build time — there is no module loader in the sandbox at runtime.

The context is a fresh V8 realm. ECMAScript intrinsics (RegExp, Function, Reflect, parseInt, Intl, globalThis, …) exist because the realm creates them. Every Web or Node API must be explicitly seeded, and only the following are.

Shared modules (7)

require() resolves exactly seven specifiers:

// Platform source: homerunner-renderer/lib/plugin-federation.ts:25-38
const SHARED_MODULES: Record<string, unknown> = {
  react: React,
  "react/jsx-runtime": ReactJsxRuntime,
  "react-dom": ReactDOM,
  "react-dom/client": ReactDOMClient,
  "react-dom/server": ReactDOMServer,
  "@tanstack/react-query": ReactQuery,
  // SDK >= 0.10.0 externalizes widget-core's runtime in the SSR umd too.
  "@homerunner-next/widget-core/runtime": WidgetCoreRuntime,
};

Anything else throws, verbatim:

Plugin cannot require "<mod>" (not in shared modules whitelist)

Enforcement: runtime — widget removed (the throw happens during module evaluation, so the bundle never loads).

@homerunner-next/widget-core/runtime is the evergreen entry (widget-core 0.10.0+): the build externalises it, and the renderer supplies its own current copy. Your server renders therefore use the platform’s live runtime helpers, not a copy frozen at your npm install. The other widget-core subpaths — /globals, /schema, /plugin-schema, /utils, /urls, /spacing, /contracts — stay bundled into your SSR file, so they are whatever version you built with.

Everything else you import — React libraries, date utilities, your own code — is bundled. Keep the bundle small: it is fetched, evaluated and cached per renderer instance.

Globals

globalThis does exist and resolves to the sandbox object itself, not the host realm’s global. The build’s bundled-asset banner relies on that (globalThis.__HR_PLUGIN_ASSET_BASE__ is its server-side fallback).

fetch returns a Response created in the host realm. Its methods work; res instanceof Response is a ReferenceError because Response is not bound in the sandbox.

process.env exposes exactly three keys, and nothing else — reading any other name gives undefined:

Browser-global stubs, and the guard that actually works

The seven browser globals are new Proxy(function(){}, {get, set, has, apply, construct}) where get returns another stub. That stub is an object, so it is truthy:

// Platform source: homerunner-renderer/lib/plugin-federation.ts:306-315
function makeBrowserGlobalStub(): unknown {
  const handler: ProxyHandler<object> = {
    get: () => makeBrowserGlobalStub(),   // truthy!
    set: () => true,                      // writes silently dropped
    has: () => false,                     // `"x" in window` is false
    apply: () => makeBrowserGlobalStub(),
    construct: () => ({}),
  };
  return new Proxy(function () {}, handler);
}

Consequences:

The SSR build rewrites typeof on window, document, self, navigator, localStorage and sessionStorage to "undefined". Only that form is tree-shaken; the proxy is a safety net for whatever escapes, not a substitute.

// widget-core README.md — the canonical browser-only side effect
useEffect(() => {
  if (typeof window === "undefined") return;
  import("webfontloader").then(({ load }) => load(opts));
}, [opts]);
// The SSR build rewrites `typeof window` to "undefined", esbuild DCEs everything
// after the unconditional return, and the dependency never lands in the SSR umd.

useEffect never runs on the server anyway, but the import would still be bundled without the guard.

Execution bounds

Give every outbound request in your data hooks an explicit AbortSignal.timeout(…). The sandbox provides AbortController/AbortSignal for exactly this reason, and nothing else will stop a slow upstream from holding the page.

The vm is not a security boundary

The context is seeded with host-realm objects, so a determined bundle can walk back into the renderer’s realm. The real gate is human source review plus an admin-side build — see From your laptop to a customer page. Write as if the sandbox were airtight anyway; a reviewer reads your source.

externalFetch

The sandbox’s fetch is wrapped in an allowlist derived from the widget’s externalFetch manifest field.

The refused-host set is textual (no DNS resolution): localhost, *.localhost, *.local, 0.0.0.0, ::1, 127.*, 10.*, 192.168.*, 172.16–31.*, 169.254.* and metadata.google.internal.

// Platform source: homerunner-renderer/lib/plugin-federation.ts:386-399
const validate = (u: URL): void => {
  const host = u.hostname.toLowerCase();
  const hostPort = u.port ? `${host}:${u.port}` : host;
  const allowed = host === centralHost() || declared.has(host) || declared.has(hostPort);
  if (!allowed) {
    throw new Error(
      `[plugin] fetch to "${host}" blocked — not declared in the widget's externalFetch manifest field.`,
    );
  }
  if (!platformIsLocalRig() && host !== centralHost() && isForbiddenHost(host)) {
    throw new Error(`[plugin] fetch to "${host}" blocked — private/metadata hosts are never allowed.`);
  }
};

The throw surfaces inside your hook, so it is runtime — throws into your code. Let it propagate and the widget is removed; catch it and you can degrade gracefully. Catching is usually right for optional enrichment data, wrong for the widget’s primary content.

Declaration lives on the widget summary in a suite, or at the manifest root in the single-widget shape:

// manifest.json — suite shape, inside widgets[]
{ "slug": "stay-facts", "externalFetch": ["api.weather.example", "cdn.example.com:8443"] }

The root-level form is read by the resolver for single-widget manifests, but it is not declared on the published PluginManifest type and is not covered by any publish validator. Treat it as working but undocumented, and say so in your submission notes so the reviewer knows to look for it.

Two behaviours that surprise people

A 60-second server-side GET cache. Outside development mode, ok GET responses are cached for 60 s across renders (LRU, 50 entries), so dehydrateState may legitimately see data up to a minute stale. The key is the URL plus your request headers, so two calls that differ by a single header never share a response — and a request that carries authorization, proxy-authorization or cookie, uses credentials: "include", sets cache: "no-store"/"reload", sends a body, or is not a GET is never cached at all. Null-body answers (204, 205) are passed straight through and not cached either. This exists because Central’s public API is rate-limited per IP and a purge fan-out multiplies renders. Development renders bypass the cache but stay enforced — you see a block locally, not in review.

The allowlist is frozen into the cached module. The evaluated bundle is cached with its enforced-fetch closure already bound, so the first load’s allowlist is the one that sticks for that module’s lifetime. For pipeline-published plugins this never bites: a new version is a new URL, hence a new module. For a legacy author-hosted plugin, editing externalFetch in a mutable manifest takes up to 5 minutes to apply.

Failure semantics

A removed widget leaves this in the page source, so you can find it with view-source or a curl:

<!-- Emitted by widgetFailureNode — homerunner-renderer/lib/render-utils.tsx:132-145 -->
<div data-hr-widget-error="plugin:pdp-suite:stay-hero" hidden>
  <!-- HR widget failed — type="plugin:pdp-suite:stay-hero" id="42": SSR data prep failed: Cannot read properties of null -->
</div>

Any failure node (or any errored prefetch) marks the whole page degraded, which drops its cache TTL from 24 hours to 60 seconds at every layer. A degraded page is not a broken page — it is a page that will re-render a minute later.

Your console.* calls and the renderer’s own lines go to renderer stdout. The ones worth grepping when an SSR module misbehaves:

# Platform source: homerunner-renderer/lib/plugin-federation.ts + lib/render-utils.tsx
[plugin] Fetching SSR bundle: <url>
[plugin] Failed to load SSR bundle from <url>: <message>
[plugin] SSR bundle has no default export: <url>
[plugin] Loaded "<keyword>" (<id>) via SSR bundle
[plugin] No manifest entry for "<keyword>". Skipping.
[widget] Failed to prepare "<keyword>" (<id>): <message>
[layout] Failed to prepare "<keyword>" (<id>): <message>
[widget] SSR prefetch FAILED — shipping loading markup. key=<queryHash> error=<message> (caught during …)

More diagnosis routes are in Troubleshooting.

The layout asymmetry

A content widget’s server render happens inside getWidgetMarkup’s try. A layout’s component is returned as an un-rendered React element and rendered later, in the page’s single renderToString, which has no try. A layout component that throws during render takes the entire customer page down with a 500.

Layout authors: parse defensively, default every slot, and never index into renderedSlots without a fallback.

// pdp-suite/src/widgets/pdp-frame/widget.tsx (real, published)
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>
);

Prefetch errors only warn

queryClient.prefetchQuery swallows failures by design. The renderer diffs the shared cache’s error set around your dehydrateState and logs:

[widget] SSR prefetch FAILED — shipping loading markup. key=<queryHash> error=<message>

Your widget still renders — with whatever it renders when the query has no data. If that is a spinner, crawlers see a spinner. Prefer returning a real empty state.

In the browser

Every render site in mount() wraps your component in WidgetRenderBoundary, inside the providers. On catch it logs

[hr-widget] "<widgetType>" render failed (widget <id>, feed <id>) — rendering the error state instead of a blank node.

sets data-hr-error="render-failed" on the host element, best-effort stamps a data-hr-theme if nothing else did, and renders the shared neutral error state. A latched failure clears when resetKey changes — which is how a bad live-edit payload in the dashboard preview recovers without a reload. The complete data-hr-error vocabulary is in Runtime, mount and the DOM contract.

The hydration contract

The renderer renders each content widget as an isolated React root:

// Platform source: homerunner-renderer/lib/render-utils.tsx:715, 733-744
const ssrId = `${widgetConfig.id}:${widgetConfig.feed.id}:${widgetConfig.instanceKey ?? '0'}`;

const widgetHtml = renderToString(
  <WidgetHydrationTree queryClient={queryClient}>
    <WidgetComponent {...props} />
  </WidgetHydrationTree>,
  { identifierPrefix: ssrId },
);

mount() hydrates with the identical wrapper shape and the identical identifierPrefix, read back from the host’s data-hr-ssr-id attribute. React derives useId values from a component’s position in the tree plus that prefix, so any drift — an extra provider, a different prefix, a hand-rolled hydrateRoot — makes every useId consumer (Radix Dialog/Popover aria attributes, form ids) mismatch. React’s response is to regenerate the whole tree and silently discard your server DOM.

This is why you must mount through mount() from @homerunner-next/widget-core/runtime and never call hydrateRoot yourself. The wrapper is PortalContainerProvider → ShadowHostProvider → QueryClientProvider; provider values do not affect useId, only the shape does, which is why the server can pass undefined and the client the live shadow elements. See Runtime, mount and the DOM contract.

Two more hydration rules:

• Render deterministically. No Math.random(), no Date.now(), no reading props.widgetType (absent on the server), no reading window. Anything that differs between the two passes costs you the SSR DOM.
• renderToString does not await. A suspended boundary ships its fallback into the HTML. Fetch in getInitialData/dehydrateState, not by suspending during render.

Layout modules

Plugin layout widgets require widget-core 0.11.0+ and the suite manifest shape.

A layout widget’s SSR module follows the same contract with these differences:

Because the shell is light DOM on server-rendered pages, its stylesheet is loaded document-level and applies to the whole customer page. Namespace every class (pdp-suite uses .pdpf-…), never rely on :host, and never paint a background. The same layout in a single-snippet CSR embed does get a shadow root, so the CSS must work both ways.

Not supported yet. A plugin layout on a server-rendered page can never be interactive: the renderer emits no data-hr-ssr-id and no registry entry for the shell, and mount() returns early for it. Its slot children hydrate themselves normally. Put interactivity in a content widget bound into a slot, not in the shell.

Layouts may still export getInitialData, dehydrateState and getStaticAssets — the renderer calls all three. pdp-suite’s layout exports none. Slot mechanics, slots, accepts, prefill, presets and pages are all in Layout widgets.

Where the local SSR preview differs from production

The local harness (renderPluginSSR / createSSRDevServer, see Previewing SSR locally) is a faithful port of the renderer’s sandbox. The sandbox itself now matches (widget-core 0.12.2+): @homerunner-next/widget-core/runtime resolves as a shared module, TextEncoder / TextDecoder are absent from both, __HR_PLUGIN_ASSET_BASE__ is defined, externalFetch is enforced from the manifest, module scope runs under the same 5000 ms budget, and the render goes through WidgetHydrationTree with identifierPrefix set — so useId drift reproduces locally instead of first appearing on a customer’s page. On an SDK below 0.12.2 all six of those diverge, and code that passes locally fails on the renderer.

What still differs is the environment around the sandbox, not the sandbox. This is the summary; Previewing SSR locally works through what each row does to you.

Not supported yet. No local harness composes a layout’s slots. renderPluginSSR builds the props itself and passes no renderedSlots, so a layout previews as its shell with every slot empty. That still proves the shell evaluates and renders without throwing — the failure that 500s a whole customer page — but it is not a preview of the composed result.

A suite widget previews like any other: createSSRDevServer takes the widget you name and resolves dist/{widget}/{widget}-ssr.umd.js under plugin:{slug}:{widget} (widget-core 0.12.2+; the suite scaffold’s dev:ssr script needs create-hr-plugin 0.8.1+).

Checklist

• parseWidgetConfig(configZod, props.options ?? {}) in widget.tsx and in every SSR hook.
• Types imported from @homerunner-next/widget-core/contracts, not hand-written.
• No props.widgetType, Math.random(), Date.now() or window read during render.
• Only typeof window === "undefined" guards for browser-only code.
• Query keys prefixed with your plugin slug; ["widget", …] left alone.
• Every declared externalFetch host spelled exactly, with an explicit request timeout.
• getStaticAssets omitted unless you genuinely need to vary assets by settings.
• Layout components that cannot throw: defaults for every slot and every config field.

Runtime, mount and the DOM contract

Normative reference for what mount() does, every DOM attribute it reads and writes, and how your component reaches the browser. Almost everything here is runtime behaviour — observable on a customer page, not checked before you ship — so the failure modes are silent by default. Publish-time rules live in packaging-and-publishing.md; the canonical index of every number and message is limits-and-errors.md.

Enforcement levels used below follow the legend in limits-and-errors.md. Runtime rules are additionally tagged:

• runtime throw (isolated) — throws, is caught by mount, marks that one embed, other embeds continue.
• silent runtime — no error, the widget just behaves differently than you expected.
• advisory — nothing checks it; getting it wrong is a bug in your plugin only.

Boot order

Two scripts, in this order, per page:

<!-- src/app/(protected)/feeds/[id]/widgets/[widgetId]/[widgetName]/playground/EmbedCodeDialog.tsx:63-86 -->
<script src="https://assets.homerunner.io/w/runtime.iife.js" crossorigin="anonymous"></script>
<!-- single-widget plugin -->
<script src="https://assets.homerunner.io/p/my-plugin/my-plugin.iife.js"></script>
<!-- one widget of a suite -->
<script src="https://assets.homerunner.io/p/pdp-suite/stay-hero/stay-hero.iife.js"></script>

Never add crossorigin="anonymous" to a /p/ script tag — see assets-and-urls.md.

runtime.iife.js is the host page’s responsibility. On platform-composed pages it is emitted for you, in this order, by getDefaultJsUrls(). In a hand-written embed you must load it yourself, first.

Both shapes. Since widget-core 0.10.0 your client IIFE does not bundle React, React DOM, React Query or the widget-core runtime. The Vite preset externalizes them onto the runtime global:

// packages/homerunner-widget-core/src/vite/index.ts:141-153 — RUNTIME_GLOBALS
{
  react:                                "HRWidgetRuntime.React",
  "react/jsx-runtime":                  "HRWidgetRuntime.jsxRuntime",
  "react-dom":                          "HRWidgetRuntime.ReactDOM",
  "react-dom/client":                   "HRWidgetRuntime",
  "@tanstack/react-query":              "HRWidgetRuntime",
  "@homerunner-next/widget-core/runtime": "HRWidgetRuntime.widgetCore",
}

Consequences you must design around:

Not supported yet. The HRWidgetRuntime TypeScript interface in packages/homerunner-widget-core/src/globals.ts:15-69 does not declare widgetCore (nor useQueries / keepPreviousData, which the live runtime IIFE does export). The build maps them regardless — the type is behind the runtime. Cast if you must read them directly.

Registration

Registration writes a page-global registry. It is what the dashboard playground, the CSR layout child loader and mount’s category fallback all read.

// packages/homerunner-widget-core/src/globals.ts:149-177
registerPlugin(key: string, component: ComponentType<any>, meta?: { category?: "content" | "layout" }): void
registerPluginWidget(pluginSlug: string, widgetSlug: string, component: ComponentType<any>, meta?): void

registerPluginWidget(p, w, C, meta) is exactly registerPlugin("{p}:{w}", C, meta) — same registry, different spelling.

The registry key is everything after the plugin: prefix — there is no separate namespace. Both write window.HRPlugins[key] = { component, category? }; category is omitted entirely when meta.category is falsy. Registration is idempotent (last write wins) and is a no-op when window is undefined, so importing your entry in a Node test is safe.

The renderer itself never reads HRPlugins — it loads your SSR bundle directly. The registry is what the dashboard playground preview and a CSR layout’s slot-child loader read, and it is what the publish audit proves is present. Note that the audit only checks the string: a bundle that registers under the wrong key passes publish and fails silently at runtime.

mount(container, config)

// packages/homerunner-widget-core/src/runtime/mount.tsx:251
export function mount(container: HTMLElement, config: MountConfig): void

Returns void. There is no unmount return value — the handle is on the DOM element (see The unmount handle).