payload-live-preview 1.4.0 → 1.5.0

package/dist/probe-tMHdim5y.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Stable identifiers for everything the runtime reports.
+ *
+ * Prose gets reworded; a code does not. A consumer filtering logs, an alert
+ * rule, or a bug report referring to `LP0301` keeps meaning the same thing
+ * after the sentence around it is rewritten, and a code is greppable in a way
+ * that a sentence fragment is not.
+ *
+ * Codes are grouped by the question they answer:
+ *
+ * - `LP01xx` — configuration and origin trust: the runtime is running, but it
+ *   was set up in a way that will bite.
+ * - `LP02xx` — bindings and markup: an update had nowhere to land.
+ * - `LP03xx` — updates and scheduling: the update landed somewhere other than
+ *   the DOM, or not yet.
+ * - `LP04xx` — rendering: a value reached an element and was refused.
+ * - `LP05xx` — protocol and messages: something arrived that was not accepted.
+ * - `LP06xx` — consumer callbacks: code the consumer supplied threw.
+ * - `LP07xx` — audit findings from `pll doctor`, which reports on a served
+ *   response rather than on a running runtime.
+ *
+ * A code is part of the public contract. Codes are never reused for a
+ * different meaning and never renumbered; a retired code stays retired.
+ * `LP0604` is unassigned: a throwing token validator is deliberately treated
+ * as a rejection and reported as `LP0502`, so there is nothing distinct to
+ * report yet. The number stays reserved rather than being handed to something
+ * else.
+ *
+ * The runtime writes these as string literals at each reporting site rather
+ * than reading them from this record, so the inline build pays for the six
+ * characters it prints and nothing more. This record exists so consumers can
+ * refer to a code by name instead of copying a literal.
+ *
+ * @module @core/diagnostic-codes
+ */
+/**
+ * Every diagnostic code the runtime can report, by name.
+ *
+ * ```ts
+ * client.events.on('error', (e) => {
+ *   if (e.code === DIAGNOSTIC_CODES.TransformThrew) reportToSentry(e.error);
+ * });
+ * ```
+ */
+declare const DIAGNOSTIC_CODES: Readonly<{
+    /** No trusted origin configured in production; nothing will be accepted. */
+    readonly NoTrustedOrigin: "LP0101";
+    /** Origin trust rests on `document.referrer`, so any framing site is trusted. */
+    readonly ReferrerOnlyTrust: "LP0102";
+    /** An update named a field with no binding anchor on the page. */
+    readonly OrphanField: "LP0201";
+    /** Owner scoping is on and the update names no document it could belong to. */
+    readonly UnattributableUpdate: "LP0202";
+    /** The visibility gate held offscreen writes back until they scroll into view. */
+    readonly VisibilityGateDeferred: "LP0301";
+    /** A value was refused because the attribute or the value itself is unsafe. */
+    readonly UnsafeAttributeWrite: "LP0401";
+    /** A text element has structured children, so replacing its text was skipped. */
+    readonly TextTargetHasChildren: "LP0402";
+    /** A structural container has no array template, so the update was skipped. */
+    readonly MissingArrayTemplate: "LP0403";
+    /** A message was rejected before it reached the update pipeline. */
+    readonly MessageRejected: "LP0501";
+    /** A preview token was rejected. */
+    readonly TokenRejected: "LP0502";
+    /** A consumer event handler threw. */
+    readonly HandlerThrew: "LP0601";
+    /** A consumer transform threw; the original value was kept. */
+    readonly TransformThrew: "LP0602";
+    /** A renderer threw while writing a value. */
+    readonly RendererThrew: "LP0603";
+    /** Runtime startup failed. */
+    readonly StartupFailed: "LP0605";
+    /** Sending the ready handshake failed. */
+    readonly ReadyFailed: "LP0606";
+    /** The audit found no runtime in a response that carried preview intent. */
+    readonly AuditRuntimeMissing: "LP0701";
+    /** The preview response declares no `frame-ancestors`. */
+    readonly AuditNoFrameAncestors: "LP0702";
+    /** `X-Frame-Options` forbids framing, which no CSP can undo. */
+    readonly AuditFrameOptionsBlocks: "LP0703";
+    /** Binding attributes are served to anonymous visitors. */
+    readonly AuditBindingsExposed: "LP0704";
+    /** More bindings than the default visibility gate will write eagerly. */
+    readonly AuditGateThresholdExceeded: "LP0705";
+    /** Owner markers exist, but some bindings are outside all of them. */
+    readonly AuditUnownedBindings: "LP0706";
+    /** The preview response carries no bindings at all. */
+    readonly AuditNoBindings: "LP0707";
+    /** The URL did not return an HTML page, so nothing else can be judged. */
+    readonly AuditNotAPage: "LP0708";
+}>;
+/** A diagnostic code, as it appears in log output and on the `error` event. */
+type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+
+/**
+ * Shapes for the `pll doctor` audit.
+ *
+ * This module is types only.
+ *
+ * @module @doctor/types
+ */
+
+/** How much a finding should worry the reader. */
+type DoctorLevel = 'error' | 'warning' | 'info';
+/** One thing the audit noticed about what the site actually served. */
+interface DoctorFinding {
+    readonly code: DiagnosticCode;
+    readonly level: DoctorLevel;
+    /** One line, the problem itself. */
+    readonly title: string;
+    /** What was observed, in terms of the actual response. */
+    readonly detail: string;
+    /** What to change. Empty for informational findings that need no action. */
+    readonly remedy: string;
+}
+/**
+ * A response as the audit needs to see it. Modelled as plain data rather than
+ * a `Response` so the analysis is testable without a network or a fetch
+ * implementation.
+ */
+interface DoctorResponse {
+    readonly status: number;
+    /** Header names lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** The two fetches the audit compares. */
+interface DoctorProbe {
+    /**
+     * The page as an ordinary visitor sees it: no preview intent, no admin
+     * referer, top-level navigation.
+     */
+    readonly publicResponse: DoctorResponse;
+    /**
+     * The same page requested the way the admin's iframe requests it, which is
+     * what triggers `'preview-only'` injection.
+     */
+    readonly previewResponse: DoctorResponse;
+}
+/** What the audit was told about the deployment it is checking. */
+interface DoctorContext {
+    /** The page that was probed. */
+    readonly url: string;
+    /**
+     * The admin origin the preview is supposed to be embedded from, when the
+     * caller supplied one. Without it the `frame-ancestors` check can only say
+     * whether a policy exists, not whether it admits the right origin.
+     */
+    readonly adminOrigin?: string | undefined;
+}
+/** The complete audit result. */
+interface DoctorReport {
+    readonly url: string;
+    /** Findings, most severe first. */
+    readonly findings: readonly DoctorFinding[];
+    /** Counts by level, for the exit code and the summary line. */
+    readonly errors: number;
+    readonly warnings: number;
+}
+
+/** Injectable so tests can drive the audit without a server. */
+type DoctorFetch = (url: string, init: {
+    readonly headers: Readonly<Record<string, string>>;
+}) => Promise<DoctorResponse>;
+interface RunDoctorOptions {
+    readonly url: string;
+    /** Admin origin the preview is meant to be embedded from, when known. */
+    readonly adminOrigin?: string | undefined;
+    /** Defaults to `globalThis.fetch`. */
+    readonly fetchImpl?: DoctorFetch | undefined;
+}
+/**
+ * Normalise header names to lowercase.
+ *
+ * Exported because every header check downstream reads a lowercase key: if
+ * this were wrong, `content-security-policy` and `x-frame-options` would both
+ * read as absent and the audit would invent findings rather than report them.
+ * A silent failure of exactly that shape is worth a test of its own.
+ */
+declare function lowercaseHeaders(headers: Headers): Record<string, string>;
+/**
+ * Fetch the URL twice — as a visitor and as the admin's iframe — and audit the
+ * difference.
+ */
+declare function runDoctor(options: RunDoctorOptions): Promise<DoctorReport>;
+/** Render a report for a terminal. */
+declare function formatReport(report: DoctorReport): string;
+
+export { type DoctorFetch as D, type RunDoctorOptions as R, type DoctorProbe as a, type DoctorContext as b, type DoctorReport as c, DIAGNOSTIC_CODES as d, type DiagnosticCode as e, type DoctorFinding as f, type DoctorLevel as g, type DoctorResponse as h, formatReport as i, lowercaseHeaders as l, runDoctor as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-live-preview",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Live preview for Payload CMS in Astro and any SSR/static frontend (SvelteKit, Nuxt, Next.js, plain HTML). Patches the DOM live, no rebuild.",
   "author": "relative23",
   "license": "MIT",
@@ -70,6 +70,12 @@
         "default": "./dist/codegen-astro.js"
       }
     },
+    "./doctor": {
+      "import": {
+        "types": "./dist/doctor.d.ts",
+        "default": "./dist/doctor.js"
+      }
+    },
     "./payload": {
       "import": {
         "types": "./dist/payload.d.ts",
@@ -89,7 +95,8 @@
     }
   },
   "bin": {
-    "pll-codegen": "./dist/codegen-cli.js"
+    "pll-codegen": "./dist/codegen-cli.js",
+    "pll": "./dist/doctor-cli.js"
   },
   "files": [
     "dist",