@pixpilot/chrome-lifecycle 0.4.0 → 0.6.0

package/README.md

@@ -42,45 +42,45 @@ Tracks whether side panels are visible or hidden across different windows.
 
 #### Setup
 
-**Background script (service worker):**
+This feature requires initialization in both your background script and side panel script.
+
+**1. Background script (service worker):**
+
+Call `initSidePanelStateManager()` at the top of your background script, before any other side panel functions. All other functions (`getSidePanelStateForWindow`, `isWindowSidePanelVisible`, `onSidePanelStateChange`) will throw an error if called before initialization.
 
 ```typescript
+// background.ts
 import { initSidePanelStateManager } from '@pixpilot/chrome-lifecycle';
 
-// Initialize once at startup
+// ⚠️ Critical Setup
+// Must be called first, before any other side panel functions
 initSidePanelStateManager();
+
+// Now you can use other functions
 ```
 
-**Side panel script (frontend):**
+**2. Side panel script (frontend):**
+
+Call `initializeSidePanelStateTracker()` when your side panel loads. This sets up visibility tracking and a heartbeat to keep the connection alive.
 
 ```typescript
+// sidepanel.ts
 import { initializeSidePanelStateTracker } from '@pixpilot/chrome-lifecycle';
 
-// Initialize when side panel loads
 const cleanup = initializeSidePanelStateTracker();
+
+// Optional: call cleanup() when done to remove listeners and disconnect
 ```
 
 #### Functions
 
 ##### `initSidePanelStateManager()`
 
-Initializes the backend state manager. Must be called once in your background script before using other side panel functions. Subsequent calls log a warning and are ignored.
-
-```typescript
-import { initSidePanelStateManager } from '@pixpilot/chrome-lifecycle';
-
-initSidePanelStateManager();
-```
+Initializes the backend state manager. **Must be called once at the top of your background script before using any other side panel functions.** Subsequent calls log a warning and are ignored.
 
 ##### `initializeSidePanelStateTracker()`
 
-Initializes the frontend tracker in your side panel. Sets up visibility tracking and heartbeat to keep the connection alive.
-
-```typescript
-import { initializeSidePanelStateTracker } from '@pixpilot/chrome-lifecycle';
-
-const cleanup = initializeSidePanelStateTracker();
-```
+Initializes the frontend tracker in your side panel. Sets up visibility change detection and a heartbeat (every 15 seconds) to maintain the connection.
 
 **Returns:** Cleanup function to remove listeners and disconnect
 

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=15e3;let a=!1;function o(){a&&console.warn(`Side panel state tracker already initialized`),a=!0;let e,t,n;return chrome.windows.getCurrent(r=>{if(r.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}e=chrome.runtime.connect({name:chrome.runtime.id});let i=r.id;function a(t){try{e.postMessage({...t,windowId:i,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e)}}t=setInterval(()=>{try{e.postMessage({type:`side-panel-heartbeat`,windowId:i,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Heartbeat failed:`,e),t&&clearInterval(t)}},15e3),n=()=>{a({state:document.hidden?`hidden`:`visible`,reason:`visibility-change`})},document.addEventListener(`visibilitychange`,n),e.onDisconnect.addListener(()=>{console.warn(`[side-panel-state-tracker] Background connection lost`),t&&clearInterval(t)}),e.onMessage.addListener(e=>{e.type===`close-side-panel`&&(t&&clearInterval(t),window.close())}),a({state:document.hidden?`hidden`:`visible`,reason:`document-load`})}),()=>{t&&clearInterval(t),n&&document.removeEventListener(`visibilitychange`,n),e&&e.disconnect(),a=!1}}const s=new Map,c=new Set;let l=!1;function u(){if(!l)throw Error(`Side panel state manager must be initialized with initSidePanelStateManager() before use.`)}function d(){l||(l=!0,chrome.action.onClicked.addListener(e=>{let t=s.get(e.windowId);t&&t.state===`visible`?t.port&&(s.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(s.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`})})}))}))}function f(e){if(e.type!==`side-panel-state-tracker`)return;let t={state:e.state,reason:e.reason,windowId:e.windowId};c.forEach(e=>{try{e(t)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function p(e){let{windowId:t,state:n}=e;if(n===`hidden`){s.delete(t),f(e);return}s.set(t,e),f(e)}function m(e){return u(),s.get(e)?.state}function h(e){return u(),m(e)===`visible`}function g(e){return u(),c.add(e),()=>{c.delete(e)}}exports.getSidePanelStateForWindow=m,exports.initSidePanelStateManager=d,exports.initializeSidePanelStateTracker=o,exports.isWindowSidePanelVisible=h,exports.onSidePanelStateChange=g,exports.onWindowClose=r;
+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=15e3;let a=!1;function o(){a&&console.warn(`Side panel state tracker already initialized`),a=!0;let e,t,n;return chrome.windows.getCurrent(r=>{if(r.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}e=chrome.runtime.connect({name:chrome.runtime.id});let i=r.id;function a(t){try{e.postMessage({...t,windowId:i,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e)}}t=setInterval(()=>{try{e.postMessage({type:`side-panel-heartbeat`,windowId:i,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Heartbeat failed:`,e),t&&clearInterval(t)}},15e3),n=()=>{a({state:document.hidden?`hidden`:`visible`,reason:`visibility-change`})},document.addEventListener(`visibilitychange`,n),e.onDisconnect.addListener(()=>{console.warn(`[side-panel-state-tracker] Background connection lost`),t&&clearInterval(t)}),e.onMessage.addListener(e=>{e.type===`close-side-panel`&&(t&&clearInterval(t),window.close())}),a({state:document.hidden?`hidden`:`visible`,reason:`document-load`})}),()=>{t&&clearInterval(t),n&&document.removeEventListener(`visibilitychange`,n),e&&e.disconnect(),a=!1}}const s=new Map,c=new Set;let l=!1;function u(){l||console.error(`Side panel state manager is not initialized.`,`Call initSidePanelStateManager() at the top of your background script before using any other functions.`)}function d(){l||(l=!0,chrome.action.onClicked.addListener(e=>{let t=s.get(e.windowId);t&&t.state===`visible`?t.port&&(s.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(s.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`})})}))}))}function f(e){if(e.type!==`side-panel-state-tracker`)return;let t={state:e.state,reason:e.reason,windowId:e.windowId};c.forEach(e=>{try{e(t)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function p(e){let{windowId:t,state:n}=e;if(n===`hidden`){s.delete(t),f(e);return}s.set(t,e),f(e)}function m(e){return u(),s.get(e)?.state}function h(e){return u(),m(e)===`visible`}function g(e){return u(),c.add(e),()=>{c.delete(e)}}exports.getSidePanelStateForWindow=m,exports.initSidePanelStateManager=d,exports.initializeSidePanelStateTracker=o,exports.isWindowSidePanelVisible=h,exports.onSidePanelStateChange=g,exports.onWindowClose=r;

package/dist/index.d.cts

@@ -38,7 +38,6 @@ type SidePanelStateChangeData = Omit<SidePanelStateData, 'timestamp' | 'type'>;
 interface SidePanelClientMessage {
   type: 'close-side-panel';
 }
-type SidePanelTabTypes = 'insights' | 'history' | 'settings';
 //#endregion
 //#region src/sidepanel-state-manager.d.ts
 type SidePanelStateListener = (data: SidePanelStateChangeData) => void;
@@ -61,4 +60,4 @@ declare function isWindowSidePanelVisible(windowId: number): boolean;
  */
 declare function onSidePanelStateChange(listener: SidePanelStateListener): () => void;
 //#endregion
-export { SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateData, SidePanelTabTypes, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelStateChange, onWindowClose };
+export { SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateData, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelStateChange, onWindowClose };

package/dist/index.d.ts

@@ -38,7 +38,6 @@ type SidePanelStateChangeData = Omit<SidePanelStateData, 'timestamp' | 'type'>;
 interface SidePanelClientMessage {
   type: 'close-side-panel';
 }
-type SidePanelTabTypes = 'insights' | 'history' | 'settings';
 //#endregion
 //#region src/sidepanel-state-manager.d.ts
 type SidePanelStateListener = (data: SidePanelStateChangeData) => void;
@@ -61,4 +60,4 @@ declare function isWindowSidePanelVisible(windowId: number): boolean;
  */
 declare function onSidePanelStateChange(listener: SidePanelStateListener): () => void;
 //#endregion
-export { SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateData, SidePanelTabTypes, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, onSidePanelStateChange, onWindowClose };
+export { SidePanelClientMessage, SidePanelState, SidePanelStateChangeData, SidePanelStateData, getSidePanelStateForWindow, initSidePanelStateManager, initializeSidePanelStateTracker, isWindowSidePanelVisible, 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(){i&&console.warn(`Side panel state tracker already initialized`),i=!0;let e,t,n;return chrome.windows.getCurrent(r=>{if(r.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}e=chrome.runtime.connect({name:chrome.runtime.id});let i=r.id;function a(t){try{e.postMessage({...t,windowId:i,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e)}}t=setInterval(()=>{try{e.postMessage({type:`side-panel-heartbeat`,windowId:i,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Heartbeat failed:`,e),t&&clearInterval(t)}},15e3),n=()=>{a({state:document.hidden?`hidden`:`visible`,reason:`visibility-change`})},document.addEventListener(`visibilitychange`,n),e.onDisconnect.addListener(()=>{console.warn(`[side-panel-state-tracker] Background connection lost`),t&&clearInterval(t)}),e.onMessage.addListener(e=>{e.type===`close-side-panel`&&(t&&clearInterval(t),window.close())}),a({state:document.hidden?`hidden`:`visible`,reason:`document-load`})}),()=>{t&&clearInterval(t),n&&document.removeEventListener(`visibilitychange`,n),e&&e.disconnect(),i=!1}}const o=new Map,s=new Set;let c=!1;function l(){if(!c)throw Error(`Side panel state manager must be initialized with initSidePanelStateManager() before use.`)}function u(){c||(c=!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&&f({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&&f({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:t,type:`side-panel-state-tracker`})})}))}))}function d(e){if(e.type!==`side-panel-state-tracker`)return;let t={state:e.state,reason:e.reason,windowId:e.windowId};s.forEach(e=>{try{e(t)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function f(e){let{windowId:t,state:n}=e;if(n===`hidden`){o.delete(t),d(e);return}o.set(t,e),d(e)}function p(e){return l(),o.get(e)?.state}function m(e){return l(),p(e)===`visible`}function h(e){return l(),s.add(e),()=>{s.delete(e)}}export{p as getSidePanelStateForWindow,u as initSidePanelStateManager,a as initializeSidePanelStateTracker,m as isWindowSidePanelVisible,h as onSidePanelStateChange,r as onWindowClose};
+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(){i&&console.warn(`Side panel state tracker already initialized`),i=!0;let e,t,n;return chrome.windows.getCurrent(r=>{if(r.id==null){console.error(`[side-panel-state-tracker] Could not get window ID`);return}e=chrome.runtime.connect({name:chrome.runtime.id});let i=r.id;function a(t){try{e.postMessage({...t,windowId:i,type:`side-panel-state-tracker`,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Failed to send message:`,e)}}t=setInterval(()=>{try{e.postMessage({type:`side-panel-heartbeat`,windowId:i,timestamp:Date.now()})}catch(e){console.error(`[side-panel-state-tracker] Heartbeat failed:`,e),t&&clearInterval(t)}},15e3),n=()=>{a({state:document.hidden?`hidden`:`visible`,reason:`visibility-change`})},document.addEventListener(`visibilitychange`,n),e.onDisconnect.addListener(()=>{console.warn(`[side-panel-state-tracker] Background connection lost`),t&&clearInterval(t)}),e.onMessage.addListener(e=>{e.type===`close-side-panel`&&(t&&clearInterval(t),window.close())}),a({state:document.hidden?`hidden`:`visible`,reason:`document-load`})}),()=>{t&&clearInterval(t),n&&document.removeEventListener(`visibilitychange`,n),e&&e.disconnect(),i=!1}}const o=new Map,s=new Set;let c=!1;function l(){c||console.error(`Side panel state manager is not initialized.`,`Call initSidePanelStateManager() at the top of your background script before using any other functions.`)}function u(){c||(c=!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&&f({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&&f({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:t,type:`side-panel-state-tracker`})})}))}))}function d(e){if(e.type!==`side-panel-state-tracker`)return;let t={state:e.state,reason:e.reason,windowId:e.windowId};s.forEach(e=>{try{e(t)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function f(e){let{windowId:t,state:n}=e;if(n===`hidden`){o.delete(t),d(e);return}o.set(t,e),d(e)}function p(e){return l(),o.get(e)?.state}function m(e){return l(),p(e)===`visible`}function h(e){return l(),s.add(e),()=>{s.delete(e)}}export{p as getSidePanelStateForWindow,u as initSidePanelStateManager,a as initializeSidePanelStateTracker,m as isWindowSidePanelVisible,h as onSidePanelStateChange,r as onWindowClose};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pixpilot/chrome-lifecycle",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Lifecycle management utilities for Chrome extensions.",
   "author": "m.doaie <m.doaie@hotmail.com>",
   "license": "MIT",
@@ -30,10 +30,10 @@
     "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/prettier-config": "0.1.0",
+    "@internal/vitest-config": "0.1.0",
+    "@internal/tsconfig": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {