@kitn.ai/ui 0.28.0 → 0.30.0

package/src/primitives/create-tween.ts

@@ -1,266 +0,0 @@
-import { createSignal, onCleanup, untrack, type Accessor } from 'solid-js';
-
-export type Transition =
-  | { duration: number; ease?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' }
-  | { type: 'spring'; duration: number; bounce: number };
-
-/**
- * Builds an easing function from a CSS-style cubic bezier. The curve's
- * endpoints are fixed at (0, 0) and (1, 1); (x1, y1) and (x2, y2) are the
- * two control points. Given a progress value `t` used as the curve's `x`,
- * solves `X(s) === t` for the curve parameter `s` via Newton-Raphson (a
- * handful of iterations converges for these curves), falls back to
- * bisection if the derivative gets too small or a step would leave
- * [0, 1], then returns `Y(s)`.
- */
-function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
-  const x = (s: number) => 3 * (1 - s) * (1 - s) * s * x1 + 3 * (1 - s) * s * s * x2 + s * s * s;
-  const y = (s: number) => 3 * (1 - s) * (1 - s) * s * y1 + 3 * (1 - s) * s * s * y2 + s * s * s;
-  const xDerivative = (s: number) =>
-    3 * (1 - s) * (1 - s) * x1 + 6 * (1 - s) * s * (x2 - x1) + 3 * s * s * (1 - x2);
-
-  function bisect(t: number): number {
-    let lo = 0;
-    let hi = 1;
-    for (let i = 0; i < 30; i++) {
-      const mid = (lo + hi) / 2;
-      if (x(mid) < t) lo = mid;
-      else hi = mid;
-    }
-    return (lo + hi) / 2;
-  }
-
-  return (t: number) => {
-    if (t <= 0) return 0;
-    if (t >= 1) return 1;
-
-    let s = t;
-    for (let i = 0; i < 8; i++) {
-      const derivative = xDerivative(s);
-      if (Math.abs(derivative) < 1e-6) return y(bisect(t));
-
-      const next = s - (x(s) - t) / derivative;
-      if (next <= 0 || next >= 1) return y(bisect(t));
-
-      s = next;
-    }
-    return y(s);
-  };
-}
-
-// Matches motion's named curves so the visualizers feel like their LiveKit
-// counterparts rather than a plausible-looking approximation.
-//
-// Every easing here is TOTAL: it clamps `t` into [0, 1] itself rather than
-// trusting its caller. `cubicBezier` already did (its Newton solve needs `t`
-// in range to converge); `linear` was the bare identity and passed anything
-// straight through. `step()` below clamps the top but not the bottom, so a
-// frame timestamp EARLIER than the origin `to()` captured yields a negative
-// `t` and, through an unclamped easing, a tween that runs backwards.
-//
-// That timestamp cannot occur in a browser -- requestAnimationFrame's
-// timestamp and `performance.now()` share a time origin per spec -- so this is
-// robustness, not a live bug. It does occur under vitest + jsdom, where the
-// two do not share an origin. The clamp lives in the easings rather than at
-// the `step()` call site so the tests can drive a negative `t` through each
-// curve individually and prove which ones guard.
-const EASINGS = {
-  linear: (t: number) => Math.min(1, Math.max(0, t)),
-  easeIn: cubicBezier(0.42, 0, 1, 1),
-  easeOut: cubicBezier(0, 0, 0.58, 1),
-  easeInOut: cubicBezier(0.42, 0, 0.58, 1),
-} as const;
-
-/**
- * Damped-spring position at normalized time `t` (0..1), settling at 1.
- *
- * `bounce` maps to the damping ratio: 0 is critically damped (no overshoot),
- * higher values overshoot more. Matches the feel of motion's spring defaults
- * closely enough for shader uniforms, without the dependency.
- *
- * `t` is clamped at 0 for the same reason the named easings are (see EASINGS),
- * and the failure here is far louder than theirs: the decay term is
- * `Math.exp(-zeta * omega * t)`, so a negative `t` makes it GROW rather than
- * decay. At t = -0.25 with bounce 0.4 this returned ~5.9 instead of something
- * in [0, ~1.3]. No top clamp: overshooting past 1 is what a spring is for.
- */
-function spring(t: number, bounce: number): number {
-  t = Math.max(0, t);
-  const zeta = Math.max(0.05, 1 - Math.min(0.95, bounce));
-  const omega = 10;
-  const damped = omega * Math.sqrt(Math.max(0, 1 - zeta * zeta));
-  return (
-    1 -
-    Math.exp(-zeta * omega * t) *
-      (Math.cos(damped * t) + ((zeta * omega) / (damped || 1)) * Math.sin(damped * t))
-  );
-}
-
-function isSpring(tr: Transition): tr is { type: 'spring'; duration: number; bounce: number } {
-  return 'type' in tr && tr.type === 'spring';
-}
-
-/**
- * A tweened number driven by requestAnimationFrame.
- *
- * Exists so shader uniforms can animate without pulling in a motion library.
- * CSS transitions cannot help here: uniforms are plain JS numbers handed to
- * WebGL every frame.
- *
- * `to()` interrupts whatever is in flight. An array target ping-pongs between
- * its two values forever, which is how the listening and thinking pulses read.
- * `duration: 0` (or no transition) sets instantly, which live volume needs so
- * the picture never lags the audio.
- *
- * `animating` is true exactly while a frame loop is armed: from an animated
- * `to()` until it lands (a ping-pong never lands, so it stays true), false
- * for instant sets and after dispose. It is a real signal on purpose -- the
- * aurora variant's volume-override effect reads it as its upstream-parity
- * "scale tween idle" guard, and being reactive means that effect re-runs
- * the moment a landing settles instead of waiting for the next volume tick.
- */
-export function createTween(initial: number): {
-  value: Accessor<number>;
-  animating: Accessor<boolean>;
-  to(target: number | [number, number], transition?: Transition): void;
-} {
-  const [value, setValue] = createSignal(initial);
-  const [animating, setAnimating] = createSignal(false);
-  let raf = 0;
-  let disposed = false;
-
-  /**
-   * `cancelAnimationFrame`, captured at SETUP.
-   *
-   * `stop()` below runs at dispose, and dispose is not guaranteed to happen
-   * while the page that mounted this tween is still standing -- a host can tear
-   * its DOM globals down in between (`component-register`'s
-   * `disconnectedCallback` defers a microtask; a test environment deletes the
-   * globals synchronously right after detaching). A bare `cancelAnimationFrame`
-   * there throws from a promise nobody holds, so it surfaces as an unhandled
-   * rejection that fails a run in which every test passed. See
-   * tests/components/teardown-without-dom-globals.test.tsx.
-   *
-   * The FUNCTION, not the view. The `const win = window` capture that fixes a
-   * bare `document` does nothing here: `window === globalThis` -- measured, in
-   * jsdom and in real Chromium/WebKit alike -- and the teardown deletes these
-   * keys off that very object, so `win.cancelAnimationFrame` is undefined by
-   * the time cleanup runs. It only trades the ReferenceError for a TypeError.
-   * `.bind` pins the receiver the WebIDL operation is specified on; Chromium
-   * and WebKit both accept a detached call (measured), so the bind is belt and
-   * braces against an engine that does not, at zero cost.
-   *
-   * GUARDED because "setup" for this primitive is the component body, and a
-   * server render executes component bodies. Node has no `cancelAnimationFrame`
-   * at all, so an unguarded capture here would trade the disposal crash for an
-   * SSR crash -- measured, not hypothesised. Nothing can be scheduled without
-   * `requestAnimationFrame` either, so the no-op fallback is exactly right.
-   */
-  const cancelFrame = typeof cancelAnimationFrame === 'function'
-    ? cancelAnimationFrame.bind(globalThis)
-    : () => {};
-
-  const stop = () => {
-    if (raf) cancelFrame(raf);
-    raf = 0;
-  };
-
-  onCleanup(() => {
-    disposed = true;
-    stop();
-    setAnimating(false);
-  });
-
-  function to(target: number | [number, number], transition?: Transition) {
-    stop();
-    if (disposed) return;
-
-    const pingPong = Array.isArray(target);
-    // Untracked: `.to()` is an imperative command ("animate to this
-    // target"), not a reactive read. Its normal caller is a createEffect
-    // reacting to some OTHER signal (e.g. state changing); reading this
-    // tween's own `value()` here without untrack() would make that effect
-    // implicitly depend on the tween's own signal too. That is invisible
-    // for a single tween (it would just restart itself every frame and
-    // still crawl toward the target) but is fatal the moment a caller
-    // creates a SECOND tween and `.to()`'s both from the same effect (see
-    // the wave shader variant, which does exactly this for amplitude and
-    // frequency): a browser fires one frame's queued
-    // requestAnimationFrame callbacks in the order they were registered, so
-    // the FIRST tween's step -- which runs first, and whose `setValue`
-    // synchronously re-triggers the (now-dependent) effect -- cancels the
-    // SECOND tween's already-queued step before the browser ever reaches
-    // it. That repeats identically every single frame, so the second
-    // tween's `step` never fires even once and its value never leaves its
-    // initial one, permanently, no matter how long the effect keeps
-    // "restarting" it.
-    const [a, b] = pingPong ? target : [untrack(value), target];
-
-    if (!transition || (!isSpring(transition) && transition.duration === 0)) {
-      setAnimating(false);
-      setValue(pingPong ? a : b);
-      return;
-    }
-
-    const durationMs = transition.duration * 1000;
-    if (durationMs <= 0) {
-      setAnimating(false);
-      setValue(b);
-      return;
-    }
-
-    if (typeof requestAnimationFrame === 'undefined') {
-      setAnimating(false);
-      setValue(b);
-      return;
-    }
-
-    const ease = isSpring(transition)
-      ? (t: number) => spring(t, transition.bounce)
-      : EASINGS[transition.ease ?? 'easeOut'];
-
-    // A ping-pong starts from its first value rather than wherever it was, so
-    // the pulse reads the same every time it restarts. `a` is already an
-    // untracked read of the current value (or the ping-pong's first target
-    // value) from above -- reused here instead of reading `value()` again.
-    let from = a;
-    let to_ = b;
-    if (pingPong) setValue(a);
-
-    // requestAnimationFrame's timestamp and performance.now() share a time
-    // origin per spec, so capturing the origin here, at the moment to() is
-    // called, is directly comparable to the `now` a later frame reports.
-    // That means elapsed time is measured from when this leg actually
-    // started, correct on the very first frame with no lazy-capture dance
-    // and no risk of an idle gap since the last tween being charged against
-    // this one.
-    let legStart = performance.now();
-    const step = (now: number) => {
-      const t = Math.min(1, (now - legStart) / durationMs);
-      setValue(from + (to_ - from) * ease(t));
-
-      if (t < 1) {
-        raf = requestAnimationFrame(step);
-        return;
-      }
-
-      if (!pingPong) {
-        setValue(to_);
-        raf = 0;
-        setAnimating(false);
-        return;
-      }
-
-      // Reverse and run again, from a fresh origin for the new leg.
-      setValue(to_);
-      [from, to_] = [to_, from];
-      legStart = performance.now();
-      raf = requestAnimationFrame(step);
-    };
-
-    setAnimating(true);
-    raf = requestAnimationFrame(step);
-  }
-
-  return { value, animating, to };
-}

package/src/primitives/embed-providers.ts

@@ -1,254 +0,0 @@
-// src/primitives/embed-providers.ts
-// Pure provider resolution for <kai-embed>: map an EmbedCardData → an embeddable
-// player URL + poster + iframe sandbox/allow. Covers youtube (privacy-enhanced
-// youtube-nocookie), vimeo (dnt=1), and generic (https-only, ORIGIN-ALLOWLISTED).
-// No network, no DOM. See docs/superpowers/specs/2026-06-13-kc-link-embed-cards-design.md.
-import type { CardEnvelope } from './card-contract';
-
-/** Media provider for an embed card. */
-export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
-
-/** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */
-export interface EmbedCardData {
-  /** Media provider. 'generic' frames `url` directly. */
-  provider: EmbedProvider;
-  /** Provider video id (youtube/vimeo) when not parsing from `url`. */
-  id?: string;
-  /** Full media/watch/embed URL. */
-  url?: string;
-  /** Accessible iframe title + poster label. */
-  title?: string;
-  /** Thumbnail before play; derived for youtube/vimeo when omitted. */
-  poster?: string;
-  /** Start offset, seconds. */
-  start?: number;
-  /** Player aspect ratio. Default '16:9'. */
-  aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
-}
-
-/** The full envelope an agent/server emits for an embed card. */
-export type EmbedCardEnvelope = CardEnvelope<'embed', EmbedCardData>;
-
-/** The `type` discriminator for embed cards. */
-export const EMBED_CARD_TYPE = 'embed' as const;
-
-export interface ResolvedEmbed {
-  /** The iframe src loaded on play (already including autoplay/start params). */
-  embedUrl: string;
-  /** Poster/thumbnail to show before play (derived when not supplied). */
-  posterUrl?: string;
-  /** sandbox attribute for the player iframe. */
-  sandbox: string;
-  /** allow attribute (fullscreen, encrypted-media, picture-in-picture, …). */
-  allow: string;
-}
-
-// A provider player NEEDS allow-scripts + allow-same-origin (its OWN origin) to run.
-// That is safe here because the framed origin is a KNOWN, trusted video provider on a
-// DIFFERENT origin than the host — same-origin policy still isolates the host page from
-// the provider. allow-popups(-to-escape-sandbox) lets "watch on YouTube" work. The
-// `allow` attribute (not sandbox) governs autoplay/fullscreen/encrypted-media.
-// Contrast <kai-artifact> (allow-scripts allow-forms, NO allow-same-origin) which frames
-// arbitrary consumer HTML and so trusts nothing.
-const PLAYER_SANDBOX =
-  'allow-scripts allow-same-origin allow-presentation allow-popups allow-popups-to-escape-sandbox';
-const PLAYER_ALLOW =
-  'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen';
-
-// --- generic origin allowlist (security decision) -------------------------
-//
-// A `generic` embed frames an ARBITRARY https URL. An agent-supplied generic URL is a
-// supply-chain risk, so it is REJECTED unless the app has explicitly allowlisted its
-// origin. The allowlist defaults to EMPTY: out of the box, `generic` embeds are blocked.
-const allowedGenericOrigins = new Set<string>();
-
-/**
- * App opt-in: allow `generic` embeds whose origin is in this list. Origins are
- * normalized via the URL parser (scheme + host + port). Only https origins are
- * accepted (a non-https origin is ignored). Call once at app startup.
- */
-export function configureEmbedAllowlist(origins: string[]): void {
-  for (const o of origins) {
-    const origin = normalizeOrigin(o);
-    if (origin) allowedGenericOrigins.add(origin);
-  }
-}
-
-/** True when `url`'s origin has been allowlisted for `generic` embeds. */
-export function isGenericOriginAllowed(url: string): boolean {
-  const origin = originOf(url);
-  return origin !== undefined && allowedGenericOrigins.has(origin);
-}
-
-/** Test-only: clear the generic allowlist so tests stay isolated. */
-export function __resetEmbedAllowlistForTests(): void {
-  allowedGenericOrigins.clear();
-}
-
-/** Normalize an allowlist entry (a URL or bare origin) to a canonical https origin, or undefined. */
-function normalizeOrigin(input: string): string | undefined {
-  const origin = originOf(input) ?? originOf(`https://${input}`);
-  if (!origin) return undefined;
-  return origin.startsWith('https://') ? origin : undefined;
-}
-
-/** The `scheme://host[:port]` origin of a URL, or undefined when unparseable. */
-function originOf(url: string): string | undefined {
-  try {
-    return new URL(url).origin;
-  } catch {
-    return undefined;
-  }
-}
-
-// --- id parsing -----------------------------------------------------------
-
-/** Extract a YouTube id from a watch / youtu.be / shorts / embed URL. */
-export function parseYouTubeId(url: string): string | undefined {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return undefined;
-  }
-  const host = parsed.hostname.replace(/^www\./, '');
-  if (host === 'youtu.be') {
-    return cleanId(parsed.pathname.slice(1));
-  }
-  if (host === 'youtube.com' || host === 'm.youtube.com' || host === 'youtube-nocookie.com') {
-    const v = parsed.searchParams.get('v');
-    if (v) return cleanId(v);
-    // /shorts/<id>, /embed/<id>, /v/<id>
-    const m = parsed.pathname.match(/^\/(?:shorts|embed|v)\/([^/?#]+)/);
-    if (m) return cleanId(m[1]);
-  }
-  return undefined;
-}
-
-/** Extract a Vimeo id from a vimeo.com/<id> (or player.vimeo.com/video/<id>) URL. */
-export function parseVimeoId(url: string): string | undefined {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return undefined;
-  }
-  const host = parsed.hostname.replace(/^www\./, '');
-  if (host !== 'vimeo.com' && host !== 'player.vimeo.com') return undefined;
-  const m = parsed.pathname.match(/(?:^|\/)(\d+)(?:\/|$)/);
-  return m ? m[1] : undefined;
-}
-
-/** A provider video id must be the [A-Za-z0-9_-] alphabet (matches the schema pattern). */
-function cleanId(id: string): string | undefined {
-  return /^[A-Za-z0-9_-]+$/.test(id) ? id : undefined;
-}
-
-// --- resolution -----------------------------------------------------------
-
-/**
- * Resolve an EmbedCardData to an embeddable player URL + poster + sandbox/allow.
- * Throws (with a human message) on a missing/invalid provider id, a non-https
- * generic URL, or a generic origin not in the app allowlist — the card turns these
- * into an inline error + an `error` event.
- */
-export function resolveEmbed(data: EmbedCardData): ResolvedEmbed {
-  const start = data.start ? `&start=${data.start}` : '';
-  switch (data.provider) {
-    case 'youtube': {
-      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
-      if (!id) throw new Error('youtube embed: missing or unparseable id/url');
-      return {
-        embedUrl: `https://www.youtube-nocookie.com/embed/${id}?autoplay=1&rel=0${start}`,
-        posterUrl: data.poster ?? `https://i.ytimg.com/vi/${id}/hqdefault.jpg`,
-        sandbox: PLAYER_SANDBOX,
-        allow: PLAYER_ALLOW,
-      };
-    }
-    case 'vimeo': {
-      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
-      if (!id) throw new Error('vimeo embed: missing or unparseable id/url');
-      return {
-        embedUrl: `https://player.vimeo.com/video/${id}?autoplay=1&dnt=1${
-          data.start ? `#t=${data.start}s` : ''
-        }`,
-        // Vimeo has no static thumbnail URL; rely on a supplied poster (or placeholder).
-        posterUrl: data.poster,
-        sandbox: PLAYER_SANDBOX,
-        allow: PLAYER_ALLOW,
-      };
-    }
-    case 'generic': {
-      if (!data.url) throw new Error('generic embed: missing url');
-      assertHttpsEmbeddable(data.url);
-      if (!isGenericOriginAllowed(data.url)) {
-        throw new Error(
-          `generic embed: origin not allowlisted — call configureEmbedAllowlist([...]) to permit ${
-            originOf(data.url) ?? data.url
-          }`,
-        );
-      }
-      return { embedUrl: data.url, posterUrl: data.poster, sandbox: PLAYER_SANDBOX, allow: PLAYER_ALLOW };
-    }
-  }
-}
-
-/** Reject non-https or javascript:/data: player URLs (defense in depth). */
-function assertHttpsEmbeddable(url: string): void {
-  let protocol: string;
-  try {
-    protocol = new URL(url).protocol;
-  } catch {
-    throw new Error(`generic embed: invalid url "${url}"`);
-  }
-  if (protocol !== 'https:') {
-    throw new Error(`generic embed: only https player URLs are allowed (got ${protocol})`);
-  }
-}
-
-/**
- * The canonical "watch on the provider" URL for the optional fallback affordance
- * (emitted as `open`/target:'tab' when an embed is blocked). Returns `undefined`
- * when there is nothing useful to link to.
- */
-export function watchUrl(data: EmbedCardData): string | undefined {
-  switch (data.provider) {
-    case 'youtube': {
-      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
-      return id ? `https://www.youtube.com/watch?v=${id}` : data.url;
-    }
-    case 'vimeo': {
-      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
-      return id ? `https://vimeo.com/${id}` : data.url;
-    }
-    case 'generic':
-      return data.url;
-  }
-}
-
-/** Human-readable provider label for the fallback affordance ("Open on YouTube"). */
-export function providerLabel(provider: EmbedProvider): string {
-  switch (provider) {
-    case 'youtube':
-      return 'YouTube';
-    case 'vimeo':
-      return 'Vimeo';
-    case 'generic':
-      return 'site';
-  }
-}
-
-/** CSS aspect-ratio value for a card's aspectRatio (default 16:9). */
-export function aspectRatioValue(aspectRatio: EmbedCardData['aspectRatio']): string {
-  switch (aspectRatio) {
-    case '4:3':
-      return '4 / 3';
-    case '1:1':
-      return '1 / 1';
-    case '9:16':
-      return '9 / 16';
-    case '16:9':
-    default:
-      return '16 / 9';
-  }
-}