@gentomiyano/optimized-web-audio-player 0.2.0 → 0.2.1

package/README.md

@@ -39,6 +39,18 @@ The public npm registry, scoped package name, and release workflow are fixed.
 Initial npm publication still requires the scope owner's authentication.
 Release and consumer pinning rules are documented in `docs/RELEASING.md`.
 
+## WP-04.3 React package boundary
+
+Version 0.2.1 keeps React Context consumers in the `/react` entrypoint and
+exports props-only views from `/ui`. Import `PlayerProvider`, `usePlayer`,
+`useBoundPlayer`, and `BoundCompactPlayer` from `/react`; import
+`BoundCompactPlayerView`, `MiniPlayer`, and the other pure views from `/ui`.
+
+The release check packs the built package, installs that tarball into an empty
+consumer, renders a bound inline Player with a shared Mini Player, and verifies
+one Store, one active item, and one audio element. See
+`docs/WP-04.3-REACT-BOUNDARY.md`.
+
 ## WP-04.2 playback contexts and bound inline players
 
 Version 0.2.0 adds consumer-neutral `manual-history` and `ordered-queue`

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { j as PlayerCommands, x as PlayerMediaSyncReason, Q as QueueItem, p as PlayerExperienceConfig, z as PlayerStore, r as PlayerExperienceConfigStore, y as PlayerState, c as PlaybackContextInput, a as BoundPlayerViewState, B as BoundPlayerCommands } from '../player-BxNFzRq4.js';
+import { j as PlayerCommands, x as PlayerMediaSyncReason, Q as QueueItem, p as PlayerExperienceConfig, z as PlayerStore, r as PlayerExperienceConfigStore, y as PlayerState, c as PlaybackContextInput, a as BoundPlayerViewState, B as BoundPlayerCommands, h as PlayerAppearance } from '../player-BxNFzRq4.js';
 import { c as PlayerMediaEventType, a as MediaElementStateSnapshot } from '../media-element-DyMO-PhK.js';
 
 type PlayerAudioMode = "auto" | "web-audio" | "html-media";
@@ -94,4 +94,12 @@ interface UseBoundPlayerResult {
 declare function deriveBoundPlayerViewState(playerState: Readonly<PlayerState>, contextId: string, queueItem: QueueItem): Readonly<BoundPlayerViewState>;
 declare function useBoundPlayer({ context, queueItem, }: UseBoundPlayerOptions): UseBoundPlayerResult;
 
-export { MiniPlayerHost, type MiniPlayerHostProps, PlayerProvider, type PlayerProviderProps, type PlayerRuntimeContextValue, type PlayerRuntimeDiagnosticEvent, type PlayerRuntimeDiagnosticListener, type PlayerRuntimeDiagnosticPayload, type UseBoundPlayerOptions, type UseBoundPlayerResult, type UsePlayerResult, deriveBoundPlayerViewState, useBoundPlayer, usePlayer };
+interface BoundCompactPlayerProps {
+    readonly appearance: PlayerAppearance;
+    readonly context: PlaybackContextInput;
+    readonly queueItem: QueueItem;
+    readonly className?: string;
+}
+declare function BoundCompactPlayer({ appearance, className, context, queueItem, }: BoundCompactPlayerProps): react.JSX.Element;
+
+export { BoundCompactPlayer, type BoundCompactPlayerProps, MiniPlayerHost, type MiniPlayerHostProps, PlayerProvider, type PlayerProviderProps, type PlayerRuntimeContextValue, type PlayerRuntimeDiagnosticEvent, type PlayerRuntimeDiagnosticListener, type PlayerRuntimeDiagnosticPayload, type UseBoundPlayerOptions, type UseBoundPlayerResult, type UsePlayerResult, deriveBoundPlayerViewState, useBoundPlayer, usePlayer };

package/dist/react/index.js

@@ -1,4 +1,4 @@
-import { createContext, useRef, useState, useEffect, useSyncExternalStore, useMemo, useContext } from 'react';
+import { createContext, useRef, useState, useEffect, useSyncExternalStore, useMemo, useContext, useId } from 'react';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 
 // src/react/player-provider.tsx
@@ -2568,7 +2568,535 @@ function useBoundPlayer({
   }, [context, player.commands, player.state, queueItem]);
   return { state, commands };
 }
+function IconFrame({
+  children,
+  size = 20,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      "aria-hidden": "true",
+      focusable: "false",
+      viewBox: "0 0 24 24",
+      width: size,
+      height: size,
+      fill: "currentColor",
+      ...props,
+      children
+    }
+  );
+}
+function PlayIcon(props) {
+  return /* @__PURE__ */ jsx(IconFrame, { ...props, children: /* @__PURE__ */ jsx("path", { d: "M7 4.8c0-1.05 1.16-1.68 2.04-1.1l11 7.2a1.3 1.3 0 0 1 0 2.2l-11 7.2A1.31 1.31 0 0 1 7 19.2V4.8Z" }) });
+}
+function PauseIcon(props) {
+  return /* @__PURE__ */ jsxs(IconFrame, { ...props, children: [
+    /* @__PURE__ */ jsx("rect", { x: "5", y: "4", width: "5", height: "16", rx: "0.8" }),
+    /* @__PURE__ */ jsx("rect", { x: "14", y: "4", width: "5", height: "16", rx: "0.8" })
+  ] });
+}
+
+// src/ui/player-utils.ts
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function formatTime(seconds) {
+  if (seconds === null || !Number.isFinite(seconds) || seconds < 0) {
+    return "--:--";
+  }
+  const wholeSeconds = Math.floor(seconds);
+  const hours = Math.floor(wholeSeconds / 3600);
+  const minutes = Math.floor(wholeSeconds % 3600 / 60);
+  const remainder = wholeSeconds % 60;
+  if (hours > 0) {
+    return `${String(hours)}:${String(minutes).padStart(2, "0")}:${String(remainder).padStart(2, "0")}`;
+  }
+  return `${String(minutes).padStart(2, "0")}:${String(remainder).padStart(2, "0")}`;
+}
+function formatTimeAria(seconds) {
+  const safeSeconds = Math.max(0, Math.floor(seconds));
+  const hours = Math.floor(safeSeconds / 3600);
+  const minutes = Math.floor(safeSeconds % 3600 / 60);
+  const remainder = safeSeconds % 60;
+  const parts = [
+    hours > 0 ? `${String(hours)} hour${hours === 1 ? "" : "s"}` : "",
+    minutes > 0 ? `${String(minutes)} minute${minutes === 1 ? "" : "s"}` : "",
+    `${String(remainder)} second${remainder === 1 ? "" : "s"}`
+  ].filter(Boolean);
+  return parts.join(" ");
+}
+function PlayerSurface({
+  appearance,
+  children,
+  className,
+  label
+}) {
+  return /* @__PURE__ */ jsx(
+    "section",
+    {
+      "aria-label": label,
+      className: ["player-surface", className].filter(Boolean).join(" "),
+      "data-appearance": appearance,
+      children
+    }
+  );
+}
+function Artwork({ className, item }) {
+  const classes = ["player-artwork", className].filter(Boolean).join(" ");
+  if (item?.artwork !== void 0) {
+    return /* @__PURE__ */ jsx("span", { className: `${classes} player-artwork--image`, children: /* @__PURE__ */ jsx(
+      "img",
+      {
+        alt: item.artwork.alt,
+        className: "player-artwork__image",
+        decoding: "async",
+        src: item.artwork.url
+      }
+    ) });
+  }
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "aria-label": "Artwork unavailable",
+      className: `${classes} player-artwork--fallback`,
+      role: "img",
+      children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true" })
+    }
+  );
+}
+function ScrollingTitle({
+  enabled,
+  title
+}) {
+  const containsJapanese = /[\u3040-\u30ff\u3400-\u9fff]/u.test(title);
+  const viewportRef = useRef(null);
+  const contentRef = useRef(null);
+  const [marquee, setMarquee] = useState({
+    distance: 0,
+    duration: 10,
+    overflow: false
+  });
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    const content = contentRef.current;
+    if (viewport === null || content === null) {
+      return;
+    }
+    const viewportElement = viewport;
+    const contentElement = content;
+    function measure() {
+      const viewportWidth = Math.max(
+        viewportElement.getBoundingClientRect().width,
+        viewportElement.clientWidth
+      );
+      const contentWidth = Math.max(
+        contentElement.getBoundingClientRect().width,
+        contentElement.scrollWidth
+      );
+      const overflow = contentWidth - viewportWidth > 1;
+      const distance = enabled ? contentWidth + 12 : 0;
+      setMarquee({
+        distance,
+        duration: Math.max(10, distance / 22 + 4),
+        overflow
+      });
+    }
+    measure();
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", measure);
+      return () => {
+        window.removeEventListener("resize", measure);
+      };
+    }
+    const observer = new ResizeObserver(measure);
+    observer.observe(viewportElement);
+    observer.observe(contentElement);
+    return () => {
+      observer.disconnect();
+    };
+  }, [enabled, title]);
+  const style = {
+    "--player-title-scroll-offset": `${String(-marquee.distance)}px`,
+    "--player-title-scroll-duration": `${String(marquee.duration)}s`
+  };
+  return /* @__PURE__ */ jsx(
+    "strong",
+    {
+      className: "player-title",
+      "data-overflow": marquee.overflow ? "true" : "false",
+      "data-scroll": enabled ? "true" : "false",
+      "data-script": containsJapanese ? "japanese" : "latin",
+      ref: viewportRef,
+      style,
+      children: /* @__PURE__ */ jsx("span", { className: "player-title__text", ref: contentRef, children: title })
+    }
+  );
+}
+function TrackMetadata({
+  className,
+  item,
+  scrollTitle = false,
+  status
+}) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: ["player-metadata", className].filter(Boolean).join(" "),
+      children: [
+        status === void 0 ? null : /* @__PURE__ */ jsx("span", { className: "player-kicker", children: status }),
+        /* @__PURE__ */ jsx(
+          ScrollingTitle,
+          {
+            enabled: item !== null && scrollTitle,
+            title: item?.title ?? "No media selected"
+          },
+          item?.title ?? "No media selected"
+        ),
+        /* @__PURE__ */ jsx("span", { className: "player-creator", children: item === null ? "Select media to begin" : item.creatorName ?? "Artist unavailable" }),
+        item?.collectionTitle === void 0 ? null : /* @__PURE__ */ jsx("span", { className: "player-collection", children: item.collectionTitle })
+      ]
+    }
+  );
+}
+function TimeReadout({
+  className,
+  currentTimeSec,
+  durationSec
+}) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "aria-label": `${formatTime(currentTimeSec)} of ${formatTime(durationSec)}`,
+      className: ["player-time", className].filter(Boolean).join(" "),
+      children: [
+        /* @__PURE__ */ jsx("time", { children: formatTime(currentTimeSec) }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "/" }),
+        /* @__PURE__ */ jsx("time", { children: formatTime(durationSec) })
+      ]
+    }
+  );
+}
+function IconButton({
+  children,
+  className,
+  disabled = false,
+  label,
+  onClick,
+  pressed
+}) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      "aria-label": label,
+      ...pressed === void 0 ? {} : { "aria-pressed": pressed },
+      className: ["player-icon-button", className].filter(Boolean).join(" "),
+      disabled,
+      onClick,
+      title: label,
+      type: "button",
+      children
+    }
+  );
+}
+function SeekBar({
+  canSeek,
+  className,
+  commitMode,
+  currentTimeSec,
+  durationSec,
+  label = "Seek",
+  onSeek,
+  status
+}) {
+  const duration = durationSec !== null && Number.isFinite(durationSec) && durationSec > 0 ? durationSec : 0;
+  const disabled = !canSeek || duration === 0 || status === "loading";
+  const safeCurrentTime = clamp(currentTimeSec, 0, duration);
+  const [previewTime, setPreviewTime] = useState(safeCurrentTime);
+  const previewProgress = duration === 0 ? 0 : clamp(previewTime / duration, 0, 1) * 100;
+  const isAdjusting = useRef(false);
+  const lastCommitted = useRef(null);
+  useEffect(() => {
+    if (!isAdjusting.current) {
+      setPreviewTime(safeCurrentTime);
+    }
+  }, [safeCurrentTime]);
+  function updatePreview(value) {
+    const nextValue = clamp(value, 0, duration);
+    isAdjusting.current = true;
+    setPreviewTime(nextValue);
+    if (commitMode === "live") {
+      onSeek(nextValue);
+      lastCommitted.current = nextValue;
+    }
+  }
+  function commitPreview(value = previewTime) {
+    const nextValue = clamp(value, 0, duration);
+    if (disabled || !isAdjusting.current || commitMode === "live" && lastCommitted.current === nextValue) {
+      isAdjusting.current = false;
+      return;
+    }
+    onSeek(nextValue);
+    lastCommitted.current = nextValue;
+    isAdjusting.current = false;
+  }
+  function cancelPreview() {
+    isAdjusting.current = false;
+    lastCommitted.current = null;
+    setPreviewTime(safeCurrentTime);
+  }
+  return /* @__PURE__ */ jsxs(
+    "label",
+    {
+      className: ["player-seek", className].filter(Boolean).join(" "),
+      "data-disabled": disabled ? "true" : "false",
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "player-visually-hidden", children: label }),
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": "true",
+            className: "player-seek__progress",
+            style: { width: `${String(disabled ? 0 : previewProgress)}%` }
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            "aria-label": label,
+            "aria-valuetext": formatTimeAria(previewTime),
+            disabled,
+            max: duration || 1,
+            min: 0,
+            onBlur: (event) => {
+              commitPreview(Number(event.currentTarget.value));
+            },
+            onChange: (event) => {
+              updatePreview(Number(event.currentTarget.value));
+            },
+            onKeyUp: (event) => {
+              commitPreview(Number(event.currentTarget.value));
+            },
+            onPointerDown: () => {
+              isAdjusting.current = true;
+            },
+            onPointerCancel: cancelPreview,
+            onPointerUp: (event) => {
+              commitPreview(Number(event.currentTarget.value));
+            },
+            step: 0.1,
+            type: "range",
+            value: disabled ? 0 : previewTime
+          }
+        )
+      ]
+    }
+  );
+}
+var FALLBACK_PEAKS = [
+  0.16,
+  0.24,
+  0.42,
+  0.3,
+  0.58,
+  0.76,
+  0.48,
+  0.34,
+  0.66,
+  0.88,
+  0.62,
+  0.4,
+  0.52,
+  0.72,
+  0.44,
+  0.28,
+  0.56,
+  0.82,
+  0.68,
+  0.38,
+  0.24,
+  0.46,
+  0.32,
+  0.18
+];
+var BAR_COUNT = 512;
+var VIEWBOX_WIDTH = BAR_COUNT;
+function createWaveformBars(peaks) {
+  const source = peaks.length > 1 ? peaks : FALLBACK_PEAKS;
+  return Array.from({ length: BAR_COUNT }, (_, index) => {
+    const sourcePosition = index / Math.max(BAR_COUNT - 1, 1) * (source.length - 1);
+    const leftIndex = Math.floor(sourcePosition);
+    const rightIndex = Math.min(leftIndex + 1, source.length - 1);
+    const mix = sourcePosition - leftIndex;
+    const leftPeak = Math.abs(source[leftIndex] ?? 0);
+    const rightPeak = Math.abs(source[rightIndex] ?? leftPeak);
+    const interpolated = leftPeak + (rightPeak - leftPeak) * mix;
+    if (source.length >= BAR_COUNT) {
+      return clamp(Math.pow(interpolated, 1.18), 0.04, 1);
+    }
+    const noiseSeed = Math.sin((index + 1) * 12.9898 + source.length * 78.233) * 43758.5453;
+    const noise = noiseSeed - Math.floor(noiseSeed);
+    const fineDetail = 0.76 + noise * 0.34;
+    const transient = noise > 0.975 ? 3.2 : noise > 0.91 ? 1.75 : 1;
+    return clamp(
+      Math.pow(interpolated, 1.22) * fineDetail * transient,
+      0.04,
+      1
+    );
+  });
+}
+function Waveform({
+  className,
+  opacity = 1,
+  playedStateEnabled = true,
+  progress = 0,
+  waveform
+}) {
+  const clipId = useId().replaceAll(":", "");
+  const bars = createWaveformBars(waveform?.peaks ?? FALLBACK_PEAKS);
+  const progressWidth = clamp(progress, 0, 1) * VIEWBOX_WIDTH;
+  const classes = ["player-waveform", className].filter(Boolean).join(" ");
+  const barPath = bars.map((peak, index) => {
+    const halfHeight = peak * 47;
+    const x = index + 0.5;
+    return `M ${String(x)} ${String(50 - halfHeight)} V ${String(
+      50 + halfHeight
+    )}`;
+  }).join(" ");
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      "aria-hidden": "true",
+      className: classes,
+      focusable: "false",
+      preserveAspectRatio: "none",
+      style: { opacity: clamp(opacity, 0, 1), pointerEvents: "none" },
+      viewBox: `0 0 ${String(VIEWBOX_WIDTH)} 100`,
+      children: [
+        /* @__PURE__ */ jsx("path", { className: "player-waveform__base", d: barPath }),
+        playedStateEnabled ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("clipPath", { id: clipId, children: /* @__PURE__ */ jsx("rect", { width: progressWidth, height: "100" }) }),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              className: "player-waveform__played",
+              clipPath: `url(#${clipId})`,
+              d: barPath
+            }
+          )
+        ] }) : null
+      ]
+    }
+  );
+}
+function BoundCompactPlayerView({
+  appearance,
+  className,
+  commands,
+  contextId,
+  contextMode,
+  options,
+  state
+}) {
+  const progress = state.durationSec === null || state.durationSec <= 0 ? 0 : state.currentTimeSec / state.durationSec;
+  return /* @__PURE__ */ jsx(
+    PlayerSurface,
+    {
+      appearance,
+      className: ["player-bound-compact", className].filter(Boolean).join(" "),
+      label: `Inline player: ${state.item.title}`,
+      children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          className: "player-bound-compact__main",
+          "data-active": state.isActive ? "true" : "false",
+          "data-playback-context-id": contextId,
+          "data-playback-context-mode": contextMode,
+          "data-queue-item-id": state.queueItemId,
+          children: [
+            /* @__PURE__ */ jsx(
+              IconButton,
+              {
+                className: "player-play-button",
+                label: state.isPlaying ? "Pause" : "Play",
+                onClick: () => {
+                  void commands.togglePlayback();
+                },
+                children: state.isPlaying ? /* @__PURE__ */ jsx(PauseIcon, { size: 22 }) : /* @__PURE__ */ jsx(PlayIcon, { size: 22 })
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              Artwork,
+              {
+                className: "player-bound-compact__artwork",
+                item: state.item
+              }
+            ),
+            /* @__PURE__ */ jsx(TrackMetadata, { item: state.item, scrollTitle: state.isPlaying }),
+            /* @__PURE__ */ jsxs("div", { className: "player-bound-compact__signal", children: [
+              /* @__PURE__ */ jsx(
+                Waveform,
+                {
+                  opacity: options.waveformOpacity,
+                  playedStateEnabled: options.waveformPlayedStateEnabled,
+                  progress,
+                  waveform: state.item.waveform
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                TimeReadout,
+                {
+                  currentTimeSec: state.currentTimeSec,
+                  durationSec: state.durationSec
+                }
+              )
+            ] }),
+            /* @__PURE__ */ jsx(
+              SeekBar,
+              {
+                canSeek: state.canSeek,
+                commitMode: options.seekCommitMode,
+                currentTimeSec: state.currentTimeSec,
+                durationSec: state.durationSec,
+                label: `Seek in ${state.item.title}`,
+                onSeek: (seconds) => {
+                  commands.seekTo(seconds);
+                },
+                status: state.status
+              }
+            )
+          ]
+        }
+      )
+    }
+  );
+}
+function BoundCompactPlayer({
+  appearance,
+  className,
+  context,
+  queueItem
+}) {
+  const bound = useBoundPlayer({ context, queueItem });
+  const player = usePlayer();
+  return /* @__PURE__ */ jsx(
+    BoundCompactPlayerView,
+    {
+      appearance,
+      ...className === void 0 ? {} : { className },
+      commands: bound.commands,
+      contextId: context.id,
+      contextMode: context.mode,
+      options: {
+        seekCommitMode: player.state.experienceConfig.seekCommitMode,
+        waveformOpacity: player.state.experienceConfig.waveformOpacity,
+        waveformPlayedStateEnabled: player.state.experienceConfig.waveformPlayedStateEnabled
+      },
+      state: bound.state
+    }
+  );
+}
 
-export { MiniPlayerHost, PlayerProvider, deriveBoundPlayerViewState, useBoundPlayer, usePlayer };
+export { BoundCompactPlayer, MiniPlayerHost, PlayerProvider, deriveBoundPlayerViewState, useBoundPlayer, usePlayer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map