chromium-tabs 0.1.0

package/dist/core/index.d.cts

@@ -0,0 +1,761 @@
+/**
+ * Port of ui/base/models/list_selection_model.{h,cc}.
+ *
+ * Selection model represented as a list of indexes. In addition to the set of
+ * selected indices it maintains:
+ *
+ * - active: the index of the currently visible item, or null if nothing is
+ *   selected.
+ * - anchor: the index of the last item the user clicked on. Extending the
+ *   selection extends it from this index. Null if nothing is selected.
+ *
+ * Typically there is one selected item, in which case anchor and active are
+ * the same.
+ */
+declare class ListSelectionModel {
+    private selectedIndices_;
+    private active_;
+    private anchor_;
+    get anchor(): number | null;
+    setAnchor(anchor: number | null): void;
+    get active(): number | null;
+    setActive(active: number | null): void;
+    /** True if nothing is selected. */
+    get empty(): boolean;
+    get size(): number;
+    /** Selected indices in ascending order. */
+    selectedIndices(): number[];
+    /**
+     * Increments all indices >= index. Used when a new item is inserted.
+     * list_selection_model.cc:112
+     */
+    incrementFrom(index: number): void;
+    /**
+     * Shifts all indices > index down by 1; index itself is removed from the
+     * selection. Used when an item is removed. list_selection_model.cc:122
+     */
+    decrementFrom(index: number): void;
+    /** Sets the anchor, active and selection to index. */
+    setSelectedIndex(index: number | null): void;
+    isSelected(index: number): boolean;
+    /** Adds index to the selection without changing active or anchor. */
+    addIndexToSelection(index: number): void;
+    /** Adds [indexStart, indexEnd] inclusive without changing active or anchor. */
+    addIndexRangeToSelection(indexStart: number, indexEnd: number): void;
+    /** Removes index from the selection without changing active or anchor. */
+    removeIndexFromSelection(index: number): void;
+    /**
+     * Sets the selection to the range anchor..index. If there is no anchor,
+     * behaves like setSelectedIndex. list_selection_model.cc:171
+     */
+    setSelectionFromAnchorTo(index: number): void;
+    /**
+     * Makes sure anchor..index are selected, adding to the existing selection.
+     * list_selection_model.cc:186
+     */
+    addSelectionFromAnchorTo(index: number): void;
+    /**
+     * Invoked when `length` items move from oldIndex to newIndex. If moving to
+     * a greater index, newIndex is the index *after* removing the moved range.
+     * list_selection_model.cc:199
+     */
+    move(oldIndex: number, newIndex: number, length: number): void;
+    /** Clears the selection, anchor and active. */
+    clear(): void;
+    clone(): ListSelectionModel;
+    equals(other: ListSelectionModel): boolean;
+    /** 'active=X anchor=X selection=X X X...' — matches the C++ ToString. */
+    toString(): string;
+}
+
+/**
+ * Core types. Ported from chromium-reference/chrome/browser/ui/tabs/tab_enums.h
+ * and the supporting types in tab_strip_model.h.
+ *
+ * Chrome's tabs carry a WebContents. This library carries a generic `data: T`
+ * payload instead so it works for any application.
+ */
+/** Sentinel for "no tab" — mirrors TabStripModel::kNoTab. */
+declare const NO_TAB = -1;
+type TabId = string;
+type TabGroupId = string;
+/**
+ * How a tab is being opened. Trimmed from ui::PageTransition to the two
+ * qualities the TabStripModel actually branches on (tab_strip_model.cc:1731,
+ * 1786): link-like openings (inherit opener, insert adjacent) and typed/manual
+ * openings (append at end, transient opener at end-of-strip).
+ */
+type TabOpenCause = 'link' | 'typed' | 'other';
+/** Bitmask flags used when adding tabs. Mirrors AddTabTypes (tab_enums.h:42). */
+declare const AddTabFlags: {
+    readonly NONE: 0;
+    /** The tab should become the active tab. */
+    readonly ACTIVE: number;
+    /** The tab should be pinned. */
+    readonly PINNED: number;
+    /**
+     * Use the caller-supplied index rather than letting the model determine
+     * the position from the open cause and opener relationships.
+     */
+    readonly FORCE_INDEX: number;
+    /** Set the new tab's opener to the currently active tab. */
+    readonly INHERIT_OPENER: number;
+};
+/** Bitmask flags used when closing tabs. Mirrors TabCloseTypes (tab_enums.h:26). */
+declare const CloseTabFlags: {
+    readonly NONE: 0;
+    /** The close was triggered directly by a user gesture. */
+    readonly USER_GESTURE: number;
+};
+/**
+ * Visual data attached to a tab group. Mirrors tab_groups::TabGroupVisualData.
+ * Chrome cycles through 9 named colors; we keep the names so UIs can map them
+ * to whatever palette they like.
+ */
+type TabGroupColor = 'grey' | 'blue' | 'red' | 'yellow' | 'green' | 'pink' | 'purple' | 'cyan' | 'orange';
+declare const TAB_GROUP_COLORS: readonly TabGroupColor[];
+interface TabGroupVisualData {
+    title: string;
+    color: TabGroupColor;
+    isCollapsed: boolean;
+}
+/**
+ * A tab in the strip. Identity is the object (like Chrome's TabModel pointer);
+ * `id` exists for React keys and serialization.
+ */
+interface Tab<T = unknown> {
+    readonly id: TabId;
+    /** Application payload (your "WebContents"). */
+    data: T;
+    /** The tab that opened this tab, if tracked. Mirrors TabModel::opener(). */
+    opener: Tab<T> | null;
+    /**
+     * When true, the opener relationship is cleared the next time the active
+     * tab changes. Set for typed new-tabs at end of strip ("quick look-up"
+     * pattern, tab_strip_model.cc:1804-1810).
+     */
+    resetOpenerOnActiveTabChange: boolean;
+    /** Pinned tabs are locked to the left side of the strip. */
+    pinned: boolean;
+    /** Group membership, if any. Pinned tabs are never grouped. */
+    group: TabGroupId | null;
+    /** Blocked by a modal — selectable but flagged. Mirrors TabModel::blocked. */
+    blocked: boolean;
+    /**
+     * True when the tab's content has been dropped to save memory. The tab
+     * stays in the strip (title intact via `data`); content remounts fresh
+     * when the tab is next activated. Mirrors TabLifecycleUnit::is_discarded_
+     * (tab_lifecycle_unit.cc:312) and WebContents::WasDiscarded.
+     */
+    discarded: boolean;
+    /**
+     * Wall-clock ms of the last time this tab stopped being active, or
+     * Infinity while it is active. Used for least-recently-used discard
+     * ordering. Mirrors last_focused_time_ (tab_lifecycle_unit.cc:142, which
+     * uses Time::Max() while focused).
+     */
+    lastActiveAt: number;
+    /**
+     * Per-tab opt-out from automatic discarding. Mirrors
+     * TabLifecycleUnit::auto_discardable_ (the extensions setAutoDiscardable
+     * API surface).
+     */
+    autoDiscardable: boolean;
+}
+interface TabGroup {
+    readonly id: TabGroupId;
+    visualData: TabGroupVisualData;
+}
+/** Options for TabStripModel.addTab / insertTabAt. */
+interface AddTabOptions {
+    /** Target index. Omit (or pass NO_TAB) to let the model decide. */
+    index?: number;
+    /** What kind of action opened this tab. Default 'other'. */
+    cause?: TabOpenCause;
+    /** Bitmask of AddTabFlags. */
+    flags?: number;
+    /** Insert directly into an existing group. */
+    group?: TabGroupId;
+    /** Stable id; generated if omitted. */
+    id?: TabId;
+}
+/** Desired state of one tab, for TabStripModel.reconcile. */
+interface ReconcileTab<T> {
+    id: TabId;
+    data: T;
+    /** Defaults to false. The list should be pinned-first-consistent. */
+    pinned?: boolean;
+}
+interface ReconcileOptions<T> {
+    /** Tab to end up active. Omit to leave activation to the model. */
+    activeId?: TabId | null;
+    /** Equality for data payloads; defaults to Object.is. */
+    dataEquals?: (a: T, b: T) => boolean;
+}
+interface TabStripModelOptions<T> {
+    /**
+     * Veto tab closes (Chrome: IsTabClosable / policy). Return false to keep
+     * the tab open; observers get a tabCloseCancelled event.
+     */
+    canCloseTab?: (tab: Tab<T>) => boolean;
+    /** Disable the group feature entirely (Chrome: null TabGroupModelFactory). */
+    supportsGroups?: boolean;
+    /** Custom id generator for tabs and groups. */
+    generateId?: () => string;
+}
+
+/**
+ * Observer event types. Ported from
+ * chromium-reference/chrome/browser/ui/tabs/tab_strip_model_observer.h.
+ *
+ * Changes to (1) the selection model, (2) the active tab, and (3) the set of
+ * tabs are bundled into a single onTabStripModelChanged call because the
+ * first two consist of indices into the list determined by the third.
+ */
+
+/** Mirrors TabStripModelChange::Type. */
+type TabStripModelChange<T> = {
+    type: 'selectionOnly';
+} | {
+    /**
+     * Tabs were inserted at the given indices (index is the position at the
+     * time of that insertion, see tab_strip_model_observer.h:88).
+     */
+    type: 'inserted';
+    contents: Array<{
+        tab: Tab<T>;
+        index: number;
+    }>;
+} | {
+    /**
+     * Tabs were removed; index is the position at the time of that removal
+     * (tab_strip_model_observer.h:123).
+     */
+    type: 'removed';
+    contents: Array<{
+        tab: Tab<T>;
+        index: number;
+    }>;
+} | {
+    type: 'moved';
+    tab: Tab<T>;
+    fromIndex: number;
+    toIndex: number;
+} | {
+    type: 'replaced';
+    tab: Tab<T>;
+    oldData: T;
+    newData: T;
+    index: number;
+};
+/** Mirrors TabStripSelectionChange. */
+interface TabStripSelectionChange<T> {
+    oldTab: Tab<T> | null;
+    newTab: Tab<T> | null;
+    oldModel: ListSelectionModel;
+    newModel: ListSelectionModel;
+    /** Mirrors TabStripModelObserver::CHANGE_REASON_USER_GESTURE. */
+    reason: 'none' | 'userGesture';
+    get activeTabChanged(): boolean;
+    get selectionChanged(): boolean;
+}
+/** Mirrors TabGroupChange::Type (minus editor-UI concerns). */
+type TabGroupChange = {
+    type: 'created';
+    groupId: TabGroupId;
+} | {
+    type: 'visualsChanged';
+    groupId: TabGroupId;
+    oldVisuals: TabGroupVisualData;
+    newVisuals: TabGroupVisualData;
+} | {
+    type: 'moved';
+    groupId: TabGroupId;
+} | {
+    type: 'closed';
+    groupId: TabGroupId;
+};
+type CloseAllStoppedReason = 'completed' | 'canceled';
+/**
+ * Observer interface. All methods optional — implement what you need.
+ * Mirrors TabStripModelObserver.
+ */
+interface TabStripModelObserver<T> {
+    onTabStripModelChanged?(change: TabStripModelChange<T>, selection: TabStripSelectionChange<T>): void;
+    /** A tab's pinned state changed. Fired after any accompanying move. */
+    onTabPinnedStateChanged?(tab: Tab<T>, index: number): void;
+    /** A tab entered or left a group. */
+    onTabGroupedStateChanged?(oldGroup: TabGroupId | null, newGroup: TabGroupId | null, tab: Tab<T>, index: number): void;
+    /** Group lifecycle and visual changes. */
+    onTabGroupChanged?(change: TabGroupChange): void;
+    /** A tab's data payload or blocked state changed in place. */
+    onTabChanged?(tab: Tab<T>, index: number): void;
+    /**
+     * A tab was discarded (content dropped to save memory) or restored.
+     * Mirrors TabLifecycleObserver::OnDiscardedStateChange.
+     */
+    onTabDiscardedStateChanged?(tab: Tab<T>, index: number, discarded: boolean): void;
+    /** A close was vetoed by canCloseTab. */
+    onTabCloseCancelled?(tab: Tab<T>): void;
+    /** CloseAllTabs is starting. */
+    willCloseAllTabs?(): void;
+    /** CloseAllTabs finished or was canceled by a veto. */
+    closeAllTabsStopped?(reason: CloseAllStoppedReason): void;
+}
+
+/**
+ * Port of chrome/browser/ui/tabs/tab_strip_model.{h,cc} (Chromium main
+ * @ 3dbd2135). Line references in comments point into chromium-reference/.
+ *
+ * Differences from Chrome are listed in PORTING_NOTES.md. The big ones:
+ * tabs carry generic `data: T` instead of WebContents, split tabs are not
+ * ported, and there is no async unload-handler dance — closes are
+ * synchronous, vetoable via `canCloseTab`.
+ *
+ * Like Chrome, the model maintains these invariants:
+ * - all pinned tabs occur before all non-pinned tabs
+ * - tabs of a group are contiguous, and never pinned
+ * - the active tab is always valid while the strip is non-empty
+ */
+
+/** [start, end) index range, mirroring gfx::Range usage for group spans. */
+interface IndexRange {
+    start: number;
+    end: number;
+}
+interface ActivateOptions {
+    /**
+     * Marks the activation as a direct user gesture. Mirrors
+     * TabStripUserGestureDetails; gates the opener-forgetting heuristic
+     * (tab_strip_model.cc:5301).
+     */
+    userGesture?: boolean;
+}
+declare class TabStripModel<T = unknown> {
+    private tabs_;
+    private groups_;
+    private selectedTabs_;
+    private activeTab_;
+    private anchorTab_;
+    private observers_;
+    private closingAll_;
+    private reentrancyGuard_;
+    private readonly canCloseTab_;
+    private readonly supportsGroups_;
+    private readonly generateId_;
+    constructor(options?: TabStripModelOptions<T>);
+    get count(): number;
+    get empty(): boolean;
+    /** True while closeAllTabs is in progress. */
+    get closingAll(): boolean;
+    containsIndex(index: number): boolean;
+    getTabAt(index: number): Tab<T>;
+    indexOfTab(tab: Tab<T> | null): number;
+    getTabById(id: TabId): Tab<T> | null;
+    /** Snapshot of the tabs in strip order. */
+    getTabs(): ReadonlyArray<Tab<T>>;
+    get activeTab(): Tab<T> | null;
+    get activeIndex(): number;
+    /** Index of the first non-pinned tab; count if all pinned. (cc:1418 area) */
+    indexOfFirstNonPinnedTab(): number;
+    isTabPinned(index: number): boolean;
+    isTabBlocked(index: number): boolean;
+    isTabSelected(index: number): boolean;
+    /** Derived index-based view of the selection (Chrome: GetListSelectionModel). */
+    selectionModel(): ListSelectionModel;
+    get supportsTabGroups(): boolean;
+    getTabGroupForTab(index: number): TabGroupId | null;
+    getGroups(): TabGroup[];
+    getGroupVisualData(group: TabGroupId): TabGroupVisualData | null;
+    containsGroup(group: TabGroupId): boolean;
+    /** [start, end) range of the group's tabs. Mirrors TabGroup::ListTabs. */
+    listTabsInGroup(group: TabGroupId): IndexRange;
+    isGroupCollapsed(group: TabGroupId): boolean;
+    /** True if the tab is inside a collapsed group. (cc:1423) */
+    isTabCollapsed(index: number): boolean;
+    /**
+     * If a tab inserted at index would land inside a group, returns that group.
+     * Returns null at the first index of a group (a tab there sits between
+     * groups, not inside one). Mirrors GetSurroundingTabGroup.
+     */
+    getSurroundingTabGroup(index: number): TabGroupId | null;
+    addObserver(observer: TabStripModelObserver<T>): () => void;
+    removeObserver(observer: TabStripModelObserver<T>): void;
+    /**
+     * Command-level add: picks the position from the open cause and opener
+     * relationships, then inserts. Port of AddTab (cc:1715-1828).
+     */
+    addTab(data: T, options?: AddTabOptions): Tab<T>;
+    /** Adds a tab at the end of the strip. Port of AppendTab. */
+    appendTab(data: T, foreground?: boolean): Tab<T>;
+    /**
+     * Inserts at the given index, only adjusting it to keep pinned tabs at the
+     * front. Does NOT consult the order controller. Port of InsertWebContentsAt.
+     * Returns the index actually used.
+     */
+    insertTabAt(index: number, data: T, options?: Omit<AddTabOptions, 'index' | 'cause'>): Tab<T>;
+    /** Makes the tab at index active. Port of ActivateTabAt (cc:1022). */
+    activateTabAt(index: number, options?: ActivateOptions): void;
+    /** Extends the selection from the anchor to index. Port of cc:1514. */
+    extendSelectionTo(index: number): void;
+    /** Adds the tab at index to the selection and makes it active+anchor. (cc:1545) */
+    selectTabAt(index: number): void;
+    /** Removes the tab at index from the selection. No-op if it's the last one. (cc:1570) */
+    deselectTabAt(index: number): void;
+    /** Selects anchor..index, adding to the current selection. (cc:1616) */
+    addSelectionFromAnchorTo(index: number): void;
+    /** Replaces the selection with the given index-based model. */
+    setSelectionFromModel(source: ListSelectionModel): void;
+    /**
+     * Activates the next/previous tab, wrapping around and skipping collapsed
+     * groups. Port of SelectRelativeTab (cc:3951).
+     */
+    selectNextTab(options?: ActivateOptions): void;
+    selectPreviousTab(options?: ActivateOptions): void;
+    selectLastTab(options?: ActivateOptions): void;
+    private selectRelativeTab_;
+    /**
+     * Moves the tab at index to toPosition (clamped so pinned tabs stay
+     * together). Group membership adjusts to keep groups contiguous. Port of
+     * MoveWebContentsAt (cc:1053). Returns the final index.
+     */
+    moveTabTo(index: number, toPosition: number, selectAfterMove?: boolean): number;
+    /**
+     * Moves the selected tabs to index, pinned tabs first as a chunk, then
+     * unpinned. `index` is interpreted as if the strip did not contain the
+     * selected tabs. Port of MoveSelectedTabsTo (cc:1089).
+     */
+    moveSelectedTabsTo(index: number, group?: TabGroupId | null): void;
+    /** Moves all tabs of a group to toIndex. Port of MoveGroupTo (cc:1117). */
+    moveGroupTo(group: TabGroupId, toIndex: number): void;
+    /**
+     * Moves the active tab one slot right/left. At a group boundary the tab
+     * first changes group membership without moving; collapsed neighbor groups
+     * are hopped over entirely. Port of MoveTabRelative (cc:3976).
+     */
+    moveTabNext(): void;
+    moveTabPrevious(): void;
+    private moveTabRelative_;
+    /**
+     * Pins or unpins the tab, moving it to the pinned/unpinned boundary.
+     * Pinning removes the tab from its group. Returns the final index.
+     * Port of SetTabPinned (cc:1407) + SetTabPinnedImpl (cc:5052).
+     */
+    setTabPinned(index: number, pinned: boolean): number;
+    /** Closes the tab at index. Returns true if it closed (not vetoed). */
+    closeTabAt(index: number): boolean;
+    /** Closes the tabs at the given indices. */
+    closeTabsAt(indices: number[]): boolean;
+    /** Port of CloseSelectedTabs. */
+    closeSelectedTabs(): boolean;
+    /** Port of CloseAllTabs (cc:455). */
+    closeAllTabs(): boolean;
+    /** Context-menu style helper: close every tab except the one at index. */
+    closeOtherTabs(index: number): boolean;
+    /** Context-menu style helper: close unpinned tabs to the right of index. */
+    closeTabsToRight(index: number): boolean;
+    /** Closes all tabs in a group. Port of CloseAllTabsInGroup. */
+    closeAllTabsInGroup(group: TabGroupId): boolean;
+    private closeTabs_;
+    /**
+     * Removes the tab and fixes up the selection. Port of
+     * RemoveTabFromIndexImpl (cc:4551). Caller batches notifications.
+     */
+    private removeTabFromIndexImpl_;
+    /**
+     * Converges the strip to an external source-of-truth list with minimal
+     * mutations (no remove-all/re-add), so an app whose canonical tab state
+     * lives elsewhere (a router, a store, another window) can mirror it into
+     * the model without losing tab identity, content state, or discard status.
+     *
+     * - tabs absent from `desired` are removed, bypassing `canCloseTab` (the
+     *   external state has already decided)
+     * - missing tabs are inserted at their position under the given id
+     * - `data` is swapped via setTabData where `dataEquals` reports a change
+     * - pinned state and order converge to the desired list; pass a
+     *   pinned-first-consistent list or Chrome's clamping rules win
+     * - `activeId`, when provided and present, is activated last
+     *
+     * Observers fire for each underlying mutation as usual; reconcile-driven
+     * activations carry reason 'none', so a consumer that also writes model
+     * changes back to the external store can tell them from user gestures.
+     * Groups are not reconciled. No Chrome equivalent: this is integration
+     * surface for embedding apps.
+     */
+    reconcile(desired: ReadonlyArray<ReconcileTab<T>>, options?: ReconcileOptions<T>): void;
+    getOpenerOfTabAt(index: number): Tab<T> | null;
+    setOpenerOfTabAt(index: number, opener: Tab<T> | null): void;
+    /** Port of ForgetAllOpeners (cc:3376). */
+    forgetAllOpeners(): void;
+    forgetOpener(tab: Tab<T>): void;
+    /**
+     * Call when the user navigates a tab. Typed-style navigations reset all
+     * opener relationships (the user started a new task), except in a fresh
+     * end-of-strip tab. Port of TabNavigating (cc:1378).
+     */
+    tabNavigating(tab: Tab<T>, cause: TabOpenCause): void;
+    /**
+     * Index of the last tab opened (transitively) by the tab at startIndex,
+     * scanning right, skipping pinned tabs, stopping at the first unrelated
+     * unpinned tab. Port of GetIndexOfLastWebContentsOpenedBy (cc:1351).
+     */
+    getIndexOfLastTabOpenedBy(opener: Tab<T>, startIndex: number): number;
+    /**
+     * Creates a group containing the tabs at indices (ascending). Tabs are
+     * unpinned and made contiguous without splitting other groups. Returns the
+     * group id. Port of AddToNewGroup (cc:671) + AddToNewGroupImpl (cc:4344).
+     */
+    addToNewGroup(indices: number[], visualData?: Partial<TabGroupVisualData>): TabGroupId;
+    /**
+     * Adds the tabs at indices (ascending) to an existing group. Tabs left of
+     * the group move to its start, tabs right of it to its end; addToEnd sends
+     * everything to the end. Port of AddToExistingGroup (cc:4415).
+     */
+    addToExistingGroup(indices: number[], group: TabGroupId, addToEnd?: boolean): void;
+    /**
+     * Removes the tabs at indices (ascending) from their groups. Tabs in the
+     * first half of a group exit left of it, the rest exit right. Port of
+     * RemoveFromGroup (cc:4253 area) + SeparateTabsByVisualPosition.
+     */
+    removeFromGroup(indices: number[]): void;
+    /** Updates a group's title/color/collapsed state. Port of ChangeTabGroupVisuals. */
+    updateGroupVisuals(group: TabGroupId, visuals: Partial<TabGroupVisualData>): void;
+    setGroupCollapsed(group: TabGroupId, collapsed: boolean): void;
+    /** Chrome's TabGroupModel::GetNextColor: least-used color, in palette order. */
+    private nextGroupColor_;
+    /** Swaps the tab's data payload. Emits a 'replaced' change (Chrome: Replace). */
+    setTabData(index: number, data: T): void;
+    /** Notify observers the tab changed in place (after mutating tab.data). */
+    notifyTabChanged(index: number): void;
+    /** Port of SetTabBlocked (cc:1397). */
+    setTabBlocked(index: number, blocked: boolean): void;
+    /**
+     * Drops the tab's content to save memory while keeping the tab in the
+     * strip. The active tab cannot be discarded (it's visible). Content
+     * remounts fresh on the next activation, like Chrome's reload-on-focus.
+     * Port of TabLifecycleUnit::Discard (tab_lifecycle_unit.cc:346) +
+     * TabStripModel::DiscardWebContentsAt semantics. Returns true on success.
+     */
+    discardTabAt(index: number): boolean;
+    /**
+     * Restores a discarded tab without activating it (Chrome: reloading a
+     * background discarded tab, DidStartLoading path).
+     */
+    restoreTabAt(index: number): boolean;
+    /** Per-tab opt-out from automatic discarding (extensions setAutoDiscardable). */
+    setTabAutoDiscardable(index: number, autoDiscardable: boolean): void;
+    isTabDiscarded(index: number): boolean;
+    /** Number of tabs whose content is currently live (not discarded). */
+    get loadedTabCount(): number;
+    private restoreTab_;
+    /**
+     * Where to place a newly opened tab. Port of DetermineInsertionIndex
+     * (cc:5329).
+     */
+    determineInsertionIndex(cause: TabOpenCause, foreground: boolean): number;
+    /**
+     * Which tab should become active after the tab at `index` closes.
+     * Port of DetermineNewSelectedIndex (cc:5377), single-tab block, with the
+     * "parent collection" preference specialized to groups. Returns the index
+     * in post-close coordinates, or null if this is the last tab.
+     */
+    private determineNewSelectedIndex_;
+    /** Port of GetIndexOfNextWebContentsOpenedBy (cc:3286). */
+    private getIndexOfNextTabOpenedBy_;
+    /** Port of GetIndexOfNextWebContentsOpenedByOpenerOf (cc:3312). */
+    private getIndexOfNextTabOpenedByOpenerOf_;
+    /** Port of GetNextExpandedActiveTab (cc:3346): right of block, then left. */
+    private getNextExpandedActiveTab_;
+    private createTab_;
+    /** Port of ConstrainInsertionIndex (cc:3408). */
+    private constrainInsertionIndex_;
+    /** Port of ConstrainMoveIndex (cc:3413). */
+    private constrainMoveIndex_;
+    /** Port of InsertTabAtImpl (cc:3575). Returns the index actually used. */
+    private insertTabAtImpl_;
+    /**
+     * Single-tab move with explicit final group/pin state. Port of
+     * MoveTabToIndexImpl (cc:4617).
+     */
+    private moveTabToIndexImpl_;
+    /**
+     * Block move: removes the tabs at `indices`, reinserts them contiguously at
+     * `destination` (post-removal coordinates), assigning the given group and
+     * the pinned state of the first moving tab. Port of MoveTabsToIndexImpl
+     * (cc:4698) + MoveTabsWithNotifications (cc:5081).
+     */
+    private moveTabsToIndexImpl_;
+    /**
+     * Port of MoveTabsAndSetPropertiesImpl (cc:4469): destination is given in
+     * pre-removal coordinates and adjusted here.
+     */
+    private moveTabsAndSetProperties_;
+    /**
+     * Group to assign when a tab moves from index to toPosition so groups stay
+     * contiguous. Port of GetGroupToAssign (cc:5195).
+     */
+    private getGroupToAssign_;
+    /**
+     * Re-points the openers of any tab that referenced the tab at index at that
+     * tab's own opener. Port of FixOpeners (cc:5171).
+     */
+    private fixOpeners_;
+    /** Selection helpers (Chrome: TabStripModelSelectionState). */
+    private setSelectedTab_;
+    private firstSelectedTab_;
+    private selectedIndices_;
+    /**
+     * Wraps a selection mutation in change tracking + notification. Mirrors
+     * SetSelection (cc:1178).
+     */
+    private setSelection_;
+    private buildSelectionChange_;
+    /**
+     * Opener and lifecycle bookkeeping when the active tab changes. Port of
+     * OnActiveTabChanged (cc:5255) plus TabLifecycleUnit::SetFocused
+     * (tab_lifecycle_unit.cc:135).
+     */
+    private handleActiveTabChanged_;
+    private emitGroupStateChange_;
+    private notifyAll_;
+    private requireGroups_;
+    private checkReentrancy_;
+    /**
+     * Invariant validation. Port of CompleteModelUpdateTransaction; Chrome
+     * CHECKs, we throw.
+     */
+    private validate_;
+}
+
+/**
+ * Automatic tab discarding. Port of Chrome's tab lifecycle stack:
+ *
+ * - chrome/browser/resource_coordinator/tab_manager.cc (orchestration)
+ * - chrome/browser/performance_manager/policies/discard_eligibility_policy.h
+ *   (CanDiscardResult tri-state, CannotDiscardReason, the importance sort in
+ *   PageNodeSortProxy::operator<, kNonVisiblePagesUrgentProtectionTime)
+ * - chrome/browser/resource_coordinator/tab_lifecycle_unit.cc (discard
+ *   mechanics live on the model as discardTabAt/restore-on-focus)
+ *
+ * Chrome triggers discards on OS memory pressure, which the web platform
+ * does not expose reliably. The deterministic equivalent is a budget on the
+ * number of loaded (mounted) tabs: when `maxLoadedTabs` is exceeded, the
+ * least important tabs are discarded, in exactly Chrome's importance order.
+ */
+
+/** Mirrors LifecycleUnitDiscardReason (minus Chrome-internal variants). */
+type DiscardReason = 'proactive' | 'urgent' | 'external';
+/** Trimmed CannotDiscardReason (cannot_discard_reason.h). */
+type CannotDiscardReason = 'activeTab' | 'alreadyDiscarded' | 'optedOut' | 'appVeto' | 'pinnedTab' | 'recentlyActive';
+/** Mirrors CanDiscardResult (discard_eligibility_policy.h:56). */
+type CanDiscardResult = 'eligible' | 'protected' | 'disallowed';
+interface CanDiscardDecision {
+    result: CanDiscardResult;
+    reasons: CannotDiscardReason[];
+}
+interface TabLifecycleOptions<T> {
+    /**
+     * Maximum number of tabs whose content stays loaded at once. Exceeding it
+     * triggers automatic discarding of the least important tabs. Pass null to
+     * disable automatic discarding (manual discardLeastImportant still works).
+     * Chrome's equivalent trigger is OS memory pressure.
+     */
+    maxLoadedTabs?: number | null;
+    /**
+     * Tabs active within this window are protected (not disallowed) from
+     * discarding. Mirrors kNonVisiblePagesUrgentProtectionTime, 10 minutes on
+     * desktop (discard_eligibility_policy.h:38).
+     */
+    recentlyActiveProtectionMs?: number;
+    /**
+     * Protect pinned tabs (CannotDiscardReason::kPinnedTab). Protected tabs
+     * are only discarded when eligible tabs alone can't satisfy the budget.
+     */
+    protectPinnedTabs?: boolean;
+    /**
+     * App-level veto, the equivalent of the protections Chrome detects in the
+     * renderer (playing audio, form input, user edits, capturing, PiP...).
+     * Return false to disallow discarding a tab.
+     */
+    canDiscardTab?: (tab: Tab<T>) => boolean;
+    /**
+     * Called just before a tab's content is dropped, the equivalent of
+     * WebContents::AboutToBeDiscarded. Last chance to snapshot restorable
+     * state (scroll position, draft text) into tab.data.
+     */
+    onBeforeDiscard?: (tab: Tab<T>) => void;
+    /**
+     * Apps whose tab content shares global state per content type (a
+     * singleton store per route/scene) can return a key here: at most one
+     * non-discarded tab per distinct key stays loaded. Whenever two loaded
+     * tabs share a key, every one except the active (else the most recently
+     * active) is discarded immediately, and reload-on-focus re-derives each
+     * tab's state from its own `data` when it is next activated — shared
+     * state can then never bleed between two visible-at-once duplicates.
+     * Return null to exempt a tab (e.g. content that isolates correctly).
+     *
+     * This is a correctness policy, not a memory policy: it overrides the
+     * pinned/recently-active protections and the `canDiscardTab` veto (the
+     * active tab still always keeps its content). No Chrome equivalent —
+     * Chrome tabs never share renderer state.
+     */
+    exclusiveContentKey?: (tab: Tab<T>) => string | null;
+}
+declare class TabLifecycleManager<T = unknown> {
+    private readonly model_;
+    private readonly maxLoadedTabs_;
+    private readonly recentlyActiveProtectionMs_;
+    private readonly protectPinnedTabs_;
+    private readonly canDiscardTab_;
+    private readonly onBeforeDiscard_;
+    private readonly exclusiveContentKey_;
+    private detach_;
+    private enforcePending_;
+    constructor(model: TabStripModel<T>, options?: TabLifecycleOptions<T>);
+    /**
+     * Starts observing the model and enforcing the loaded-tab budget. Returns
+     * a stop function. Discards run on a microtask after model changes, never
+     * re-entrantly (Chrome posts discard tasks for the same reason).
+     */
+    start(): () => void;
+    stop(): void;
+    /**
+     * Tri-state discard eligibility for one tab. Port of
+     * DiscardEligibilityPolicy::CanDiscard.
+     */
+    canDiscard(tab: Tab<T>): CanDiscardDecision;
+    /**
+     * Discard candidates in Chrome's importance order, least important first:
+     * eligible before protected, each group least-recently-active first,
+     * disallowed never. Port of PageNodeSortProxy::operator<
+     * (discard_eligibility_policy.h:95) with focused/visible folded into
+     * 'activeTab' (a single-window strip has one visible tab).
+     */
+    getDiscardCandidates(includeProtected: boolean): Array<Tab<T>>;
+    /**
+     * Discards the least important discardable tab. 'urgent' may take
+     * protected tabs (Chrome: urgent discarding under memory pressure);
+     * 'proactive' and 'external' only take eligible ones. Port of
+     * PageDiscardingHelper::DiscardAPage. Returns the discarded tab or null.
+     */
+    discardLeastImportant(reason?: DiscardReason): Tab<T> | null;
+    /**
+     * Discards tabs until the loaded count fits the budget. Eligible tabs go
+     * first; protected tabs are taken only if the budget still isn't met
+     * (matching the sort order Chrome walks when reclaiming memory).
+     * Disallowed tabs are never discarded, so the budget can be exceeded when
+     * everything left is active/opted-out/vetoed.
+     */
+    enforceBudget(): number;
+    /**
+     * Enforces `exclusiveContentKey`: for every key shared by more than one
+     * loaded tab, keep the active tab (else the most recently active) and
+     * discard the rest. Returns the number of tabs discarded. Runs before the
+     * budget pass, so duplicates count toward freed budget first.
+     */
+    enforceExclusiveContent(): number;
+    private discardTab_;
+    private scheduleEnforce_;
+}
+
+export { AddTabFlags, type AddTabOptions, type CanDiscardDecision, type CanDiscardResult, type CannotDiscardReason, type CloseAllStoppedReason, CloseTabFlags, type DiscardReason, type IndexRange, ListSelectionModel, NO_TAB, type ReconcileOptions, type ReconcileTab, TAB_GROUP_COLORS, type Tab, type TabGroup, type TabGroupChange, type TabGroupColor, type TabGroupId, type TabGroupVisualData, type TabId, TabLifecycleManager, type TabLifecycleOptions, type TabOpenCause, TabStripModel, type TabStripModelChange, type TabStripModelObserver, type TabStripModelOptions, type TabStripSelectionChange };