payload-live-preview 1.4.1 → 1.6.0

package/README.md

@@ -141,7 +141,31 @@ import RichText from 'payload-live-preview/astro/RichText.astro';
 <RichText value={page.body} field="body" class="prose" />
 ```
 
-**Injection modes.** The default (`mode: 'inline'`) bakes the runtime into every page at build time — right for `output: 'static'`, where no middleware runs at request time. For SSR projects (`output: 'server'`), request-time injection can limit the bytes to requests carrying preview intent:
+**Injection modes.** Three, and for a statically built site the default is rarely the best one.
+
+`mode: 'inline'` (the default) bakes the runtime into every page at build time. Simple, and it works without a server — but every ordinary visitor downloads and parses ~21 KB gzip for a feature only an editor uses.
+
+`mode: 'loader'` is the same deal without that cost. The page carries a few hundred bytes that check the preview context and fetch the runtime as a content-hashed, SRI-verified asset **only inside a preview**. Measured on the Astro fixture in this repository:
+
+|                  | `index.html`    |
+| ---------------- | --------------- |
+| `mode: 'inline'` | 70 314 bytes    |
+| `mode: 'loader'` | **3 151 bytes** |
+
+That is per page, so a hundred-page site saves it a hundred times. The asset is published once at `/_payload-live-preview/runtime.<hash>.js`, cached across every page, and — because the configuration stays in the inline bootstrap — byte identical for every site on this version. It therefore cannot carry a deployment secret, and a redeploy that did not change the runtime does not invalidate the cached copy. `astro dev` serves the same path from memory, so development and production behave the same.
+
+```ts
+livePreview({
+  mode: 'loader',
+  allowedOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
+}),
+```
+
+The trade is one extra request the first time an editor opens a preview.
+
+Under a strict CSP, the asset itself is unremarkable: a same-origin script with an `integrity` attribute, needing no `'unsafe-inline'`. The bootstrap does need covering, though — a static build has no request, so there is no per-request nonce to attach and Astro emits it as a plain inline `<script>`. Its content is deterministic for a given package version and configuration, so the practical answer is a `'sha256-…'` source expression rather than `'unsafe-inline'`. `mode: 'middleware'` is the option that can carry a real nonce, because there a request exists to derive one from.
+
+For SSR projects (`output: 'server'`), request-time injection can limit the bytes to requests carrying preview intent:
 
 ```ts
 livePreview({
@@ -567,9 +591,119 @@ Together these span the whole spectrum: tier 1 proves the real thing works end t
 
 Full details in [docs/security.md](docs/security.md). Report vulnerabilities per [SECURITY.md](SECURITY.md).
 
+## Inspecting a running preview
+
+When a preview misbehaves, `inspect()` returns a point-in-time snapshot of what
+the runtime actually sees. It performs no I/O and transmits nothing.
+
+Adapter users reach it on the global handle inside the preview iframe — that is
+the point, because there is no client object to call a method on:
+
+```js
+// In the browser console, inside the preview iframe
+__livePreview.inspect();
+```
+
+Consumers driving the runtime themselves call it on the client:
+
+```ts
+const client = initLivePreview({ allowedOrigins: ['https://cms.example.com'] });
+console.log(client.inspect());
+```
+
+The snapshot answers the questions that are otherwise guesswork:
+
+| Reading                                                    | What it tells you                                                                                                                                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bindings.orphanFields`                                    | Field names that arrived but matched no element. A name here is a markup problem; a name in neither this nor `bindings.fieldNames` was never sent.                                   |
+| `scheduler.deferred` with `scheduler.visibilityGateActive` | Updates the visibility gate is holding until the element scrolls into view. On a page nobody scrolls, that is "never" — the symptom is a preview that stops updating below the fold. |
+| `revisions.superseded`                                     | Updates abandoned because a newer one arrived. Tracking `accepted` closely is normal for fast typing; it only matters when the _last_ update is among them.                          |
+| `origins.locked`                                           | The origin the runtime locked onto after its first accepted update. Every other origin is refused from then on.                                                                      |
+| `bindings.ownerScoped` with `bindings.owners`              | Whether owner scoping is on, and which documents the page declares. Under scoping, an unowned binding receives nothing.                                                              |
+| `protocol.negotiated`                                      | The version both sides share, which caps the capabilities in `protocol.capabilities`.                                                                                                |
+
+This is deliberately not gated to development builds. A snapshot discloses
+nothing that is not already on the page — the trusted origins are inside the
+injected script and the field names are `data-payload-field` attributes in the
+DOM — and a preview that misbehaves only on the deployed site is exactly the
+case where the information is worth having.
+
+## Auditing a deployment: `pll doctor`
+
+`inspect()` answers "what is this runtime doing right now" from inside the page.
+`pll doctor` answers the question one step earlier: **what is this deployment
+actually serving?**
+
+```
+npx pll doctor https://example.com/some-page --admin https://cms.example.com
+```
+
+It fetches the URL twice — once as an ordinary visitor, once with the headers
+the admin's iframe sends — and reports the difference. That comparison is the
+point: a config can say `allowedOrigins: [...]` while a proxy strips the
+header, an adapter runs in a mode nobody remembers choosing, or a build emits
+binding attributes on public pages.
+
+What it checks:
+
+| Code     | Finding                                                                                                                                                                                                                                                                                             |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LP0701` | No inline runtime in the preview response. A warning, not an error: the audit cannot tell an adapter that missed the request from a consumer who starts `LivePreviewClient` themselves. Also reports, as information, when the runtime reaches anonymous visitors (correct for `inject: 'always'`). |
+| `LP0702` | No `frame-ancestors` on the preview response, or a policy that does not admit `--admin`. A bare `'self'` counts as admitting it when admin and site share an origin.                                                                                                                                |
+| `LP0703` | `X-Frame-Options` forbids framing — browsers honour it independently of CSP. `SAMEORIGIN` is accepted when `--admin` shares the page's origin; `DENY` never is.                                                                                                                                     |
+| `LP0704` | Binding attributes served to anonymous visitors.                                                                                                                                                                                                                                                    |
+| `LP0705` | More bindings than the default `visibilityGateThreshold` writes eagerly.                                                                                                                                                                                                                            |
+| `LP0706` | Bindings outside every owner marker, which receive nothing under `scopeBindingsByOwner`.                                                                                                                                                                                                            |
+| `LP0707` | The runtime is present with nothing to write into.                                                                                                                                                                                                                                                  |
+
+Exit codes: `0` no error-level findings, `1` usage error or the URL could not be
+fetched, `2` at least one error-level finding — so it drops into CI as a smoke
+test against a deploy preview. `--json` emits the report as data.
+
+The audit makes exactly the two requests it is told to make, sends no
+credentials, and reports no telemetry. `analyzeProbe()` is exported from
+`payload-live-preview/doctor` for callers who fetch the responses themselves.
+
+## Diagnostic codes
+
+Every message the runtime reports carries a stable code. Prose gets reworded; a
+code does not — so a log filter, an alert rule, or a bug report that names
+`LP0301` still means the same thing after the sentence around it changes.
+
+| Code     | Meaning                                              | What to do                                                                                             |
+| -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `LP0101` | No trusted origin configured in production           | Set `PAYLOAD_ADMIN_ORIGIN` or pass `allowedOrigins`. Nothing is accepted until you do.                 |
+| `LP0102` | Origin trust rests on `document.referrer`            | Any framing site is trusted. Set `allowedOrigins` and a `frame-ancestors` CSP.                         |
+| `LP0201` | An update named a field with no binding on the page  | Render the binding anchor unconditionally so edits to an initially-empty field have somewhere to land. |
+| `LP0202` | Owner scoping is on and the update names no document | The message carries neither a global slug nor a collection slug plus id.                               |
+| `LP0301` | The visibility gate held offscreen writes back       | Raise `visibilityGateThreshold`, or accept that below-the-fold updates wait for a scroll.              |
+| `LP0401` | A value was refused as an unsafe attribute write     | The attribute or the value is not safe to write; see the security model.                               |
+| `LP0402` | A text element has structured children               | Move `data-payload-field` to the value element, or add `data-payload-text`.                            |
+| `LP0403` | A structural container has no array template         | Add `data-payload-array-template`.                                                                     |
+| `LP0501` | A message was rejected before the update pipeline    | Reason is one of origin, shape, type, token. Visible with `debug: true`.                               |
+| `LP0502` | A preview token was rejected                         | Also reported when your `validateToken` throws — a throwing validator fails closed.                    |
+| `LP0601` | A consumer event handler threw                       | Your `on(...)` handler; the runtime continued.                                                         |
+| `LP0602` | A consumer transform threw                           | The original value was kept.                                                                           |
+| `LP0603` | A renderer threw while writing                       | That one write was abandoned.                                                                          |
+| `LP0605` | Runtime startup failed                               |                                                                                                        |
+| `LP0606` | Sending the ready handshake failed                   |                                                                                                        |
+
+Codes on the `error` event can be branched on directly:
+
+```ts
+import { DIAGNOSTIC_CODES } from 'payload-live-preview';
+
+client.events.on('error', (e) => {
+  if (e.code === DIAGNOSTIC_CODES.TransformThrew) reportToSentry(e.error);
+});
+```
+
+Codes are never reused for a different meaning and never renumbered. `LP0604`
+is reserved and unassigned.
+
 ## Troubleshooting
 
-- **Nothing updates** — open the browser console inside the preview iframe (`debug: true` adds verbose diagnostics). The most common causes: the admin origin is not in `allowedOrigins`; the page is not actually loaded in an iframe; the binding element does not exist (see the empty-field gotcha above — orphan-update warnings are always enabled and deduplicated per field).
+- **Nothing updates** — call `__livePreview.inspect()` in the preview iframe's console first; it names the cause in most cases (see [Inspecting a running preview](#inspecting-a-running-preview)). `debug: true` adds verbose diagnostics on top. The most common causes: the admin origin is not in `allowedOrigins`; the page is not actually loaded in an iframe; the binding element does not exist (see the empty-field gotcha above — orphan-update warnings are always enabled and deduplicated per field).
 - **Relationship fields show IDs** — set `serverURL` (Payload 3.x sends unpopulated form values).
 - **`Referrer-Policy: no-referrer`** on the admin breaks zero-config origin detection — set `allowedOrigins` explicitly.
 - **Preview iframe refuses to load** — your host sets `X-Frame-Options` or a restrictive `frame-ancestors`. The adapters' CSP management overrides `frame-ancestors` on intent-matched responses, but `X-Frame-Options: DENY` from a proxy must be removed for authorized preview responses.

package/dist/adapters/astro/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LivePreviewAstroOptions } from '../../middleware-CkSeLZ-9.js';
-export { a as LivePreviewMiddleware, N as NONCE_LOCALS_KEY, c as createLivePreviewMiddleware } from '../../middleware-CkSeLZ-9.js';
+import { L as LivePreviewAstroOptions } from '../../middleware-DD4Hwomt.js';
+export { a as LivePreviewMiddleware, N as NONCE_LOCALS_KEY, c as createLivePreviewMiddleware } from '../../middleware-DD4Hwomt.js';
 
 /**
  * Astro integration for Payload Live Preview.
@@ -36,8 +36,32 @@ export { a as LivePreviewMiddleware, N as NONCE_LOCALS_KEY, c as createLivePrevi
 type ScriptStage = 'head-inline' | 'page' | 'before-hydration' | 'page-ssr';
 interface VitePluginLike {
     readonly name: string;
-    readonly resolveId: (id: string) => string | undefined;
-    readonly load: (id: string) => string | undefined;
+    readonly resolveId?: (id: string) => string | undefined;
+    readonly load?: (id: string) => string | undefined;
+    readonly configureServer?: (server: ViteDevServerLike) => void;
+    readonly generateBundle?: (this: RollupEmitContext) => void;
+}
+/** The one Rollup facility this needs: publishing a file into the output. */
+interface RollupEmitContext {
+    emitFile: (file: {
+        type: 'asset';
+        fileName: string;
+        source: string;
+    }) => void;
+}
+/** Just enough of Vite's dev server to serve one file. */
+interface ViteDevServerLike {
+    readonly middlewares: {
+        use: (handler: (req: DevRequest, res: DevResponse, next: () => void) => void) => void;
+    };
+}
+interface DevRequest {
+    readonly url?: string | undefined;
+}
+interface DevResponse {
+    statusCode: number;
+    setHeader: (name: string, value: string) => void;
+    end: (body?: string) => void;
 }
 interface AstroConfigSetupContext {
     readonly injectScript: (stage: ScriptStage, content: string) => void;
@@ -50,6 +74,10 @@ interface AstroConfigSetupContext {
             plugins?: VitePluginLike[];
         };
     }) => void;
+    /** Astro's configured `base`; absent on versions that do not expose it. */
+    readonly config?: {
+        readonly base?: string;
+    };
 }
 interface AstroIntegrationLike {
     readonly name: string;