@pixpilot/chrome-lifecycle 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -1 +1 @@
-const e=new Map;let t=!1;function n(){t||(t=!0,chrome.windows.onRemoved.addListener(t=>{let n=e.get(t);n&&(n.forEach(e=>{e()}),e.delete(t))}))}function r(t,r){n();let i=e.get(t);return i||(i=new Set,e.set(t,i)),i.add(r),()=>{let n=e.get(t);n&&(n.delete(r),n.size===0&&e.delete(t))}}const i=250,a=5e3,o=2;let s=!1;function c(e={}){if(s)return console.info(`Side panel state tracker already initialized`),()=>{};s=!0;let{trackDocumentVisibility:t=!0}=e,n,r,i=0,a,o=!1;function c(){r&&=(clearTimeout(r),void 0)}return chrome.windows.getCurrent(e=>{if(o)return;if(e.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}let s=e.id;function l(){return t&&document.hidden?`hidden`:`visible`}function u(){if(o||r)return;n=void 0,console.info(`[side-panel-state-tracker] Connection to background lost, scheduling reconnect...`);let e=Math.min(250*2**i,5e3);i+=1,r=setTimeout(()=>{r=void 0,f(`reconnected`)},e)}function d(e){let t=n;if(!t){u();return}try{t.postMessage({...e,windowId:s,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e),u()}}function f(e){if(!o){c();try{let t=chrome.runtime.connect({name:chrome.runtime.id});n=t,i=0,t.onDisconnect.addListener(()=>{n===t&&(console.info(`[side-panel-state-tracker] Background connection lost.`),u())}),t.onMessage.addListener(e=>{e.type===`close-side-panel`&&(o=!0,c(),window.close())}),d({state:e===`document-load`?`visible`:l(),reason:e})}catch(e){console.error(`[side-panel-state-tracker] Failed to connect:`,e),u()}}}t&&(a=()=>{d({state:l(),reason:`visibility-change`})},document.addEventListener(`visibilitychange`,a)),f(`document-load`)}),()=>{o=!0,c(),a&&document.removeEventListener(`visibilitychange`,a);let e=n;n=void 0,e?.disconnect(),s=!1}}const l=new Map,u=new Map,d=new Set;let f=!1;function p(){f||(f=!0,chrome.action.onClicked.addListener(e=>{let t=l.get(e.windowId);t&&t.state===`visible`?t.port&&(l.delete(e.windowId),t.port.postMessage({type:`close-side-panel`})):chrome.sidePanel.open({windowId:e.windowId}).catch(console.error)}),chrome.runtime.onConnect.addListener(e=>{e.name===chrome.runtime.id&&(e.onMessage.addListener(t=>{t.type===`side-panel-state-tracker`&&t.state&&g({port:e,state:t.state,reason:t.reason??`unknown`,windowId:t.windowId,type:t.type})}),e.onDisconnect.addListener(e=>{Array.from(l.entries()).forEach(([t,n])=>{n.port&&n.port===e&&g({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:t,type:`side-panel-state-tracker`})})}))}),chrome.windows.onRemoved.addListener(e=>{l.delete(e),u.delete(e)}))}function m(){f||=(p(),!0)}function h(e,t){if(e.type!==`side-panel-state-tracker`)return;let n={state:e.state,reason:e.reason,windowId:e.windowId,previousState:t},r=e.state===t;d.forEach(({listener:e,includeRepeats:t})=>{if(!(r&&!t))try{e(n)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function g(e){let{windowId:t,state:n}=e,r=u.get(t);if(e.type===`side-panel-state-tracker`&&u.set(t,n),n===`hidden`){l.delete(t),h(e,r);return}l.set(t,e),h(e,r)}function _(e){return m(),l.get(e)?.state}function v(e){return m(),_(e)===`visible`}function y(e,t={}){m();let n={listener:e,includeRepeats:t.includeRepeats===!0};return d.add(n),()=>{d.delete(n)}}function b(e){return y(t=>{t.state===`visible`&&t.previousState!==`visible`&&e(t)})}function x(e){return y(t=>{t.state===`hidden`&&t.previousState===`visible`&&e(t)})}exports.getSidePanelStateForWindow=_,exports.initSidePanelStateManager=p,exports.initializeSidePanelStateTracker=c,exports.isWindowSidePanelVisible=v,exports.onSidePanelHidden=x,exports.onSidePanelShown=b,exports.onSidePanelStateChange=y,exports.onWindowClose=r;
+const e=new Map,t=new Map,n=new Set;let r=!1;function i(){r||(r=!0,chrome.action.onClicked.addListener(t=>{let n=e.get(t.windowId);n&&n.state===`visible`?n.port&&(e.delete(t.windowId),n.port.postMessage({type:`close-side-panel`})):chrome.sidePanel.open({windowId:t.windowId}).catch(console.error)}),chrome.runtime.onConnect.addListener(t=>{t.name===chrome.runtime.id&&(t.onMessage.addListener(e=>{e.type===`side-panel-state-tracker`&&e.state&&s({port:t,state:e.state,reason:e.reason??`unknown`,windowId:e.windowId,type:e.type})}),t.onDisconnect.addListener(t=>{Array.from(e.entries()).forEach(([e,n])=>{n.port&&n.port===t&&s({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:e,type:`side-panel-state-tracker`})})}))}),chrome.windows.onRemoved.addListener(n=>{e.delete(n),t.delete(n)}))}function a(){r||=(i(),!0)}function o(e,t){if(e.type!==`side-panel-state-tracker`)return;let r={state:e.state,reason:e.reason,windowId:e.windowId,previousState:t},i=e.state===t;n.forEach(({listener:e,includeRepeats:t})=>{if(!(i&&!t))try{e(r)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function s(n){let{windowId:r,state:i}=n,a=t.get(r);if(n.type===`side-panel-state-tracker`&&t.set(r,i),i===`hidden`){e.delete(r),o(n,a);return}e.set(r,n),o(n,a)}function c(t){return a(),e.get(t)?.state}function l(e){return a(),c(e)===`visible`}function u(e,t={}){a();let r={listener:e,includeRepeats:t.includeRepeats===!0};return n.add(r),()=>{n.delete(r)}}function d(e){return u(t=>{t.reason!==`reconnected`&&t.state===`visible`&&t.previousState!==`visible`&&e(t)})}function f(e){return u(t=>{t.reason!==`reconnected`&&t.state===`hidden`&&t.previousState===`visible`&&e(t)})}const p=500;function m(e){let{defaultView:t,debounceMs:n=500}=e,r=new Set,i=t,a,o,s=!1,c;function u(){c&&=(clearTimeout(c),void 0)}async function f(e){await Promise.all([...r].map(async t=>{try{await t(e)}catch(e){console.error(`[browser-change] A change handler failed`,e)}}))}async function p(e,t,n,r={}){if(!s)try{let s=await chrome.tabs.get(e);if(!s.active||n===`page`&&o===e&&a===t)return;let c=o??null;n===`page`&&(o=e,a=t),await f({reason:n,tabId:e,url:t,windowId:s.windowId,tab:s,view:i,previousTabId:c,isPanelReload:r.isPanelReload===!0})}catch(e){console.error(`[browser-change] Failed to read the tab that changed`,e)}}async function m(e,t={}){if(s)return;let r=await chrome.tabs.get(e);if(!r.active||!l(r.windowId))return;let{url:i}=r;if(i!=null){if(u(),t.immediate===!0){await p(e,i,`page`,t);return}c=setTimeout(()=>{c=void 0,p(e,i,`page`,t).catch(console.error)},n)}}function h(e,t={}){chrome.tabs.query({windowId:e,active:!0}).then(async e=>{let n=e[0];n?.id!=null&&await m(n.id,{...t,immediate:!0})}).catch(console.error)}function g(){chrome.tabs.query({active:!0,lastFocusedWindow:!0}).then(async e=>{let t=e[0];t?.id==null||t.url==null||l(t.windowId)&&await p(t.id,t.url,`view`)}).catch(console.error)}function _(e){m(e).catch(console.error)}function v(e){m(e.tabId).catch(()=>{})}chrome.tabs.onUpdated.addListener(_),chrome.tabs.onActivated.addListener(v);let y=d(({reason:e,windowId:n})=>{s||(e===`document-load`&&(i=t),a=void 0,o=void 0,h(n,{isPanelReload:e===`document-load`}))});return{onBrowserChange(e){return r.add(e),()=>{r.delete(e)}},setView(e){s||i===e||(i=e,g())},dispose(){s=!0,u(),chrome.tabs.onUpdated.removeListener(_),chrome.tabs.onActivated.removeListener(v),y(),r.clear()}}}function h(){let e=new Map;return{isDisplaying(t){if(t.isPanelReload)return!1;let n=e.get(t.windowId);return n?.tabId===t.tabId&&n.url===t.url},record(t){e.set(t.windowId,{tabId:t.tabId,url:t.url})},forget(t){e.delete(t)}}}const g=new Map;let _=!1;function v(){_||(_=!0,chrome.windows.onRemoved.addListener(e=>{let t=g.get(e);t&&(t.forEach(e=>{e()}),g.delete(e))}))}function y(e,t){v();let n=g.get(e);return n||(n=new Set,g.set(e,n)),n.add(t),()=>{let n=g.get(e);n&&(n.delete(t),n.size===0&&g.delete(e))}}const b=250,x=5e3,S=2;let C=!1;function w(e={}){if(C)return console.info(`Side panel state tracker already initialized`),()=>{};C=!0;let{trackDocumentVisibility:t=!0}=e,n,r,i=0,a,o=!1;function s(){r&&=(clearTimeout(r),void 0)}return chrome.windows.getCurrent(e=>{if(o)return;if(e.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}let c=e.id;function l(){return t&&document.hidden?`hidden`:`visible`}function u(){if(o||r)return;n=void 0,console.info(`[side-panel-state-tracker] Connection to background lost, scheduling reconnect...`);let e=Math.min(250*2**i,5e3);i+=1,r=setTimeout(()=>{r=void 0,f(`reconnected`)},e)}function d(e){let t=n;if(!t){u();return}try{t.postMessage({...e,windowId:c,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e),u()}}function f(e){if(!o){s();try{let t=chrome.runtime.connect({name:chrome.runtime.id});n=t,i=0,t.onDisconnect.addListener(()=>{n===t&&(console.info(`[side-panel-state-tracker] Background connection lost.`),u())}),t.onMessage.addListener(e=>{e.type===`close-side-panel`&&(o=!0,s(),window.close())}),d({state:e===`document-load`?`visible`:l(),reason:e})}catch(e){console.error(`[side-panel-state-tracker] Failed to connect:`,e),u()}}}t&&(a=()=>{d({state:l(),reason:`visibility-change`})},document.addEventListener(`visibilitychange`,a)),f(`document-load`)}),()=>{o=!0,s(),a&&document.removeEventListener(`visibilitychange`,a);let e=n;n=void 0,e?.disconnect(),C=!1}}exports.createBrowserChangeWatcher=m,exports.createDisplayedPageTracker=h,exports.getSidePanelStateForWindow=c,exports.initSidePanelStateManager=i,exports.initializeSidePanelStateTracker=w,exports.isWindowSidePanelVisible=l,exports.onSidePanelHidden=f,exports.onSidePanelShown=d,exports.onSidePanelStateChange=u,exports.onWindowClose=y;

package/dist/index.d.cts

@@ -1,34 +1,96 @@
-//#region src/on-window-close.d.ts
+//#region src/types/browser-change.d.ts
 /**
- * Manages callbacks for when specific Chrome windows are closed.
- * Useful for triggering alerts, saving data, or cleaning up resources
- * when a specific popup or window is removed.
+ * What moved under the side panel.
+ *
+ * - `page` — the active tab navigated, the user switched to another tab, or the
+ *   panel came back on screen and needs to be told what it is looking at.
+ * - `view` — the user picked a different view inside the panel; the page is
+ *   untouched.
  */
-type CloseCallback = () => void;
+type BrowserChangeReason = 'page' | 'view';
 /**
- * Registers a callback to be executed when a specific window is closed.
- * @param windowId - The chrome window ID to watch
- * @param callback - Function to execute when the window closes
- * @returns A function to unsubscribe (remove) this specific listener
- * @example
- * const unsubscribe = onWindowClose(123, () => {
- *   console.log("Window 123 was closed!");
- * });
+ * @typeParam TView - Whatever the extension uses to name the views inside its side
+ * panel, usually a union of string literals.
  */
-declare function onWindowClose(windowId: number, callback: CloseCallback): () => void;
-//#endregion
-//#region src/side-panel-state-tracker.d.ts
-interface InitializeSidePanelStateTrackerOptions {
+interface BrowserChangeEvent<TView> {
+  reason: BrowserChangeReason;
+  /** The active tab the side panel is looking at. */
+  tabId: number;
+  /** Never empty — a tab with no URL is not announced. */
+  url: string;
+  windowId: number;
+  tab: chrome.tabs.Tab;
+  /** The view on screen, so a handler can ignore changes that are not its own. */
+  view: TView;
   /**
-   * When true, visibilitychange events report document.hidden as hidden state.
-   * Disable this if you only want open/closed port state.
+   * The tab this event moved away from, or `null` for the first event after the
+   * panel opens. Handlers that left something behind on a page — markers, injected
+   * UI — need it to clean up the tab they are leaving, not the one being arrived
+   * at.
    */
-  trackDocumentVisibility?: boolean;
+  previousTabId: number | null;
+  /**
+   * True when this is the first event for a side panel document that has just
+   * loaded. The panel has rendered nothing yet, so a handler that skips work for a
+   * page it believes is already on screen has to treat this as a fresh page — what
+   * it drew last time went away with the previous document.
+   */
+  isPanelReload: boolean;
+}
+type BrowserChangeHandler<TView> = (event: BrowserChangeEvent<TView>) => Promise<void> | void;
+interface BrowserChangeWatcherOptions<TView> {
+  /**
+   * The view a freshly loaded panel document starts on. A new document has none of
+   * the previous one's state, so the watcher resets to this rather than waiting for
+   * the panel's first report.
+   */
+  defaultView: TView;
+  /**
+   * How long to wait for a navigation to settle before announcing it.
+   * `chrome.tabs.onUpdated` fires repeatedly through a single navigation.
+   *
+   * @default 500
+   */
+  debounceMs?: number;
+}
+interface BrowserChangeWatcher<TView> {
+  /**
+   * Registers `handler` for every page or view change under the side panel.
+   * Returns a disposer.
+   */
+  onBrowserChange: (handler: BrowserChangeHandler<TView>) => () => void;
+  /**
+   * Tells the watcher which view the panel is showing. Call it from wherever the
+   * panel reports its view; repeats of the view already recorded are ignored, so it
+   * is safe to call on mount as well as on a change.
+   */
+  setView: (view: TView) => void;
+  /** Removes the watcher's browser listeners and drops every handler. */
+  dispose: () => void;
+}
+/** The page a window's side panel currently has on screen. */
+interface DisplayedPage {
+  tabId: number;
+  url: string;
+}
+/** The part of a {@link BrowserChangeEvent} a {@link DisplayedPageTracker} reads. */
+interface DisplayedPageInput {
+  windowId: number;
+  tabId: number;
+  url: string;
+  isPanelReload: boolean;
+}
+interface DisplayedPageTracker {
+  /**
+   * True when the panel in this window already has this exact page on screen, so
+   * there is nothing for the user to wait for.
+   */
+  isDisplaying: (event: DisplayedPageInput) => boolean;
+  /** Records the page the panel is now showing. */
+  record: (event: DisplayedPageInput) => void;
+  /** Drops what is remembered for a window, e.g. when the window closes. */
+  forget: (windowId: number) => void;
 }
-/**
- * Should only be called inside a Chrome extension side panel page.
- */
-declare function initializeSidePanelStateTracker(options?: InitializeSidePanelStateTrackerOptions): () => void;
 //#endregion
 //#region src/types/side-panel.d.ts
 type SidePanelState = 'visible' | 'hidden';
@@ -58,6 +120,94 @@ interface SidePanelClientMessage {
   type: 'close-side-panel';
 }
 //#endregion
+//#region src/browser-change-watcher.d.ts
+/**
+ * Watches what the side panel is looking at and announces every change.
+ *
+ * Nothing feature-specific lives here: the browser listeners, the debounce and the
+ * "have we already said this" bookkeeping are shared by every consumer, so they are
+ * done once and the result handed to whoever registered. Features register a
+ * handler instead of wiring their own tab listeners.
+ *
+ * The watcher does not know how the panel reports its view — call
+ * {@link BrowserChangeWatcher.setView} from wherever that arrives.
+ *
+ * @example
+ * ```typescript
+ * const { onBrowserChange, setView } = createBrowserChangeWatcher({
+ *   defaultView: 'insights',
+ * });
+ *
+ * sidePanelTabChange.onMessage(setView);
+ * ```
+ */
+declare function createBrowserChangeWatcher<TView>(options: BrowserChangeWatcherOptions<TView>): BrowserChangeWatcher<TView>;
+//#endregion
+//#region src/displayed-page-tracker.d.ts
+/**
+ * Remembers what each window's side panel currently has on screen, so a handler can
+ * tell a real move apart from a page being announced again.
+ *
+ * The same page reaches a handler more than once — the panel comes back into view,
+ * the service worker is recycled, a feature re-reads its data — and putting a
+ * loading state up for a page already rendered replaces good content with a spinner,
+ * or worse, with an empty state.
+ *
+ * Keyed by window, not by tab, because a panel shows one page at a time: once it has
+ * moved to another tab, coming back is a real change even though that tab had been
+ * rendered before. A panel document that has just loaded has drawn nothing, so
+ * {@link DisplayedPageTracker.isDisplaying} is always false for it.
+ *
+ * @example
+ * ```typescript
+ * const displayedPage = createDisplayedPageTracker();
+ *
+ * onBrowserChange(async (event) => {
+ *   const isAlreadyOnScreen = displayedPage.isDisplaying(event);
+ *   displayedPage.record(event);
+ *
+ *   if (!isAlreadyOnScreen) {
+ *     await showLoader(event.windowId);
+ *   }
+ *
+ *   await render(await loadData(event.tabId), event.windowId);
+ * });
+ * ```
+ */
+declare function createDisplayedPageTracker(): DisplayedPageTracker;
+//#endregion
+//#region src/on-window-close.d.ts
+/**
+ * Manages callbacks for when specific Chrome windows are closed.
+ * Useful for triggering alerts, saving data, or cleaning up resources
+ * when a specific popup or window is removed.
+ */
+type CloseCallback = () => void;
+/**
+ * Registers a callback to be executed when a specific window is closed.
+ * @param windowId - The chrome window ID to watch
+ * @param callback - Function to execute when the window closes
+ * @returns A function to unsubscribe (remove) this specific listener
+ * @example
+ * const unsubscribe = onWindowClose(123, () => {
+ *   console.log("Window 123 was closed!");
+ * });
+ */
+declare function onWindowClose(windowId: number, callback: CloseCallback): () => void;
+//#endregion
+//#region src/side-panel-state-tracker.d.ts
+interface InitializeSidePanelStateTrackerOptions {
+  /**
+   * When true, visibilitychange events report document.hidden as hidden state.
+   * Disable this if you only want open/closed port state.
+   */
+  trackDocumentVisibility?: boolean;
+}
+/**
+ * Should only be called inside a Chrome extension side panel page.
+ */
+declare function initializeSidePanelStateTracker(options?: InitializeSidePanelStateTrackerOptions): () => void;
+//#endregion
 //#region src/sidepanel-state-manager.d.ts
 type SidePanelStateListener = (data: SidePanelStateChangeData) => void;
 interface SidePanelStateChangeOptions {
@@ -104,11 +254,16 @@ declare function onSidePanelStateChange(listener: SidePanelStateListener, option
  *
  * A narrowed {@link onSidePanelStateChange} for code that only cares about one
  * direction. This is the event to use for "the panel is back on screen, resync
- * it". It covers
- * a freshly loaded document (`reason: 'document-load'`), a panel Chrome had cached
- * while another extension's side panel took over the slot
- * (`reason: 'visibility-change'`), and the first report after a service worker
- * restart (`reason: 'reconnected'`).
+ * it". It covers a freshly loaded document (`reason: 'document-load'`) and a panel
+ * Chrome had cached while another extension's side panel took over the slot
+ * (`reason: 'visibility-change'`).
+ *
+ * Reconnects (`reason: 'reconnected'`) are not shows and never fire this. The
+ * tracker reconnects when the service worker is torn down and restarted, and the
+ * panel document lives through that untouched — nothing appeared, so nothing needs
+ * resyncing. It has to be excluded explicitly because a restarted worker has no
+ * record of the window, leaving `previousState` empty, which would otherwise make
+ * every recycle look like a fresh show.
  *
  * @param listener - Callback function that receives state change data
  * @returns Unsubscribe function to remove the listener
@@ -120,11 +275,13 @@ declare function onSidePanelShown(listener: SidePanelStateListener): () => void;
  * A narrowed {@link onSidePanelStateChange} for code that only cares about one
  * direction. Nothing fires for a window that was never seen visible, so a service worker
  * restart followed by a port disconnect stays quiet instead of reporting a close
- * that the listener never saw open.
+ * that the listener never saw open. Reconnects are excluded for the same reason
+ * they are in {@link onSidePanelShown}: they report the state the panel is already
+ * in, not a move into it.
  *
  * @param listener - Callback function that receives state change data
  * @returns Unsubscribe function to remove the listener
  */
 declare function onSidePanelHidden(listener: SidePanelStateListener): () => void;
 //#endregion
-export { InitializeSidePanelStateTrackerOptions, SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateChangeOptions, SidePanelStateData, SidePanelStateListener, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelHidden, onSidePanelShown, onSidePanelStateChange, onWindowClose };
+export { BrowserChangeEvent, BrowserChangeHandler, BrowserChangeReason, BrowserChangeWatcher, BrowserChangeWatcherOptions, DisplayedPage, DisplayedPageInput, DisplayedPageTracker, InitializeSidePanelStateTrackerOptions, SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateChangeOptions, SidePanelStateData, SidePanelStateListener, createBrowserChangeWatcher, createDisplayedPageTracker, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelHidden, onSidePanelShown, onSidePanelStateChange, onWindowClose };

package/dist/index.d.ts

@@ -1,34 +1,96 @@
-//#region src/on-window-close.d.ts
+//#region src/types/browser-change.d.ts
 /**
- * Manages callbacks for when specific Chrome windows are closed.
- * Useful for triggering alerts, saving data, or cleaning up resources
- * when a specific popup or window is removed.
+ * What moved under the side panel.
+ *
+ * - `page` — the active tab navigated, the user switched to another tab, or the
+ *   panel came back on screen and needs to be told what it is looking at.
+ * - `view` — the user picked a different view inside the panel; the page is
+ *   untouched.
  */
-type CloseCallback = () => void;
+type BrowserChangeReason = 'page' | 'view';
 /**
- * Registers a callback to be executed when a specific window is closed.
- * @param windowId - The chrome window ID to watch
- * @param callback - Function to execute when the window closes
- * @returns A function to unsubscribe (remove) this specific listener
- * @example
- * const unsubscribe = onWindowClose(123, () => {
- *   console.log("Window 123 was closed!");
- * });
+ * @typeParam TView - Whatever the extension uses to name the views inside its side
+ * panel, usually a union of string literals.
  */
-declare function onWindowClose(windowId: number, callback: CloseCallback): () => void;
-//#endregion
-//#region src/side-panel-state-tracker.d.ts
-interface InitializeSidePanelStateTrackerOptions {
+interface BrowserChangeEvent<TView> {
+  reason: BrowserChangeReason;
+  /** The active tab the side panel is looking at. */
+  tabId: number;
+  /** Never empty — a tab with no URL is not announced. */
+  url: string;
+  windowId: number;
+  tab: chrome.tabs.Tab;
+  /** The view on screen, so a handler can ignore changes that are not its own. */
+  view: TView;
   /**
-   * When true, visibilitychange events report document.hidden as hidden state.
-   * Disable this if you only want open/closed port state.
+   * The tab this event moved away from, or `null` for the first event after the
+   * panel opens. Handlers that left something behind on a page — markers, injected
+   * UI — need it to clean up the tab they are leaving, not the one being arrived
+   * at.
    */
-  trackDocumentVisibility?: boolean;
+  previousTabId: number | null;
+  /**
+   * True when this is the first event for a side panel document that has just
+   * loaded. The panel has rendered nothing yet, so a handler that skips work for a
+   * page it believes is already on screen has to treat this as a fresh page — what
+   * it drew last time went away with the previous document.
+   */
+  isPanelReload: boolean;
+}
+type BrowserChangeHandler<TView> = (event: BrowserChangeEvent<TView>) => Promise<void> | void;
+interface BrowserChangeWatcherOptions<TView> {
+  /**
+   * The view a freshly loaded panel document starts on. A new document has none of
+   * the previous one's state, so the watcher resets to this rather than waiting for
+   * the panel's first report.
+   */
+  defaultView: TView;
+  /**
+   * How long to wait for a navigation to settle before announcing it.
+   * `chrome.tabs.onUpdated` fires repeatedly through a single navigation.
+   *
+   * @default 500
+   */
+  debounceMs?: number;
+}
+interface BrowserChangeWatcher<TView> {
+  /**
+   * Registers `handler` for every page or view change under the side panel.
+   * Returns a disposer.
+   */
+  onBrowserChange: (handler: BrowserChangeHandler<TView>) => () => void;
+  /**
+   * Tells the watcher which view the panel is showing. Call it from wherever the
+   * panel reports its view; repeats of the view already recorded are ignored, so it
+   * is safe to call on mount as well as on a change.
+   */
+  setView: (view: TView) => void;
+  /** Removes the watcher's browser listeners and drops every handler. */
+  dispose: () => void;
+}
+/** The page a window's side panel currently has on screen. */
+interface DisplayedPage {
+  tabId: number;
+  url: string;
+}
+/** The part of a {@link BrowserChangeEvent} a {@link DisplayedPageTracker} reads. */
+interface DisplayedPageInput {
+  windowId: number;
+  tabId: number;
+  url: string;
+  isPanelReload: boolean;
+}
+interface DisplayedPageTracker {
+  /**
+   * True when the panel in this window already has this exact page on screen, so
+   * there is nothing for the user to wait for.
+   */
+  isDisplaying: (event: DisplayedPageInput) => boolean;
+  /** Records the page the panel is now showing. */
+  record: (event: DisplayedPageInput) => void;
+  /** Drops what is remembered for a window, e.g. when the window closes. */
+  forget: (windowId: number) => void;
 }
-/**
- * Should only be called inside a Chrome extension side panel page.
- */
-declare function initializeSidePanelStateTracker(options?: InitializeSidePanelStateTrackerOptions): () => void;
 //#endregion
 //#region src/types/side-panel.d.ts
 type SidePanelState = 'visible' | 'hidden';
@@ -58,6 +120,94 @@ interface SidePanelClientMessage {
   type: 'close-side-panel';
 }
 //#endregion
+//#region src/browser-change-watcher.d.ts
+/**
+ * Watches what the side panel is looking at and announces every change.
+ *
+ * Nothing feature-specific lives here: the browser listeners, the debounce and the
+ * "have we already said this" bookkeeping are shared by every consumer, so they are
+ * done once and the result handed to whoever registered. Features register a
+ * handler instead of wiring their own tab listeners.
+ *
+ * The watcher does not know how the panel reports its view — call
+ * {@link BrowserChangeWatcher.setView} from wherever that arrives.
+ *
+ * @example
+ * ```typescript
+ * const { onBrowserChange, setView } = createBrowserChangeWatcher({
+ *   defaultView: 'insights',
+ * });
+ *
+ * sidePanelTabChange.onMessage(setView);
+ * ```
+ */
+declare function createBrowserChangeWatcher<TView>(options: BrowserChangeWatcherOptions<TView>): BrowserChangeWatcher<TView>;
+//#endregion
+//#region src/displayed-page-tracker.d.ts
+/**
+ * Remembers what each window's side panel currently has on screen, so a handler can
+ * tell a real move apart from a page being announced again.
+ *
+ * The same page reaches a handler more than once — the panel comes back into view,
+ * the service worker is recycled, a feature re-reads its data — and putting a
+ * loading state up for a page already rendered replaces good content with a spinner,
+ * or worse, with an empty state.
+ *
+ * Keyed by window, not by tab, because a panel shows one page at a time: once it has
+ * moved to another tab, coming back is a real change even though that tab had been
+ * rendered before. A panel document that has just loaded has drawn nothing, so
+ * {@link DisplayedPageTracker.isDisplaying} is always false for it.
+ *
+ * @example
+ * ```typescript
+ * const displayedPage = createDisplayedPageTracker();
+ *
+ * onBrowserChange(async (event) => {
+ *   const isAlreadyOnScreen = displayedPage.isDisplaying(event);
+ *   displayedPage.record(event);
+ *
+ *   if (!isAlreadyOnScreen) {
+ *     await showLoader(event.windowId);
+ *   }
+ *
+ *   await render(await loadData(event.tabId), event.windowId);
+ * });
+ * ```
+ */
+declare function createDisplayedPageTracker(): DisplayedPageTracker;
+//#endregion
+//#region src/on-window-close.d.ts
+/**
+ * Manages callbacks for when specific Chrome windows are closed.
+ * Useful for triggering alerts, saving data, or cleaning up resources
+ * when a specific popup or window is removed.
+ */
+type CloseCallback = () => void;
+/**
+ * Registers a callback to be executed when a specific window is closed.
+ * @param windowId - The chrome window ID to watch
+ * @param callback - Function to execute when the window closes
+ * @returns A function to unsubscribe (remove) this specific listener
+ * @example
+ * const unsubscribe = onWindowClose(123, () => {
+ *   console.log("Window 123 was closed!");
+ * });
+ */
+declare function onWindowClose(windowId: number, callback: CloseCallback): () => void;
+//#endregion
+//#region src/side-panel-state-tracker.d.ts
+interface InitializeSidePanelStateTrackerOptions {
+  /**
+   * When true, visibilitychange events report document.hidden as hidden state.
+   * Disable this if you only want open/closed port state.
+   */
+  trackDocumentVisibility?: boolean;
+}
+/**
+ * Should only be called inside a Chrome extension side panel page.
+ */
+declare function initializeSidePanelStateTracker(options?: InitializeSidePanelStateTrackerOptions): () => void;
+//#endregion
 //#region src/sidepanel-state-manager.d.ts
 type SidePanelStateListener = (data: SidePanelStateChangeData) => void;
 interface SidePanelStateChangeOptions {
@@ -104,11 +254,16 @@ declare function onSidePanelStateChange(listener: SidePanelStateListener, option
  *
  * A narrowed {@link onSidePanelStateChange} for code that only cares about one
  * direction. This is the event to use for "the panel is back on screen, resync
- * it". It covers
- * a freshly loaded document (`reason: 'document-load'`), a panel Chrome had cached
- * while another extension's side panel took over the slot
- * (`reason: 'visibility-change'`), and the first report after a service worker
- * restart (`reason: 'reconnected'`).
+ * it". It covers a freshly loaded document (`reason: 'document-load'`) and a panel
+ * Chrome had cached while another extension's side panel took over the slot
+ * (`reason: 'visibility-change'`).
+ *
+ * Reconnects (`reason: 'reconnected'`) are not shows and never fire this. The
+ * tracker reconnects when the service worker is torn down and restarted, and the
+ * panel document lives through that untouched — nothing appeared, so nothing needs
+ * resyncing. It has to be excluded explicitly because a restarted worker has no
+ * record of the window, leaving `previousState` empty, which would otherwise make
+ * every recycle look like a fresh show.
  *
  * @param listener - Callback function that receives state change data
  * @returns Unsubscribe function to remove the listener
@@ -120,11 +275,13 @@ declare function onSidePanelShown(listener: SidePanelStateListener): () => void;
  * A narrowed {@link onSidePanelStateChange} for code that only cares about one
  * direction. Nothing fires for a window that was never seen visible, so a service worker
  * restart followed by a port disconnect stays quiet instead of reporting a close
- * that the listener never saw open.
+ * that the listener never saw open. Reconnects are excluded for the same reason
+ * they are in {@link onSidePanelShown}: they report the state the panel is already
+ * in, not a move into it.
  *
  * @param listener - Callback function that receives state change data
  * @returns Unsubscribe function to remove the listener
  */
 declare function onSidePanelHidden(listener: SidePanelStateListener): () => void;
 //#endregion
-export { InitializeSidePanelStateTrackerOptions, SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateChangeOptions, SidePanelStateData, SidePanelStateListener, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelHidden, onSidePanelShown, onSidePanelStateChange, onWindowClose };
+export { BrowserChangeEvent, BrowserChangeHandler, BrowserChangeReason, BrowserChangeWatcher, BrowserChangeWatcherOptions, DisplayedPage, DisplayedPageInput, DisplayedPageTracker, InitializeSidePanelStateTrackerOptions, SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateChangeOptions, SidePanelStateData, SidePanelStateListener, createBrowserChangeWatcher, createDisplayedPageTracker, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelHidden, onSidePanelShown, onSidePanelStateChange, onWindowClose };

package/dist/index.js

@@ -1 +1 @@
-const e=new Map;let t=!1;function n(){t||(t=!0,chrome.windows.onRemoved.addListener(t=>{let n=e.get(t);n&&(n.forEach(e=>{e()}),e.delete(t))}))}function r(t,r){n();let i=e.get(t);return i||(i=new Set,e.set(t,i)),i.add(r),()=>{let n=e.get(t);n&&(n.delete(r),n.size===0&&e.delete(t))}}let i=!1;function a(e={}){if(i)return console.info(`Side panel state tracker already initialized`),()=>{};i=!0;let{trackDocumentVisibility:t=!0}=e,n,r,a=0,o,s=!1;function c(){r&&=(clearTimeout(r),void 0)}return chrome.windows.getCurrent(e=>{if(s)return;if(e.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}let i=e.id;function l(){return t&&document.hidden?`hidden`:`visible`}function u(){if(s||r)return;n=void 0,console.info(`[side-panel-state-tracker] Connection to background lost, scheduling reconnect...`);let e=Math.min(250*2**a,5e3);a+=1,r=setTimeout(()=>{r=void 0,f(`reconnected`)},e)}function d(e){let t=n;if(!t){u();return}try{t.postMessage({...e,windowId:i,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e),u()}}function f(e){if(!s){c();try{let t=chrome.runtime.connect({name:chrome.runtime.id});n=t,a=0,t.onDisconnect.addListener(()=>{n===t&&(console.info(`[side-panel-state-tracker] Background connection lost.`),u())}),t.onMessage.addListener(e=>{e.type===`close-side-panel`&&(s=!0,c(),window.close())}),d({state:e===`document-load`?`visible`:l(),reason:e})}catch(e){console.error(`[side-panel-state-tracker] Failed to connect:`,e),u()}}}t&&(o=()=>{d({state:l(),reason:`visibility-change`})},document.addEventListener(`visibilitychange`,o)),f(`document-load`)}),()=>{s=!0,c(),o&&document.removeEventListener(`visibilitychange`,o);let e=n;n=void 0,e?.disconnect(),i=!1}}const o=new Map,s=new Map,c=new Set;let l=!1;function u(){l||(l=!0,chrome.action.onClicked.addListener(e=>{let t=o.get(e.windowId);t&&t.state===`visible`?t.port&&(o.delete(e.windowId),t.port.postMessage({type:`close-side-panel`})):chrome.sidePanel.open({windowId:e.windowId}).catch(console.error)}),chrome.runtime.onConnect.addListener(e=>{e.name===chrome.runtime.id&&(e.onMessage.addListener(t=>{t.type===`side-panel-state-tracker`&&t.state&&p({port:e,state:t.state,reason:t.reason??`unknown`,windowId:t.windowId,type:t.type})}),e.onDisconnect.addListener(e=>{Array.from(o.entries()).forEach(([t,n])=>{n.port&&n.port===e&&p({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:t,type:`side-panel-state-tracker`})})}))}),chrome.windows.onRemoved.addListener(e=>{o.delete(e),s.delete(e)}))}function d(){l||=(u(),!0)}function f(e,t){if(e.type!==`side-panel-state-tracker`)return;let n={state:e.state,reason:e.reason,windowId:e.windowId,previousState:t},r=e.state===t;c.forEach(({listener:e,includeRepeats:t})=>{if(!(r&&!t))try{e(n)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function p(e){let{windowId:t,state:n}=e,r=s.get(t);if(e.type===`side-panel-state-tracker`&&s.set(t,n),n===`hidden`){o.delete(t),f(e,r);return}o.set(t,e),f(e,r)}function m(e){return d(),o.get(e)?.state}function h(e){return d(),m(e)===`visible`}function g(e,t={}){d();let n={listener:e,includeRepeats:t.includeRepeats===!0};return c.add(n),()=>{c.delete(n)}}function _(e){return g(t=>{t.state===`visible`&&t.previousState!==`visible`&&e(t)})}function v(e){return g(t=>{t.state===`hidden`&&t.previousState===`visible`&&e(t)})}export{m as getSidePanelStateForWindow,u as initSidePanelStateManager,a as initializeSidePanelStateTracker,h as isWindowSidePanelVisible,v as onSidePanelHidden,_ as onSidePanelShown,g as onSidePanelStateChange,r as onWindowClose};
+const e=new Map,t=new Map,n=new Set;let r=!1;function i(){r||(r=!0,chrome.action.onClicked.addListener(t=>{let n=e.get(t.windowId);n&&n.state===`visible`?n.port&&(e.delete(t.windowId),n.port.postMessage({type:`close-side-panel`})):chrome.sidePanel.open({windowId:t.windowId}).catch(console.error)}),chrome.runtime.onConnect.addListener(t=>{t.name===chrome.runtime.id&&(t.onMessage.addListener(e=>{e.type===`side-panel-state-tracker`&&e.state&&s({port:t,state:e.state,reason:e.reason??`unknown`,windowId:e.windowId,type:e.type})}),t.onDisconnect.addListener(t=>{Array.from(e.entries()).forEach(([e,n])=>{n.port&&n.port===t&&s({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:e,type:`side-panel-state-tracker`})})}))}),chrome.windows.onRemoved.addListener(n=>{e.delete(n),t.delete(n)}))}function a(){r||=(i(),!0)}function o(e,t){if(e.type!==`side-panel-state-tracker`)return;let r={state:e.state,reason:e.reason,windowId:e.windowId,previousState:t},i=e.state===t;n.forEach(({listener:e,includeRepeats:t})=>{if(!(i&&!t))try{e(r)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function s(n){let{windowId:r,state:i}=n,a=t.get(r);if(n.type===`side-panel-state-tracker`&&t.set(r,i),i===`hidden`){e.delete(r),o(n,a);return}e.set(r,n),o(n,a)}function c(t){return a(),e.get(t)?.state}function l(e){return a(),c(e)===`visible`}function u(e,t={}){a();let r={listener:e,includeRepeats:t.includeRepeats===!0};return n.add(r),()=>{n.delete(r)}}function d(e){return u(t=>{t.reason!==`reconnected`&&t.state===`visible`&&t.previousState!==`visible`&&e(t)})}function f(e){return u(t=>{t.reason!==`reconnected`&&t.state===`hidden`&&t.previousState===`visible`&&e(t)})}function p(e){let{defaultView:t,debounceMs:n=500}=e,r=new Set,i=t,a,o,s=!1,c;function u(){c&&=(clearTimeout(c),void 0)}async function f(e){await Promise.all([...r].map(async t=>{try{await t(e)}catch(e){console.error(`[browser-change] A change handler failed`,e)}}))}async function p(e,t,n,r={}){if(!s)try{let s=await chrome.tabs.get(e);if(!s.active||n===`page`&&o===e&&a===t)return;let c=o??null;n===`page`&&(o=e,a=t),await f({reason:n,tabId:e,url:t,windowId:s.windowId,tab:s,view:i,previousTabId:c,isPanelReload:r.isPanelReload===!0})}catch(e){console.error(`[browser-change] Failed to read the tab that changed`,e)}}async function m(e,t={}){if(s)return;let r=await chrome.tabs.get(e);if(!r.active||!l(r.windowId))return;let{url:i}=r;if(i!=null){if(u(),t.immediate===!0){await p(e,i,`page`,t);return}c=setTimeout(()=>{c=void 0,p(e,i,`page`,t).catch(console.error)},n)}}function h(e,t={}){chrome.tabs.query({windowId:e,active:!0}).then(async e=>{let n=e[0];n?.id!=null&&await m(n.id,{...t,immediate:!0})}).catch(console.error)}function g(){chrome.tabs.query({active:!0,lastFocusedWindow:!0}).then(async e=>{let t=e[0];t?.id==null||t.url==null||l(t.windowId)&&await p(t.id,t.url,`view`)}).catch(console.error)}function _(e){m(e).catch(console.error)}function v(e){m(e.tabId).catch(()=>{})}chrome.tabs.onUpdated.addListener(_),chrome.tabs.onActivated.addListener(v);let y=d(({reason:e,windowId:n})=>{s||(e===`document-load`&&(i=t),a=void 0,o=void 0,h(n,{isPanelReload:e===`document-load`}))});return{onBrowserChange(e){return r.add(e),()=>{r.delete(e)}},setView(e){s||i===e||(i=e,g())},dispose(){s=!0,u(),chrome.tabs.onUpdated.removeListener(_),chrome.tabs.onActivated.removeListener(v),y(),r.clear()}}}function m(){let e=new Map;return{isDisplaying(t){if(t.isPanelReload)return!1;let n=e.get(t.windowId);return n?.tabId===t.tabId&&n.url===t.url},record(t){e.set(t.windowId,{tabId:t.tabId,url:t.url})},forget(t){e.delete(t)}}}const h=new Map;let g=!1;function _(){g||(g=!0,chrome.windows.onRemoved.addListener(e=>{let t=h.get(e);t&&(t.forEach(e=>{e()}),h.delete(e))}))}function v(e,t){_();let n=h.get(e);return n||(n=new Set,h.set(e,n)),n.add(t),()=>{let n=h.get(e);n&&(n.delete(t),n.size===0&&h.delete(e))}}let y=!1;function b(e={}){if(y)return console.info(`Side panel state tracker already initialized`),()=>{};y=!0;let{trackDocumentVisibility:t=!0}=e,n,r,i=0,a,o=!1;function s(){r&&=(clearTimeout(r),void 0)}return chrome.windows.getCurrent(e=>{if(o)return;if(e.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}let c=e.id;function l(){return t&&document.hidden?`hidden`:`visible`}function u(){if(o||r)return;n=void 0,console.info(`[side-panel-state-tracker] Connection to background lost, scheduling reconnect...`);let e=Math.min(250*2**i,5e3);i+=1,r=setTimeout(()=>{r=void 0,f(`reconnected`)},e)}function d(e){let t=n;if(!t){u();return}try{t.postMessage({...e,windowId:c,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e),u()}}function f(e){if(!o){s();try{let t=chrome.runtime.connect({name:chrome.runtime.id});n=t,i=0,t.onDisconnect.addListener(()=>{n===t&&(console.info(`[side-panel-state-tracker] Background connection lost.`),u())}),t.onMessage.addListener(e=>{e.type===`close-side-panel`&&(o=!0,s(),window.close())}),d({state:e===`document-load`?`visible`:l(),reason:e})}catch(e){console.error(`[side-panel-state-tracker] Failed to connect:`,e),u()}}}t&&(a=()=>{d({state:l(),reason:`visibility-change`})},document.addEventListener(`visibilitychange`,a)),f(`document-load`)}),()=>{o=!0,s(),a&&document.removeEventListener(`visibilitychange`,a);let e=n;n=void 0,e?.disconnect(),y=!1}}export{p as createBrowserChangeWatcher,m as createDisplayedPageTracker,c as getSidePanelStateForWindow,i as initSidePanelStateManager,b as initializeSidePanelStateTracker,l as isWindowSidePanelVisible,f as onSidePanelHidden,d as onSidePanelShown,u as onSidePanelStateChange,v as onWindowClose};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pixpilot/chrome-lifecycle",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Lifecycle management utilities for Chrome extensions.",
   "author": "m.doaie <m.doaie@hotmail.com>",
   "license": "MIT",
@@ -29,11 +29,11 @@
     "eslint": "^9.38.0",
     "tsdown": "^0.15.9",
     "typescript": "^5.9.3",
+    "@internal/eslint-config": "0.3.0",
     "@internal/prettier-config": "0.1.0",
-    "@internal/tsconfig": "0.1.0",
-    "@internal/tsdown-config": "0.1.0",
     "@internal/vitest-config": "0.1.0",
-    "@internal/eslint-config": "0.3.0"
+    "@internal/tsconfig": "0.1.0",
+    "@internal/tsdown-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {