@riverbankcms/sdk 0.147.0 → 0.149.0

package/dist/_dts/content-editor/src/index.d.ts

@@ -1,20 +1,39 @@
+export { canWriteLinkedEntry } from './ui/stores/linkedEntryLeaseStore';
+export { LinkedEntryLeaseBanner } from './controller/LinkedEntryLeaseBanner';
 export * from './registry';
+export { getEditorClientId } from './controller/editorClientId';
+export { useEditLeaseActions, type EditLeaseControllerActions, type EditorLeaseConfig, } from './controller/EditLeaseController';
+export { EditLeaseDiscardedNotice, EditLeaseModal, EditorWriteGate, EditorWriteSurface, } from './controller/EditorWriteGate';
+export { planLeaseNotice, type LeaseNotice, type LeaseNoticeAction } from './controller/editLeaseNotice';
+export { VIEWING_PARTICIPATION, type EditorLeaseParticipation, } from './controller/editorLeaseParticipation';
+export { canEditorWrite, unmanagedSurfaceEditability } from './controller/editorEditability';
+export { liveDraftRole, type LiveDraftsClient, type LiveDraftsConfig, type LiveDraftRole, } from './liveDrafts/useLiveDrafts';
+export { remoteDraftValues, renderedFieldChanges, renderSourceFor, resolveRenderedValues, type RemoteDraftEntry, type RenderSource, type RemoteDraftOverlay, } from './liveDrafts/remoteDraftOverlay';
+export { activeLinkedSaveHandover, planLinkedSaveHandoverRetention, type LinkedSaveHandover, type LinkedSaveHandovers, type RenderedLinkedRevisions, } from './liveDrafts/linkedSaveHandovers';
+export { useRetentionTicks } from './liveDrafts/useRetentionTicks';
+export type { EditorEditability } from './controller/editorEditability';
 export * from './services';
 export { useDebouncedLatestSave, type DebouncedLatestSaveConfig, type DebouncedLatestSaveHandle, } from './hooks/useDebouncedLatestSave';
-export { useSimpleAutosave, useMultiAutosave } from './hooks/useSimpleAutosave';
-export { useStoreAutosave, type StoreAutosaveConfig, type AutosaveScope, } from './hooks/useStoreAutosave';
+export { useAutosaveStatus } from './hooks/useAutosaveStatus';
+export { selectAutosaveStatus } from './sync/schedulerValues';
+export { lifecycleOutcomeMessage, requireSavedDraft } from './sync/lifecycleFailure';
+export type { LifecycleFailure, LifecycleOutcome } from './ui/stores/types';
+export type { RouteWrites, RouteWriteOperation } from './controller/routeWrites';
+export { documentSince, type DocumentSince } from './sync/runLifecycle';
+export type { FlushPolicy, FlushResult } from './sync/sendPlanning';
+export { baselineRevisionOf, displayedValues, hasOutstandingRequest, isEdited, syncStateOf, valueStatus, type ValueStatus, } from './sync/valueSync';
 export { useBlockAutosave, type BlockAutosaveOptions, } from './hooks/useBlockAutosave';
-export { collectPendingLinkedEntrySaves, useLinkedEntryAutosave, type LinkedEntryAutosaveOptions, type LinkedEntrySaveResult, type PendingLinkedEntrySave, } from './hooks/useLinkedEntryAutosave';
+export { useLinkedEntryAutosave, type LinkedEntryAutosaveOptions, type LinkedEntrySaveResult, type PendingLinkedEntrySave, } from './hooks/useLinkedEntryAutosave';
 export { unsafeAsLinkedContentEntryId, unsafeAsLinkedContentTypeKey, type LinkedContentEntryId, type LinkedContentTypeKey, } from './linkedEntries/domain';
 export { useEntryActions, type EntryActionsOptions, } from './hooks/useEntryActions';
 export { useReactiveToolbar } from './hooks/useReactiveToolbar';
+export { canDiscardDraft } from './controller/deriveEditorUnpublishedState';
 export { isInvalidSaveability, selectHasInvalidBlocks, } from './hooks/invalidBlockSelectors';
 export { useHistoryShortcuts } from './hooks/useHistoryShortcuts';
 export { validateAllBlocks, type BlockValidationError, type PublishEditorTarget, } from './hooks/validateBlocksForPublish';
 export type { BlockedPublishPlan, PublishValidationDiagnostic, } from './hooks/blockedPublishPlan';
-export { EntryControllerProvider, useEntryEditorController, useEntryController, useAutosave, useEntryUiStore, } from './controller/EntryControllerProvider';
-export type { EntryDraftBlockPatch, EntryDraftCompositePatch, EntryDraftsActions, EntryDraftsSlice, } from './controller/EntryControllerProvider';
-export type { EntryEditorDriver } from './controller/driver';
+export { EntryControllerProvider, useEntryEditorController, useEntryController, } from './controller/EntryControllerProvider';
+export type { EntryDraftBlockPatch, EntryDraftCompositePatch, EntryDraftsActions, EntryDraftsSlice, EntryActions, } from './controller/EntryControllerProvider';
 export { EditableBlockProvider, useBlockData, } from './components/EditableBlockProvider';
 export { ContentFieldsForm, type ContentFieldsFormProps, } from './components/ContentFieldsForm';
 export { useUISelector } from './ui/useUISelector';
@@ -39,4 +58,4 @@ export { buildFooterBlocksUpdatePayload, createInitialFooterBlocksEditorState, f
 export { asContentEntrySnapshotSource, createContentEntriesDefinitionPlan, createPageSnapshot, createPagesDefinitionPlan, createSnapshotDefaults, getDefaultEntityLabel, mapPageRecordToSnapshot, type ContentEntriesDefinitionPlanOptions, type ContentEntryDefinitionPlan, type DefinitionServices, type PageEntrySnapshot, type PagesDefinitionPlanOptions, type SnapshotDefaults, } from './definitions/factory';
 export { canRedoHistory, canUndoHistory, createHistoryState, unsafeAsEditorBlockId, pushHistoryEntry, redoHistory, replaceHistoryPresent, undoHistory, type HistoryState, type EditorBlockId, } from './ui/editorHistory';
 export { classifyHistoryShortcut, isNativeHistoryTarget, type HistoryShortcutCommand, } from './historyShortcuts';
-export type { ContentEntryControllerOptions, ContentEntryControllerState, DraftWorkflowStatus, MetadataAutosaveConfig, MetadataKindConfig, } from './types';
+export type { EditLeaseChangeSubscription } from './hooks/useEditLease';

package/dist/_dts/content-editor/src/lib/browserStorage.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The browser's storage, or null during server rendering or when the browser blocks
+ * access (privacy settings, sandboxed frames).
+ */
+export declare function browserStorage(kind: 'local' | 'session'): Storage | null;

package/dist/_dts/content-editor/src/linkedEntries/domain.d.ts

@@ -6,3 +6,15 @@ export type LinkedContentTypeKey = string & {
 };
 export declare function unsafeAsLinkedContentEntryId(value: string): LinkedContentEntryId;
 export declare function unsafeAsLinkedContentTypeKey(value: string): LinkedContentTypeKey;
+export type LinkedEntryOpenTarget = {
+    entryId: string;
+    contentTypeKey: string;
+    contentTypeLabel: string;
+    title: string;
+    optimisticHash?: string | null;
+    content: Record<string, unknown>;
+    contentType: {
+        titleField?: string | null;
+        fields: readonly Record<string, unknown>[];
+    };
+};

package/dist/_dts/content-editor/src/linkedEntries/owner.d.ts

@@ -0,0 +1,9 @@
+import type { ValueRefresh } from '../ui/editorRefresh';
+import { type EditorCommand, type EditorHistorySnapshot, type EditorLinkedEntrySnapshot, type EditorValueKey } from '../ui/editorHistory';
+/** A reference to the document itself is another view of its existing content. */
+export declare function linkedEntrySnapshot(snapshot: EditorHistorySnapshot, entryId: string, ownerEntryId?: string): EditorLinkedEntrySnapshot | null;
+/** Sync events for the document's own entry apply to its content. */
+export declare function routeValueKey(key: EditorValueKey, ownerEntryId?: string): EditorValueKey;
+/** A server read of the document's own entry refreshes its content. */
+export declare function routeRefresh(refresh: ValueRefresh, ownerEntryId?: string): ValueRefresh;
+export declare function routeLinkedEntryCommand(command: EditorCommand, ownerEntryId?: string): EditorCommand;

package/dist/_dts/content-editor/src/liveDrafts/draftProjection.d.ts

@@ -0,0 +1,66 @@
+import { type DraftItem, type DraftTarget, type DroppedDraftItem } from '../../../realtime/src/index';
+import type { EditorHistorySnapshot } from '../ui/editorHistory';
+/** The inputs of one projection: the editor state, what was last sent, and who may write what. */
+export type DraftProjectionInput = Readonly<{
+    snapshot: EditorHistorySnapshot;
+    previouslySent: readonly DraftItem[];
+    contentOwnerEntryId?: string;
+    /** Per-item write authority (`canWriteDraftTarget`): a tab only speaks for what it may write. */
+    canWrite: (target: DraftTarget) => boolean;
+}>;
+/**
+ * Pure projection of the editor state into the items to stream.
+ *
+ * - An item this tab may not write (a linked entry whose own lease moved elsewhere)
+ *   is omitted before anything else, so it is never sent as unsaved or as saved. A
+ *   viewer treats the omission as that item being gone and drops it.
+ * - Every value the person has edited is sent as `unsaved` with what it shows.
+ * - A value that was sent as `unsaved` last time and is now pristine (saved,
+ *   discarded, or undone) is sent once as `saved` with the baseline and its server
+ *   revision, so a viewer can hand over to its own refreshed baseline without
+ *   flashing the old value. Without a known revision it is simply omitted.
+ *
+ * Diffing against what was last *sent* (not last observed) keeps saved markers
+ * correct when sends are throttled.
+ */
+export declare function projectDraftItems(input: DraftProjectionInput): DraftItem[];
+/**
+ * Why the emitter is considering a send:
+ * - `change`: the store changed; send only when the items differ from the last send.
+ * - `heartbeat`: keep viewers' unsaved items alive while anything is unsaved.
+ * - `sync`: a viewer asked for the current state; always answer.
+ */
+export type DraftPublishReason = 'change' | 'heartbeat' | 'sync';
+/** `dropped` is reported on both outcomes: an oversized item can be dropped on a skip too. */
+export type DraftPublishPlan = Readonly<{
+    kind: 'skip';
+    dropped: readonly DroppedDraftItem[];
+}> | Readonly<{
+    kind: 'send';
+    items: readonly DraftItem[];
+    dropped: readonly DroppedDraftItem[];
+}>;
+/**
+ * What the emitter sends, decided purely: project, keep what fits the message
+ * budget, then send or skip by reason. `items` is exactly what goes on the wire,
+ * so the emitter keeps it as the next `previouslySent`.
+ */
+export declare function planDraftPublish(input: DraftProjectionInput & Readonly<{
+    reason: DraftPublishReason;
+}>): DraftPublishPlan;
+/**
+ * The dropped items not already reported, so each oversized item warns once while it
+ * stays oversized, and again only if it fits and later outgrows the budget again.
+ */
+export declare function newlyDroppedDraftItems(previouslyDropped: ReadonlySet<string>, dropped: readonly DroppedDraftItem[]): readonly DroppedDraftItem[];
+/**
+ * The next sequence number for an emitter. Viewers ignore a seq that isn't newer
+ * than the last one from the same origin, and the origin outlives an editor mount,
+ * so a new mount starts from the clock rather than from zero.
+ */
+export declare function nextDraftSeq(previous: number, now: number): number;
+/**
+ * The server revision of the viewer's own baselines, keyed like the overlay. Built
+ * once per retention check rather than once per overlay entry.
+ */
+export declare function baselineRevisions(snapshot: EditorHistorySnapshot): ReadonlyMap<string, string | null>;

package/dist/_dts/content-editor/src/liveDrafts/linkedSaveHandovers.d.ts

@@ -0,0 +1,37 @@
+import type { BaselineRevision, EditorValueRecord, ValueSync } from '../../../core/src/index';
+import { type LinkedContentEntryId } from '../linkedEntries/domain';
+import type { EditorValueKey } from '../ui/editorSnapshot';
+import { type RetentionPlan, type SavedHandover } from './remoteDraftOverlay';
+/**
+ * This tab's accepted linked-entry save, handing over to the rendered data (issue 1553, D).
+ * No content is copied: the render reads the record's own baseline while the handover applies.
+ */
+export type LinkedSaveHandover = Readonly<{
+    revision: string;
+    since: number;
+    phase: SavedHandover;
+}>;
+/** Outside history, beside `remoteDrafts`; only the renderer reads it. */
+export type LinkedSaveHandovers = ReadonlyMap<LinkedContentEntryId, LinkedSaveHandover>;
+export declare const EMPTY_LINKED_SAVE_HANDOVERS: LinkedSaveHandovers;
+/** Every rendered occurrence's `optimisticHash` for each linked entry. */
+export type RenderedLinkedRevisions = ReadonlyMap<LinkedContentEntryId, readonly (string | null)[]>;
+/** A later accepted save replaces the entry's earlier handover (row H7). */
+export declare function recordLinkedSaveHandover(handovers: LinkedSaveHandovers, entryId: LinkedContentEntryId, revision: string, since: number): LinkedSaveHandovers;
+/**
+ * What an accepted save leaves behind: a linked entry's save, at a known revision, hands
+ * over to the rendered data, including a save that lands after a discard (rows H1, H5).
+ * Other values render from the store and need no handover.
+ */
+export declare function handoversAfterAcceptedSave(handovers: LinkedSaveHandovers, key: EditorValueKey, revision: BaselineRevision, at: string): LinkedSaveHandovers;
+/**
+ * The handover that applies to a record, if any. It holds only while the record is
+ * pristine at the saved revision: an edit, a refresh to another baseline or a later
+ * save ends it by derivation (rows H3, H4).
+ */
+export declare function activeLinkedSaveHandover(handovers: LinkedSaveHandovers | undefined, entryId: LinkedContentEntryId, sync: ValueSync<EditorValueRecord | null>): LinkedSaveHandover | null;
+/**
+ * Local retention (rows H1b, H2): a caught-up handover drops with no refresh; otherwise
+ * the shared `decideSavedHandover` timing applies.
+ */
+export declare function planLinkedSaveHandoverRetention(handovers: LinkedSaveHandovers, rendered: RenderedLinkedRevisions, now: number): RetentionPlan<LinkedContentEntryId, LinkedSaveHandover>;

package/dist/_dts/content-editor/src/liveDrafts/remoteDraftOverlay.d.ts

@@ -0,0 +1,113 @@
+import { type DraftItem, type DraftStateMessage, type DraftTarget } from '../../../realtime/src/index';
+import { type EditorValueRecord, type ValueSync } from '../../../core/src/index';
+import type { EditorEditability } from '../controller/editorEditability';
+/**
+ * A preview tab's read-only overlay of another tab's live drafts (issue 1545).
+ * It lives outside history, snapshots, autosave and the lease: nothing here is
+ * ever edited, saved or undone, it is only read by the renderer.
+ */
+/** No message from an unsaved item's origin for this long means its editor went away. */
+export declare const UNSAVED_DRAFT_TTL_MS = 15000;
+/** A saved item whose baseline has not caught up by then asks the host for one refresh. */
+export declare const SAVED_DRAFT_REFRESH_AFTER_MS = 10000;
+/** After the refresh, a saved item that still has not matched is dropped. */
+export declare const SAVED_DRAFT_DROP_AFTER_REFRESH_MS = 10000;
+/** Where a saved value's wait for fresh data stands: before or after its one refresh. */
+export type SavedHandover = Readonly<{
+    kind: 'awaiting-baseline';
+}> | Readonly<{
+    kind: 'refresh-requested';
+    at: number;
+}>;
+export type RemoteDraftEntry = Readonly<{
+    kind: 'unsaved';
+    item: DraftItem;
+    origin: string;
+    receivedAt: number;
+}> | Readonly<{
+    kind: 'saved';
+    item: DraftItem;
+    origin: string;
+    revision: string;
+    receivedAt: number;
+    handover: SavedHandover;
+}>;
+/** Keyed by `draftItemKey`. */
+export type RemoteDraftOverlay = ReadonlyMap<string, RemoteDraftEntry>;
+export declare const EMPTY_REMOTE_DRAFTS: RemoteDraftOverlay;
+/**
+ * Apply an accepted draft-state. It replaces everything unsaved from the same
+ * origin: an unsaved item it omits is gone (discarded or undone). Saved items
+ * stay until their own retention rule drops them, and other origins are untouched.
+ */
+export declare function applyRemoteDraftState(overlay: RemoteDraftOverlay, message: Pick<DraftStateMessage, 'origin' | 'items'>, now: number): RemoteDraftOverlay;
+export type OverlayRetentionPlan = Readonly<{
+    overlay: RemoteDraftOverlay;
+    changed: boolean;
+    /** Ask the host to refresh its server baselines once. */
+    refresh: boolean;
+}>;
+export type SavedHandoverDecision = 'keep' | 'request-refresh' | 'drop';
+/**
+ * How long a saved value keeps showing while the data it hands over to catches up
+ * (issue 1553, DP5). Shared by a viewer's saved remote drafts and this tab's own
+ * linked-entry saves; each caller decides what "caught up" means for its data.
+ * - Caught up: drop, so the fresh data shows in the same render.
+ * - Not caught up after `SAVED_DRAFT_REFRESH_AFTER_MS`: ask the host for one refresh.
+ * - Still not caught up `SAVED_DRAFT_DROP_AFTER_REFRESH_MS` after that: drop.
+ */
+export declare function decideSavedHandover(timing: Readonly<{
+    since: number;
+    phase: SavedHandover;
+}>, caughtUp: boolean, now: number): SavedHandoverDecision;
+export type RetentionDecision<E> = Readonly<{
+    kind: 'keep';
+}> | Readonly<{
+    kind: 'drop';
+}> | Readonly<{
+    kind: 'request-refresh';
+    entry: E;
+}>;
+export type RetentionPlan<K, E> = Readonly<{
+    entries: ReadonlyMap<K, E>;
+    changed: boolean;
+    /** Ask the host to refresh its server baselines once. */
+    refresh: boolean;
+}>;
+/** Applies one retention decision per entry; an unchanged map keeps its identity. */
+export declare function planRetention<K, E>(entries: ReadonlyMap<K, E>, decide: (key: K, entry: E) => RetentionDecision<E>): RetentionPlan<K, E>;
+/** A saved-handover decision as a retention decision, recording the refresh on the entry. */
+export declare function savedRetentionDecision<E>(decision: SavedHandoverDecision, withRefreshRequested: () => E): RetentionDecision<E>;
+/**
+ * Pure retention rule for the overlay.
+ * - Unsaved items expire after `UNSAVED_DRAFT_TTL_MS` without a message from their origin.
+ * - Saved items follow `decideSavedHandover`, caught up once the viewer's own baseline
+ *   for the item has the saved revision. The overlay and that baseline are read in the
+ *   same render, so the swap is atomic and nothing flashes.
+ */
+export declare function planOverlayRetention(overlay: RemoteDraftOverlay, baselineRevision: (key: string) => string | null, now: number): OverlayRetentionPlan;
+/** The remote value for a target, if another tab is streaming one. */
+export declare function remoteDraftValues(overlay: RemoteDraftOverlay | undefined, target: DraftTarget): EditorValueRecord | null;
+/**
+ * Where a tab's rendered values come from. A tab that is only viewing renders
+ * what the editing tab streams; any other tab renders its own edits.
+ */
+export type RenderSource = 'own-edits' | 'live-drafts';
+export declare function renderSourceFor(editability: EditorEditability): RenderSource;
+type LocalValues = Readonly<{
+    sync: ValueSync<EditorValueRecord | null>;
+}>;
+/**
+ * Render precedence, in one place.
+ * - `own-edits`: the tab's current value (its dirty edit, or the baseline). It never
+ *   holds a remote overlay, so none is read.
+ * - `live-drafts`: another tab's live draft, then the baseline. Local values are never
+ *   used, so edits a viewer abandoned can't outrank what the editing tab streams.
+ */
+export declare function resolveRenderedValues(source: RenderSource, local: LocalValues | null, remote: EditorValueRecord | null): EditorValueRecord | null;
+/**
+ * The top-level fields whose rendered value (after the precedence above) differs
+ * from the baseline, e.g. entry fields a template page must bind in again.
+ */
+export declare function renderedFieldChanges(source: RenderSource, local: LocalValues | null, remote: EditorValueRecord | null): Readonly<Record<string, unknown>>;
+export {};

package/dist/_dts/content-editor/src/liveDrafts/useLiveDrafts.d.ts

@@ -0,0 +1,32 @@
+import { type RealtimeEditScope } from '../../../realtime/src/index';
+import { type DraftRealtimeClient, type UseDraftChannelAuth } from '../../../realtime/src/client';
+import type { EditorEditability } from '../controller/editorEditability';
+import type { EditorUiStoreInstance } from '../ui/editorUiStore';
+/**
+ * What the host app supplies for live drafts: its own Supabase client (the
+ * preview uses a dedicated one, because token auth pins the token client-wide),
+ * how the channel authenticates, the document, and how a viewer refreshes its
+ * server baselines when a saved value has not arrived.
+ */
+export type LiveDraftsConfig = Readonly<{
+    client: DraftRealtimeClient;
+    auth: UseDraftChannelAuth;
+    siteId: string;
+    scope: RealtimeEditScope;
+    refreshBaselines?: () => void;
+}>;
+/** The structural slice of a Supabase client the drafts channel needs. */
+export type LiveDraftsClient = DraftRealtimeClient;
+export type LiveDraftRole = 'emit' | 'view' | 'off';
+/**
+ * A tab that holds the lease streams its drafts; a preview tab that is only
+ * viewing shows other tabs' drafts; any other tab (acquiring, read-only,
+ * unleased surfaces) takes no part.
+ */
+export declare function liveDraftRole(editability: EditorEditability): LiveDraftRole;
+/**
+ * Live drafts for one editor mount (issue 1545): joins the private drafts
+ * channel while the tab emits or views, streams this tab's dirty values while
+ * it holds the lease, and keeps the remote overlay while it only views.
+ */
+export declare function useLiveDrafts(uiStore: EditorUiStoreInstance, config: LiveDraftsConfig | null): void;

package/dist/_dts/content-editor/src/liveDrafts/useRetentionTicks.d.ts

@@ -0,0 +1,7 @@
+import type { EditorUiStoreInstance } from '../ui/editorUiStore';
+/**
+ * Runs a retention pass on every store change and once a second while `retain` is set.
+ * Shared by a viewer's remote-draft overlay (issue 1545) and the renderer's linked-entry
+ * save handovers (issue 1553, D); each pass decides with `decideSavedHandover`.
+ */
+export declare function useRetentionTicks(uiStore: EditorUiStoreInstance, retain: (() => void) | null): void;

package/dist/_dts/content-editor/src/primitives/shared/activePreviewField.d.ts

@@ -9,3 +9,9 @@ import type { PreviewLinkedEntryFieldBinding } from '../../../../blocks/src/syst
  */
 export declare function isLinkedSidebarField(editorPath: string, activeField: ActivePreviewField): boolean;
 export declare function isLinkedEntrySidebarField(binding: PreviewLinkedEntryFieldBinding | null | undefined, activeField: ActivePreviewField): boolean;
+/** A read-only inline field remains an opener for its scoped editor. */
+export declare function linkedEntryActivation(binding: PreviewLinkedEntryFieldBinding | undefined, canWrite: boolean, onOpen: ((binding: PreviewLinkedEntryFieldBinding) => void) | undefined): {
+    tabIndex: number | undefined;
+    onClick: () => void;
+    onFocus: () => void;
+};

package/dist/_dts/content-editor/src/primitives/shared/storeBinding.d.ts

@@ -26,5 +26,6 @@ export declare function useStoreBinding(input: StoreBindingInput): {
     value: unknown;
     setValue: (value: unknown) => void;
     version: number;
+    canWrite: boolean;
     pathInfo: PathInfo;
 };

package/dist/_dts/content-editor/src/services/contentEntryServices.d.ts

@@ -1,34 +1,111 @@
-import { type ContentTypeKey, type ApiClient, type PublishedBlockBaseline, type RouteMetadataPayload } from '../../../api/src/content-editor';
+import type { APIEndpoints } from '../../../api/src/request';
+import { type ContentTypeKey, type ApiClient, type DocumentBlockState, type RouteMetadataPayload, type PageSurfaceEditorDocument } from '../../../api/src/content-editor';
 import type { ContentEntrySnapshot } from '../../../content-model/src/index';
+import type { DocumentSaveReceipt } from '../controller/documentValueBaseline';
+type EntryResponse = NonNullable<APIEndpoints['publishContentEntry']['response']>['entry'];
 export type { ApiClient };
-export type ContentEntryServiceConfig<TResponse extends object, TSnapshot extends ContentEntrySnapshot> = {
+export type ContentEntryServiceConfig<TSnapshot extends ContentEntrySnapshot> = {
     type: ContentTypeKey;
     siteId: string;
     entryId: string;
     routeId?: string;
-    snapshotFromResponse: (response: TResponse) => TSnapshot;
-    publishedContentFromResponse?: (response: TResponse) => Record<string, unknown> | null | undefined;
-    onResponse?: (response: TResponse) => void;
+    snapshotFromResponse: (response: EntryResponse) => TSnapshot;
+    publishedContentFromResponse?: (response: EntryResponse) => Record<string, unknown> | null | undefined;
+    onResponse?: (response: EntryResponse) => void;
 };
+/**
+ * What a publish or discard wrote to the entry's content (issue 1553, WR5b): the content
+ * it wrote with its hash (the content compare-and-set token), or `unchanged` when it
+ * wrote none, in which case the editor keeps its content baseline and revision.
+ */
+export type ContentWriteResult = Readonly<{
+    kind: 'written';
+    values: Record<string, unknown>;
+    revision: string;
+}> | Readonly<{
+    kind: 'unchanged';
+}>;
+/**
+ * A lifecycle response's writes: the route's draft timestamp (the metadata
+ * compare-and-set token; absent when the response carries none, in which case the
+ * editor keeps its own) and what it did to the content.
+ */
+export type LifecycleWrites = Readonly<{
+    metadataRevision?: string | null;
+    content: ContentWriteResult;
+}>;
 export type PublishEntryResult<TSnapshot extends ContentEntrySnapshot> = Readonly<{
     snapshot: TSnapshot;
     publishedContent?: Record<string, unknown> | null;
-    publishedBlocks?: readonly PublishedBlockBaseline[];
+    blockState: DocumentBlockState;
+    writes: LifecycleWrites;
+}>;
+/** Every lifecycle result accounts for all document block collections, including empty ones. */
+export type DiscardEntryResult<TSnapshot extends ContentEntrySnapshot> = Readonly<{
+    snapshot: TSnapshot;
+    writes: LifecycleWrites;
+    blockState: DocumentBlockState;
+}>;
+/** An accepted atomic content write may include its complete publication receipt. */
+export type ContentSavePublication = Readonly<{
+    kind: 'published';
+    result: NonNullable<APIEndpoints['publishPageSurface']['response']>;
+}>;
+export type ContentSaveResult = DocumentSaveReceipt<string> & Readonly<{
+    publication?: ContentSavePublication;
 }>;
-type ContentEditorDraftServices<TSnapshot extends ContentEntrySnapshot = ContentEntrySnapshot, TMetadataPayload extends Record<string, unknown> = RouteMetadataPayload> = Readonly<{
-    saveContent: (content: Record<string, unknown>) => Promise<Record<string, unknown>>;
-    saveMetadata: (payload: TMetadataPayload) => Promise<Record<string, unknown>>;
+type ContentEditorDraftServices<TMetadataPayload extends Record<string, unknown> = RouteMetadataPayload> = Readonly<{
+    saveContent: (content: Record<string, unknown>, optimisticHash: string) => Promise<ContentSaveResult>;
+    saveMetadata: (payload: TMetadataPayload, expectedDraftUpdatedAt: string | null) => Promise<DocumentSaveReceipt>;
 }>;
-export type ContentEditorServices<TSnapshot extends ContentEntrySnapshot = ContentEntrySnapshot, TMetadataPayload extends Record<string, unknown> = RouteMetadataPayload> = ContentEditorDraftServices<TSnapshot, TMetadataPayload> & (Readonly<{
-    kind: 'entryLifecycle';
-    publishDetailed: (payload: unknown) => Promise<PublishEntryResult<TSnapshot>>;
-    publish: (payload: unknown) => Promise<TSnapshot>;
-    discardDraft: () => Promise<TSnapshot>;
+export type PublishLifecycleResult<TSnapshot extends ContentEntrySnapshot> = (PublishEntryResult<TSnapshot> & Readonly<{
+    kind: 'serverSnapshot';
+}>) | Readonly<{
+    kind: 'pageSurface';
+    publication: NonNullable<APIEndpoints['publishPageSurface']['response']>;
+}>;
+export type DiscardLifecycleResult<TSnapshot extends ContentEntrySnapshot> = (DiscardEntryResult<TSnapshot> & Readonly<{
+    kind: 'serverSnapshot';
+}>) | Readonly<{
+    kind: 'serverDocument';
+    document: PageSurfaceEditorDocument;
+    blockState: DocumentBlockState;
+}> | Readonly<{
+    kind: 'unchanged';
+}>;
+export type DiscardDraftInput = Readonly<{
+    contentRevision: string | null;
+}>;
+export type EditorDeletion = Readonly<{
+    kind: 'deletable';
     deleteEntry: () => Promise<void>;
 }> | Readonly<{
-    kind: 'pageSurfaceDraft';
-}>);
-export type EntryLifecycleContentEditorServices<TSnapshot extends ContentEntrySnapshot = ContentEntrySnapshot, TMetadataPayload extends Record<string, unknown> = RouteMetadataPayload> = Extract<ContentEditorServices<TSnapshot, TMetadataPayload>, {
-    kind: 'entryLifecycle';
+    kind: 'deletedWithOwner';
+}>;
+export type ContentEditorServices<TSnapshot extends ContentEntrySnapshot = ContentEntrySnapshot, TMetadataPayload extends Record<string, unknown> = RouteMetadataPayload> = ContentEditorDraftServices<TMetadataPayload> & Readonly<{
+    publish: () => Promise<PublishLifecycleResult<TSnapshot>>;
+    discardDraft: (input: DiscardDraftInput) => Promise<DiscardLifecycleResult<TSnapshot>>;
+    deletion: EditorDeletion;
+}>;
+export type ContentEntryEditorServices<TSnapshot extends ContentEntrySnapshot = ContentEntrySnapshot, TMetadataPayload extends Record<string, unknown> = RouteMetadataPayload> = ContentEditorServices<TSnapshot, TMetadataPayload> & Readonly<{
+    deletion: Extract<EditorDeletion, {
+        kind: 'deletable';
+    }>;
+}>;
+export type PageSurfaceEditorServices = ContentEditorServices & Readonly<{
+    deletion: Extract<EditorDeletion, {
+        kind: 'deletedWithOwner';
+    }>;
 }>;
-export declare function createContentEntryServices<TResponse extends object, TMetadataPayload extends Record<string, unknown>, TPublishPayload, TSnapshot extends ContentEntrySnapshot>(apiClient: ApiClient, config: ContentEntryServiceConfig<TResponse, TSnapshot>): EntryLifecycleContentEditorServices<TSnapshot, TMetadataPayload>;
+export declare function createContentEntryServices<TMetadataPayload extends Record<string, unknown>, TSnapshot extends ContentEntrySnapshot>(apiClient: ApiClient, config: ContentEntryServiceConfig<TSnapshot>): ContentEntryEditorServices<TSnapshot, TMetadataPayload>;
+/** Both entry and surface commands return this same persistence evidence. */
+export declare function savedContentReceipt(document: Pick<PageSurfaceEditorDocument, 'draftContent' | 'optimisticHash' | 'publishedContent'>): DocumentSaveReceipt<string>;
+/** Normalize the authoritative route response once, before shared save handling. */
+export declare function savedRouteReceipt(route: Readonly<{
+    draftTitle: string | null;
+    draftSlug: string | null;
+    draftMetaTitle?: string | null;
+    draftMetaDescription?: string | null;
+    ogImageId?: string | null;
+    draftUpdatedAt?: string | null;
+}>): DocumentSaveReceipt;

package/dist/_dts/content-editor/src/services/editorApiClient.d.ts

@@ -0,0 +1,13 @@
+import type { ApiClient } from '../../../api/src/request';
+import type { EditorEditability } from '../controller/editorEditability';
+declare const editorClientCapability: unique symbol;
+/** A transport whose managed writes are checked and decorated by the editor. */
+export type EditorApiClient = ApiClient & Readonly<{
+    [editorClientCapability]: true;
+}>;
+export type EditorApiClientFactory = (getClientId: () => string, getEditability: () => EditorEditability, onLeaseLost?: () => void) => EditorApiClient;
+/** Bind the transport once; each editor supplies its own current lease state. */
+export declare function createEditorApiClientFactory(client: ApiClient): EditorApiClientFactory;
+/** Adds the document identity to editor writes so realtime can suppress self echoes. */
+export declare function createEditorApiClient(client: ApiClient, getClientId: () => string, getEditability: () => EditorEditability, onLeaseLost?: () => void): EditorApiClient;
+export {};

package/dist/_dts/content-editor/src/services/index.d.ts

@@ -1 +1,3 @@
 export * from './contentEntryServices';
+export * from './pageSurfaceEditorServices';
+export { createEditorApiClient, createEditorApiClientFactory, type EditorApiClient, type EditorApiClientFactory } from './editorApiClient';

package/dist/_dts/content-editor/src/services/pageSurfaceEditorServices.d.ts

@@ -0,0 +1,23 @@
+import type { ApiClient } from '../../../api/src/request';
+import { type PageSurfaceEditorServices } from './contentEntryServices';
+export type PageSurfaceMetadataBaseline = Readonly<{
+    draftTitle: string;
+    draftPath: string;
+}>;
+export type PageSurfaceEditorServicesDeps = Readonly<{
+    apiClient: ApiClient;
+}>;
+/**
+ * Where a content save goes. Every editor saves a draft, except the event
+ * Content tab, whose save publishes an external event's card straight away
+ * (the server decides). Its lease uses that endpoint too, so the words have
+ * one write path from the tab however the save is reached.
+ */
+export type PageSurfaceContentWriter = 'draft' | 'eventContentTab';
+export declare function createPageSurfaceEditorServices(input: Readonly<{
+    siteId: string;
+    pageSurfaceId: string;
+    route: PageSurfaceMetadataBaseline;
+    /** Default `draft`. */
+    contentWriter?: PageSurfaceContentWriter;
+}>, deps: PageSurfaceEditorServicesDeps): PageSurfaceEditorServices;

package/dist/_dts/content-editor/src/sync/flushValues.d.ts

@@ -0,0 +1,13 @@
+import type { StoreApi } from 'zustand';
+import type { EditorUiState } from '../ui/editorUiStore';
+import type { EditorValueKey } from '../ui/editorSnapshot';
+import { type FlushPlan, type FlushPolicy, type FlushResult, type LifecycleDrain } from './sendPlanning';
+export type FlushOptions = Readonly<{
+    keys?: readonly EditorValueKey[];
+    timeoutMs?: number;
+}>;
+type FlushStore = Pick<StoreApi<EditorUiState>, 'getState' | 'subscribe'>;
+export declare function selectPublishFlushPlan(state: EditorUiState): FlushPlan;
+/** A finite checkpoint. Only its owning lifecycle passes the exact held-state reference as drain authority. */
+export declare function flushValues(store: FlushStore, policy: FlushPolicy, options?: FlushOptions, drain?: LifecycleDrain): Promise<FlushResult>;
+export {};

package/dist/_dts/content-editor/src/sync/lifecycleFailure.d.ts

@@ -0,0 +1,51 @@
+import type { EditorValueRecord, ValueSync } from '../../../core/src/index';
+import type { EditorValueKey } from '../ui/editorSnapshot';
+import type { LifecycleFailure, LifecycleOperation, LifecycleOutcome, LifecycleStatus } from '../ui/stores/types';
+import { type FlushResult, type SchedulerValue } from './sendPlanning';
+/**
+ * Whether a recorded lifecycle failure still holds (issue 1553, rows B1–B7). One
+ * condition drives both the error banner and the autosave status, so they can't disagree
+ * about whether a failure has resolved. A failure whose condition has ended is inert: it
+ * stays in the store until the next operation overwrites it, but it no longer counts.
+ */
+export declare const SAVE_DRAFT_FAILED = "Failed to save draft \u2014 some changes may not be saved.";
+export declare const PUBLISH_SAVE_FAILED = "Cannot publish: failed to save draft changes.";
+export type FailureFacts = Readonly<{
+    /** Loaded only when a failure's condition reads the values. */
+    values: () => readonly SchedulerValue[];
+    /** How many saves the store has accepted; a `server` failure holds until this moves. */
+    acceptedSaves: number;
+    /** The current publish validation message while validation blocks publishing, else null. */
+    publishBlockedMessage: string | null;
+}>;
+export type ActiveFailure = Readonly<{
+    operation: LifecycleOperation;
+    failure: LifecycleFailure;
+}>;
+export declare function activeFailure(lifecycle: LifecycleStatus, facts: FailureFacts): ActiveFailure | null;
+/**
+ * The copy for a failure, unchanged from the messages each operation stored before.
+ * `invalid-blocks` shows the current publish validation message.
+ */
+export declare function lifecycleFailureMessage(operation: LifecycleOperation, failure: LifecycleFailure, publishBlockedMessage: string | null): string | null;
+/**
+ * The error banner: the active lifecycle failure's message, else the document's own save
+ * failure (metadata and content), which clears once no such value is failed.
+ */
+export declare function bannerMessage(lifecycle: LifecycleStatus, facts: FailureFacts): string | null;
+/**
+ * A flush that didn't reach `ready`, as the operation's failure: the failed values by the
+ * requests that failed, or the values that couldn't be sent.
+ */
+export declare function flushFailure(result: FlushResult, syncOf: (key: EditorValueKey) => ValueSync<EditorValueRecord | null> | undefined): LifecycleFailure | null;
+/**
+ * A refused operation's copy, for a caller's own dialog or toast (the banner shows the
+ * same copy); null when the operation didn't fail.
+ */
+export declare function lifecycleOutcomeMessage(operation: LifecycleOperation, outcome: LifecycleOutcome): string | null;
+/**
+ * For a caller that goes on only once Save draft has saved everything (a workflow step,
+ * leaving the page): a refusal becomes an Error with the banner's copy, for that
+ * caller's own error handling.
+ */
+export declare function requireSavedDraft(outcome: LifecycleOutcome): void;