aeon-ui-engine 1.0.0

package/packages/react-scene/README.md

@@ -0,0 +1,11 @@
+# @aeon-ui/react-scene
+
+Optional React layer for ambient visuals — pair with `@aeon-ui/signal`, `@aeon-ui/geometry`, and `@aeon-ui/surface`.
+
+```tsx
+import { SceneRoot, ProceduralGrid, SignalBars, SceneStage, SceneLayer, ScenePlane } from '@aeon-ui/react-scene'
+import '@aeon-ui/surface/surface.css'
+import '@aeon-ui/react-scene/scene-3d.css'
+```
+
+See [SCENE.md](../../SCENE.md).

package/packages/react-scene/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@aeon-ui/react-scene",
+  "version": "0.1.0",
+  "description": "React bindings for Aeon Scene — visualizers, backdrops, textures",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/react-scene"
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "scene-3d.css", "README.md"],
+  "keywords": ["aeon-ui", "react", "visualizer", "background", "scene"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./scene-3d.css": "./scene-3d.css"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external react --external react-dom --external @aeon-ui/geometry --external @aeon-ui/signal --external @aeon-ui/surface --external @aeon-ui/scene",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aeon-ui/geometry": "workspace:*",
+    "@aeon-ui/scene": "workspace:*",
+    "@aeon-ui/signal": "workspace:*",
+    "@aeon-ui/surface": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/packages/react-scene/scene-3d.css

@@ -0,0 +1,37 @@
+/* Optional — import when using SceneStage / SceneLayer / ScenePlane / SceneRoom */
+@import './scene-room.css';
+
+.aeon-scene-stage {
+  position: relative;
+  overflow: hidden;
+  transform-style: preserve-3d;
+}
+
+.aeon-scene-layer {
+  position: absolute;
+  inset: 0;
+  transform-style: preserve-3d;
+  pointer-events: none;
+}
+
+.aeon-scene-plane {
+  position: absolute;
+  transform-style: preserve-3d;
+  background-repeat: no-repeat;
+  background-size: cover;
+  background-position: center;
+}
+
+.aeon-scene-plane--fill {
+  inset: 0;
+}
+
+.aeon-scene-slot {
+  position: absolute;
+  transform-style: preserve-3d;
+  pointer-events: auto;
+}
+
+.aeon-scene-slot--fill {
+  inset: 0;
+}

package/packages/react-scene/scene-room.css

@@ -0,0 +1,95 @@
+/* Box room — use with SceneRoom; requires .aeon-scene-stage perspective */
+
+.aeon-scene-room-wrap {
+  position: absolute;
+  left: 50%;
+  top: var(--aeon-room-anchor-y, 46%);
+  transform-style: preserve-3d;
+  transform: translate3d(-50%, -50%, var(--aeon-room-offset-z, -120px))
+    rotateX(var(--aeon-room-pitch, 10deg)) rotateY(var(--aeon-room-yaw, 0deg));
+  pointer-events: none;
+}
+
+.aeon-scene-room {
+  position: relative;
+  width: var(--aeon-room-w);
+  height: var(--aeon-room-h);
+  transform-style: preserve-3d;
+}
+
+.aeon-scene-room__face {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform-style: preserve-3d;
+  backface-visibility: hidden;
+  -webkit-backface-visibility: hidden;
+}
+
+.aeon-scene-room__back {
+  width: var(--aeon-room-w);
+  height: var(--aeon-room-h);
+  margin: calc(var(--aeon-room-h) / -2) 0 0 calc(var(--aeon-room-w) / -2);
+  transform: translate3d(0, 0, calc(var(--aeon-room-d) / -2));
+}
+
+.aeon-scene-room__left {
+  width: var(--aeon-room-d);
+  height: var(--aeon-room-h);
+  margin: calc(var(--aeon-room-h) / -2) 0 0 calc(var(--aeon-room-d) / -2);
+  transform: rotateY(-90deg) translate3d(calc(var(--aeon-room-w) / -2), 0, 0);
+  transform-origin: right center;
+}
+
+.aeon-scene-room__right {
+  width: var(--aeon-room-d);
+  height: var(--aeon-room-h);
+  margin: calc(var(--aeon-room-h) / -2) 0 0 calc(var(--aeon-room-d) / -2);
+  transform: rotateY(90deg) translate3d(calc(var(--aeon-room-w) / 2), 0, 0);
+  transform-origin: left center;
+}
+
+.aeon-scene-room__floor {
+  width: var(--aeon-room-w);
+  height: var(--aeon-room-d);
+  margin: calc(var(--aeon-room-d) / -2) 0 0 calc(var(--aeon-room-w) / -2);
+  transform: rotateX(90deg) translate3d(0, calc(var(--aeon-room-h) / 2), 0);
+  transform-origin: center top;
+}
+
+.aeon-scene-room__floor-plane {
+  inset: 0;
+}
+
+.aeon-scene-room__ceiling {
+  width: var(--aeon-room-w);
+  height: var(--aeon-room-d);
+  margin: calc(var(--aeon-room-d) / -2) 0 0 calc(var(--aeon-room-w) / -2);
+  transform: rotateX(-90deg) translate3d(0, calc(var(--aeon-room-h) / -2), 0);
+  transform-origin: center bottom;
+  background: linear-gradient(180deg, #0a0908 0%, #1e1a16 55%, #2a2520 100%);
+}
+
+/* UI on the floor: counter-rotate so controls face the camera */
+.aeon-scene-room__floor-slot {
+  position: absolute;
+  inset: 10% 6% 14% 6%;
+  transform: rotateX(-90deg) translateZ(10px);
+  transform-origin: center center;
+  transform-style: preserve-3d;
+  pointer-events: auto;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0.75rem;
+}
+
+.aeon-scene-room__vignette {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  background:
+    radial-gradient(ellipse 90% 70% at 50% 55%, transparent 35%, rgba(0, 0, 0, 0.55) 100%),
+    linear-gradient(180deg, rgba(0, 0, 0, 0.35) 0%, transparent 22%, transparent 72%, rgba(0, 0, 0, 0.5) 100%);
+  z-index: 0;
+}

package/packages/react-scene/src/index.ts

@@ -0,0 +1,20 @@
+export { SceneRoot, SceneBackdrop } from './scene-root.js'
+export { ProceduralGrid } from './procedural-grid.js'
+export { SceneSurface } from './scene-surface.js'
+export { SignalBars } from './signal-bars.js'
+export { useSignalVisualizer } from './use-signal-visualizer.js'
+export { SceneStage } from './scene-stage.js'
+export { SceneLayer } from './scene-layer.js'
+export { ScenePlane } from './scene-plane.js'
+export { SceneSlot } from './scene-slot.js'
+export { SceneRoom } from './scene-room.js'
+export type { SceneRootProps, SceneBackdropProps } from './scene-root.js'
+export type { ProceduralGridProps } from './procedural-grid.js'
+export type { SceneSurfaceProps } from './scene-surface.js'
+export type { SignalBarsProps } from './signal-bars.js'
+export type { UseSignalVisualizerOptions } from './use-signal-visualizer.js'
+export type { SceneStageProps } from './scene-stage.js'
+export type { SceneLayerProps } from './scene-layer.js'
+export type { ScenePlaneProps } from './scene-plane.js'
+export type { SceneSlotProps } from './scene-slot.js'
+export type { SceneRoomProps } from './scene-room.js'

package/packages/react-scene/src/procedural-grid.tsx

@@ -0,0 +1,35 @@
+import type { CSSProperties, HTMLAttributes } from 'react'
+import { gridPatternStyle, vignetteStyle, sceneAttrs } from '@aeon-ui/geometry'
+
+export type ProceduralGridProps = HTMLAttributes<HTMLDivElement> & {
+  cell?: number
+  lineColor?: string
+  vignette?: boolean
+}
+
+/** Layered grid lines + optional vignette for page/scene backgrounds. */
+export function ProceduralGrid({
+  cell,
+  lineColor,
+  vignette = true,
+  className,
+  style,
+  ...rest
+}: ProceduralGridProps) {
+  const grid = gridPatternStyle({ cell, lineColor })
+  const merged: CSSProperties = {
+    position: 'absolute',
+    inset: 0,
+    pointerEvents: 'none',
+    ...grid,
+    ...style,
+  }
+
+  return (
+    <div {...rest} {...sceneAttrs('grid')} className={className} style={merged} aria-hidden>
+      {vignette ? (
+        <div style={{ position: 'absolute', inset: 0, ...vignetteStyle() }} aria-hidden />
+      ) : null}
+    </div>
+  )
+}

package/packages/react-scene/src/scene-layer.tsx

@@ -0,0 +1,38 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { sceneAttrs } from '@aeon-ui/geometry'
+import { sceneTransformStyle, type SceneTransform3d } from '@aeon-ui/scene'
+
+export type SceneLayerProps = HTMLAttributes<HTMLDivElement> & {
+  part?: string
+  transform?: SceneTransform3d
+  origin?: string
+  children?: ReactNode
+}
+
+/** Positioned 3D layer inside a `SceneStage` (absolute fill + transform). */
+export function SceneLayer({
+  part = 'layer',
+  transform,
+  origin = '50% 50%',
+  className,
+  style,
+  children,
+  ...rest
+}: SceneLayerProps) {
+  const merged: CSSProperties = {
+    ...(transform ? sceneTransformStyle(transform, { origin }) : { transformStyle: 'preserve-3d' }),
+    ...style,
+  }
+
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs(part)}
+      className={['aeon-scene-layer', className].filter(Boolean).join(' ')}
+      style={merged}
+      aria-hidden={rest['aria-hidden'] ?? true}
+    >
+      {children}
+    </div>
+  )
+}

package/packages/react-scene/src/scene-plane.tsx

@@ -0,0 +1,69 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { sceneAttrs } from '@aeon-ui/geometry'
+import { sceneTransformStyle, sceneWallClip, type SceneTransform3d } from '@aeon-ui/scene'
+import { surfaceClass, type SurfaceMaterial } from '@aeon-ui/surface'
+
+export type ScenePlaneProps = HTMLAttributes<HTMLDivElement> & {
+  part?: string
+  /** Extra transform on this plane (in addition to parent `SceneLayer`). */
+  transform?: SceneTransform3d
+  origin?: string
+  /** Cover the parent layer (`inset: 0`). Default true. */
+  fill?: boolean
+  texture?: string
+  material?: SurfaceMaterial
+  /** Left or right wall trapezoid clip. */
+  wall?: 'left' | 'right'
+  children?: ReactNode
+}
+
+/** Textured or material-filled plane in 3D space — ground, wall, backdrop, UI mount. */
+export function ScenePlane({
+  part = 'plane',
+  transform,
+  origin = '50% 50%',
+  fill = true,
+  texture,
+  material,
+  wall,
+  className,
+  style,
+  children,
+  ...rest
+}: ScenePlaneProps) {
+  const merged: CSSProperties = {
+    ...(transform ? sceneTransformStyle(transform, { origin }) : {}),
+    ...(texture
+      ? {
+          backgroundImage: `url(${texture})`,
+          backgroundSize: 'cover',
+          backgroundPosition: 'center',
+        }
+      : {}),
+    ...(wall ? { clipPath: sceneWallClip(wall) } : {}),
+    ...style,
+  }
+
+  const classes = [
+    'aeon-scene-plane',
+    fill ? 'aeon-scene-plane--fill' : '',
+    material ? surfaceClass(material) : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  const interactive = Boolean(children)
+
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs(part)}
+      className={classes}
+      style={merged}
+      aria-hidden={interactive ? undefined : true}
+    >
+      {children}
+    </div>
+  )
+}

package/packages/react-scene/src/scene-room.tsx

@@ -0,0 +1,81 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { sceneAttrs } from '@aeon-ui/geometry'
+import { sceneRoomVars, type SceneRoomCamera, type SceneRoomSize } from '@aeon-ui/scene'
+import type { SurfaceMaterial } from '@aeon-ui/surface'
+import { ScenePlane } from './scene-plane.js'
+
+export type SceneRoomProps = HTMLAttributes<HTMLDivElement> & {
+  size?: SceneRoomSize
+  camera?: SceneRoomCamera
+  floorMaterial?: SurfaceMaterial
+  wallMaterial?: SurfaceMaterial
+  /** Content mounted on the floor plane (counter-rotated to face the viewer). */
+  floor?: ReactNode
+}
+
+const DEFAULT_SIZE: SceneRoomSize = { width: 1280, height: 680, depth: 920 }
+
+/**
+ * CSS 3D box room — floor, ceiling, back, left, and right faces with a shared vanishing point.
+ * Mount UI via `floor` so it sits on the ground plane in the same transform space.
+ */
+export function SceneRoom({
+  size = DEFAULT_SIZE,
+  camera,
+  floorMaterial = 'pavement',
+  wallMaterial = 'brick',
+  floor,
+  className,
+  style,
+  children,
+  ...rest
+}: SceneRoomProps) {
+  const merged: CSSProperties = {
+    ...sceneRoomVars(size, camera),
+    ...style,
+  }
+
+  const interactive = Boolean(floor)
+
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs('room-wrap')}
+      className={['aeon-scene-room-wrap', className].filter(Boolean).join(' ')}
+      style={merged}
+      aria-hidden={rest['aria-hidden'] ?? (interactive ? undefined : true)}
+    >
+      <div {...sceneAttrs('room')} className="aeon-scene-room">
+        <ScenePlane
+          part="ceiling"
+          fill={false}
+          className="aeon-scene-room__face aeon-scene-room__ceiling"
+        />
+        <ScenePlane
+          part="back-wall"
+          material={wallMaterial}
+          fill={false}
+          className="aeon-scene-room__face aeon-scene-room__back"
+        />
+        <ScenePlane
+          part="wall-left"
+          material={wallMaterial}
+          fill={false}
+          className="aeon-scene-room__face aeon-scene-room__left"
+        />
+        <ScenePlane
+          part="wall-right"
+          material={wallMaterial}
+          fill={false}
+          className="aeon-scene-room__face aeon-scene-room__right"
+        />
+        <div className="aeon-scene-room__face aeon-scene-room__floor">
+          <ScenePlane part="ground" material={floorMaterial} fill className="aeon-scene-room__floor-plane">
+            {children}
+          </ScenePlane>
+          {floor ? <div className="aeon-scene-room__floor-slot">{floor}</div> : null}
+        </div>
+      </div>
+    </div>
+  )
+}

package/packages/react-scene/src/scene-root.tsx

@@ -0,0 +1,49 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { sceneAttrs, type SceneState } from '@aeon-ui/geometry'
+
+export type SceneRootProps = HTMLAttributes<HTMLDivElement> & {
+  part?: string
+  state?: SceneState
+  children?: ReactNode
+}
+
+/** Root for an ambient scene region (`data-aeon-scope="scene"`). */
+export function SceneRoot({
+  part = 'root',
+  state,
+  className,
+  style,
+  children,
+  ...rest
+}: SceneRootProps) {
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs(part, state)}
+      className={className}
+      style={style}
+    >
+      {children}
+    </div>
+  )
+}
+
+export type SceneBackdropProps = HTMLAttributes<HTMLDivElement> & {
+  state?: SceneState
+  style?: CSSProperties
+}
+
+/** Full-bleed backdrop slot inside a scene. */
+export function SceneBackdrop({ state, className, style, children, ...rest }: SceneBackdropProps) {
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs('backdrop', state)}
+      className={className}
+      style={{ position: 'absolute', inset: 0, ...style }}
+      aria-hidden
+    >
+      {children}
+    </div>
+  )
+}

package/packages/react-scene/src/scene-slot.tsx

@@ -0,0 +1,41 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { sceneAttrs } from '@aeon-ui/geometry'
+import { sceneTransformStyle, type SceneTransform3d } from '@aeon-ui/scene'
+
+export type SceneSlotProps = HTMLAttributes<HTMLDivElement> & {
+  part?: string
+  transform?: SceneTransform3d
+  origin?: string
+  fill?: boolean
+  children?: ReactNode
+}
+
+/** Mount arbitrary UI (boards, HUD, controls) at a 3D transform — receives pointer events. */
+export function SceneSlot({
+  part = 'slot',
+  transform,
+  origin = '50% 50%',
+  fill = false,
+  className,
+  style,
+  children,
+  ...rest
+}: SceneSlotProps) {
+  const merged: CSSProperties = {
+    ...(transform ? sceneTransformStyle(transform, { origin }) : { transformStyle: 'preserve-3d' }),
+    ...style,
+  }
+
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs(part)}
+      className={['aeon-scene-slot', fill ? 'aeon-scene-slot--fill' : '', className]
+        .filter(Boolean)
+        .join(' ')}
+      style={merged}
+    >
+      {children}
+    </div>
+  )
+}

package/packages/react-scene/src/scene-stage.tsx

@@ -0,0 +1,37 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { sceneAttrs } from '@aeon-ui/geometry'
+import { sceneStageStyle, type ScenePerspective } from '@aeon-ui/scene'
+
+export type SceneStageProps = HTMLAttributes<HTMLDivElement> & {
+  perspective?: ScenePerspective
+  minHeight?: SceneUnit
+  children?: ReactNode
+}
+
+type SceneUnit = number | string
+
+export function SceneStage({
+  perspective,
+  minHeight = 320,
+  className,
+  style,
+  children,
+  ...rest
+}: SceneStageProps) {
+  const merged: CSSProperties = {
+    ...sceneStageStyle(perspective),
+    minHeight: typeof minHeight === 'number' ? `${minHeight}px` : minHeight,
+    ...style,
+  }
+
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs('stage')}
+      className={['aeon-scene-stage', className].filter(Boolean).join(' ')}
+      style={merged}
+    >
+      {children}
+    </div>
+  )
+}

package/packages/react-scene/src/scene-surface.tsx

@@ -0,0 +1,20 @@
+import type { HTMLAttributes } from 'react'
+import { surfaceClass, type SurfaceMaterial } from '@aeon-ui/surface'
+import { sceneAttrs } from '@aeon-ui/geometry'
+
+export type SceneSurfaceProps = HTMLAttributes<HTMLDivElement> & {
+  material: SurfaceMaterial
+}
+
+/** Textured material layer (`@aeon-ui/surface` CSS + scene anatomy). */
+export function SceneSurface({ material, className, children, ...rest }: SceneSurfaceProps) {
+  return (
+    <div
+      {...rest}
+      {...sceneAttrs('surface')}
+      className={[surfaceClass(material), className].filter(Boolean).join(' ')}
+    >
+      {children}
+    </div>
+  )
+}

package/packages/react-scene/src/signal-bars.tsx

@@ -0,0 +1,57 @@
+import { barLayout, barScaleTransform, sceneAttrs } from '@aeon-ui/geometry'
+import { useSignalVisualizer, type UseSignalVisualizerOptions } from './use-signal-visualizer.js'
+
+export type SignalBarsProps = UseSignalVisualizerOptions & {
+  className?: string
+  viewWidth?: number
+  viewHeight?: number
+  fills?: readonly string[]
+  label?: string
+}
+
+/** SVG bar visualizer driven by `@aeon-ui/signal` band motion. */
+export function SignalBars({
+  className,
+  viewWidth = 80,
+  viewHeight = 52,
+  fills,
+  label = 'Audio visualizer',
+  barCount = 7,
+  ...vizOptions
+}: SignalBarsProps) {
+  const { scales, brightness, active } = useSignalVisualizer({ barCount, ...vizOptions })
+  const bars = barLayout({ count: barCount, viewWidth, viewHeight, fills })
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={`0 0 ${viewWidth} ${viewHeight}`}
+      role="img"
+      aria-label={label}
+      className={className}
+      {...sceneAttrs('visualizer', active ? 'active' : 'idle')}
+      style={{ display: 'block', overflow: 'visible' }}
+    >
+      {bars.map((bar, i) => {
+        const scale = scales[i] ?? 1
+        const bright = brightness[i] ?? 1
+        return (
+          <g
+            key={i}
+            transform={barScaleTransform(bar, scale)}
+            style={active ? { filter: `brightness(${bright})` } : undefined}
+          >
+            <rect
+              x={bar.x}
+              y={bar.y}
+              width={bar.w}
+              height={bar.h}
+              rx={bar.w / 2}
+              fill={bar.fill}
+            />
+          </g>
+        )
+      })}
+    </svg>
+  )
+}