@refraction-ui/astro 0.5.0 → 0.6.0

package/dist/shared/library-origin-error.ts

@@ -0,0 +1,240 @@
+/**
+ * library-origin-error — builds the **library-origin error envelope** for
+ * errors that originate inside a `@refraction-ui/*` package.
+ *
+ * The envelope is expressed THROUGH the existing telemetry record contract
+ * (`@refraction-ui/logger`'s `LogRecord`) — the contract is reused, NOT
+ * redefined. To keep `@refraction-ui/shared` zero-dependency, the record is
+ * mirrored structurally (see {@link DevFeedbackRecord}) rather than imported;
+ * a consumer wiring the real logger sink satisfies it structurally.
+ *
+ * Aggressive redaction (epic #247 guardrails): the payload is package,
+ * componentName, version, a normalized stack **fingerprint hash**, and
+ * framework only. Never app state, props values, user data, PII, or full app
+ * stack frames.
+ */
+
+import type { DevFeedbackRecord, DevFeedbackSink } from './dev-feedback.js'
+
+/** Matches any stack frame that references a `@refraction-ui/*` package. */
+const REFRACTION_FRAME = /@refraction-ui\//
+
+/** Frameworks a refraction-ui adapter can run under. */
+export type LibraryFramework =
+  | 'react'
+  | 'angular'
+  | 'astro'
+  | 'vue'
+  | 'svelte'
+  | 'vanilla'
+  | 'unknown'
+
+/** Inputs describing where a library-origin error came from. */
+export interface LibraryOriginErrorInput {
+  /** Originating package, e.g. `@refraction-ui/react`. */
+  package: string
+  /** refraction-ui component the error originated in, e.g. `Dialog`. */
+  componentName: string
+  /** Originating package version, e.g. `0.1.5`. */
+  version: string
+  /** Host framework the component was running under. */
+  framework: LibraryFramework
+  /** The thrown error (or its stack string). Used ONLY to derive a hash. */
+  error?: unknown
+}
+
+/**
+ * The redacted, library-origin payload carried in `LogRecord.context`. Contains
+ * NO app data — only the five identifying fields plus a stack fingerprint hash.
+ */
+export interface LibraryOriginEnvelope {
+  /** Marks this record as a library-origin error (for downstream routing). */
+  origin: 'refraction-ui'
+  package: string
+  componentName: string
+  version: string
+  framework: LibraryFramework
+  /** Stable, app-data-free hash of the normalized stack. */
+  fingerprint: string
+}
+
+/**
+ * Normalize a stack trace into a deterministic, app-data-free string before
+ * hashing:
+ * - keep only frames that reference a `@refraction-ui/*` package (drop the
+ *   app's own frames — library-origin only),
+ * - strip absolute paths, line/column numbers, query strings, and hashes,
+ * - sort-free (preserve call order) but whitespace-collapsed.
+ *
+ * If no refraction-ui frames are present the function returns an empty string,
+ * which yields a stable "no-frames" fingerprint rather than leaking app frames.
+ */
+function normalizeStack(stack: string): string {
+  const frames = stack
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('at ') || line.includes('@'))
+    .filter((line) => REFRACTION_FRAME.test(line))
+    .map((line) =>
+      line
+        // drop everything from the path/url onward, keep the symbol
+        .replace(/\((?:.*?)(@refraction-ui\/[^):]+)[^)]*\)/, '($1)')
+        .replace(/(@refraction-ui\/[^\s:?#]+)[^\s)]*/g, '$1')
+        // strip :line:col
+        .replace(/:\d+:\d+/g, '')
+        // strip line:col without colon prefix
+        .replace(/:\d+\b/g, '')
+        // strip query/hash
+        .replace(/[?#][^\s)]*/g, '')
+        .replace(/\s+/g, ' ')
+        .trim(),
+    )
+
+  return frames.join('\n')
+}
+
+/**
+ * Deterministic, dependency-free 53-bit string hash (cyrb53). Stable across
+ * runs and processes for the same input — required so the intake can dedupe by
+ * fingerprint. NOT cryptographic; it only needs to be collision-resistant
+ * enough to group identical normalized stacks.
+ */
+function cyrb53(str: string, seed = 0): string {
+  let h1 = 0xdeadbeef ^ seed
+  let h2 = 0x41c6ce57 ^ seed
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i)
+    h1 = Math.imul(h1 ^ ch, 2654435761)
+    h2 = Math.imul(h2 ^ ch, 1597334677)
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507)
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909)
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507)
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909)
+  const out = 4294967296 * (2097151 & h2) + (h1 >>> 0)
+  return out.toString(16).padStart(14, '0')
+}
+
+function stackOf(error: unknown): string {
+  if (typeof error === 'string') return error
+  if (
+    error &&
+    typeof error === 'object' &&
+    'stack' in error &&
+    typeof (error as { stack?: unknown }).stack === 'string'
+  ) {
+    return (error as { stack: string }).stack
+  }
+  return ''
+}
+
+/**
+ * Compute the stable stack fingerprint for a library-origin error. Exposed
+ * separately so capture seams / tests can assert fingerprint stability without
+ * building the whole record.
+ */
+export function stackFingerprint(error: unknown): string {
+  const normalized = normalizeStack(stackOf(error))
+  return cyrb53(normalized)
+}
+
+/**
+ * Build the redacted library-origin envelope for an error.
+ */
+export function libraryOriginEnvelope(
+  input: LibraryOriginErrorInput,
+): LibraryOriginEnvelope {
+  return {
+    origin: 'refraction-ui',
+    package: input.package,
+    componentName: input.componentName,
+    version: input.version,
+    framework: input.framework,
+    fingerprint: stackFingerprint(input.error),
+  }
+}
+
+/**
+ * Build the full library-origin error record, expressed THROUGH the existing
+ * telemetry record contract (`LogRecord`, mirrored as {@link DevFeedbackRecord}
+ * to avoid a hard logger dependency). The redacted envelope rides in
+ * `context`; no app data, props, PII, or app stack frames are included.
+ *
+ * This record is exactly what a consumer-wired telemetry sink (or the
+ * `devWarn`/`devError` injected sink) consumes.
+ */
+export function libraryOriginError(
+  input: LibraryOriginErrorInput,
+): DevFeedbackRecord {
+  const envelope = libraryOriginEnvelope(input)
+  return {
+    level: 'error',
+    message: `${input.package}/${input.componentName}: library-origin error`,
+    timestamp: Date.now(),
+    context: { ...envelope },
+  }
+}
+
+/**
+ * Library-origin predicate — `true` iff the error's stack contains at least
+ * one frame that references a `@refraction-ui/*` package. This is the gate
+ * every per-framework capture seam uses: only library-origin errors are
+ * eligible; the app's own errors return `false` and pass through untouched.
+ *
+ * Mirrors exactly the frame-detection rule {@link stackFingerprint} normalizes
+ * by — no new contract, just the companion predicate the seams need. Never
+ * throws for a missing/odd error (returns `false`).
+ */
+export function isLibraryOriginError(error: unknown): boolean {
+  const stack = stackOf(error)
+  if (!stack) return false
+  return REFRACTION_FRAME.test(stack)
+}
+
+/**
+ * The fixed identity of the refraction-ui package/component a seam tags an
+ * error with. The seam supplies this; the stack itself supplies the
+ * fingerprint. Never carries app data.
+ */
+export type LibraryOriginIdentity = Pick<
+  LibraryOriginErrorInput,
+  'package' | 'componentName' | 'version' | 'framework'
+>
+
+/**
+ * The single capture primitive shared by every per-framework seam (React error
+ * boundary, Angular `ErrorHandler`, Astro middleware). It performs the entire
+ * guarded flow in one place so the seams stay thin and identical in behavior:
+ *
+ *  1. **Library-origin filter** — if the error's stack has no
+ *     `@refraction-ui/*` frame it is the app's own error: return `null` and do
+ *     NOT touch, capture, or forward it.
+ *  2. **Tag** — build the redacted {@link libraryOriginError} record
+ *     (package/componentName/version/framework + app-data-free fingerprint).
+ *  3. **Route to the optional sink** — forward the record to the
+ *     consumer-injected sink ONLY if one was wired; a broken sink can never
+ *     break the consumer app. With no sink this is a no-op beyond returning
+ *     the record (so a seam can still surface it locally).
+ *
+ * @returns the tagged record for a library-origin error, or `null` when the
+ *          error is app-origin (the "pass through untouched" signal).
+ */
+export function captureLibraryOriginError(
+  error: unknown,
+  identity: LibraryOriginIdentity,
+  sink: DevFeedbackSink | null | undefined,
+): DevFeedbackRecord | null {
+  if (!isLibraryOriginError(error)) return null
+
+  const record = libraryOriginError({ ...identity, error })
+
+  if (sink) {
+    try {
+      sink.log(record)
+    } catch {
+      // A broken sink must never break the consumer app.
+    }
+  }
+
+  return record
+}

package/dist/voice-pill/voice-pill.styles.ts

@@ -22,33 +22,34 @@ export const voicePillSpeakerStyles =
   '[--rfr-voice-pill-accent:hsl(var(--primary))] [--rfr-voice-pill-accent-foreground:hsl(var(--primary-foreground))] data-[speaker=user]:[--rfr-voice-pill-accent:hsl(var(--accent-foreground))] data-[speaker=user]:[--rfr-voice-pill-accent-foreground:hsl(var(--accent))] data-[muted=true]:[--rfr-voice-pill-accent:hsl(var(--muted-foreground))]'
 
 export const voicePillPositionVariants = cva({
-  base: 'fixed z-50',
+  base: 'z-50',
   variants: {
     position: {
+      inline: 'relative',
       'top-start':
-        'top-[calc(env(safe-area-inset-top)+1rem)] left-[calc(env(safe-area-inset-left)+1rem)]',
+        'fixed top-[calc(env(safe-area-inset-top)+1rem)] left-[calc(env(safe-area-inset-left)+1rem)]',
       'top-center':
-        'top-[calc(env(safe-area-inset-top)+1rem)] left-1/2 -translate-x-1/2',
+        'fixed top-[calc(env(safe-area-inset-top)+1rem)] left-1/2 -translate-x-1/2',
       'top-end':
-        'top-[calc(env(safe-area-inset-top)+1rem)] right-[calc(env(safe-area-inset-right)+1rem)]',
+        'fixed top-[calc(env(safe-area-inset-top)+1rem)] right-[calc(env(safe-area-inset-right)+1rem)]',
       'bottom-start':
-        'bottom-[calc(env(safe-area-inset-bottom)+1rem)] left-[calc(env(safe-area-inset-left)+1rem)]',
+        'fixed bottom-[calc(env(safe-area-inset-bottom)+1rem)] left-[calc(env(safe-area-inset-left)+1rem)]',
       'bottom-center':
-        'bottom-[calc(env(safe-area-inset-bottom)+1rem)] left-1/2 -translate-x-1/2',
+        'fixed bottom-[calc(env(safe-area-inset-bottom)+1rem)] left-1/2 -translate-x-1/2',
       'bottom-end':
-        'bottom-[calc(env(safe-area-inset-bottom)+1rem)] right-[calc(env(safe-area-inset-right)+1rem)]',
+        'fixed bottom-[calc(env(safe-area-inset-bottom)+1rem)] right-[calc(env(safe-area-inset-right)+1rem)]',
       'left-start':
-        'left-[calc(env(safe-area-inset-left)+1rem)] top-[calc(env(safe-area-inset-top)+1rem)]',
+        'fixed left-[calc(env(safe-area-inset-left)+1rem)] top-[calc(env(safe-area-inset-top)+1rem)]',
       'left-center':
-        'left-[calc(env(safe-area-inset-left)+1rem)] top-1/2 -translate-y-1/2',
+        'fixed left-[calc(env(safe-area-inset-left)+1rem)] top-1/2 -translate-y-1/2',
       'left-end':
-        'left-[calc(env(safe-area-inset-left)+1rem)] bottom-[calc(env(safe-area-inset-bottom)+1rem)]',
+        'fixed left-[calc(env(safe-area-inset-left)+1rem)] bottom-[calc(env(safe-area-inset-bottom)+1rem)]',
       'right-start':
-        'right-[calc(env(safe-area-inset-right)+1rem)] top-[calc(env(safe-area-inset-top)+1rem)]',
+        'fixed right-[calc(env(safe-area-inset-right)+1rem)] top-[calc(env(safe-area-inset-top)+1rem)]',
       'right-center':
-        'right-[calc(env(safe-area-inset-right)+1rem)] top-1/2 -translate-y-1/2',
+        'fixed right-[calc(env(safe-area-inset-right)+1rem)] top-1/2 -translate-y-1/2',
       'right-end':
-        'right-[calc(env(safe-area-inset-right)+1rem)] bottom-[calc(env(safe-area-inset-bottom)+1rem)]',
+        'fixed right-[calc(env(safe-area-inset-right)+1rem)] bottom-[calc(env(safe-area-inset-bottom)+1rem)]',
     },
   },
   defaultVariants: {

package/dist/voice-pill/voice-pill.ts

@@ -3,6 +3,7 @@ import type { AccessibilityProps } from '../shared/index.ts'
 export type VoicePillSpeaker = 'ai' | 'user' | (string & {})
 
 export type VoicePillPosition =
+  | 'inline'
   | 'top-start'
   | 'top-center'
   | 'top-end'
@@ -29,7 +30,7 @@ export interface VoicePillProps {
   muted?: boolean
   /** Callback for the optional mute toggle */
   onToggleMute?: () => void
-  /** Fixed viewport position */
+  /** Viewport position, or inline for embedding inside another layout */
   position?: VoicePillPosition
 }
 
@@ -52,7 +53,7 @@ export interface VoicePillAPI {
   visualIntensity: number
   /** Muted state */
   muted: boolean
-  /** Fixed viewport position */
+  /** Viewport position, or inline for embedding inside another layout */
   position: VoicePillPosition
   /** Fallback initials for the speaker avatar */
   initials: string

package/dist/waveform/waveform-renderer.ts

@@ -1,7 +1,9 @@
 import {
   DEFAULT_WAVEFORM_COLOR,
+  DEFAULT_WAVEFORM_AMPLITUDE,
   DEFAULT_WAVEFORM_INTENSITY,
   getWaveformPeak,
+  normalizeAmplitude,
   normalizeBarCount,
   normalizeIntensity,
   resampleWaveformSamples,
@@ -20,6 +22,7 @@ export interface WaveformRenderOptions {
   variant?: WaveformVariant
   color?: string
   intensity?: number
+  amplitude?: number
   barCount?: number
 }
 
@@ -60,22 +63,23 @@ export function drawWaveform(
   const variant = options.variant ?? 'bars'
   const color = options.color ?? DEFAULT_WAVEFORM_COLOR
   const intensity = normalizeIntensity(options.intensity ?? DEFAULT_WAVEFORM_INTENSITY)
+  const amplitude = normalizeAmplitude(options.amplitude ?? DEFAULT_WAVEFORM_AMPLITUDE)
   const barCount = normalizeBarCount(options.barCount)
 
   context.clearRect(0, 0, width, height)
   applyCanvasColor(context, color)
 
   if (variant === 'line') {
-    drawLine(context, samples, width, height, intensity)
+    drawLine(context, samples, width, height, intensity, amplitude)
     return
   }
 
   if (variant === 'rings') {
-    drawRings(context, samples, width, height, intensity)
+    drawRings(context, samples, width, height, intensity, amplitude)
     return
   }
 
-  drawBars(context, samples, width, height, intensity, barCount)
+  drawBars(context, samples, width, height, intensity, amplitude, barCount)
 }
 
 function drawBars(
@@ -84,6 +88,7 @@ function drawBars(
   width: number,
   height: number,
   intensity: number,
+  amplitude: number,
   barCount: number,
 ) {
   const bars = scaleWaveformSamples(resampleWaveformSamples(samples, barCount), intensity)
@@ -93,7 +98,7 @@ function drawBars(
 
   for (let i = 0; i < bars.length; i += 1) {
     const value = Math.abs(bars[i])
-    const barHeight = Math.max(value * height, value > 0 ? 1 : 0)
+    const barHeight = Math.max(value * height * amplitude, value > 0 ? 1 : 0)
     const x = i * slotWidth + (slotWidth - barWidth) / 2
     const y = center - barHeight / 2
 
@@ -107,10 +112,11 @@ function drawLine(
   width: number,
   height: number,
   intensity: number,
+  amplitudeScale: number,
 ) {
   const lineSamples = scaleWaveformSamples(samples, intensity)
   const center = height / 2
-  const amplitude = height * 0.45
+  const amplitude = height * 0.45 * amplitudeScale
 
   context.beginPath()
 
@@ -137,8 +143,9 @@ function drawRings(
   width: number,
   height: number,
   intensity: number,
+  amplitude: number,
 ) {
-  const peak = getWaveformPeak(scaleWaveformSamples(samples, intensity))
+  const peak = getWaveformPeak(scaleWaveformSamples(samples, intensity)) * amplitude
   const minDimension = Math.min(width, height)
   const centerX = width / 2
   const centerY = height / 2

package/dist/waveform/waveform.ts

@@ -8,6 +8,7 @@ export interface WaveformProps {
   source?: WaveformSource
   samples?: WaveformSampleInput
   intensity?: number
+  amplitude?: number
   variant?: WaveformVariant
   height?: number | string
   width?: number | string
@@ -20,6 +21,7 @@ export interface WaveformProps {
 export interface NormalizedWaveformConfig {
   variant: WaveformVariant
   intensity: number
+  amplitude: number
   height: number | string
   width: number | string
   barCount: number
@@ -40,6 +42,7 @@ export const DEFAULT_WAVEFORM_BAR_COUNT = 48
 export const DEFAULT_WAVEFORM_COLOR = 'var(--accent-2)'
 export const DEFAULT_WAVEFORM_HEIGHT = 80
 export const DEFAULT_WAVEFORM_INTENSITY = 1
+export const DEFAULT_WAVEFORM_AMPLITUDE = 1
 export const DEFAULT_WAVEFORM_SMOOTHING = 0.8
 
 const MAX_BAR_COUNT = 1024
@@ -63,10 +66,17 @@ export function normalizeIntensity(value: number | undefined): number {
   return Math.min(MAX_INTENSITY, Math.max(0, value))
 }
 
+export function normalizeAmplitude(value: number | undefined): number {
+  if (value == null || !Number.isFinite(value)) return DEFAULT_WAVEFORM_AMPLITUDE
+
+  return Math.min(1, Math.max(0, value))
+}
+
 export function normalizeWaveformConfig(props: WaveformProps = {}): NormalizedWaveformConfig {
   return {
     variant: props.variant ?? 'bars',
     intensity: normalizeIntensity(props.intensity),
+    amplitude: normalizeAmplitude(props.amplitude),
     height: props.height ?? DEFAULT_WAVEFORM_HEIGHT,
     width: props.width ?? '100%',
     barCount: normalizeBarCount(props.barCount),
@@ -87,6 +97,7 @@ export function createSilentSamples(count = DEFAULT_WAVEFORM_BAR_COUNT): Float32
 export function createIntensitySamples(
   intensity = DEFAULT_WAVEFORM_INTENSITY,
   count = DEFAULT_WAVEFORM_BAR_COUNT,
+  phase = 0,
 ): Float32Array {
   const normalizedIntensity = normalizeIntensity(intensity)
   const normalizedCount = normalizeBarCount(count)
@@ -94,11 +105,13 @@ export function createIntensitySamples(
 
   if (normalizedIntensity === 0) return samples
 
+  const pulse = 0.72 + Math.sin(phase * 1.8) * 0.18
+
   for (let i = 0; i < normalizedCount; i += 1) {
     const progress = normalizedCount <= 1 ? 0.5 : i / (normalizedCount - 1)
     const envelope = 0.35 + Math.sin(progress * Math.PI) * 0.65
-    const carrier = Math.sin(progress * Math.PI * 6)
-    samples[i] = carrier * envelope * normalizedIntensity
+    const carrier = Math.sin(progress * Math.PI * 6 + phase * 2.8)
+    samples[i] = carrier * envelope * normalizedIntensity * pulse
   }
 
   return samples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refraction-ui/astro",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "All Refraction UI Astro components in one package",
   "type": "module",
   "exports": {
@@ -93,7 +93,9 @@
     "@refraction-ui/astro-link-card": "workspace:*",
     "@refraction-ui/astro-card-grid": "workspace:*",
     "@refraction-ui/astro-payment": "workspace:*",
-    "@refraction-ui/astro-command-input": "workspace:*"
+    "@refraction-ui/astro-command-input": "workspace:*",
+    "@refraction-ui/astro-logger": "workspace:*",
+    "@refraction-ui/astro-analytics": "workspace:*"
   },
   "publishConfig": {
     "access": "public"