+140

app/lib/session.d.ts

reviewed

··· 1 1 + /** 2 2 + * Session snapshot — shared pure logic for save/restore. 3 3 + * 4 4 + * Contains type definitions, URL extraction, parameter sanitization, 5 5 + * snapshot validation, crash detection heuristics, and restore 6 6 + * sequencing/ordering logic. 7 7 + * 8 8 + * @module session 9 9 + */ 10 10 + 11 11 + // ============================================================================ 12 12 + // Type definitions 13 13 + // ============================================================================ 14 14 + 15 15 + export interface Rectangle { 16 16 + x: number; 17 17 + y: number; 18 18 + width: number; 19 19 + height: number; 20 20 + } 21 21 + 22 22 + export interface WindowContext { 23 23 + mode: string | null; 24 24 + modeMetadata: Record<string, unknown> | null; 25 25 + } 26 26 + 27 27 + export interface WindowDescriptor { 28 28 + url: string; 29 29 + key: string | undefined; 30 30 + title: string; 31 31 + bounds: Rectangle; 32 32 + source: string; 33 33 + params: Record<string, unknown>; 34 34 + zOrder: number; 35 35 + focused: boolean; 36 36 + context?: WindowContext; 37 37 + } 38 38 + 39 39 + export interface SessionMetadata { 40 40 + lastSaveReason: string; 41 41 + lastSaveAt: number; 42 42 + windowCount: number; 43 43 + cleanShutdown: boolean; 44 44 + crashCount: number; 45 45 + lastRestoreAt?: number; 46 46 + restoreCount?: number; 47 47 + } 48 48 + 49 49 + export interface SessionSnapshot { 50 50 + version: 1; 51 51 + createdAt: number; 52 52 + reason: 'before-quit' | 'autosave' | 'manual'; 53 53 + windows: WindowDescriptor[]; 54 54 + } 55 55 + 56 56 + // ============================================================================ 57 57 + // Constants 58 58 + // ============================================================================ 59 59 + 60 60 + export declare const MAX_CRASH_COUNT: number; 61 61 + export declare const RESTORE_STRIP_KEYS: Set<string>; 62 62 + export declare const SYSTEM_WINDOW_URLS: string[]; 63 63 + 64 64 + // ============================================================================ 65 65 + // URL extraction 66 66 + // ============================================================================ 67 67 + 68 68 + export declare function extractRealUrl(url: string): string; 69 69 + export declare function extractCanvasBounds(url: string): Rectangle | null; 70 70 + 71 71 + // ============================================================================ 72 72 + // Parameter sanitization 73 73 + // ============================================================================ 74 74 + 75 75 + export declare function sanitizeParams(params: Record<string, unknown>): Record<string, unknown>; 76 76 + export declare function stripRestoreParams(params: Record<string, unknown>): Record<string, unknown>; 77 77 + 78 78 + // ============================================================================ 79 79 + // Snapshot validation 80 80 + // ============================================================================ 81 81 + 82 82 + export declare function isValidDescriptor(descriptor: WindowDescriptor): boolean; 83 83 + export declare function isSystemWindowUrl(url: string): boolean; 84 84 + export declare function validateSnapshot(snapshot: SessionSnapshot): { validWindows: WindowDescriptor[] } | null; 85 85 + 86 86 + // ============================================================================ 87 87 + // Crash detection heuristics 88 88 + // ============================================================================ 89 89 + 90 90 + export declare function determineCrashAction( 91 91 + wasCleanShutdown: boolean, 92 92 + crashCount: number 93 93 + ): 'restore' | 'ask' | 'skip'; 94 94 + 95 95 + export declare function computeCrashCount( 96 96 + wasCleanShutdown: boolean, 97 97 + previousCrashCount: number 98 98 + ): number; 99 99 + 100 100 + // ============================================================================ 101 101 + // Restore sequencing / ordering 102 102 + // ============================================================================ 103 103 + 104 104 + export declare function sortWindowsByZOrder(windows: WindowDescriptor[]): WindowDescriptor[]; 105 105 + 106 106 + export declare function computeRestoreBounds( 107 107 + bounds: Rectangle, 108 108 + isOnScreen: (x: number, y: number) => boolean 109 109 + ): { width: number; height: number; x?: number; y?: number }; 110 110 + 111 111 + export declare function buildRestoreOptions( 112 112 + descriptor: WindowDescriptor, 113 113 + isOnScreen: (x: number, y: number) => boolean 114 114 + ): Record<string, unknown>; 115 115 + 116 116 + // ============================================================================ 117 117 + // Restore result analysis 118 118 + // ============================================================================ 119 119 + 120 120 + export declare function isPartialRestore(result: { 121 121 + restored: number; 122 122 + failed: number; 123 123 + total: number; 124 124 + }): boolean; 125 125 + 126 126 + // ============================================================================ 127 127 + // Snapshot construction helpers 128 128 + // ============================================================================ 129 129 + 130 130 + export declare function buildSnapshot( 131 131 + windows: WindowDescriptor[], 132 132 + reason: 'before-quit' | 'autosave' | 'manual' 133 133 + ): SessionSnapshot; 134 134 + 135 135 + export declare function buildMetadata( 136 136 + reason: 'before-quit' | 'autosave' | 'manual', 137 137 + windowCount: number, 138 138 + existing?: Partial<SessionMetadata>, 139 139 + opts?: { cleanShutdown?: boolean } 140 140 + ): SessionMetadata;

+375

app/lib/session.js

reviewed

··· 1 1 + /** 2 2 + * Session snapshot — shared pure logic for save/restore. 3 3 + * 4 4 + * Contains type definitions, URL extraction, parameter sanitization, 5 5 + * snapshot validation, crash detection heuristics, and restore 6 6 + * sequencing/ordering logic. All functions are pure — no BrowserWindow, 7 7 + * no database, no Electron imports. 8 8 + * 9 9 + * Backend-specific operations (window enumeration, window creation, 10 10 + * database persistence, dialog display) remain in each backend's 11 11 + * session implementation. 12 12 + * 13 13 + * @module session 14 14 + */ 15 15 + 16 16 + // ============================================================================ 17 17 + // Constants 18 18 + // ============================================================================ 19 19 + 20 20 + /** 21 21 + * Maximum consecutive crash count before auto-skipping restore. 22 22 + * After this many crashes, the app starts fresh without asking. 23 23 + * @type {number} 24 24 + */ 25 25 + export const MAX_CRASH_COUNT = 3; 26 26 + 27 27 + /** 28 28 + * Keys stripped from window params during restore. 29 29 + * These are internal bookkeeping or context-dependent values that should be 30 30 + * re-derived from the URL and current environment during restore: 31 31 + * - x/y/width/height: stale positions from original creation (bounds are authoritative) 32 32 + * - role: saved role can trigger hasNonContentRole in window-open, preventing 33 33 + * canvas mode for web pages that had role 'workspace' 34 34 + * - escapeMode: affects role detection (escapeMode:'navigate' -> role:'workspace') 35 35 + * which also disables canvas mode for web pages 36 36 + * - address: internal bookkeeping param, overwritten by window-open anyway 37 37 + * - transient/parentWindowId: session state, not applicable to restored windows 38 38 + * @type {Set<string>} 39 39 + */ 40 40 + export const RESTORE_STRIP_KEYS = new Set([ 41 41 + 'x', 'y', 'width', 'height', 42 42 + 'role', 'escapeMode', 'address', 43 43 + 'transient', 'parentWindowId', 44 44 + ]); 45 45 + 46 46 + /** 47 47 + * URLs that identify internal system windows (should be excluded from snapshots). 48 48 + * @type {string[]} 49 49 + */ 50 50 + export const SYSTEM_WINDOW_URLS = [ 51 51 + 'peek://app/background.html', 52 52 + 'peek://app/extension-host.html', 53 53 + ]; 54 54 + 55 55 + // ============================================================================ 56 56 + // URL extraction 57 57 + // ============================================================================ 58 58 + 59 59 + /** 60 60 + * Extract the real URL from a page container URL. 61 61 + * Page containers use peek://app/page/index.html?url=<actual-url> 62 62 + * Returns the actual URL, or the original URL if not a container. 63 63 + * 64 64 + * @param {string} url - The possibly-rewritten peek:// URL 65 65 + * @returns {string} The actual URL 66 66 + */ 67 67 + export function extractRealUrl(url) { 68 68 + if (url.startsWith('peek://app/page')) { 69 69 + try { 70 70 + const parsed = new URL(url); 71 71 + const actualUrl = parsed.searchParams.get('url'); 72 72 + if (actualUrl) { 73 73 + return actualUrl; 74 74 + } 75 75 + } catch { 76 76 + // If URL parsing fails, keep the original 77 77 + } 78 78 + } 79 79 + return url; 80 80 + } 81 81 + 82 82 + /** 83 83 + * Extract webview bounds from a canvas page container URL. 84 84 + * Canvas pages encode the visible webview position/size in URL params. 85 85 + * Returns null if the URL is not a canvas page or params are missing. 86 86 + * 87 87 + * @param {string} url - The peek:// container URL 88 88 + * @returns {{ x: number, y: number, width: number, height: number } | null} 89 89 + */ 90 90 + export function extractCanvasBounds(url) { 91 91 + if (!url.startsWith('peek://app/page')) return null; 92 92 + try { 93 93 + const parsed = new URL(url); 94 94 + const x = parsed.searchParams.get('x'); 95 95 + const y = parsed.searchParams.get('y'); 96 96 + const width = parsed.searchParams.get('width'); 97 97 + const height = parsed.searchParams.get('height'); 98 98 + if (x && y && width && height) { 99 99 + return { 100 100 + x: parseInt(x, 10), 101 101 + y: parseInt(y, 10), 102 102 + width: parseInt(width, 10), 103 103 + height: parseInt(height, 10), 104 104 + }; 105 105 + } 106 106 + } catch { 107 107 + // If URL parsing fails, skip 108 108 + } 109 109 + return null; 110 110 + } 111 111 + 112 112 + // ============================================================================ 113 113 + // Parameter sanitization 114 114 + // ============================================================================ 115 115 + 116 116 + /** 117 117 + * Sanitize params to only include serializable values. 118 118 + * Filters out functions, complex objects, and other non-JSON-safe types. 119 119 + * Mirrors the logic in ipc.ts window-list handler. 120 120 + * 121 121 + * @param {Record<string, unknown>} params - Raw window params 122 122 + * @returns {Record<string, unknown>} Params safe for JSON serialization 123 123 + */ 124 124 + export function sanitizeParams(params) { 125 125 + const safe = {}; 126 126 + for (const [key, value] of Object.entries(params)) { 127 127 + const type = typeof value; 128 128 + if (type === 'string' || type === 'number' || type === 'boolean' || value === null) { 129 129 + safe[key] = value; 130 130 + } else if (Array.isArray(value)) { 131 131 + if (value.every(v => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v === null)) { 132 132 + safe[key] = value; 133 133 + } 134 134 + } 135 135 + // Skip functions, objects, etc. that may not serialize safely 136 136 + } 137 137 + return safe; 138 138 + } 139 139 + 140 140 + /** 141 141 + * Strip internal bookkeeping keys from params for restore. 142 142 + * Returns a new object without the keys that should be re-derived 143 143 + * from the URL and environment during window restoration. 144 144 + * 145 145 + * @param {Record<string, unknown>} params - Saved window params 146 146 + * @returns {Record<string, unknown>} Cleaned params for window-open 147 147 + */ 148 148 + export function stripRestoreParams(params) { 149 149 + const clean = {}; 150 150 + for (const [key, value] of Object.entries(params)) { 151 151 + if (!RESTORE_STRIP_KEYS.has(key)) { 152 152 + clean[key] = value; 153 153 + } 154 154 + } 155 155 + return clean; 156 156 + } 157 157 + 158 158 + // ============================================================================ 159 159 + // Snapshot validation 160 160 + // ============================================================================ 161 161 + 162 162 + /** 163 163 + * Validate that a window descriptor has the required fields for restore. 164 164 + * Returns false if the descriptor is invalid and should be skipped. 165 165 + * 166 166 + * @param {WindowDescriptor} descriptor 167 167 + * @returns {boolean} 168 168 + */ 169 169 + export function isValidDescriptor(descriptor) { 170 170 + // Must have a URL 171 171 + if (!descriptor.url || typeof descriptor.url !== 'string' || descriptor.url.trim() === '') { 172 172 + return false; 173 173 + } 174 174 + return true; 175 175 + } 176 176 + 177 177 + /** 178 178 + * Check if a URL belongs to an internal system window. 179 179 + * 180 180 + * @param {string} url - The window URL to check 181 181 + * @returns {boolean} True if this is a system window URL 182 182 + */ 183 183 + export function isSystemWindowUrl(url) { 184 184 + return SYSTEM_WINDOW_URLS.some(sysUrl => url.includes(sysUrl)); 185 185 + } 186 186 + 187 187 + /** 188 188 + * Validate a session snapshot and return valid window descriptors. 189 189 + * Checks version, filters invalid descriptors, returns null if nothing to restore. 190 190 + * 191 191 + * @param {SessionSnapshot} snapshot - The raw parsed snapshot 192 192 + * @returns {{ validWindows: WindowDescriptor[] } | null} Valid windows or null 193 193 + */ 194 194 + export function validateSnapshot(snapshot) { 195 195 + // Validate version 196 196 + if (!snapshot || snapshot.version !== 1) { 197 197 + return null; 198 198 + } 199 199 + 200 200 + // Check if there are windows to restore 201 201 + if (!snapshot.windows || snapshot.windows.length === 0) { 202 202 + return null; 203 203 + } 204 204 + 205 205 + // Filter out invalid descriptors 206 206 + const validWindows = snapshot.windows.filter(d => isValidDescriptor(d)); 207 207 + 208 208 + if (validWindows.length === 0) { 209 209 + return null; 210 210 + } 211 211 + 212 212 + return { validWindows }; 213 213 + } 214 214 + 215 215 + // ============================================================================ 216 216 + // Crash detection heuristics 217 217 + // ============================================================================ 218 218 + 219 219 + /** 220 220 + * Determine whether crash recovery dialog should be shown. 221 221 + * Only shown after repeated crashes (crashCount > 0 with unclean shutdown). 222 222 + * A single unclean shutdown (e.g. Ctrl+C, power loss) silently restores. 223 223 + * 224 224 + * @param {boolean} wasCleanShutdown - Whether last session shut down cleanly 225 225 + * @param {number} crashCount - Number of consecutive crashes 226 226 + * @returns {'restore' | 'ask' | 'skip'} Action to take 227 227 + */ 228 228 + export function determineCrashAction(wasCleanShutdown, crashCount) { 229 229 + if (wasCleanShutdown || crashCount === 0) { 230 230 + return 'restore'; 231 231 + } 232 232 + if (crashCount > MAX_CRASH_COUNT) { 233 233 + return 'skip'; 234 234 + } 235 235 + return 'ask'; 236 236 + } 237 237 + 238 238 + /** 239 239 + * Compute updated crash count based on previous shutdown state. 240 240 + * If the previous session was not clean, increments the crash count. 241 241 + * 242 242 + * @param {boolean} wasCleanShutdown - Previous session's clean shutdown flag 243 243 + * @param {number} previousCrashCount - Previous crash count 244 244 + * @returns {number} Updated crash count 245 245 + */ 246 246 + export function computeCrashCount(wasCleanShutdown, previousCrashCount) { 247 247 + if (wasCleanShutdown === false) { 248 248 + return previousCrashCount + 1; 249 249 + } 250 250 + return previousCrashCount; 251 251 + } 252 252 + 253 253 + // ============================================================================ 254 254 + // Restore sequencing / ordering 255 255 + // ============================================================================ 256 256 + 257 257 + /** 258 258 + * Sort window descriptors by z-order for restore sequencing. 259 259 + * Higher zOrder = later in stack = opened later. 260 260 + * Returns a new sorted array (does not mutate input). 261 261 + * 262 262 + * @param {WindowDescriptor[]} windows - Window descriptors to sort 263 263 + * @returns {WindowDescriptor[]} Sorted descriptors (back-to-front) 264 264 + */ 265 265 + export function sortWindowsByZOrder(windows) { 266 266 + return [...windows].sort((a, b) => b.zOrder - a.zOrder); 267 267 + } 268 268 + 269 269 + /** 270 270 + * Compute restore bounds for a window descriptor. 271 271 + * Calculates the center point and returns bounds options for window-open. 272 272 + * If the center point is off-screen (as determined by the caller's 273 273 + * isOnScreen callback), x/y are omitted so the backend can center the window. 274 274 + * 275 275 + * @param {{ x: number, y: number, width: number, height: number }} bounds - Saved window bounds 276 276 + * @param {(x: number, y: number) => boolean} isOnScreen - Callback to check if a point is on screen 277 277 + * @returns {{ width: number, height: number, x?: number, y?: number }} 278 278 + */ 279 279 + export function computeRestoreBounds(bounds, isOnScreen) { 280 280 + const centerX = bounds.x + Math.round(bounds.width / 2); 281 281 + const centerY = bounds.y + Math.round(bounds.height / 2); 282 282 + 283 283 + const result = { 284 284 + width: bounds.width, 285 285 + height: bounds.height, 286 286 + }; 287 287 + 288 288 + if (isOnScreen(centerX, centerY)) { 289 289 + result.x = bounds.x; 290 290 + result.y = bounds.y; 291 291 + } 292 292 + 293 293 + return result; 294 294 + } 295 295 + 296 296 + /** 297 297 + * Build restore options for a window from its descriptor. 298 298 + * Combines cleaned params with computed bounds and key. 299 299 + * 300 300 + * @param {WindowDescriptor} descriptor - The window descriptor 301 301 + * @param {(x: number, y: number) => boolean} isOnScreen - Screen bounds checker 302 302 + * @returns {Record<string, unknown>} Options object for window-open 303 303 + */ 304 304 + export function buildRestoreOptions(descriptor, isOnScreen) { 305 305 + const cleanParams = stripRestoreParams(descriptor.params); 306 306 + const boundsOptions = computeRestoreBounds(descriptor.bounds, isOnScreen); 307 307 + 308 308 + const options = { 309 309 + ...cleanParams, 310 310 + ...boundsOptions, 311 311 + }; 312 312 + 313 313 + if (descriptor.key) { 314 314 + options.key = descriptor.key; 315 315 + } 316 316 + 317 317 + return options; 318 318 + } 319 319 + 320 320 + // ============================================================================ 321 321 + // Restore result analysis 322 322 + // ============================================================================ 323 323 + 324 324 + /** 325 325 + * Check if a restore result indicates a problematic partial restore. 326 326 + * Returns true if more than half the windows failed (and there were 327 327 + * enough windows for this to be meaningful). 328 328 + * 329 329 + * @param {{ restored: number, failed: number, total: number }} result 330 330 + * @returns {boolean} 331 331 + */ 332 332 + export function isPartialRestore(result) { 333 333 + return result.failed > 0 && result.total > 2 && result.failed > result.total / 2; 334 334 + } 335 335 + 336 336 + // ============================================================================ 337 337 + // Snapshot construction helpers 338 338 + // ============================================================================ 339 339 + 340 340 + /** 341 341 + * Build a SessionSnapshot object from an array of window descriptors. 342 342 + * 343 343 + * @param {WindowDescriptor[]} windows - Collected window descriptors 344 344 + * @param {'before-quit' | 'autosave' | 'manual'} reason - Why the snapshot is being taken 345 345 + * @returns {SessionSnapshot} 346 346 + */ 347 347 + export function buildSnapshot(windows, reason) { 348 348 + return { 349 349 + version: 1, 350 350 + createdAt: Date.now(), 351 351 + reason, 352 352 + windows, 353 353 + }; 354 354 + } 355 355 + 356 356 + /** 357 357 + * Build a SessionMetadata object, preserving fields from existing metadata. 358 358 + * 359 359 + * @param {'before-quit' | 'autosave' | 'manual'} reason 360 360 + * @param {number} windowCount 361 361 + * @param {Partial<SessionMetadata>} [existing] - Previous metadata to merge 362 362 + * @param {{ cleanShutdown?: boolean }} [opts] 363 363 + * @returns {SessionMetadata} 364 364 + */ 365 365 + export function buildMetadata(reason, windowCount, existing, opts) { 366 366 + return { 367 367 + lastSaveReason: reason, 368 368 + lastSaveAt: Date.now(), 369 369 + windowCount, 370 370 + cleanShutdown: opts?.cleanShutdown !== false, 371 371 + crashCount: existing?.crashCount ?? 0, 372 372 + lastRestoreAt: existing?.lastRestoreAt, 373 373 + restoreCount: existing?.restoreCount, 374 374 + }; 375 375 + }

+2

backend/electron/session.ts

reviewed

··· 9 9 * Captures all visible user windows and writes to extension_settings 10 10 * using synchronous better-sqlite3 APIs (safe for before-quit handler). 11 11 * On startup, reads the snapshot and recreates windows. 12 12 + * 13 13 + * NOTE: Pure logic shared copy lives in app/lib/session.js for frontend/Tauri use. 12 14 */ 13 15 14 16 import { BrowserWindow, dialog, screen } from 'electron';