@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/media/AudioPlayer.svelte

@@ -0,0 +1,236 @@
+<!--
+  @file widgets/media/AudioPlayer.svelte
+  @description Audio player over a native HTMLAudioElement: play / pause, seek,
+    volume / mute, skip ±10s, with cover art and title. Ported from the
+    ocean-flow genesis composite widget into Ripple conventions — lucide named
+    icons replace the genesis `IconWidget`, Tailwind shadcn semantic tokens
+    throughout.
+  @created 2026-05-31 — composite consumer widgets migration. The genesis fake
+    `Math.random` waveform is removed; `showWaveform` now renders a simple
+    static bar strip (a real PCM analyser is out of scope and not needed for the
+    spec-driven use case). Lives in `media/` alongside ModelViewer / Embed.
+  @changed 2026-09-17 (fix/port-gaps) — the buffering ring stops under
+    prefers-reduced-motion (`motion-reduce:animate-none`, the variant Segmented
+    uses). A still ring with one open side still reads as loading.
+-->
+<script lang="ts">
+  import { safeUrl, safeStyle } from '@ripple-ui/core';
+  import { cn } from '../../utils.js';
+  import {
+    Music,
+    Play,
+    Pause,
+    Volume2,
+    VolumeX,
+    RotateCcw,
+    RotateCw
+  } from '@lucide/svelte';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    /** Audio source URL. Required. */
+    src: string;
+    /** Track title. */
+    title?: string;
+    /** Artist / author line. */
+    artist?: string;
+    /** Cover art image URL. */
+    cover?: string;
+    /** Start playing on mount. */
+    autoplay?: boolean;
+    /** Render a static decorative bar strip above the controls. */
+    showWaveform?: boolean;
+  }
+
+  let {
+    id,
+    class: className,
+    src,
+    title = 'Audio Track',
+    artist,
+    cover,
+    autoplay = false,
+    showWaveform = false
+  }: Props = $props();
+
+  let audio: HTMLAudioElement;
+  let isPlaying = $state(false);
+  let currentTime = $state(0);
+  let duration = $state(0);
+  let volume = $state(1);
+  let isMuted = $state(false);
+  let isLoading = $state(true);
+
+  // Static decorative bar heights (no fake audio analysis — see file header).
+  const bars = [
+    0.4, 0.7, 0.5, 0.9, 0.6, 0.3, 0.8, 0.55, 0.65, 0.45, 0.75, 0.5, 0.85, 0.4,
+    0.6, 0.7, 0.35, 0.9, 0.5, 0.65, 0.45, 0.8, 0.55, 0.7, 0.4
+  ];
+
+  function formatTime(seconds: number): string {
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.floor(seconds % 60);
+    return `${mins}:${secs.toString().padStart(2, '0')}`;
+  }
+
+  function togglePlay() {
+    if (isPlaying) audio.pause();
+    else audio.play();
+  }
+
+  function toggleMute() {
+    isMuted = !isMuted;
+    audio.muted = isMuted;
+  }
+
+  function handleVolumeChange(e: Event) {
+    const target = e.currentTarget as HTMLInputElement;
+    volume = parseFloat(target.value);
+    audio.volume = volume;
+    if (volume > 0) isMuted = false;
+  }
+
+  function handleSeek(e: Event) {
+    const target = e.currentTarget as HTMLInputElement;
+    const time = parseFloat(target.value);
+    audio.currentTime = time;
+    currentTime = time;
+  }
+
+  function skip(seconds: number) {
+    audio.currentTime = Math.max(0, Math.min(duration, audio.currentTime + seconds));
+  }
+
+  const progressPercent = $derived(duration > 0 ? (currentTime / duration) * 100 : 0);
+  const playedBars = $derived(
+    duration > 0 ? Math.round((currentTime / duration) * bars.length) : 0
+  );
+</script>
+
+<div {id} class={cn('audio-widget bg-card rounded-2xl border overflow-hidden', className)}>
+  <!-- Cover art and info -->
+  <div class="flex items-center gap-4 p-4">
+    {#if cover}
+      <div class="w-16 h-16 rounded-xl overflow-hidden bg-muted shrink-0">
+        <img src={safeUrl(cover, { kind: 'resource' })} alt={title} class="w-full h-full object-cover" />
+      </div>
+    {:else}
+      <div class="w-16 h-16 rounded-xl bg-primary/10 flex items-center justify-center shrink-0">
+        <Music size={24} class="text-primary" />
+      </div>
+    {/if}
+
+    <div class="flex-1 min-w-0">
+      <h3 class="font-semibold truncate">{title}</h3>
+      {#if artist}
+        <p class="text-sm text-muted-foreground truncate">{artist}</p>
+      {/if}
+    </div>
+  </div>
+
+  <!-- Static decorative bars -->
+  {#if showWaveform}
+    <div class="flex items-end gap-0.5 px-4 h-12">
+      {#each bars as h, i}
+        <div
+          class={cn('flex-1 rounded-sm', i < playedBars ? 'bg-primary' : 'bg-muted')}
+          style={safeStyle(`height: ${h * 100}%`)}
+        ></div>
+      {/each}
+    </div>
+  {/if}
+
+  <!-- Progress bar -->
+  <div class="px-4 py-2">
+    <input
+      type="range"
+      min="0"
+      max={duration || 100}
+      value={currentTime}
+      oninput={handleSeek}
+      aria-label="Seek"
+      class="w-full h-1 bg-muted rounded-full appearance-none cursor-pointer
+        [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-3 [&::-webkit-slider-thumb]:h-3
+        [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary"
+      style={safeStyle(`background: linear-gradient(to right, var(--primary) ${progressPercent}%, var(--muted) ${progressPercent}%)`)}
+    />
+    <div class="flex justify-between text-xs text-muted-foreground mt-1">
+      <span>{formatTime(currentTime)}</span>
+      <span>{formatTime(duration)}</span>
+    </div>
+  </div>
+
+  <!-- Controls -->
+  <div class="flex items-center justify-between px-4 pb-4">
+    <div class="flex items-center gap-2">
+      <button onclick={toggleMute} class="p-2 rounded-lg hover:bg-muted transition-colors" aria-label="Mute">
+        {#if isMuted || volume === 0}
+          <VolumeX size={18} class="text-muted-foreground" />
+        {:else}
+          <Volume2 size={18} class="text-muted-foreground" />
+        {/if}
+      </button>
+      <input
+        type="range"
+        min="0"
+        max="1"
+        step="0.1"
+        value={volume}
+        oninput={handleVolumeChange}
+        aria-label="Volume"
+        class="w-20 h-1 bg-muted rounded-full appearance-none cursor-pointer
+          [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-2 [&::-webkit-slider-thumb]:h-2
+          [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary"
+      />
+    </div>
+
+    <div class="flex items-center gap-2">
+      <button onclick={() => skip(-10)} class="p-2 rounded-lg hover:bg-muted transition-colors" aria-label="Back 10 seconds">
+        <RotateCcw size={18} class="text-muted-foreground" />
+      </button>
+      <button
+        onclick={togglePlay}
+        class="w-12 h-12 rounded-full bg-primary text-primary-foreground flex items-center justify-center hover:opacity-90 transition-opacity"
+        aria-label={isPlaying ? 'Pause' : 'Play'}
+      >
+        {#if isLoading}
+          <div class="w-5 h-5 border-2 border-current border-t-transparent rounded-full animate-spin motion-reduce:animate-none"></div>
+        {:else if isPlaying}
+          <Pause size={20} />
+        {:else}
+          <Play size={20} class="ml-0.5" />
+        {/if}
+      </button>
+      <button onclick={() => skip(10)} class="p-2 rounded-lg hover:bg-muted transition-colors" aria-label="Forward 10 seconds">
+        <RotateCw size={18} class="text-muted-foreground" />
+      </button>
+    </div>
+
+    <div class="w-[76px]"></div>
+  </div>
+
+  <!-- Native audio element -->
+  <audio
+    bind:this={audio}
+    src={safeUrl(src, { kind: 'resource' })}
+    {autoplay}
+    onloadedmetadata={() => {
+      duration = audio.duration;
+      isLoading = false;
+    }}
+    ontimeupdate={() => {
+      currentTime = audio.currentTime;
+    }}
+    onplay={() => {
+      isPlaying = true;
+    }}
+    onpause={() => {
+      isPlaying = false;
+    }}
+    onended={() => {
+      isPlaying = false;
+      currentTime = 0;
+    }}
+  ></audio>
+</div>

package/dist/widgets/media/AudioPlayer.svelte.d.ts

@@ -0,0 +1,19 @@
+interface Props {
+    id?: string;
+    class?: string;
+    /** Audio source URL. Required. */
+    src: string;
+    /** Track title. */
+    title?: string;
+    /** Artist / author line. */
+    artist?: string;
+    /** Cover art image URL. */
+    cover?: string;
+    /** Start playing on mount. */
+    autoplay?: boolean;
+    /** Render a static decorative bar strip above the controls. */
+    showWaveform?: boolean;
+}
+declare const AudioPlayer: import("svelte").Component<Props, {}, "">;
+type AudioPlayer = ReturnType<typeof AudioPlayer>;
+export default AudioPlayer;

package/dist/widgets/media/Embed.svelte

@@ -0,0 +1,205 @@
+<!--
+  @file Embed.svelte
+  @description Sandboxed iframe escape-hatch widget. Renders third-party
+    content (a URL or an inline `srcdoc` document) inside a hardened iframe.
+  @created 2026-05-22 — Increment 5 (escape-hatch widgets). This is the
+    "sandboxed escape hatch" half of the increment: when no real widget
+    fits, a spec can embed arbitrary content here without the renderer
+    surrendering control of the security boundary.
+
+  SECURITY — read before changing anything in this file:
+
+    * The `sandbox` attribute is RENDERER-CONTROLLED. It is hard-coded to
+      exactly `allow-scripts allow-popups allow-popups-to-escape-sandbox
+      allow-forms`. It is NOT author-settable: no spec prop flows into the
+      sandbox string. A spec MUST NOT be able to widen, alter, or remove
+      it. `allow-same-origin` is deliberately ABSENT — its absence is the
+      load-bearing guarantee. Without it the iframe runs at an opaque
+      origin and cannot read the pocket's cookies / localStorage or reach
+      the pocket backend. `allow-top-navigation` is also absent so the
+      frame cannot hijack the host page.
+    * `referrerpolicy="no-referrer"` and `loading="lazy"` are always set.
+    * The `allow` permissions-policy passes through a CLOSED enum — only
+      fullscreen / autoplay / encrypted-media / picture-in-picture survive.
+      camera / microphone / geolocation / usb / payment / display-capture
+      can never be granted, regardless of spec input.
+    * `mode=url` accepts `https://` URLs only. javascript: / data: / blob:
+      / file:// / http:// / protocol-relative `//` are rejected here as a
+      belt-and-braces client check. The authoritative host-allowlist gate
+      lives pocketpaw-side.
+    * `mode=srcdoc` content is bound through Svelte (attribute-encoded) and
+      capped at ~64KB. It runs in the same opaque-origin sandbox, so it
+      injects into a quarantined DOM — never the pocket's.
+  @changes
+    - Initial creation.
+-->
+<script lang="ts" module>
+  /**
+   * The one and only sandbox token set. Renderer-controlled — never derived
+   * from spec input. Exported so tests can assert the exact string and so
+   * the contract is auditable from one place.
+   */
+  export const EMBED_SANDBOX =
+    'allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms';
+
+  /**
+   * Closed allowlist for the iframe `allow=` permissions-policy attribute.
+   * Anything not in this set is dropped. Sensitive capabilities
+   * (camera, microphone, geolocation, usb, payment, display-capture) are
+   * intentionally NOT here and cannot be granted.
+   */
+  export const EMBED_ALLOW_ENUM = [
+    'fullscreen',
+    'autoplay',
+    'encrypted-media',
+    'picture-in-picture'
+  ] as const;
+
+  /** Max byte length accepted for inline `srcdoc` content. */
+  export const EMBED_SRCDOC_MAX = 64 * 1024;
+
+  /** True only for absolute `https://` URLs. Rejects every other scheme. */
+  export function isSafeEmbedUrl(raw: unknown): raw is string {
+    if (typeof raw !== 'string') return false;
+    const value = raw.trim();
+    if (value === '') return false;
+    // Reject protocol-relative `//host` — it inherits the page scheme.
+    if (value.startsWith('//')) return false;
+    let parsed: URL;
+    try {
+      parsed = new URL(value);
+    } catch {
+      return false;
+    }
+    // Only https. Blocks javascript:, data:, blob:, file:, http:, etc.
+    return parsed.protocol === 'https:';
+  }
+
+  /** Filter an `allow` list down to the closed enum. */
+  export function sanitizeEmbedAllow(input: unknown): string {
+    if (!Array.isArray(input)) return '';
+    const permitted = new Set<string>(EMBED_ALLOW_ENUM);
+    const seen = new Set<string>();
+    for (const item of input) {
+      if (typeof item !== 'string') continue;
+      const token = item.trim().toLowerCase();
+      if (permitted.has(token)) seen.add(token);
+    }
+    return [...seen].join('; ');
+  }
+</script>
+
+<script lang="ts">
+  import { safeStyle } from '@ripple-ui/core';
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    /** `url` embeds a remote page; `srcdoc` embeds an inline document. */
+    mode: 'url' | 'srcdoc';
+    /** Remote page URL — used when mode=url. Must be https://. */
+    url?: string;
+    /** Inline HTML document — used when mode=srcdoc. Capped at 64KB. */
+    srcdoc?: string;
+    /** Accessible title for the iframe. Required for a11y. */
+    title: string;
+    /** Fixed height in px. Ignored when `aspectRatio` is set. */
+    height?: number;
+    /** Aspect ratio, e.g. "16 / 9". Wins over `height` when present. */
+    aspectRatio?: string;
+    /** Optional permissions-policy tokens — filtered through a closed enum. */
+    allow?: string[];
+  }
+
+  let {
+    id,
+    class: className,
+    style,
+    mode,
+    url,
+    srcdoc,
+    title,
+    height,
+    aspectRatio,
+    allow
+  }: Props = $props();
+
+  // `allow` is run through the closed enum — disallowed tokens are dropped.
+  const allowAttr = $derived(sanitizeEmbedAllow(allow));
+
+  // mode=url: only https:// survives. Everything else renders an error.
+  const safeUrl = $derived(mode === 'url' && isSafeEmbedUrl(url) ? url : undefined);
+
+  // mode=srcdoc: cap the payload. Svelte attribute-binds it, so the value is
+  // HTML-attribute-encoded and cannot break out of the `srcdoc=` attribute.
+  const safeSrcdoc = $derived.by(() => {
+    if (mode !== 'srcdoc') return undefined;
+    if (typeof srcdoc !== 'string') return undefined;
+    if (srcdoc.length > EMBED_SRCDOC_MAX) {
+      console.warn(
+        `[Ripple] embed srcdoc exceeds ${EMBED_SRCDOC_MAX} bytes — truncated.`
+      );
+      return srcdoc.slice(0, EMBED_SRCDOC_MAX);
+    }
+    return srcdoc;
+  });
+
+  const invalid = $derived(
+    (mode === 'url' && safeUrl === undefined) ||
+      (mode === 'srcdoc' && safeSrcdoc === undefined)
+  );
+
+  const frameStyle = $derived.by(() => {
+    const s: string[] = ['width:100%', 'border:0', 'display:block'];
+    if (aspectRatio) {
+      s.push(`aspect-ratio:${aspectRatio}`);
+    } else if (typeof height === 'number') {
+      s.push(`height:${height}px`);
+    } else {
+      s.push('height:360px');
+    }
+    if (style) s.push(...Object.entries(style).map(([k, v]) => `${k}:${v}`));
+    return safeStyle(s.join(';'));
+  });
+</script>
+
+{#if invalid}
+  <div
+    {id}
+    class="ripple-embed-error text-red-500 p-2 border border-red-300 rounded bg-red-50 text-sm {className ?? ''}"
+  >
+    {#if mode === 'url'}
+      Embed blocked: only <code>https://</code> URLs are allowed.
+    {:else}
+      Embed blocked: no <code>srcdoc</code> content provided.
+    {/if}
+  </div>
+{:else if mode === 'url'}
+  <!--
+    sandbox is the hard-coded EMBED_SANDBOX constant — NOT bound to any
+    spec prop. referrerpolicy + loading are always pinned.
+  -->
+  <iframe
+    {id}
+    class={className}
+    style={frameStyle}
+    {title}
+    src={safeUrl}
+    sandbox={EMBED_SANDBOX}
+    allow={allowAttr || undefined}
+    referrerpolicy="no-referrer"
+    loading="lazy"
+  ></iframe>
+{:else}
+  <iframe
+    {id}
+    class={className}
+    style={frameStyle}
+    {title}
+    srcdoc={safeSrcdoc}
+    sandbox={EMBED_SANDBOX}
+    allow={allowAttr || undefined}
+    referrerpolicy="no-referrer"
+    loading="lazy"
+  ></iframe>
+{/if}

package/dist/widgets/media/Embed.svelte.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The one and only sandbox token set. Renderer-controlled — never derived
+ * from spec input. Exported so tests can assert the exact string and so
+ * the contract is auditable from one place.
+ */
+export declare const EMBED_SANDBOX = "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms";
+/**
+ * Closed allowlist for the iframe `allow=` permissions-policy attribute.
+ * Anything not in this set is dropped. Sensitive capabilities
+ * (camera, microphone, geolocation, usb, payment, display-capture) are
+ * intentionally NOT here and cannot be granted.
+ */
+export declare const EMBED_ALLOW_ENUM: readonly ["fullscreen", "autoplay", "encrypted-media", "picture-in-picture"];
+/** Max byte length accepted for inline `srcdoc` content. */
+export declare const EMBED_SRCDOC_MAX: number;
+/** True only for absolute `https://` URLs. Rejects every other scheme. */
+export declare function isSafeEmbedUrl(raw: unknown): raw is string;
+/** Filter an `allow` list down to the closed enum. */
+export declare function sanitizeEmbedAllow(input: unknown): string;
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    /** `url` embeds a remote page; `srcdoc` embeds an inline document. */
+    mode: 'url' | 'srcdoc';
+    /** Remote page URL — used when mode=url. Must be https://. */
+    url?: string;
+    /** Inline HTML document — used when mode=srcdoc. Capped at 64KB. */
+    srcdoc?: string;
+    /** Accessible title for the iframe. Required for a11y. */
+    title: string;
+    /** Fixed height in px. Ignored when `aspectRatio` is set. */
+    height?: number;
+    /** Aspect ratio, e.g. "16 / 9". Wins over `height` when present. */
+    aspectRatio?: string;
+    /** Optional permissions-policy tokens — filtered through a closed enum. */
+    allow?: string[];
+}
+declare const Embed: import("svelte").Component<Props, {}, "">;
+type Embed = ReturnType<typeof Embed>;
+export default Embed;