@riverbankcms/sdk 0.146.0 → 0.148.0

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

@@ -1,5 +1,9 @@
-import { unsafeAsEditorBlockId, unsafeAsEditorBlockValues, unsafeAsEditorContentValues, unsafeAsEditorEntryId, unsafeAsEditorMetadataValues, unsafeAsEditorPageId, unsafeAsEditorSiteId, type EditorBlockBaselineInput, type EditorBlockId, type EditorBlockPublishedBaselineInput, type EditorDraftBlockBaselineUpdateMetaInput, type EditorDraftBlockInitMetaInput, type EditorBlockValues, type EditorContentValues, type EditorEntryId, type EditorMetadataValues, type EditorPageId, type EditorPersistedBlock, type BlockContentIdentity, type EditorSiteId, type EditorStructuralCommand, type EditorStructuralDraftSnapshot, type EditorSyncState, type EditorValueRecord } from '../../../core/src/index';
+import { type EditorBlockVersions } from '../../../core/src/index';
+import { type EditorBlockCollectionOwner, type EditorBlockCollectionReadBaseline, unsafeAsEditorBlockId, unsafeAsEditorBlockValues, unsafeAsEditorContentValues, unsafeAsEditorEntryId, unsafeAsEditorMetadataValues, unsafeAsEditorPageId, unsafeAsEditorSiteId, type EditorBlockBaselineInput, type EditorBlockId, type EditorDraftBlockBaselineUpdateMetaInput, type EditorDraftBlockInitMetaInput, type EditorBlockValues, type EditorContentValues, type EditorEntryId, type EditorMetadataValues, type EditorPageId, type EditorPersistedBlock, type EditorSiteId, type EditorStructuralCommand, type EditorStructuralDraftSnapshot, type EditorValueRecord, type BaselineRevision, type SendId, type ValueSync } from '../../../core/src/index';
 import { type LinkedContentEntryId, type LinkedContentTypeKey } from '../linkedEntries/domain';
+import { type EditorValueSnapshot } from './editorValueSnapshot';
+import { type OwnWriteSince, type RefreshPolicy, type ValueSyncEvent, type ValueSyncOutcome } from '../sync/valueSync';
+export type { EditorValueSnapshot } from './editorValueSnapshot';
 export { unsafeAsEditorBlockId, unsafeAsEditorBlockValues, unsafeAsEditorContentValues, unsafeAsEditorEntryId, unsafeAsEditorMetadataValues, unsafeAsEditorPageId, unsafeAsEditorSiteId, type EditorBlockId, type EditorBlockValues, type EditorContentValues, type EditorEntryId, type EditorMetadataValues, type EditorPageId, type EditorSiteId, };
 export type EditorCommand = {
     type: 'set-metadata-value';
@@ -52,13 +56,6 @@ type PersistRemoveEffect = Readonly<{
     blockId: EditorBlockId;
 }>;
 export type EditorEffect = PersistReorderEffect | PersistInsertEffect | PersistRemoveEffect;
-export type EditorValueSnapshot<TValue extends EditorValueRecord | null> = Readonly<{
-    version: number;
-    baseline: TValue;
-    current: TValue;
-    publishedBaseline: TValue;
-    syncState: EditorSyncState;
-}>;
 export type EditorValuePublicationState<TValue extends EditorValueRecord | null> = Readonly<{
     kind: 'empty';
     hasUnpublishedChanges: false;
@@ -81,27 +78,15 @@ export type EditorValuePublicationState<TValue extends EditorValueRecord | null>
     hasUnpublishedChanges: true;
 }>;
 export declare function deriveEditorValuePublicationState<TValue extends EditorValueRecord | null>(snapshot: EditorValueSnapshot<TValue>): EditorValuePublicationState<TValue>;
-export type EditorPublishSuccessTransition = Readonly<{
-    metadata: Readonly<{
-        baseline: EditorMetadataValues | null;
-        current: EditorMetadataValues | null;
-        published: EditorMetadataValues | null;
-    }>;
-    content: Readonly<{
-        published: EditorContentValues | null;
-        versionAtPublishStart: number;
-    }>;
-    blockPublishedBaselines: readonly BlockPublishedBaselineInput[] | null;
-}>;
 type EditorMetadataSnapshot = EditorValueSnapshot<EditorMetadataValues | null>;
 type EditorContentSnapshot = EditorValueSnapshot<EditorContentValues | null>;
+/** The linked entry's baseline revision (its optimistic hash) lives in `sync`. */
 export type EditorLinkedEntryMeta = Readonly<{
     entryId: LinkedContentEntryId;
     contentTypeKey: LinkedContentTypeKey;
     contentTypeLabel: string;
     title: string;
     titleField: string | null;
-    optimisticHash: string | null;
     fields: readonly EditorValueRecord[];
 }>;
 export type EditorLinkedEntrySnapshot = EditorValueSnapshot<EditorContentValues | null> & Readonly<{
@@ -111,31 +96,26 @@ export type EditorBlockMeta = Readonly<{
     kind: string;
     purpose: string | null;
     orderIndex: number | null;
-    publishedContent: EditorBlockValues | null;
-    optimisticHash: string | null;
 }>;
 export type EditorDraftSnapshot = EditorStructuralDraftSnapshot;
 export type DraftBlockInitMetaInput = EditorDraftBlockInitMetaInput;
 export type DraftBlockBaselineUpdateMetaInput = EditorDraftBlockBaselineUpdateMetaInput;
 export type DraftBlockBaselineInput = EditorBlockBaselineInput;
-export type BlockPublishedBaselineInput = EditorBlockPublishedBaselineInput;
-export type EditorBlockItem = Partial<BlockContentIdentity> & Readonly<{
+export type EditorBlockItem = Readonly<{
     id?: string | null;
     kind: string;
     content?: EditorValueRecord | null;
     orderIndex?: number | null;
     draftContent?: EditorValueRecord | null;
-    publishedContent?: EditorValueRecord | null;
     bindings?: EditorValueRecord | null;
     purpose?: string | null;
     optimisticHash?: string | null;
 }>;
-type NormalizedEditorBlockBase = BlockContentIdentity & Readonly<{
+type NormalizedEditorBlockBase = Readonly<{
     kind: string;
     content: EditorBlockValues | null;
     orderIndex: number | null;
     draftContent: EditorBlockValues | null;
-    publishedContent: EditorBlockValues | null;
     bindings: EditorBlockValues | null;
     purpose: string | null;
     optimisticHash: string | null;
@@ -153,10 +133,30 @@ export type EditorHistorySnapshot = Readonly<{
      * Structural/history operations and baseline acknowledgements keep this list in sync,
      * while draft-only validation/edit metadata continues to live in `drafts`.
      */
+    blockCollectionOwner: EditorBlockCollectionOwner | null;
+    collectionReadBaselines: Readonly<Record<string, EditorBlockCollectionReadBaseline>>;
     blockList: readonly NormalizedEditorBlockItem[];
     drafts: Readonly<Record<EditorBlockId, EditorDraftSnapshot>>;
     linkedEntries: Readonly<Record<string, EditorLinkedEntrySnapshot>>;
 }>;
+/** Which value a sync event applies to. A linked entry that is the document itself routes to content. */
+export type EditorValueKey = Readonly<{
+    kind: 'metadata';
+}> | Readonly<{
+    kind: 'content';
+}> | Readonly<{
+    kind: 'block';
+    blockId: EditorBlockId;
+}> | Readonly<{
+    kind: 'linked-entry';
+    entryId: string;
+}>;
+/** Events arrive unbranded; each family brands (and clones) the values it stores. */
+export type EditorValueSyncEvent = ValueSyncEvent<EditorValueRecord | null>;
+export type EditorValueTransition = Readonly<{
+    snapshot: EditorHistorySnapshot;
+    outcome: ValueSyncOutcome;
+}>;
 export declare function requirePersistedEditorBlock(block: EditorBlockItem | NormalizedEditorBlockItem): PersistedEditorBlockItem;
 export declare function createEditorDraftSnapshotFromBlock(block: PersistedEditorBlockItem): EditorDraftSnapshot;
 export declare function createEditorHistorySnapshot(): EditorHistorySnapshot;
@@ -171,78 +171,24 @@ export type EditorUserOperation = {
     type: 'user-command';
     command: EditorCommand;
 };
+/**
+ * History-free operations. Save requests don't appear here: the store applies their
+ * sync events (`send-started`, `send-succeeded`, `send-failed`) through `applyValueEvent`.
+ */
 export type EditorSystemOperation = {
-    type: 'hydrate-metadata';
-    baseline: EditorMetadataValues | null;
-    current?: EditorMetadataValues | null;
-    published?: EditorMetadataValues | null;
-} | {
-    type: 'hydrate-content';
-    baseline: EditorContentValues | null;
-    current?: EditorContentValues | null;
-    published?: EditorContentValues | null;
-} | {
     type: 'set-metadata-published-baseline';
     published: EditorMetadataValues | null;
 } | {
     type: 'set-content-published-baseline';
     published: EditorContentValues | null;
-} | {
-    type: 'apply-publish-success';
-    transition: EditorPublishSuccessTransition;
-} | {
-    type: 'autosave-metadata-succeeded';
-    savedValues: EditorMetadataValues | null;
-    acknowledgedVersion: number;
-} | {
-    type: 'autosave-content-succeeded';
-    savedValues: EditorContentValues | null;
-    acknowledgedVersion: number;
-} | {
-    type: 'autosave-metadata-failed';
-    message?: string;
-} | {
-    type: 'autosave-content-failed';
-    message?: string;
-} | {
-    type: 'clear-metadata-error';
-} | {
-    type: 'clear-content-error';
 } | {
     type: 'init-new-draft-block';
     blockId: EditorBlockId;
     baseline: DraftBlockBaselineInput;
     meta: DraftBlockInitMetaInput;
-} | {
-    type: 'update-draft-block-baseline';
-    blockId: EditorBlockId;
-    baseline: DraftBlockBaselineInput;
-    meta?: DraftBlockBaselineUpdateMetaInput;
 } | {
     type: 'remove-draft-block';
     blockId: EditorBlockId;
-} | {
-    type: 'set-draft-published-baselines';
-    blocks: readonly BlockPublishedBaselineInput[];
-} | {
-    type: 'autosave-draft-succeeded';
-    blockId: EditorBlockId;
-    savedValues: EditorBlockValues | null;
-    acknowledgedVersion: number;
-    optimisticHash: string | null;
-} | {
-    type: 'autosave-draft-failed';
-    blockId: EditorBlockId;
-    message?: string;
-} | {
-    type: 'clear-draft-error';
-    blockId: EditorBlockId;
-} | {
-    type: 'set-draft-pending';
-    blockId: EditorBlockId;
-} | {
-    type: 'clear-draft-pending';
-    blockId: EditorBlockId;
 } | {
     type: 'hydrate-linked-entry';
     entryId: string;
@@ -253,23 +199,14 @@ export type EditorSystemOperation = {
     optimisticHash?: string | null;
     fields: readonly EditorValueRecord[];
     baseline: EditorContentValues | null;
-    current?: EditorContentValues | null;
-} | {
-    type: 'discard-linked-entry';
-    entryId: string;
 } | {
-    type: 'save-linked-entry-succeeded';
-    entryId: string;
-    savedValues: EditorContentValues | null;
-    acknowledgedVersion: number;
-    optimisticHash?: string | null;
+    /** An `edited` event outside history: a preview runtime showing values it drives. */
+    type: 'edit-without-history';
+    key: EditorValueKey;
+    values: EditorValueRecord | null;
 } | {
-    type: 'save-linked-entry-failed';
-    entryId: string;
-    message?: string;
-} | {
-    type: 'clear-linked-entry-error';
-    entryId: string;
+    type: 'discard-local-edits';
+    contentOwnerEntryId?: string;
 } | {
     type: 'replace-block-list';
     next: readonly EditorBlockItem[];
@@ -279,36 +216,73 @@ export declare function applyEditorCommand(snapshot: EditorHistorySnapshot, comm
 export declare function applyUserOperation(snapshot: EditorHistorySnapshot, operation: EditorUserOperation): EditorHistorySnapshot;
 export declare function applySystemOperation(snapshot: EditorHistorySnapshot, operation: EditorSystemOperation): EditorHistorySnapshot;
 export declare function applyEditorOperation(snapshot: EditorHistorySnapshot, operation: EditorOperation): EditorHistorySnapshot;
-export declare function hydrateMetadataSnapshot(snapshot: EditorHistorySnapshot, baseline: EditorMetadataValues | null, current?: EditorMetadataValues | null, published?: EditorMetadataValues | null): EditorHistorySnapshot;
-export declare function hydrateContentSnapshot(snapshot: EditorHistorySnapshot, baseline: EditorContentValues | null, current?: EditorContentValues | null, published?: EditorContentValues | null): EditorHistorySnapshot;
+/** The sync state of one value, or `undefined` when that block or linked entry isn't loaded. */
+export declare function valueSyncAt(snapshot: EditorHistorySnapshot, key: EditorValueKey): ValueSync<EditorValueRecord | null> | undefined;
+/** Applies one sync event to one value; the single path every family's transitions take. */
+export declare function applyValueEvent(snapshot: EditorHistorySnapshot, key: EditorValueKey, event: EditorValueSyncEvent): EditorValueTransition;
+/** What one started request carries: the values sent and the revision they were based on. */
+export type StartedSend = Readonly<{
+    key: EditorValueKey;
+    id: SendId;
+    values: EditorValueRecord | null;
+    basis: BaselineRevision;
+}>;
+export declare function startedSendAt(snapshot: EditorHistorySnapshot, key: EditorValueKey, id: SendId): StartedSend | null;
+export declare function aggregateSyncState(snapshot: EditorHistorySnapshot): 'baseline' | 'pending' | 'failed';
 export declare function setMetadataPublishedBaseline(snapshot: EditorHistorySnapshot, published: EditorMetadataValues | null): EditorHistorySnapshot;
 export declare function setContentPublishedBaseline(snapshot: EditorHistorySnapshot, published: EditorContentValues | null): EditorHistorySnapshot;
-export declare function applyPublishSuccessTransition(snapshot: EditorHistorySnapshot, transition: EditorPublishSuccessTransition): EditorHistorySnapshot;
-export declare function autosaveMetadataSucceeded(snapshot: EditorHistorySnapshot, savedValues: EditorMetadataValues | null, acknowledgedVersion: number): EditorHistorySnapshot;
-export declare function autosaveContentSucceeded(snapshot: EditorHistorySnapshot, savedValues: EditorContentValues | null, acknowledgedVersion: number): EditorHistorySnapshot;
-export declare function autosaveMetadataFailed(snapshot: EditorHistorySnapshot, message?: string): EditorHistorySnapshot;
-export declare function autosaveContentFailed(snapshot: EditorHistorySnapshot, message?: string): EditorHistorySnapshot;
-export declare function clearMetadataError(snapshot: EditorHistorySnapshot): EditorHistorySnapshot;
-export declare function clearContentError(snapshot: EditorHistorySnapshot): EditorHistorySnapshot;
 export declare function getCurrentValues<TValue extends EditorValueRecord | null>(snapshot: EditorValueSnapshot<TValue>): TValue;
-export declare function getSnapshotStatus(syncState: EditorSyncState): 'baseline' | 'pending' | 'failed';
-export declare function getSnapshotError(syncState: EditorSyncState): string | null;
+/**
+ * How a server block value arrives (issue 1553): a read is a refresh under its policy;
+ * a response to this tab's own write (discard draft's block result) is rebased against
+ * what the person's edits are measured from.
+ */
+export type DraftBlockArrival = Readonly<{
+    kind: 'refreshed';
+    policy: RefreshPolicy;
+}> | Readonly<{
+    kind: 'own-write';
+    since: OwnWriteSince<EditorBlockValues | null>;
+}>;
 export declare function initNewDraftBlock(snapshot: EditorHistorySnapshot, blockId: EditorBlockId, baseline: DraftBlockBaselineInput, meta: DraftBlockInitMetaInput): EditorHistorySnapshot;
-export declare function updateDraftBlockBaseline(snapshot: EditorHistorySnapshot, blockId: EditorBlockId, baseline: DraftBlockBaselineInput, meta?: DraftBlockBaselineUpdateMetaInput): EditorHistorySnapshot;
+/** What a server block refresh carries; the shape of editor-blocks' baseline seed. */
+export type DraftBlockRefresh = Readonly<{
+    blockId: EditorBlockId;
+    baseline: DraftBlockBaselineInput;
+    initMeta?: DraftBlockInitMetaInput;
+    refreshMeta?: DraftBlockBaselineUpdateMetaInput;
+}>;
+/**
+ * Refreshes one block from the server: an existing draft moves under the policy, a
+ * missing one is created pristine (when the refresh says how to create it).
+ */
+export declare function refreshDraftBlock(snapshot: EditorHistorySnapshot, refresh: DraftBlockRefresh, arrival: DraftBlockArrival): EditorValueTransition;
 export declare function removeDraftBlock(snapshot: EditorHistorySnapshot, blockId: EditorBlockId): EditorHistorySnapshot;
-export declare function setDraftPublishedBaselines(snapshot: EditorHistorySnapshot, blocks: readonly BlockPublishedBaselineInput[]): EditorHistorySnapshot;
-export declare function autosaveDraftSucceeded(snapshot: EditorHistorySnapshot, blockId: EditorBlockId, savedValues: EditorBlockValues | null, acknowledgedVersion: number, optimisticHash: string | null): EditorHistorySnapshot;
-export declare function autosaveDraftFailed(snapshot: EditorHistorySnapshot, blockId: EditorBlockId, message?: string): EditorHistorySnapshot;
-export declare function clearDraftError(snapshot: EditorHistorySnapshot, blockId: EditorBlockId): EditorHistorySnapshot;
-export declare function setDraftPending(snapshot: EditorHistorySnapshot, blockId: EditorBlockId): EditorHistorySnapshot;
-export declare function clearDraftPending(snapshot: EditorHistorySnapshot, blockId: EditorBlockId): EditorHistorySnapshot;
-export declare function hydrateLinkedEntrySnapshot(snapshot: EditorHistorySnapshot, input: Extract<EditorSystemOperation, {
+type LinkedEntryHydration = Extract<EditorSystemOperation, {
     type: 'hydrate-linked-entry';
-}>): EditorHistorySnapshot;
-export declare function discardLinkedEntrySnapshot(snapshot: EditorHistorySnapshot, entryId: string): EditorHistorySnapshot;
-export declare function saveLinkedEntrySucceeded(snapshot: EditorHistorySnapshot, entryId: string, savedValues: EditorContentValues | null, acknowledgedVersion: number, optimisticHash?: string | null): EditorHistorySnapshot;
-export declare function saveLinkedEntryFailed(snapshot: EditorHistorySnapshot, entryId: string, message?: string): EditorHistorySnapshot;
-export declare function clearLinkedEntryError(snapshot: EditorHistorySnapshot, entryId: string): EditorHistorySnapshot;
+}>;
+/**
+ * Opening a linked entry from the rendered page is an ordinary keep-local refresh of its
+ * record. A render without a revision keeps the record's own rather than wiping it.
+ */
+export declare function hydrateLinkedEntrySnapshot(snapshot: EditorHistorySnapshot, input: LinkedEntryHydration): EditorHistorySnapshot;
+/**
+ * Throw away every unsaved local edit, synchronously and locally: each value is
+ * `discarded`, so it shows its baseline and any request still outstanding becomes
+ * abandoned (issue 1553, D1–D3). Linked entries keep their record (D2); the document's
+ * own entry is routed through content. Nothing is read from the server, so it can't
+ * fail; newer server values arrive by the usual paths.
+ */
+export declare function discardLocalEditsSnapshot(snapshot: EditorHistorySnapshot, contentOwnerEntryId?: string): EditorHistorySnapshot;
+/** The linked entries whose local edits a discard would throw away. */
+export declare function editedLinkedEntryIds(snapshot: EditorHistorySnapshot): readonly string[];
+/**
+ * Undo and redo restore what the person sees, never sync state (issue 1553, D4).
+ * Displayed values and structure come from the target; baselines, revisions, requests
+ * and published baselines come from the present. A block record brought back by
+ * structure has no request (U3); other records missing from the target keep the present's.
+ */
+export declare function restoreDisplay(present: EditorHistorySnapshot, target: EditorHistorySnapshot): EditorHistorySnapshot;
 export declare function replaceEditorBlockList(snapshot: EditorHistorySnapshot, blockList: readonly EditorBlockItem[]): EditorHistorySnapshot;
 export declare function getDraftSnapshot(snapshot: EditorHistorySnapshot, blockId: string): EditorDraftSnapshot | null;
 export declare function inspectDrafts(snapshot: EditorHistorySnapshot): EditorDraftSnapshot[];
@@ -320,5 +294,6 @@ export type EditorDraftUnpublishedBlockChange = Readonly<{
     currentContent: EditorBlockValues | null;
     publishedContent: EditorBlockValues | null;
 }>;
-export declare function getFirstUnpublishedDraftChange(snapshot: EditorHistorySnapshot): EditorDraftUnpublishedBlockChange | null;
-export declare function hasUnpublishedDraftChanges(snapshot: EditorHistorySnapshot): boolean;
+export declare function blockPublicationState(draft: EditorDraftSnapshot, versions: EditorBlockVersions): EditorValuePublicationState<EditorBlockValues | null>;
+export declare function getFirstUnpublishedDraftChange(snapshot: EditorHistorySnapshot, versionsFor: (blockId: EditorBlockId) => EditorBlockVersions): EditorDraftUnpublishedBlockChange | null;
+export declare function hasUnpublishedDraftChanges(snapshot: EditorHistorySnapshot, versionsFor: (blockId: EditorBlockId) => EditorBlockVersions): boolean;

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

@@ -87,7 +87,7 @@ export declare function confirmStagedSession<TSnapshot, THistoryEntry, TTargetKe
 export declare function rejectStagedSession<TSnapshot, THistoryEntry, TTargetKey extends string = string>(state: EditorStagedSessionState<TSnapshot, THistoryEntry, TTargetKey>, failure: EditorTransactionFailure): EditorStagedSessionState<TSnapshot, THistoryEntry, TTargetKey>;
 export declare function cancelStagedSession<TSnapshot, THistoryEntry, TTargetKey extends string = string>(state: EditorStagedSessionState<TSnapshot, THistoryEntry, TTargetKey>): EditorStagedSessionState<TSnapshot, THistoryEntry, TTargetKey>;
 export declare function enqueueTransaction<TAction, THistoryEntry, TTargetKey extends string = string>(state: EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>, transaction: EditorTransaction<TAction, THistoryEntry, TTargetKey>): EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>;
-export declare function beginAutosaveBatch<TAction, THistoryEntry, TTargetKey extends string = string>(state: EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>): EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>;
+export declare function beginAutosaveBatch<TAction, THistoryEntry, TTargetKey extends string = string>(state: EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>, captured?: EditorSaveBatch<TAction, THistoryEntry, TTargetKey>): EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>;
 export declare function confirmAutosaveBatch<TAction, THistoryEntry, TTargetKey extends string = string>(state: EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>): EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>;
 export declare function rejectAutosaveBatch<TAction, THistoryEntry, TTargetKey extends string = string>(state: EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>, failure: EditorTransactionFailure): EditorTransactionQueueState<TAction, THistoryEntry, TTargetKey>;
 export declare function coalesceQueuedTransactions<TAction, THistoryEntry, TTargetKey extends string = string>(queue: readonly EditorTransaction<TAction, THistoryEntry, TTargetKey>[], transaction: EditorTransaction<TAction, THistoryEntry, TTargetKey>): readonly EditorTransaction<TAction, THistoryEntry, TTargetKey>[];

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

@@ -1,16 +1,33 @@
-import type { FooterModuleId } from '../../../core/src/index';
+import { type BlockFieldExtensions } from '../../../editor-blocks/src/block-editor/blockDraftBaselineSeed';
+import type { EditorBlockCollectionOwner, EditorBlockCollectionReadBaseline } from '../../../core/src/index';
+import { type ServerBlockAdmission } from './serverBlockAdmission';
+import { type BlockVersionsState } from './stores/blockVersionsStore';
+import { type EditorBlockVersions, type EditorInsertBlockCommand, type SavedBlockContentVersion } from '../../../core/src/index';
+import type { ServerBlockItem } from '../../../editor-blocks/src/block-editor/types';
+import { type DocumentLifecycleResult } from './documentLifecycle';
+import type { EditorValueRecord, FooterModuleId } from '../../../core/src/index';
+import type { EditorLeaseUiState } from './editorLeaseUiState';
+import type { DraftsSlice } from '../../../editor-blocks/src/block-editor/types';
+import { type EditorEditability } from '../controller/editorEditability';
+export { unmanagedSurfaceEditability } from '../controller/editorEditability';
+import { type LinkedEntryLeaseState } from './stores/linkedEntryLeaseStore';
+import { type DocumentValueRefreshInput, type OwnWrite, type PublishSuccessRefresh, type ValueRefresh } from './editorRefresh';
+import { type RemoteDraftsState } from './stores/remoteDraftsStore';
+import { type LinkedSaveHandoversState } from './stores/linkedSaveHandoversStore';
 import { type EditorUnpublishedState } from '../controller/deriveEditorUnpublishedState';
 import { type AutosaveState } from './stores/autosaveStore';
 import { type GeneratedIconAssetsState } from './stores/generatedIconAssetsStore';
 import { type ArrayKeysState } from './stores/arrayKeysStore';
 import { type ViewportState } from './stores/viewportStore';
 import { type AiOverlaysState } from './stores/aiOverlaysSlice';
-import { type EditorValueSnapshot, type EditorBlockItem, type EditorBlockId, type NormalizedEditorBlockItem, type DraftBlockBaselineInput, type DraftBlockBaselineUpdateMetaInput, type DraftBlockInitMetaInput, type EditorCommand, type EditorContentValues, type EditorDraftSnapshot, type EditorDraftUnpublishedBlockChange, type EditorEffect, type EditorHistorySnapshot, type EditorLinkedEntrySnapshot, type EditorMetadataValues, type BlockPublishedBaselineInput } from './editorHistory';
+import { type EditorValueSnapshot, type EditorBlockItem, type EditorBlockId, type NormalizedEditorBlockItem, type EditorCommand, type EditorContentValues, type EditorDraftUnpublishedBlockChange, type EditorEffect, type EditorHistorySnapshot, type EditorLinkedEntrySnapshot, type EditorMetadataValues, type EditorValueKey, type StartedSend } from './editorHistory';
+import { type RefreshPolicy, type SendMode, type ValueSyncOutcome } from '../sync/valueSync';
+import type { BaselineRevision, SaveFailure, SendId, ValueSync } from '../../../core/src/index';
 import { type HistoryState } from './editorHistory';
-import type { FocusRequest, FocusTarget } from './stores/types';
-import { type LinkedContentEntryId } from '../linkedEntries/domain';
+import type { FocusRequest, FocusTarget, HeldOperation, LifecycleFailure, LifecycleOperation, LifecycleStatus } from './stores/types';
+import { type LinkedContentEntryId, type LinkedEntryOpenTarget } from '../linkedEntries/domain';
 import { type BlockDraftSaveability, type BlockDraftValidationIssue, type ResolveBlockManifest } from './blockValidationView';
-export type { AutosaveStatusValue, AutosaveStatus, AutosaveHandle, AutosaveType, AutosaveType as AutosaveSchedulerKey, FocusRequest, ViewportMode, ViewportWidth, ZoomLevel, } from './stores/types';
+export type { AutosaveStatusValue, AutosaveStatus, AutosaveHandle, AutosaveType, FocusRequest, HeldOperation, LifecycleFailure, LifecycleOperation, LifecycleOutcome, LifecycleStatus, ViewportMode, ViewportWidth, ZoomLevel, } from './stores/types';
 export type { AutosaveState } from './stores/autosaveStore';
 export type { ArrayKeysState } from './stores/arrayKeysStore';
 export type { ViewportState } from './stores/viewportStore';
@@ -41,15 +58,24 @@ export type ActivePreviewField = (Readonly<{
     entryId: LinkedContentEntryId;
     fieldPath: string;
 }>) | null;
-/**
- * Version of the local draft snapshot that a completed autosave request persisted.
- * The reducer uses this to accept the saved baseline without treating older
- * in-flight saves as acknowledgements of newer local edits.
- */
-export type AutosaveAcknowledgement = Readonly<{
-    acknowledgedVersion: number;
-    optimisticHash?: string | null;
+/** How a save request settled. `at` is the ISO time the shell observed the response. */
+export type SendResult = Readonly<{
+    kind: 'succeeded';
+    values: Record<string, unknown> | null;
+    revision: BaselineRevision;
+    at: string;
+    published?: Readonly<{
+        kind: 'known';
+        values: Record<string, unknown> | null;
+    } | {
+        kind: 'unknown';
+    }>;
+    blockVersion?: SavedBlockContentVersion;
+}> | Readonly<{
+    kind: 'failed';
+    failure: SaveFailure;
 }>;
+export type { EditorValueKey, StartedSend } from './editorHistory';
 /**
  * Form-facing metadata facade. Consumers pass plain records for ergonomics;
  * the reducer core normalizes and brands values at this boundary.
@@ -57,16 +83,16 @@ export type AutosaveAcknowledgement = Readonly<{
 export type MetadataState = {
     getSnapshot: () => MetadataSnapshot;
     getCurrentValues: () => Record<string, unknown> | null;
-    hydrate: (baseline: Record<string, unknown> | null, current?: Record<string, unknown> | null, published?: Record<string, unknown> | null) => void;
+    /**
+     * Applies a server read of this value as a refresh event (issue 1553). Ordinary
+     * refreshes are keep-local; returns whether local edits were discarded.
+     */
+    refresh: (input: DocumentValueRefreshInput, policy?: RefreshPolicy) => boolean;
     setPublishedBaseline: (published: Record<string, unknown> | null) => void;
     hasUnpublishedChanges: () => boolean;
-    setBaseline: (baseline: Record<string, unknown> | null) => void;
     setCurrentValues: (values: Record<string, unknown> | null) => void;
     setAtPath: (path: string, value: unknown) => void;
     getAtPath: <R = unknown>(path: string) => R | undefined;
-    autosaveSucceeded: (savedValues: Record<string, unknown> | null, acknowledgement?: AutosaveAcknowledgement) => void;
-    autosaveFailed: (message?: string) => void;
-    clearError: () => void;
 };
 export type ContentState = Omit<MetadataState, 'getSnapshot'> & {
     getSnapshot: () => ContentSnapshot;
@@ -91,18 +117,7 @@ export type PreviewInspection = Readonly<{
 }>;
 export type LinkedEntryState = {
     getSelectedEntryId: () => LinkedContentEntryId | null;
-    open: (target: {
-        entryId: string;
-        contentTypeKey: string;
-        contentTypeLabel: string;
-        title: string;
-        optimisticHash?: string | null;
-        content: Record<string, unknown>;
-        contentType: {
-            titleField?: string | null;
-            fields: readonly Record<string, unknown>[];
-        };
-    }) => void;
+    open: (target: LinkedEntryOpenTarget) => void;
     close: () => void;
     discard: (entryId?: string) => void;
     getSelectedSnapshot: () => EditorLinkedEntrySnapshot | null;
@@ -112,11 +127,6 @@ export type LinkedEntryState = {
     setCurrentValues: (values: Record<string, unknown> | null, entryId?: string) => void;
     setAtPath: (path: string, value: unknown, entryId?: string) => void;
     getAtPath: <R = unknown>(path: string, entryId?: string) => R | undefined;
-    saveSucceeded: (entryId: string, content: Record<string, unknown> | null, acknowledgement?: AutosaveAcknowledgement & {
-        optimisticHash?: string | null;
-    }) => void;
-    saveFailed: (entryId: string, message?: string) => void;
-    clearError: (entryId?: string) => void;
 };
 export type EditorPreviewInspectorStore = {
     getState: () => {
@@ -127,6 +137,12 @@ export type EditorPreviewInspectorStore = {
             structure?: AiOverlaysState['structure'];
         }>;
         linkedEntries: Pick<LinkedEntryState, 'inspect'>;
+        blockVersions: Pick<BlockVersionsState, 'get' | 'revision'>;
+        remoteDrafts?: RemoteDraftsState['remoteDrafts'];
+        linkedSaveHandovers?: LinkedSaveHandoversState['linkedSaveHandovers'];
+        content?: Pick<ContentState, 'getSnapshot'>;
+        /** Decides the render source: a viewer renders live drafts, any other tab its own edits. */
+        editability: EditorEditability;
     };
 };
 export type EditorHistoryState = HistoryState<EditorHistorySnapshot>;
@@ -155,54 +171,40 @@ export type BlockValidationState = {
     } | null;
     getBlockSaveability: (blockId: EditorBlockId) => BlockDraftSaveability;
 };
-export type DraftsState = {
-    getBlockSnapshot: (blockId: EditorBlockId) => EditorDraftSnapshot | null;
-    getCurrentValues: (blockId: EditorBlockId) => Record<string, unknown> | null;
-    inspect: () => EditorDraftSnapshot[];
-    /**
-     * Form-facing drafts facade. Baseline inputs stay unbranded so editor consumers
-     * can pass raw form values; the reducer core normalizes and brands them here.
-     */
-    initNewBlock: (blockId: EditorBlockId, baseline: DraftBlockBaselineInput, meta: DraftBlockInitMetaInput) => void;
-    updateBlockBaseline: (blockId: EditorBlockId, baseline: DraftBlockBaselineInput, meta?: DraftBlockBaselineUpdateMetaInput) => void;
-    setBlockPublishedBaselinesFromBlocks: (blocks: readonly BlockPublishedBaselineInput[]) => void;
-    edit: (blockId: EditorBlockId, content: Record<string, unknown> | null) => void;
-    remove: (blockId: EditorBlockId) => void;
-    clearError: (blockId: EditorBlockId) => void;
-    setPending: (blockId: EditorBlockId) => void;
-    clearPending: (blockId: EditorBlockId) => void;
-    setFailed: (blockId: EditorBlockId, message?: string) => void;
-    autosaveSucceeded: (blockId: EditorBlockId, content: Record<string, unknown> | null, acknowledgement?: AutosaveAcknowledgement) => void;
-    autosaveFailed: (blockId: EditorBlockId, message?: string) => void;
-    setAtPath: (blockId: EditorBlockId, path: string, value: unknown) => void;
-    getAtPath: <T = unknown>(blockId: EditorBlockId, path: string) => T | undefined;
-    updateBlockOrder: (blockIds: EditorBlockId[]) => void;
+/**
+ * Form-facing drafts facade: editor-blocks' `DraftsSlice` contract plus the store-only
+ * publish helpers. Baseline inputs stay unbranded so editor consumers can pass raw
+ * form values; the reducer core normalizes and brands them here.
+ */
+export type DraftsState = DraftsSlice & {
     hasUnpublishedBlockChanges: () => boolean;
     getFirstUnpublishedBlockChange: () => EditorDraftUnpublishedBlockChange | null;
-    markAllBlocksAsPublished: () => void;
     onChange: (listener: (blockId: EditorBlockId) => void) => () => void;
+    /**
+     * Shows `content` as the block's local edit without a history entry: a preview runtime
+     * (customize) drives these values and owns their undo (issue 1553).
+     */
+    editWithoutHistory: (blockId: EditorBlockId, content: Record<string, unknown> | null) => void;
 };
+/** Local edits are refused while the tab can't write (read-only, acquiring or viewing). */
+export type EditorUserOperationOutcome = 'applied' | 'unchanged' | 'refused';
+export type EditorPublishedVersionScope = 'metadata' | 'content';
 export type CreateEditorUiStoreOptions = Readonly<{
+    publishedVersionScope?: EditorPublishedVersionScope;
+    contentOwnerEntryId?: string;
+    /** Required so a new caller can't write freely by omission; unmanaged surfaces say so explicitly. */
+    editability: EditorLeaseUiState['editability'];
     resolveBlockManifest?: ResolveBlockManifest;
+    resolveBlockFieldExtensions?: () => BlockFieldExtensions | null | undefined;
 }>;
 type RestoreListener = (transition: {
     previous: EditorHistorySnapshot;
     next: EditorHistorySnapshot;
     effects: readonly EditorEffect[];
 }) => void;
-export type ApplyPublishSuccessTransitionInput = Readonly<{
-    metadata: Readonly<{
-        baseline: Record<string, unknown> | null;
-        current: Record<string, unknown> | null;
-        published: Record<string, unknown> | null;
-    }>;
-    content: Readonly<{
-        published: Record<string, unknown> | null;
-        versionAtPublishStart: number;
-    }>;
-    blockPublishedBaselines: readonly BlockPublishedBaselineInput[] | null;
-}>;
-export type EditorUiState = {
+export type ApplyPublishSuccessTransitionInput = PublishSuccessRefresh;
+export type EditorUiState = EditorLeaseUiState & LinkedEntryLeaseState & RemoteDraftsState & LinkedSaveHandoversState & {
+    contentOwnerEntryId: string | undefined;
     drawerOpen: boolean;
     previewSidebarTab: PreviewSidebarTab;
     previewInspection: PreviewInspection;
@@ -222,9 +224,36 @@ export type EditorUiState = {
     clearFocus: () => void;
     setActiveBlockId: (id: EditorBlockId | null) => void;
     getDraftSyncState: () => 'baseline' | 'pending' | 'failed';
+    /** The document's lifecycle operations (`LifecycleOperation`); outside history, beside the values' states. */
+    lifecycle: LifecycleStatus;
+    /** When a save or lifecycle operation was last accepted (ISO time). */
+    lastSavedAt: string | null;
+    /** How many saves have been accepted; a `server` lifecycle failure holds until this moves. */
+    acceptedSaves: number;
+    setLifecycle: (change: LifecycleChange) => void;
+    /**
+     * Starts a save for each value that may send now, allocating one id per request.
+     * Returns what each started request carries; values that may not send are left out.
+     */
+    beginSends: (keys: readonly EditorValueKey[], mode?: SendMode, checkpoints?: ReadonlyMap<string, Record<string, unknown> | null>) => readonly StartedSend[];
+    /** One value's sync state; `undefined` when that block or linked entry isn't loaded. */
+    getValueSync: (key: EditorValueKey) => ValueSync<EditorValueRecord | null> | undefined;
+    /** Applies a response. Only the value's current request is acknowledged; others are ignored. */
+    settle: (key: EditorValueKey, id: SendId, result: SendResult) => ValueSyncOutcome;
+    /** Throws away every unsaved local edit, synchronously; see `discardLocalEditsSnapshot`. */
+    discardLocalEdits: () => void;
     getUnpublishedState: () => EditorUnpublishedState;
     hasAnyUnpublishedChanges: () => boolean;
+    applyDocumentLifecycle: (result: DocumentLifecycleResult) => void;
     applyPublishSuccessTransition: (transition: ApplyPublishSuccessTransitionInput) => void;
+    /** Applies what this tab's own writes returned, rebased under any edits (`OwnWrite`). */
+    applyOwnWrites: (writes: readonly OwnWrite[]) => void;
+    /**
+     * Applies server reads as refresh events in one update, under one policy (issue 1553):
+     * keep-local for ordinary refreshes, take-back for a lease grant, replace for discard
+     * draft. Returns whether local edits were discarded.
+     */
+    refreshValues: (refreshes: readonly ValueRefresh[], policy: RefreshPolicy) => boolean;
     history: {
         getState: () => EditorHistoryState;
         canUndo: () => boolean;
@@ -241,9 +270,16 @@ export type EditorUiState = {
     };
     blockValidation: BlockValidationState;
     structure: {
+        getOwner: () => EditorBlockCollectionOwner | null;
+        mount: (owner: EditorBlockCollectionOwner, blocks: readonly ServerBlockItem[], reads?: readonly EditorBlockCollectionReadBaseline[]) => void;
+        unmount: (owner: EditorBlockCollectionOwner) => void;
         getList: () => readonly NormalizedEditorBlockItem[];
         replaceList: (next: readonly EditorBlockItem[]) => void;
     };
+    blockVersions: BlockVersionsState;
+    admitServerBlocks: (entries: readonly ServerBlockAdmission[], policy?: RefreshPolicy) => void;
+    insertServerBlock: (command: EditorInsertBlockCommand, versions: EditorBlockVersions) => void;
+    remapServerBlock: (fromId: EditorBlockId, toId: EditorBlockId, versions: EditorBlockVersions) => void;
     drafts: DraftsState;
     metadata: MetadataState;
     content: ContentState;
@@ -254,7 +290,25 @@ export type EditorUiState = {
     viewport: ViewportState;
     aiOverlays: AiOverlaysState;
 };
-export declare function createEditorUiStore(options?: CreateEditorUiStoreOptions): import("zustand").StoreApi<EditorUiState>;
+/**
+ * How a lifecycle operation moves the status: it starts, finishes (recording when it
+ * saved, if it did) or fails.
+ */
+export type LifecycleChange = Readonly<{
+    kind: 'start';
+    operation: LifecycleOperation;
+}> | Readonly<{
+    kind: 'hold';
+    operation: HeldOperation;
+}> | Readonly<{
+    kind: 'finish';
+    at: string | null;
+}> | Readonly<{
+    kind: 'fail';
+    operation: LifecycleOperation;
+    failure: LifecycleFailure;
+}>;
+export declare function createEditorUiStore(options: CreateEditorUiStoreOptions): import("zustand").StoreApi<EditorUiState>;
 export type EditorUiStoreInstance = ReturnType<typeof createEditorUiStore>;
 export declare const EditorUiStoreProvider: import("react").Provider<import("zustand").StoreApi<EditorUiState> | null>;
 export declare function useEditorUiStore<T>(selector: (state: EditorUiState) => T): T;