chromium-tabs 0.1.0 → 0.2.0

package/dist/session/index.d.cts

@@ -0,0 +1,479 @@
+import { C as CommandStorageBackend, S as SessionCommand, R as ReadCommandsResult, a as SessionTab, b as SessionWindow, c as SessionWindowId, d as SessionSnapshot, e as SerializedNavigationEntry } from '../command-storage-backend-BLy7EP79.cjs';
+export { D as DEFAULT_WINDOW_ID, f as SessionCommandId, g as SessionTabGroup, h as createAddTabExtraDataCommand, i as createAddWindowExtraDataCommand, j as createLastActiveTimeCommand, k as createPinnedStateCommand, l as createSetActiveWindowCommand, m as createSetSelectedNavigationIndexCommand, n as createSetSelectedTabInWindowCommand, o as createSetTabDataCommand, p as createSetTabIndexInWindowCommand, q as createSetTabWindowCommand, r as createTabClosedCommand, s as createTabGroupCommand, t as createTabGroupMetadataUpdateCommand, u as createTabNavigationPathPrunedCommand, v as createUpdateTabNavigationCommand, w as createWindowClosedCommand, x as currentNavigationEntry, y as findClosestNavigationWithIndex, z as isClosingCommand, A as processTabNavigationPathPruned, B as restoreSessionFromCommands } from '../command-storage-backend-BLy7EP79.cjs';
+import { T as TabStripModel } from '../tab-strip-model-DSFYavJO.cjs';
+import { d as TabId, T as TabGroupId, b as Tab } from '../types-CYa7ouKw.cjs';
+
+/**
+ * Buffers commands and flushes them to a storage backend on a delay.
+ * Ported from chromium-reference/components/sessions/core/command_storage_manager.cc.
+ *
+ * Chrome posts backend writes to a sequenced task runner; this port chains
+ * them on a promise queue so writes land in order even when the backend is
+ * asynchronous. Saves snapshot the pending buffer synchronously, exactly
+ * like Chrome moving pending_commands_ into the posted task (cc:251).
+ */
+
+/** Delay before pending commands are written. Mirrors kSaveDelay (cc:36). */
+declare const SAVE_DELAY_MS = 2500;
+/** Mirrors CommandStorageManagerDelegate (command_storage_manager_delegate.h). */
+interface CommandStorageManagerDelegate {
+    /** Called before each save; a chance to append more commands (cc:255). */
+    onWillSaveCommands?(): void;
+    /** A backend write failed; schedule a full rebuild (delegate.h:29). */
+    onErrorWritingSessionCommands?(): void;
+}
+interface CommandStorageManagerOptions {
+    backend: CommandStorageBackend;
+    delegate?: CommandStorageManagerDelegate;
+    saveDelayMs?: number;
+    /**
+     * Awaited before the first backend write — the SessionService uses this to
+     * make sure the previous session has been rotated to the "last" slot
+     * before this session's first (truncating) write can clobber it.
+     */
+    ready?: Promise<unknown>;
+}
+declare class CommandStorageManager {
+    private readonly backend_;
+    private readonly delegate_;
+    private readonly saveDelayMs_;
+    private pendingCommands_;
+    /** Starts true: the first save is always a complete rewrite (cc:117). */
+    private pendingReset_;
+    private commandsSinceReset_;
+    private saveTimer_;
+    /** Sequenced "task runner" for backend writes. */
+    private queue_;
+    /** Backend operations started but not yet settled. */
+    private inflight_;
+    constructor(options: CommandStorageManagerOptions);
+    /**
+     * Runs a backend operation. When nothing is in flight it runs inline — a
+     * synchronous backend then completes before this returns, which is what
+     * makes a pagehide flush reliable (the web stand-in for Chrome's
+     * BLOCK_SHUTDOWN task traits). Otherwise it is sequenced behind the queue.
+     */
+    private enqueue_;
+    get pendingReset(): boolean;
+    /** Mirrors set_pending_reset (command_storage_manager.h:77). */
+    setPendingReset(value: boolean): void;
+    get commandsSinceReset(): number;
+    /** Buffers a command and starts the save timer. Mirrors cc:192. */
+    scheduleCommand(command: SessionCommand): void;
+    /** Buffers rebuild commands without starting the timer. Mirrors cc:207. */
+    appendRebuildCommands(commands: readonly SessionCommand[]): void;
+    appendRebuildCommand(command: SessionCommand): void;
+    /** Removes a not-yet-saved command. Mirrors EraseCommand (cc:216). */
+    eraseCommand(command: SessionCommand): void;
+    /** Replaces a not-yet-saved command in place. Mirrors SwapCommand (cc:225). */
+    swapCommand(oldCommand: SessionCommand, newCommand: SessionCommand): void;
+    /** Mirrors ClearPendingCommands (cc:233) — note it does not zero the reset counter. */
+    clearPendingCommands(): void;
+    /** Read-only view for ReplacePendingCommand-style optimizations. */
+    get pendingCommands(): readonly SessionCommand[];
+    /** True between startSaveTimer() and the save it scheduled. Mirrors cc:316. */
+    get hasPendingSave(): boolean;
+    /** Schedules a save in saveDelayMs unless one is already pending. Mirrors cc:239. */
+    startSaveTimer(): void;
+    /**
+     * Flushes pending commands to the backend. Mirrors Save (cc:251): the
+     * buffer and reset flag are snapshotted synchronously; the write itself is
+     * sequenced behind earlier writes. Returns once this write has settled.
+     */
+    save(): Promise<void>;
+    /** Cancels any timer and flushes immediately. */
+    saveNow(): Promise<void>;
+    /**
+     * Promotes the current session to "last". Pending commands are flushed
+     * first, mirroring MoveCurrentSessionToLastSession (cc:320). The caller is
+     * expected to follow up with setPendingReset(true) plus a full re-emit of
+     * live state, since the current session is now empty.
+     */
+    moveCurrentSessionToLastSession(): Promise<void>;
+    /** Stops the save timer without flushing. */
+    dispose(): void;
+}
+
+/**
+ * In-memory backend: no persistence beyond the object's lifetime. Useful for
+ * tests, server-side rendering, and as the reference implementation of the
+ * two-slot current/last contract.
+ */
+
+declare class InMemoryStorageBackend implements CommandStorageBackend {
+    private current_;
+    private last_;
+    appendCommands(commands: readonly SessionCommand[], truncate: boolean): void;
+    readLastSessionCommands(): ReadCommandsResult;
+    moveCurrentSessionToLastSession(): void;
+    /** Test hook: the commands persisted for the current session, if any. */
+    get currentSessionCommands(): readonly SessionCommand[] | null;
+    /** Test hook: the commands persisted for the last session, if any. */
+    get lastSessionCommands(): readonly SessionCommand[] | null;
+}
+
+/**
+ * One session writer per profile. Ported from
+ * chromium-reference/chrome/browser/process_singleton.h.
+ *
+ * Chrome never lets two processes share a profile directory: ProcessSingleton
+ * is "named according to the user data directory, so we can be sure that no
+ * more than one copy of the application can be running at once with a given
+ * data directory" (h:45). A second launch gets PROCESS_NOTIFIED and stands
+ * down; only the PROCESS_NONE winner runs a SessionService over the profile.
+ *
+ * Two browser tabs of the same app are the web's version of two processes
+ * sharing a profile. The web cannot make the second tab exit, but it can make
+ * it stand down: the loser becomes a "secondary" SessionService with saving
+ * disabled (the SetSavingEnabled(false) state, session_service_base.cc:877)
+ * that neither rotates nor writes the shared log.
+ *
+ * The claim is made once, at startup, exactly like Chrome's — there is no
+ * mid-life takeover. When the owner dies its lock evaporates with the realm
+ * (the Web Lock analog of the OS reclaiming Chrome's SingletonLock), and the
+ * next realm to BOOT over that profile claims it and restores the session.
+ */
+/** 'owner' ~ PROCESS_NONE, 'secondary' ~ PROCESS_NOTIFIED (h:85). */
+type ProcessSingletonResult = 'owner' | 'secondary';
+interface ProcessSingleton {
+    /**
+     * Attempts to become the singleton for the profile. Resolves exactly once;
+     * repeated calls return the same promise. Mirrors
+     * NotifyOtherProcessOrCreate (h:119).
+     */
+    acquire(): Promise<ProcessSingletonResult>;
+    /** Releases the claim if held. Mirrors Cleanup (h:133). Idempotent. */
+    release(): void;
+}
+interface WebLocksProcessSingletonOptions {
+    /** Lock name. One storage area (profile) = one name. */
+    name: string;
+    /** Injectable for tests / non-window realms. Defaults to navigator.locks. */
+    locks?: LockManager;
+}
+/**
+ * ProcessSingleton over the Web Locks API. The owner holds an exclusive lock
+ * named for the profile until release() or realm death; contenders ask with
+ * ifAvailable and stand down instead of queueing, mirroring Chrome's
+ * startup-time claim.
+ */
+declare class WebLocksProcessSingleton implements ProcessSingleton {
+    private readonly name_;
+    private readonly locks_;
+    private acquirePromise_;
+    private releaseHold_;
+    private released_;
+    constructor(options: WebLocksProcessSingletonOptions);
+    acquire(): Promise<ProcessSingletonResult>;
+    /**
+     * Claim with bounded retries. Chrome's POSIX singleton retries its claim
+     * the same way — kRetryAttempts with timeout/retry_attempts sleeps
+     * (process_singleton_posix.cc:137-140, :794) — because a dying holder's
+     * lock disappears asynchronously. Web Lock releases also propagate
+     * asynchronously (the holder resolves its callback promise), so a realm
+     * booting right after another one released (HMR, dispose-then-reconstruct)
+     * needs a beat before the lock reads as free. A lock still held after the
+     * final attempt belongs to a live realm: stand down.
+     */
+    private acquireWithRetries_;
+    private tryClaim_;
+    release(): void;
+}
+/**
+ * The default wiring: Web Locks keyed by the backend's profile name when the
+ * platform has them, otherwise sole ownership (SSR, Node, older browsers —
+ * today's behavior).
+ */
+declare function createDefaultProcessSingleton(profileLockName: string | undefined): ProcessSingleton | null;
+
+/**
+ * Web Storage backend: persists the command log to localStorage (default) or
+ * sessionStorage. Both slots hold a JSON envelope `{version, commands}`; a
+ * write replaces the whole value, so unlike Chrome's incremental file we
+ * never need the trailing validity marker (command_storage_backend.cc writes
+ * kInitialStateMarkerCommandId to detect torn writes) — setItem is atomic.
+ *
+ * Synchronous on purpose: a pagehide flush only works reliably when the
+ * write completes before the handler returns.
+ */
+
+interface WebStorageBackendOptions {
+    /** Key prefix; slots live at `<key>/current` and `<key>/last`. */
+    key?: string;
+    /** Storage area to use. Defaults to window.localStorage. */
+    storage?: Storage;
+}
+declare class WebStorageBackend implements CommandStorageBackend {
+    /** Two realms over the same key contend for the same profile singleton. */
+    readonly profileLockName: string;
+    private readonly storage_;
+    private readonly currentKey_;
+    private readonly lastKey_;
+    /** Parsed mirror of the current slot, so appends don't re-parse. */
+    private currentCache_;
+    constructor(options?: WebStorageBackendOptions);
+    appendCommands(commands: readonly SessionCommand[], truncate: boolean): void;
+    readLastSessionCommands(): ReadCommandsResult;
+    moveCurrentSessionToLastSession(): void;
+    private readSlot_;
+}
+
+/**
+ * Turns a restored SessionWindow back into live tabs. Ported from
+ * chromium-reference/chrome/browser/sessions/session_restore.cc
+ * (SessionRestoreImpl::RestoreTabsToBrowser / RestoreTab).
+ *
+ * Restore order mirrors Chrome: tabs are created in visual order with their
+ * pinned state (AddRestoredTab), groups are formed and given their visual
+ * data afterwards (RestoreTabGroupMetadata), then the selected tab is
+ * activated. Group ids are re-generated by the model — exactly like Chrome,
+ * which relabels every restored group via TabGroupId::GenerateNew() to avoid
+ * cross-session id collisions — so callers get a groupIdMap back.
+ */
+
+interface RestoreOptions<T> {
+    /**
+     * Builds the live data payload for a restored tab. Defaults to the
+     * persisted `data` value as-is. Tabs persisted with navigation tracking
+     * only can derive their payload from currentNavigationEntry(tab).
+     */
+    createTabData?: (tab: SessionTab) => T;
+    /**
+     * Keep the persisted tab ids (default). Ids already present in the model
+     * fall back to generated ones. Pass false to always generate fresh ids —
+     * Chrome's behavior, where restored tabs get new SessionIDs.
+     */
+    preserveTabIds?: boolean;
+    /**
+     * Restore non-selected tabs in the discarded state, the analog of Chrome's
+     * deferred TabLoader (background tabs exist but don't load until first
+     * activation). Default false: everything restores loaded.
+     */
+    deferLoading?: boolean;
+}
+interface RestoreResult {
+    tabsRestored: number;
+    /** Persisted tab id -> live tab id. Identity unless ids were regenerated. */
+    tabIdMap: Map<TabId, TabId>;
+    /** Persisted group id -> live group id (always regenerated by the model). */
+    groupIdMap: Map<TabGroupId, TabGroupId>;
+}
+/**
+ * Appends a SessionWindow's tabs to `model`. The model is typically empty;
+ * with existing tabs the restored ones are appended after them (Chrome
+ * restores into an existing browser the same way, session_restore.cc's
+ * initial_tab_count handling).
+ */
+declare function restoreSessionWindow<T>(model: TabStripModel<T>, window: SessionWindow, options?: RestoreOptions<T>): RestoreResult;
+
+/**
+ * SessionService: records TabStripModel mutations as a command log and reads
+ * the previous session back. Ported from
+ * chromium-reference/chrome/browser/sessions/session_service_base.cc and
+ * session_service.cc.
+ *
+ * In Chrome the service learns about tab changes through Browser /
+ * SessionTabHelper plumbing; here it is a TabStripModelObserver. Navigation
+ * events have no model-level source (tabs carry opaque `data`), so — exactly
+ * like SessionTabHelper driving SessionService — the embedding app reports
+ * them through navigateTab / updateTabNavigation / setSelectedNavigationIndex.
+ *
+ * Tab `data` is persisted automatically (kCommandSetTabData analog) on
+ * insert and on every data change, so apps that keep their url in `data`
+ * restore correctly with zero extra wiring.
+ *
+ * Deviation from Chrome: on inserts, moves, and removals we re-emit
+ * SetTabIndexInWindow for every tab whose index shifted, so the persisted
+ * visual order is always exact. Chrome tolerates stale indices and relies on
+ * periodic full rewrites; the in-buffer command swaps below keep our
+ * approach cheap.
+ */
+
+/** Commands between full log rewrites. Mirrors kWritesPerReset (session_service_base.cc:78). */
+declare const WRITES_PER_RESET = 250;
+/** Navigation entries persisted either side of the current one. Mirrors gMaxPersistNavigationCount. */
+declare const MAX_PERSISTED_NAVIGATIONS = 6;
+interface SessionServiceOptions<T> {
+    storage: CommandStorageBackend;
+    /**
+     * Converts tab data to a JSON-serializable value. Defaults to identity —
+     * fine when T is already plain JSON (e.g. `{ url: string }`).
+     */
+    serializeTabData?: (data: T, tab: Tab<T>) => unknown;
+    /** Inverse of serializeTabData, used by restoreInto. Defaults to identity. */
+    deserializeTabData?: (raw: unknown) => T;
+    /** Delay before buffered commands hit storage. Default SAVE_DELAY_MS (2500). */
+    saveDelayMs?: number;
+    /** Commands between full rewrites. Default WRITES_PER_RESET (250). */
+    writesPerReset?: number;
+    /** Navigation entries kept either side of current. Default 6. */
+    maxPersistedNavigations?: number;
+    /**
+     * Flush synchronously on window `pagehide` (web teardown gives timers no
+     * chance to fire). Default true when a window exists. Only effective with
+     * a synchronous backend such as WebStorageBackend.
+     */
+    flushOnPageHide?: boolean;
+    /** Observer-side failures are reported here instead of thrown. */
+    onError?: (error: unknown) => void;
+    /**
+     * Cross-realm coordination for the storage area — the ProcessSingleton
+     * port (process_singleton.h). Exactly one realm (browser tab) owns a
+     * profile; the rest become secondaries that neither rotate, write, nor
+     * restore it. Omit for the default: Web Locks keyed by
+     * storage.profileLockName when the platform has them, else sole ownership.
+     * Pass null to force sole ownership, or your own implementation for
+     * tests/custom environments.
+     */
+    processSingleton?: ProcessSingleton | null;
+}
+interface AttachOptions {
+    /** Identifies this model in the log. Default DEFAULT_WINDOW_ID. */
+    windowId?: SessionWindowId;
+}
+interface RestoreIntoOptions<T> extends RestoreOptions<T> {
+    /** Restore (and attach as) this window. Defaults to the first saved window. */
+    windowId?: SessionWindowId;
+}
+interface RestoreIntoResult extends RestoreResult {
+    /** False when there was no saved window to restore (e.g. first run). */
+    restored: boolean;
+    /** The full snapshot, for callers that also restore other windows. */
+    snapshot: SessionSnapshot;
+    /**
+     * 'owner' when this realm persists the session; 'secondary' when another
+     * realm already owns the storage area — this service then restored nothing
+     * and will record nothing.
+     */
+    ownership: ProcessSingletonResult;
+}
+declare class SessionService<T = unknown> {
+    private readonly storage_;
+    private readonly manager_;
+    private readonly serializeTabData_;
+    private readonly deserializeTabData_;
+    private readonly writesPerReset_;
+    private readonly maxPersistedNavigations_;
+    private readonly onError_;
+    /**
+     * Resolves once the profile claim is settled and, for the owner, the
+     * previous session has been rotated to the last slot.
+     */
+    private readonly ready_;
+    private readonly windows_;
+    private readonly navState_;
+    private readonly tabExtraData_;
+    private readonly windowExtraData_;
+    private activeWindowId_;
+    /** Mirrors rebuild_on_next_save_ (session_service_base.cc). */
+    private rebuildOnNextSave_;
+    private pageHideListener_;
+    private disposed_;
+    private readonly singleton_;
+    private ownership_;
+    /** Mirrors is_saving_enabled_ (session_service_base.h:337). */
+    private savingEnabled_;
+    constructor(options: SessionServiceOptions<T>);
+    /**
+     * Which side of the profile claim this service landed on: 'pending' until
+     * resolved, then 'owner' (this realm persists the session) or 'secondary'
+     * (another realm owns the storage area; this service records and restores
+     * nothing). Settled by the time getLastSession/restoreInto resolve.
+     */
+    get ownership(): 'pending' | ProcessSingletonResult;
+    /** Starts rotation; returns the pending promise when async, else null. */
+    private rotateNow_;
+    /** Port of SetSavingEnabled (session_service_base.cc:877). */
+    private setSavingEnabled_;
+    /**
+     * Starts recording a model under the given window id and schedules a full
+     * snapshot of its current state (the SetSavingEnabled(true) startup path,
+     * session_service_base.cc:412). Returns a detach function.
+     */
+    attach(model: TabStripModel<T>, options?: AttachOptions): () => void;
+    /**
+     * Stops recording a window. The window's commands stay in the log until
+     * the next full rewrite; use markWindowClosed first to drop it eagerly.
+     */
+    detach(windowId: SessionWindowId): void;
+    /**
+     * Records the window as closed and detaches it. Tab closes are committed
+     * alongside kCommandWindowClosed, mirroring CommitPendingCloses
+     * (session_service.cc) — otherwise the tabs' surviving commands would
+     * resurrect the window husk during rebuild.
+     */
+    markWindowClosed(windowId: SessionWindowId): void;
+    /** Records which window is active (kCommandSetActiveWindow). */
+    setActiveWindow(windowId: SessionWindowId): void;
+    /**
+     * Records that a tab committed a new navigation: forward history is pruned
+     * and the new entry becomes current — normal browser semantics. Untracked
+     * tab ids are ignored, like commands for untracked windows in Chrome.
+     */
+    navigateTab(tabId: TabId, entry: {
+        url: string;
+        title?: string;
+        state?: unknown;
+        timestamp?: number;
+    }): void;
+    /**
+     * Replaces-or-inserts one navigation entry by its index — e.g. the current
+     * page's title or scroll state changed in place. Mirrors
+     * UpdateTabNavigation (session_service.cc).
+     */
+    updateTabNavigation(tabId: TabId, navigation: SerializedNavigationEntry): void;
+    /** Records back/forward movement. Mirrors SetSelectedNavigationIndex. */
+    setSelectedNavigationIndex(tabId: TabId, index: number): void;
+    /** Removes `count` entries from index value `index`. Mirrors TabNavigationPathPruned. */
+    pruneTabNavigations(tabId: TabId, index: number, count: number): void;
+    setTabExtraData(tabId: TabId, key: string, value: string): void;
+    setWindowExtraData(windowId: SessionWindowId, key: string, value: string): void;
+    /** Replays the previous session's log. Mirrors GetLastSession. */
+    getLastSession(): Promise<SessionSnapshot>;
+    /**
+     * The one-call integration: restores the previous session's window into
+     * `model` (when there is one) and attaches the model so the new session is
+     * recorded. Restored navigation histories and extra data are re-adopted so
+     * they survive future log rewrites.
+     */
+    restoreInto(model: TabStripModel<T>, options?: RestoreIntoOptions<T>): Promise<RestoreIntoResult>;
+    /** Flushes buffered commands now (e.g. before an intentional teardown). */
+    saveNow(): Promise<void>;
+    /** True while commands are buffered awaiting the save timer. */
+    get hasPendingSave(): boolean;
+    /**
+     * Discards the log and rewrites it from live state. Mirrors
+     * ScheduleResetCommands (session_service_base.cc:404) +
+     * BuildCommandsFromBrowsers (cc:767).
+     */
+    scheduleResetCommands(): void;
+    /** Detaches everything and stops timers. Does not flush — saveNow() first if needed. */
+    dispose(): void;
+    private checkNotDisposed_;
+    private findTab_;
+    /** Replace-or-insert by navigation index (session_service_commands.cc:664). */
+    private insertNavigation_;
+    private serializeTab_;
+    /**
+     * Coalesces a new command with a buffered one when only the latest value
+     * matters. Port of ReplacePendingCommand (session_service_commands.cc:1344)
+     * — Chrome only handles UpdateTabNavigation and SetActiveWindow; the other
+     * last-write-wins commands here are this port's extension, safe because the
+     * rebuild treats each of them as a keyed assignment.
+     */
+    private replacePendingCommand_;
+    /** Mirrors SessionServiceBase::ScheduleCommand (session_service_base.cc:788). */
+    private scheduleCommand_;
+    /** SetTabIndexInWindow for every tab in [lo, hi] — see the header comment. */
+    private emitIndexRange_;
+    /** Dedup-cached SetSelectedTabInWindow, like session_service.cc. */
+    private maybeEmitSelectedTab_;
+    /**
+     * BuildCommandsForBrowser + BuildCommandsForTab
+     * (session_service_base.cc:672, :592), adapted to one TabStripModel.
+     */
+    private buildCommandsForWindow_;
+    private createObserver_;
+}
+
+export { type AttachOptions, CommandStorageBackend, CommandStorageManager, type CommandStorageManagerDelegate, type CommandStorageManagerOptions, InMemoryStorageBackend, MAX_PERSISTED_NAVIGATIONS, type ProcessSingleton, type ProcessSingletonResult, ReadCommandsResult, type RestoreIntoOptions, type RestoreIntoResult, type RestoreOptions, type RestoreResult, SAVE_DELAY_MS, SerializedNavigationEntry, SessionCommand, SessionService, type SessionServiceOptions, SessionSnapshot, SessionTab, SessionWindow, SessionWindowId, WRITES_PER_RESET, WebLocksProcessSingleton, type WebLocksProcessSingletonOptions, WebStorageBackend, type WebStorageBackendOptions, createDefaultProcessSingleton, restoreSessionWindow };