@gentomiyano/optimized-web-audio-player 0.1.0

package/dist/media-delivery/index.d.ts

@@ -0,0 +1,185 @@
+import { s as PlayerMediaSource, r as PlayerMediaItem } from '../player-DE9Vqztu.js';
+
+declare const MEDIA_DELIVERY_CONTRACT_VERSION: 1;
+type SupportedUploadFormat = "wav" | "mp3";
+type FutureUploadFormat = "flac" | "aiff" | "aac" | "m4a";
+/**
+ * This classification belongs to the consumer/backend boundary. It MUST NOT be
+ * used by Player Core to make authorization decisions.
+ */
+type MediaAccessClass = "public" | "free-member" | "support-member" | "purchased" | "admin" | "unpublished";
+type MediaSourceRole = "public" | "protected" | "preview";
+type UploadHeaderFormat = SupportedUploadFormat | "unknown";
+/**
+ * Evidence produced by the upload service. `detectedHeaderFormat` must come
+ * from a trusted parser/decoder, not from the file name or declared MIME type.
+ */
+interface MediaUploadEvidence {
+    readonly extension: string;
+    readonly declaredMimeType: string;
+    readonly detectedHeaderFormat: UploadHeaderFormat;
+}
+type UploadValidationErrorCode = "unsupported-extension" | "unsupported-mime-type" | "unrecognized-header" | "extension-header-mismatch" | "mime-header-mismatch";
+interface UploadValidationError {
+    readonly code: UploadValidationErrorCode;
+    readonly field: "extension" | "declaredMimeType" | "detectedHeaderFormat";
+}
+interface NormalizedUploadIdentity {
+    readonly format: SupportedUploadFormat;
+    readonly extension: ".wav" | ".mp3";
+    /** Canonical delivery-independent MIME identity. */
+    readonly mimeType: "audio/wave" | "audio/mpeg";
+}
+type MediaUploadValidationResult = {
+    readonly ok: true;
+    readonly value: NormalizedUploadIdentity;
+    readonly errors: readonly [];
+} | {
+    readonly ok: false;
+    readonly errors: readonly UploadValidationError[];
+};
+type AudioSampleEncoding = "pcm-integer" | "ieee-float" | "lossy" | "other";
+interface MediaLoudnessMetadata {
+    /** Integrated loudness in LUFS when the processor supports it. */
+    readonly integratedLufs: number | null;
+    /** Maximum decoded sample peak in dBFS. */
+    readonly samplePeakDbfs: number | null;
+    /** Optional oversampled true peak in dBTP. */
+    readonly truePeakDbtp: number | null;
+}
+/**
+ * Normalized mono envelope. Each value is the maximum absolute amplitude in
+ * one equal-duration bucket after taking the maximum across source channels.
+ */
+interface WaveformPeaksV1 {
+    readonly version: 1;
+    readonly aggregation: "max-absolute";
+    readonly channelMode: "merged";
+    readonly peaks: readonly number[];
+}
+interface ProcessedMediaMetadata {
+    readonly contractVersion: typeof MEDIA_DELIVERY_CONTRACT_VERSION;
+    readonly mediaAssetId: string;
+    readonly processingRevision: string;
+    readonly durationSec: number;
+    /**
+     * Intentionally numeric rather than an enum. Upload policy does not fix a
+     * single sample rate.
+     */
+    readonly sampleRateHz: number;
+    /**
+     * Null when bit depth is not meaningful for the encoded format (for example
+     * MP3).
+     */
+    readonly bitDepth: number | null;
+    readonly sampleEncoding: AudioSampleEncoding;
+    /** Processor-reported codec identifier; not interpreted by Player Core. */
+    readonly codec: string;
+    readonly channelCount: number;
+    readonly bitrateBps: number | null;
+    readonly loudness: MediaLoudnessMetadata;
+}
+/**
+ * Stable, URL-free identity for one generated delivery representation.
+ * Container and codec are strings so the delivery format can evolve without a
+ * Player contract revision.
+ */
+interface MediaDeliveryDescriptor {
+    readonly contractVersion: typeof MEDIA_DELIVERY_CONTRACT_VERSION;
+    readonly deliveryId: string;
+    readonly mediaAssetId: string;
+    readonly deliveryRevision: string;
+    readonly container: string;
+    readonly codec: string;
+    readonly mimeType: string;
+    readonly byteLength: number;
+    readonly durationSec: number;
+    readonly rangeMode: "bytes";
+    readonly metadataId: string;
+    readonly waveformId: string;
+}
+/**
+ * Opaque backend storage references. These are never Player input and must not
+ * be interpreted as public URLs.
+ */
+interface MediaStorageReferences {
+    readonly sourceMasterRef: string;
+    readonly deliveryAudioRef: string;
+    readonly waveformRef: string;
+    readonly artworkRef: string | null;
+    readonly metadataRef: string;
+}
+/**
+ * A Host-owned candidate. Host may retain multiple candidates, but only
+ * candidates currently playable by the user may be returned to Player Runtime.
+ */
+interface MediaDeliverySourceReference {
+    readonly sourceId: string;
+    readonly deliveryId: string;
+    readonly role: MediaSourceRole;
+    readonly priority: number;
+}
+type PlayerMediaDescriptor = Omit<PlayerMediaItem, "source"> & {
+    /**
+     * Ordered Host-approved candidates. This object contains no playback URL,
+     * token, cookie, Authorization value, or access-policy decision.
+     */
+    readonly sourceSet: readonly MediaDeliverySourceReference[];
+};
+type PlaybackSourceResolveReason = "initial" | "expires-soon" | "expired" | "recoverable-network-error" | "manual-retry";
+interface PlaybackSourceResolveRequest {
+    readonly mediaItemId: string;
+    readonly sourceSet: readonly MediaDeliverySourceReference[];
+    readonly reason: PlaybackSourceResolveReason;
+    /** Opaque non-secret correlation id from the previous successful response. */
+    readonly currentLeaseId?: string;
+    readonly resumeAtSec?: number;
+}
+/**
+ * The only contract that carries a playback URL. It is an ephemeral in-memory
+ * lease and must not be serialized, persisted, logged, or placed in analytics.
+ */
+interface ResolvedPlaybackSource extends PlayerMediaSource {
+    readonly sourceId: string;
+    readonly deliveryId: string;
+    readonly leaseId: string;
+    /**
+     * Optional absolute epoch time. When present, Runtime refreshes before use
+     * after this time; the refresh margin remains Host configuration.
+     */
+    readonly expiresAtEpochMs?: number;
+    readonly rangeMode: "bytes";
+}
+type PlaybackSourceResolveErrorCode = "not-playable" | "source-unavailable" | "temporarily-unavailable";
+type PlaybackSourceResolveResult = {
+    readonly ok: true;
+    readonly source: ResolvedPlaybackSource;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: PlaybackSourceResolveErrorCode;
+        readonly recoverable: boolean;
+        readonly messageKey: string;
+    };
+};
+/**
+ * Consumer-owned boundary. Authentication, membership, purchase, publication,
+ * rights, and URL signing stay behind this interface.
+ */
+interface PlayerDeliveryHostAdapter<TConsumerMedia> {
+    /**
+     * Returns null when the consumer declines to expose playable media. Returned
+     * source references have already passed consumer access policy.
+     */
+    toPlayerMediaDescriptor(source: TConsumerMedia): PlayerMediaDescriptor | null;
+    /**
+     * Resolves or refreshes one short-lived playback lease. The request never
+     * echoes the previous URL or any credential.
+     */
+    resolvePlaybackSource(request: PlaybackSourceResolveRequest): Promise<PlaybackSourceResolveResult>;
+}
+
+declare function validateMediaUploadEvidence(evidence: MediaUploadEvidence): MediaUploadValidationResult;
+declare function validateWaveformPeaks(waveform: WaveformPeaksV1): readonly string[];
+
+export { type AudioSampleEncoding, type FutureUploadFormat, MEDIA_DELIVERY_CONTRACT_VERSION, type MediaAccessClass, type MediaDeliveryDescriptor, type MediaDeliverySourceReference, type MediaLoudnessMetadata, type MediaSourceRole, type MediaStorageReferences, type MediaUploadEvidence, type MediaUploadValidationResult, type NormalizedUploadIdentity, type PlaybackSourceResolveErrorCode, type PlaybackSourceResolveReason, type PlaybackSourceResolveRequest, type PlaybackSourceResolveResult, type PlayerDeliveryHostAdapter, type PlayerMediaDescriptor, type ProcessedMediaMetadata, type ResolvedPlaybackSource, type SupportedUploadFormat, type UploadHeaderFormat, type UploadValidationError, type UploadValidationErrorCode, type WaveformPeaksV1, validateMediaUploadEvidence, validateWaveformPeaks };

package/dist/media-delivery/index.js

@@ -0,0 +1,91 @@
+// src/media-delivery/validation.ts
+var EXTENSION_FORMATS = /* @__PURE__ */ new Map([
+  [".wav", "wav"],
+  [".mp3", "mp3"]
+]);
+var MIME_FORMATS = /* @__PURE__ */ new Map([
+  ["audio/wave", "wav"],
+  ["audio/wav", "wav"],
+  ["audio/x-wav", "wav"],
+  ["audio/vnd.wave", "wav"],
+  ["audio/mpeg", "mp3"],
+  ["audio/mp3", "mp3"]
+]);
+function normalizeExtension(extension) {
+  const normalized = extension.trim().toLowerCase();
+  return normalized.startsWith(".") ? normalized : `.${normalized}`;
+}
+function normalizeMimeType(mimeType) {
+  return mimeType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function validateMediaUploadEvidence(evidence) {
+  const extension = normalizeExtension(evidence.extension);
+  const mimeType = normalizeMimeType(evidence.declaredMimeType);
+  const extensionFormat = EXTENSION_FORMATS.get(extension);
+  const mimeFormat = MIME_FORMATS.get(mimeType);
+  const headerFormat = evidence.detectedHeaderFormat === "unknown" ? void 0 : evidence.detectedHeaderFormat;
+  const errors = [];
+  if (extensionFormat === void 0) {
+    errors.push({
+      code: "unsupported-extension",
+      field: "extension"
+    });
+  }
+  if (mimeFormat === void 0) {
+    errors.push({
+      code: "unsupported-mime-type",
+      field: "declaredMimeType"
+    });
+  }
+  if (headerFormat === void 0) {
+    errors.push({
+      code: "unrecognized-header",
+      field: "detectedHeaderFormat"
+    });
+  }
+  if (extensionFormat !== void 0 && headerFormat !== void 0 && extensionFormat !== headerFormat) {
+    errors.push({
+      code: "extension-header-mismatch",
+      field: "extension"
+    });
+  }
+  if (mimeFormat !== void 0 && headerFormat !== void 0 && mimeFormat !== headerFormat) {
+    errors.push({
+      code: "mime-header-mismatch",
+      field: "declaredMimeType"
+    });
+  }
+  if (errors.length > 0 || extensionFormat === void 0 || mimeFormat === void 0 || headerFormat === void 0) {
+    return Object.freeze({
+      ok: false,
+      errors: Object.freeze(errors)
+    });
+  }
+  return Object.freeze({
+    ok: true,
+    value: Object.freeze({
+      format: headerFormat,
+      extension: headerFormat === "wav" ? ".wav" : ".mp3",
+      mimeType: headerFormat === "wav" ? "audio/wave" : "audio/mpeg"
+    }),
+    errors: []
+  });
+}
+function validateWaveformPeaks(waveform) {
+  const errors = [];
+  if (waveform.peaks.length === 0) {
+    errors.push("waveform.peaks must contain at least one value.");
+  }
+  waveform.peaks.forEach((peak, index) => {
+    if (!Number.isFinite(peak) || peak < 0 || peak > 1) {
+      errors.push(
+        `waveform.peaks[${String(index)}] must be a finite number between 0 and 1.`
+      );
+    }
+  });
+  return Object.freeze(errors);
+}
+
+export { validateMediaUploadEvidence, validateWaveformPeaks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/media-delivery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/media-delivery/validation.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n  MediaUploadEvidence,\n  MediaUploadValidationResult,\n  SupportedUploadFormat,\n  UploadValidationError,\n  WaveformPeaksV1,\n} from \"./contracts\";\n\nconst EXTENSION_FORMATS = new Map<string, SupportedUploadFormat>([\n  [\".wav\", \"wav\"],\n  [\".mp3\", \"mp3\"],\n]);\n\nconst MIME_FORMATS = new Map<string, SupportedUploadFormat>([\n  [\"audio/wave\", \"wav\"],\n  [\"audio/wav\", \"wav\"],\n  [\"audio/x-wav\", \"wav\"],\n  [\"audio/vnd.wave\", \"wav\"],\n  [\"audio/mpeg\", \"mp3\"],\n  [\"audio/mp3\", \"mp3\"],\n]);\n\nfunction normalizeExtension(extension: string): string {\n  const normalized = extension.trim().toLowerCase();\n  return normalized.startsWith(\".\") ? normalized : `.${normalized}`;\n}\n\nfunction normalizeMimeType(mimeType: string): string {\n  return mimeType.split(\";\", 1)[0]?.trim().toLowerCase() ?? \"\";\n}\n\nexport function validateMediaUploadEvidence(\n  evidence: MediaUploadEvidence,\n): MediaUploadValidationResult {\n  const extension = normalizeExtension(evidence.extension);\n  const mimeType = normalizeMimeType(evidence.declaredMimeType);\n  const extensionFormat = EXTENSION_FORMATS.get(extension);\n  const mimeFormat = MIME_FORMATS.get(mimeType);\n  const headerFormat =\n    evidence.detectedHeaderFormat === \"unknown\"\n      ? undefined\n      : evidence.detectedHeaderFormat;\n  const errors: UploadValidationError[] = [];\n\n  if (extensionFormat === undefined) {\n    errors.push({\n      code: \"unsupported-extension\",\n      field: \"extension\",\n    });\n  }\n  if (mimeFormat === undefined) {\n    errors.push({\n      code: \"unsupported-mime-type\",\n      field: \"declaredMimeType\",\n    });\n  }\n  if (headerFormat === undefined) {\n    errors.push({\n      code: \"unrecognized-header\",\n      field: \"detectedHeaderFormat\",\n    });\n  }\n  if (\n    extensionFormat !== undefined &&\n    headerFormat !== undefined &&\n    extensionFormat !== headerFormat\n  ) {\n    errors.push({\n      code: \"extension-header-mismatch\",\n      field: \"extension\",\n    });\n  }\n  if (\n    mimeFormat !== undefined &&\n    headerFormat !== undefined &&\n    mimeFormat !== headerFormat\n  ) {\n    errors.push({\n      code: \"mime-header-mismatch\",\n      field: \"declaredMimeType\",\n    });\n  }\n\n  if (\n    errors.length > 0 ||\n    extensionFormat === undefined ||\n    mimeFormat === undefined ||\n    headerFormat === undefined\n  ) {\n    return Object.freeze({\n      ok: false,\n      errors: Object.freeze(errors),\n    });\n  }\n\n  return Object.freeze({\n    ok: true,\n    value: Object.freeze({\n      format: headerFormat,\n      extension: headerFormat === \"wav\" ? \".wav\" : \".mp3\",\n      mimeType: headerFormat === \"wav\" ? \"audio/wave\" : \"audio/mpeg\",\n    }),\n    errors: [] as const,\n  });\n}\n\nexport function validateWaveformPeaks(\n  waveform: WaveformPeaksV1,\n): readonly string[] {\n  const errors: string[] = [];\n\n  if (waveform.peaks.length === 0) {\n    errors.push(\"waveform.peaks must contain at least one value.\");\n  }\n\n  waveform.peaks.forEach((peak, index) => {\n    if (!Number.isFinite(peak) || peak < 0 || peak > 1) {\n      errors.push(\n        `waveform.peaks[${String(index)}] must be a finite number between 0 and 1.`,\n      );\n    }\n  });\n\n  return Object.freeze(errors);\n}\n"]}

package/dist/media-element-C9dis4aG.d.ts

@@ -0,0 +1,40 @@
+import { j as PlayerError, s as PlayerMediaSource } from './player-DE9Vqztu.js';
+
+type PlayerMediaEventType = "loadstart" | "loadedmetadata" | "canplay" | "play" | "playing" | "pause" | "waiting" | "stalled" | "seeking" | "seeked" | "timeupdate" | "ended" | "error" | "durationchange" | "volumechange";
+interface PlayerMediaEvent {
+    readonly type: PlayerMediaEventType;
+}
+type PlayerMediaEventListener = (event: PlayerMediaEvent) => void;
+interface MediaElementStateSnapshot {
+    readonly currentTimeSec: number;
+    readonly durationSec: number | null;
+    readonly volume: number;
+    readonly muted: boolean;
+    readonly paused: boolean;
+    readonly ended: boolean;
+    /** Confirms that the element still has an assigned/current source. */
+    readonly hasCurrentSource: boolean;
+    /** Compares the current source with the last source assigned by this port. */
+    readonly currentSourceMatchesAssigned: boolean;
+}
+interface MediaElementPort {
+    getCurrentTimeSec(): number;
+    getDurationSec(): number | null;
+    getVolume(): number;
+    isMuted(): boolean;
+    isPaused(): boolean;
+    getStateSnapshot(): MediaElementStateSnapshot;
+    getError(): PlayerError | null;
+    setSource(source: PlayerMediaSource): void;
+    clearSource(): void;
+    load(): void;
+    play(): Promise<void>;
+    pause(): void;
+    seekTo(seconds: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    addEventListener(type: PlayerMediaEventType, listener: PlayerMediaEventListener): void;
+    removeEventListener(type: PlayerMediaEventType, listener: PlayerMediaEventListener): void;
+}
+
+export type { MediaElementPort as M, PlayerMediaEvent as P, MediaElementStateSnapshot as a, PlayerMediaEventListener as b, PlayerMediaEventType as c };

package/dist/player-DE9Vqztu.d.ts

@@ -0,0 +1,212 @@
+type PlaybackStatus = "idle" | "loading" | "playing" | "paused" | "seeking" | "ended" | "error";
+type PlaybackTransitionCause = "user-play" | "user-pause" | "user-stop" | "natural-end" | "os-interruption" | "background-suspension" | "autoplay-blocked" | "source-error";
+type PlayerMediaSyncReason = "visibilitychange" | "pageshow" | "focus" | "audio-context-statechange" | "manual";
+type RepeatMode = "off" | "all" | "one";
+type MediaKind = "track" | "podcastEpisode";
+type PlayerAppearance = "dark" | "light";
+type FadeCurve = "linear" | "ease-in" | "ease-out" | "equal-power";
+type SeekCommitMode = "live" | "on-release";
+type PersistMode = "none" | "session" | "local";
+type PodcastPreviousMode = "previous-episode" | "restart-episode";
+interface PlayerExperienceConfig {
+    readonly playFadeInMs: number;
+    readonly pauseFadeOutMs: number;
+    readonly trackChangeFadeOutMs: number;
+    readonly trackChangeFadeInMs: number;
+    readonly seekFadeMs: number;
+    readonly fadeCurve: FadeCurve;
+    readonly previousRestartThresholdSec: number;
+    readonly seekCommitMode: SeekCommitMode;
+    /** Whether the played waveform region is visually distinguished. */
+    readonly waveformPlayedStateEnabled: boolean;
+    /** Overall waveform opacity in the inclusive range 0..1. */
+    readonly waveformOpacity: number;
+    readonly initialShuffleEnabled: boolean;
+    readonly initialRepeatMode: RepeatMode;
+    readonly initialVolume: number;
+    readonly persistMode: PersistMode;
+    readonly podcastBackSec: number;
+    readonly podcastForwardSec: number;
+    readonly podcastPreviousMode: PodcastPreviousMode;
+}
+interface PlayerExperienceConfigEnvelope {
+    readonly schemaVersion: 2;
+    readonly config: PlayerExperienceConfig;
+}
+interface PlayerMediaSource {
+    readonly url: string;
+    readonly mimeType?: string;
+    readonly crossOrigin: "anonymous";
+}
+interface PlayerWaveform {
+    readonly version: 1;
+    readonly peaks: readonly number[];
+}
+interface PlayerMediaItem {
+    readonly id: string;
+    readonly kind: MediaKind;
+    readonly title: string;
+    readonly creatorName?: string;
+    readonly collectionTitle?: string;
+    readonly artwork?: {
+        readonly url: string;
+        readonly alt: string;
+    };
+    readonly source: PlayerMediaSource;
+    readonly durationHintSec?: number;
+    readonly waveform?: PlayerWaveform;
+}
+interface QueueItem {
+    readonly queueItemId: string;
+    readonly item: PlayerMediaItem;
+}
+type PlayerErrorCode = "autoplay-blocked" | "network" | "cors" | "decode" | "unsupported" | "audio-context" | "unknown";
+interface PlayerError {
+    readonly code: PlayerErrorCode;
+    readonly recoverable: boolean;
+    readonly messageKey: string;
+}
+interface PlayerState {
+    readonly currentItem: PlayerMediaItem | null;
+    readonly currentItemId: string | null;
+    readonly currentQueueItemId: string | null;
+    readonly mediaKind: MediaKind | null;
+    readonly status: PlaybackStatus;
+    readonly currentTimeSec: number;
+    readonly durationSec: number | null;
+    readonly volume: number;
+    readonly muted: boolean;
+    readonly shuffleEnabled: boolean;
+    readonly repeatMode: RepeatMode;
+    readonly queue: readonly QueueItem[];
+    readonly currentQueueIndex: number | null;
+    readonly canSeek: boolean;
+    readonly canGoPrevious: boolean;
+    readonly canGoNext: boolean;
+    readonly needsUserGesture: boolean;
+    /**
+     * Last meaningful playback transition. External media pauses are never
+     * persisted as a user pause.
+     */
+    readonly lastTransitionCause: PlaybackTransitionCause | null;
+    readonly error: PlayerError | null;
+    readonly experienceConfig: Readonly<PlayerExperienceConfig>;
+}
+interface SetQueueOptions {
+    readonly startQueueItemId?: string;
+    readonly autoplay?: boolean;
+}
+interface PauseOptions {
+    /** When omitted, Core applies the configured pause fade. */
+    readonly fade?: boolean;
+}
+interface StopOptions {
+    /** When omitted, Core applies the configured stop/pause fade. */
+    readonly fade?: boolean;
+    /** Defaults to true. Stop keeps the item and queue even when reset. */
+    readonly resetPosition?: boolean;
+}
+interface PlayerCommandResult {
+    readonly ok: boolean;
+    readonly error?: PlayerError;
+}
+interface PlayerCommands {
+    load(item: PlayerMediaItem): Promise<PlayerCommandResult>;
+    setQueue(queue: readonly QueueItem[], options?: SetQueueOptions): Promise<PlayerCommandResult>;
+    play(): Promise<PlayerCommandResult>;
+    pause(options?: PauseOptions): Promise<void>;
+    stop(options?: StopOptions): Promise<void>;
+    togglePlayback(): Promise<PlayerCommandResult>;
+    seekTo(seconds: number): void;
+    seekBy(deltaSeconds: number): void;
+    setVolume(volume: number): void;
+    toggleMute(): void;
+    setShuffle(enabled: boolean): void;
+    setRepeatMode(mode: RepeatMode): void;
+    next(): Promise<PlayerCommandResult>;
+    previous(): Promise<PlayerCommandResult>;
+    retry(): Promise<PlayerCommandResult>;
+    /** Stops at zero, then removes the current item, queue, and error. */
+    clear(): Promise<void>;
+}
+interface PlayerExperienceConfigStore {
+    getConfig(): Readonly<PlayerExperienceConfig>;
+    updateConfig(patch: Partial<PlayerExperienceConfig>): void;
+    resetConfig(): void;
+    subscribe(listener: () => void): () => void;
+}
+interface PlayerStore {
+    getState(): PlayerState;
+    subscribe(listener: () => void): () => void;
+    readonly commands: PlayerCommands;
+    readonly experience: PlayerExperienceConfigStore;
+    /**
+     * Re-reads the media element after page/background lifecycle transitions.
+     * This is Runtime infrastructure, not a UI command.
+     */
+    synchronizeFromMedia(reason: PlayerMediaSyncReason): Promise<void>;
+    /** Runtime-unmount cleanup; not a normal UI command. */
+    destroy(): Promise<void>;
+}
+interface PlayerMediaAdapter<TSource> {
+    /**
+     * Maps already-authorized media with a directly playable Delivery Audio URL.
+     * This covers public immutable delivery media as well as local/fixture media.
+     * Protected expiring delivery uses PlayerDeliveryHostAdapter from
+     * /media-delivery instead.
+     */
+    toPlayerMediaItem(source: TSource): PlayerMediaItem | null;
+}
+interface PlayerHostConfig {
+    readonly appearance: PlayerAppearance;
+    readonly experienceConfig?: Partial<PlayerExperienceConfig>;
+    readonly miniPlayer: {
+        readonly enabled: boolean;
+        readonly onInsetChange?: (bottomInsetPx: number) => void;
+    };
+    readonly persistenceNamespace: string;
+}
+interface PlayerViewProps {
+    readonly state: Readonly<PlayerState>;
+    readonly commands: PlayerCommands;
+    readonly appearance: PlayerAppearance;
+}
+interface PlayerExperiencePreset {
+    readonly id: string;
+    readonly name: string;
+    readonly config: PlayerExperienceConfig;
+    readonly updatedAt: string;
+}
+interface PlayerConfigImportResult {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+interface PlayerDebugSnapshot {
+    readonly config: Readonly<PlayerExperienceConfig>;
+    readonly presets: readonly PlayerExperiencePreset[];
+    readonly activePresetId: string | null;
+    readonly lastConfigImportResult: PlayerConfigImportResult | null;
+}
+interface PlayerDebugController {
+    getConfig(): Readonly<PlayerExperienceConfig>;
+    /** Immutable external-store snapshot for useSyncExternalStore-style consumers. */
+    getSnapshot(): Readonly<PlayerDebugSnapshot>;
+    subscribe(listener: () => void): () => void;
+    /** A manual patch clears activePresetId because the config has diverged. */
+    applyConfig(patch: Partial<PlayerExperienceConfig>): void;
+    /** Restores preview defaults and clears activePresetId. */
+    resetConfig(): void;
+    copyConfigJson(): Promise<void>;
+    /** Atomic import; a successful import clears activePresetId. */
+    loadConfigJson(json: string): PlayerConfigImportResult;
+    listPresets(): readonly PlayerExperiencePreset[];
+    /** Saves the current config and makes the new preset active. */
+    savePreset(name: string): PlayerExperiencePreset;
+    /** Applies the preset atomically and makes its id active. */
+    applyPreset(id: string): PlayerConfigImportResult;
+    /** Deleting the active preset clears its id but keeps the current config. */
+    deletePreset(id: string): void;
+    exportProductionConfigJson(): string;
+}
+
+export type { StopOptions as A, FadeCurve as F, MediaKind as M, PauseOptions as P, QueueItem as Q, RepeatMode as R, SeekCommitMode as S, PersistMode as a, PlaybackStatus as b, PlaybackTransitionCause as c, PlayerAppearance as d, PlayerCommandResult as e, PlayerCommands as f, PlayerConfigImportResult as g, PlayerDebugController as h, PlayerDebugSnapshot as i, PlayerError as j, PlayerErrorCode as k, PlayerExperienceConfig as l, PlayerExperienceConfigEnvelope as m, PlayerExperienceConfigStore as n, PlayerExperiencePreset as o, PlayerHostConfig as p, PlayerMediaAdapter as q, PlayerMediaItem as r, PlayerMediaSource as s, PlayerMediaSyncReason as t, PlayerState as u, PlayerStore as v, PlayerViewProps as w, PlayerWaveform as x, PodcastPreviousMode as y, SetQueueOptions as z };

package/dist/ports/index.d.ts

@@ -0,0 +1,32 @@
+import { F as FadeCurve } from '../player-DE9Vqztu.js';
+export { M as MediaElementPort, a as MediaElementStateSnapshot, P as PlayerMediaEvent, b as PlayerMediaEventListener, c as PlayerMediaEventType } from '../media-element-C9dis4aG.js';
+
+interface GainTransition {
+    readonly durationMs: number;
+    readonly curve: FadeCurve;
+}
+interface GainPort {
+    getValue(): number;
+    setValue(value: number): void;
+    cancelTransition(): void;
+    transitionTo(value: number, transition: GainTransition): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+interface PlayerPersistencePort {
+    read(namespace: string, key: string): string | null;
+    write(namespace: string, key: string, value: string): void;
+    remove(namespace: string, key: string): void;
+}
+interface PodcastProgress {
+    readonly itemId: string;
+    readonly positionSec: number;
+    readonly updatedAt: string;
+}
+interface PodcastProgressPort {
+    load(itemId: string): Promise<PodcastProgress | null>;
+    save(progress: PodcastProgress): Promise<void>;
+    remove(itemId: string): Promise<void>;
+}
+
+export type { GainPort, GainTransition, PlayerPersistencePort, PodcastProgress, PodcastProgressPort };

package/dist/ports/index.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/react/index.d.ts

@@ -0,0 +1,86 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { f as PlayerCommands, t as PlayerMediaSyncReason, Q as QueueItem, l as PlayerExperienceConfig, v as PlayerStore, n as PlayerExperienceConfigStore, u as PlayerState } from '../player-DE9Vqztu.js';
+import { c as PlayerMediaEventType, a as MediaElementStateSnapshot } from '../media-element-C9dis4aG.js';
+
+type PlayerAudioMode = "auto" | "web-audio" | "html-media";
+type ResolvedPlayerAudioMode = "web-audio" | "html-media";
+
+type PlayerRuntimeCommandName = keyof PlayerCommands;
+
+type PlayerRuntimeDiagnosticPayload = {
+    readonly type: "command";
+    readonly command: PlayerRuntimeCommandName;
+} | {
+    readonly type: "media-event";
+    readonly event: PlayerMediaEventType;
+    readonly media: MediaElementStateSnapshot;
+} | {
+    readonly type: "lifecycle-sync";
+    readonly reason: PlayerMediaSyncReason;
+    readonly visibility: DocumentVisibilityState;
+    readonly media: MediaElementStateSnapshot;
+} | {
+    readonly type: "audio-context-statechange";
+    readonly state: AudioContextState | "uninitialized";
+} | {
+    readonly type: "audio-context-resume";
+    readonly outcome: "resumed" | "failed";
+    readonly state: AudioContextState | "uninitialized";
+    readonly errorCode: "audio-context" | null;
+} | {
+    readonly type: "media-session-action";
+    readonly action: MediaSessionAction;
+    readonly failed: boolean;
+};
+type PlayerRuntimeDiagnosticEvent = PlayerRuntimeDiagnosticPayload & {
+    readonly occurredAt: string;
+};
+type PlayerRuntimeDiagnosticListener = (event: PlayerRuntimeDiagnosticEvent) => void;
+
+interface PlayerProviderProps {
+    readonly children: ReactNode;
+    /** Read once when the Runtime is created. Later queue changes use commands. */
+    readonly initialQueue?: readonly QueueItem[];
+    readonly initialQueueItemId?: string;
+    readonly experienceConfig?: Partial<PlayerExperienceConfig>;
+    readonly loadingFallback?: ReactNode;
+    /**
+     * auto uses native HTML audio on iOS/iPadOS and Web Audio elsewhere.
+     * Explicit modes exist for real-device comparison and host policy.
+     */
+    readonly audioMode?: PlayerAudioMode;
+    /** Optional host observer. The runtime does not retain diagnostic history. */
+    readonly onDiagnosticEvent?: PlayerRuntimeDiagnosticListener;
+}
+interface PlayerRuntimeContextValue {
+    readonly store: PlayerStore;
+    readonly commands: PlayerCommands;
+    readonly experience: PlayerExperienceConfigStore;
+    readonly audioContextState: AudioContextState | "uninitialized";
+    readonly audioMode: ResolvedPlayerAudioMode;
+    readonly mediaSessionSupported: boolean;
+    readonly mediaSessionActionsEnabled: boolean;
+}
+declare function PlayerProvider({ audioMode, children, experienceConfig, initialQueue, initialQueueItemId, loadingFallback, onDiagnosticEvent, }: PlayerProviderProps): react.JSX.Element;
+
+interface MiniPlayerHostProps {
+    readonly children: ReactNode;
+    readonly visible: boolean;
+    readonly onInsetChange?: (bottomInsetPx: number) => void;
+    readonly className?: string;
+}
+declare function MiniPlayerHost({ children, className, onInsetChange, visible, }: MiniPlayerHostProps): react.JSX.Element | null;
+
+interface UsePlayerResult {
+    readonly state: Readonly<PlayerState>;
+    readonly commands: PlayerCommands;
+    readonly experience: PlayerExperienceConfigStore;
+    readonly audioContextState: AudioContextState | "uninitialized";
+    readonly audioMode: ResolvedPlayerAudioMode;
+    readonly mediaSessionSupported: boolean;
+    readonly mediaSessionActionsEnabled: boolean;
+}
+declare function usePlayer(): UsePlayerResult;
+
+export { MiniPlayerHost, type MiniPlayerHostProps, PlayerProvider, type PlayerProviderProps, type PlayerRuntimeContextValue, type PlayerRuntimeDiagnosticEvent, type PlayerRuntimeDiagnosticListener, type PlayerRuntimeDiagnosticPayload, type UsePlayerResult, usePlayer };