@rockhall/electron-offline-content 0.4.0

package/dist/main/store.cjs

@@ -0,0 +1,197 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_shared_errors = require("../shared/errors.cjs");
+const require_internal_asset_key = require("../internal/asset-key.cjs");
+const require_internal_asset_file_name = require("../internal/asset-file-name.cjs");
+const require_internal_media_kind = require("../internal/media-kind.cjs");
+const require_shared_types = require("../shared/types.cjs");
+//#region src/main/store.ts
+const MIME_PATTERN = /^\S+\/\S+$/;
+const BUILTIN_INDEX_NAMES = new Set(["mimeType", "mediaKind"]);
+function fileStem(fileName) {
+	const dotIndex = fileName.lastIndexOf(".");
+	return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
+}
+/**
+* A flat key-value asset store with user-defined secondary indexes.
+*
+* Build a store imperatively inside your `resolveStore` callback:
+*
+* ```ts
+* const store = createMediaStore();
+* const gallery = store.defineIndex("gallery");
+* store.add(["forest", "video"], {
+*   version: "v1",
+*   mimeType: "video/mp4",
+*   url: "https://cdn.example.com/forest.mp4",
+*   indexes: [gallery("nature")],
+* });
+* ```
+*/
+var MediaStore = class {
+	options;
+	indexes = /* @__PURE__ */ new Map();
+	assets = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options ?? {};
+	}
+	/**
+	* Register a secondary index that assets can be tagged with and queried by.
+	* Must be called before any {@link add} call that references this index.
+	*
+	* @param name - Unique index name. Must not collide with built-in indexes (`mimeType`, `mediaKind`).
+	* @param options - Cardinality (`"single"` or `"multi"`) and whether the index is required on every asset.
+	* @returns A callable {@link MediaIndex} handle. Call it with a value to produce an {@link IndexTag}.
+	*/
+	defineIndex(name, options) {
+		if (!name) throw new require_shared_errors.StoreValidationError("Index name must be a non-empty string.");
+		if (BUILTIN_INDEX_NAMES.has(name)) throw new require_shared_errors.StoreValidationError(`Index name "${name}" is reserved as a built-in index.`);
+		if (this.indexes.has(name)) throw new require_shared_errors.StoreValidationError(`Duplicate index name "${name}".`);
+		const cardinality = options?.cardinality ?? "single";
+		const required = options?.required ?? false;
+		if (cardinality !== "single" && cardinality !== "multi") throw new require_shared_errors.StoreValidationError(`Index "${name}": cardinality must be "single" or "multi" (got "${String(cardinality)}").`);
+		if (typeof required !== "boolean") throw new require_shared_errors.StoreValidationError(`Index "${name}": required must be a boolean (got ${typeof required}).`);
+		this.indexes.set(name, {
+			name,
+			cardinality,
+			required,
+			builtin: false
+		});
+		const fn = (value) => new require_shared_types.IndexTag(name, value);
+		Object.defineProperties(fn, {
+			indexName: {
+				value: name,
+				enumerable: true
+			},
+			cardinality: {
+				value: cardinality,
+				enumerable: true
+			},
+			required: {
+				value: required,
+				enumerable: true
+			}
+		});
+		return fn;
+	}
+	/**
+	* Add an asset to the store.
+	*
+	* @param key - Unique asset key. A string or array of string segments (e.g. `["videos", "hubble", "main"]`).
+	* @param input - Asset data: version, mimeType, source, and optional indexes/metadata.
+	*/
+	add(key, input) {
+		if (!require_internal_asset_key.isValidKeyInput(key)) throw new require_shared_errors.StoreValidationError("Asset key must be a non-empty string or non-empty string array.");
+		const hashedKey = require_internal_asset_key.hashKey(key);
+		const display = require_internal_asset_key.displayKey(key);
+		if (this.assets.has(hashedKey)) throw new require_shared_errors.StoreValidationError(`Duplicate asset key "${display}" (hash collision with existing key).`);
+		if (!input.version) throw new require_shared_errors.StoreValidationError(`Asset "${display}": version is required.`);
+		if (!input.mimeType || !MIME_PATTERN.test(input.mimeType)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": mimeType must be a valid type/subtype string (got "${input.mimeType ?? ""}").`);
+		if (!input.url) throw new require_shared_errors.StoreValidationError(`Asset "${display}": url is required.`);
+		try {
+			const parsed = new URL(input.url);
+			if (!/^https?:$/i.test(parsed.protocol)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": URL must use http or https (got "${parsed.protocol}").`);
+		} catch (err) {
+			if (err instanceof require_shared_errors.StoreValidationError) throw err;
+			throw new require_shared_errors.StoreValidationError(`Asset "${display}": URL is not valid: "${input.url}".`);
+		}
+		if (input.byteLength !== void 0 && (typeof input.byteLength !== "number" || !Number.isFinite(input.byteLength) || input.byteLength < 0)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": byteLength must be a non-negative finite number (got ${String(input.byteLength)}).`);
+		const fileName = input.fileName ?? require_internal_asset_file_name.deriveAssetFileName(input.url);
+		const assetIndexes = Object.create(null);
+		if (input.indexes !== void 0 && !Array.isArray(input.indexes)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`);
+		if (input.indexes) for (const tag of input.indexes) {
+			if (!(tag instanceof require_shared_types.IndexTag)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`);
+			const indexName = tag.name;
+			const value = tag.value;
+			const def = this.indexes.get(indexName);
+			if (!def) throw new require_shared_errors.StoreValidationError(`Asset "${display}": index "${indexName}" has not been defined. Call store.defineIndex("${indexName}") first.`);
+			if (Object.hasOwn(assetIndexes, indexName)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": duplicate index "${indexName}" in indexes array.`);
+			if (def.cardinality === "single") {
+				if (Array.isArray(value)) throw new require_shared_errors.StoreValidationError(`Asset "${display}": index "${indexName}" has single cardinality but received an array. Use { cardinality: "multi" } when defining the index to allow arrays.`);
+				if (typeof value !== "string" || !value) throw new require_shared_errors.StoreValidationError(`Asset "${display}": index "${indexName}" value must be a non-empty string.`);
+				assetIndexes[indexName] = value;
+			} else {
+				const values = Array.isArray(value) ? value : [value];
+				if (values.length === 0) throw new require_shared_errors.StoreValidationError(`Asset "${display}": index "${indexName}" value array must not be empty.`);
+				for (const v of values) if (typeof v !== "string" || !v) throw new require_shared_errors.StoreValidationError(`Asset "${display}": index "${indexName}" values must be non-empty strings.`);
+				assetIndexes[indexName] = [...new Set(values)];
+			}
+		}
+		const metadataSnapshot = input.metadata === void 0 ? {} : structuredClone(input.metadata);
+		this.assets.set(hashedKey, {
+			key: hashedKey,
+			displayKey: display,
+			version: input.version,
+			mimeType: input.mimeType,
+			url: input.url,
+			fileName,
+			byteLength: input.byteLength,
+			metadata: metadataSnapshot,
+			indexes: assetIndexes
+		});
+	}
+	/**
+	* Serialize the store for the sync engine. Validates required indexes and produces
+	* the flat manifest consumed internally. Not part of the public consumer API.
+	* @internal
+	*/
+	_serialize() {
+		for (const [, def] of this.indexes) {
+			if (!def.required) continue;
+			for (const [, asset] of this.assets) if (!(def.name in asset.indexes)) throw new require_shared_errors.StoreValidationError(`Asset "${asset.displayKey}": required index "${def.name}" is missing.`);
+		}
+		const indexDefinitions = [
+			...Array.from(this.indexes.values()),
+			{
+				name: "mimeType",
+				cardinality: "single",
+				required: false,
+				builtin: true
+			},
+			{
+				name: "mediaKind",
+				cardinality: "single",
+				required: false,
+				builtin: true
+			}
+		];
+		const assets = [];
+		for (const [, stored] of this.assets) {
+			const mediaKind = require_internal_media_kind.mediaKindFromMime(stored.mimeType);
+			const stem = fileStem(stored.fileName);
+			const allIndexes = {
+				...stored.indexes,
+				mimeType: stored.mimeType,
+				mediaKind
+			};
+			assets.push({
+				key: stored.key,
+				displayKey: stored.displayKey,
+				version: stored.version,
+				mimeType: stored.mimeType,
+				mediaKind,
+				url: stored.url,
+				fileName: stored.fileName,
+				fileStem: stem,
+				byteLength: stored.byteLength,
+				metadata: stored.metadata,
+				indexes: allIndexes
+			});
+		}
+		return {
+			snapshotId: this.options.snapshotId,
+			retrievedAt: this.options.retrievedAt,
+			expiresAt: this.options.expiresAt,
+			indexDefinitions,
+			assets
+		};
+	}
+};
+/** Creates a new {@link MediaStore} for populating in a `resolveStore` callback. */
+function createMediaStore(options) {
+	return new MediaStore(options);
+}
+//#endregion
+exports.MediaStore = MediaStore;
+exports.createMediaStore = createMediaStore;
+
+//# sourceMappingURL=store.cjs.map

package/dist/main/store.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.cjs","names":["StoreValidationError","IndexTag","isValidKeyInput","hashKey","displayKey","deriveAssetFileName","mediaKindFromMime"],"sources":["../../src/main/store.ts"],"sourcesContent":["import { StoreValidationError } from \"../shared/errors.js\";\nimport { deriveAssetFileName } from \"../internal/asset-file-name.js\";\nimport { mediaKindFromMime } from \"../internal/media-kind.js\";\nimport { hashKey, displayKey, isValidKeyInput, type AssetKeyInput } from \"../internal/asset-key.js\";\nimport {\n  IndexTag,\n  type FlatManifest,\n  type FlatManifestAsset,\n  type IndexDefinition,\n  type JsonValue,\n  type MediaAssetInput,\n} from \"../shared/types.js\";\n\nconst MIME_PATTERN = /^\\S+\\/\\S+$/;\n\nconst BUILTIN_INDEX_NAMES = new Set([\"mimeType\", \"mediaKind\"]);\n\nfunction fileStem(fileName: string): string {\n  const dotIndex = fileName.lastIndexOf(\".\");\n  return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;\n}\n\n/**\n * Callable handle returned by {@link MediaStore.defineIndex}. Call it with a value\n * to produce an {@link IndexTag} for use in the `indexes` array of {@link MediaStore.add}:\n *\n * ```ts\n * const gallery = store.defineIndex(\"gallery\");\n * store.add(\"photo-1\", { ..., indexes: [gallery(\"nature\")] });\n * ```\n */\nexport interface MediaIndex {\n  (value: string | string[]): IndexTag;\n  readonly indexName: string;\n  readonly cardinality: \"single\" | \"multi\";\n  readonly required: boolean;\n}\n\n/** Options for {@link createMediaStore}. */\nexport interface MediaStoreOptions {\n  /** Optional opaque id for correlation, debugging, or multi-source merges. */\n  snapshotId?: string;\n  /** ISO 8601 timestamp describing when the store payload was built. */\n  retrievedAt?: string;\n  /**\n   * ISO 8601 timestamp after which source URLs must be treated as expired.\n   * Sync will fail assets whose download starts after this time.\n   */\n  expiresAt?: string;\n}\n\ninterface StoredAsset {\n  key: string;\n  displayKey: string;\n  version: string;\n  mimeType: string;\n  url: string;\n  fileName: string;\n  byteLength?: number;\n  metadata: Record<string, JsonValue>;\n  indexes: Record<string, string | string[]>;\n}\n\n/**\n * A flat key-value asset store with user-defined secondary indexes.\n *\n * Build a store imperatively inside your `resolveStore` callback:\n *\n * ```ts\n * const store = createMediaStore();\n * const gallery = store.defineIndex(\"gallery\");\n * store.add([\"forest\", \"video\"], {\n *   version: \"v1\",\n *   mimeType: \"video/mp4\",\n *   url: \"https://cdn.example.com/forest.mp4\",\n *   indexes: [gallery(\"nature\")],\n * });\n * ```\n */\nexport class MediaStore {\n  private readonly options: MediaStoreOptions;\n  private readonly indexes = new Map<string, IndexDefinition>();\n  private readonly assets = new Map<string, StoredAsset>();\n\n  constructor(options?: MediaStoreOptions) {\n    this.options = options ?? {};\n  }\n\n  /**\n   * Register a secondary index that assets can be tagged with and queried by.\n   * Must be called before any {@link add} call that references this index.\n   *\n   * @param name - Unique index name. Must not collide with built-in indexes (`mimeType`, `mediaKind`).\n   * @param options - Cardinality (`\"single\"` or `\"multi\"`) and whether the index is required on every asset.\n   * @returns A callable {@link MediaIndex} handle. Call it with a value to produce an {@link IndexTag}.\n   */\n  defineIndex(\n    name: string,\n    options?: { cardinality?: \"single\" | \"multi\"; required?: boolean },\n  ): MediaIndex {\n    if (!name) {\n      throw new StoreValidationError(\"Index name must be a non-empty string.\");\n    }\n    if (BUILTIN_INDEX_NAMES.has(name)) {\n      throw new StoreValidationError(`Index name \"${name}\" is reserved as a built-in index.`);\n    }\n    if (this.indexes.has(name)) {\n      throw new StoreValidationError(`Duplicate index name \"${name}\".`);\n    }\n\n    const cardinality = options?.cardinality ?? \"single\";\n    const required = options?.required ?? false;\n\n    if (cardinality !== \"single\" && cardinality !== \"multi\") {\n      throw new StoreValidationError(\n        `Index \"${name}\": cardinality must be \"single\" or \"multi\" (got \"${String(cardinality)}\").`,\n      );\n    }\n    if (typeof required !== \"boolean\") {\n      throw new StoreValidationError(\n        `Index \"${name}\": required must be a boolean (got ${typeof required}).`,\n      );\n    }\n\n    this.indexes.set(name, { name, cardinality, required, builtin: false });\n\n    const fn = (value: string | string[]) => new IndexTag(name, value);\n    Object.defineProperties(fn, {\n      indexName: { value: name, enumerable: true },\n      cardinality: { value: cardinality, enumerable: true },\n      required: { value: required, enumerable: true },\n    });\n    return fn as MediaIndex;\n  }\n\n  /**\n   * Add an asset to the store.\n   *\n   * @param key - Unique asset key. A string or array of string segments (e.g. `[\"videos\", \"hubble\", \"main\"]`).\n   * @param input - Asset data: version, mimeType, source, and optional indexes/metadata.\n   */\n  add(key: AssetKeyInput, input: MediaAssetInput): void {\n    if (!isValidKeyInput(key)) {\n      throw new StoreValidationError(\n        \"Asset key must be a non-empty string or non-empty string array.\",\n      );\n    }\n    const hashedKey = hashKey(key);\n    const display = displayKey(key);\n    if (this.assets.has(hashedKey)) {\n      throw new StoreValidationError(\n        `Duplicate asset key \"${display}\" (hash collision with existing key).`,\n      );\n    }\n\n    if (!input.version) {\n      throw new StoreValidationError(`Asset \"${display}\": version is required.`);\n    }\n    if (!input.mimeType || !MIME_PATTERN.test(input.mimeType)) {\n      throw new StoreValidationError(\n        `Asset \"${display}\": mimeType must be a valid type/subtype string (got \"${input.mimeType ?? \"\"}\").`,\n      );\n    }\n    if (!input.url) {\n      throw new StoreValidationError(`Asset \"${display}\": url is required.`);\n    }\n    try {\n      const parsed = new URL(input.url);\n      if (!/^https?:$/i.test(parsed.protocol)) {\n        throw new StoreValidationError(\n          `Asset \"${display}\": URL must use http or https (got \"${parsed.protocol}\").`,\n        );\n      }\n    } catch (err) {\n      if (err instanceof StoreValidationError) throw err;\n      throw new StoreValidationError(`Asset \"${display}\": URL is not valid: \"${input.url}\".`);\n    }\n\n    // byteLength: any non-negative finite number is accepted, including non-integer fractions\n    // (see MediaAssetInput.byteLength JSDoc).\n    if (\n      input.byteLength !== undefined &&\n      (typeof input.byteLength !== \"number\" ||\n        !Number.isFinite(input.byteLength) ||\n        input.byteLength < 0)\n    ) {\n      throw new StoreValidationError(\n        `Asset \"${display}\": byteLength must be a non-negative finite number (got ${String(input.byteLength)}).`,\n      );\n    }\n\n    const fileName = input.fileName ?? deriveAssetFileName(input.url);\n\n    const assetIndexes: Record<string, string | string[]> = Object.create(null);\n    if (input.indexes !== undefined && !Array.isArray(input.indexes)) {\n      throw new StoreValidationError(\n        `Asset \"${display}\": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`,\n      );\n    }\n    if (input.indexes) {\n      for (const tag of input.indexes) {\n        if (!(tag instanceof IndexTag)) {\n          throw new StoreValidationError(\n            `Asset \"${display}\": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`,\n          );\n        }\n        const indexName = tag.name;\n        const value = tag.value;\n        const def = this.indexes.get(indexName);\n        if (!def) {\n          throw new StoreValidationError(\n            `Asset \"${display}\": index \"${indexName}\" has not been defined. Call store.defineIndex(\"${indexName}\") first.`,\n          );\n        }\n        if (Object.hasOwn(assetIndexes, indexName)) {\n          throw new StoreValidationError(\n            `Asset \"${display}\": duplicate index \"${indexName}\" in indexes array.`,\n          );\n        }\n\n        if (def.cardinality === \"single\") {\n          if (Array.isArray(value)) {\n            throw new StoreValidationError(\n              `Asset \"${display}\": index \"${indexName}\" has single cardinality but received an array. ` +\n                `Use { cardinality: \"multi\" } when defining the index to allow arrays.`,\n            );\n          }\n          if (typeof value !== \"string\" || !value) {\n            throw new StoreValidationError(\n              `Asset \"${display}\": index \"${indexName}\" value must be a non-empty string.`,\n            );\n          }\n          assetIndexes[indexName] = value;\n        } else {\n          const values = Array.isArray(value) ? value : [value];\n          if (values.length === 0) {\n            throw new StoreValidationError(\n              `Asset \"${display}\": index \"${indexName}\" value array must not be empty.`,\n            );\n          }\n          for (const v of values) {\n            if (typeof v !== \"string\" || !v) {\n              throw new StoreValidationError(\n                `Asset \"${display}\": index \"${indexName}\" values must be non-empty strings.`,\n              );\n            }\n          }\n          assetIndexes[indexName] = [...new Set(values)];\n        }\n      }\n    }\n\n    const metadataSnapshot = input.metadata === undefined ? {} : structuredClone(input.metadata);\n\n    this.assets.set(hashedKey, {\n      key: hashedKey,\n      displayKey: display,\n      version: input.version,\n      mimeType: input.mimeType,\n      url: input.url,\n      fileName,\n      byteLength: input.byteLength,\n      metadata: metadataSnapshot,\n      indexes: assetIndexes,\n    });\n  }\n\n  /**\n   * Serialize the store for the sync engine. Validates required indexes and produces\n   * the flat manifest consumed internally. Not part of the public consumer API.\n   * @internal\n   */\n  _serialize(): FlatManifest {\n    for (const [, def] of this.indexes) {\n      if (!def.required) continue;\n      for (const [, asset] of this.assets) {\n        if (!(def.name in asset.indexes)) {\n          throw new StoreValidationError(\n            `Asset \"${asset.displayKey}\": required index \"${def.name}\" is missing.`,\n          );\n        }\n      }\n    }\n\n    const indexDefinitions: IndexDefinition[] = [\n      ...Array.from(this.indexes.values()),\n      { name: \"mimeType\", cardinality: \"single\", required: false, builtin: true },\n      { name: \"mediaKind\", cardinality: \"single\", required: false, builtin: true },\n    ];\n\n    const assets: FlatManifestAsset[] = [];\n    for (const [, stored] of this.assets) {\n      const mediaKind = mediaKindFromMime(stored.mimeType);\n      const stem = fileStem(stored.fileName);\n\n      const allIndexes: Record<string, string | string[]> = {\n        ...stored.indexes,\n        mimeType: stored.mimeType,\n        mediaKind,\n      };\n\n      assets.push({\n        key: stored.key,\n        displayKey: stored.displayKey,\n        version: stored.version,\n        mimeType: stored.mimeType,\n        mediaKind,\n        url: stored.url,\n        fileName: stored.fileName,\n        fileStem: stem,\n        byteLength: stored.byteLength,\n        metadata: stored.metadata,\n        indexes: allIndexes,\n      });\n    }\n\n    return {\n      snapshotId: this.options.snapshotId,\n      retrievedAt: this.options.retrievedAt,\n      expiresAt: this.options.expiresAt,\n      indexDefinitions,\n      assets,\n    };\n  }\n}\n\n/** Creates a new {@link MediaStore} for populating in a `resolveStore` callback. */\nexport function createMediaStore(options?: MediaStoreOptions): MediaStore {\n  return new MediaStore(options);\n}\n"],"mappings":"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"}

package/dist/main/store.d.cts

@@ -0,0 +1,83 @@
+import { AssetKeyInput } from "../internal/asset-key.cjs";
+import { FlatManifest, IndexTag, MediaAssetInput } from "../shared/types.cjs";
+
+//#region src/main/store.d.ts
+/**
+ * Callable handle returned by {@link MediaStore.defineIndex}. Call it with a value
+ * to produce an {@link IndexTag} for use in the `indexes` array of {@link MediaStore.add}:
+ *
+ * ```ts
+ * const gallery = store.defineIndex("gallery");
+ * store.add("photo-1", { ..., indexes: [gallery("nature")] });
+ * ```
+ */
+interface MediaIndex {
+  (value: string | string[]): IndexTag;
+  readonly indexName: string;
+  readonly cardinality: "single" | "multi";
+  readonly required: boolean;
+}
+/** Options for {@link createMediaStore}. */
+interface MediaStoreOptions {
+  /** Optional opaque id for correlation, debugging, or multi-source merges. */
+  snapshotId?: string;
+  /** ISO 8601 timestamp describing when the store payload was built. */
+  retrievedAt?: string;
+  /**
+   * ISO 8601 timestamp after which source URLs must be treated as expired.
+   * Sync will fail assets whose download starts after this time.
+   */
+  expiresAt?: string;
+}
+/**
+ * A flat key-value asset store with user-defined secondary indexes.
+ *
+ * Build a store imperatively inside your `resolveStore` callback:
+ *
+ * ```ts
+ * const store = createMediaStore();
+ * const gallery = store.defineIndex("gallery");
+ * store.add(["forest", "video"], {
+ *   version: "v1",
+ *   mimeType: "video/mp4",
+ *   url: "https://cdn.example.com/forest.mp4",
+ *   indexes: [gallery("nature")],
+ * });
+ * ```
+ */
+declare class MediaStore {
+  private readonly options;
+  private readonly indexes;
+  private readonly assets;
+  constructor(options?: MediaStoreOptions);
+  /**
+   * Register a secondary index that assets can be tagged with and queried by.
+   * Must be called before any {@link add} call that references this index.
+   *
+   * @param name - Unique index name. Must not collide with built-in indexes (`mimeType`, `mediaKind`).
+   * @param options - Cardinality (`"single"` or `"multi"`) and whether the index is required on every asset.
+   * @returns A callable {@link MediaIndex} handle. Call it with a value to produce an {@link IndexTag}.
+   */
+  defineIndex(name: string, options?: {
+    cardinality?: "single" | "multi";
+    required?: boolean;
+  }): MediaIndex;
+  /**
+   * Add an asset to the store.
+   *
+   * @param key - Unique asset key. A string or array of string segments (e.g. `["videos", "hubble", "main"]`).
+   * @param input - Asset data: version, mimeType, source, and optional indexes/metadata.
+   */
+  add(key: AssetKeyInput, input: MediaAssetInput): void;
+  /**
+   * Serialize the store for the sync engine. Validates required indexes and produces
+   * the flat manifest consumed internally. Not part of the public consumer API.
+   * @internal
+   */
+  _serialize(): FlatManifest;
+}
+/** Creates a new {@link MediaStore} for populating in a `resolveStore` callback. */
+declare function createMediaStore(options?: MediaStoreOptions): MediaStore;
+//#endregion
+export { MediaIndex, MediaStore, MediaStoreOptions, createMediaStore };
+//# sourceMappingURL=store.d.cts.map

package/dist/main/store.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.cts","names":[],"sources":["../../src/main/store.ts"],"mappings":";;;;;;AA+BA;;;;;;;UAAiB,UAAA;EAAA,CACd,KAAA,sBAA2B,QAAA;EAAA,SACnB,SAAA;EAAA,SACA,WAAA;EAAA,SACA,QAAA;AAAA;;UAIM,iBAAA;EAEf;EAAA,UAAA;EAOA;EALA,WAAA;EAKS;AA+BX;;;EA/BE,SAAA;AAAA;;;;;;;;;;;;;;;;;cA+BW,UAAA;EAAA,iBACM,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,MAAA;cAEL,OAAA,GAAU,iBAAA;EAyDE;;;;;AA0L1B;;;EAvOE,WAAA,CACE,IAAA,UACA,OAAA;IAAY,WAAA;IAAkC,QAAA;EAAA,IAC7C,UAAA;EAoOoE;;;;;;EA1LvE,GAAA,CAAI,GAAA,EAAK,aAAA,EAAe,KAAA,EAAO,eAAA;;;;;;EAmI/B,UAAA,CAAA,GAAc,YAAA;AAAA;;iBAuDA,gBAAA,CAAiB,OAAA,GAAU,iBAAA,GAAoB,UAAA"}

package/dist/main/store.d.ts

@@ -0,0 +1,83 @@
+import { AssetKeyInput } from "../internal/asset-key.js";
+import { FlatManifest, IndexTag, MediaAssetInput } from "../shared/types.js";
+
+//#region src/main/store.d.ts
+/**
+ * Callable handle returned by {@link MediaStore.defineIndex}. Call it with a value
+ * to produce an {@link IndexTag} for use in the `indexes` array of {@link MediaStore.add}:
+ *
+ * ```ts
+ * const gallery = store.defineIndex("gallery");
+ * store.add("photo-1", { ..., indexes: [gallery("nature")] });
+ * ```
+ */
+interface MediaIndex {
+  (value: string | string[]): IndexTag;
+  readonly indexName: string;
+  readonly cardinality: "single" | "multi";
+  readonly required: boolean;
+}
+/** Options for {@link createMediaStore}. */
+interface MediaStoreOptions {
+  /** Optional opaque id for correlation, debugging, or multi-source merges. */
+  snapshotId?: string;
+  /** ISO 8601 timestamp describing when the store payload was built. */
+  retrievedAt?: string;
+  /**
+   * ISO 8601 timestamp after which source URLs must be treated as expired.
+   * Sync will fail assets whose download starts after this time.
+   */
+  expiresAt?: string;
+}
+/**
+ * A flat key-value asset store with user-defined secondary indexes.
+ *
+ * Build a store imperatively inside your `resolveStore` callback:
+ *
+ * ```ts
+ * const store = createMediaStore();
+ * const gallery = store.defineIndex("gallery");
+ * store.add(["forest", "video"], {
+ *   version: "v1",
+ *   mimeType: "video/mp4",
+ *   url: "https://cdn.example.com/forest.mp4",
+ *   indexes: [gallery("nature")],
+ * });
+ * ```
+ */
+declare class MediaStore {
+  private readonly options;
+  private readonly indexes;
+  private readonly assets;
+  constructor(options?: MediaStoreOptions);
+  /**
+   * Register a secondary index that assets can be tagged with and queried by.
+   * Must be called before any {@link add} call that references this index.
+   *
+   * @param name - Unique index name. Must not collide with built-in indexes (`mimeType`, `mediaKind`).
+   * @param options - Cardinality (`"single"` or `"multi"`) and whether the index is required on every asset.
+   * @returns A callable {@link MediaIndex} handle. Call it with a value to produce an {@link IndexTag}.
+   */
+  defineIndex(name: string, options?: {
+    cardinality?: "single" | "multi";
+    required?: boolean;
+  }): MediaIndex;
+  /**
+   * Add an asset to the store.
+   *
+   * @param key - Unique asset key. A string or array of string segments (e.g. `["videos", "hubble", "main"]`).
+   * @param input - Asset data: version, mimeType, source, and optional indexes/metadata.
+   */
+  add(key: AssetKeyInput, input: MediaAssetInput): void;
+  /**
+   * Serialize the store for the sync engine. Validates required indexes and produces
+   * the flat manifest consumed internally. Not part of the public consumer API.
+   * @internal
+   */
+  _serialize(): FlatManifest;
+}
+/** Creates a new {@link MediaStore} for populating in a `resolveStore` callback. */
+declare function createMediaStore(options?: MediaStoreOptions): MediaStore;
+//#endregion
+export { MediaIndex, MediaStore, MediaStoreOptions, createMediaStore };
+//# sourceMappingURL=store.d.ts.map

package/dist/main/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","names":[],"sources":["../../src/main/store.ts"],"mappings":";;;;;;AA+BA;;;;;;;UAAiB,UAAA;EAAA,CACd,KAAA,sBAA2B,QAAA;EAAA,SACnB,SAAA;EAAA,SACA,WAAA;EAAA,SACA,QAAA;AAAA;;UAIM,iBAAA;EAEf;EAAA,UAAA;EAOA;EALA,WAAA;EAKS;AA+BX;;;EA/BE,SAAA;AAAA;;;;;;;;;;;;;;;;;cA+BW,UAAA;EAAA,iBACM,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,MAAA;cAEL,OAAA,GAAU,iBAAA;EAyDE;;;;;AA0L1B;;;EAvOE,WAAA,CACE,IAAA,UACA,OAAA;IAAY,WAAA;IAAkC,QAAA;EAAA,IAC7C,UAAA;EAoOoE;;;;;;EA1LvE,GAAA,CAAI,GAAA,EAAK,aAAA,EAAe,KAAA,EAAO,eAAA;;;;;;EAmI/B,UAAA,CAAA,GAAc,YAAA;AAAA;;iBAuDA,gBAAA,CAAiB,OAAA,GAAU,iBAAA,GAAoB,UAAA"}

package/dist/main/store.js

@@ -0,0 +1,195 @@
+import { StoreValidationError } from "../shared/errors.js";
+import { displayKey, hashKey, isValidKeyInput } from "../internal/asset-key.js";
+import { deriveAssetFileName } from "../internal/asset-file-name.js";
+import { mediaKindFromMime } from "../internal/media-kind.js";
+import { IndexTag } from "../shared/types.js";
+//#region src/main/store.ts
+const MIME_PATTERN = /^\S+\/\S+$/;
+const BUILTIN_INDEX_NAMES = new Set(["mimeType", "mediaKind"]);
+function fileStem(fileName) {
+	const dotIndex = fileName.lastIndexOf(".");
+	return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
+}
+/**
+* A flat key-value asset store with user-defined secondary indexes.
+*
+* Build a store imperatively inside your `resolveStore` callback:
+*
+* ```ts
+* const store = createMediaStore();
+* const gallery = store.defineIndex("gallery");
+* store.add(["forest", "video"], {
+*   version: "v1",
+*   mimeType: "video/mp4",
+*   url: "https://cdn.example.com/forest.mp4",
+*   indexes: [gallery("nature")],
+* });
+* ```
+*/
+var MediaStore = class {
+	options;
+	indexes = /* @__PURE__ */ new Map();
+	assets = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options ?? {};
+	}
+	/**
+	* Register a secondary index that assets can be tagged with and queried by.
+	* Must be called before any {@link add} call that references this index.
+	*
+	* @param name - Unique index name. Must not collide with built-in indexes (`mimeType`, `mediaKind`).
+	* @param options - Cardinality (`"single"` or `"multi"`) and whether the index is required on every asset.
+	* @returns A callable {@link MediaIndex} handle. Call it with a value to produce an {@link IndexTag}.
+	*/
+	defineIndex(name, options) {
+		if (!name) throw new StoreValidationError("Index name must be a non-empty string.");
+		if (BUILTIN_INDEX_NAMES.has(name)) throw new StoreValidationError(`Index name "${name}" is reserved as a built-in index.`);
+		if (this.indexes.has(name)) throw new StoreValidationError(`Duplicate index name "${name}".`);
+		const cardinality = options?.cardinality ?? "single";
+		const required = options?.required ?? false;
+		if (cardinality !== "single" && cardinality !== "multi") throw new StoreValidationError(`Index "${name}": cardinality must be "single" or "multi" (got "${String(cardinality)}").`);
+		if (typeof required !== "boolean") throw new StoreValidationError(`Index "${name}": required must be a boolean (got ${typeof required}).`);
+		this.indexes.set(name, {
+			name,
+			cardinality,
+			required,
+			builtin: false
+		});
+		const fn = (value) => new IndexTag(name, value);
+		Object.defineProperties(fn, {
+			indexName: {
+				value: name,
+				enumerable: true
+			},
+			cardinality: {
+				value: cardinality,
+				enumerable: true
+			},
+			required: {
+				value: required,
+				enumerable: true
+			}
+		});
+		return fn;
+	}
+	/**
+	* Add an asset to the store.
+	*
+	* @param key - Unique asset key. A string or array of string segments (e.g. `["videos", "hubble", "main"]`).
+	* @param input - Asset data: version, mimeType, source, and optional indexes/metadata.
+	*/
+	add(key, input) {
+		if (!isValidKeyInput(key)) throw new StoreValidationError("Asset key must be a non-empty string or non-empty string array.");
+		const hashedKey = hashKey(key);
+		const display = displayKey(key);
+		if (this.assets.has(hashedKey)) throw new StoreValidationError(`Duplicate asset key "${display}" (hash collision with existing key).`);
+		if (!input.version) throw new StoreValidationError(`Asset "${display}": version is required.`);
+		if (!input.mimeType || !MIME_PATTERN.test(input.mimeType)) throw new StoreValidationError(`Asset "${display}": mimeType must be a valid type/subtype string (got "${input.mimeType ?? ""}").`);
+		if (!input.url) throw new StoreValidationError(`Asset "${display}": url is required.`);
+		try {
+			const parsed = new URL(input.url);
+			if (!/^https?:$/i.test(parsed.protocol)) throw new StoreValidationError(`Asset "${display}": URL must use http or https (got "${parsed.protocol}").`);
+		} catch (err) {
+			if (err instanceof StoreValidationError) throw err;
+			throw new StoreValidationError(`Asset "${display}": URL is not valid: "${input.url}".`);
+		}
+		if (input.byteLength !== void 0 && (typeof input.byteLength !== "number" || !Number.isFinite(input.byteLength) || input.byteLength < 0)) throw new StoreValidationError(`Asset "${display}": byteLength must be a non-negative finite number (got ${String(input.byteLength)}).`);
+		const fileName = input.fileName ?? deriveAssetFileName(input.url);
+		const assetIndexes = Object.create(null);
+		if (input.indexes !== void 0 && !Array.isArray(input.indexes)) throw new StoreValidationError(`Asset "${display}": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`);
+		if (input.indexes) for (const tag of input.indexes) {
+			if (!(tag instanceof IndexTag)) throw new StoreValidationError(`Asset "${display}": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`);
+			const indexName = tag.name;
+			const value = tag.value;
+			const def = this.indexes.get(indexName);
+			if (!def) throw new StoreValidationError(`Asset "${display}": index "${indexName}" has not been defined. Call store.defineIndex("${indexName}") first.`);
+			if (Object.hasOwn(assetIndexes, indexName)) throw new StoreValidationError(`Asset "${display}": duplicate index "${indexName}" in indexes array.`);
+			if (def.cardinality === "single") {
+				if (Array.isArray(value)) throw new StoreValidationError(`Asset "${display}": index "${indexName}" has single cardinality but received an array. Use { cardinality: "multi" } when defining the index to allow arrays.`);
+				if (typeof value !== "string" || !value) throw new StoreValidationError(`Asset "${display}": index "${indexName}" value must be a non-empty string.`);
+				assetIndexes[indexName] = value;
+			} else {
+				const values = Array.isArray(value) ? value : [value];
+				if (values.length === 0) throw new StoreValidationError(`Asset "${display}": index "${indexName}" value array must not be empty.`);
+				for (const v of values) if (typeof v !== "string" || !v) throw new StoreValidationError(`Asset "${display}": index "${indexName}" values must be non-empty strings.`);
+				assetIndexes[indexName] = [...new Set(values)];
+			}
+		}
+		const metadataSnapshot = input.metadata === void 0 ? {} : structuredClone(input.metadata);
+		this.assets.set(hashedKey, {
+			key: hashedKey,
+			displayKey: display,
+			version: input.version,
+			mimeType: input.mimeType,
+			url: input.url,
+			fileName,
+			byteLength: input.byteLength,
+			metadata: metadataSnapshot,
+			indexes: assetIndexes
+		});
+	}
+	/**
+	* Serialize the store for the sync engine. Validates required indexes and produces
+	* the flat manifest consumed internally. Not part of the public consumer API.
+	* @internal
+	*/
+	_serialize() {
+		for (const [, def] of this.indexes) {
+			if (!def.required) continue;
+			for (const [, asset] of this.assets) if (!(def.name in asset.indexes)) throw new StoreValidationError(`Asset "${asset.displayKey}": required index "${def.name}" is missing.`);
+		}
+		const indexDefinitions = [
+			...Array.from(this.indexes.values()),
+			{
+				name: "mimeType",
+				cardinality: "single",
+				required: false,
+				builtin: true
+			},
+			{
+				name: "mediaKind",
+				cardinality: "single",
+				required: false,
+				builtin: true
+			}
+		];
+		const assets = [];
+		for (const [, stored] of this.assets) {
+			const mediaKind = mediaKindFromMime(stored.mimeType);
+			const stem = fileStem(stored.fileName);
+			const allIndexes = {
+				...stored.indexes,
+				mimeType: stored.mimeType,
+				mediaKind
+			};
+			assets.push({
+				key: stored.key,
+				displayKey: stored.displayKey,
+				version: stored.version,
+				mimeType: stored.mimeType,
+				mediaKind,
+				url: stored.url,
+				fileName: stored.fileName,
+				fileStem: stem,
+				byteLength: stored.byteLength,
+				metadata: stored.metadata,
+				indexes: allIndexes
+			});
+		}
+		return {
+			snapshotId: this.options.snapshotId,
+			retrievedAt: this.options.retrievedAt,
+			expiresAt: this.options.expiresAt,
+			indexDefinitions,
+			assets
+		};
+	}
+};
+/** Creates a new {@link MediaStore} for populating in a `resolveStore` callback. */
+function createMediaStore(options) {
+	return new MediaStore(options);
+}
+//#endregion
+export { MediaStore, createMediaStore };
+
+//# sourceMappingURL=store.js.map

package/dist/main/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":[],"sources":["../../src/main/store.ts"],"sourcesContent":["import { StoreValidationError } from \"../shared/errors.js\";\nimport { deriveAssetFileName } from \"../internal/asset-file-name.js\";\nimport { mediaKindFromMime } from \"../internal/media-kind.js\";\nimport { hashKey, displayKey, isValidKeyInput, type AssetKeyInput } from \"../internal/asset-key.js\";\nimport {\n  IndexTag,\n  type FlatManifest,\n  type FlatManifestAsset,\n  type IndexDefinition,\n  type JsonValue,\n  type MediaAssetInput,\n} from \"../shared/types.js\";\n\nconst MIME_PATTERN = /^\\S+\\/\\S+$/;\n\nconst BUILTIN_INDEX_NAMES = new Set([\"mimeType\", \"mediaKind\"]);\n\nfunction fileStem(fileName: string): string {\n  const dotIndex = fileName.lastIndexOf(\".\");\n  return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;\n}\n\n/**\n * Callable handle returned by {@link MediaStore.defineIndex}. Call it with a value\n * to produce an {@link IndexTag} for use in the `indexes` array of {@link MediaStore.add}:\n *\n * ```ts\n * const gallery = store.defineIndex(\"gallery\");\n * store.add(\"photo-1\", { ..., indexes: [gallery(\"nature\")] });\n * ```\n */\nexport interface MediaIndex {\n  (value: string | string[]): IndexTag;\n  readonly indexName: string;\n  readonly cardinality: \"single\" | \"multi\";\n  readonly required: boolean;\n}\n\n/** Options for {@link createMediaStore}. */\nexport interface MediaStoreOptions {\n  /** Optional opaque id for correlation, debugging, or multi-source merges. */\n  snapshotId?: string;\n  /** ISO 8601 timestamp describing when the store payload was built. */\n  retrievedAt?: string;\n  /**\n   * ISO 8601 timestamp after which source URLs must be treated as expired.\n   * Sync will fail assets whose download starts after this time.\n   */\n  expiresAt?: string;\n}\n\ninterface StoredAsset {\n  key: string;\n  displayKey: string;\n  version: string;\n  mimeType: string;\n  url: string;\n  fileName: string;\n  byteLength?: number;\n  metadata: Record<string, JsonValue>;\n  indexes: Record<string, string | string[]>;\n}\n\n/**\n * A flat key-value asset store with user-defined secondary indexes.\n *\n * Build a store imperatively inside your `resolveStore` callback:\n *\n * ```ts\n * const store = createMediaStore();\n * const gallery = store.defineIndex(\"gallery\");\n * store.add([\"forest\", \"video\"], {\n *   version: \"v1\",\n *   mimeType: \"video/mp4\",\n *   url: \"https://cdn.example.com/forest.mp4\",\n *   indexes: [gallery(\"nature\")],\n * });\n * ```\n */\nexport class MediaStore {\n  private readonly options: MediaStoreOptions;\n  private readonly indexes = new Map<string, IndexDefinition>();\n  private readonly assets = new Map<string, StoredAsset>();\n\n  constructor(options?: MediaStoreOptions) {\n    this.options = options ?? {};\n  }\n\n  /**\n   * Register a secondary index that assets can be tagged with and queried by.\n   * Must be called before any {@link add} call that references this index.\n   *\n   * @param name - Unique index name. Must not collide with built-in indexes (`mimeType`, `mediaKind`).\n   * @param options - Cardinality (`\"single\"` or `\"multi\"`) and whether the index is required on every asset.\n   * @returns A callable {@link MediaIndex} handle. Call it with a value to produce an {@link IndexTag}.\n   */\n  defineIndex(\n    name: string,\n    options?: { cardinality?: \"single\" | \"multi\"; required?: boolean },\n  ): MediaIndex {\n    if (!name) {\n      throw new StoreValidationError(\"Index name must be a non-empty string.\");\n    }\n    if (BUILTIN_INDEX_NAMES.has(name)) {\n      throw new StoreValidationError(`Index name \"${name}\" is reserved as a built-in index.`);\n    }\n    if (this.indexes.has(name)) {\n      throw new StoreValidationError(`Duplicate index name \"${name}\".`);\n    }\n\n    const cardinality = options?.cardinality ?? \"single\";\n    const required = options?.required ?? false;\n\n    if (cardinality !== \"single\" && cardinality !== \"multi\") {\n      throw new StoreValidationError(\n        `Index \"${name}\": cardinality must be \"single\" or \"multi\" (got \"${String(cardinality)}\").`,\n      );\n    }\n    if (typeof required !== \"boolean\") {\n      throw new StoreValidationError(\n        `Index \"${name}\": required must be a boolean (got ${typeof required}).`,\n      );\n    }\n\n    this.indexes.set(name, { name, cardinality, required, builtin: false });\n\n    const fn = (value: string | string[]) => new IndexTag(name, value);\n    Object.defineProperties(fn, {\n      indexName: { value: name, enumerable: true },\n      cardinality: { value: cardinality, enumerable: true },\n      required: { value: required, enumerable: true },\n    });\n    return fn as MediaIndex;\n  }\n\n  /**\n   * Add an asset to the store.\n   *\n   * @param key - Unique asset key. A string or array of string segments (e.g. `[\"videos\", \"hubble\", \"main\"]`).\n   * @param input - Asset data: version, mimeType, source, and optional indexes/metadata.\n   */\n  add(key: AssetKeyInput, input: MediaAssetInput): void {\n    if (!isValidKeyInput(key)) {\n      throw new StoreValidationError(\n        \"Asset key must be a non-empty string or non-empty string array.\",\n      );\n    }\n    const hashedKey = hashKey(key);\n    const display = displayKey(key);\n    if (this.assets.has(hashedKey)) {\n      throw new StoreValidationError(\n        `Duplicate asset key \"${display}\" (hash collision with existing key).`,\n      );\n    }\n\n    if (!input.version) {\n      throw new StoreValidationError(`Asset \"${display}\": version is required.`);\n    }\n    if (!input.mimeType || !MIME_PATTERN.test(input.mimeType)) {\n      throw new StoreValidationError(\n        `Asset \"${display}\": mimeType must be a valid type/subtype string (got \"${input.mimeType ?? \"\"}\").`,\n      );\n    }\n    if (!input.url) {\n      throw new StoreValidationError(`Asset \"${display}\": url is required.`);\n    }\n    try {\n      const parsed = new URL(input.url);\n      if (!/^https?:$/i.test(parsed.protocol)) {\n        throw new StoreValidationError(\n          `Asset \"${display}\": URL must use http or https (got \"${parsed.protocol}\").`,\n        );\n      }\n    } catch (err) {\n      if (err instanceof StoreValidationError) throw err;\n      throw new StoreValidationError(`Asset \"${display}\": URL is not valid: \"${input.url}\".`);\n    }\n\n    // byteLength: any non-negative finite number is accepted, including non-integer fractions\n    // (see MediaAssetInput.byteLength JSDoc).\n    if (\n      input.byteLength !== undefined &&\n      (typeof input.byteLength !== \"number\" ||\n        !Number.isFinite(input.byteLength) ||\n        input.byteLength < 0)\n    ) {\n      throw new StoreValidationError(\n        `Asset \"${display}\": byteLength must be a non-negative finite number (got ${String(input.byteLength)}).`,\n      );\n    }\n\n    const fileName = input.fileName ?? deriveAssetFileName(input.url);\n\n    const assetIndexes: Record<string, string | string[]> = Object.create(null);\n    if (input.indexes !== undefined && !Array.isArray(input.indexes)) {\n      throw new StoreValidationError(\n        `Asset \"${display}\": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`,\n      );\n    }\n    if (input.indexes) {\n      for (const tag of input.indexes) {\n        if (!(tag instanceof IndexTag)) {\n          throw new StoreValidationError(\n            `Asset \"${display}\": indexes must be an array of IndexTag entries produced by calling a defineIndex handle.`,\n          );\n        }\n        const indexName = tag.name;\n        const value = tag.value;\n        const def = this.indexes.get(indexName);\n        if (!def) {\n          throw new StoreValidationError(\n            `Asset \"${display}\": index \"${indexName}\" has not been defined. Call store.defineIndex(\"${indexName}\") first.`,\n          );\n        }\n        if (Object.hasOwn(assetIndexes, indexName)) {\n          throw new StoreValidationError(\n            `Asset \"${display}\": duplicate index \"${indexName}\" in indexes array.`,\n          );\n        }\n\n        if (def.cardinality === \"single\") {\n          if (Array.isArray(value)) {\n            throw new StoreValidationError(\n              `Asset \"${display}\": index \"${indexName}\" has single cardinality but received an array. ` +\n                `Use { cardinality: \"multi\" } when defining the index to allow arrays.`,\n            );\n          }\n          if (typeof value !== \"string\" || !value) {\n            throw new StoreValidationError(\n              `Asset \"${display}\": index \"${indexName}\" value must be a non-empty string.`,\n            );\n          }\n          assetIndexes[indexName] = value;\n        } else {\n          const values = Array.isArray(value) ? value : [value];\n          if (values.length === 0) {\n            throw new StoreValidationError(\n              `Asset \"${display}\": index \"${indexName}\" value array must not be empty.`,\n            );\n          }\n          for (const v of values) {\n            if (typeof v !== \"string\" || !v) {\n              throw new StoreValidationError(\n                `Asset \"${display}\": index \"${indexName}\" values must be non-empty strings.`,\n              );\n            }\n          }\n          assetIndexes[indexName] = [...new Set(values)];\n        }\n      }\n    }\n\n    const metadataSnapshot = input.metadata === undefined ? {} : structuredClone(input.metadata);\n\n    this.assets.set(hashedKey, {\n      key: hashedKey,\n      displayKey: display,\n      version: input.version,\n      mimeType: input.mimeType,\n      url: input.url,\n      fileName,\n      byteLength: input.byteLength,\n      metadata: metadataSnapshot,\n      indexes: assetIndexes,\n    });\n  }\n\n  /**\n   * Serialize the store for the sync engine. Validates required indexes and produces\n   * the flat manifest consumed internally. Not part of the public consumer API.\n   * @internal\n   */\n  _serialize(): FlatManifest {\n    for (const [, def] of this.indexes) {\n      if (!def.required) continue;\n      for (const [, asset] of this.assets) {\n        if (!(def.name in asset.indexes)) {\n          throw new StoreValidationError(\n            `Asset \"${asset.displayKey}\": required index \"${def.name}\" is missing.`,\n          );\n        }\n      }\n    }\n\n    const indexDefinitions: IndexDefinition[] = [\n      ...Array.from(this.indexes.values()),\n      { name: \"mimeType\", cardinality: \"single\", required: false, builtin: true },\n      { name: \"mediaKind\", cardinality: \"single\", required: false, builtin: true },\n    ];\n\n    const assets: FlatManifestAsset[] = [];\n    for (const [, stored] of this.assets) {\n      const mediaKind = mediaKindFromMime(stored.mimeType);\n      const stem = fileStem(stored.fileName);\n\n      const allIndexes: Record<string, string | string[]> = {\n        ...stored.indexes,\n        mimeType: stored.mimeType,\n        mediaKind,\n      };\n\n      assets.push({\n        key: stored.key,\n        displayKey: stored.displayKey,\n        version: stored.version,\n        mimeType: stored.mimeType,\n        mediaKind,\n        url: stored.url,\n        fileName: stored.fileName,\n        fileStem: stem,\n        byteLength: stored.byteLength,\n        metadata: stored.metadata,\n        indexes: allIndexes,\n      });\n    }\n\n    return {\n      snapshotId: this.options.snapshotId,\n      retrievedAt: this.options.retrievedAt,\n      expiresAt: this.options.expiresAt,\n      indexDefinitions,\n      assets,\n    };\n  }\n}\n\n/** Creates a new {@link MediaStore} for populating in a `resolveStore` callback. */\nexport function createMediaStore(options?: MediaStoreOptions): MediaStore {\n  return new MediaStore(options);\n}\n"],"mappings":"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"}