@buoy-gg/shared-ui 7.0.22 → 7.0.24

package/lib/module/license/tierLimits.js

@@ -0,0 +1,158 @@
+"use strict";
+
+/**
+ * Per-tier numeric limits — the ONLY thing that separates anonymous from free.
+ *
+ * Every binary Pro gate (copy-to-clipboard, state editing, storage mutations,
+ * navigation) is identical for both: locked. That keeps the tier split to one
+ * table instead of scattered conditionals.
+ *
+ * The governing rule: **the free column never moves.** Anonymous is carved out
+ * BELOW today's free tier — nothing is ever added to free in exchange for an
+ * account, because that would come straight out of the Pro upgrade.
+ */
+
+import { getUseIsPro, getUseTier, isAnonymousTierEnabled } from "./licenseModule.js";
+const LIMITS = {
+  // ── network ───────────────────────────────────────────────────────────────
+  "network.requests": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  "network.saved": {
+    anonymous: 1,
+    free: 5,
+    pro: 50
+  },
+  // Already 1 for free, so 25% would be 0 — which deletes the feature rather
+  // than trialling it. Raising the FREE value to make room is not an option.
+  "network.overrideRules": {
+    anonymous: 1,
+    free: 1,
+    pro: 50
+  },
+  // ── storage ───────────────────────────────────────────────────────────────
+  "storage.events": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  "storage.keys": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  // Same floor-at-1 reasoning as network.overrideRules.
+  "storage.mmkvInstances": {
+    anonymous: 1,
+    free: 1,
+    pro: Infinity
+  },
+  // ── state tools ───────────────────────────────────────────────────────────
+  "redux.actions": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  "zustand.changes": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  "jotai.changes": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  "events.entries": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  // ── render / navigation ───────────────────────────────────────────────────
+  "highlightUpdates.components": {
+    anonymous: 5,
+    free: 25,
+    pro: Infinity
+  },
+  "highlightUpdates.historyEvents": {
+    anonymous: 1,
+    free: 3,
+    pro: Infinity
+  },
+  "highlightUpdates.detailEvents": {
+    anonymous: 2,
+    free: 5,
+    pro: Infinity
+  },
+  "routeEvents.entries": {
+    anonymous: 1,
+    free: 3,
+    pro: Infinity
+  },
+  "timeMachine.snapshots": {
+    anonymous: 1,
+    free: 2,
+    pro: Infinity
+  },
+  "perfMonitor.automationCases": {
+    anonymous: 1,
+    free: 3,
+    pro: Infinity
+  }
+};
+export const TIER_LIMITS = LIMITS;
+
+/**
+ * The tier whose limits actually apply.
+ *
+ * `hasProAccess` is `useIsPro()`, which is true for a real Pro license OR the
+ * free Weekend Pass. Routing the Weekend Pass through here is what keeps
+ * today's behavior intact: weekend users get Pro limits, exactly as they do
+ * now. When the Weekend Pass is later gated to key-holders, that change lands
+ * here for free — no limit call site has to know about it.
+ */
+export function resolveEffectiveTier(tier, hasProAccess) {
+  if (hasProAccess) return "pro";
+  // The switch lives in @buoy-gg/license so that this and the Weekend Pass
+  // change flip together — see isAnonymousTierEnabled().
+  if (!isAnonymousTierEnabled() && tier === "anonymous") return "free";
+  return tier;
+}
+
+/**
+ * The limit for the current tier.
+ *
+ * Replaces the per-package `const FREE_TIER_X = 25` + `isPro ? Infinity : X`
+ * pattern. `Infinity` is returned for uncapped tiers and is safe to use
+ * directly in `slice(0, limit)` and `length >= limit` comparisons.
+ */
+export function useLimit(key) {
+  const hasProAccess = getUseIsPro()();
+  const tier = getUseTier()();
+  return TIER_LIMITS[key][resolveEffectiveTier(tier, hasProAccess)];
+}
+
+/**
+ * Whether claiming a FREE key would actually raise this limit right now.
+ *
+ * The anonymous upsell must never promise something a free key won't deliver.
+ * Two ways it could lie, and this closes both:
+ *
+ *  - **Pro-exclusive features.** Copy-to-clipboard, state editing, storage
+ *    mutations and navigation are locked for anonymous AND free alike. Telling
+ *    an anonymous user a free key opens them would be false.
+ *  - **Limits that are already equal.** Override rules and MMKV instances sit
+ *    at 1 for both tiers, so a key changes nothing there either.
+ *
+ * It also respects `ANONYMOUS_TIER_ENABLED`: while the anonymous tier is off,
+ * an anonymous user is *already* getting the free limits, so there is nothing
+ * to claim and this correctly returns false everywhere. That falls out of
+ * asking `resolveEffectiveTier` rather than reading the table directly, so the
+ * switch and the copy can never disagree.
+ */
+export function freeKeyRaises(key) {
+  const limits = TIER_LIMITS[key];
+  return limits[resolveEffectiveTier("anonymous", false)] < limits[resolveEffectiveTier("free", false)];
+}

package/lib/module/ui/backgrounds/BackgroundSwitcher.js

@@ -0,0 +1,176 @@
+"use strict";
+
+/**
+ * The ‹ prev / next › strip for auditioning backgrounds.
+ *
+ * This is a REVIEW control, not shipped chrome: it exists so the whole
+ * catalogue can be walked without a rebuild, with the cost of each preset shown
+ * next to its name. Mount it at the top of a tool's body while evaluating, and
+ * pull it once a winner is picked (or keep it behind a setting).
+ *
+ * It writes to the shared `backgroundStore`, so stepping here changes the
+ * background in every tool at once.
+ */
+
+import { memo } from "react";
+import { StyleSheet, Text, TouchableOpacity, View } from "react-native";
+import { ChevronLeft, ChevronRight, Palette } from "../../icons/lucide-icons.js";
+import { macOSColors } from "../gameUI/constants/macOSDesignSystemColors.js";
+import { useToolBackground } from "./backgroundStore.js";
+import { getPreset } from "./registry.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const BackgroundSwitcher = /*#__PURE__*/memo(function BackgroundSwitcher() {
+  const {
+    id,
+    index,
+    count,
+    motion,
+    next,
+    previous,
+    setMotion
+  } = useToolBackground();
+  const preset = getPreset(id);
+  return /*#__PURE__*/_jsxs(View, {
+    style: styles.root,
+    children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+      onPress: previous,
+      style: styles.step,
+      hitSlop: HIT_SLOP,
+      accessibilityLabel: "Previous background",
+      "sentry-label": "ignore background previous",
+      children: /*#__PURE__*/_jsx(ChevronLeft, {
+        size: 16,
+        color: macOSColors.text.secondary
+      })
+    }), /*#__PURE__*/_jsxs(View, {
+      style: styles.center,
+      children: [/*#__PURE__*/_jsxs(View, {
+        style: styles.titleRow,
+        children: [/*#__PURE__*/_jsx(Palette, {
+          size: 11,
+          color: macOSColors.semantic.info
+        }), /*#__PURE__*/_jsx(Text, {
+          style: styles.title,
+          numberOfLines: 1,
+          children: preset.label
+        }), /*#__PURE__*/_jsxs(Text, {
+          style: styles.counter,
+          children: [index + 1, "/", count]
+        })]
+      }), /*#__PURE__*/_jsx(Text, {
+        style: styles.blurb,
+        numberOfLines: 1,
+        children: preset.blurb
+      }), /*#__PURE__*/_jsxs(Text, {
+        style: styles.cost,
+        numberOfLines: 1,
+        children: [preset.nodes === 0 ? "0 animated nodes" : `${preset.nodes} native node${preset.nodes === 1 ? "" : "s"}`, "  ·  ", "~", preset.views, " static views"]
+      })]
+    }), /*#__PURE__*/_jsx(TouchableOpacity, {
+      onPress: () => setMotion(!motion),
+      style: [styles.motion, motion ? styles.motionOn : null],
+      hitSlop: HIT_SLOP,
+      accessibilityLabel: motion ? "Turn motion off" : "Turn motion on",
+      "sentry-label": "ignore background motion",
+      children: /*#__PURE__*/_jsx(Text, {
+        style: [styles.motionText, motion ? styles.motionTextOn : null],
+        children: motion ? "MOTION" : "STATIC"
+      })
+    }), /*#__PURE__*/_jsx(TouchableOpacity, {
+      onPress: next,
+      style: styles.step,
+      hitSlop: HIT_SLOP,
+      accessibilityLabel: "Next background",
+      "sentry-label": "ignore background next",
+      children: /*#__PURE__*/_jsx(ChevronRight, {
+        size: 16,
+        color: macOSColors.text.secondary
+      })
+    })]
+  });
+});
+const HIT_SLOP = {
+  top: 8,
+  bottom: 8,
+  left: 8,
+  right: 8
+};
+const styles = StyleSheet.create({
+  root: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+    marginHorizontal: 8,
+    marginTop: 6,
+    marginBottom: 2,
+    borderRadius: 10,
+    borderWidth: 1,
+    borderColor: macOSColors.border.default,
+    // Deliberately translucent: the strip sits ON the background it is
+    // previewing, so you can see the field through it.
+    backgroundColor: "rgba(26,26,28,0.72)"
+  },
+  step: {
+    width: 28,
+    height: 28,
+    borderRadius: 8,
+    alignItems: "center",
+    justifyContent: "center",
+    backgroundColor: "rgba(38,38,42,0.8)",
+    borderWidth: 1,
+    borderColor: macOSColors.border.default
+  },
+  center: {
+    flex: 1,
+    minWidth: 0
+  },
+  titleRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 5
+  },
+  title: {
+    color: macOSColors.text.primary,
+    fontSize: 12,
+    fontWeight: "600"
+  },
+  counter: {
+    color: macOSColors.text.muted,
+    fontSize: 10,
+    fontVariant: ["tabular-nums"]
+  },
+  blurb: {
+    color: macOSColors.text.secondary,
+    fontSize: 10,
+    marginTop: 1
+  },
+  cost: {
+    color: macOSColors.text.icon,
+    fontSize: 9,
+    marginTop: 1,
+    fontVariant: ["tabular-nums"]
+  },
+  motion: {
+    paddingHorizontal: 7,
+    paddingVertical: 4,
+    borderRadius: 6,
+    borderWidth: 1,
+    borderColor: macOSColors.border.default,
+    backgroundColor: "rgba(38,38,42,0.8)"
+  },
+  motionOn: {
+    borderColor: macOSColors.semantic.info + "55",
+    backgroundColor: macOSColors.semantic.infoBackground
+  },
+  motionText: {
+    fontSize: 9,
+    fontWeight: "700",
+    letterSpacing: 0.6,
+    color: macOSColors.text.muted
+  },
+  motionTextOn: {
+    color: macOSColors.semantic.info
+  }
+});

package/lib/module/ui/backgrounds/README.md

@@ -0,0 +1,115 @@
+# Tool backgrounds
+
+Animated and static backdrops for Buoy tool surfaces. Drop `<ToolBackground />`
+in as the first child of a tool's body container; everything after it draws on
+top.
+
+```tsx
+<View style={styles.container}>
+  <ToolBackground />
+  {/* screens */}
+</View>
+```
+
+The preset is a single shared, persisted choice (`backgroundStore`), so
+switching it in one tool switches it everywhere. `<BackgroundSwitcher />` is the
+‹ prev / next › review strip used to audition the catalogue.
+
+## The two families
+
+- **Starfield** (`variants/starfield.tsx`) — the cheap scenic preset: 99 stars
+  quantised into five depth bands.
+- **Deep Field** (`variants/deepField.tsx`) — the Everlights
+  `ParallaxDriftBackground`, ported 1:1: same seed and generator call order,
+  same 160 stars, same far-plane bias, sizes, palette and drift. Speed is
+  quantised into 18 bands (a distinct speed costs a distinct animated node);
+  everything else stays per-star. Roughly twice Starfield's cost — the file
+  documents exactly what could and couldn't come across from Skia.
+- **The lattice family** (`variants/lattice.tsx`) — Hex Mesh, Iso Grid,
+  Crosshatch, Perf Board, Halftone, Waffle, Instrument, Radar. Quiet technical
+  geometry: near-black base, one soft off-centre glow, a rasterized hairline
+  pattern at low alpha, a slow breath, a vignette. They read as instrument
+  panels and drafting paper rather than scenery, which is what keeps them
+  legible under dense tool UI. `LatticeShell` owns everything but the geometry,
+  so the family stays a family.
+
+## The constraint
+
+Buoy's packages peer-depend on nothing but `react` and `react-native`. No Skia,
+no Reanimated, no SVG, no gradient library — a devtool cannot force a native
+dependency into someone's app. So every preset is plain `View`s plus `Animated`,
+and the gradients and glows in `primitives.tsx` are faked by stacking
+translucent layers. For the same reason nothing here uses `transformOrigin`
+(RN 0.74+); end-pivot rotation is built out of layout instead — see Radar.
+
+## The performance contract
+
+1. **Every animation is native-driven.** `useNativeDriver: true` on a looping
+   `Animated.timing` hands the whole loop to the UI thread once and never
+   touches JS again — no per-frame callback, no re-render, no bridge traffic. A
+   preset animates a handful of *layers*, never per-particle.
+2. **Every static layer is rasterized.** `shouldRasterizeIOS` /
+   `renderToHardwareTextureAndroid` (see `RasterLayer`) flatten a layer of 40
+   dots into one cached GPU texture, so sliding it is a single composite.
+3. **Nothing recomputes.** Scatter tables are generated once at module load from
+   a fixed seed (`rng.ts`); presets only read them. `ToolBackground` buckets its
+   measured size to 8px so a resize drag rebuilds a handful of times, not
+   hundreds.
+
+Loops stop when the app backgrounds, and unmount with the tool.
+
+**Known trap:** `Animated.sequence([timing, Animated.loop(...)])` silently fails
+to drive the value on the native driver — no warning, the field renders and
+never moves. It's the obvious way to phase-offset siblings; don't. Stagger via
+different periods, or bake the offset into the `interpolate`.
+
+### Measured
+
+Network tool open on an iPhone 16 simulator, via perf-monitor and
+`measure_renders`. Starfield is the heaviest preset (6 animated nodes, ~222
+static views); the lattice presets are 1–2 nodes and 40–176 views.
+
+**Steady state** — 12–13s idle recordings:
+
+| | nodes | views | JS FPS | UI FPS | CPU avg | jank | render commits | render ms |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| Off | 0 | 1 | 60 | 60 | 23.65% | 0 | 3 | 0 |
+| Starfield | 6 | 222 | 60 | 60 | 23.79% | 0 | 4 | 0 |
+| Deep Field | 22 | 462 | 60 | 60 | 27.19% | 0 | 4 | 0 |
+
+Starfield's 0.14pt is sample noise. **Deep Field's +3.5pt is not** — 22 nodes
+driving 462 transformed views per frame is real UI-thread work, even native. It
+still holds 60/60 with zero dropped frames, but it is the one preset here with a
+measurable running cost, and that is the trade for matching the original.
+
+The commits in every column are the network tool's own once-a-minute
+`TickProvider`, not the background. A separate `measure_renders` idle sample
+reported one component render in every configuration — the animation contributes
+zero React work while it runs, which is rule 1 holding regardless of node count.
+
+**Mount** — the cost that is real for all of them:
+
+```
+Off → Starfield          348 renders / 3 commits · 13.3ms
+  StarBand    4.0ms ×5  mount    ← 222 star views       ≈ 4.5ms for the preset
+
+Starfield → Deep Field   668 renders / 3 commits · 25.2ms
+  DeepBand    8.5ms ×18 mount    ← 462 star views       ≈ 9.6ms for the preset
+  TwinkleGroup 0.5ms ×4
+  RasterLayer  0.4ms ×18
+```
+
+The balance in each is the switcher and its icons re-rendering. So: ~4.5ms and
+~9.6ms of React work respectively, once, when the tool opens — scaling with view
+count, as expected. `registry.tsx` lists each preset's count so the trade is
+visible while comparing.
+
+## Adding a preset
+
+Add the component to `variants/`, then one entry in `registry.tsx` with an
+honest `nodes` (animated nodes) and `views` (static views at ~380×620). The
+switcher shows both, which is the point — it's a review tool, not decoration.
+
+Alpha calibration: Hex Mesh is the reference. Anything fainter than its lattice
+disappears under the vignette — hairline strokes in particular need ~0.2 alpha
+or a second pixel of height to register at all.

package/lib/module/ui/backgrounds/ToolBackground.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * Drop-in animated backdrop for a Buoy tool surface.
+ *
+ * Mount it as the FIRST child of a tool's body container and everything after
+ * it draws on top:
+ *
+ *   <View style={styles.container}>
+ *     <ToolBackground />
+ *     ...screens...
+ *   </View>
+ *
+ * It is `position: absolute` + `pointerEvents: "none"`, so it never affects
+ * layout and never eats a touch. The preset comes from the shared persisted
+ * selection (`backgroundStore`), so switching it in one tool switches it in all
+ * of them.
+ */
+
+import { memo, useCallback, useState } from "react";
+import { View } from "react-native";
+import { absoluteFill } from "../../utils/absoluteFill.js";
+import { useToolBackground } from "./backgroundStore.js";
+import { getPreset } from "./registry.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Round the measured size into 8px buckets. Presets lay out from width/height,
+ * so an unbucketed measurement would rebuild the whole field on every frame of
+ * a modal resize drag; at this granularity nobody can see the difference and a
+ * drag costs a handful of rebuilds instead of hundreds.
+ */
+const bucket = n => Math.max(0, Math.ceil(n / 8) * 8);
+export const ToolBackground = /*#__PURE__*/memo(function ToolBackground({
+  id,
+  motion,
+  opacity = 1
+}) {
+  const shared = useToolBackground();
+  const [size, setSize] = useState({
+    width: 0,
+    height: 0
+  });
+  const onLayout = useCallback(event => {
+    const {
+      width,
+      height
+    } = event.nativeEvent.layout;
+    const next = {
+      width: bucket(width),
+      height: bucket(height)
+    };
+    setSize(prev => prev.width === next.width && prev.height === next.height ? prev : next);
+  }, []);
+  const preset = getPreset(id ?? shared.id);
+  const animated = motion ?? shared.motion;
+  const Variant = preset.Component;
+  const ready = size.width > 0 && size.height > 0;
+  return /*#__PURE__*/_jsx(View, {
+    style: [absoluteFill, opacity === 1 ? null : {
+      opacity
+    }],
+    pointerEvents: "none",
+    onLayout: onLayout,
+    children: Variant && ready ? /*#__PURE__*/_jsx(Variant, {
+      width: size.width,
+      height: size.height,
+      animated: animated
+    }) : null
+  });
+});

package/lib/module/ui/backgrounds/backgroundStore.js

@@ -0,0 +1,111 @@
+"use strict";
+
+/**
+ * The persisted background selection, shared by every tool.
+ *
+ * A singleton rather than context so a tool anywhere in the tree — modal,
+ * inline desktop panel, bottom sheet — reads the same choice without a provider
+ * having to wrap it. Same shape as `ignoredPatternsStore`: subscribe/notify,
+ * best-effort persistence, a dirty flag so a slow initial read can't clobber a
+ * choice the user already made.
+ */
+
+import { useEffect, useState } from "react";
+import { devToolsStorageKeys } from "../../storage/devToolsStorageKeys.js";
+import { persistentStorage } from "../../utils/persistentStorage.js";
+import { BACKGROUND_PRESETS, DEFAULT_BACKGROUND, presetAt, presetIndex } from "./registry.js";
+const KEY = `${devToolsStorageKeys.base}_tool_background`;
+function isValidId(value) {
+  return typeof value === "string" && BACKGROUND_PRESETS.some(p => p.id === value);
+}
+class BackgroundStore {
+  id = DEFAULT_BACKGROUND;
+  motion = true;
+  listeners = new Set();
+  loadPromise = null;
+  dirty = false;
+  getId() {
+    return this.id;
+  }
+  getMotion() {
+    return this.motion;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    void this.load();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    for (const listener of this.listeners) listener();
+  }
+  load() {
+    if (this.loadPromise) return this.loadPromise;
+    this.loadPromise = (async () => {
+      try {
+        const raw = await persistentStorage.getItem(KEY);
+        if (!raw || this.dirty) return;
+        const parsed = JSON.parse(raw);
+        if (isValidId(parsed.id)) this.id = parsed.id;
+        if (typeof parsed.motion === "boolean") this.motion = parsed.motion;
+        this.notify();
+      } catch {
+        // A missing or corrupt entry just means "use the default".
+      }
+    })();
+    return this.loadPromise;
+  }
+  persist() {
+    this.dirty = true;
+    const payload = {
+      id: this.id,
+      motion: this.motion
+    };
+    void persistentStorage.setItem(KEY, JSON.stringify(payload)).catch(() => {});
+  }
+  setId(id) {
+    if (this.id === id) return;
+    this.id = id;
+    this.persist();
+    this.notify();
+  }
+
+  /** Step through the catalogue; `delta` is +1 (next) or -1 (previous). */
+  step(delta) {
+    this.setId(presetAt(presetIndex(this.id) + delta).id);
+  }
+  setMotion(motion) {
+    if (this.motion === motion) return;
+    this.motion = motion;
+    this.persist();
+    this.notify();
+  }
+}
+export const backgroundStore = new BackgroundStore();
+/** Subscribe a component to the current background selection. */
+export function useToolBackground() {
+  const [id, setLocalId] = useState(() => backgroundStore.getId());
+  const [motion, setLocalMotion] = useState(() => backgroundStore.getMotion());
+  useEffect(() => backgroundStore.subscribe(() => {
+    setLocalId(backgroundStore.getId());
+    setLocalMotion(backgroundStore.getMotion());
+  }), []);
+  return {
+    id,
+    motion,
+    index: presetIndex(id),
+    count: BACKGROUND_PRESETS.length,
+    setId: setId,
+    next: next,
+    previous: previous,
+    setMotion: setMotion
+  };
+}
+
+// Module-scope identities so the returned object's callbacks never change and
+// consumers can hand them straight to a memoized button.
+const setId = id => backgroundStore.setId(id);
+const next = () => backgroundStore.step(1);
+const previous = () => backgroundStore.step(-1);
+const setMotion = motion => backgroundStore.setMotion(motion);

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

@@ -0,0 +1,9 @@
+"use strict";
+
+export { ToolBackground } from "./ToolBackground.js";
+export { BackgroundSwitcher } from "./BackgroundSwitcher.js";
+export { backgroundStore, useToolBackground } from "./backgroundStore.js";
+export { BACKGROUND_PRESETS, DEFAULT_BACKGROUND, getPreset, presetAt, presetIndex } from "./registry.js";
+// Exported for the bg-bench harness in example-dev-build, so every measured
+// variant is the shipping component with knobs turned rather than a copy.
+export { DeepFieldTunable } from "./variants/deepField.js";