@picked/client 0.0.70-next.1 → 0.0.70-next.2

package/dist/types/preview-receiver/protocol.d.ts

@@ -0,0 +1,60 @@
+import { ContentPatchOp } from './apply-ops';
+/** Current protocol version. Reported on the handshake for support and telemetry only. */
+export declare const PREVIEW_PROTOCOL_VERSION = 1;
+/** Receiver → embedder: the frame is listening and content is registered. */
+export declare const PREVIEW_READY_MESSAGE = "picked-preview:ready";
+/** Embedder → receiver: path-addressed replacements for one content record. */
+export declare const PREVIEW_CONTENT_PATCH_MESSAGE = "picked-preview:content-patch";
+/** Receiver → embedder: a sequence gap was detected; resend the dirty paths. */
+export declare const PREVIEW_RESYNC_MESSAGE = "picked-preview:resync";
+/** Receiver → embedder: cumulative count of inserted subtrees whose scripts were neutralised. */
+export declare const PREVIEW_INERT_SCRIPTS_MESSAGE = "picked-preview:inert-scripts";
+/** Handshake posted by the receiver to each allowlisted origin. */
+export interface PreviewReadyMessage {
+    /** Discriminator. */
+    type: typeof PREVIEW_READY_MESSAGE;
+    /** Protocol version this receiver speaks. Diagnostics only. */
+    protocolVersion: number;
+    /** Content record ids currently registered, so the embedder knows what it can patch. */
+    contentIds: string[];
+}
+/** Patch posted by the embedder for one content record. Narrowed to by {@link isContentPatchMessage}. */
+interface PreviewContentPatchMessage {
+    /** Discriminator. */
+    type: typeof PREVIEW_CONTENT_PATCH_MESSAGE;
+    /** The content record to patch. */
+    contentId: string;
+    /** Path-addressed replacements, applied in order. */
+    ops: ContentPatchOp[];
+    /** Monotonic per-record sequence number, used only to detect a dropped message. */
+    seq: number;
+}
+/** Resync request posted by the receiver after a sequence gap. */
+export interface PreviewResyncMessage {
+    /** Discriminator. */
+    type: typeof PREVIEW_RESYNC_MESSAGE;
+    /** The content record whose sequence broke. */
+    contentId: string;
+    /** The last sequence number successfully applied. */
+    lastSeq: number;
+}
+/** Inert-script report posted by the receiver. */
+export interface PreviewInertScriptsMessage {
+    /** Discriminator. */
+    type: typeof PREVIEW_INERT_SCRIPTS_MESSAGE;
+    /** Cumulative count of inserted subtrees whose scripts were neutralised this session. */
+    total: number;
+}
+/**
+ * Type guard for an inbound content-patch message.
+ *
+ * Validates structurally rather than trusting the sender: the message crosses a frame boundary, and
+ * an unrecognised or malformed one is ignored rather than throwing inside a customer's page.
+ *
+ * @param {unknown} data - The `MessageEvent.data` payload.
+ * @returns {boolean} True when the payload is a well-formed content-patch message.
+ * @example isContentPatchMessage(event.data)
+ */
+export declare function isContentPatchMessage(data: unknown): data is PreviewContentPatchMessage;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/types/preview-receiver/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/preview-receiver/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,yBAAyB,CAAA;AAC3D,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,iCAAiC,CAAA;AAC3E,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,0BAA0B,CAAA;AAC7D,iGAAiG;AACjG,eAAO,MAAM,6BAA6B,iCAAiC,CAAA;AAE3E,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,qBAAqB;IACrB,IAAI,EAAE,OAAO,qBAAqB,CAAA;IAClC,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAA;IACvB,wFAAwF;IACxF,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,yGAAyG;AACzG,UAAU,0BAA0B;IAClC,qBAAqB;IACrB,IAAI,EAAE,OAAO,6BAA6B,CAAA;IAC1C,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,GAAG,EAAE,cAAc,EAAE,CAAA;IACrB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,qBAAqB;IACrB,IAAI,EAAE,OAAO,sBAAsB,CAAA;IACnC,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IACzC,qBAAqB;IACrB,IAAI,EAAE,OAAO,6BAA6B,CAAA;IAC1C,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;CACd;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,0BAA0B,CAavF"}

package/dist/types/utils/content-path.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Content-path parsing for live-preview patches.
+ *
+ * Paths address a field inside a Content Entry's delivered `data` blob using the format the Picked
+ * API already emits for content-data validation errors — `$.sections[0].data.title`, rooted at `$`,
+ * with `.key` for object keys and `[n]` for array indices. Reusing that format keeps one convention
+ * across validation errors and preview patches instead of inventing a second.
+ *
+ * Content-model field keys are constrained to `/^[a-z][a-z0-9_]*$/` server-side, so no key can
+ * contain `.` or `[` and the string form needs no escaping.
+ */
+/** One step along a content path: an object key, or an array index. */
+export type ContentPathSegment = string | number;
+/**
+ * Parses a content path into its segments.
+ *
+ * Returns an empty list for the root path *and* for anything malformed. Callers treat an empty list
+ * as "no addressable target" and skip the operation, so a corrupt or hostile path from another
+ * frame degrades to a no-op instead of throwing inside a customer's page.
+ *
+ * @param {string} path - The path to parse, for example `$.sections[0].data.title`.
+ * @returns {ContentPathSegment[]} The parsed segments, or `[]` for the root or an invalid path.
+ * @example
+ * parseContentPath('$.sections[0].data.title') // ['sections', 0, 'data', 'title']
+ */
+export declare function parseContentPath(path: string): ContentPathSegment[];
+/**
+ * Formats segments back into a content path. Inverse of {@link parseContentPath} for every
+ * well-formed path.
+ *
+ * @param {readonly ContentPathSegment[]} segments - The segments to format.
+ * @returns {string} The path string, or `'$'` when there are no segments.
+ * @example
+ * formatContentPath(['sections', 0, 'data', 'title']) // '$.sections[0].data.title'
+ */
+export declare function formatContentPath(segments: readonly ContentPathSegment[]): string;
+//# sourceMappingURL=content-path.d.ts.map

package/dist/types/utils/content-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-path.d.ts","sourceRoot":"","sources":["../../../src/utils/content-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,CAAA;AA2ChD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAYnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAOjF"}

package/dist/types/utils/inert-script-report.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Relays the count of preview-inserted subtrees whose scripts were neutralised.
+ *
+ * The render layer (`@picked/react`'s `HtmlRender`) knows how many script-bearing subtrees a
+ * preview morph inserted; the preview receiver knows how to tell the dashboard. Neither should
+ * import the other, so the count passes through this tiny module. Every framework binding's render
+ * path reports into the same receiver through it.
+ *
+ * The count is cumulative for the session and only ever grows, which matches how the editor uses
+ * it: "some markup you added is inert until you save", not a per-edit delta.
+ */
+/** Listener notified when the cumulative inert-subtree count changes. */
+type InertScriptListener = (total: number) => void;
+/**
+ * Records that a preview render inserted `count` subtrees whose scripts were neutralised.
+ *
+ * @param {number} count - Subtrees neutralised by the render that just completed.
+ * @returns {void} Nothing.
+ * @example reportInertScriptSubtrees(2)
+ */
+export declare function reportInertScriptSubtrees(count: number): void;
+/**
+ * Subscribes to the cumulative inert-subtree count, invoking `listener` immediately with the
+ * current total so a late subscriber (the receiver connects after first paint) is not left behind.
+ *
+ * @param {InertScriptListener} listener - Called with the running total.
+ * @returns {() => void} Unsubscribe function.
+ * @example const stop = onInertScriptSubtrees((n) => post({ inertScriptSubtrees: n }))
+ */
+export declare function onInertScriptSubtrees(listener: InertScriptListener): () => void;
+/**
+ * Resets the cumulative count and drops every listener. Exposed for tests, which share a module
+ * registry across cases.
+ *
+ * @returns {void} Nothing.
+ * @example resetInertScriptReport()
+ */
+export declare function resetInertScriptReport(): void;
+export {};
+//# sourceMappingURL=inert-script-report.d.ts.map

package/dist/types/utils/inert-script-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inert-script-report.d.ts","sourceRoot":"","sources":["../../../src/utils/inert-script-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,yEAAyE;AACzE,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;AAKlD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI7D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAM/E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}

package/dist/types/utils/preview-session.d.ts

@@ -0,0 +1,12 @@
+/** Search parameter the dashboard appends to the preview iframe's URL. */
+export declare const PREVIEW_TOKEN_PARAM = "preview-token";
+/**
+ * Whether this frame is running as a Picked live-preview session: inside an iframe, with a preview
+ * token on the URL.
+ *
+ * @returns {boolean} True when the frame is a preview session.
+ * @example
+ * if (isPreviewSession()) enableMorphingRender()
+ */
+export declare function isPreviewSession(): boolean;
+//# sourceMappingURL=preview-session.d.ts.map

package/dist/types/utils/preview-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-session.d.ts","sourceRoot":"","sources":["../../../src/utils/preview-session.ts"],"names":[],"mappings":"AAUA,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAElD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAG1C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picked/client",
-  "version": "0.0.70-next.1",
+  "version": "0.0.70-next.2",
   "dependencies": {
     "@withease/factories": "^1.0.5"
   },
@@ -35,6 +35,12 @@
       "require": "./dist/cjs/server/index.js",
       "default": "./dist/esm/server/index.js"
     },
+    "./preview": {
+      "types": "./dist/types/preview/index.d.ts",
+      "import": "./dist/esm/preview/index.js",
+      "require": "./dist/cjs/preview/index.js",
+      "default": "./dist/esm/preview/index.js"
+    },
     "./plugins/single-page-app": {
       "types": "./dist/types/plugins/single-page-app/index.d.ts",
       "import": "./dist/esm/plugins/single-page-app/index.js",
@@ -166,12 +172,18 @@
   "size-limit": [
     {
       "path": "dist/esm/index.js",
-      "limit": "14.5 kB"
+      "limit": "16 kB",
+      "name": "index (incl. lazily-loaded preview channel; see AGENTS.md)"
     },
     {
       "path": "dist/esm/server/index.js",
       "limit": "10 kB"
     },
+    {
+      "path": "dist/esm/preview/index.js",
+      "limit": "5 kB",
+      "name": "preview helpers (dashboard-only subpath)"
+    },
     {
       "path": "dist/esm/plugins/single-page-app/index.js",
       "limit": "5 kB"

package/dist/preview-bridge-CpX1BkSA.cjs

@@ -1 +0,0 @@
-const e=require("./object-CIkt7Fkr.cjs"),t=require("./supports-DBzjGaWD.cjs");var n=`picked-preview:navigation`,r=!1;function i(){return`*`}function a(){let{href:e,pathname:t,search:r}=globalThis.location,a={type:n,href:e,pathname:t,search:r};globalThis.parent.postMessage(a,i())}function o(e){return function(...t){e.apply(this,t),a()}}function s(){if(r||!t.f())return()=>void 0;r=!0,a();let n=()=>{a()};return globalThis.addEventListener(`popstate`,n),t.a()&&(e.n(globalThis.history,`pushState`,o),e.n(globalThis.history,`replaceState`,o)),()=>{r=!1,globalThis.removeEventListener(`popstate`,n)}}exports.initPreviewBridge=s;

package/dist/preview-bridge-D76l-dPy.js

@@ -1,33 +0,0 @@
-import { n as e } from "./object-BUDGxEqy.js";
-import { a as t, f as n } from "./supports-CO9bJGNl.js";
-//#region src/preview-bridge/index.ts
-var r = "picked-preview:navigation", i = !1;
-function a() {
-	return "*";
-}
-function o() {
-	let { href: e, pathname: t, search: n } = globalThis.location, i = {
-		type: r,
-		href: e,
-		pathname: t,
-		search: n
-	};
-	globalThis.parent.postMessage(i, a());
-}
-function s(e) {
-	return function(...t) {
-		e.apply(this, t), o();
-	};
-}
-function c() {
-	if (i || !n()) return () => void 0;
-	i = !0, o();
-	let r = () => {
-		o();
-	};
-	return globalThis.addEventListener("popstate", r), t() && (e(globalThis.history, "pushState", s), e(globalThis.history, "replaceState", s)), () => {
-		i = !1, globalThis.removeEventListener("popstate", r);
-	};
-}
-//#endregion
-export { c as initPreviewBridge };