@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/gl/shader-grain/README.md

@@ -0,0 +1,23 @@
+# shader-grain
+
+Grano de película animado por shader, intensidad .07 (Siena).
+
+```ts
+import { createShaderGrain } from '@yewdiel21/motion-kit/gl';
+import { useShaderGrain } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const effect = createShaderGrain(root);
+effect.setProgress(.5);
+effect.setAmount(.07);
+effect.destroy();
+```
+
+Opciones compartidas: `images?: HTMLImageElement[]` (por defecto las dos primeras imágenes de root; una se repite), `progress` 0–1, `amount`, `maxDpr` 1.5. Las imágenes pueden terminar de cargar después de crear la instancia. Recursos del mismo origen o con CORS configurado antes de cargar la imagen. El kit no descarga imágenes. Root debe tener dimensiones; el canvas decorativo cubre su caja y deja el HTML accesible debajo.
+
+Controles: `setProgress(0..1)`, `setAmount(0..100)`, `pause()`, `resume()`, `mode: 'webgl' | 'none'`, `destroy()`. React: `useShaderGrain(ref, options, deps)`, ref a la instancia. No usa `autoInit`: importar explícitamente desde `/gl` conserva la separación de GPU del paquete principal.
+
+Pausa fuera de pantalla y con pestaña oculta. Movimiento reducido: frame fijo, con controles manuales. Sin WebGL, error de textura o contexto perdido: canvas oculto, HTML original disponible. Contexto restaurado: recompila y vuelve a cargar texturas. Destroy libera texturas, buffer, shaders y programa, desconecta observers y restaura la clase original.
+
+Siena `siena.webgl.post`: intensidad .07. Ruido propio con semilla temporal a 24 Hz; amount 0 conserva la imagen. No reproduce el pipeline de postprocesado del sitio completo.
+
+Desde 0.9.0. Fuentes de parámetros: `REA - Dousan OFFFICE Siena/`. Shaders originales, sin redistribuir código ni assets de terceros.

package/src/gl/shader-grain/create-shader-grain.ts

@@ -0,0 +1,7 @@
+import { createShaderEffect, type ShaderEffectInstance, type ShaderEffectOptions } from '../shared/create-shader-effect';
+import { grainFragment } from './shader';
+
+export type ShaderGrainOptions = ShaderEffectOptions;
+export type ShaderGrainInstance = ShaderEffectInstance;
+export const createShaderGrain = (root: HTMLElement | null, options: ShaderGrainOptions = {}): ShaderGrainInstance =>
+  createShaderEffect(root, grainFragment, { amount: 0.07, ...options });

package/src/gl/shader-grain/shader.ts

@@ -0,0 +1,6 @@
+export const grainFragment = `
+void main() {
+  vec4 color = texture2D(uImage0, cover(vUv, uImageSize0));
+  float grain = noise(floor(vUv * uSize) + floor(uTime * 24.)) - .5;
+  gl_FragColor = vec4(color.rgb + grain * uAmount, color.a);
+}`;

package/src/gl/shared/create-shader-effect.ts

@@ -0,0 +1,186 @@
+import { whileVisible } from '../../core/loop';
+import { clamp } from '../../core/math';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { fragmentHeader, fullscreenVertex } from './shaders';
+
+export interface ShaderEffectOptions {
+  images?: HTMLImageElement[];
+  progress?: number;
+  amount?: number;
+  maxDpr?: number;
+}
+export interface ShaderEffectInstance extends Instance {
+  readonly mode: 'webgl' | 'none';
+  setProgress(progress: number): void;
+  setAmount(amount: number): void;
+  pause(): void;
+  resume(): void;
+}
+
+interface Renderer {
+  draw(time: number, progress: number, amount: number): void;
+  upload(): boolean;
+  destroy(): void;
+}
+
+function createRenderer(canvas: HTMLCanvasElement, fragment: string, images: HTMLImageElement[]): Renderer {
+  const gl = canvas.getContext('webgl', { alpha: true, antialias: false, premultipliedAlpha: false });
+  if (!gl) throw new Error('WebGL unavailable');
+  const releases: Array<() => void> = [];
+  const destroy = () => { releases.splice(0).reverse().forEach((release) => release()); };
+  try {
+    const compile = (type: number, source: string) => {
+      const shader = gl.createShader(type);
+      if (!shader) throw new Error('Shader allocation failed');
+      releases.push(() => gl.deleteShader(shader));
+      gl.shaderSource(shader, source);
+      gl.compileShader(shader);
+      if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) throw new Error(gl.getShaderInfoLog(shader) ?? 'Shader failed');
+      return shader;
+    };
+    const vertex = compile(gl.VERTEX_SHADER, fullscreenVertex);
+    const pixel = compile(gl.FRAGMENT_SHADER, fragmentHeader + fragment);
+    const program = gl.createProgram();
+    if (!program) throw new Error('Program allocation failed');
+    releases.push(() => gl.deleteProgram(program));
+    gl.attachShader(program, vertex);
+    gl.attachShader(program, pixel);
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(gl.getProgramInfoLog(program) ?? 'Link failed');
+    gl.useProgram(program);
+    const buffer = gl.createBuffer();
+    if (!buffer) throw new Error('Buffer allocation failed');
+    releases.push(() => gl.deleteBuffer(buffer));
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    const attribute = gl.getAttribLocation(program, 'position');
+    gl.enableVertexAttribArray(attribute);
+    gl.vertexAttribPointer(attribute, 2, gl.FLOAT, false, 0, 0);
+    const names = ['uSize', 'uImageSize0', 'uImageSize1', 'uTime', 'uProgress', 'uAmount', 'uImage0', 'uImage1', 'uHasImage'] as const;
+    const uniforms = Object.fromEntries(names.map((name) => [name, gl.getUniformLocation(program, name)]));
+    const textures = [0, 1].map((index) => {
+      const texture = gl.createTexture();
+      if (!texture) throw new Error('Texture allocation failed');
+      releases.push(() => gl.deleteTexture(texture));
+      gl.activeTexture(gl.TEXTURE0 + index);
+      gl.bindTexture(gl.TEXTURE_2D, texture);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([26, 40, 55, 255]));
+      gl.uniform1i(uniforms[`uImage${index}`]!, index);
+      return texture;
+    });
+    const upload = () => {
+      if (images.some((image) => !image.complete || !image.naturalWidth)) return false;
+      gl.useProgram(program);
+      images.slice(0, 2).forEach((image, index) => {
+        gl.activeTexture(gl.TEXTURE0 + index);
+        gl.bindTexture(gl.TEXTURE_2D, textures[index]!);
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
+      });
+      return true;
+    };
+    return {
+      upload,
+      draw(time, progress, amount) {
+        gl.viewport(0, 0, canvas.width, canvas.height);
+        gl.useProgram(program);
+        gl.uniform2f(uniforms.uSize!, canvas.width, canvas.height);
+        [0, 1].forEach((index) => gl.uniform2f(uniforms[`uImageSize${index}`]!, images[index]?.naturalWidth || 1, images[index]?.naturalHeight || 1));
+        gl.uniform1f(uniforms.uTime!, time);
+        gl.uniform1f(uniforms.uProgress!, progress);
+        gl.uniform1f(uniforms.uAmount!, amount);
+        gl.uniform1f(uniforms.uHasImage!, images.length ? 1 : 0);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+      },
+      destroy,
+    };
+  } catch (error) {
+    destroy();
+    throw error;
+  }
+}
+
+export function createShaderEffect(root: HTMLElement | null, fragment: string, options: ShaderEffectOptions = {}): ShaderEffectInstance {
+  if (!root) return inert({ mode: 'none' as const, setProgress() {}, setAmount() {}, pause() {}, resume() {} });
+  const scope = createScope();
+  const canvas = document.createElement('canvas');
+  canvas.className = 'mk-shader__canvas';
+  canvas.setAttribute('aria-hidden', 'true');
+  canvas.hidden = true;
+  const images = (options.images ?? [...root.querySelectorAll('img')]).slice(0, 2);
+  if (images.length === 1) images.push(images[0]!);
+  let renderer: Renderer | null = null;
+  let mode: ShaderEffectInstance['mode'] = 'none';
+  let progress = clamp(options.progress ?? 0, 0, 1);
+  let amount = clamp(options.amount ?? 1, 0, 100);
+  let time = 0;
+  let paused = false;
+  let ready = false;
+  const draw = () => {
+    if (!scope.disposed && ready && renderer && mode === 'webgl') renderer.draw(time, progress, amount);
+  };
+  const fallback = () => {
+    mode = 'none';
+    ready = false;
+    canvas.hidden = true;
+  };
+  const load = () => {
+    if (scope.disposed || !renderer) return;
+    try {
+      ready = renderer.upload();
+      canvas.hidden = !ready;
+      if (ready) mode = 'webgl';
+      draw();
+    } catch { fallback(); }
+  };
+  const resize = (render = true) => {
+    if (scope.disposed) return;
+    const rect = root.getBoundingClientRect();
+    const dpr = Math.min(typeof devicePixelRatio === 'number' ? devicePixelRatio : 1, Math.max(0.5, options.maxDpr ?? 1.5));
+    canvas.width = Math.max(1, Math.round(rect.width * dpr));
+    canvas.height = Math.max(1, Math.round(rect.height * dpr));
+    if (render) draw();
+  };
+  const initialize = () => {
+    renderer?.destroy();
+    renderer = null;
+    try {
+      renderer = createRenderer(canvas, fragment, images);
+      mode = 'webgl';
+      resize(false);
+      load();
+      return true;
+    } catch { fallback(); return false; }
+  };
+  if (!initialize()) { scope.dispose(); return inert({ mode: 'none' as const, setProgress() {}, setAmount() {}, pause() {}, resume() {} }); }
+  scope.attr(root, 'class', `${root.className} mk-shader`.trim());
+  root.append(canvas);
+  scope.add(() => { renderer?.destroy(); renderer = null; canvas.remove(); mode = 'none'; });
+  images.forEach((image) => {
+    scope.on(image, 'load', load);
+    scope.on(image, 'error', fallback);
+  });
+  scope.on(canvas, 'webglcontextlost', (event) => { event.preventDefault(); fallback(); });
+  scope.on(canvas, 'webglcontextrestored', initialize);
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => resize())).observe(root);
+  scope.on(window, 'resize', () => resize());
+  if (!reduced()) scope.add(whileVisible(root, (dt) => {
+    if (paused || document.hidden || mode === 'none') return;
+    time += dt / 60;
+    draw();
+  }));
+  return {
+    get mode() { return mode; },
+    setProgress(value) { if (scope.disposed || !Number.isFinite(value)) return; progress = clamp(value, 0, 1); draw(); },
+    setAmount(value) { if (scope.disposed || !Number.isFinite(value)) return; amount = clamp(value, 0, 100); draw(); },
+    pause() { paused = true; },
+    resume() { paused = false; },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/gl/shared/shader.css

@@ -0,0 +1,3 @@
+.mk-shader { position: relative; isolation: isolate; overflow: hidden; }
+.mk-shader__canvas { position: absolute; inset: 0; width: 100%; height: 100%; pointer-events: none; }
+.mk-shader__canvas[hidden] { display: none; }

package/src/gl/shared/shaders.ts

@@ -0,0 +1,30 @@
+export const fullscreenVertex = `
+attribute vec2 position;
+varying vec2 vUv;
+void main() {
+  vUv = position * .5 + .5;
+  gl_Position = vec4(position, 0., 1.);
+}`;
+
+export const fragmentHeader = `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D uImage0;
+uniform sampler2D uImage1;
+uniform vec2 uSize;
+uniform vec2 uImageSize0;
+uniform vec2 uImageSize1;
+uniform float uTime;
+uniform float uProgress;
+uniform float uAmount;
+uniform float uHasImage;
+vec2 cover(vec2 uv, vec2 imageSize) {
+  float aspect = uSize.x / uSize.y;
+  float imageAspect = imageSize.x / imageSize.y;
+  vec2 scale = vec2(min(aspect / imageAspect, 1.), min(imageAspect / aspect, 1.));
+  return (uv - .5) * scale + .5;
+}
+float noise(vec2 point) {
+  return fract(sin(dot(point, vec2(12.9898, 78.233))) * 43758.5453);
+}
+`;

package/src/index.ts

@@ -0,0 +1,177 @@
+// Core
+export { registerMotion, gsap, ScrollTrigger, SplitText, CustomEase, Flip, ELASTIC, EASE } from './core/gsap';
+export { PATHS, springPath, SIGNATURE_LINEAR } from './core/curves';
+export { TIMING } from './core/timing';
+export {
+  channels,
+  stepChannel,
+  createChannelState,
+  spring,
+  eased,
+  bezier,
+  easeOut,
+  easeOutCubic,
+  easeInCubic,
+  springEase,
+  type Channel,
+  type ChannelState,
+} from './core/channels';
+export { splitWords, splitGraphemes, type Split, type SplitWordsOptions } from './core/split';
+export { requestFrame, nextFrame } from './core/frame';
+export { clearStyles, MORPH_STYLES } from './core/styles';
+export { motionSpring, springDuration, springLinear, type MotionSpring } from './core/physics-spring';
+export { trackScroll, type ScrollTrack, type ScrollTrackOptions } from './core/scroll-track';
+
+// Motion functions (no instance)
+export { flowIn, flowOut, stepChange, type FlowInOptions, type FlowOutOptions } from './motion/flow';
+export { flowInMenu, flowInPalette, flowInForm, flowInLanding, flowInContent } from './motion/entrances';
+export { revealFrom, type RevealOptions, type RevealHandle, type RevealSpeed } from './motion/reveal';
+export { toggleDetails, installDetailsMotion } from './motion/details';
+export { slideIndicator, type IndicatorOptions } from './motion/indicator';
+export { countTo, revealCounter, tweenNumber, type CountOptions, type NumberFormat } from './motion/count';
+export { captureLayout, reflowLayout, type CapturedLayout } from './motion/layout';
+export { enterMessages, fitComposer, scrollToLatest, type EnterMessagesOptions } from './motion/chat';
+export { animate, leave, ANIMATIONS, type AnimationName, type ExitName, type AnimateOptions, type LeaveOptions } from './motion/effects';
+export { confetti, type ConfettiOptions, type ConfettiHandle } from './motion/confetti';
+export { reduced, entrances, MK_HEAD_SCRIPT } from './core/reduced';
+export { subscribe, whileVisible, type Tick } from './core/loop';
+export { createSpring, type Spring, type Vec } from './core/spring';
+export { clamp, lerp, damp, wrap, mapRange } from './core/math';
+export { bindPointer, pointer, takeMovement } from './core/pointer';
+export { createScope, type Scope } from './core/scope';
+export type { Instance, Cleanup } from './core/types';
+
+// Recipes
+export { createSpringCards, type SpringCardsOptions, type SpringCardsInstance } from './recipes/spring-cards/create-spring-cards';
+export {
+  createCurvedCarousel,
+  type CurvedCarouselOptions,
+  type CurvedCarouselInstance,
+} from './recipes/curved-carousel/create-curved-carousel';
+export { createPile, pileLayers, pileStyle, type PileOptions, type PileInstance, type PileLayer } from './recipes/pile/create-pile';
+export { createWords, type WordsOptions, type WordsInstance } from './recipes/words/create-words';
+export { createFlow, type FlowOptions, type FlowInstance } from './recipes/flow/create-flow';
+export { createPop, type PopOptions, type PopInstance } from './recipes/pop/create-pop';
+export { createFitText, type FitTextOptions, type FitTextInstance } from './recipes/fit-text/create-fit-text';
+export { createStretchFooter, type StretchFooterOptions, type StretchFooterInstance } from './recipes/stretch-footer/create-stretch-footer';
+export { createRadialMenu, type RadialMenuOptions, type RadialMenuInstance } from './recipes/radial-menu/create-radial-menu';
+export { createTabs, type TabsOptions, type TabsInstance } from './recipes/tabs/create-tabs';
+export { createCounter, type CounterOptions, type CounterInstance } from './recipes/counter/create-counter';
+export { createDetails, type DetailsInstance } from './recipes/details/create-details';
+export { createReveal, type RevealRecipeOptions, type RevealInstance } from './recipes/reveal/create-reveal';
+export { createReflow, type ReflowOptions, type ReflowInstance } from './recipes/reflow/create-reflow';
+export { createSlotText, type SlotTextOptions, type SlotTextInstance } from './recipes/slot-text/create-slot-text';
+export {
+  createSortable,
+  moveItem,
+  type SortableOptions,
+  type SortableInstance,
+  type SortableLabels,
+  type ReorderDetail,
+} from './recipes/sortable/create-sortable';
+export { createMaskText, type MaskTextOptions, type MaskTextInstance } from './recipes/mask-text/create-mask-text';
+export { createCascade, type CascadeOptions, type CascadeInstance } from './recipes/cascade/create-cascade';
+export { createTextRoll, type TextRollOptions, type TextRollInstance } from './recipes/text-roll/create-text-roll';
+export { createLetters, type LettersOptions, type LettersInstance } from './recipes/letters/create-letters';
+export { createParallax, type ParallaxOptions, type ParallaxInstance } from './recipes/parallax/create-parallax';
+export { createDepthGrid, type DepthGridOptions, type DepthGridInstance } from './recipes/depth-grid/create-depth-grid';
+export { createFrameZoom, type FrameZoomOptions, type FrameZoomInstance } from './recipes/frame-zoom/create-frame-zoom';
+export { createContrast, type ContrastOptions, type ContrastInstance } from './recipes/contrast/create-contrast';
+export { createMarquee, type MarqueeOptions, type MarqueeInstance } from './recipes/marquee/create-marquee';
+export { createCardDock, type CardDockOptions, type CardDockInstance } from './recipes/card-dock/create-card-dock';
+export { createSnapStrip, type SnapStripOptions, type SnapStripInstance } from './recipes/snap-strip/create-snap-strip';
+export { createFillText, type FillTextOptions, type FillTextInstance } from './recipes/fill-text/create-fill-text';
+export { createTicketMenu, type TicketMenuOptions, type TicketMenuInstance } from './recipes/ticket-menu/create-ticket-menu';
+export { createInfiniteReel, type InfiniteReelOptions, type InfiniteReelInstance } from './recipes/infinite-reel/create-infinite-reel';
+export { createRepelBento, type RepelBentoOptions, type RepelBentoInstance } from './recipes/repel-bento/create-repel-bento';
+export { createRotator, type RotatorOptions, type RotatorInstance } from './recipes/rotator/create-rotator';
+export { createDragRuler, type DragRulerOptions, type DragRulerInstance } from './recipes/drag-ruler/create-drag-ruler';
+export { createDockPill, type DockPillOptions, type DockPillInstance } from './recipes/dock-pill/create-dock-pill';
+
+// Components (engines; custom elements in /elements, React components in /react)
+export { createThemePicker, type ThemePickerOptions, type ThemePickerInstance } from './components/theme-picker/engine';
+
+// Surface engines (dialogs, menus, toasts build on these)
+export { openModal, closeModal, fadeBackdrop, ghostOf, backdropVeil, transparentColor } from './motion/surface';
+export {
+  morphOpen,
+  morphClose,
+  morphCloseWithGhost,
+  showOrigin,
+  releaseShared,
+  shareInto,
+  shareBack,
+  isMorphing,
+  stopMorph,
+  type MorphOpenOptions,
+  type MorphCloseOptions,
+} from './motion/morph';
+export { liquidOpen, liquidClose } from './motion/liquid';
+export { sheetOpen, sheetClose, pushUnderlay, releaseUnderlay } from './motion/sheet';
+export { attachDragDismiss, type DragDismissOptions } from './motion/drag-dismiss';
+export {
+  attachFloating,
+  liftWindow,
+  dockWindow,
+  savedFloat,
+  forgetFloat,
+  floatingAvailable,
+  clampRect,
+  type FloatingOptions,
+  type Rect,
+} from './motion/floating';
+export { anchorSurface, clearAnchor, type Viewport } from './motion/anchor';
+export {
+  createDialog,
+  type DialogOptions,
+  type DialogInstance,
+  type DialogVariant,
+  type DialogPlacement,
+  type DialogLabels,
+} from './components/dialog/engine';
+export { createMenu, type MenuOptions, type MenuInstance } from './components/menu/engine';
+export { createToaster, type ToasterOptions, type ToasterLabels, type ToasterInstance } from './components/toast/engine';
+export {
+  createChatBackground,
+  chatBackgroundOf,
+  type ChatBackgroundOptions,
+  type ChatBackgroundInstance,
+} from './components/chat-background/engine';
+export { audioEnergy, type AudioEnergy } from './components/chat-background/audio';
+export {
+  createChat,
+  chatMessage,
+  capturePending,
+  morphPendingToReply,
+  PENDING_ID,
+  type ChatOptions,
+  type ChatInstance,
+  type ChatLabels,
+  type ChatRole,
+} from './components/chat/engine';
+export {
+  createNav,
+  revealShell,
+  NAV_STYLES,
+  type NavOptions,
+  type NavInstance,
+  type NavStyle,
+  type NavigateDetail,
+} from './components/nav/engine';
+export { createSteps, type StepsOptions, type StepsInstance, type StepDetail } from './components/steps/engine';
+export { createCursor, type CursorOptions, type CursorInstance, type CursorVariant } from './components/cursor/engine';
+export {
+  toast,
+  dismissToast,
+  removeToast,
+  clearToasts,
+  getToasts,
+  subscribeToasts,
+  toastTimers,
+  TOAST_LIMIT,
+  type ToastOptions,
+  type ToastItem,
+  type ToastTone,
+  type ToastAction,
+} from './components/toast/store';
+export { createIsland, type IslandOptions, type IslandInstance } from './components/island/engine';

package/src/motion/anchor.ts

@@ -0,0 +1,45 @@
+/*
+ * Place an anchored surface (menu, anchored dialog) under its opener, left
+ * aligned with it, inside the viewport: above when there is no room below,
+ * beside it when neither fits (never covering it), else as low as it can go.
+ * Under 680 px the stylesheet's full-screen sheet wins, so the inline place is cleared.
+ */
+
+const EDGE = 16;
+const GAP = 8;
+const PHONE = 680;
+/** Shorthands and longhands: some engines keep the longhands of a removed shorthand. */
+const PLACED = ['top', 'left', 'right', 'bottom', 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left'];
+
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+export function anchorSurface(surface: HTMLElement, origin: DOMRect | null | undefined, viewport?: Viewport) {
+  const view = viewport ?? { width: innerWidth, height: innerHeight };
+  if (!origin || view.width < PHONE) {
+    for (const side of PLACED) surface.style.removeProperty(side);
+    return;
+  }
+  const box = surface.getBoundingClientRect();
+  const clampLeft = (value: number) => Math.max(EDGE, Math.min(value, view.width - box.width - EDGE));
+  const below = origin.bottom + GAP;
+  const above = origin.top - GAP - box.height;
+  const lowest = Math.max(EDGE, view.height - box.height - EDGE);
+  const besideRight = origin.right + GAP;
+  const besideLeft = origin.left - GAP - box.width;
+  let top: number;
+  let left: number;
+  if (below <= lowest) [top, left] = [below, clampLeft(origin.left)];
+  else if (above >= EDGE) [top, left] = [above, clampLeft(origin.left)];
+  else if (besideRight + box.width <= view.width - EDGE) [top, left] = [Math.min(Math.max(EDGE, origin.top), lowest), besideRight];
+  else if (besideLeft >= EDGE) [top, left] = [Math.min(Math.max(EDGE, origin.top), lowest), besideLeft];
+  else [top, left] = [lowest, clampLeft(origin.left)];
+  Object.assign(surface.style, { margin: '0', top: `${Math.round(top)}px`, left: `${Math.round(left)}px`, right: 'auto', bottom: 'auto' });
+}
+
+/** Remove the inline place anchorSurface wrote. */
+export function clearAnchor(surface: HTMLElement) {
+  for (const side of PLACED) surface.style.removeProperty(side);
+}

package/src/motion/chat.ts

@@ -0,0 +1,97 @@
+import { gsap, EASE, registerMotion } from '../core/gsap';
+import { reduced } from '../core/reduced';
+import { TIMING } from '../core/timing';
+import { splitWords } from '../core/split';
+
+/*
+ * Stepbro's chat (PrettyChat): new bubbles grow from their speaker's side
+ * (scale .5, 24 px blur, 0.7 s, 60 ms apart) while their words rise into place
+ * (16 px, 6 px blur, 0.25 s, 50 ms apart, back.out). Words are split only for
+ * the animation; tables and code stay whole; if splitting would reflow the text
+ * by more than half a line, the text block moves as one.
+ */
+
+export interface EnterMessagesOptions {
+  /** Text inside each bubble whose words rise. */
+  textSelector?: string;
+}
+
+const isUser = (bubble: HTMLElement) => bubble.dataset.mkRole === 'user' || bubble.classList.contains('user');
+
+export function enterMessages(bubbles: HTMLElement[], { textSelector = '[data-mk-text], .message-text' }: EnterMessagesOptions = {}) {
+  if (!bubbles.length || reduced()) return null;
+  registerMotion();
+  const reverts: Array<() => void> = [];
+  const cleanup = () => {
+    for (const revert of reverts.splice(0)) revert();
+  };
+  const timeline = gsap.timeline({ onComplete: cleanup, onInterrupt: cleanup });
+  bubbles.forEach((bubble, index) => {
+    gsap.set(bubble, { transformOrigin: isUser(bubble) ? '100% 50%' : '0% 50%' });
+    timeline.fromTo(
+      bubble,
+      { scale: 0.5, autoAlpha: 0, filter: 'blur(24px)' },
+      { scale: 1, autoAlpha: 1, filter: 'blur(0px)', duration: TIMING.bubble, ease: EASE.signature, clearProps: 'transform,opacity,visibility,filter' },
+      index * TIMING.bubbleStagger,
+    );
+    const text = bubble.querySelector<HTMLElement>(textSelector);
+    if (!text) return;
+    const before = text.offsetHeight;
+    const split = splitWords(text);
+    const lineHeight = parseFloat(getComputedStyle(text).lineHeight) || 0;
+    let targets: HTMLElement[] = split.parts;
+    if (!split.parts.length || text.offsetHeight - before > lineHeight / 2) {
+      split.revert();
+      targets = [text];
+    } else reverts.push(() => split.revert());
+    timeline.fromTo(
+      targets,
+      { y: 16, autoAlpha: 0, filter: 'blur(6px)' },
+      {
+        y: 0,
+        autoAlpha: 1,
+        filter: 'blur(0px)',
+        duration: TIMING.word,
+        ease: 'back.out(1)',
+        stagger: TIMING.wordStagger,
+        clearProps: 'transform,opacity,visibility,filter',
+      },
+      index * TIMING.bubbleStagger,
+    );
+  });
+  return timeline;
+}
+
+/** A message box grows or shrinks to its text (0.18 s, power2.out), from `min` px. */
+export function fitComposer(field: HTMLTextAreaElement, min = 64) {
+  const from = field.offsetHeight;
+  field.style.height = 'auto';
+  const to = Math.max(min, field.scrollHeight);
+  field.style.height = `${from}px`;
+  if (from === to || reduced()) {
+    field.style.height = `${to}px`;
+    return null;
+  }
+  registerMotion();
+  return gsap.to(field, { height: to, duration: TIMING.composer, ease: 'power2.out', overwrite: 'auto' });
+}
+
+/** Scroll a conversation to its newest message (0.35 s, Stepbro's chat scroll curve). */
+export function scrollToLatest(scroller: HTMLElement) {
+  const top = scroller.scrollHeight - scroller.clientHeight;
+  if (reduced()) {
+    scroller.scrollTop = top;
+    return null;
+  }
+  registerMotion();
+  const state = { top: scroller.scrollTop };
+  return gsap.to(state, {
+    top,
+    duration: TIMING.chatScroll,
+    ease: EASE.chatScroll,
+    overwrite: 'auto',
+    onUpdate: () => {
+      scroller.scrollTop = state.top;
+    },
+  });
+}