@pixpilot/chrome-lifecycle 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,130 @@
 # @pixpilot/chrome-lifecycle
 
-## Usage Add usage instructions here.
+Utilities for managing Chrome extension lifecycle events.
+
+## Installation
+
+```bash
+npm install @pixpilot/chrome-lifecycle
+```
+
+## API
+
+### Window Events
+
+#### `onWindowClose(windowId, callback)`
+
+Registers a callback when a specific Chrome window closes.
+
+```typescript
+import { onWindowClose } from '@pixpilot/chrome-lifecycle';
+
+const unsubscribe = onWindowClose(windowId, () => {
+  console.log('Window closed');
+});
+
+// Stop listening
+unsubscribe();
+```
+
+| Parameter  | Type         | Description                  |
+| ---------- | ------------ | ---------------------------- |
+| `windowId` | `number`     | Chrome window ID to watch    |
+| `callback` | `() => void` | Function to execute on close |
+
+**Returns:** Unsubscribe function
+
+---
+
+### Side Panel State Manager
+
+Tracks whether side panels are visible or hidden across different windows.
+
+#### Setup
+
+**Background script (service worker):**
+
+```typescript
+import { initSidePanelStateManager } from '@pixpilot/chrome-lifecycle';
+
+// Initialize once at startup
+initSidePanelStateManager();
+```
+
+**Side panel script (frontend):**
+
+```typescript
+import { initializeSidePanelStateTracker } from '@pixpilot/chrome-lifecycle';
+
+// Initialize when side panel loads
+const cleanup = initializeSidePanelStateTracker();
+```
+
+#### 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();
+```
+
+##### `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();
+```
+
+**Returns:** Cleanup function to remove listeners and disconnect
+
+##### `isWindowSidePanelVisible(windowId)`
+
+Returns `true` if the side panel is visible for the given window.
+
+```typescript
+import { isWindowSidePanelVisible } from '@pixpilot/chrome-lifecycle';
+
+const isVisible = isWindowSidePanelVisible(windowId);
+```
+
+##### `getSidePanelStateForWindow(windowId)`
+
+Returns the current state (`'visible'` | `'hidden'` | `undefined`) for the given window.
+
+```typescript
+import { getSidePanelStateForWindow } from '@pixpilot/chrome-lifecycle';
+
+const state = getSidePanelStateForWindow(windowId);
+```
+
+##### `onSidePanelStateChange(listener)`
+
+Listens for side panel state changes across all windows.
+
+```typescript
+import { onSidePanelStateChange } from '@pixpilot/chrome-lifecycle';
+
+const unsubscribe = onSidePanelStateChange(({ windowId, state, reason }) => {
+  console.log(`Window ${windowId}: ${state}`);
+});
+
+// Stop listening
+unsubscribe();
+```
+
+**Callback data:**
+
+| Property   | Type                      | Description               |
+| ---------- | ------------------------- | ------------------------- |
+| `windowId` | `number`                  | Chrome window ID          |
+| `state`    | `'visible'` \| `'hidden'` | Current side panel state  |
+| `reason`   | `string`                  | What triggered the change |
+
+**Returns:** Unsubscribe function

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))}}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=new Map,a=new Set;let o=!1;function s(){if(!o)throw Error(`Side panel state manager must be initialized with initSidePanelStateManager() before use.`)}function c(){o||(o=!0,chrome.action.onClicked.addListener(e=>{let t=i.get(e.windowId);t&&t.state===`visible`?t.port&&(i.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&&u({port:e,state:t.state,reason:t.reason??`unknown`,windowId:t.windowId,type:t.type})}),e.onDisconnect.addListener(e=>{Array.from(i.entries()).forEach(([t,n])=>{n.port&&n.port===e&&u({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:t,type:`side-panel-state-tracker`})})}))}))}function l(e){if(e.type!==`side-panel-state-tracker`)return;let t={state:e.state,reason:e.reason,windowId:e.windowId};a.forEach(e=>{try{e(t)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function u(e){let{windowId:t,state:n}=e;if(n===`hidden`){i.delete(t),l(e);return}i.set(t,e),l(e)}function d(e){return s(),i.get(e)?.state}function f(e){return s(),d(e)===`visible`}function p(e){return s(),a.add(e),()=>{a.delete(e)}}exports.getSidePanelStateForWindow=d,exports.initSidePanelStateManager=c,exports.isWindowSidePanelVisible=f,exports.onSidePanelStateChange=p,exports.onWindowClose=r;

package/dist/index.d.cts

@@ -17,4 +17,38 @@ type CloseCallback = () => void;
  */
 declare function onWindowClose(windowId: number, callback: CloseCallback): () => void;
 //#endregion
-export { onWindowClose };
+//#region src/types/side-panel.d.ts
+type SidePanelState = 'visible' | 'hidden';
+interface BaseSidePanelMessage {
+  windowId: number;
+  timestamp?: number;
+}
+interface SidePanelStateData extends BaseSidePanelMessage {
+  type: 'side-panel-heartbeat' | 'side-panel-state-tracker' | 'side-panel-state-open';
+  state: SidePanelState;
+  reason: string;
+}
+type SidePanelStateChangeData = Omit<SidePanelStateData, 'timestamp' | 'type'>;
+//#endregion
+//#region src/sidepanel-state-manager.d.ts
+type SidePanelStateListener = (data: SidePanelStateChangeData) => void;
+/**
+ * Initializes the side panel state manager.
+ * Sets up Chrome event listeners for action clicks and runtime connections.
+ * This function should be called once before using other functions in this module.
+ * Subsequent calls will log a warning and do nothing.
+ */
+declare function initSidePanelStateManager(): void;
+declare function getSidePanelStateForWindow(windowId: number): SidePanelState | undefined;
+declare function isWindowSidePanelVisible(windowId: number): boolean;
+/**
+ * Adds a listener for side panel state changes.
+ * The listener will be called whenever the side panel state changes (visible/hidden).
+ * Note: Heartbeat messages do not trigger listeners, and timestamp is excluded from the data.
+ *
+ * @param listener - Callback function that receives state change data
+ * @returns Unsubscribe function to remove the listener
+ */
+declare function onSidePanelStateChange(listener: SidePanelStateListener): () => void;
+//#endregion
+export { getSidePanelStateForWindow, initSidePanelStateManager, isWindowSidePanelVisible, onSidePanelStateChange, onWindowClose };

package/dist/index.d.ts

@@ -17,4 +17,38 @@ type CloseCallback = () => void;
  */
 declare function onWindowClose(windowId: number, callback: CloseCallback): () => void;
 //#endregion
-export { onWindowClose };
+//#region src/types/side-panel.d.ts
+type SidePanelState = 'visible' | 'hidden';
+interface BaseSidePanelMessage {
+  windowId: number;
+  timestamp?: number;
+}
+interface SidePanelStateData extends BaseSidePanelMessage {
+  type: 'side-panel-heartbeat' | 'side-panel-state-tracker' | 'side-panel-state-open';
+  state: SidePanelState;
+  reason: string;
+}
+type SidePanelStateChangeData = Omit<SidePanelStateData, 'timestamp' | 'type'>;
+//#endregion
+//#region src/sidepanel-state-manager.d.ts
+type SidePanelStateListener = (data: SidePanelStateChangeData) => void;
+/**
+ * Initializes the side panel state manager.
+ * Sets up Chrome event listeners for action clicks and runtime connections.
+ * This function should be called once before using other functions in this module.
+ * Subsequent calls will log a warning and do nothing.
+ */
+declare function initSidePanelStateManager(): void;
+declare function getSidePanelStateForWindow(windowId: number): SidePanelState | undefined;
+declare function isWindowSidePanelVisible(windowId: number): boolean;
+/**
+ * Adds a listener for side panel state changes.
+ * The listener will be called whenever the side panel state changes (visible/hidden).
+ * Note: Heartbeat messages do not trigger listeners, and timestamp is excluded from the data.
+ *
+ * @param listener - Callback function that receives state change data
+ * @returns Unsubscribe function to remove the listener
+ */
+declare function onSidePanelStateChange(listener: SidePanelStateListener): () => void;
+//#endregion
+export { getSidePanelStateForWindow, initSidePanelStateManager, 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))}}export{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))}}const i=new Map,a=new Set;let o=!1;function s(){if(!o)throw Error(`Side panel state manager must be initialized with initSidePanelStateManager() before use.`)}function c(){o||(o=!0,chrome.action.onClicked.addListener(e=>{let t=i.get(e.windowId);t&&t.state===`visible`?t.port&&(i.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&&u({port:e,state:t.state,reason:t.reason??`unknown`,windowId:t.windowId,type:t.type})}),e.onDisconnect.addListener(e=>{Array.from(i.entries()).forEach(([t,n])=>{n.port&&n.port===e&&u({port:void 0,state:`hidden`,reason:`port-disconnected`,windowId:t,type:`side-panel-state-tracker`})})}))}))}function l(e){if(e.type!==`side-panel-state-tracker`)return;let t={state:e.state,reason:e.reason,windowId:e.windowId};a.forEach(e=>{try{e(t)}catch(e){console.error(`Error in side panel state listener:`,e)}})}function u(e){let{windowId:t,state:n}=e;if(n===`hidden`){i.delete(t),l(e);return}i.set(t,e),l(e)}function d(e){return s(),i.get(e)?.state}function f(e){return s(),d(e)===`visible`}function p(e){return s(),a.add(e),()=>{a.delete(e)}}export{d as getSidePanelStateForWindow,c as initSidePanelStateManager,f as isWindowSidePanelVisible,p as onSidePanelStateChange,r as onWindowClose};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pixpilot/chrome-lifecycle",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.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/tsdown-config": "0.1.0",
+    "@internal/tsconfig": "0.1.0",
     "@internal/vitest-config": "0.1.0",
-    "@internal/tsconfig": "0.1.0"
+    "@internal/prettier-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {