@riverbankcms/sdk 0.147.0 → 0.148.0

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;

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

@@ -0,0 +1,64 @@
+import type { EditorBlockId, EditorBlockValues, EditorValueRecord } from '../../../core/src/index';
+import type { EditorUiState, EditorUiStoreInstance } from '../ui/editorUiStore';
+import type { HeldOperation, LifecycleFailure, LifecycleOperation, LifecycleOutcome } from '../ui/stores/types';
+import { type FlushPolicy, type LifecycleDrain } from './sendPlanning';
+import { type OwnWriteSince } from './valueSync';
+/**
+ * The one shell for the document's lifecycle operations (issue 1553, B-ownership). Save
+ * draft and restore replay run under the lifecycle status; publish, schedule, cancel,
+ * discard draft and delete also hold the document while their request is out, because
+ * they write the same route or draft that autosave does. What each held operation
+ * settles first, and what its response's edits are measured from, is data
+ * (`LIFECYCLE_RECONCILIATION`), not branches here.
+ */
+export declare const DONE: LifecycleOutcome;
+export declare const failed: (failure: LifecycleFailure) => LifecycleOutcome;
+/**
+ * What a held operation settles before its request, and what the person's edits are
+ * measured from when its response comes back (the "Reconciliation per operation" table).
+ * - `settle`: a flush policy. The hold starts immediately. Sending policies drain a
+ *   frozen checkpoint under that hold; later typing waits. `grant-wait` sends nothing
+ *   and waits only for requests already out before the operation writes.
+ * - `since`: `baseline` keeps every edit (publish, schedule, cancel); `displayed` makes
+ *   the edits present when the person confirmed part of what the operation throws away
+ *   (discard draft, rows X1–X4). Delete applies nothing: on success the editor goes.
+ */
+type LifecycleReconciliation = Readonly<{
+    settle: FlushPolicy;
+    since: 'baseline' | 'displayed';
+}>;
+export declare const LIFECYCLE_RECONCILIATION: Readonly<Record<HeldOperation, LifecycleReconciliation>>;
+/** What the document's values were when the hold started, for the response's rebase. */
+export type DocumentSince = Readonly<{
+    metadata: OwnWriteSince<EditorValueRecord | null>;
+    content: OwnWriteSince<EditorValueRecord | null>;
+    blocks: ReadonlyMap<EditorBlockId, OwnWriteSince<EditorBlockValues | null>>;
+}>;
+export declare function documentSince(state: EditorUiState, kind: LifecycleReconciliation['since']): DocumentSince;
+/**
+ * Runs a document lifecycle operation under the store's lifecycle status: running while
+ * it's under way, then idle or failed with its typed failure, which the banner and the
+ * status derive from. A rejected request is the operation's `server` failure; callers
+ * get the outcome rather than a throw.
+ */
+export declare function runLifecycle(uiStore: EditorUiStoreInstance, operation: LifecycleOperation, action: () => Promise<LifecycleOutcome>): Promise<LifecycleOutcome>;
+/** Waits until the values are settled under `policy`; a refusal is the operation's failure. */
+export declare function flushBefore(uiStore: EditorUiStoreInstance, policy: FlushPolicy, drain?: LifecycleDrain): Promise<LifecycleOutcome | null>;
+export type HeldLifecycle = Readonly<{
+    operation: HeldOperation;
+    /** A refusal before anything settles or is held (publish's validation), else null. */
+    precheck?: () => LifecycleOutcome | null;
+    /**
+     * The request, and applying its response (as own writes rebased against `since`).
+     * The document is held throughout; the hold ends when this settles.
+     */
+    write: (since: DocumentSince) => Promise<LifecycleOutcome>;
+}>;
+/**
+ * Runs a held operation: its precheck, what it settles first, then its request with the
+ * document held. Edits typed during the hold aren't sent; once the hold ends they're
+ * rebased on the response and autosave sends them against the new revision (rows R2, X3).
+ * On failure nothing was applied, so they send as usual (row X5).
+ */
+export declare function runHeldLifecycle(uiStore: EditorUiStoreInstance, lifecycle: HeldLifecycle): Promise<LifecycleOutcome>;
+export {};

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

@@ -0,0 +1,27 @@
+import type { EditorUiState } from '../ui/editorUiStore';
+import type { AutosaveStatus, AutosaveType } from '../ui/stores/types';
+import { type ScheduledValue, type SchedulerValue, type LifecycleDrain } from './sendPlanning';
+import { type FailureFacts } from './lifecycleFailure';
+/**
+ * Loads the planners' inputs from the editor store: every value with the scheduler that
+ * saves it. The document's own linked entry is its content, so it is listed once.
+ */
+export declare function scheduledValues(state: EditorUiState): readonly ScheduledValue[];
+/**
+ * Every value with whether this tab may send it now. A document value (metadata, content,
+ * a block) isn't writable while a lifecycle operation holds the document: the operation
+ * writes the same route or draft, so edits typed meanwhile wait and send once it ends
+ * (rows R2, X3). Linked entries have their own revisions and aren't held.
+ */
+export declare function schedulerValues(state: EditorUiState, drain?: LifecycleDrain): readonly SchedulerValue[];
+/**
+ * The derived autosave status, for one scheduler or the whole document. The document
+ * lifecycle counts toward metadata and the whole.
+ */
+export declare function selectAutosaveStatus(state: EditorUiState, scheduler?: AutosaveType): AutosaveStatus;
+/**
+ * The error banner (rows B1–B7), from the same active failure as the status.
+ * `publishBlockedMessage` is the current publish validation message while it blocks.
+ */
+export declare function selectBannerMessage(state: EditorUiState, publishBlockedMessage: string | null): string | null;
+export declare function failureFacts(state: EditorUiState, publishBlockedMessage: string | null): FailureFacts;

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

@@ -0,0 +1,104 @@
+import type { EditorValueRecord, SendId, ValueSync } from '../../../core/src/index';
+import type { EditorValueKey } from '../ui/editorSnapshot';
+import type { AutosaveStatus, AutosaveType, LifecycleStatus } from '../ui/stores/types';
+import { type SendMode } from './valueSync';
+import type { ActiveFailure } from './lifecycleFailure';
+/**
+ * Pure planners over the editor's values (issue 1553): what autosave sends, when a
+ * flush is done, and the status the status bars show. The store loads the inputs
+ * (`schedulerValues`); the hooks and `flushValues` perform the effects.
+ */
+/** One value as the planners see it. */
+export type ScheduledValue = Readonly<{
+    key: EditorValueKey;
+    scheduler: AutosaveType;
+    sync: ValueSync<EditorValueRecord | null>;
+}>;
+/** A value plus whether this tab may send it now. */
+export type SchedulerValue = ScheduledValue & Readonly<{
+    /** The tab holds write authority for it (`canWriteDraftTarget`). */
+    writable: boolean;
+    /** Its values may be sent: blocks pass validation, metadata has a title. */
+    saveable: boolean;
+}>;
+/** How a flush treats a failed value: Save draft retries it, publish refuses, a grant only waits. */
+export type FlushPolicy = 'save-draft' | 'publish' | 'grant-wait';
+export type LifecycleDrain = Extract<LifecycleStatus, {
+    kind: 'holding';
+}>;
+export type FlushCheckpoint = Readonly<{
+    key: EditorValueKey;
+    values: EditorValueRecord | null;
+    saveable: boolean;
+    drain?: LifecycleDrain;
+}>;
+export type SendAcknowledgement = Readonly<{
+    key: EditorValueKey;
+    values: EditorValueRecord | null;
+    kind: 'accepted' | 'failed' | 'blocked';
+}>;
+export type FlushRequest = Readonly<{
+    scheduler: AutosaveType;
+    keys: readonly EditorValueKey[];
+    checkpoints?: readonly FlushCheckpoint[];
+    signal?: AbortSignal;
+}>;
+export type FlushPlan = Readonly<{
+    kind: 'ready';
+}> | Readonly<{
+    kind: 'wait';
+}> | Readonly<{
+    kind: 'send';
+    requests: readonly FlushRequest[];
+}> | Readonly<{
+    kind: 'failed';
+    keys: readonly EditorValueKey[];
+}> | Readonly<{
+    kind: 'blocked';
+    keys: readonly EditorValueKey[];
+}>;
+/** How a flush finished. */
+export type FlushResult = Exclude<FlushPlan, Readonly<{
+    kind: 'wait' | 'send';
+}>>;
+/** The values that may send now: edited, writable, saveable and allowed by `canSend`. */
+export declare function planSends(values: readonly SchedulerValue[], mode: SendMode): readonly SchedulerValue[];
+/**
+ * What an autosave trigger watches: each sendable value with its displayed values and
+ * request. It changes on an edit, when a request settles with newer edits, and when a
+ * value becomes writable again (rows S2, S5, D2).
+ */
+export type SendSignature = readonly unknown[];
+export declare function sendSignature(sendable: readonly SchedulerValue[]): SendSignature;
+export declare function sameSignature(left: SendSignature, right: SendSignature): boolean;
+export declare function valueKeyId(key: EditorValueKey): string;
+/**
+ * Whether "saved before X" holds yet. Outstanding requests (in flight or abandoned)
+ * are waited for; sendable values are sent; what can never send ends the flush.
+ * `retrying` holds the failures this flush may send again (Save draft, row S3b).
+ */
+export declare function planFlush(values: readonly SchedulerValue[], policy: FlushPolicy, retrying?: ReadonlySet<SendId>): FlushPlan;
+/** The failures a flush sends again: those it was asked to retry. */
+export declare function retryableFailures(values: readonly ScheduledValue[]): ReadonlySet<SendId>;
+export type AutosaveStatusInput = Readonly<{
+    syncs: readonly ValueSync<EditorValueRecord | null>[];
+    lifecycle: LifecycleStatus;
+    /** The lifecycle failure that still holds (`activeFailure`), the same one the banner reads. */
+    failure: ActiveFailure | null;
+    lastSavedAt: string | null;
+}>;
+/**
+ * The autosave status the status bars show, derived from the values' states plus the
+ * document lifecycle. A failure outranks saving, as the per-scheduler statuses it
+ * replaced did. Of the lifecycle failures only a refused request (`server`) is an error
+ * here: failed values already count through their own states, and blocked or invalid
+ * values are the banner's alone (rows B4, B5).
+ */
+export declare function deriveAutosaveStatus(input: AutosaveStatusInput): AutosaveStatus;
+/** An operation is under way: settling what it needs first, or holding while its request is out. */
+export declare function isLifecycleRunning(lifecycle: LifecycleStatus): boolean;
+/**
+ * The message of the first value whose save failed, which the error banner shows. It's
+ * null once no value is failed (a retry succeeded, the edit went back, or was discarded).
+ */
+export declare function saveFailureMessage(values: readonly ScheduledValue[]): string | null;

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

@@ -0,0 +1,114 @@
+import type { BaselineRevision, EditorValueRecord, SaveFailure, SendId, ValueBaseline, ValueSync } from '../../../core/src/index';
+export { displayedValues, syncStateOf, valueStatus, type ValueStatus } from '../../../core/src/index';
+/**
+ * The one sync model for editor values (issue 1553). Metadata, content, blocks and
+ * linked entries all move through `applyValueSyncEvent`; every rule here is a row in
+ * the plan's sequence tables and in `valueSync.test.ts`. Pure: the clock and send ids
+ * come in as event data.
+ */
+export type SyncValues = EditorValueRecord | null;
+/** Values at the operation boundary, and the server baseline they were based on. */
+export type OwnWriteSince<V extends SyncValues> = Readonly<{
+    values: V;
+    basis: BaselineRevision;
+}>;
+/**
+ * How a refresh (a server read) treats a value the person has edited:
+ * - keep-local: an ordinary refresh; the edits stay.
+ * - take-back: the tab regained the lease; the edits survive only if nobody else changed the value.
+ * - replace: the server draft was discarded; the edits go.
+ *
+ * A response to this tab's own write isn't a read: it's the `own-write` event, rebased
+ * rather than refreshed (`rebaseOnOwnWrite`).
+ */
+export type RefreshPolicy = 'keep-local' | 'take-back' | 'replace';
+export type ValueSyncEvent<V extends SyncValues> = Readonly<{
+    kind: 'edited';
+    values: V;
+}> | Readonly<{
+    kind: 'send-started';
+    id: SendId;
+    checkpoint?: V;
+}> | Readonly<{
+    kind: 'send-succeeded';
+    id: SendId;
+    values: V;
+    revision: BaselineRevision;
+    at: string;
+    published?: Readonly<{
+        kind: 'known';
+        values: V;
+    } | {
+        kind: 'unknown';
+    }>;
+}> | Readonly<{
+    kind: 'send-failed';
+    id: SendId;
+    failure: SaveFailure;
+}> | Readonly<{
+    kind: 'discarded';
+}> | Readonly<{
+    kind: 'refreshed';
+    baseline: ValueBaseline<V>;
+    policy: RefreshPolicy;
+}>
+/** This tab's own write returned `baseline`; `since` is what the person's edits are measured from. */
+ | Readonly<{
+    kind: 'own-write';
+    baseline: ValueBaseline<V>;
+    since: OwnWriteSince<V>;
+}>;
+/** `accepted` records `lastSavedAt`; `discarded` asks for the "edited in another tab" notice. */
+export type ValueSyncOutcome = Readonly<{
+    kind: 'none';
+}> | Readonly<{
+    kind: 'accepted';
+    at: string;
+}> | Readonly<{
+    kind: 'discarded';
+}>;
+export type ValueSyncTransition<V extends SyncValues> = Readonly<{
+    sync: ValueSync<V>;
+    outcome: ValueSyncOutcome;
+}>;
+/** `background` sends leave a failure alone until its values change; `explicit` retries it. */
+export type SendMode = 'background' | 'explicit';
+export declare function applyValueSyncEvent<V extends SyncValues>(sync: ValueSync<V>, event: ValueSyncEvent<V>): ValueSyncTransition<V>;
+/** Send ids are unique per store; the store's closure owns the only allocator. */
+export declare function createSendIdAllocator(): () => SendId;
+export declare function isEdited<V extends SyncValues>(sync: ValueSync<V>): boolean;
+/** A request is in flight or abandoned: flushes and grants wait for it to settle. */
+export declare function hasOutstandingRequest<V extends SyncValues>(sync: ValueSync<V>): boolean;
+/** The baseline revision as the wire carries it; `undefined` until the editor receives one. */
+export declare function revisionValue(revision: BaselineRevision): string | null | undefined;
+export declare function baselineRevisionOf<V extends SyncValues>(sync: ValueSync<V>): string | null | undefined;
+/** An optional wire revision (`undefined` means none was received) as a `BaselineRevision`. */
+export declare function revisionFromWire(value: string | null | undefined): BaselineRevision;
+/**
+ * Whether a send may start. A failure waits for new values in the background, so a
+ * rejected save isn't retried in a loop; an explicit Save draft retries it.
+ */
+export declare function canSend<V extends SyncValues>(sync: ValueSync<V>, mode: SendMode): boolean;
+/**
+ * The same server baseline, for take-back. Two revisions decide it when both are
+ * present; otherwise the revisions (possibly missing) and the values must both match.
+ */
+export declare function sameServerBaseline<V extends SyncValues>(left: ValueBaseline<V>, right: ValueBaseline<V>): boolean;
+export declare function valueSyncEqual<V extends SyncValues>(left: ValueSync<V>, right: ValueSync<V>): boolean;
+/**
+ * Undo and redo restore what the person sees, never sync state: the target's displayed
+ * values become an edit over the present baseline and request (row U1, U2).
+ */
+export declare function restoreDisplayedValues<V extends SyncValues>(present: ValueSync<V>, target: ValueSync<V>): ValueSync<V>;
+/** A record brought back from history: its request is long gone (row U3). */
+export declare function withIdleRequest<V extends SyncValues>(sync: ValueSync<V>): ValueSync<V>;
+/**
+ * A response to this tab's own write (publish, schedule, cancel, discard). The displayed
+ * value keeps changes since the operation's snapshot: an edit is any
+ * top-level key whose presence or value differs between `since` and the local values, so
+ * a removed key stays removed and a key set to `null` counts. Nested values are whole
+ * fields (no deep merge), and where both sides changed a key the person's edit wins.
+ * Keys the person didn't touch take the server's value, including its removals. The
+ * request is kept: one based on the old revision isn't accepted over the new one (R6).
+ */
+export declare function rebaseOnOwnWrite<V extends SyncValues>(sync: ValueSync<V>, server: ValueBaseline<V>, since: OwnWriteSince<V>): ValueSync<V>;

package/dist/_dts/content-editor/src/ui/blockCollection.d.ts

@@ -0,0 +1,8 @@
+import { type EditorBlockCollectionOwner, type EditorBlockCollectionReadBaseline } from '../../../core/src/index';
+import { type DraftBlockRefresh, type EditorBlockItem, type EditorHistorySnapshot } from './editorSnapshot';
+/** A collection read enters through one boundary; a held lifecycle supplies its own result. */
+export declare function mountBlockCollection(snapshot: EditorHistorySnapshot, owner: EditorBlockCollectionOwner, blocks: readonly EditorBlockItem[], seeds: readonly DraftBlockRefresh[], held: boolean, reads?: readonly EditorBlockCollectionReadBaseline[]): EditorHistorySnapshot;
+export declare function unmountBlockCollection(snapshot: EditorHistorySnapshot, owner: EditorBlockCollectionOwner): EditorHistorySnapshot;
+/** Query facts are not history edits; a held write will supply the authoritative receipt. */
+export declare function refreshCollectionReadBaselines(snapshot: EditorHistorySnapshot, reads: readonly EditorBlockCollectionReadBaseline[], held?: boolean): EditorHistorySnapshot;
+export declare function hasUnpublishedCollectionChanges(snapshot: EditorHistorySnapshot): boolean;

package/dist/_dts/content-editor/src/ui/documentLifecycle.d.ts

@@ -0,0 +1,18 @@
+import type { DocumentBlockState } from '../../../api/src/content-editor';
+import { type BlockFieldExtensions } from '../../../editor-blocks/src/block-editor/blockDraftBaselineSeed';
+import type { DocumentSince } from '../sync/runLifecycle';
+import { type OwnWrite, type PublishSuccessRefresh } from './editorRefresh';
+import { type EditorHistorySnapshot } from './editorSnapshot';
+/** A complete document operation always reconciles its block collections too. */
+export type DocumentLifecycleResult = Readonly<{
+    blockState: DocumentBlockState;
+    since: DocumentSince;
+}> & (Readonly<{
+    operation: 'publish';
+    values: PublishSuccessRefresh;
+}> | Readonly<{
+    operation: 'discard';
+    values: readonly OwnWrite[];
+}>);
+/** Apply one receipt atomically: entry values, block values and block membership. */
+export declare function documentLifecycleSnapshot(snapshot: EditorHistorySnapshot, result: DocumentLifecycleResult, extensions?: BlockFieldExtensions | null): EditorHistorySnapshot;

package/dist/_dts/content-editor/src/ui/editorLeaseUiState.d.ts

@@ -0,0 +1,7 @@
+import type { EditorEditability } from '../controller/editorEditability';
+export type EditorLeaseUiState = {
+    editability: EditorEditability;
+    setEditability: (editability: EditorEditability) => void;
+    leaseDiscardedChanges: boolean;
+    setLeaseDiscardedChanges: (discarded: boolean) => void;
+};