@uxpilot/openai-astra-shape-cue 1.0.0

package/dist/panel.css

@@ -0,0 +1,178 @@
+.astra-panel [hidden] {
+  display: none !important;
+}
+
+.astra-panel {
+  position: fixed;
+  top: 1rem;
+  right: 1rem;
+  z-index: 50;
+  width: 18.5rem;
+  max-height: calc(100vh - 2rem);
+  overflow: auto;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 0.75rem;
+  background: rgba(12, 12, 14, 0.82);
+  color: #e6e6e6;
+  font-size: 0.8125rem;
+  scrollbar-color: rgba(255, 255, 255, 0.2) transparent;
+  backdrop-filter: blur(14px);
+  -webkit-backdrop-filter: blur(14px);
+}
+
+.astra-panel::-webkit-scrollbar {
+  width: 8px;
+}
+
+.astra-panel::-webkit-scrollbar-thumb {
+  border: 2px solid transparent;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.2);
+  background-clip: padding-box;
+}
+
+.astra-panel header {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.625rem 0.75rem;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(12, 12, 14, 0.92);
+  backdrop-filter: blur(14px);
+}
+
+.astra-panel-toggle {
+  width: 1.5rem;
+  height: 1.5rem;
+  border: 0;
+  background: none;
+  color: inherit;
+  font-size: 1rem;
+  cursor: pointer;
+}
+
+.astra-panel-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem 0.75rem;
+}
+
+.astra-panel label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.astra-panel select {
+  width: 100%;
+  padding: 0.3rem 0.4rem;
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  border-radius: 0.375rem;
+  background: rgba(255, 255, 255, 0.06);
+  color: inherit;
+}
+
+.astra-panel select option {
+  background: #15151a;
+}
+
+.astra-range span {
+  float: right;
+  opacity: 0.7;
+  font-variant-numeric: tabular-nums;
+}
+
+.astra-range input {
+  width: 100%;
+  accent-color: #9b87ff;
+}
+
+.astra-check {
+  flex-direction: row !important;
+  align-items: center;
+  gap: 0.5rem !important;
+}
+
+.astra-check input {
+  accent-color: #9b87ff;
+}
+
+.astra-custom {
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.astra-svg-file {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+.astra-svg-upload {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 2rem;
+  padding: 0.4rem 0.75rem;
+  border: 1px solid rgba(155, 135, 255, 0.55);
+  border-radius: 0.375rem;
+  background: rgba(155, 135, 255, 0.12);
+  color: #f5f6fb;
+  font-weight: 650;
+  cursor: pointer;
+  transition: 150ms ease;
+}
+
+.astra-svg-upload:hover,
+.astra-svg-upload:focus-visible {
+  border-color: #9b87ff;
+  background: rgba(155, 135, 255, 0.2);
+  outline: 2px solid rgba(155, 135, 255, 0.28);
+  outline-offset: 2px;
+}
+
+.astra-upload-note {
+  color: rgba(230, 230, 230, 0.58);
+  font-size: 0.7rem;
+}
+
+.astra-error {
+  color: #fa994c;
+  font-size: 0.75rem;
+}
+
+.astra-actions {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+}
+
+.astra-panel button[data-action] {
+  flex: 1;
+  padding: 0.375rem 0.5rem;
+  border: 1px solid rgba(255, 255, 255, 0.16);
+  border-radius: 0.375rem;
+  background: rgba(255, 255, 255, 0.1);
+  color: inherit;
+  cursor: pointer;
+}
+
+.astra-panel button[data-action]:hover {
+  background: rgba(255, 255, 255, 0.18);
+}
+
+
+.astra-panel { position: relative; inset: auto; width: 100%; max-height: 100%; box-sizing: border-box; font-family: system-ui,sans-serif; }
+.astra-panel *, .astra-panel *::before, .astra-panel *::after { box-sizing: border-box; }
+.astra-panel button, .astra-panel select, .astra-panel input { font: inherit; }

package/dist/react.d.ts

@@ -0,0 +1,27 @@
+import type { CSSProperties, HTMLAttributes, ForwardRefExoticComponent, RefAttributes } from "react";
+import type { Cue, CueOptions, Shape, ParticleOptions, AnimationOptions, ScrollOptions } from "./index.js";
+export interface ShapeCueHandle {
+  readonly cue: Cue | null;
+  replay(): void;
+  setShape(shape: Shape): void;
+  update(options: CueOptions): void;
+  pause(): void;
+  play(): void;
+  loadSVG(source: File | Blob | string): Promise<Cue>;
+  getOptions(): CueOptions | null;
+  setScrollProgress(progress: number | null): void;
+}
+export interface ShapeCueProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onError"> {
+  shape?: Shape;
+  options?: Omit<CueOptions, "shape">;
+  colors?: string[] | null;
+  particles?: ParticleOptions;
+  animation?: AnimationOptions;
+  bloom?: number;
+  scroll?: ScrollOptions;
+  style?: CSSProperties;
+  onReady?: (cue: Cue) => void;
+  onError?: (error: unknown) => void;
+  onSettingsChange?: (options: CueOptions) => void;
+}
+export const ShapeCue: ForwardRefExoticComponent<ShapeCueProps & RefAttributes<ShapeCueHandle>>;

package/dist/react.js

@@ -0,0 +1,50 @@
+"use client";
+/*! @uxpilot/openai-astra-shape-cue v1.0.0 | Copyright 2026 UX Pilot Inc., original contributions. | UX Pilot Creative Use License 1.0. See LICENSE.md.
+
+three
+The MIT License
+
+Copyright © 2010-2025 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+postprocessing
+Copyright © 2015 Raoul van Rüschen
+
+This software is provided 'as-is', without any express or implied warranty. In
+no event will the authors be held liable for any damages arising from the use of
+this software.
+
+Permission is granted to anyone to use this software for any purpose, including
+commercial applications, and to alter it and redistribute it freely, subject to
+the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not claim
+   that you wrote the original software. If you use this software in a product,
+   an acknowledgment in the product documentation would be appreciated but is
+   not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.
+
+*/
+"use client";import{createElement as O,forwardRef as P,useEffect as y,useImperativeHandle as G,useRef as h}from"react";import{createShapeCue as b}from"./index.js";var j=Object.freeze({}),T=P(function({shape:i="star",options:s=j,colors:n,particles:t,animation:u,bloom:d,scroll:c,onReady:p,onError:l,onSettingsChange:S,style:E,children:z,...w},C){let o=h(null),r=h(null),f=h({onReady:p,onError:l,onSettingsChange:S});return f.current={onReady:p,onError:l,onSettingsChange:S},G(C,()=>({get cue(){return r.current},replay(){r.current?.replay()},setShape(e){r.current?.setShape(e)},update(e){r.current?.update(e)},pause(){r.current?.pause()},play(){r.current?.play()},loadSVG(e){return r.current?r.current.loadSVG(e):Promise.reject(new Error("Shape Cue is not mounted."))},getOptions(){return r.current?.getOptions()??null},setScrollProgress(e){r.current?.setScrollProgress(e)}}),[]),y(()=>{let e,g;try{if(e=b(o.current,{...s,shape:i,...n!==void 0?{colors:n}:{},...t!==void 0?{particles:t}:{},...u!==void 0?{animation:u}:{},...d!==void 0?{bloom:d}:{},...c!==void 0?{scroll:c}:{}}),r.current=e,e.status==="error")throw new Error("Unable to initialize the WebGL renderer.");g=e.onChange(a=>f.current.onSettingsChange?.(a)),f.current.onReady?.(e)}catch(a){e?.dispose(),r.current=null,f.current.onError?.(a)}return()=>{g?.(),e?.dispose(),r.current=null}},[]),y(()=>{try{r.current?.update({...s,shape:i,...n!==void 0?{colors:n}:{},...t!==void 0?{particles:t}:{},...u!==void 0?{animation:u}:{},...d!==void 0?{bloom:d}:{},...c!==void 0?{scroll:c}:{}})}catch(e){f.current.onError?.(e)}},[i,s,n,t,u,d,c]),O("div",{...w,ref:o,style:{width:"100%",height:500,...E}})});export{T as ShapeCue};

package/dist/settings.d.ts

@@ -0,0 +1,188 @@
+export interface EngineConfig {
+  animationPlaying?: boolean;
+  animationRestartKey?: number;
+  bloomIntensity?: number;
+  bloomThreshold?: number;
+  colorMode?: boolean;
+  convergeDuration?: number;
+  faceForward?: boolean;
+  pathShapeAutoRotate?: boolean;
+  pathShapeAutoRotateAmount?: number;
+  pathShapeAutoRotateSpeed?: number;
+  pathShapeScatter?: number;
+  rotationDepth?: number;
+  scrollDisperseDistance?: number;
+  scrollEffects?: boolean;
+  scrollStarDriftSpeed?: number;
+  scrollStartOffset?: number;
+  scrollTextFadeDistance?: number;
+  showCenterCluster?: boolean;
+  accretionExhale?: {
+    accretionRatio?: number;
+    ambientAmount?: number;
+    ambientSpeed?: number;
+    coreIntensity?: number;
+    duration?: number;
+    exhaleStrength?: number;
+    inwardStrength?: number;
+    propagationSoftness?: number;
+    settleDuration?: number;
+    startScale?: number;
+  };
+  animationPreset?: string;
+  colorPalette?: string;
+  colorPaletteColors?: string[];
+  dirtyGlass?: {
+    distortion?: number;
+    drift?: boolean;
+    driftStrength?: number;
+    enabled?: boolean;
+    grain?: number;
+    procedural?: number;
+    texture?: number;
+  };
+  grow?: {
+    duration?: number;
+    growthSpeed?: number;
+    softness?: number;
+    startZoom?: number;
+  };
+  interaction?: {
+    depthDisplacement?: number;
+    followDamping?: number;
+    illumination?: number;
+    magnification?: number;
+    particleRepel?: boolean;
+    repelDistance?: number;
+    repelFalloff?: number;
+    repelHighlight?: number;
+    repelHighlightRadius?: number;
+    repelPressMultiplier?: number;
+    repelRadius?: number;
+    repelReturnSpring?: number;
+    repelSpring?: number;
+    rotationLag?: number;
+    radius?: number;
+    smearCurl?: number;
+    smearTrailLength?: number;
+  };
+  interactionMode?: string;
+  lensFlare?: {
+    animated?: boolean;
+    enabled?: boolean;
+    ghosts?: number;
+    halo?: number;
+    intensity?: number;
+    secondary?: number;
+    streakLength?: number;
+    streaks?: number;
+    verticalStreaks?: number;
+  };
+  orbitalDust?: {
+    density?: number;
+    driftSpeed?: number;
+    enabled?: boolean;
+    intensity?: number;
+    reach?: number;
+    spread?: number;
+    tightSpread?: number;
+  };
+  stars?: {
+    density?: number;
+    densityFalloff?: number;
+    flowInward?: boolean;
+    flowSpeed?: number;
+    intensity?: number;
+    scatter?: number;
+    size?: number;
+    sizeFalloff?: number;
+    twinkleSpeed?: number;
+  };
+}
+export interface EngineSettingValues {
+  "animationPlaying": boolean;
+  "animationRestartKey": number;
+  "bloomIntensity": number;
+  "bloomThreshold": number;
+  "colorMode": boolean;
+  "convergeDuration": number;
+  "faceForward": boolean;
+  "pathShapeAutoRotate": boolean;
+  "pathShapeAutoRotateAmount": number;
+  "pathShapeAutoRotateSpeed": number;
+  "pathShapeScatter": number;
+  "rotationDepth": number;
+  "scrollDisperseDistance": number;
+  "scrollEffects": boolean;
+  "scrollStarDriftSpeed": number;
+  "scrollStartOffset": number;
+  "scrollTextFadeDistance": number;
+  "showCenterCluster": boolean;
+  "accretionExhale.accretionRatio": number;
+  "accretionExhale.ambientAmount": number;
+  "accretionExhale.ambientSpeed": number;
+  "accretionExhale.coreIntensity": number;
+  "accretionExhale.duration": number;
+  "accretionExhale.exhaleStrength": number;
+  "accretionExhale.inwardStrength": number;
+  "accretionExhale.propagationSoftness": number;
+  "accretionExhale.settleDuration": number;
+  "accretionExhale.startScale": number;
+  "animationPreset": string;
+  "colorPalette": string;
+  "colorPaletteColors": string[];
+  "dirtyGlass.distortion": number;
+  "dirtyGlass.drift": boolean;
+  "dirtyGlass.driftStrength": number;
+  "dirtyGlass.enabled": boolean;
+  "dirtyGlass.grain": number;
+  "dirtyGlass.procedural": number;
+  "dirtyGlass.texture": number;
+  "grow.duration": number;
+  "grow.growthSpeed": number;
+  "grow.softness": number;
+  "grow.startZoom": number;
+  "interaction.depthDisplacement": number;
+  "interaction.followDamping": number;
+  "interaction.illumination": number;
+  "interaction.magnification": number;
+  "interaction.particleRepel": boolean;
+  "interaction.repelDistance": number;
+  "interaction.repelFalloff": number;
+  "interaction.repelHighlight": number;
+  "interaction.repelHighlightRadius": number;
+  "interaction.repelPressMultiplier": number;
+  "interaction.repelRadius": number;
+  "interaction.repelReturnSpring": number;
+  "interaction.repelSpring": number;
+  "interaction.rotationLag": number;
+  "interaction.radius": number;
+  "interaction.smearCurl": number;
+  "interaction.smearTrailLength": number;
+  "interactionMode": string;
+  "lensFlare.animated": boolean;
+  "lensFlare.enabled": boolean;
+  "lensFlare.ghosts": number;
+  "lensFlare.halo": number;
+  "lensFlare.intensity": number;
+  "lensFlare.secondary": number;
+  "lensFlare.streakLength": number;
+  "lensFlare.streaks": number;
+  "lensFlare.verticalStreaks": number;
+  "orbitalDust.density": number;
+  "orbitalDust.driftSpeed": number;
+  "orbitalDust.enabled": boolean;
+  "orbitalDust.intensity": number;
+  "orbitalDust.reach": number;
+  "orbitalDust.spread": number;
+  "orbitalDust.tightSpread": number;
+  "stars.density": number;
+  "stars.densityFalloff": number;
+  "stars.flowInward": boolean;
+  "stars.flowSpeed": number;
+  "stars.intensity": number;
+  "stars.scatter": number;
+  "stars.size": number;
+  "stars.sizeFalloff": number;
+  "stars.twinkleSpeed": number;
+}

package/examples/ReactHero.jsx

@@ -0,0 +1,34 @@
+'use client';
+import { useState } from 'react';
+import { ShapeCue } from '@uxpilot/openai-astra-shape-cue/react';
+
+export default function ReactHero() {
+  const [shape, setShape] = useState('heart');
+  const [playing, setPlaying] = useState(true);
+  const [speed, setSpeed] = useState(0.4);
+  const [error, setError] = useState('');
+  return (
+    <section style={{ background: '#0b0b12', color: '#eee', padding: 24 }}>
+      <h1>Shape Cue by UX Pilot</h1>
+      <label>Shape{' '}
+        <select value={shape} onChange={e => setShape(e.target.value)}>
+          <option value="heart">Heart</option>
+          <option value="star">Star</option>
+          <option value="infinity">Infinity</option>
+          <option value="hexagon">Hexagon</option>
+        </select>
+      </label>{' '}
+      <label>Speed{' '}
+        <input type="range" min="0" max="3" step="0.05" value={speed}
+          onChange={e => setSpeed(Number(e.target.value))} />
+      </label>{' '}
+      <button onClick={() => setPlaying(!playing)}>{playing ? 'Pause' : 'Resume'}</button>
+      {error && <p role="alert">{error}</p>}
+      <ShapeCue shape={shape} colors={['#9b87ff', '#47e2c2', '#ffffff']}
+        particles={{ density: 2, size: 1.5 }}
+        animation={{ speed, duration: 3, playing }} bloom={0.5}
+        options={{ interaction: 'rotate', background: 'transparent' }}
+        style={{ height: 500 }} onError={e => setError(String(e))} />
+    </section>
+  );
+}

package/examples/customize.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Customize Shape Cue</title>
+<style>body{background:#0b0b12;color:#eee;font:16px system-ui;margin:24px}button{padding:10px 16px;margin-right:8px;border-radius:6px;border:1px solid #77679c;background:#292336;color:#eee;cursor:pointer}astra-shape-cue{display:block;width:100%;height:65vh;min-height:320px}</style>
+<script defer src="../dist/astra.min.js"></script></head><body>
+<h1>Shape Cue by UX Pilot</h1>
+<p>Switch colors and motion without editing the engine.</p>
+<astra-shape-cue id="effect" shape="heart" colors="#9b87ff,#47e2c2,#ffffff" speed="0.4" gather-duration="3" particle-density="2" particle-size="1.5" bloom="0.5"></astra-shape-cue>
+<button id="colors">Warm colors</button><button id="motion">Pause</button><button id="replay">Replay</button>
+<script>
+window.addEventListener('DOMContentLoaded',()=>{
+  const effect=document.getElementById('effect');
+  document.getElementById('colors').onclick=()=>effect.setAttribute('colors','#ff8e5e,#ffcf87');
+  document.getElementById('motion').onclick=e=>{
+    const paused=!effect.hasAttribute('paused');
+    effect.toggleAttribute('paused',paused);
+    e.target.textContent=paused?'Resume':'Pause';
+  };
+  document.getElementById('replay').onclick=()=>effect.cue.replay();
+});
+</script></body></html>

package/examples/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Shape Cue by UX Pilot</title>
+  <link rel="stylesheet" href="../dist/panel.css">
+  <style>
+    body { margin:0; background:#08080b; color:#eee; font:14px system-ui; }
+    main { display:grid; grid-template-columns:minmax(0,1fr) 300px; gap:24px; padding:24px; min-height:100vh; box-sizing:border-box; }
+    #effect { display:block; width:100%; height:calc(100vh - 48px); min-height:400px; }
+    #controls { max-height:calc(100vh - 48px); overflow:auto; }
+    @media(max-width:760px) { main { grid-template-columns:1fr; } #effect { height:55vh; } }
+  </style>
+</head>
+<body>
+  <main><div id="effect"></div><div id="controls"></div></main>
+  <script src="../dist/astra.min.js"></script>
+  <script>
+    const cue = UXPShapeCue.createShapeCue(document.getElementById('effect'), { shape:'star', palette:'aurora' });
+    const removeControls = UXPShapeCue.mountControls(cue, document.getElementById('controls'));
+    window.addEventListener('pagehide', () => { removeControls(); cue.dispose(); }, {once:true});
+  </script>
+</body>
+</html>

package/examples/two-rings.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
+  <circle cx="50" cy="50" r="36"/>
+  <circle cx="150" cy="50" r="24"/>
+</svg>

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@uxpilot/openai-astra-shape-cue",
+  "version": "1.0.0",
+  "description": "Interactive WebGL particle shapes for HTML and React, with custom SVG support.",
+  "type": "module",
+  "author": "UX Pilot Inc.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "default": "./dist/index.js" },
+    "./react": { "types": "./dist/react.d.ts", "import": "./dist/react.js", "default": "./dist/react.js" },
+    "./panel.css": "./dist/panel.css",
+    "./dist/astra.min.js": "./dist/astra.min.js"
+  },
+  "unpkg": "dist/astra.min.js",
+  "jsdelivr": "dist/astra.min.js",
+  "files": ["dist", "examples", "LICENSE.md", "THIRD_PARTY_NOTICES.md", "README.md", "SETTINGS.md"],
+  "peerDependencies": { "react": ">=18 <20" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "keywords": ["particles", "webgl", "svg", "animation", "react", "web-component"]
+}