@buoy-gg/shared-ui 7.0.35 → 7.0.38

package/lib/module/sync/valueShape.js

@@ -0,0 +1,153 @@
+"use strict";
+
+/**
+ * A compact type sketch of a runtime value — one implementation, shared by every
+ * adapter that hands data to a model.
+ *
+ * WHY. A model cannot write a well-formed item into a list it has never seen the
+ * shape of, and we were not showing it. Measured on `cart/bag-still-zustand`: the
+ * rendered prompt is 83,000 characters and the words `lineId`, `itemId`,
+ * `sizeId`, `addonIds` and `unitPrice` appear in it ZERO times. Every model
+ * "failing" that case invented a line shape because inventing was the only move
+ * available. The zustand typed-edit guard would have caught the invention — but
+ * only on a list that already holds an item, since it builds its template from
+ * `list[0]`. On an EMPTY list there is no template, the guard has nothing to
+ * compare against, and the invented shape is written silently.
+ *
+ * So the sketch has two jobs, and the second is the one that pays:
+ *
+ *   1. Say what the items in a list look like, so an addition can match.
+ *   2. Say when NOTHING knows — an empty list's item shape is not merely
+ *      unread, it is unknowable from runtime state, and the honest answer is to
+ *      admit that rather than let a guess through unremarked.
+ *
+ * It is deliberately tiny. A sketch of a 120-line bag is the same size as a
+ * sketch of a 2-line one, so unlike the data it survives the engine's 24,000-
+ * character result cap — which is the whole point, because the cases where the
+ * model most needs the shape are exactly the ones where the data got cut off.
+ */
+
+const isPlainObject = v => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Beyond this the sketch stops being cheaper to read than the data. */
+const MAX_DEPTH = 3;
+const MAX_KEYS = 24;
+/**
+ * Hard caps on `listShapes`. MAX_DEPTH bounds how DEEP it goes; nothing bounded
+ * how WIDE it went, and it walks every entry of every object at each permitted
+ * level. A store holding a few hundred keyed records therefore produced a
+ * "compact" sketch larger than the data it was standing in for — in a value
+ * that rides in every prompt. Depth is not a size budget.
+ */
+const MAX_LIST_PATHS = 40;
+const MAX_ENTRIES_VISITED = 600;
+
+/**
+ * `{lineId: string, qty: number, addonIds: string[]}` — a one-line type for a
+ * value, built from the value itself.
+ *
+ * An array is described by its FIRST item, because a list whose items disagree
+ * is a list nothing can safely add to and the guard will say so anyway. An empty
+ * array is `unknown[]`, which is the true answer and the one that matters: it
+ * tells a reader that adding to this list is unchecked.
+ */
+export function shapeOf(value, depth = 0) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) {
+    if (!value.length) return "unknown[]";
+    if (depth >= MAX_DEPTH) return "…[]";
+    const inner = shapeOf(value[0], depth + 1);
+    return inner.includes(" ") || inner.endsWith("]") ? `(${inner})[]` : `${inner}[]`;
+  }
+  if (isPlainObject(value)) {
+    if (depth >= MAX_DEPTH) return "{…}";
+    const keys = Object.keys(value);
+    const shown = keys.slice(0, MAX_KEYS);
+    const body = shown.map(k => `${k}: ${shapeOf(value[k], depth + 1)}`).join(", ");
+    const more = keys.length > shown.length ? `, +${keys.length - shown.length} more` : "";
+    return `{${body}${more}}`;
+  }
+  const t = typeof value;
+  return t === "undefined" ? "undefined" : t === "function" ? "function" : t;
+}
+/**
+ * Every list inside a value, with the shape of what goes in it.
+ *
+ * This is what a caller needs before adding to a list, and it is the part that
+ * cannot be recovered from a truncated read of the data itself.
+ *
+ * A list with `item: undefined` is the warning case: it is empty, so its item
+ * shape exists nowhere in the running app — not in the store, not in the
+ * persisted copy, not in this sketch. Anything added to it goes in unchecked.
+ */
+export function listShapes(value, path = "", out = [], depth = 0, budget = {
+  visited: 0
+}) {
+  if (depth > MAX_DEPTH) return out;
+  // Two independent stops: enough lists described, or enough of the value
+  // walked. The second is what a wide-but-shallow store hits.
+  if (out.length >= MAX_LIST_PATHS || budget.visited >= MAX_ENTRIES_VISITED) return out;
+  if (Array.isArray(value)) {
+    const first = value[0];
+    out.push({
+      path: path || "(root)",
+      length: value.length,
+      ...(value.length ? {
+        item: shapeOf(first)
+      } : {})
+    });
+    // One level into the items, so `lines[].addonIds` is reachable too.
+    if (value.length && isPlainObject(first)) {
+      for (const [k, v] of Object.entries(first)) {
+        if (++budget.visited >= MAX_ENTRIES_VISITED) break;
+        listShapes(v, path ? `${path}[].${k}` : `[].${k}`, out, depth + 1, budget);
+      }
+    }
+    return out;
+  }
+  if (isPlainObject(value)) {
+    for (const [k, v] of Object.entries(value)) {
+      if (++budget.visited >= MAX_ENTRIES_VISITED) break;
+      listShapes(v, path ? `${path}.${k}` : k, out, depth + 1, budget);
+    }
+  }
+  return out;
+}
+
+/** True when a sketch stopped early, so a caller can say so rather than imply completeness. */
+export function shapesWereTruncated(value) {
+  const budget = {
+    visited: 0
+  };
+  const out = listShapes(value, "", [], 0, budget);
+  return out.length >= MAX_LIST_PATHS || budget.visited >= MAX_ENTRIES_VISITED;
+}
+
+/**
+ * The lists in a value that a caller could add to WITHOUT any way to know the
+ * item shape. Empty by definition on a healthy value; non-empty means a write
+ * into one of these paths cannot be checked by anything.
+ */
+export function unshapedLists(value) {
+  return listShapes(value).filter(l => l.item === undefined).map(l => l.path);
+}
+
+/**
+ * The sketch an adapter attaches to a read: the value's own type, plus the item
+ * type of every list in it.
+ *
+ * Returns undefined when there is nothing worth saying (a scalar, or an object
+ * holding no lists) so adapters can spread it and add no noise.
+ */
+export function shapeSummary(value) {
+  if (value === undefined) return undefined;
+  const lists = listShapes(value);
+  const shape = shapeOf(value);
+  if (!lists.length && !isPlainObject(value) && !Array.isArray(value)) return undefined;
+  return lists.length ? {
+    shape,
+    lists
+  } : {
+    shape
+  };
+}

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

@@ -195,3 +195,55 @@ switcher shows both, which is the point — it's a review tool, not decoration.
 Alpha calibration: every preset runs a 0.4–0.55 vignette, and anything fainter
 than ~0.2 alpha disappears under it — hairline strokes in particular need ~0.2
 alpha or a second pixel of height to register at all.
+
+
+## Wormhole mobile preview
+
+Wormhole is the eighth registry entry (including Off). Select it under the
+Buoy dial's Settings → Background; the existing store persists that choice.
+The example app also exposes `/bg-bench?v=wormhole` and
+`/bg-bench?v=wormhole-still` for comparison under identical tool content.
+
+The moving scene is a zoom, and a zoom only loops invisibly when the picture
+is self-similar under the handoff. Two copies of one opaque cloud sheet scale
+toward the viewer one period apart (×√6 in scale, +21° in rotation) and
+crossfade with balanced source-over opacities; each forward pass takes six
+seconds (two periods) at constant proportional expansion, and four passes fit
+inside one 24-second camera-bank cycle. The sheet is built by
+`scripts/generate-wormhole-textures.cjs` by tiling one annulus of the real
+shader frame in log-polar space with exactly that (×√6, +21°) symmetry, so the
+two copies are the same picture wherever they overlap and neither the
+crossfade nor a layer's reset can be seen. The destination is cut from the
+same frame with a feathered alpha and drawn as a static layer above the
+sheets — the far end of a tunnel does not zoom. One native Animated loop
+drives the scene. It approximates the flight: the tunnel geometry is baked into
+the textures, not ray-marched on the device. There is no Skia, Reanimated,
+WebView, new native dependency, or per-frame JS callback.
+
+TRAP (the "badly looping GIF" we shipped first): a feathered ring texture is
+NOT self-similar, so a copy born at 0.42× painted a shrunken tunnel — its own
+copper rim included — over the destination every 3 s, then pushed it outward.
+Fade tuning cannot hide that; only a sheet that matches itself under the
+handoff transform can. `WORMHOLE_PERIOD` / `WORMHOLE_TWIST` in `motion.ts` are
+that transform: change either and regenerate the sheet (the generator checks
+the pixels against the symmetry and refuses a sheet that does not match).
+
+While moving, the 1440×1440 sheet (JPEG) and the 384×384 eye (PNG) contribute
+about 337 KiB of source data and roughly 8.5 MiB of decoded pixels; the still
+(640×640 JPEG, 57 KiB, 1.6 MiB decoded) is mounted only when the scene does
+not move. Instances can reuse the same image source objects. Reduced motion
+shows the still texture; the existing animation primitive pauses on AppState
+changes and stops on unmount. Geometry is window-sized and cropped by each tool
+surface. Actual device performance remains to be measured in the benchmark
+screen.
+
+The desktop menu keeps one Wormhole entry and its existing live WebGL renderer.
+The mobile texture preview does not replace the desktop shader.
+
+Texture source: `node scripts/generate-wormhole-textures.cjs` (from
+`packages/shared`) ports the website's dark shader to the CPU, renders it at
+u_t=4 with the destination centred and no copy scrim or vignette, tiles the
+sheet, cuts the eye, and rewrites `textures.ts`. It keeps the embedded still
+unless `--still scene.jpg` supplies a fresh centered 640px WebGL capture; JPEG
+encoding shells out to macOS `sips`. Both packages and Metro can consume the
+module without an asset-loader plugin.

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

@@ -33,7 +33,8 @@ const bucket = n => Math.max(0, Math.ceil(n / 8) * 8);
 export const ToolBackground = /*#__PURE__*/memo(function ToolBackground({
   id,
   motion,
-  opacity = 1
+  opacity = 1,
+  focus
 }) {
   const shared = useToolBackground();
   const [size, setSize] = useState({
@@ -64,7 +65,8 @@ export const ToolBackground = /*#__PURE__*/memo(function ToolBackground({
     children: Variant && ready ? /*#__PURE__*/_jsx(Variant, {
       width: size.width,
       height: size.height,
-      animated: animated
+      animated: animated,
+      focus: focus
     }) : null
   });
 });

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

@@ -15,4 +15,5 @@ export { DeepFieldTunable } from "./variants/deepField.js";
 export { MoonlightTunable } from "./variants/moonlight.js";
 export { DaylightTunable } from "./variants/daylight.js";
 export { LiveSkyTunable } from "./variants/liveSky.js";
-export { getSkyScrub, setSkyScrub, useSkyScrub } from "./skyClock.js";
+export { getSkyScrub, setSkyScrub, useSkyScrub } from "./skyClock.js";
+export { Wormhole } from "./variants/wormhole.js";

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

@@ -11,6 +11,7 @@
  */
 
 import { DeepField } from "./variants/deepField.js";
+import { Wormhole } from "./variants/wormhole.js";
 import { Hyperspace } from "./variants/hyperspace.js";
 import { LiveSky } from "./variants/liveSky.js";
 import { Abyss, Bubbles, Jellyfish } from "./variants/underwater.js";
@@ -65,6 +66,13 @@ export const BACKGROUND_PRESETS = [{
   nodes: 15,
   views: 250,
   Component: Jellyfish
+}, {
+  id: "wormhole",
+  label: "Wormhole",
+  blurb: "Cobalt clouds and copper light — a native flight through the tunnel",
+  nodes: 1,
+  views: 7,
+  Component: Wormhole
 }];
 
 // Ships OFF: a backdrop is an opt-in, so first load is plain black and the

package/lib/module/ui/backgrounds/variants/wormhole/motion.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/** One slow camera cycle containing four faster forward passes.
+ * Keyframes run on Animated's native driver; this math runs only at import.
+ *
+ * The sheet texture is self-similar: scaled by WORMHOLE_PERIOD and rotated by
+ * WORMHOLE_TWIST it is the same picture (scripts/generate-wormhole-textures.cjs
+ * builds it that way and checks it). The two shells sit exactly one period
+ * apart, so at every instant they show identical pixels and the crossfade
+ * between them — and each shell's reset — cannot be seen. Change either
+ * constant and regenerate the textures; the sheet must be rebuilt to match.
+ */
+export const WORMHOLE_CYCLE_MS = 24000;
+export const WORMHOLE_PASSES = 4;
+/** Scale ratio between the two shells; one pass covers two periods (×6). */
+export const WORMHOLE_PERIOD = Math.sqrt(6);
+/** Degrees the picture turns per period — its spiral symmetry. */
+export const WORMHOLE_TWIST = 21;
+const STEPS_PER_PASS = 64;
+export const WORMHOLE_INPUT = Array.from({
+  length: STEPS_PER_PASS * WORMHOLE_PASSES + 1
+}, (_, i) => i / (STEPS_PER_PASS * WORMHOLE_PASSES));
+const smooth = (from, to, value) => {
+  const t = Math.max(0, Math.min(1, (value - from) / (to - from)));
+  return t * t * (3 - 2 * t);
+};
+const PHASES = [0, 0.5].map(offset => WORMHOLE_INPUT.map(t => (t * WORMHOLE_PASSES + offset) % 1));
+// Broad overlapping windows, with a completely invisible interval around wraps.
+const WEIGHTS = PHASES.map(phase => phase.map(t => Math.sin(Math.PI * t) ** 2 * smooth(0.02, 0.12, t) * (1 - smooth(0.88, 0.98, t))));
+export const WORMHOLE_SHELLS = PHASES.map((phase, layer) => ({
+  // Constant proportional expansion keeps the forward speed steady. The
+  // sheet covers the whole plane from scale 1, so a shell never shows an edge.
+  scale: phase.map(t => Math.pow(WORMHOLE_PERIOD, 2 * t)),
+  // Normalize layer transmission across the overlapping fades.
+  opacity: phase.map((_, i) => {
+    const total = WEIGHTS.reduce((sum, weights) => sum + weights[i], 0);
+    return 1 - Math.pow(0.08, WEIGHTS[layer][i] / total);
+  }),
+  // One twist per period, centred so the shells sit ±θ/2 around the camera.
+  rotate: phase.map(t => `${(2 * t - 1) * WORMHOLE_TWIST}deg`)
+}));
+// Zero velocity at the turnarounds and the loop boundary, rather than the
+// sharp reversal from a three-keyframe triangle-wave camera bank.
+export const WORMHOLE_CAMERA_ROTATION = WORMHOLE_INPUT.map(t => `${-5 * Math.cos(t * Math.PI * 2)}deg`);