@bettercms-ai/preview-runtime 0.2.0 → 0.4.0

package/README.md

@@ -42,12 +42,33 @@ A component does not have to be a standalone file with its fields as props. A se
 `npx @bettercms-ai/convert --componentize` extracted from a page (a file starting
 `// @bettercms-ai/convert section v…`) is recognised by that marker and rendered with its section contract:
 `<Section blockId="bcms-preview" overrides={props} page={{}} />`, so the live props arrive as the instance's
-own copy. Record those sources with the MCP tool `submit_componentize_receipt`, or `set_component_source`
-with `kind: "section"` for a section written by hand to the same contract.
+own copy.
+
+## Components with no file
+
+A component placed on a page, or used in the project Layout (navigation, footer), needs no recorded file.
+The manifest lists it as `kind: "page"`; the preview renders that real route of your app — its loops, child
+components, collections and page styles exactly as deployed — keeps only the component's own element
+(`data-bcms-block`, else the element holding its fields, else the layout's `<header>`/`<footer>`), and writes
+the live props onto it through the same `data-bcms-field` / `data-bcms-layout-field` / `data-bcms-props`
+attributes the site already declares. A recorded file still wins when there is one.
+
+v1 limits: scripts inside the kept element do not run, so a client island renders its server HTML without
+hydrating (validation is unaffected). The Next.js page path (`render` → `render-page`) is untested against a
+real Next app yet; Astro is verified.
 
 A failed validation reports what broke — the app server's own error lines first — and the dashboard shows
 it under "Runtime + console".
 
+## Batch validation
+
+One run can validate several components against a single build. When the dispatch carries a `batch`
+(`BCMS_BATCH`, a JSON array of `{ requestId, componentId, familyKey, nativeViewports }`), the validator builds and
+uploads the runtime once, starts one browser, and validates each component in turn — a component that cannot be
+validated is reported for that component and the rest carry on. Without `BCMS_BATCH` it validates the single
+component named by `BCMS_REQUEST_ID` / `BCMS_COMPONENT_ID` / `BCMS_FAMILY_KEY` / `BCMS_NATIVE_VIEWPORTS`, as
+before. The step fails when any component could not be validated.
+
 ## How a preview renders
 
 - **Astro**: built with `output: "server"` and `@astrojs/node`, so `.astro` components render on the