@buoy-gg/shared-ui 7.0.31 → 7.0.33

package/lib/module/ui/otto/OttoSprite.js

@@ -0,0 +1,496 @@
+"use strict";
+
+/**
+ * Otto in React Native — core APIs only, so the same file runs in Expo, in a
+ * bare RN CLI app, and on the web through react-native-web.
+ *
+ *   <Otto state="thinking" pixelSize={4} />   the shipping sprite
+ *   <Otto state="reel" />                     plays the demo schedule
+ *   <OttoStill pixelSize={1} />               frame 0, no clock (icons, stills)
+ *   <OttoPixels grid={…} pixelSize={…} />     paint any frame as Views
+ *   useOttoAnchorMotion(state, …)             move a prop in lock-step with
+ *                                             Otto's hands (the tool scenes)
+ *
+ * How the shipping sprite works (winner of the buoy-optimize rounds, see
+ * OTTO_PERF_PLAN.md): each layer of a state's animation is a STRIP of its
+ * distinct frames, mounted once as static Views (merged rectangles), inside
+ * an overflow-hidden window one frame wide. A clock slides the strip:
+ *
+ *   native  core `Animated` on the native driver — one looping linear timing
+ *           mapped to strip offsets by a step interpolation
+ *   web     CSS keyframes with `step-end` timing (react-native-web's
+ *           `animationKeyframes` style), the zero-JS path in a browser
+ *
+ * Zero JS per tick on both, no React commits, and it keeps moving while the
+ * JS thread is blocked — exactly when a "working" Otto is on screen. On the
+ * iOS sim: 60 UI / 59 JS FPS at one sprite (the page's own floor) where the
+ * old per-tick renderer dropped UI frames.
+ *
+ * ONE TIMEBASE. Body, water and any anchored prop derive from the same
+ * `units` span (see `motionUnits`) at the same duration and start in the same
+ * commit, so they can never drift out of phase with each other.
+ */
+import { useEffect, useRef, useState } from "react";
+import { Animated, Easing, Platform, StyleSheet, View } from "react-native";
+import { OTTO_ANCHORS, OTTO_GRID, OTTO_REEL, ottoRuns, renderOttoFrame } from "./ottoEngine.js";
+import { WATER_FRAMES, WATER_ROW0, WATER_ROWS, ottoSheets } from "./ottoSheet.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const IS_WEB = Platform.OS === "web";
+
+/** Every anchor in the engine repeats within 16 ticks. */
+const ANCHOR_PERIOD = 16;
+/** The water wave holds each frame for 2 ticks. */
+const WATER_UNITS_PER_STEP = 2;
+function gcd(a, b) {
+  return b === 0 ? a : gcd(b, a % b);
+}
+function lcm(a, b) {
+  return a * b / gcd(a, b);
+}
+
+/**
+ * The tick span every layer of a state loops over. It is a common multiple of
+ * the body cycle and the anchor cycle, so a prop held in Otto's hand and the
+ * hand itself repeat together.
+ */
+export function motionUnits(state, keyline = true) {
+  return lcm(ottoSheets(state, keyline).period, ANCHOR_PERIOD);
+}
+
+// ---------------------------------------------------------------- pixels --
+
+/** Pure renderer: a frame → coloured run Views. Fine for stills; costly per tick. */
+export function OttoPixels({
+  grid,
+  pixelSize,
+  style
+}) {
+  const side = OTTO_GRID * pixelSize;
+  const runs = ottoRuns(grid);
+  const spans = [];
+  let rowY = -1;
+  let rowIndex = 0;
+  for (const r of runs) {
+    if (r.y !== rowY) {
+      rowY = r.y;
+      rowIndex = 0;
+    }
+    spans.push(/*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        left: r.x * pixelSize,
+        top: r.y * pixelSize,
+        width: r.w * pixelSize,
+        height: pixelSize,
+        backgroundColor: r.color
+      }
+    }, `${r.y}:${rowIndex++}`));
+  }
+  return /*#__PURE__*/_jsx(View, {
+    pointerEvents: "none",
+    style: [{
+      width: side,
+      height: side
+    }, style],
+    children: spans
+  });
+}
+
+// ---------------------------------------------------------------- still ---
+
+/** Frame 0 of a state, no clock — safe on screens that must not re-render. */
+export function OttoStill({
+  state = "static",
+  pixelSize = 1,
+  water,
+  keyline,
+  style
+}) {
+  const grid = renderOttoFrame(state, 0, {
+    water,
+    keyline
+  });
+  return /*#__PURE__*/_jsx(OttoPixels, {
+    grid: grid,
+    pixelSize: pixelSize,
+    style: style
+  });
+}
+
+// ---------------------------------------------------------------- reel ----
+
+/**
+ * Walks the demo reel: which state plays now. One React state change per
+ * schedule entry (every few seconds), nothing per tick.
+ */
+export function useOttoReel(enabled, tickMs = 140, active = true) {
+  const [idx, setIdx] = useState(0);
+  useEffect(() => {
+    if (!enabled || !active) return;
+    const len = OTTO_REEL[idx % OTTO_REEL.length][1];
+    const id = setTimeout(() => setIdx(i => (i + 1) % OTTO_REEL.length), len * tickMs);
+    return () => clearTimeout(id);
+  }, [enabled, active, idx, tickMs]);
+  return OTTO_REEL[idx % OTTO_REEL.length][0];
+}
+
+// ---------------------------------------------------------------- clock ---
+
+/** A style that moves a view through offsets in lock-step with Otto's clock. */
+
+const EPS = 0.0001;
+
+/**
+ * The layer the clock moves.
+ *
+ * On native this has to be an `Animated.View` — it carries interpolated
+ * values. On web the motion is a COMPILED CSS class (see `webStepStyle`), and
+ * `Animated.View` flattens its style prop into a fresh object, which loses the
+ * identity react-native-web looks the compiled rules up by; the keyframes are
+ * then silently dropped and the sprite sits on frame 0. So the web path takes
+ * a plain View, which passes the class straight through.
+ */
+const OttoMotionView = IS_WEB ? View : Animated.View;
+export { OttoMotionView };
+
+/**
+ * Web keyframes, compiled once per motion pattern.
+ *
+ * react-native-web only turns `animationKeyframes` into real `@keyframes`
+ * rules through `StyleSheet.create` — its inline-style path drops the prop
+ * without a warning. Patterns repeat heavily across a page of sprites (every
+ * Otto shares one water wave, every state of a group shares body cycles), so
+ * the cache keeps the sheet small and the render cheap.
+ */
+const webStyleCache = new Map();
+function webStepStyle(offsets, unitsPerStep, units, tickMs, steps, at) {
+  const key = `${units}/${unitsPerStep}/${tickMs}/${offsets.map(o => `${o.x},${o.y}`).join("|")}`;
+  const cached = webStyleCache.get(key);
+  if (cached) return cached;
+
+  // Keyframe blocks skip react-native-web's style preprocessor, so the value
+  // has to be CSS already — an RN transform ARRAY compiles to an empty block.
+  const css = o => `translateX(${o.x}px) translateY(${o.y}px)`;
+  const keyframes = {};
+  for (let k = 0; k < steps; k++) {
+    const pct = k * unitsPerStep / units * 100;
+    keyframes[`${pct.toFixed(4)}%`] = {
+      transform: css(at(k))
+    };
+  }
+  keyframes["100%"] = {
+    transform: css(at(steps - 1))
+  };
+
+  // react-native-web's CSS-animation style props (not part of RN's ViewStyle).
+  const style = StyleSheet.create({
+    motion: {
+      animationKeyframes: [keyframes],
+      animationDuration: `${units * tickMs}ms`,
+      animationTimingFunction: "step-end",
+      animationIterationCount: "infinite",
+      animationFillMode: "both"
+    }
+  }).motion;
+  webStyleCache.set(key, style);
+  return style;
+}
+
+/**
+ * Otto's timebase: a clock that runs `units` ticks and loops.
+ *
+ *   native → one `Animated.Value` on the native driver (zero JS per tick)
+ *   web    → nothing to drive; CSS keyframes carry the motion (zero JS at all)
+ *
+ * Every consumer of the SAME state builds the same `units` and duration and
+ * starts in the same commit, which is what keeps layers in phase.
+ */
+function useOttoMotionClock(units, tickMs, active, restartKey) {
+  const value = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    if (IS_WEB) return;
+    value.setValue(0);
+    if (!active) return;
+    const loop = Animated.loop(Animated.timing(value, {
+      toValue: units,
+      duration: units * tickMs,
+      easing: Easing.linear,
+      useNativeDriver: true,
+      isInteraction: false
+    }), {
+      resetBeforeIteration: true
+    });
+    loop.start();
+    return () => loop.stop();
+  }, [value, units, tickMs, active, restartKey]);
+  return value;
+}
+
+/**
+ * Turn a repeating offset pattern into a style on that clock. `offsets[k]` is
+ * where the view sits during tick `k·unitsPerStep`; the pattern repeats until
+ * `units` is filled, so patterns of different lengths share one timebase.
+ */
+function stepStyle(value, offsets, unitsPerStep, units, tickMs, active) {
+  const steps = Math.max(1, Math.round(units / unitsPerStep));
+  const at = k => offsets[k % offsets.length] ?? {
+    x: 0,
+    y: 0
+  };
+  if (!active || offsets.length <= 1) {
+    const o = at(0);
+    return {
+      transform: [{
+        translateX: o.x
+      }, {
+        translateY: o.y
+      }]
+    };
+  }
+  if (IS_WEB) return webStepStyle(offsets, unitsPerStep, units, tickMs, steps, at);
+  const inputRange = [];
+  const xs = [];
+  const ys = [];
+  for (let k = 0; k < steps; k++) {
+    const o = at(k);
+    inputRange.push(k * unitsPerStep, (k + 1) * unitsPerStep - EPS);
+    xs.push(o.x, o.x);
+    ys.push(o.y, o.y);
+  }
+  return {
+    transform: [{
+      translateX: value.interpolate({
+        inputRange,
+        outputRange: xs,
+        extrapolate: "clamp"
+      })
+    }, {
+      translateY: value.interpolate({
+        inputRange,
+        outputRange: ys,
+        extrapolate: "clamp"
+      })
+    }]
+  };
+}
+/**
+ * Move a prop in lock-step with Otto's hands. `OTTO_ANCHORS[state]` publishes
+ * where the hand is each tick; this turns that into the same kind of clocked
+ * style the sprite itself uses, on the same timebase, so the two can't drift.
+ *
+ * Returns `null` for a state that has no anchor.
+ */
+export function useOttoAnchorMotion(state, pixelSize, tickMs = 140, active = true, keyline = true) {
+  const anchorFn = OTTO_ANCHORS[state];
+  const units = motionUnits(state, keyline);
+  const value = useOttoMotionClock(units, tickMs, active && !!anchorFn, state);
+  if (!anchorFn) return null;
+  const first = anchorFn(0);
+  const offsets = [];
+  for (let t = 0; t < ANCHOR_PERIOD; t++) {
+    const a = anchorFn(t);
+    offsets.push({
+      x: (a.x - first.x) * pixelSize,
+      y: (a.y - first.y) * pixelSize
+    });
+  }
+  return {
+    style: stepStyle(value, offsets, 1, units, tickMs, active),
+    over: first.over,
+    origin: {
+      x: first.x,
+      y: first.y
+    }
+  };
+}
+
+// ---------------------------------------------------------------- otto ----
+
+/**
+ * The shipping sprite.
+ *
+ * Mounting is deferred on purpose. The strips are ~500 static Views for a
+ * typical state, and creating those is native COMMIT cost: measured at 128 ms
+ * for one sprite, against 28 ms for a still. A mascot almost always appears
+ * while something else is animating (a panel opening, a list settling), and
+ * 128 ms of commit dropped into that is a visible hitch.
+ *
+ * So the first commit paints `OttoStill` — frame 0, ~36 Views, the exact
+ * pixels the animation starts on — and the strips mount once the interaction
+ * has settled (an idle callback). Nothing pops, because the still IS frame 0.
+ * Pass `eager` when the sprite is the thing the user is waiting for.
+ *
+ * The two layers are siblings that each gate themselves with `return null`
+ * rather than a ternary swap, so this component's child slots never change
+ * shape (Fabric view-index safety).
+ */
+export function Otto({
+  state,
+  pixelSize = 8,
+  water = true,
+  keyline = true,
+  tickMs = 140,
+  active = true,
+  eager = false,
+  style
+}) {
+  const reelState = useOttoReel(state === "reel", tickMs, active);
+  const resolved = state === "reel" ? reelState : state;
+  const side = OTTO_GRID * pixelSize;
+  const [mounted, setMounted] = useState(eager);
+  useEffect(() => {
+    if (eager || mounted) return;
+    // requestIdleCallback, not InteractionManager: RN 0.85 deprecates the
+    // latter and warns on every use, and this runs in every host we support.
+    // The setTimeout fallback covers runtimes without the idle callback.
+    const idle = globalThis.requestIdleCallback;
+    const cancelIdle = globalThis.cancelIdleCallback;
+    if (idle) {
+      const handle = idle(() => setMounted(true));
+      return () => cancelIdle?.(handle);
+    }
+    const timer = setTimeout(() => setMounted(true), 0);
+    return () => clearTimeout(timer);
+  }, [eager, mounted]);
+  return /*#__PURE__*/_jsxs(View, {
+    pointerEvents: "none",
+    style: [{
+      width: side,
+      height: side
+    }, style],
+    children: [/*#__PURE__*/_jsx(OttoStillLayer, {
+      show: !mounted,
+      state: resolved,
+      pixelSize: pixelSize,
+      water: water,
+      keyline: keyline
+    }), /*#__PURE__*/_jsx(OttoStrips, {
+      show: mounted,
+      state: resolved,
+      pixelSize: pixelSize,
+      water: water,
+      keyline: keyline,
+      tickMs: tickMs,
+      active: active
+    })]
+  });
+}
+
+/** Frame 0 while the strips are still coming. */
+function OttoStillLayer({
+  show,
+  state,
+  pixelSize,
+  water,
+  keyline
+}) {
+  if (!show) return null;
+  return /*#__PURE__*/_jsx(OttoStill, {
+    state: state,
+    pixelSize: pixelSize,
+    water: water,
+    keyline: keyline
+  });
+}
+
+/** The animated strips and their clock. */
+function OttoStrips({
+  show,
+  state,
+  pixelSize,
+  water,
+  keyline,
+  tickMs,
+  active
+}) {
+  const sheets = ottoSheets(state, keyline);
+  const side = OTTO_GRID * pixelSize;
+  const waterH = WATER_ROWS * pixelSize;
+  const units = lcm(sheets.period, ANCHOR_PERIOD);
+  const value = useOttoMotionClock(units, tickMs, active && show, state);
+  const bodyStyle = stepStyle(value, stripOffsets(sheets.body, side), 1, units, tickMs, active);
+  const waterStyle = stepStyle(value, stripOffsets(sheets.water, side), WATER_UNITS_PER_STEP, units, tickMs, active);
+  if (!show) return null;
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(StripWindow, {
+      top: WATER_ROW0 * pixelSize,
+      width: side,
+      height: waterH,
+      strip: sheets.water,
+      px: pixelSize,
+      frameW: side,
+      motion: waterStyle,
+      visible: water
+    }), /*#__PURE__*/_jsx(StripWindow, {
+      top: 0,
+      width: side,
+      height: side,
+      strip: sheets.body,
+      px: pixelSize,
+      frameW: side,
+      motion: bodyStyle,
+      visible: true
+    })]
+  });
+}
+function stripOffsets(strip, frameW) {
+  return strip.colOf.map(c => ({
+    x: -c * frameW,
+    y: 0
+  }));
+}
+/** Pure UI: an overflow-hidden window over a strip of frames. */
+function StripWindow({
+  top,
+  width,
+  height,
+  strip,
+  px,
+  frameW,
+  motion,
+  visible
+}) {
+  const stripW = strip.frames.length * frameW;
+  return /*#__PURE__*/_jsx(View, {
+    style: {
+      position: "absolute",
+      left: 0,
+      top,
+      width,
+      height,
+      overflow: "hidden"
+    },
+    children: /*#__PURE__*/_jsx(OttoMotionView, {
+      style: [{
+        width: stripW,
+        height
+      }, motion],
+      children: visible ? strip.frames.map((rects, i) => /*#__PURE__*/_jsx(FrameViews, {
+        rects: rects,
+        px: px,
+        offsetX: i * frameW
+      }, i)) : null
+    })
+  });
+}
+
+/** One frame as absolutely positioned rectangle Views. Static after mount. */
+function FrameViews({
+  rects,
+  px,
+  offsetX
+}) {
+  return /*#__PURE__*/_jsx(_Fragment, {
+    children: rects.map((r, i) => /*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        left: offsetX + r.x * px,
+        top: r.y * px,
+        width: r.w * px,
+        height: r.h * px,
+        backgroundColor: r.color
+      }
+    }, i))
+  });
+}
+export { WATER_FRAMES };

package/lib/module/ui/otto/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Otto — the Buoy mascot, as a shared UI primitive.
+ *
+ * One 16×16 pixel character with a state per product moment. `OTTO_USES` says
+ * what each state is for; place him only where the alternative is nothing
+ * (empty bodies, waiting states) and only in states that are actually true.
+ * See OTTO_PLACEMENT_PLAN.md.
+ *
+ * The renderer is core-RN only (no Reanimated, no expo-image), so it runs in
+ * Expo, in a bare RN CLI host, and on react-native-web. See OTTO_PERF_PLAN.md
+ * for the measurements behind that.
+ *
+ * This is the ONE copy. The example app's review page and the website's lab
+ * re-export from here rather than keeping forks.
+ */
+export * from "./ottoEngine.js";
+export * from "./ottoSheet.js";
+export * from "./OttoSprite.js";