@snailicid3/gbt-scope 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,308 @@
+/*
+ * @snailicid3/gbt-scope v0.0.1
+ * Module: GbtScope
+ * (c) 2026 Gillian Tunney
+ * React components and hooks for the operator user interface.
+ * https://github.com/gbtunney/gbt-monorepov2
+ * Released under the MIT License.
+ * Build: 9/9/2026, 7:05:01 AM
+ */
+import { Mesh, ShaderMaterial, Vector3 } from "@babylonjs/core";
+import { ReactElement } from "react";
+//#region src/helpers.d.ts
+type Dimensions = {
+  height: number;
+  width: number;
+};
+type Point = {
+  x: number;
+  y: number;
+};
+type XY = [number, number];
+type Vector3Params = ConstructorParameters<typeof Vector3>;
+type CameraConfigPosition = Partial<{
+  enabled: boolean;
+  hRotation: number; /** Alpha Math.PI / 2, // Alpha (horizontal rotation) */
+  /** Slow down the zoom speed */
+  mouseWheelSpeed: number;
+  position: Vector3Params;
+  radius: number;
+  target: Vector3Params;
+  vRotation: number; /** Beta Math.PI / 4, // Beta (vertical rotation) */
+}>;
+type CameraOrthoConfig = Pick<CameraConfigPosition, 'enabled' | 'target'> & {
+  ortho?: true;
+};
+//#endregion
+//#region src/motion/animator.d.ts
+/**
+ * A single declarative animation rule: read `source`, shape it through `curve`, scale by `speed * delta`, then `add` to
+ * (default) or `set` the `target`.
+ */
+type GbtScopeAnimator = {
+  curve?: GbtScopeCurve;
+  mode?: 'add' | 'set';
+  source: GbtScopeAnimatorSource;
+  speed?: number;
+  target: GbtScopeAnimatorTarget;
+};
+/** Input signal an animator reads from. */
+type GbtScopeAnimatorSource = 'mouseDistance' | 'scrollProgress' | 'scrollVelocity' | 'time';
+/** Uniform-backed value an animator can drive. */
+type GbtScopeAnimatorTarget = 'offset.x' | 'offset.y' | 'opacity' | 'rotation' | 'scaleFactor';
+/**
+ * Fixed values that replace the live pointer/scroll signals in the driver — for mocking motion input (device-free
+ * testing, deterministic demos). A defined field wins over the real input; `undefined` fields fall through.
+ */
+type GbtScopeInputOverrides = Partial<Pick<GbtScopeInputs, 'mouseDistance' | 'scrollProgress' | 'scrollVelocity'>>;
+/** Per-frame inputs fed to the animators. */
+type GbtScopeInputs = {
+  delta: number;
+  mouseDistance: number;
+  scrollProgress: number;
+  scrollVelocity: number;
+  time: number;
+};
+/** Mutable, uniform-facing animation state. */
+type GbtScopeState = {
+  offset: [number, number];
+  opacity: number;
+  rotation: number;
+  scaleFactor: number;
+};
+/**
+ * Applies every animator to a copy of `state` for one frame and returns the new state. Each animator's source value is
+ * curved, scaled by `speed * delta` (frame-rate independent), then added to or set on its target.
+ */
+declare const applyAnimators: (state: GbtScopeState, animators: Array<GbtScopeAnimator>, inputs: GbtScopeInputs) => GbtScopeState;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Curve parameters controlling how an input value (eg. pointer distance from center, scroll velocity) maps to an effect
+ * amount. Replaces the old `[min, max]` tuple form of `mouse_curve` with a richer, named shape.
+ *
+ * @see applyCurve in ./motion/curve.ts
+ */
+type GbtScopeCurve = {
+  /** Input magnitude below this is treated as 0. Default 0. */
+  deadzone?: number;
+  /** Shaping exponent (1 = linear, >1 = ease-in). Default 1. */
+  exponent?: number;
+  /** Negate the result. Default false. */
+  invert?: boolean;
+  /** Upper clamp applied after curving. Default 1. */
+  max?: number;
+  /** Lower clamp applied after curving. Default 0. */
+  min?: number;
+  /** Linear gain applied before the exponent. Default 1. */
+  multiplier?: number;
+};
+/**
+ * Shared, serializable material props for all GbtScope viewers (flat + 3D mesh). camelCase only — animation is
+ * data-driven via {@link GbtScopeAnimator}, not speed fields. `rotation`/`offset`/`scaleFactor`/`opacity` are the
+ * resting (base) values the animators build on.
+ */
+type GbtScopeMaterialProps = {
+  /** Pre-resolved texture dimensions; viewers derive this from `resolution`. */
+  dimensions?: Dimensions;
+  imageAspect?: number;
+  offset?: [number, number];
+  /** Multiplier on the offset uniform (`uOffsetAmount`). */
+  offsetScale?: number;
+  opacity?: number;
+  rotation?: number;
+  /** Multiplier on the rotation uniform (`uRotationAmount`). */
+  rotationScale?: number;
+  scaleFactor?: number;
+  segments?: number;
+  src: string;
+  tileMode?: GbtScopeTileMode;
+  tiling?: number;
+};
+/**
+ * Tiling strategy applied to the kaleidoscope pattern after the radial fold.
+ *
+ * - `none` — no wrapping; the pattern is sampled directly.
+ * - `repeat` — `fract(uv * tiling)` square repeats (the historical behavior).
+ * - `mirror` — mirrored repeats for seamless edges.
+ */
+type GbtScopeTileMode = 'mirror' | 'none' | 'repeat';
+/**
+ * Canonical default values for {@link GbtScopeMaterialProps}. `src` is required and has no default. Imported by
+ * component defaults and Storybook args so the defaults live in a single place.
+ */
+declare const defaultGbtScopeMaterialProps: {
+  imageAspect: number;
+  offset: [number, number];
+  offsetScale: number;
+  opacity: number;
+  rotation: number;
+  rotationScale: number;
+  scaleFactor: number;
+  segments: number;
+  tileMode: GbtScopeTileMode;
+  tiling: number;
+};
+/**
+ * Viewer-level props shared by both the flat and mesh viewers. Camera config is viewer-specific and declared on each
+ * component. Material props are forwarded down to {@link GbtScopeMaterialProps}.
+ */
+type GbtScopeViewerBaseProps = {
+  /** Declarative motion rules applied each frame. */
+  animators?: Array<GbtScopeAnimator>;
+  /** Aspect ratio of the host canvas. */
+  aspect_ratio?: 'parent' | number;
+  bg_color?: string;
+  /** Fixed values replacing the live pointer/scroll inputs (mock/testing). */
+  inputOverrides?: GbtScopeInputOverrides;
+  /** Canvas background; `'screen'` resolution matches the viewport. */
+  resolution?: 'screen' | Dimensions | null;
+};
+//#endregion
+//#region src/components/GbtScopeFlatViewer.d.ts
+type GbtScopeFlatViewerProps = GbtScopeViewerBaseProps & Omit<GbtScopeMaterialProps, 'dimensions'> & {
+  cameraSettings?: CameraOrthoConfig;
+  name?: string;
+};
+/** Default props for the flat viewer — single source of truth for Storybook args. */
+declare const defaultGbtScopeFlatViewerProps: {
+  animators: never[];
+  aspect_ratio: "parent" | number;
+  bg_color: string;
+  cameraSettings: CameraOrthoConfig;
+  name: string;
+  resolution: "screen" | Dimensions | null;
+  src: string;
+  imageAspect: number;
+  offset: [number, number];
+  offsetScale: number;
+  opacity: number;
+  rotation: number;
+  rotationScale: number;
+  scaleFactor: number;
+  segments: number;
+  tileMode: GbtScopeTileMode;
+  tiling: number;
+};
+declare const GbtScopeFlatViewer: ({ animators, aspect_ratio, bg_color, cameraSettings, imageAspect, inputOverrides, name, offset, offsetScale, opacity, resolution, rotation, rotationScale, scaleFactor, segments, src, tileMode, tiling }: GbtScopeFlatViewerProps) => ReactElement;
+//#endregion
+//#region src/motion/pointer.d.ts
+/** Current normalized pointer position, centered on the canvas, range [-1, 1]. */
+type PointerState = {
+  readonly x: number;
+  readonly y: number;
+};
+type PointerStateHandle = {
+  /** Attach pointerdown/pointermove/pointerleave listeners to a canvas. */
+  attach: (canvas: HTMLCanvasElement) => void;
+  /** Remove the listeners. Call from the scene's onDisposeObservable. */
+  detach: (canvas: HTMLCanvasElement) => void;
+  /** Live pointer position. Mutated internally; read it inside a render loop. */
+  state: PointerState;
+};
+/**
+ * Creates a mutable pointer-state object for use inside a Babylon.js scene setup callback. Intentionally NOT a React
+ * hook: `onSceneReady` runs outside React's render cycle, so a hook's state would be stale inside the render
+ * observable. The returned `state` object is mutated in place and is safe to read every frame.
+ *
+ * Position is normalized to [-1, 1] on both axes (canvas-relative). Uses pointer events so mouse and touch behave
+ * uniformly: a mouse resets to [0, 0] on leaving the canvas, while a touch latches at the last tap/drag position (tap
+ * center to zero it) — hover-less devices would otherwise never produce input.
+ */
+declare const createPointerState: () => PointerStateHandle;
+//#endregion
+//#region src/motion/scroll.d.ts
+/** Current scroll signals. `progress` is [0,1]; `velocity` decays toward 0. */
+type ScrollState = {
+  readonly progress: number;
+  readonly velocity: number;
+};
+type ScrollStateHandle = {
+  /** Attach scroll/wheel listeners (defaults to window). */
+  attach: (target?: HTMLElement | Window) => void;
+  /**
+   * Decay the velocity by one frame's worth (call once per frame from the driver after reading). `factor` in [0,1];
+   * lower = faster decay.
+   */
+  decay: (factor?: number) => void;
+  /** Remove listeners. Call from the scene's onDisposeObservable. */
+  detach: (target?: HTMLElement | Window) => void;
+  /** Live scroll signals. Mutated internally; read inside a render loop. */
+  state: ScrollState;
+};
+/**
+ * Creates a mutable scroll-state object for use inside a Babylon.js scene setup callback. Tracks page scroll `progress`
+ * [0,1] and a wheel-driven `velocity` that the driver decays each frame. Plain factory (not a React hook) — mirrors
+ * {@link ./pointer.createPointerState} so it can be read from the render observable.
+ */
+declare const createScrollState: () => ScrollStateHandle;
+//#endregion
+//#region src/components/GbtScopeMaterial.d.ts
+type GbtScopeMaterialComponentProps = GbtScopeMaterialProps & {
+  /** Declarative motion rules driven each frame. */
+  animators?: Array<GbtScopeAnimator>;
+  /** Fixed values replacing the live pointer/scroll inputs (mock/testing). */
+  inputOverrides?: GbtScopeInputOverrides;
+  /** Mesh the material is applied to. */
+  mesh: Mesh | null;
+  name?: string;
+  onInit?: (material: ShaderMaterial) => void;
+  onUpdate?: (material: ShaderMaterial) => void;
+  /** Live pointer + scroll inputs (created by the viewer). */
+  pointer: PointerStateHandle;
+  scroll: ScrollStateHandle;
+};
+/**
+ * Kaleidoscope shader material applied to a Babylon mesh. Static uniforms update reactively from props; the animated
+ * uniforms (rotation/offset/scaleFactor/ opacity) are driven each frame by {@link createGbtScopeDriver} from the
+ * `animators` + live pointer/scroll inputs. No Babylon Animation is used.
+ */
+declare const GbtScopeMaterial: ({ animators, dimensions, imageAspect, inputOverrides, mesh, name, offset, offsetScale, onInit, onUpdate, opacity, pointer, rotation, rotationScale, scaleFactor, scroll, segments, src, tileMode, tiling }: GbtScopeMaterialComponentProps) => null | ReactElement;
+//#endregion
+//#region src/components/GbtScopeMeshViewer.d.ts
+type GbtScopeMeshViewerProps = GbtScopeViewerBaseProps & Omit<GbtScopeMaterialProps, 'dimensions'> & {
+  cameraSettings?: CameraConfigPosition;
+  name?: string;
+};
+/** Default props for the 3D mesh viewer — single source of truth for Storybook args. */
+declare const defaultGbtScopeMeshViewerProps: {
+  animators: never[];
+  aspect_ratio: "parent" | number;
+  bg_color: string;
+  cameraSettings: CameraConfigPosition;
+  name: string;
+  resolution: "screen" | Dimensions | null;
+  src: string;
+  imageAspect: number;
+  offset: [number, number];
+  offsetScale: number;
+  opacity: number;
+  rotation: number;
+  rotationScale: number;
+  scaleFactor: number;
+  segments: number;
+  tileMode: GbtScopeTileMode;
+  tiling: number;
+};
+declare const GbtScopeMeshViewer: ({ animators, aspect_ratio, bg_color, cameraSettings, imageAspect, inputOverrides, name, offset, offsetScale, opacity, resolution, rotation, rotationScale, scaleFactor, segments, src, tileMode, tiling }: GbtScopeMeshViewerProps) => ReactElement;
+//#endregion
+//#region src/motion/curve.d.ts
+/**
+ * Maps an input value through a {@link GbtScopeCurve}: deadzone → gain → exponent → clamp → optional invert. The input
+ * is treated by magnitude (`Math.abs`), so direction is supplied by `invert`, not the sign of `value`.
+ */
+declare const applyCurve: (value: number, curve?: GbtScopeCurve) => number;
+/**
+ * Type guard distinguishing the legacy `[min, max]` tuple form of `mouse_curve` from the richer {@link GbtScopeCurve}
+ * object form.
+ */
+declare const isTupleCurve: (value: [number, number] | GbtScopeCurve) => value is [number, number];
+/**
+ * Bridges the legacy `[min, max]` tuple (plus a separate `mouse_multiplier`) into an equivalent {@link GbtScopeCurve}.
+ * With the historical defaults `[0, 0.015]` and multiplier `0.01`, `applyCurve` reproduces the old inline
+ * `Math.min(Math.max(dist * mult, min), max)` clamp exactly.
+ */
+declare const tupleToGbtScopeCurve: (tuple: [number, number], multiplier?: number) => GbtScopeCurve;
+//#endregion
+export { type Dimensions, type GbtScopeAnimator, type GbtScopeAnimatorSource, type GbtScopeAnimatorTarget, type GbtScopeCurve, GbtScopeFlatViewer, type GbtScopeFlatViewerProps, type GbtScopeInputOverrides, type GbtScopeInputs, GbtScopeMaterial, type GbtScopeMaterialComponentProps, type GbtScopeMaterialProps, GbtScopeMeshViewer, type GbtScopeMeshViewerProps, type GbtScopeState, type GbtScopeTileMode, type GbtScopeViewerBaseProps, type Point, type PointerState, type PointerStateHandle, type ScrollState, type ScrollStateHandle, type XY, applyAnimators, applyCurve, createPointerState, createScrollState, defaultGbtScopeFlatViewerProps, defaultGbtScopeMaterialProps, defaultGbtScopeMeshViewerProps, isTupleCurve, tupleToGbtScopeCurve };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/helpers.ts","../src/motion/animator.ts","../src/types.ts","../src/components/GbtScopeFlatViewer.tsx","../src/motion/pointer.ts","../src/motion/scroll.ts","../src/components/GbtScopeMaterial.tsx","../src/components/GbtScopeMeshViewer.tsx","../src/motion/curve.ts"],"mappings":";;;;;;;;;;;;KAWY;EACR;EACA;;KAEQ;EAAU;EAAW;;KACrB;KAYA,gBAAgB,6BAA6B;KAI7C,uBAAuB;EAC/B;EACA;;EAEA;EACA,UAAU;EACV;EACA,QAAQ;EACR;;KAEQ,oBAAoB,KAC5B;EAEE;;;;;;;;KCtCM;EACR,QAAQ;EACR;EACA,QAAQ;EACR;EACA,QAAQ;;;KAIA;;KAIA;;;;;KAOA,yBAAyB,QACjC,KAAK;;KAIG;EACR;EACA;EACA;EACA;EACA;;;KAIQ;EACR;EACA;EACA;EACA;;;;;;cAOS,iBACT,OAAO,eACP,WAAW,MAAM,mBACjB,QAAQ,mBACT;;;;;;;;;KC5CS;;EAER;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;KAQQ;;EAER,aAAa;EACb;EACA;;EAEA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA,WAAW;EACX;;;;;;;;;KAUQ;;;;;cAMC;;EAES;;;;;;;EAOI,UAAA;;;;;;;KAQd;;EAER,YAAY,MAAM;;EAElB;EACA;;EAEA,iBAAiB;;EAEjB,wBAAwB;;;;KC/DhB,0BAA0B,0BAClC,KAAK;EACD,iBAAiB;EACjB;;;cAKK;;EAGU;;EAMd,gBAAA;;EAEmB,uBAAW;;;;;;;;;;YAAA;;;cAIjC,uBAAsB,WAAA,cAAA,UAAA,gBAAA,aAAA,gBAAA,MAAA,QAAA,aAAA,SAAA,YAAA,UAAA,eAAA,aAAA,UAAA,KAAA,UAAA,UAmBzB,4BAA0B;;;;KCnEjB;WACC;WACA;;KAGD;;EAER,SAAS,QAAQ;;EAEjB,SAAS,QAAQ;;EAEjB,OAAO;;;;;;;;;;;cAYE,0BAAyB;;;;KCvB1B;WACC;WACA;;KAGD;;EAER,SAAS,SAAS,cAAc;;;;;EAKhC,QAAQ;;EAER,SAAS,SAAS,cAAc;;EAEhC,OAAO;;;;;;;cAgBE,yBAAwB;;;KCZzB,iCAAiC;;EAEzC,YAAY,MAAM;;EAElB,iBAAiB;;EAEjB,MAAM;EACN;EACA,UAAU,UAAU;EACpB,YAAY,UAAU;;EAEtB,SAAS;EACT,QAAQ;;;;;;;cA8BN,qBAAoB,WAAA,YAAA,aAAA,gBAAA,MAAA,MAAA,QAAA,aAAA,QAAA,UAAA,SAAA,SAAA,UAAA,eAAA,aAAA,QAAA,UAAA,KAAA,UAAA,UAqBvB,0CAAwC;;;KC1D/B,0BAA0B,0BAClC,KAAK;EACD,iBAAiB;EACjB;;;cAKK;;EAGU;;EAMd,gBAAA;;EAEe,uBAAW;;;;;;;;;;YAAA;;;cAI7B,uBAAsB,WAAA,cAAA,UAAA,gBAAA,aAAA,gBAAA,MAAA,QAAA,aAAA,SAAA,YAAA,UAAA,eAAA,aAAA,UAAA,KAAA,UAAA,UAuBzB,4BAA0B;;;;;;;cClEhB,aACT,eACA,QAAO;;;;;cAoBE,eACT,0BAA0B,kBAC3B;;;;;;cAgBU,uBACT,yBACA,wBACD"}

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+/*
+ * @snailicid3/gbt-scope v0.0.1
+ * Module: GbtScope
+ * (c) 2026 Gillian Tunney
+ * React components and hooks for the operator user interface.
+ * https://github.com/gbtunney/gbt-monorepov2
+ * Released under the MIT License.
+ * Build: 9/9/2026, 7:05:01 AM
+ */
+import { ArcRotateCamera, FreeCamera, Mesh, ShaderMaterial, Vector2, Vector3, Vector4 } from "@babylonjs/core";
+import { ReactElement } from "react";
+//#region src/helpers.d.ts
+type Dimensions = {
+  height: number;
+  width: number;
+};
+type Point = {
+  x: number;
+  y: number;
+};
+type XY = [number, number];
+type Vector3Params = ConstructorParameters<typeof Vector3>;
+type CameraConfigPosition = Partial<{
+  enabled: boolean;
+  hRotation: number; /** Alpha Math.PI / 2, // Alpha (horizontal rotation) */
+  /** Slow down the zoom speed */
+  mouseWheelSpeed: number;
+  position: Vector3Params;
+  radius: number;
+  target: Vector3Params;
+  vRotation: number; /** Beta Math.PI / 4, // Beta (vertical rotation) */
+}>;
+type CameraOrthoConfig = Pick<CameraConfigPosition, 'enabled' | 'target'> & {
+  ortho?: true;
+};
+//#endregion
+//#region src/motion/animator.d.ts
+/**
+ * A single declarative animation rule: read `source`, shape it through `curve`, scale by `speed * delta`, then `add` to
+ * (default) or `set` the `target`.
+ */
+type GbtScopeAnimator = {
+  curve?: GbtScopeCurve;
+  mode?: 'add' | 'set';
+  source: GbtScopeAnimatorSource;
+  speed?: number;
+  target: GbtScopeAnimatorTarget;
+};
+/** Input signal an animator reads from. */
+type GbtScopeAnimatorSource = 'mouseDistance' | 'scrollProgress' | 'scrollVelocity' | 'time';
+/** Uniform-backed value an animator can drive. */
+type GbtScopeAnimatorTarget = 'offset.x' | 'offset.y' | 'opacity' | 'rotation' | 'scaleFactor';
+/**
+ * Fixed values that replace the live pointer/scroll signals in the driver — for mocking motion input (device-free
+ * testing, deterministic demos). A defined field wins over the real input; `undefined` fields fall through.
+ */
+type GbtScopeInputOverrides = Partial<Pick<GbtScopeInputs, 'mouseDistance' | 'scrollProgress' | 'scrollVelocity'>>;
+/** Per-frame inputs fed to the animators. */
+type GbtScopeInputs = {
+  delta: number;
+  mouseDistance: number;
+  scrollProgress: number;
+  scrollVelocity: number;
+  time: number;
+};
+/** Mutable, uniform-facing animation state. */
+type GbtScopeState = {
+  offset: [number, number];
+  opacity: number;
+  rotation: number;
+  scaleFactor: number;
+};
+/**
+ * Applies every animator to a copy of `state` for one frame and returns the new state. Each animator's source value is
+ * curved, scaled by `speed * delta` (frame-rate independent), then added to or set on its target.
+ */
+declare const applyAnimators: (state: GbtScopeState, animators: Array<GbtScopeAnimator>, inputs: GbtScopeInputs) => GbtScopeState;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Curve parameters controlling how an input value (eg. pointer distance from center, scroll velocity) maps to an effect
+ * amount. Replaces the old `[min, max]` tuple form of `mouse_curve` with a richer, named shape.
+ *
+ * @see applyCurve in ./motion/curve.ts
+ */
+type GbtScopeCurve = {
+  /** Input magnitude below this is treated as 0. Default 0. */
+  deadzone?: number;
+  /** Shaping exponent (1 = linear, >1 = ease-in). Default 1. */
+  exponent?: number;
+  /** Negate the result. Default false. */
+  invert?: boolean;
+  /** Upper clamp applied after curving. Default 1. */
+  max?: number;
+  /** Lower clamp applied after curving. Default 0. */
+  min?: number;
+  /** Linear gain applied before the exponent. Default 1. */
+  multiplier?: number;
+};
+/**
+ * Shared, serializable material props for all GbtScope viewers (flat + 3D mesh). camelCase only — animation is
+ * data-driven via {@link GbtScopeAnimator}, not speed fields. `rotation`/`offset`/`scaleFactor`/`opacity` are the
+ * resting (base) values the animators build on.
+ */
+type GbtScopeMaterialProps = {
+  /** Pre-resolved texture dimensions; viewers derive this from `resolution`. */
+  dimensions?: Dimensions;
+  imageAspect?: number;
+  offset?: [number, number];
+  /** Multiplier on the offset uniform (`uOffsetAmount`). */
+  offsetScale?: number;
+  opacity?: number;
+  rotation?: number;
+  /** Multiplier on the rotation uniform (`uRotationAmount`). */
+  rotationScale?: number;
+  scaleFactor?: number;
+  segments?: number;
+  src: string;
+  tileMode?: GbtScopeTileMode;
+  tiling?: number;
+};
+/**
+ * Tiling strategy applied to the kaleidoscope pattern after the radial fold.
+ *
+ * - `none` — no wrapping; the pattern is sampled directly.
+ * - `repeat` — `fract(uv * tiling)` square repeats (the historical behavior).
+ * - `mirror` — mirrored repeats for seamless edges.
+ */
+type GbtScopeTileMode = 'mirror' | 'none' | 'repeat';
+/**
+ * Canonical default values for {@link GbtScopeMaterialProps}. `src` is required and has no default. Imported by
+ * component defaults and Storybook args so the defaults live in a single place.
+ */
+declare const defaultGbtScopeMaterialProps: {
+  imageAspect: number;
+  offset: [number, number];
+  offsetScale: number;
+  opacity: number;
+  rotation: number;
+  rotationScale: number;
+  scaleFactor: number;
+  segments: number;
+  tileMode: GbtScopeTileMode;
+  tiling: number;
+};
+/**
+ * Viewer-level props shared by both the flat and mesh viewers. Camera config is viewer-specific and declared on each
+ * component. Material props are forwarded down to {@link GbtScopeMaterialProps}.
+ */
+type GbtScopeViewerBaseProps = {
+  /** Declarative motion rules applied each frame. */
+  animators?: Array<GbtScopeAnimator>;
+  /** Aspect ratio of the host canvas. */
+  aspect_ratio?: 'parent' | number;
+  bg_color?: string;
+  /** Fixed values replacing the live pointer/scroll inputs (mock/testing). */
+  inputOverrides?: GbtScopeInputOverrides;
+  /** Canvas background; `'screen'` resolution matches the viewport. */
+  resolution?: 'screen' | Dimensions | null;
+};
+//#endregion
+//#region src/components/GbtScopeFlatViewer.d.ts
+type GbtScopeFlatViewerProps = GbtScopeViewerBaseProps & Omit<GbtScopeMaterialProps, 'dimensions'> & {
+  cameraSettings?: CameraOrthoConfig;
+  name?: string;
+};
+/** Default props for the flat viewer — single source of truth for Storybook args. */
+declare const defaultGbtScopeFlatViewerProps: {
+  animators: never[];
+  aspect_ratio: "parent" | number;
+  bg_color: string;
+  cameraSettings: CameraOrthoConfig;
+  name: string;
+  resolution: "screen" | Dimensions | null;
+  src: string;
+  imageAspect: number;
+  offset: [number, number];
+  offsetScale: number;
+  opacity: number;
+  rotation: number;
+  rotationScale: number;
+  scaleFactor: number;
+  segments: number;
+  tileMode: GbtScopeTileMode;
+  tiling: number;
+};
+declare const GbtScopeFlatViewer: ({ animators, aspect_ratio, bg_color, cameraSettings, imageAspect, inputOverrides, name, offset, offsetScale, opacity, resolution, rotation, rotationScale, scaleFactor, segments, src, tileMode, tiling }: GbtScopeFlatViewerProps) => ReactElement;
+//#endregion
+//#region src/motion/pointer.d.ts
+/** Current normalized pointer position, centered on the canvas, range [-1, 1]. */
+type PointerState = {
+  readonly x: number;
+  readonly y: number;
+};
+type PointerStateHandle = {
+  /** Attach pointerdown/pointermove/pointerleave listeners to a canvas. */
+  attach: (canvas: HTMLCanvasElement) => void;
+  /** Remove the listeners. Call from the scene's onDisposeObservable. */
+  detach: (canvas: HTMLCanvasElement) => void;
+  /** Live pointer position. Mutated internally; read it inside a render loop. */
+  state: PointerState;
+};
+/**
+ * Creates a mutable pointer-state object for use inside a Babylon.js scene setup callback. Intentionally NOT a React
+ * hook: `onSceneReady` runs outside React's render cycle, so a hook's state would be stale inside the render
+ * observable. The returned `state` object is mutated in place and is safe to read every frame.
+ *
+ * Position is normalized to [-1, 1] on both axes (canvas-relative). Uses pointer events so mouse and touch behave
+ * uniformly: a mouse resets to [0, 0] on leaving the canvas, while a touch latches at the last tap/drag position (tap
+ * center to zero it) — hover-less devices would otherwise never produce input.
+ */
+declare const createPointerState: () => PointerStateHandle;
+//#endregion
+//#region src/motion/scroll.d.ts
+/** Current scroll signals. `progress` is [0,1]; `velocity` decays toward 0. */
+type ScrollState = {
+  readonly progress: number;
+  readonly velocity: number;
+};
+type ScrollStateHandle = {
+  /** Attach scroll/wheel listeners (defaults to window). */
+  attach: (target?: HTMLElement | Window) => void;
+  /**
+   * Decay the velocity by one frame's worth (call once per frame from the driver after reading). `factor` in [0,1];
+   * lower = faster decay.
+   */
+  decay: (factor?: number) => void;
+  /** Remove listeners. Call from the scene's onDisposeObservable. */
+  detach: (target?: HTMLElement | Window) => void;
+  /** Live scroll signals. Mutated internally; read inside a render loop. */
+  state: ScrollState;
+};
+/**
+ * Creates a mutable scroll-state object for use inside a Babylon.js scene setup callback. Tracks page scroll `progress`
+ * [0,1] and a wheel-driven `velocity` that the driver decays each frame. Plain factory (not a React hook) — mirrors
+ * {@link ./pointer.createPointerState} so it can be read from the render observable.
+ */
+declare const createScrollState: () => ScrollStateHandle;
+//#endregion
+//#region src/components/GbtScopeMaterial.d.ts
+type GbtScopeMaterialComponentProps = GbtScopeMaterialProps & {
+  /** Declarative motion rules driven each frame. */
+  animators?: Array<GbtScopeAnimator>;
+  /** Fixed values replacing the live pointer/scroll inputs (mock/testing). */
+  inputOverrides?: GbtScopeInputOverrides;
+  /** Mesh the material is applied to. */
+  mesh: Mesh | null;
+  name?: string;
+  onInit?: (material: ShaderMaterial) => void;
+  onUpdate?: (material: ShaderMaterial) => void;
+  /** Live pointer + scroll inputs (created by the viewer). */
+  pointer: PointerStateHandle;
+  scroll: ScrollStateHandle;
+};
+/**
+ * Kaleidoscope shader material applied to a Babylon mesh. Static uniforms update reactively from props; the animated
+ * uniforms (rotation/offset/scaleFactor/ opacity) are driven each frame by {@link createGbtScopeDriver} from the
+ * `animators` + live pointer/scroll inputs. No Babylon Animation is used.
+ */
+declare const GbtScopeMaterial: ({ animators, dimensions, imageAspect, inputOverrides, mesh, name, offset, offsetScale, onInit, onUpdate, opacity, pointer, rotation, rotationScale, scaleFactor, scroll, segments, src, tileMode, tiling }: GbtScopeMaterialComponentProps) => null | ReactElement;
+//#endregion
+//#region src/components/GbtScopeMeshViewer.d.ts
+type GbtScopeMeshViewerProps = GbtScopeViewerBaseProps & Omit<GbtScopeMaterialProps, 'dimensions'> & {
+  cameraSettings?: CameraConfigPosition;
+  name?: string;
+};
+/** Default props for the 3D mesh viewer — single source of truth for Storybook args. */
+declare const defaultGbtScopeMeshViewerProps: {
+  animators: never[];
+  aspect_ratio: "parent" | number;
+  bg_color: string;
+  cameraSettings: CameraConfigPosition;
+  name: string;
+  resolution: "screen" | Dimensions | null;
+  src: string;
+  imageAspect: number;
+  offset: [number, number];
+  offsetScale: number;
+  opacity: number;
+  rotation: number;
+  rotationScale: number;
+  scaleFactor: number;
+  segments: number;
+  tileMode: GbtScopeTileMode;
+  tiling: number;
+};
+declare const GbtScopeMeshViewer: ({ animators, aspect_ratio, bg_color, cameraSettings, imageAspect, inputOverrides, name, offset, offsetScale, opacity, resolution, rotation, rotationScale, scaleFactor, segments, src, tileMode, tiling }: GbtScopeMeshViewerProps) => ReactElement;
+//#endregion
+//#region src/motion/curve.d.ts
+/**
+ * Maps an input value through a {@link GbtScopeCurve}: deadzone → gain → exponent → clamp → optional invert. The input
+ * is treated by magnitude (`Math.abs`), so direction is supplied by `invert`, not the sign of `value`.
+ */
+declare const applyCurve: (value: number, curve?: GbtScopeCurve) => number;
+/**
+ * Type guard distinguishing the legacy `[min, max]` tuple form of `mouse_curve` from the richer {@link GbtScopeCurve}
+ * object form.
+ */
+declare const isTupleCurve: (value: [number, number] | GbtScopeCurve) => value is [number, number];
+/**
+ * Bridges the legacy `[min, max]` tuple (plus a separate `mouse_multiplier`) into an equivalent {@link GbtScopeCurve}.
+ * With the historical defaults `[0, 0.015]` and multiplier `0.01`, `applyCurve` reproduces the old inline
+ * `Math.min(Math.max(dist * mult, min), max)` clamp exactly.
+ */
+declare const tupleToGbtScopeCurve: (tuple: [number, number], multiplier?: number) => GbtScopeCurve;
+//#endregion
+export { type Dimensions, type GbtScopeAnimator, type GbtScopeAnimatorSource, type GbtScopeAnimatorTarget, type GbtScopeCurve, GbtScopeFlatViewer, type GbtScopeFlatViewerProps, type GbtScopeInputOverrides, type GbtScopeInputs, GbtScopeMaterial, type GbtScopeMaterialComponentProps, type GbtScopeMaterialProps, GbtScopeMeshViewer, type GbtScopeMeshViewerProps, type GbtScopeState, type GbtScopeTileMode, type GbtScopeViewerBaseProps, type Point, type PointerState, type PointerStateHandle, type ScrollState, type ScrollStateHandle, type XY, applyAnimators, applyCurve, createPointerState, createScrollState, defaultGbtScopeFlatViewerProps, defaultGbtScopeMaterialProps, defaultGbtScopeMeshViewerProps, isTupleCurve, tupleToGbtScopeCurve };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/helpers.ts","../src/motion/animator.ts","../src/types.ts","../src/components/GbtScopeFlatViewer.tsx","../src/motion/pointer.ts","../src/motion/scroll.ts","../src/components/GbtScopeMaterial.tsx","../src/components/GbtScopeMeshViewer.tsx","../src/motion/curve.ts"],"mappings":";;;;;;;;;;;;KAWY;EACR;EACA;;KAEQ;EAAU;EAAW;;KACrB;KAYA,gBAAgB,6BAA6B;KAI7C,uBAAuB;EAC/B;EACA;;EAEA;EACA,UAAU;EACV;EACA,QAAQ;EACR;;KAEQ,oBAAoB,KAC5B;EAEE;;;;;;;;KCtCM;EACR,QAAQ;EACR;EACA,QAAQ;EACR;EACA,QAAQ;;;KAIA;;KAIA;;;;;KAOA,yBAAyB,QACjC,KAAK;;KAIG;EACR;EACA;EACA;EACA;EACA;;;KAIQ;EACR;EACA;EACA;EACA;;;;;;cAOS,iBACT,OAAO,eACP,WAAW,MAAM,mBACjB,QAAQ,mBACT;;;;;;;;;KC5CS;;EAER;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;KAQQ;;EAER,aAAa;EACb;EACA;;EAEA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA,WAAW;EACX;;;;;;;;;KAUQ;;;;;cAMC;;EAES;;;;;;;EAOI,UAAA;;;;;;;KAQd;;EAER,YAAY,MAAM;;EAElB;EACA;;EAEA,iBAAiB;;EAEjB,wBAAwB;;;;KC/DhB,0BAA0B,0BAClC,KAAK;EACD,iBAAiB;EACjB;;;cAKK;;EAGU;;EAMd,gBAAA;;EAEmB,uBAAW;;;;;;;;;;YAAA;;;cAIjC,uBAAsB,WAAA,cAAA,UAAA,gBAAA,aAAA,gBAAA,MAAA,QAAA,aAAA,SAAA,YAAA,UAAA,eAAA,aAAA,UAAA,KAAA,UAAA,UAmBzB,4BAA0B;;;;KCnEjB;WACC;WACA;;KAGD;;EAER,SAAS,QAAQ;;EAEjB,SAAS,QAAQ;;EAEjB,OAAO;;;;;;;;;;;cAYE,0BAAyB;;;;KCvB1B;WACC;WACA;;KAGD;;EAER,SAAS,SAAS,cAAc;;;;;EAKhC,QAAQ;;EAER,SAAS,SAAS,cAAc;;EAEhC,OAAO;;;;;;;cAgBE,yBAAwB;;;KCZzB,iCAAiC;;EAEzC,YAAY,MAAM;;EAElB,iBAAiB;;EAEjB,MAAM;EACN;EACA,UAAU,UAAU;EACpB,YAAY,UAAU;;EAEtB,SAAS;EACT,QAAQ;;;;;;;cA8BN,qBAAoB,WAAA,YAAA,aAAA,gBAAA,MAAA,MAAA,QAAA,aAAA,QAAA,UAAA,SAAA,SAAA,UAAA,eAAA,aAAA,QAAA,UAAA,KAAA,UAAA,UAqBvB,0CAAwC;;;KC1D/B,0BAA0B,0BAClC,KAAK;EACD,iBAAiB;EACjB;;;cAKK;;EAGU;;EAMd,gBAAA;;EAEe,uBAAW;;;;;;;;;;YAAA;;;cAI7B,uBAAsB,WAAA,cAAA,UAAA,gBAAA,aAAA,gBAAA,MAAA,QAAA,aAAA,SAAA,YAAA,UAAA,eAAA,aAAA,UAAA,KAAA,UAAA,UAuBzB,4BAA0B;;;;;;;cClEhB,aACT,eACA,QAAO;;;;;cAoBE,eACT,0BAA0B,kBAC3B;;;;;;cAgBU,uBACT,yBACA,wBACD"}