aeon-ui-engine 1.0.0

package/packages/react-scene/src/use-signal-visualizer.ts

@@ -0,0 +1,103 @@
+import { useEffect, useRef, useState } from 'react'
+import {
+  attachMediaAnalyser,
+  bandRanges,
+  createBarMotionState,
+  resumeAudioContext,
+  stepBarMotion,
+  type BarMotionOptions,
+} from '@aeon-ui/signal'
+
+export type UseSignalVisualizerOptions = BarMotionOptions & {
+  enabled?: boolean
+  barCount?: number
+  /** When set, attaches analyser to this element while active. */
+  media?: HTMLAudioElement | null
+  /** Use a pre-attached analyser (e.g. from `createDemoSignal`). */
+  analyser?: AnalyserNode | null
+  active?: boolean
+}
+
+/**
+ * RAF loop: frequency bands → per-bar scale + brightness (Soundbase-style motion).
+ */
+export function useSignalVisualizer(options: UseSignalVisualizerOptions = {}) {
+  const {
+    enabled = true,
+    barCount = 7,
+    media = null,
+    analyser: analyserProp = null,
+    active: activeProp,
+    ...motionOptions
+  } = options
+
+  const active = activeProp ?? (enabled && (!!analyserProp || !!media))
+  const [scales, setScales] = useState(() => createBarMotionState(barCount, motionOptions).scales)
+  const [brightness, setBrightness] = useState(
+    () => createBarMotionState(barCount, motionOptions).brightness,
+  )
+  const motionRef = useRef(createBarMotionState(barCount, motionOptions))
+  const rafRef = useRef<number | null>(null)
+  const dataRef = useRef<Uint8Array | null>(null)
+  const rangesRef = useRef<{ start: number; end: number }[]>([])
+
+  useEffect(() => {
+    motionRef.current = createBarMotionState(barCount, motionOptions)
+  }, [barCount])
+
+  useEffect(() => {
+    if (!active) {
+      motionRef.current = createBarMotionState(barCount, motionOptions)
+      setScales([...motionRef.current.scales])
+      setBrightness([...motionRef.current.brightness])
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current)
+        rafRef.current = null
+      }
+      return
+    }
+
+    void resumeAudioContext()
+
+    let analyser = analyserProp
+    if (!analyser && media) {
+      analyser = attachMediaAnalyser(media, { crossOrigin: 'anonymous' })
+    }
+
+    const bufferLength = analyser?.frequencyBinCount ?? 0
+    if (analyser && bufferLength > 0) {
+      dataRef.current = new Uint8Array(bufferLength)
+      rangesRef.current = bandRanges(bufferLength, barCount)
+    } else {
+      dataRef.current = null
+      rangesRef.current = []
+    }
+
+    const tick = () => {
+      if (analyser && dataRef.current) {
+        analyser.getByteFrequencyData(dataRef.current as Uint8Array<ArrayBuffer>)
+      }
+      stepBarMotion(
+        motionRef.current,
+        analyser,
+        dataRef.current,
+        rangesRef.current,
+        motionOptions,
+      )
+      setScales([...motionRef.current.scales])
+      setBrightness([...motionRef.current.brightness])
+      rafRef.current = requestAnimationFrame(tick)
+    }
+
+    rafRef.current = requestAnimationFrame(tick)
+
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current)
+        rafRef.current = null
+      }
+    }
+  }, [active, media, analyserProp, barCount])
+
+  return { scales, brightness, active }
+}

package/packages/react-scene/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/scene/README.md

@@ -0,0 +1,5 @@
+# @aeon-ui/scene
+
+Framework-agnostic CSS 3D scene helpers — perspective, `translate3d` / `rotateX|Y|Z` layers, wall clips.
+
+Used by `@aeon-ui/react-scene` (`SceneStage`, `SceneLayer`, `ScenePlane`). See [SCENE.md](../../SCENE.md).

package/packages/scene/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aeon-ui/scene",
+  "version": "0.1.0",
+  "description": "CSS 3D scene transforms and perspective helpers for Aeon Scene",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/scene"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "scene", "3d", "css", "transform"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/scene/src/index.ts

@@ -0,0 +1,2 @@
+export * from './transform.js'
+export * from './room.js'

package/packages/scene/src/room.ts

@@ -0,0 +1,40 @@
+import type { SceneUnit } from './transform.js'
+
+/** Width × height × depth of a box room (px). */
+export type SceneRoomSize = {
+  width: number
+  height: number
+  depth: number
+}
+
+export type SceneRoomCamera = {
+  /** Look-down angle on the whole room (degrees). */
+  pitch?: number
+  /** Turn the room (degrees). */
+  yaw?: number
+  /** Push room back from the viewer (px). */
+  offsetZ?: number
+  /** Vertical anchor of the room in the stage (0–100%). */
+  anchorY?: SceneUnit
+}
+
+/** CSS variables consumed by `.aeon-scene-room*` in scene-room.css */
+export function sceneRoomVars(
+  size: SceneRoomSize,
+  camera: SceneRoomCamera = {},
+): Record<string, string> {
+  const pitch = camera.pitch ?? 10
+  const yaw = camera.yaw ?? 0
+  const offsetZ = camera.offsetZ ?? -120
+  const anchorY = camera.anchorY ?? '46%'
+
+  return {
+    '--aeon-room-w': `${size.width}px`,
+    '--aeon-room-h': `${size.height}px`,
+    '--aeon-room-d': `${size.depth}px`,
+    '--aeon-room-pitch': `${pitch}deg`,
+    '--aeon-room-yaw': `${yaw}deg`,
+    '--aeon-room-offset-z': `${offsetZ}px`,
+    '--aeon-room-anchor-y': typeof anchorY === 'number' ? `${anchorY}px` : anchorY,
+  }
+}

package/packages/scene/src/transform.ts

@@ -0,0 +1,60 @@
+export type SceneUnit = number | `${number}%` | `${number}px` | `${number}rem` | `${number}vh` | `${number}vw`
+
+/** Layer transform in CSS 3D (degrees for rotation). */
+export type SceneTransform3d = {
+  x?: SceneUnit
+  y?: SceneUnit
+  z?: number
+  rotateX?: number
+  rotateY?: number
+  rotateZ?: number
+  scale?: number
+}
+
+export type ScenePerspective = {
+  distance?: number
+  origin?: string
+}
+
+export function formatSceneUnit(value: SceneUnit | undefined, fallback: string): string {
+  if (value === undefined) return fallback
+  if (typeof value === 'number') return `${value}px`
+  return value
+}
+
+/** Build `transform` + `transform-origin` for a scene layer. */
+export function sceneTransformStyle(
+  transform: SceneTransform3d,
+  options?: { origin?: string; preserve3d?: boolean },
+): Record<string, string> {
+  const x = formatSceneUnit(transform.x, '0')
+  const y = formatSceneUnit(transform.y, '0')
+  const z = transform.z ?? 0
+  const parts: string[] = [`translate3d(${x}, ${y}, ${z}px)`]
+
+  if (transform.rotateX) parts.push(`rotateX(${transform.rotateX}deg)`)
+  if (transform.rotateY) parts.push(`rotateY(${transform.rotateY}deg)`)
+  if (transform.rotateZ) parts.push(`rotateZ(${transform.rotateZ}deg)`)
+  if (transform.scale != null) parts.push(`scale(${transform.scale})`)
+
+  const style: Record<string, string> = { transform: parts.join(' ') }
+  if (options?.origin) style.transformOrigin = options.origin
+  if (options?.preserve3d !== false) style.transformStyle = 'preserve-3d'
+  return style
+}
+
+/** Perspective on a stage root (apply to the element that wraps all layers). */
+export function sceneStageStyle(perspective: ScenePerspective = {}): Record<string, string> {
+  return {
+    perspective: `${perspective.distance ?? 1100}px`,
+    perspectiveOrigin: perspective.origin ?? '50% 42%',
+    transformStyle: 'preserve-3d',
+  }
+}
+
+/** Wall trapezoid clip — left or right alley wall. */
+export function sceneWallClip(side: 'left' | 'right'): string {
+  return side === 'left'
+    ? 'polygon(0 100%, 0 5%, 78% 0, 100% 100%)'
+    : 'polygon(100% 100%, 100% 5%, 22% 0, 0 100%)'
+}

package/packages/scene/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/signal/README.md

@@ -0,0 +1,9 @@
+# @aeon-ui/signal
+
+Framework-agnostic audio analysis and bar motion smoothing for visualizers. Optional sibling to the control-plane packages — see [SCENE.md](../../SCENE.md).
+
+```ts
+import { attachMediaAnalyser, bandRanges, stepBarMotion, createBarMotionState } from '@aeon-ui/signal'
+```
+
+Pair with `@aeon-ui/react-scene` for React bindings, or drive canvas/SVG yourself from the motion state.

package/packages/signal/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aeon-ui/signal",
+  "version": "0.1.0",
+  "description": "Audio analyser tap and band motion math for Aeon Scene visualizers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/signal"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "audio", "visualizer", "analyser", "web-audio"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/signal/src/analyser.ts

@@ -0,0 +1,113 @@
+export type AttachAnalyserOptions = {
+  fftSize?: number
+  smoothingTimeConstant?: number
+  /** Set on the element before `src` when using remote audio (CORS). */
+  crossOrigin?: '' | 'anonymous' | 'use-credentials'
+}
+
+let sharedContext: AudioContext | null = null
+const graphs = new WeakMap<HTMLAudioElement, AnalyserNode>()
+const failed = new WeakSet<HTMLAudioElement>()
+
+function getContext(): AudioContext {
+  if (!sharedContext) {
+    sharedContext = new AudioContext()
+  }
+  return sharedContext
+}
+
+/** Tap an `<audio>` element for visualization without muting playback. */
+export function attachMediaAnalyser(
+  audio: HTMLAudioElement,
+  options?: AttachAnalyserOptions,
+): AnalyserNode | null {
+  if (failed.has(audio)) return null
+
+  const existing = graphs.get(audio)
+  if (existing) {
+    void sharedContext?.resume()
+    return existing
+  }
+
+  if (options?.crossOrigin !== undefined) {
+    audio.crossOrigin = options.crossOrigin
+  }
+
+  try {
+    const ctx = getContext()
+    const source = ctx.createMediaElementSource(audio)
+    const analyser = ctx.createAnalyser()
+    analyser.fftSize = options?.fftSize ?? 256
+    analyser.smoothingTimeConstant = options?.smoothingTimeConstant ?? 0.65
+
+    source.connect(analyser)
+    source.connect(ctx.destination)
+
+    graphs.set(audio, analyser)
+    void ctx.resume()
+    return analyser
+  } catch {
+    failed.add(audio)
+    return null
+  }
+}
+
+export function getMediaAnalyser(audio: HTMLAudioElement | null | undefined): AnalyserNode | null {
+  if (!audio) return null
+  return graphs.get(audio) ?? null
+}
+
+export async function resumeAudioContext(): Promise<void> {
+  if (sharedContext?.state === 'suspended') {
+    await sharedContext.resume()
+  }
+}
+
+export type DemoSignal = {
+  context: AudioContext
+  analyser: AnalyserNode
+  start: () => void
+  stop: () => void
+}
+
+/** Low-volume oscillator for demos and playgrounds (no media file). */
+export function createDemoSignal(options?: { frequency?: number; gain?: number }): DemoSignal {
+  const context = new AudioContext()
+  const oscillator = context.createOscillator()
+  oscillator.type = 'sawtooth'
+  oscillator.frequency.value = options?.frequency ?? 110
+
+  const gain = context.createGain()
+  gain.gain.value = options?.gain ?? 0.04
+
+  const analyser = context.createAnalyser()
+  analyser.fftSize = 256
+  analyser.smoothingTimeConstant = 0.65
+
+  oscillator.connect(gain)
+  gain.connect(analyser)
+  analyser.connect(context.destination)
+
+  let running = false
+
+  return {
+    context,
+    analyser,
+    start() {
+      if (running) return
+      oscillator.start()
+      running = true
+      void context.resume()
+    },
+    stop() {
+      if (!running) return
+      try {
+        oscillator.stop()
+      } catch {
+        /* already stopped */
+      }
+      running = false
+      void context.close()
+    },
+  }
+}

package/packages/signal/src/bands.ts

@@ -0,0 +1,33 @@
+export type BandRange = { start: number; end: number }
+
+/** Split FFT bins into `barCount` bands (low → high, skewed toward mids). */
+export function bandRanges(bufferLength: number, barCount: number): BandRange[] {
+  const ranges: BandRange[] = []
+  const minBin = 1
+  const maxBin = bufferLength - 1
+  const span = maxBin - minBin
+
+  for (let i = 0; i < barCount; i++) {
+    const t0 = i / barCount
+    const t1 = (i + 1) / barCount
+    const start = Math.floor(minBin + span * t0 ** 1.45)
+    const end = Math.max(start + 1, Math.floor(minBin + span * t1 ** 1.45))
+    ranges.push({ start, end })
+  }
+  return ranges
+}
+
+/** Average + peak blend for one frequency band (0–1). */
+export function bandLevel(data: Uint8Array, start: number, end: number): number {
+  let sum = 0
+  let peak = 0
+  for (let j = start; j < end; j++) {
+    const v = data[j]!
+    sum += v
+    if (v > peak) peak = v
+  }
+  const avg = sum / Math.max(1, end - start) / 255
+  const pk = peak / 255
+  const blended = avg * 0.55 + pk * 0.45
+  return Math.min(1, blended ** 0.72 * 1.35)
+}

package/packages/signal/src/index.ts

@@ -0,0 +1,3 @@
+export * from './bands.js'
+export * from './motion.js'
+export * from './analyser.js'

package/packages/signal/src/motion.ts

@@ -0,0 +1,80 @@
+import { bandLevel } from './bands.js'
+
+export type BarMotionState = {
+  scales: number[]
+  brightness: number[]
+}
+
+export type BarMotionOptions = {
+  barCount?: number
+  idleScale?: number
+  minScale?: number
+  maxScale?: number
+  idleBrightness?: number
+  minBrightness?: number
+  maxBrightness?: number
+  attack?: number
+  decay?: number
+}
+
+const DEFAULTS = {
+  idleScale: 1,
+  minScale: 0.75,
+  maxScale: 1.25,
+  idleBrightness: 1,
+  minBrightness: 0.5,
+  maxBrightness: 1.5,
+  attack: 0.42,
+  decay: 0.14,
+} as const
+
+export function createBarMotionState(barCount: number, options?: BarMotionOptions): BarMotionState {
+  const idleScale = options?.idleScale ?? DEFAULTS.idleScale
+  const idleBrightness = options?.idleBrightness ?? DEFAULTS.idleBrightness
+  return {
+    scales: Array.from({ length: barCount }, () => idleScale),
+    brightness: Array.from({ length: barCount }, () => idleBrightness),
+  }
+}
+
+function mapLevel(avg: number, min: number, max: number) {
+  return min + avg * (max - min)
+}
+
+function smoothToward(current: number, target: number, attack: number, decay: number) {
+  const rate = target > current ? attack : decay
+  return current + (target - current) * rate
+}
+
+/** Advance one animation frame from frequency data (or decay toward idle). */
+export function stepBarMotion(
+  state: BarMotionState,
+  analyser: AnalyserNode | null,
+  data: Uint8Array | null,
+  ranges: { start: number; end: number }[],
+  options?: BarMotionOptions,
+): void {
+  const idleScale = options?.idleScale ?? DEFAULTS.idleScale
+  const minScale = options?.minScale ?? DEFAULTS.minScale
+  const maxScale = options?.maxScale ?? DEFAULTS.maxScale
+  const idleBrightness = options?.idleBrightness ?? DEFAULTS.idleBrightness
+  const minBrightness = options?.minBrightness ?? DEFAULTS.minBrightness
+  const maxBrightness = options?.maxBrightness ?? DEFAULTS.maxBrightness
+  const attack = options?.attack ?? DEFAULTS.attack
+  const decay = options?.decay ?? DEFAULTS.decay
+  const barCount = state.scales.length
+
+  for (let i = 0; i < barCount; i++) {
+    if (analyser && data) {
+      const { start, end } = ranges[i] ?? { start: 0, end: 1 }
+      const level = bandLevel(data, start, end)
+      const scaleTarget = mapLevel(level, minScale, maxScale)
+      const brightTarget = mapLevel(level, minBrightness, maxBrightness)
+      state.scales[i] = smoothToward(state.scales[i]!, scaleTarget, attack, decay)
+      state.brightness[i] = smoothToward(state.brightness[i]!, brightTarget, attack, decay)
+    } else {
+      state.scales[i] = smoothToward(state.scales[i]!, idleScale, 0.12, 0.12)
+      state.brightness[i] = smoothToward(state.brightness[i]!, idleBrightness, 0.12, 0.12)
+    }
+  }
+}

package/packages/signal/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/packages/site/README.md

@@ -0,0 +1,19 @@
+# @aeon-ui/site
+
+Small helpers for **link previews** (Open Graph + Twitter Card meta tags).
+
+```ts
+import { absoluteUrl, openGraphHeadHtml } from '@aeon-ui/site'
+
+const html = openGraphHeadHtml({
+  title: 'Aeon UI — Future-proof UI infrastructure',
+  description: 'Statechart-driven primitives and a styled layer your team controls.',
+  url: absoluteUrl('https://aeon-ui.com', '/'),
+  image: absoluteUrl('https://aeon-ui.com', '/og.png'),
+  siteName: 'Aeon UI',
+})
+```
+
+Use in a Vite `transformIndexHtml` hook or any static site generator. Pair with a **1200×630** `og.png` in `public/`.
+
+Not required for component consumers — optional for docs and marketing apps in the monorepo.

package/packages/site/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aeon-ui/site",
+  "version": "0.1.0",
+  "description": "Open Graph and document meta helpers for Aeon marketing sites",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/site"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md"],
+  "keywords": ["aeon-ui", "open-graph", "meta", "seo"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/site/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  absoluteUrl,
+  openGraphHeadHtml,
+  openGraphTags,
+  renderMetaTag,
+  type MetaTag,
+  type OpenGraphConfig,
+} from './open-graph.js'