@preprio/toolkit 0.4.3 → 0.5.0-rc.10

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-e1fUWl2Y.cjs';
-export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-e1fUWl2Y.cjs';
+import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-CX422dCO.cjs';
+export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-CX422dCO.cjs';
 
 /**
  * Package version; must match package.json. Lives in its own leaf module so
  * core can import it without cycling through the barrel.
  */
-declare const VERSION = "0.4.3";
+declare const VERSION = "0.5.0-rc.10";
 
 /**
  * Resolve a `PreprFeatures` bag to plain booleans, defaulting every omitted key
@@ -137,13 +137,295 @@ declare class PreprToolbarElement extends HTMLElementBase {
 /** Idempotent, including across bundles that each try to define the element. */
 declare function definePreprToolbar(): void;
 
+/** Which field the editor asked the preview to bring on screen. */
+interface ScrollToFieldMessage {
+    field: string;
+    id?: string;
+    /** Item within a list field value: the n-th `<li>` of a rich text list. */
+    block?: number;
+    /** The entry's `data-prepr-entry-id`, preferred over `field` when present. */
+    entryId?: string;
+    /**
+     * The same field with stack entries named by id instead of position, as
+     * on entries added before save, whose position changes until then.
+     */
+    fieldById?: string;
+}
+/** A content item the open item links to, and the field that links it. */
+interface EditorReference {
+    id: string;
+    field: string;
+}
+/**
+ * An image asset used by the open item: where its field is, and the part of
+ * its CDN URL that identifies it whatever size the page renders it at.
+ */
+interface EditorAsset {
+    key: string;
+    /** Field path in the editor, as stega text carries it. */
+    field: string;
+    /** The Dynamic Content entry that holds the asset. */
+    entryId?: string;
+}
+/** What the editor told the preview when the handshake completed. */
+interface EditorHandshake {
+    /**
+     * The content item open in the editor. Absent when the editor does not
+     * send one, in which case every tagged element counts as part of it.
+     */
+    itemId?: string;
+    /**
+     * Items the open item references. Absent when the editor does not send
+     * them, in which case other items are not split into linked and unrelated.
+     */
+    referencedIds?: EditorReference[];
+    /**
+     * `_id`s of component instances inside the open item. Content tagged with
+     * one of them (`previewAttrs` on a component's image) belongs to the open
+     * item, not to another one.
+     */
+    componentIds?: string[];
+    /**
+     * The language of the editor's own interface. Absent when the editor does
+     * not send one or sends a language the toolkit has no translations for.
+     */
+    uiLocale?: Locale;
+    /**
+     * The editor asks before the preview leaves the page: navigations are
+     * stopped and reported as `navigation_blocked`, and
+     * `prepr:allowNavigation` follows one. Absent for editors that do not
+     * handle `navigation_blocked`.
+     */
+    navigationGuard?: boolean;
+    /**
+     * Image assets of the open item. Absent when the editor does not send
+     * them, in which case images are only editable where the page tags them.
+     */
+    assets?: EditorAsset[];
+}
 interface IframeBridgeOptions {
     /**
      * Replace the `*.prepr.io` wildcard with an exact origin list. Intended for
-     * self-hosted editors; when set, the wildcard no longer applies.
+     * self-hosted editors; when set, the wildcard no longer applies. `['*']`
+     * accepts any editor origin — see `PreprPreviewOptions.allowedEditorOrigins`.
      */
     allowedEditorOrigins?: string[];
+    /**
+     * Called when the editor selects a field and wants the preview to scroll to
+     * it. Only fires for messages from the handshaked editor origin. The bridge
+     * stays free of DOM lookups: the preview runtime supplies `scrollToField`.
+     */
+    onScrollToField?: (message: ScrollToFieldMessage) => void;
+    /**
+     * Called once the editor handshake is accepted, with the id of the content
+     * item open in the editor when the editor sends one. Lets the preview tell
+     * that item's fields apart from other items rendered on the same page
+     * (navigation, an author card, related posts).
+     */
+    onHandshake?: (handshake: EditorHandshake) => void;
+    /** The editor's reference list changed (`prepr:references`). */
+    onReferences?: (referencedIds: EditorReference[], componentIds?: string[]) => void;
+    /** The editor's asset list changed (`assets` on `prepr:references`). */
+    onAssets?: (assets: EditorAsset[]) => void;
+    /**
+     * The editor confirmed leaving the page for `href` after a
+     * `navigation_blocked` (`prepr:allowNavigation`). `href` is a non-empty
+     * string; its scheme is not checked here.
+     */
+    onAllowNavigation?: (href: string) => void;
+}
+
+interface PreviewAttrsTarget {
+    /** `_id` of the content item or component that owns the field. */
+    id: string | null | undefined;
+    /** API field name, or a dotted path below the item (`content.3`). */
+    field: string;
+    /** Locale of the rendered value, when the site knows it. */
+    locale?: string | null;
+    /** Site-side id of one entry in a list-like field (`data-prepr-entry-id`). */
+    entryId?: string | null;
+}
+interface PreviewAttrsOptions {
+    /**
+     * Whether to emit the attributes at all. Pass `true` only for preview or
+     * draft renders, so production HTML carries no edit metadata.
+     */
+    enabled: boolean;
+}
+/**
+ * Attributes that make an element click-to-edit in the Prepr visual editor,
+ * for values that carry no hidden edit link of their own: images, videos,
+ * anything rendered from a URL. Spread them onto the element that renders
+ * the field:
+ *
+ * ```tsx
+ * <figure {...previewAttrs({ id: post._id, field: 'cover_image' }, { enabled: isPreview })}>
+ * ```
+ *
+ * Returns an empty object when disabled or when there is no target or id, so
+ * it is safe to spread unconditionally.
+ */
+declare function previewAttrs(target: PreviewAttrsTarget | null | undefined, options: PreviewAttrsOptions): Record<string, string>;
+interface StegaTargetOptions {
+    /**
+     * A field next to the encoded one, in the same item or component, to target
+     * instead: a dotted path that replaces the encoded field's last segment
+     * (`products`, or `products.items.2` for one entry of it).
+     */
+    field?: string;
 }
+/**
+ * The edit target behind a text value Prepr returned with a hidden edit link,
+ * for {@link previewAttrs}. Reach for it when the field to edit carries no
+ * link of its own, such as remote content or a list of references, but a
+ * text field of the same component does: the component's title points the
+ * way to its `products`.
+ *
+ * ```tsx
+ * const products = stegaTarget(block.title, { field: 'products' });
+ * <article {...previewAttrs(products, { enabled: isPreview })}>
+ * ```
+ *
+ * Returns null for a value without an edit link (a production render, or a
+ * value Prepr does not encode). Works on the server and in the browser.
+ */
+declare function stegaTarget(value: string | null | undefined, options?: StegaTargetOptions): PreviewAttrsTarget | null;
+
+/** Values a push may write. Everything else goes through refetch. */
+type LiveScalar = string | number | boolean;
+/** A structured field value, such as an asset. */
+interface LiveObject {
+    [key: string]: LiveScalar | null | LiveObject;
+}
+/** Anything a `prepr:fieldChange` may carry. */
+type LiveValue = LiveScalar | null | LiveObject | LiveObject[];
+/** One entry of a `prepr:listChange`, in the editor's order. */
+interface LiveListEntry {
+    /** Stored id, or a temporary `tmp:` id for an entry added before save. */
+    _id: string;
+    __typename?: string;
+    /** Text entries only. */
+    body?: string;
+    format?: string | null;
+    /** A new entry's type as the editor names it (`Side by side`). */
+    typeName?: string;
+    /** A new entry's field values, shaped as the API returns them. */
+    fields?: Record<string, unknown>;
+}
+
+/**
+ * What `normalizeQuery` accepts as the query: GraphQL source text, a parsed
+ * `DocumentNode` (from `graphql-tag`, Apollo or GraphQL Code Generator), or a
+ * string-like object such as codegen's `TypedDocumentString`.
+ */
+type QueryInput = string | {
+    kind: 'Document';
+} | {
+    toString(): string;
+};
+
+/** The open item and a field path in the editor's id-based convention. */
+interface LiveEditTarget {
+    item: string;
+    field: string;
+}
+
+/**
+ * One unsaved change from the Prepr editor: the `_id` of the item (or stack
+ * entry) that owns the field, and the field's API name or a dotted path below
+ * it (`content.headline_style`, `content.3.body`).
+ */
+type LivePatch = {
+    type: 'field';
+    itemId: string;
+    field: string;
+    value: LiveValue;
+    /** Edit-link target for text that has none yet (an unsaved entry). */
+    edit?: LiveEditTarget;
+} | {
+    type: 'list';
+    itemId: string;
+    field: string;
+    entries: LiveListEntry[];
+};
+interface NormalizeQueryOptions {
+    /**
+     * The editor's unsaved changes, oldest first. Treated as hostile: malformed
+     * entries are dropped.
+     */
+    log?: unknown;
+    /** Which operation to use when the document holds more than one. */
+    operationName?: string;
+}
+/**
+ * Validate a patch log from an untrusted source (a request body, a cookie).
+ * Accepts the array or its JSON text, drops malformed entries, never throws.
+ */
+declare function parsePatchLog(raw: unknown): LivePatch[];
+/**
+ * Apply the Prepr editor's unsaved changes to a GraphQL result, so the page
+ * renders them before the editor saves. Pass the query that produced the
+ * result (`{ data }` or just `data`):
+ *
+ * ```ts
+ * const page = normalizeQuery(GetPageDocument, data, { log });
+ * ```
+ *
+ * The query maps fields to response keys, so changes land under aliases and
+ * on every place the same item appears; fields not in the query are left
+ * alone. Select `_id` on every item and component that should update.
+ * Without a log the query is not parsed and the result is returned as-is.
+ * Never throws.
+ */
+declare function normalizeQuery<T>(query: QueryInput, result: T, options?: NormalizeQueryOptions): T;
+
+/**
+ * Adds the list entry each piece of text belongs to (a dynamic content
+ * entry, a repeated component) to its hidden edit link, so the visual editor
+ * can find the entry by id without `data-prepr-entry-id` on the page. A
+ * `Text` entry's link, which names no field, also gets the entry's field
+ * path, so `data-prepr-edit-target` is not needed to name it.
+ *
+ * Needs `_id` on the entries. Returns the result itself when nothing
+ * changed. Pass the query to name fields by their API name under aliases.
+ */
+declare function annotateEditLinks<T>(result: T, query?: QueryInput, operationName?: string): T;
+
+interface HtmlLivePreviewOptions {
+    /**
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, as
+     * the toolbar's option of the same name.
+     */
+    allowedEditorOrigins?: string[];
+    /** See the toolbar's `strictMode`. */
+    strictMode?: boolean;
+}
+interface HtmlLivePreview {
+    stop(): void;
+}
+/**
+ * Live preview for server-rendered pages without a client framework (Astro,
+ * or any HTML-first site): while an editor types, the page is requested
+ * again from the server with the unsaved changes in the request body, and
+ * only the parts of the DOM that changed are updated. On save the page is
+ * requested without changes. The server applies them with `normalizeQuery`;
+ * see `readLiveLogFromRequest`.
+ *
+ * A no-op outside the Prepr editor's preview iframe.
+ */
+declare function startHtmlLivePreview(options?: HtmlLivePreviewOptions): HtmlLivePreview;
+
+/**
+ * The editor's unsaved changes carried by a live-preview re-render request
+ * (sent by `startHtmlLivePreview`), or an empty list for any other request.
+ *
+ * Accepted only from a same-origin `POST` with the live-preview header and a
+ * JSON body, so a link, a form on another site or a cacheable `GET` can never
+ * inject changes. Call it only when the site runs in preview, and mark the
+ * response uncacheable (`Cache-Control: private, no-store`) whenever it
+ * returns changes. Never throws.
+ */
+declare function readLiveLogFromRequest(request: Request): Promise<LivePatch[]>;
 
 /** Error thrown by the token helpers and the segments fetch. */
 declare class PreprError extends Error {
@@ -230,4 +512,4 @@ interface PreprMiddlewareOptions {
  */
 declare function processPreprRequest(request: Request, opts?: PreprMiddlewareOptions): PreprMiddlewareResult;
 
-export { type CookieSpec, type CreatePreprPreviewOptions, type IframeBridgeOptions, PreprError, PreprErrorCode, PreprFeatures, PreprHeaders, type PreprMiddlewareOptions, type PreprMiddlewareResult, type PreprNavigationAdapter, type PreprPreviewController, PreprPreviewOptions, PreprSegment, PreprToolbarElement, PreprToolbarProps, PreprVariant, ResolvedPreprFeatures, type ToolbarState, type ToolbarStore, VERSION, createPreprPreview, createToolbarStore, definePreprToolbar, extractAccessToken, getActiveSegmentFromHeaders, getActiveVariantFromHeaders, getPreprEnvironmentSegments, getPreprHeadersFromHeaders, getPreprUUIDFromHeaders, getToolbarPropsFromHeaders, processPreprRequest, resolveFeatures, stegaClean, validatePreprToken };
+export { type CookieSpec, type CreatePreprPreviewOptions, type HtmlLivePreview, type HtmlLivePreviewOptions, type IframeBridgeOptions, type LivePatch, type NormalizeQueryOptions, PreprError, PreprErrorCode, PreprFeatures, PreprHeaders, type PreprMiddlewareOptions, type PreprMiddlewareResult, type PreprNavigationAdapter, type PreprPreviewController, PreprPreviewOptions, PreprSegment, PreprToolbarElement, PreprToolbarProps, PreprVariant, type PreviewAttrsOptions, type PreviewAttrsTarget, type QueryInput, ResolvedPreprFeatures, type StegaTargetOptions, type ToolbarState, type ToolbarStore, VERSION, annotateEditLinks, createPreprPreview, createToolbarStore, definePreprToolbar, extractAccessToken, getActiveSegmentFromHeaders, getActiveVariantFromHeaders, getPreprEnvironmentSegments, getPreprHeadersFromHeaders, getPreprUUIDFromHeaders, getToolbarPropsFromHeaders, normalizeQuery, parsePatchLog, previewAttrs, processPreprRequest, readLiveLogFromRequest, resolveFeatures, startHtmlLivePreview, stegaClean, stegaTarget, validatePreprToken };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-e1fUWl2Y.js';
-export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-e1fUWl2Y.js';
+import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-CX422dCO.js';
+export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-CX422dCO.js';
 
 /**
  * Package version; must match package.json. Lives in its own leaf module so
  * core can import it without cycling through the barrel.
  */
-declare const VERSION = "0.4.3";
+declare const VERSION = "0.5.0-rc.10";
 
 /**
  * Resolve a `PreprFeatures` bag to plain booleans, defaulting every omitted key
@@ -137,13 +137,295 @@ declare class PreprToolbarElement extends HTMLElementBase {
 /** Idempotent, including across bundles that each try to define the element. */
 declare function definePreprToolbar(): void;
 
+/** Which field the editor asked the preview to bring on screen. */
+interface ScrollToFieldMessage {
+    field: string;
+    id?: string;
+    /** Item within a list field value: the n-th `<li>` of a rich text list. */
+    block?: number;
+    /** The entry's `data-prepr-entry-id`, preferred over `field` when present. */
+    entryId?: string;
+    /**
+     * The same field with stack entries named by id instead of position, as
+     * on entries added before save, whose position changes until then.
+     */
+    fieldById?: string;
+}
+/** A content item the open item links to, and the field that links it. */
+interface EditorReference {
+    id: string;
+    field: string;
+}
+/**
+ * An image asset used by the open item: where its field is, and the part of
+ * its CDN URL that identifies it whatever size the page renders it at.
+ */
+interface EditorAsset {
+    key: string;
+    /** Field path in the editor, as stega text carries it. */
+    field: string;
+    /** The Dynamic Content entry that holds the asset. */
+    entryId?: string;
+}
+/** What the editor told the preview when the handshake completed. */
+interface EditorHandshake {
+    /**
+     * The content item open in the editor. Absent when the editor does not
+     * send one, in which case every tagged element counts as part of it.
+     */
+    itemId?: string;
+    /**
+     * Items the open item references. Absent when the editor does not send
+     * them, in which case other items are not split into linked and unrelated.
+     */
+    referencedIds?: EditorReference[];
+    /**
+     * `_id`s of component instances inside the open item. Content tagged with
+     * one of them (`previewAttrs` on a component's image) belongs to the open
+     * item, not to another one.
+     */
+    componentIds?: string[];
+    /**
+     * The language of the editor's own interface. Absent when the editor does
+     * not send one or sends a language the toolkit has no translations for.
+     */
+    uiLocale?: Locale;
+    /**
+     * The editor asks before the preview leaves the page: navigations are
+     * stopped and reported as `navigation_blocked`, and
+     * `prepr:allowNavigation` follows one. Absent for editors that do not
+     * handle `navigation_blocked`.
+     */
+    navigationGuard?: boolean;
+    /**
+     * Image assets of the open item. Absent when the editor does not send
+     * them, in which case images are only editable where the page tags them.
+     */
+    assets?: EditorAsset[];
+}
 interface IframeBridgeOptions {
     /**
      * Replace the `*.prepr.io` wildcard with an exact origin list. Intended for
-     * self-hosted editors; when set, the wildcard no longer applies.
+     * self-hosted editors; when set, the wildcard no longer applies. `['*']`
+     * accepts any editor origin — see `PreprPreviewOptions.allowedEditorOrigins`.
      */
     allowedEditorOrigins?: string[];
+    /**
+     * Called when the editor selects a field and wants the preview to scroll to
+     * it. Only fires for messages from the handshaked editor origin. The bridge
+     * stays free of DOM lookups: the preview runtime supplies `scrollToField`.
+     */
+    onScrollToField?: (message: ScrollToFieldMessage) => void;
+    /**
+     * Called once the editor handshake is accepted, with the id of the content
+     * item open in the editor when the editor sends one. Lets the preview tell
+     * that item's fields apart from other items rendered on the same page
+     * (navigation, an author card, related posts).
+     */
+    onHandshake?: (handshake: EditorHandshake) => void;
+    /** The editor's reference list changed (`prepr:references`). */
+    onReferences?: (referencedIds: EditorReference[], componentIds?: string[]) => void;
+    /** The editor's asset list changed (`assets` on `prepr:references`). */
+    onAssets?: (assets: EditorAsset[]) => void;
+    /**
+     * The editor confirmed leaving the page for `href` after a
+     * `navigation_blocked` (`prepr:allowNavigation`). `href` is a non-empty
+     * string; its scheme is not checked here.
+     */
+    onAllowNavigation?: (href: string) => void;
+}
+
+interface PreviewAttrsTarget {
+    /** `_id` of the content item or component that owns the field. */
+    id: string | null | undefined;
+    /** API field name, or a dotted path below the item (`content.3`). */
+    field: string;
+    /** Locale of the rendered value, when the site knows it. */
+    locale?: string | null;
+    /** Site-side id of one entry in a list-like field (`data-prepr-entry-id`). */
+    entryId?: string | null;
+}
+interface PreviewAttrsOptions {
+    /**
+     * Whether to emit the attributes at all. Pass `true` only for preview or
+     * draft renders, so production HTML carries no edit metadata.
+     */
+    enabled: boolean;
+}
+/**
+ * Attributes that make an element click-to-edit in the Prepr visual editor,
+ * for values that carry no hidden edit link of their own: images, videos,
+ * anything rendered from a URL. Spread them onto the element that renders
+ * the field:
+ *
+ * ```tsx
+ * <figure {...previewAttrs({ id: post._id, field: 'cover_image' }, { enabled: isPreview })}>
+ * ```
+ *
+ * Returns an empty object when disabled or when there is no target or id, so
+ * it is safe to spread unconditionally.
+ */
+declare function previewAttrs(target: PreviewAttrsTarget | null | undefined, options: PreviewAttrsOptions): Record<string, string>;
+interface StegaTargetOptions {
+    /**
+     * A field next to the encoded one, in the same item or component, to target
+     * instead: a dotted path that replaces the encoded field's last segment
+     * (`products`, or `products.items.2` for one entry of it).
+     */
+    field?: string;
 }
+/**
+ * The edit target behind a text value Prepr returned with a hidden edit link,
+ * for {@link previewAttrs}. Reach for it when the field to edit carries no
+ * link of its own, such as remote content or a list of references, but a
+ * text field of the same component does: the component's title points the
+ * way to its `products`.
+ *
+ * ```tsx
+ * const products = stegaTarget(block.title, { field: 'products' });
+ * <article {...previewAttrs(products, { enabled: isPreview })}>
+ * ```
+ *
+ * Returns null for a value without an edit link (a production render, or a
+ * value Prepr does not encode). Works on the server and in the browser.
+ */
+declare function stegaTarget(value: string | null | undefined, options?: StegaTargetOptions): PreviewAttrsTarget | null;
+
+/** Values a push may write. Everything else goes through refetch. */
+type LiveScalar = string | number | boolean;
+/** A structured field value, such as an asset. */
+interface LiveObject {
+    [key: string]: LiveScalar | null | LiveObject;
+}
+/** Anything a `prepr:fieldChange` may carry. */
+type LiveValue = LiveScalar | null | LiveObject | LiveObject[];
+/** One entry of a `prepr:listChange`, in the editor's order. */
+interface LiveListEntry {
+    /** Stored id, or a temporary `tmp:` id for an entry added before save. */
+    _id: string;
+    __typename?: string;
+    /** Text entries only. */
+    body?: string;
+    format?: string | null;
+    /** A new entry's type as the editor names it (`Side by side`). */
+    typeName?: string;
+    /** A new entry's field values, shaped as the API returns them. */
+    fields?: Record<string, unknown>;
+}
+
+/**
+ * What `normalizeQuery` accepts as the query: GraphQL source text, a parsed
+ * `DocumentNode` (from `graphql-tag`, Apollo or GraphQL Code Generator), or a
+ * string-like object such as codegen's `TypedDocumentString`.
+ */
+type QueryInput = string | {
+    kind: 'Document';
+} | {
+    toString(): string;
+};
+
+/** The open item and a field path in the editor's id-based convention. */
+interface LiveEditTarget {
+    item: string;
+    field: string;
+}
+
+/**
+ * One unsaved change from the Prepr editor: the `_id` of the item (or stack
+ * entry) that owns the field, and the field's API name or a dotted path below
+ * it (`content.headline_style`, `content.3.body`).
+ */
+type LivePatch = {
+    type: 'field';
+    itemId: string;
+    field: string;
+    value: LiveValue;
+    /** Edit-link target for text that has none yet (an unsaved entry). */
+    edit?: LiveEditTarget;
+} | {
+    type: 'list';
+    itemId: string;
+    field: string;
+    entries: LiveListEntry[];
+};
+interface NormalizeQueryOptions {
+    /**
+     * The editor's unsaved changes, oldest first. Treated as hostile: malformed
+     * entries are dropped.
+     */
+    log?: unknown;
+    /** Which operation to use when the document holds more than one. */
+    operationName?: string;
+}
+/**
+ * Validate a patch log from an untrusted source (a request body, a cookie).
+ * Accepts the array or its JSON text, drops malformed entries, never throws.
+ */
+declare function parsePatchLog(raw: unknown): LivePatch[];
+/**
+ * Apply the Prepr editor's unsaved changes to a GraphQL result, so the page
+ * renders them before the editor saves. Pass the query that produced the
+ * result (`{ data }` or just `data`):
+ *
+ * ```ts
+ * const page = normalizeQuery(GetPageDocument, data, { log });
+ * ```
+ *
+ * The query maps fields to response keys, so changes land under aliases and
+ * on every place the same item appears; fields not in the query are left
+ * alone. Select `_id` on every item and component that should update.
+ * Without a log the query is not parsed and the result is returned as-is.
+ * Never throws.
+ */
+declare function normalizeQuery<T>(query: QueryInput, result: T, options?: NormalizeQueryOptions): T;
+
+/**
+ * Adds the list entry each piece of text belongs to (a dynamic content
+ * entry, a repeated component) to its hidden edit link, so the visual editor
+ * can find the entry by id without `data-prepr-entry-id` on the page. A
+ * `Text` entry's link, which names no field, also gets the entry's field
+ * path, so `data-prepr-edit-target` is not needed to name it.
+ *
+ * Needs `_id` on the entries. Returns the result itself when nothing
+ * changed. Pass the query to name fields by their API name under aliases.
+ */
+declare function annotateEditLinks<T>(result: T, query?: QueryInput, operationName?: string): T;
+
+interface HtmlLivePreviewOptions {
+    /**
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, as
+     * the toolbar's option of the same name.
+     */
+    allowedEditorOrigins?: string[];
+    /** See the toolbar's `strictMode`. */
+    strictMode?: boolean;
+}
+interface HtmlLivePreview {
+    stop(): void;
+}
+/**
+ * Live preview for server-rendered pages without a client framework (Astro,
+ * or any HTML-first site): while an editor types, the page is requested
+ * again from the server with the unsaved changes in the request body, and
+ * only the parts of the DOM that changed are updated. On save the page is
+ * requested without changes. The server applies them with `normalizeQuery`;
+ * see `readLiveLogFromRequest`.
+ *
+ * A no-op outside the Prepr editor's preview iframe.
+ */
+declare function startHtmlLivePreview(options?: HtmlLivePreviewOptions): HtmlLivePreview;
+
+/**
+ * The editor's unsaved changes carried by a live-preview re-render request
+ * (sent by `startHtmlLivePreview`), or an empty list for any other request.
+ *
+ * Accepted only from a same-origin `POST` with the live-preview header and a
+ * JSON body, so a link, a form on another site or a cacheable `GET` can never
+ * inject changes. Call it only when the site runs in preview, and mark the
+ * response uncacheable (`Cache-Control: private, no-store`) whenever it
+ * returns changes. Never throws.
+ */
+declare function readLiveLogFromRequest(request: Request): Promise<LivePatch[]>;
 
 /** Error thrown by the token helpers and the segments fetch. */
 declare class PreprError extends Error {
@@ -230,4 +512,4 @@ interface PreprMiddlewareOptions {
  */
 declare function processPreprRequest(request: Request, opts?: PreprMiddlewareOptions): PreprMiddlewareResult;
 
-export { type CookieSpec, type CreatePreprPreviewOptions, type IframeBridgeOptions, PreprError, PreprErrorCode, PreprFeatures, PreprHeaders, type PreprMiddlewareOptions, type PreprMiddlewareResult, type PreprNavigationAdapter, type PreprPreviewController, PreprPreviewOptions, PreprSegment, PreprToolbarElement, PreprToolbarProps, PreprVariant, ResolvedPreprFeatures, type ToolbarState, type ToolbarStore, VERSION, createPreprPreview, createToolbarStore, definePreprToolbar, extractAccessToken, getActiveSegmentFromHeaders, getActiveVariantFromHeaders, getPreprEnvironmentSegments, getPreprHeadersFromHeaders, getPreprUUIDFromHeaders, getToolbarPropsFromHeaders, processPreprRequest, resolveFeatures, stegaClean, validatePreprToken };
+export { type CookieSpec, type CreatePreprPreviewOptions, type HtmlLivePreview, type HtmlLivePreviewOptions, type IframeBridgeOptions, type LivePatch, type NormalizeQueryOptions, PreprError, PreprErrorCode, PreprFeatures, PreprHeaders, type PreprMiddlewareOptions, type PreprMiddlewareResult, type PreprNavigationAdapter, type PreprPreviewController, PreprPreviewOptions, PreprSegment, PreprToolbarElement, PreprToolbarProps, PreprVariant, type PreviewAttrsOptions, type PreviewAttrsTarget, type QueryInput, ResolvedPreprFeatures, type StegaTargetOptions, type ToolbarState, type ToolbarStore, VERSION, annotateEditLinks, createPreprPreview, createToolbarStore, definePreprToolbar, extractAccessToken, getActiveSegmentFromHeaders, getActiveVariantFromHeaders, getPreprEnvironmentSegments, getPreprHeadersFromHeaders, getPreprUUIDFromHeaders, getToolbarPropsFromHeaders, normalizeQuery, parsePatchLog, previewAttrs, processPreprRequest, readLiveLogFromRequest, resolveFeatures, startHtmlLivePreview, stegaClean, stegaTarget, validatePreprToken };