@rockhall/electron-offline-content 0.4.0

package/dist/shared/types.d.ts

@@ -0,0 +1,234 @@
+import { MediaStore } from "../main/store.js";
+
+//#region src/shared/types.d.ts
+/** JSON-serializable values used in structured logs, metadata, and manifest extras. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** Minimum severity emitted when logging is configured; entries below this level are dropped. */
+type MediaCacheLogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * How the built-in main-process console sink formats each line when `logging.onLog` is omitted.
+ * Callback loggers always receive structured {@link MediaCacheLogEvent} objects regardless of this setting.
+ */
+type MediaCacheLogFormat = "english" | "json";
+/** One structured log line from the cache; includes standard fields plus optional diagnostic keys. */
+interface MediaCacheLogEvent {
+  [key: string]: JsonValue | undefined;
+  timestamp: string;
+  level: MediaCacheLogLevel;
+  event: string;
+  service: string;
+  component: string;
+}
+/** Receives log entries from the main-process cache when `logging.onLog` is set on {@link MediaCacheOptions}. */
+type MediaCacheLogHandler = (entry: MediaCacheLogEvent) => void;
+/** Logging options when using a custom structured sink. */
+interface MediaCacheCustomLoggingOptions {
+  level?: MediaCacheLogLevel;
+  onLog: MediaCacheLogHandler;
+  format?: never;
+}
+/** Logging options when using the built-in development console sink. */
+interface MediaCacheConsoleLoggingOptions {
+  level?: MediaCacheLogLevel;
+  format?: MediaCacheLogFormat;
+  onLog?: undefined;
+}
+/** Logging configuration for `MediaCacheOptions`; custom sinks and console formatting are mutually exclusive. */
+type MediaCacheLoggingOptions = MediaCacheCustomLoggingOptions | MediaCacheConsoleLoggingOptions;
+/** High-level media category derived from an asset's mimeType. */
+type MediaKind = "video" | "image" | "audio" | "document" | "html" | "text" | "binary";
+/** Accepted asset key input: a plain string or an array of string segments. */
+type AssetKeyInput = string | readonly string[];
+/** Tagged index entry produced by calling a {@link import("../main/store.js").MediaIndex} handle. */
+declare class IndexTag {
+  readonly name: string;
+  readonly value: string | string[];
+  constructor(name: string, value: string | string[]);
+}
+/** Input for adding an asset to a {@link import("../main/store.js").MediaStore}. */
+interface MediaAssetInput {
+  version: string;
+  mimeType: string;
+  url: string;
+  fileName?: string;
+  /**
+   * Optional declared size in bytes. When set, must be a **non-negative finite** number
+   * (`Number.isFinite` and `>= 0`). **Fractional values are allowed** (e.g. estimates);
+   * the store does not require integers.
+   */
+  byteLength?: number;
+  metadata?: Record<string, JsonValue>;
+  indexes?: IndexTag[];
+}
+/** Describes one user-defined or built-in index in the serialized store output. */
+interface IndexDefinition {
+  name: string;
+  cardinality: "single" | "multi";
+  required: boolean;
+  builtin: boolean;
+}
+/** One asset in the serialized flat manifest (output of `MediaStore._serialize()`). */
+interface FlatManifestAsset {
+  key: string;
+  displayKey: string;
+  version: string;
+  mimeType: string;
+  mediaKind: MediaKind;
+  url: string;
+  fileName: string;
+  fileStem: string;
+  byteLength?: number;
+  metadata: Record<string, JsonValue>;
+  indexes: Record<string, string | string[]>;
+}
+/** Serialized flat manifest produced by `MediaStore._serialize()` and consumed by the sync engine. */
+interface FlatManifest {
+  snapshotId?: string;
+  retrievedAt?: string;
+  expiresAt?: string;
+  indexDefinitions: IndexDefinition[];
+  assets: FlatManifestAsset[];
+}
+/**
+ * After a failed sync: keep serving the last committed generation (`serve-last-snapshot`), or
+ * propagate the failure (`throw`). Ignored when `devPassthrough` is true (failures always throw).
+ */
+type SyncFailureMode = "serve-last-snapshot" | "throw";
+/**
+ * Allowed `electron.app.getPath(...)` keys for package-managed storage root resolution.
+ */
+type MediaCacheAppPath = "home" | "appData" | "userData" | "sessionData" | "temp" | "exe" | "module" | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos" | "recent" | "logs" | "crashDumps";
+/** Storage root composed from `electron.app.getPath(appPath)` plus optional subpath segments. */
+interface MediaCacheStoragePath {
+  appPath: MediaCacheAppPath;
+  segments?: string[];
+}
+/**
+ * Main-process configuration: where state lives, sync and storage guardrails, logging, and how the
+ * store is resolved.
+ *
+ * Default behavior is offline mode unless `process.env.NODE_ENV` is `"development"`: assets sync to
+ * disk and resolved URLs use the privileged `media:` protocol.
+ */
+interface MediaCacheOptions {
+  storagePath: MediaCacheStoragePath;
+  devPassthrough?: boolean;
+  assetBaseUrl?: string | null;
+  maxCacheBytes?: number;
+  reserveFreeBytes?: number;
+  staleDeleteAfterMs?: number;
+  onSyncFailure?: SyncFailureMode;
+  syncHistoryLimit?: number;
+  logging?: MediaCacheLoggingOptions;
+  resolveStore: () => Promise<MediaStore> | MediaStore;
+}
+/** Cursor-based page for list APIs. */
+interface PaginationInput {
+  limit?: number;
+  cursor?: string;
+}
+/** One page of results; `nextCursor` is null when there are no more items. */
+interface PaginationResult<T> {
+  items: T[];
+  nextCursor: string | null;
+}
+/** Snapshot of sync and readiness state. */
+interface MediaCacheStatus {
+  phase: "idle" | "syncing" | "ready" | "error";
+  storageRoot: string | null;
+  activeGenerationId: number | null;
+  progress: SyncProgress | null;
+  lastRun: SyncRunSummary | null;
+  error: SerializedMediaCacheError | null;
+  updatedAt: number;
+}
+type MediaCachePhase = MediaCacheStatus["phase"] | "loading";
+/** Fine-grained sync pipeline step and counters while a run is active. */
+interface SyncProgress {
+  runId: number;
+  phase: "resolving-store" | "staging-generation" | "diffing" | "downloading" | "committing" | "pruning";
+  totalAssets: number;
+  completedAssets: number;
+  downloadedAssets: number;
+  skippedAssets: number;
+  bytesDownloaded: number;
+}
+/** Counters persisted with a {@link SyncRunSummary} after (or during) a sync run. */
+interface SyncRunStats {
+  totalAssets: number;
+  downloadedAssets: number;
+  skippedAssets: number;
+  bytesDownloaded: number;
+}
+/** Record of one sync run persisted for history. */
+interface SyncRunSummary {
+  id: number;
+  status: "running" | "success" | "error";
+  startedAt: number;
+  finishedAt: number | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+  stats: SyncRunStats;
+}
+/** One asset after resolution: flat key-value with `media:` URL or remote URL in passthrough mode. */
+interface ResolvedMediaAsset {
+  key: string;
+  displayKey: string;
+  version: string;
+  mimeType: string;
+  kind: MediaKind;
+  byteLength?: number;
+  url: string;
+  metadata: Record<string, JsonValue>;
+  indexes: Record<string, string | string[]>;
+}
+/** Assets whose manifest file name stem matched a search. */
+interface FileStemMatch {
+  asset: ResolvedMediaAsset;
+}
+/**
+ * Renderer-safe API to the cache: read/query operations plus status subscription.
+ */
+interface MediaCacheBridge {
+  getStatus(): Promise<MediaCacheStatus>;
+  syncNow(): Promise<void>;
+  getAsset(key: AssetKeyInput): Promise<ResolvedMediaAsset | null>;
+  listByIndex(indexName: string, value: string, pagination?: PaginationInput): Promise<PaginationResult<ResolvedMediaAsset>>;
+  findByFileStem(stem: string, pagination?: PaginationInput): Promise<PaginationResult<FileStemMatch>>;
+  subscribeStatus(listener: (status: MediaCacheStatus) => void): () => void;
+}
+/** Stable error shape stored on {@link MediaCacheStatus} when a sync fails. */
+interface SerializedMediaCacheError {
+  name: string;
+  code: string;
+  message: string;
+}
+/** Options for {@link import("../preload/index.js").exposeMediaCacheBridge}. */
+interface PreloadExposeOptions {
+  key?: string;
+}
+/** Optional sync-complete refetch behavior for React query hooks. */
+interface MediaQuerySyncOptions {
+  refetchOnSyncComplete?: boolean;
+}
+/** Derived readiness snapshot for `useMediaCacheReady()`. */
+interface MediaCacheReadyState {
+  ready: boolean;
+  syncing: boolean;
+  phase: MediaCacheStatus["phase"];
+  activeGenerationId: number | null;
+  syncError: SerializedMediaCacheError | null;
+}
+/** Aggregated error view for the provider-driven `useMediaCacheErrors()`. */
+interface MediaCacheErrors {
+  syncError: SerializedMediaCacheError | null;
+  statusError: Error | null;
+  queryErrors: Error[];
+  hasError: boolean;
+  primaryError: Error | null;
+}
+//#endregion
+export { AssetKeyInput, FileStemMatch, FlatManifest, FlatManifestAsset, IndexDefinition, IndexTag, JsonValue, MediaAssetInput, MediaCacheAppPath, MediaCacheBridge, MediaCacheConsoleLoggingOptions, MediaCacheCustomLoggingOptions, MediaCacheErrors, MediaCacheLogEvent, MediaCacheLogFormat, MediaCacheLogHandler, MediaCacheLogLevel, MediaCacheLoggingOptions, MediaCacheOptions, MediaCachePhase, MediaCacheReadyState, MediaCacheStatus, MediaCacheStoragePath, MediaKind, MediaQuerySyncOptions, PaginationInput, PaginationResult, PreloadExposeOptions, ResolvedMediaAsset, SerializedMediaCacheError, SyncFailureMode, SyncProgress, SyncRunStats, SyncRunSummary };
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/shared/types.ts"],"mappings":"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"}

package/dist/shared/types.js

@@ -0,0 +1,14 @@
+//#region src/shared/types.ts
+/** Tagged index entry produced by calling a {@link import("../main/store.js").MediaIndex} handle. */
+var IndexTag = class {
+	name;
+	value;
+	constructor(name, value) {
+		this.name = name;
+		this.value = value;
+	}
+};
+//#endregion
+export { IndexTag };
+
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/shared/types.ts"],"sourcesContent":["/** JSON-serializable values used in structured logs, metadata, and manifest extras. */\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n/** Minimum severity emitted when logging is configured; entries below this level are dropped. */\nexport type MediaCacheLogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\n/**\n * How the built-in main-process console sink formats each line when `logging.onLog` is omitted.\n * Callback loggers always receive structured {@link MediaCacheLogEvent} objects regardless of this setting.\n */\nexport type MediaCacheLogFormat = \"english\" | \"json\";\n\n/** One structured log line from the cache; includes standard fields plus optional diagnostic keys. */\nexport interface MediaCacheLogEvent {\n  [key: string]: JsonValue | undefined;\n  timestamp: string;\n  level: MediaCacheLogLevel;\n  event: string;\n  service: string;\n  component: string;\n}\n\n/** Receives log entries from the main-process cache when `logging.onLog` is set on {@link MediaCacheOptions}. */\nexport type MediaCacheLogHandler = (entry: MediaCacheLogEvent) => void;\n\n/** Logging options when using a custom structured sink. */\nexport interface MediaCacheCustomLoggingOptions {\n  level?: MediaCacheLogLevel;\n  onLog: MediaCacheLogHandler;\n  format?: never;\n}\n\n/** Logging options when using the built-in development console sink. */\nexport interface MediaCacheConsoleLoggingOptions {\n  level?: MediaCacheLogLevel;\n  format?: MediaCacheLogFormat;\n  onLog?: undefined;\n}\n\n/** Logging configuration for `MediaCacheOptions`; custom sinks and console formatting are mutually exclusive. */\nexport type MediaCacheLoggingOptions =\n  | MediaCacheCustomLoggingOptions\n  | MediaCacheConsoleLoggingOptions;\n\n/** High-level media category derived from an asset's mimeType. */\nexport type MediaKind = \"video\" | \"image\" | \"audio\" | \"document\" | \"html\" | \"text\" | \"binary\";\n\n/** Accepted asset key input: a plain string or an array of string segments. */\nexport type AssetKeyInput = string | readonly string[];\n\n/** Tagged index entry produced by calling a {@link import(\"../main/store.js\").MediaIndex} handle. */\nexport class IndexTag {\n  constructor(\n    readonly name: string,\n    readonly value: string | string[],\n  ) {}\n}\n\n/** Input for adding an asset to a {@link import(\"../main/store.js\").MediaStore}. */\nexport interface MediaAssetInput {\n  version: string;\n  mimeType: string;\n  url: string;\n  fileName?: string;\n  /**\n   * Optional declared size in bytes. When set, must be a **non-negative finite** number\n   * (`Number.isFinite` and `>= 0`). **Fractional values are allowed** (e.g. estimates);\n   * the store does not require integers.\n   */\n  byteLength?: number;\n  metadata?: Record<string, JsonValue>;\n  indexes?: IndexTag[];\n}\n\n/** Describes one user-defined or built-in index in the serialized store output. */\nexport interface IndexDefinition {\n  name: string;\n  cardinality: \"single\" | \"multi\";\n  required: boolean;\n  builtin: boolean;\n}\n\n/** One asset in the serialized flat manifest (output of `MediaStore._serialize()`). */\nexport interface FlatManifestAsset {\n  key: string;\n  displayKey: string;\n  version: string;\n  mimeType: string;\n  mediaKind: MediaKind;\n  url: string;\n  fileName: string;\n  fileStem: string;\n  byteLength?: number;\n  metadata: Record<string, JsonValue>;\n  indexes: Record<string, string | string[]>;\n}\n\n/** Serialized flat manifest produced by `MediaStore._serialize()` and consumed by the sync engine. */\nexport interface FlatManifest {\n  snapshotId?: string;\n  retrievedAt?: string;\n  expiresAt?: string;\n  indexDefinitions: IndexDefinition[];\n  assets: FlatManifestAsset[];\n}\n\n/**\n * After a failed sync: keep serving the last committed generation (`serve-last-snapshot`), or\n * propagate the failure (`throw`). Ignored when `devPassthrough` is true (failures always throw).\n */\nexport type SyncFailureMode = \"serve-last-snapshot\" | \"throw\";\n\n/**\n * Allowed `electron.app.getPath(...)` keys for package-managed storage root resolution.\n */\nexport type MediaCacheAppPath =\n  | \"home\"\n  | \"appData\"\n  | \"userData\"\n  | \"sessionData\"\n  | \"temp\"\n  | \"exe\"\n  | \"module\"\n  | \"desktop\"\n  | \"documents\"\n  | \"downloads\"\n  | \"music\"\n  | \"pictures\"\n  | \"videos\"\n  | \"recent\"\n  | \"logs\"\n  | \"crashDumps\";\n\n/** Storage root composed from `electron.app.getPath(appPath)` plus optional subpath segments. */\nexport interface MediaCacheStoragePath {\n  appPath: MediaCacheAppPath;\n  segments?: string[];\n}\n\n/**\n * Main-process configuration: where state lives, sync and storage guardrails, logging, and how the\n * store is resolved.\n *\n * Default behavior is offline mode unless `process.env.NODE_ENV` is `\"development\"`: assets sync to\n * disk and resolved URLs use the privileged `media:` protocol.\n */\nexport interface MediaCacheOptions {\n  storagePath: MediaCacheStoragePath;\n  devPassthrough?: boolean;\n  assetBaseUrl?: string | null;\n  maxCacheBytes?: number;\n  reserveFreeBytes?: number;\n  staleDeleteAfterMs?: number;\n  onSyncFailure?: SyncFailureMode;\n  syncHistoryLimit?: number;\n  logging?: MediaCacheLoggingOptions;\n  resolveStore: () =>\n    | Promise<import(\"../main/store.js\").MediaStore>\n    | import(\"../main/store.js\").MediaStore;\n}\n\n/** Cursor-based page for list APIs. */\nexport interface PaginationInput {\n  limit?: number;\n  cursor?: string;\n}\n\n/** One page of results; `nextCursor` is null when there are no more items. */\nexport interface PaginationResult<T> {\n  items: T[];\n  nextCursor: string | null;\n}\n\n/** Snapshot of sync and readiness state. */\nexport interface MediaCacheStatus {\n  phase: \"idle\" | \"syncing\" | \"ready\" | \"error\";\n  storageRoot: string | null;\n  activeGenerationId: number | null;\n  progress: SyncProgress | null;\n  lastRun: SyncRunSummary | null;\n  error: SerializedMediaCacheError | null;\n  updatedAt: number;\n}\n\nexport type MediaCachePhase = MediaCacheStatus[\"phase\"] | \"loading\";\n\n/** Fine-grained sync pipeline step and counters while a run is active. */\nexport interface SyncProgress {\n  runId: number;\n  phase:\n    | \"resolving-store\"\n    | \"staging-generation\"\n    | \"diffing\"\n    | \"downloading\"\n    | \"committing\"\n    | \"pruning\";\n  totalAssets: number;\n  completedAssets: number;\n  downloadedAssets: number;\n  skippedAssets: number;\n  bytesDownloaded: number;\n}\n\n/** Counters persisted with a {@link SyncRunSummary} after (or during) a sync run. */\nexport interface SyncRunStats {\n  totalAssets: number;\n  downloadedAssets: number;\n  skippedAssets: number;\n  bytesDownloaded: number;\n}\n\n/** Record of one sync run persisted for history. */\nexport interface SyncRunSummary {\n  id: number;\n  status: \"running\" | \"success\" | \"error\";\n  startedAt: number;\n  finishedAt: number | null;\n  errorCode: string | null;\n  errorMessage: string | null;\n  stats: SyncRunStats;\n}\n\n/** One asset after resolution: flat key-value with `media:` URL or remote URL in passthrough mode. */\nexport interface ResolvedMediaAsset {\n  key: string;\n  displayKey: string;\n  version: string;\n  mimeType: string;\n  kind: MediaKind;\n  byteLength?: number;\n  url: string;\n  metadata: Record<string, JsonValue>;\n  indexes: Record<string, string | string[]>;\n}\n\n/** Assets whose manifest file name stem matched a search. */\nexport interface FileStemMatch {\n  asset: ResolvedMediaAsset;\n}\n\n/**\n * Renderer-safe API to the cache: read/query operations plus status subscription.\n */\nexport interface MediaCacheBridge {\n  getStatus(): Promise<MediaCacheStatus>;\n  syncNow(): Promise<void>;\n  getAsset(key: AssetKeyInput): Promise<ResolvedMediaAsset | null>;\n  listByIndex(\n    indexName: string,\n    value: string,\n    pagination?: PaginationInput,\n  ): Promise<PaginationResult<ResolvedMediaAsset>>;\n  findByFileStem(\n    stem: string,\n    pagination?: PaginationInput,\n  ): Promise<PaginationResult<FileStemMatch>>;\n  subscribeStatus(listener: (status: MediaCacheStatus) => void): () => void;\n}\n\n/** Stable error shape stored on {@link MediaCacheStatus} when a sync fails. */\nexport interface SerializedMediaCacheError {\n  name: string;\n  code: string;\n  message: string;\n}\n\n/** Options for {@link import(\"../preload/index.js\").exposeMediaCacheBridge}. */\nexport interface PreloadExposeOptions {\n  key?: string;\n}\n\n/** Optional sync-complete refetch behavior for React query hooks. */\nexport interface MediaQuerySyncOptions {\n  refetchOnSyncComplete?: boolean;\n}\n\n/** Derived readiness snapshot for `useMediaCacheReady()`. */\nexport interface MediaCacheReadyState {\n  ready: boolean;\n  syncing: boolean;\n  phase: MediaCacheStatus[\"phase\"];\n  activeGenerationId: number | null;\n  syncError: SerializedMediaCacheError | null;\n}\n\n/** Aggregated error view for the provider-driven `useMediaCacheErrors()`. */\nexport interface MediaCacheErrors {\n  syncError: SerializedMediaCacheError | null;\n  statusError: Error | null;\n  queryErrors: Error[];\n  hasError: boolean;\n  primaryError: Error | null;\n}\n"],"mappings":";;AAyDA,IAAa,WAAb,MAAsB;CAET;CACA;CAFX,YACE,MACA,OACA;EAFS,KAAA,OAAA;EACA,KAAA,QAAA"}

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@rockhall/electron-offline-content",
+  "version": "0.4.0",
+  "description": "A package for Electron apps to download, stage, and serve offline content from a remote source. Supports video, images, audio, text content, and more.",
+  "keywords": [
+    "cache",
+    "electron",
+    "media",
+    "offline",
+    "react",
+    "sqlite"
+  ],
+  "homepage": "https://github.com/rockhallweb/electron-offline-content#readme",
+  "bugs": {
+    "url": "https://github.com/rockhallweb/electron-offline-content/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rockhallweb/electron-offline-content.git"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "!skills/_artifacts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./main": {
+      "types": "./dist/main/index.d.ts",
+      "import": "./dist/main/index.js",
+      "require": "./dist/main/index.cjs"
+    },
+    "./preload": {
+      "types": "./dist/preload/index.d.ts",
+      "import": "./dist/preload/index.js",
+      "require": "./dist/preload/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./renderer": {
+      "types": "./dist/renderer/index.d.ts",
+      "import": "./dist/renderer/index.js",
+      "require": "./dist/renderer/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc --noEmit",
+    "lint": "oxlint --config .oxlintrc.json --react-plugin --vitest-plugin --node-plugin --deny-warnings .",
+    "lint:fix": "oxlint --config .oxlintrc.json --react-plugin --vitest-plugin --node-plugin --fix --deny-warnings .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "test": "vitest run --config vitest.node.config.ts && vitest run --config vitest.node.integration.config.ts && vitest run --config vitest.react.config.ts && vitest run --config vitest.renderer.config.ts",
+    "test:smoke": "vitest run --config vitest.node.smoke.config.ts",
+    "test:react": "vitest run --config vitest.react.config.ts",
+    "test:renderer": "vitest run --config vitest.renderer.config.ts",
+    "test:watch": "vitest",
+    "validate": "turbo run lint format:check check && turbo run test:smoke && turbo run test:react && turbo run test:renderer && turbo run build",
+    "worktree:new": "node scripts/worktree.mjs create",
+    "worktree:open": "node scripts/worktree.mjs open",
+    "worktree:list": "git worktree list",
+    "worktree:prune": "git worktree prune",
+    "examples:verify": "node scripts/run-examples.mjs validate",
+    "examples:validate": "pnpm build && node scripts/run-examples.mjs validate",
+    "pack:verify": "node scripts/pack-verify.mjs",
+    "ci:examples": "pnpm install --frozen-lockfile --dir examples/local && pnpm install --frozen-lockfile --dir examples/nasa && pnpm examples:verify",
+    "ci:validate": "pnpm validate"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@tanstack/intent": "^0.0.41",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^24.5.2",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "@vitest/coverage-v8": "^4.1.6",
+    "electron": "^40.0.0",
+    "happy-dom": "^20.9.0",
+    "knip": "^6.12.2",
+    "oxfmt": "^0.49.0",
+    "oxlint": "^1.64.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tsdown": "^0.22.0",
+    "turbo": "^2.9.12",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "electron": ">=40.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24.0.0",
+    "pnpm": ">=11.0.0"
+  },
+  "packageManager": "pnpm@11.1.0"
+}

package/skills/authenticated-downloads/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: authenticated-downloads
+description: >
+  Adding authentication to asset downloads in the flat store model by
+  embedding presigned (or otherwise signed) URLs in each asset’s top-level
+  url field during resolveStore. Pre-signed URL expiration vs catalog sync
+  duration tradeoff.
+type: core
+library: electron-offline-content
+library_version: "0.4.0"
+requires:
+  - store-authoring
+sources:
+  - "rockhallweb/electron-offline-content:src/main/media-cache.ts"
+  - "rockhallweb/electron-offline-content:src/main/store.ts"
+  - "rockhallweb/electron-offline-content:src/shared/types.ts"
+  - "rockhallweb/electron-offline-content:README.md"
+---
+
+> **Dependency:** This skill builds on store-authoring. Read it first for resolveStore and createMediaStore patterns.
+
+## Setup
+
+A `resolveStore` function that embeds S3 pre-signed URLs at store build time:
+
+```typescript
+import { createMediaCache, createMediaStore } from "@rockhall/electron-offline-content/main";
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+const s3 = new S3Client({ region: "us-east-1" });
+
+const mediaCache = createMediaCache({
+  storagePath: { appPath: "userData", segments: ["offline-media"] },
+  resolveStore: async () => {
+    const store = createMediaStore();
+    const catalog = await fetchCatalog();
+
+    for (const item of catalog) {
+      const signedUrl = await getSignedUrl(
+        s3,
+        new GetObjectCommand({
+          Bucket: "my-content-bucket",
+          Key: item.objectKey,
+        }),
+        { expiresIn: 3600 },
+      );
+
+      store.add(["assets", item.id], {
+        version: item.revision,
+        mimeType: "video/mp4",
+        url: signedUrl,
+        metadata: item.metadata,
+      });
+    }
+
+    return store;
+  },
+});
+```
+
+## Core Patterns
+
+### Embedding presigned URLs in resolveStore
+
+All authentication is handled during `resolveStore()`. The download pipeline fetches each asset using only its `url` string. Put signing parameters, tokens, or credentials into that URL (for example an S3 presigned URL) before calling `store.add`.
+
+```typescript
+import { createMediaStore } from "@rockhall/electron-offline-content/main";
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+const s3 = new S3Client({ region: "us-east-1" });
+
+async function resolveStore() {
+  const store = createMediaStore();
+  const catalog = await fetchCatalog();
+
+  for (const item of catalog) {
+    const signedUrl = await getSignedUrl(
+      s3,
+      new GetObjectCommand({ Bucket: "my-content-bucket", Key: item.objectKey }),
+      { expiresIn: 3600 },
+    );
+
+    store.add(["assets", item.id], {
+      version: item.revision,
+      mimeType: "video/mp4",
+      url: signedUrl,
+    });
+  }
+
+  return store;
+}
+```
+
+### OAuth or rotating credentials
+
+If you use short-lived tokens, exchange them for presigned download URLs (or a backend-issued URL that already includes auth) inside `resolveStore` before calling `store.add`. The library does not accept separate auth configuration per asset—only the final URL string.
+
+### TTL and catalog size
+
+| Scenario            | Recommendation                                                                   |
+| ------------------- | -------------------------------------------------------------------------------- |
+| Any protected asset | Presign (or otherwise embed auth in) the `url` before `store.add`.               |
+| Small catalog       | Presign in `resolveStore` with a TTL that comfortably exceeds full sync time.    |
+| Large catalog       | Use a long TTL and set store `expiresAt` to match for fail-fast `STORE_EXPIRED`. |
+
+## Common Mistakes
+
+### HIGH: Pre-signed URL expiration too short for full catalog sync
+
+When embedding pre-signed URLs in `resolveStore`, the TTL must exceed total download time for **all** assets. Assets late in the queue fail with opaque HTTP 403 when URLs expire mid-sync.
+
+Set `expiresAt` on the store to the earliest shared expiration timestamp so the cache can fail fast with `STORE_EXPIRED` before a later asset is fetched with a stale URL.
+
+Wrong — short TTL on a large catalog:
+
+```typescript
+async function resolveStore() {
+  const store = createMediaStore();
+  for (const item of await fetchCatalog()) {
+    const signedUrl = await getSignedUrl(
+      s3,
+      new GetObjectCommand({ Bucket: "b", Key: item.key }),
+      { expiresIn: 300 }, // 5 minutes — too short for 500 assets
+    );
+    store.add(["assets", item.id], { version: item.rev, mimeType: "video/mp4", url: signedUrl });
+  }
+  return store;
+}
+```
+
+Correct — generous TTL with `expiresAt`:
+
+```typescript
+async function resolveStore() {
+  const ttlSeconds = 3600;
+  const expiresAt = new Date(Date.now() + ttlSeconds * 1000).toISOString();
+  const store = createMediaStore({ expiresAt });
+
+  for (const item of await fetchCatalog()) {
+    const signedUrl = await getSignedUrl(s3, new GetObjectCommand({ Bucket: "b", Key: item.key }), {
+      expiresIn: ttlSeconds,
+    });
+    store.add(["assets", item.id], {
+      version: item.rev,
+      mimeType: "video/mp4",
+      url: signedUrl,
+    });
+  }
+
+  return store;
+}
+```
+
+Source: Maintainer interview
+
+### HIGH: Auth not tested in offline mode
+
+In dev passthrough mode, assets load from their original remote URLs directly in the renderer. Auth issues only surface when `devPassthrough` is `false` and the main process downloads assets using the URLs from `resolveStore`.
+
+Wrong — testing only in dev passthrough:
+
+```typescript
+const mediaCache = createMediaCache({
+  storagePath: { appPath: "userData", segments: ["offline-media"] },
+  devPassthrough: true,
+  resolveStore: async () => buildAuthenticatedStore(),
+});
+// "It works!" — but auth URLs are never actually used for downloads
+```
+
+Correct — test with `devPassthrough: false` to verify auth:
+
+```typescript
+const mediaCache = createMediaCache({
+  storagePath: { appPath: "userData", segments: ["offline-media"] },
+  devPassthrough: false,
+  resolveStore: async () => buildAuthenticatedStore(),
+});
+```
+
+Source: README
+Cross-skill: cache-configuration/SKILL.md § Common Mistakes
+
+### HIGH Tension: Pre-signed URL TTL vs catalog size
+
+Pre-signed URLs embedded at store build time are simple but have a TTL ceiling: expiration must cover the entire download queue. For large catalogs, evaluate expected sync duration and set TTLs accordingly. Use store `expiresAt` for fail-fast behavior.
+
+See also: store-authoring/SKILL.md § Common Mistakes
+
+### HIGH Tension: Dev passthrough simplicity vs production correctness
+
+`devPassthrough` bypasses downloads entirely. Code that works in dev (where auth isn't needed for public URLs) may fail in production when assets require signed downloads.
+
+See also: cache-configuration/SKILL.md § Common Mistakes
+
+---
+
+See also: store-authoring/SKILL.md — Asset URL definition and resolveStore
+See also: cache-configuration/SKILL.md — devPassthrough mode bypasses downloads
+See also: production-checklist/SKILL.md — Verify auth works in offline mode before deploy