@agent-native/toolkit 0.201.1 → 0.202.0-nightly-20261006033736

package/src/app/shared/ocean/bloom-blur.wgsl

@@ -0,0 +1,43 @@
+
+
+const KERNEL_RADIUS: u32 = 22u;
+struct BlurUniforms {
+  direction: vec2f,
+  invSize: vec2f,
+  gaussianCoefficients0: vec4f,
+  gaussianCoefficients1: vec4f,
+  gaussianCoefficients2: vec4f,
+  gaussianCoefficients3: vec4f,
+  gaussianCoefficients4: vec4f,
+  gaussianCoefficients5: vec4f,
+};
+@group(0) @binding(0) var<uniform> uniforms: BlurUniforms;
+@group(0) @binding(1) var colorTexture: texture_2d<f32>;
+@group(0) @binding(2) var linearSampler: sampler;
+
+fn coefficient(i: u32) -> f32 {
+  let packed = array<vec4f, 6>(
+    uniforms.gaussianCoefficients0,
+    uniforms.gaussianCoefficients1,
+    uniforms.gaussianCoefficients2,
+    uniforms.gaussianCoefficients3,
+    uniforms.gaussianCoefficients4,
+    uniforms.gaussianCoefficients5
+  );
+  return packed[i / 4u][i % 4u];
+}
+
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+
+  var weightSum = coefficient(0u);
+  var diffuseSum = textureSample(colorTexture, linearSampler, uv).rgb * weightSum;
+  for (var i = 1u; i < KERNEL_RADIUS; i = i + 1u) {
+    let x = f32(i);
+    let w = coefficient(i);
+    let uvOffset = uniforms.direction * uniforms.invSize * x;
+    let sample1 = textureSample(colorTexture, linearSampler, uv + uvOffset).rgb;
+    let sample2 = textureSample(colorTexture, linearSampler, uv - uvOffset).rgb;
+    diffuseSum = diffuseSum + (sample1 + sample2) * w;
+  }
+  return vec4f(diffuseSum, 1.0);
+}

package/src/app/shared/ocean/bloom-bright.wgsl

@@ -0,0 +1,21 @@
+struct BrightUniforms {
+  luminosityThreshold: f32,
+  smoothWidth: f32,
+  _pad0: vec2f,
+};
+@group(0) @binding(0) var<uniform> uniforms: BrightUniforms;
+@group(0) @binding(1) var tDiffuse: texture_2d<f32>;
+@group(0) @binding(2) var linearSampler: sampler;
+
+fn luminance(rgb: vec3f) -> f32 {
+  return dot(rgb, vec3f(0.299, 0.587, 0.114));
+}
+
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+
+  let texel = textureSample(tDiffuse, linearSampler, uv);
+  let v = luminance(texel.xyz);
+  let outputColor = vec4f(vec3f(0.0), 0.0);
+  let alpha = smoothstep(uniforms.luminosityThreshold, uniforms.luminosityThreshold + uniforms.smoothWidth, v);
+  return mix(outputColor, texel, alpha);
+}

package/src/app/shared/ocean/bloom-composite.wgsl

@@ -0,0 +1,40 @@
+struct CompositeUniforms {
+  bloomStrength: f32,
+  bloomRadius: f32,
+  _pad0: vec2f,
+  bloomFactors0: vec4f,
+  bloomFactors1: vec4f,
+};
+@group(0) @binding(0) var<uniform> uniforms: CompositeUniforms;
+@group(0) @binding(1) var blurTexture1: texture_2d<f32>;
+@group(0) @binding(2) var blurTexture2: texture_2d<f32>;
+@group(0) @binding(3) var blurTexture3: texture_2d<f32>;
+@group(0) @binding(4) var blurTexture4: texture_2d<f32>;
+@group(0) @binding(5) var blurTexture5: texture_2d<f32>;
+@group(0) @binding(6) var linearSampler: sampler;
+
+fn factor(i: u32) -> f32 {
+  let v = array<f32, 8>(
+    uniforms.bloomFactors0.x, uniforms.bloomFactors0.y, uniforms.bloomFactors0.z, uniforms.bloomFactors0.w,
+    uniforms.bloomFactors1.x, uniforms.bloomFactors1.y, uniforms.bloomFactors1.z, uniforms.bloomFactors1.w
+  );
+  return v[i];
+}
+
+fn lerpBloomFactor(f: f32) -> f32 {
+  let mirrorFactor = 1.2 - f;
+  return mix(f, mirrorFactor, uniforms.bloomRadius);
+}
+
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+
+  let bloom = 3.0 * uniforms.bloomStrength * (
+    lerpBloomFactor(factor(0u)) * textureSample(blurTexture1, linearSampler, uv).rgb +
+    lerpBloomFactor(factor(1u)) * textureSample(blurTexture2, linearSampler, uv).rgb +
+    lerpBloomFactor(factor(2u)) * textureSample(blurTexture3, linearSampler, uv).rgb +
+    lerpBloomFactor(factor(3u)) * textureSample(blurTexture4, linearSampler, uv).rgb +
+    lerpBloomFactor(factor(4u)) * textureSample(blurTexture5, linearSampler, uv).rgb
+  );
+  let bloomAlpha = max(bloom.r, max(bloom.g, bloom.b));
+  return vec4f(bloom, bloomAlpha);
+}

package/src/app/shared/ocean/brand-colors.ts

@@ -0,0 +1,49 @@
+import { DEFAULT_OCEAN_COLORS, type OceanColors } from "./ocean-colors.js";
+
+// guard:allow-raw-color - These fixed values calibrate the standalone GPU shader to the docs brand.
+const DARK_COLORS = { fg: "#aeadac", bg: "#0a0a0a" };
+// guard:allow-raw-color - These fixed values calibrate the standalone GPU shader to the docs brand.
+const LIGHT_COLORS = { fg: "#00677f", bg: "#faf9f5" };
+
+/**
+ * Returns null for anything that is not a full six-digit hex. Callers fall back
+ * to the packaged defaults -- an unreadable token and a legitimately dark token
+ * must not produce the same silent black.
+ */
+export function hexToLinearRgb(
+  hex: string,
+): readonly [number, number, number] | null {
+  const normalized = hex.trim().replace("#", "");
+  if (!/^[0-9a-fA-F]{6}$/.test(normalized)) return null;
+  const value = Number.parseInt(normalized, 16);
+  return [
+    srgbToLinear(((value >> 16) & 255) / 255),
+    srgbToLinear(((value >> 8) & 255) / 255),
+    srgbToLinear((value & 255) / 255),
+  ];
+}
+
+function srgbToLinear(channel: number): number {
+  return channel <= 0.04045
+    ? channel / 12.92
+    : ((channel + 0.055) / 1.055) ** 2.4;
+}
+
+export function readOceanColors(element: Element): OceanColors {
+  const styles = getComputedStyle(element);
+  const fg = hexToLinearRgb(styles.getPropertyValue("--b-hero-shader-fg"));
+  const bg = hexToLinearRgb(styles.getPropertyValue("--b-bg-page"));
+  if (fg && bg) return { fg, bg };
+
+  const root = document.documentElement;
+  const dark = root.classList.contains("dark")
+    ? true
+    : root.classList.contains("light")
+      ? false
+      : root.getAttribute("data-theme") === "dark";
+  const colors = dark ? DARK_COLORS : LIGHT_COLORS;
+  return {
+    fg: hexToLinearRgb(colors.fg) ?? DEFAULT_OCEAN_COLORS.fg,
+    bg: hexToLinearRgb(colors.bg) ?? DEFAULT_OCEAN_COLORS.bg,
+  };
+}

package/src/app/shared/ocean/camera.ts

@@ -0,0 +1,28 @@
+import { OCEAN_TUNING } from "./tuning.js";
+
+export function oceanCamera(size: readonly [number, number]) {
+  const { eye, target, pitchDegrees, fovDegrees, near, far } =
+    OCEAN_TUNING.camera;
+  const angle =
+    Math.atan2(eye[1] - target[1], eye[2] - target[2]) -
+    (pitchDegrees * Math.PI) / 180;
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const f = 1 / Math.tan((fovDegrees * Math.PI) / 360);
+
+  const view = new Float32Array(16);
+  view[0] = view[15] = 1;
+  view[5] = view[10] = c;
+  view[6] = s;
+  view[9] = -s;
+  view[13] = -(c * eye[1] - s * eye[2]);
+  view[14] = -(s * eye[1] + c * eye[2]);
+
+  const projection = new Float32Array(16);
+  projection[0] = f / (size[0] / Math.max(1, size[1]));
+  projection[5] = f;
+  projection[10] = far / (near - far);
+  projection[11] = -1;
+  projection[14] = (far * near) / (near - far);
+  return { view, projection };
+}

package/src/app/shared/ocean/hero-ocean-background.spec.tsx

@@ -0,0 +1,369 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { hexToLinearRgb } from "./brand-colors.js";
+import { HeroOceanBackground } from "./hero-ocean-background.js";
+
+const FIRST_FRAME_TIMEOUT_MS = 6000;
+
+const { createRenderer, renderer, importSpy } = vi.hoisted(() => {
+  const renderer = {
+    ready: Promise.resolve(),
+    firstFrame: Promise.resolve(),
+    dispose: vi.fn(),
+    setColors: vi.fn(),
+    setPaused: vi.fn(),
+    setPointer: vi.fn(),
+  };
+  const importSpy = vi.fn();
+  return { createRenderer: vi.fn(() => renderer), renderer, importSpy };
+});
+
+vi.mock("./renderer", async () => {
+  importSpy();
+  const actual =
+    await vi.importActual<typeof import("./renderer.js")>("./renderer.js");
+  return { ...actual, createRenderer };
+});
+
+let intersectionCallbacks: ((entries: unknown[]) => void)[] = [];
+let mutationCallbacks: (() => void)[] = [];
+let disconnected: string[] = [];
+
+beforeEach(() => {
+  intersectionCallbacks = [];
+  mutationCallbacks = [];
+  disconnected = [];
+  vi.stubGlobal(
+    "IntersectionObserver",
+    class {
+      constructor(cb: (entries: unknown[]) => void) {
+        intersectionCallbacks.push(cb);
+      }
+      observe() {}
+      disconnect() {
+        disconnected.push("intersection");
+      }
+    },
+  );
+  vi.stubGlobal(
+    "MutationObserver",
+    class {
+      constructor(cb: () => void) {
+        mutationCallbacks.push(cb);
+      }
+      observe() {}
+      disconnect() {
+        disconnected.push("mutation");
+      }
+    },
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  Object.defineProperty(document, "hidden", {
+    configurable: true,
+    value: false,
+  });
+  renderer.ready = Promise.resolve();
+  renderer.firstFrame = Promise.resolve();
+  createRenderer.mockClear();
+  importSpy.mockClear();
+  renderer.dispose.mockClear();
+  renderer.setColors.mockClear();
+  renderer.setPaused.mockClear();
+  renderer.setPointer.mockClear();
+});
+
+describe("hexToLinearRgb", () => {
+  it("converts a six-digit hex to linear RGB", () => {
+    expect(hexToLinearRgb("#ffffff")).toEqual([1, 1, 1]);
+    expect(hexToLinearRgb("#000000")).toEqual([0, 0, 0]);
+  });
+
+  it("linearizes rather than passing sRGB straight through", () => {
+    const [r] = hexToLinearRgb("#808080")!;
+    expect(r).toBeCloseTo(0.2158, 3);
+  });
+
+  it("returns null for anything that is not a six-digit hex", () => {
+    for (const input of [
+      "",
+      "  ",
+      "#fff",
+      "rgb(0,0,0)",
+      "#ggghhh",
+      "#1234567",
+    ]) {
+      expect(hexToLinearRgb(input)).toBeNull();
+    }
+  });
+});
+
+describe("HeroOceanBackground", () => {
+  it("fills the hero section behind the grid and is hidden from assistive tech", async () => {
+    const { container } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />,
+    );
+    const box = container.firstElementChild as HTMLElement;
+    expect(box.getAttribute("aria-hidden")).toBe("true");
+    expect(box.className).toContain("absolute");
+    expect(box.className).toContain("inset-0");
+    expect(box.className).toContain("z-[-1]");
+    const canvas = box.querySelector("canvas");
+    expect(canvas).not.toBeNull();
+    expect(canvas?.style.width).toBe("100%");
+    expect(canvas?.style.height).toBe("100%");
+    expect(box.style.opacity).toBe("0");
+    await waitFor(() => expect(box.style.opacity).toBe("0.3"));
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+  });
+
+  it("loads the GPU runtime in an effect, not during render", async () => {
+    const onError = vi.fn();
+    render(<HeroOceanBackground onError={onError} onReady={vi.fn()} />);
+    expect(createRenderer).not.toHaveBeenCalled();
+    await waitFor(() => {
+      if (onError.mock.calls.length) throw onError.mock.calls[0]![0];
+      expect(createRenderer).toHaveBeenCalled();
+    });
+  });
+
+  it("starts the first-frame deadline after renderer initialization", async () => {
+    vi.useFakeTimers();
+    let finishInitialization: (() => void) | undefined;
+    const ready = new Promise<void>((resolve) => {
+      finishInitialization = resolve;
+    });
+    createRenderer.mockReturnValueOnce({ ...renderer, ready });
+    const onError = vi.fn();
+    const onReady = vi.fn();
+
+    render(<HeroOceanBackground onError={onError} onReady={onReady} />);
+    await act(async () => {
+      for (let i = 0; i < 10; i++) await Promise.resolve();
+    });
+    expect(createRenderer).toHaveBeenCalledOnce();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(7_000);
+    });
+    expect(onError).not.toHaveBeenCalled();
+
+    await act(async () => {
+      finishInitialization?.();
+      await ready;
+      for (let i = 0; i < 10; i++) await Promise.resolve();
+    });
+    expect(onReady).toHaveBeenCalledOnce();
+  });
+
+  it("pauses the first-frame deadline while the document is hidden", async () => {
+    vi.useFakeTimers();
+    Object.defineProperty(document, "hidden", {
+      configurable: true,
+      value: false,
+    });
+    renderer.firstFrame = new Promise<void>(() => {});
+    const onError = vi.fn();
+    render(<HeroOceanBackground onError={onError} onReady={vi.fn()} />);
+
+    await act(async () => {
+      for (let tick = 0; tick < 10; tick += 1) await Promise.resolve();
+    });
+    expect(createRenderer).toHaveBeenCalledOnce();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000);
+      Object.defineProperty(document, "hidden", {
+        configurable: true,
+        value: true,
+      });
+      document.dispatchEvent(new Event("visibilitychange"));
+      await vi.advanceTimersByTimeAsync(7000);
+      expect(onError).not.toHaveBeenCalled();
+      Object.defineProperty(document, "hidden", {
+        configurable: true,
+        value: false,
+      });
+      document.dispatchEvent(new Event("visibilitychange"));
+      await vi.advanceTimersByTimeAsync(FIRST_FRAME_TIMEOUT_MS - 1001);
+      expect(onError).not.toHaveBeenCalled();
+      await vi.advanceTimersByTimeAsync(1);
+    });
+
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: "The ocean wave did not draw a frame",
+      }),
+    );
+  });
+
+  it("pushes brand colours through on a theme change", async () => {
+    render(<HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />);
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+
+    for (const cb of mutationCallbacks) cb();
+    expect(renderer.setColors).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fg: expect.any(Array),
+        bg: expect.any(Array),
+      }),
+    );
+  });
+
+  it("pauses when scrolled out of view and resumes when back", async () => {
+    render(<HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />);
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+
+    for (const cb of intersectionCallbacks) cb([{ isIntersecting: false }]);
+    expect(renderer.setPaused).toHaveBeenCalledWith(true);
+
+    for (const cb of intersectionCallbacks) cb([{ isIntersecting: true }]);
+    expect(renderer.setPaused).toHaveBeenCalledWith(false);
+  });
+
+  it("tracks body mouse movement relative to the hero bounds", async () => {
+    const { container } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />,
+    );
+    const box = container.firstElementChild as HTMLElement;
+    vi.spyOn(box, "getBoundingClientRect").mockReturnValue({
+      left: 10,
+      top: 20,
+      width: 200,
+      height: 100,
+    } as DOMRect);
+
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+    renderer.setPointer.mockClear();
+
+    document.body.dispatchEvent(
+      new MouseEvent("mousemove", {
+        bubbles: true,
+        clientX: 110,
+        clientY: 70,
+      }),
+    );
+    expect(renderer.setPointer).toHaveBeenLastCalledWith([0, 0, 1]);
+
+    document.body.dispatchEvent(
+      new MouseEvent("mousemove", {
+        bubbles: true,
+        clientX: 310,
+        clientY: 70,
+      }),
+    );
+    expect(renderer.setPointer).toHaveBeenLastCalledWith([2, 0, 0]);
+  });
+
+  it("remaps the active pointer on scroll and fades it on window blur", async () => {
+    const { container } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />,
+    );
+    const box = container.firstElementChild as HTMLElement;
+    const rect = {
+      left: 10,
+      top: 20,
+      width: 200,
+      height: 100,
+    } as DOMRect;
+    vi.spyOn(box, "getBoundingClientRect").mockReturnValue(rect);
+
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+    renderer.setPointer.mockClear();
+
+    document.body.dispatchEvent(
+      new MouseEvent("mousemove", {
+        bubbles: true,
+        clientX: 110,
+        clientY: 70,
+      }),
+    );
+    expect(renderer.setPointer).toHaveBeenLastCalledWith([0, 0, 1]);
+
+    vi.spyOn(box, "getBoundingClientRect").mockReturnValue({
+      ...rect,
+      left: 60,
+    } as DOMRect);
+    window.dispatchEvent(new Event("scroll"));
+    expect(renderer.setPointer).toHaveBeenLastCalledWith([-0.5, 0, 1]);
+
+    window.dispatchEvent(new Event("blur"));
+    expect(renderer.setPointer).toHaveBeenLastCalledWith([-0.5, 0, 0]);
+
+    window.dispatchEvent(new Event("scroll"));
+    expect(renderer.setPointer).toHaveBeenLastCalledWith([-0.5, 0, 0]);
+  });
+
+  it("disposes the GPU and both observers on unmount", async () => {
+    const { unmount } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />,
+    );
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+
+    const before = disconnected.length;
+    unmount();
+    expect(renderer.dispose).toHaveBeenCalled();
+    expect([...disconnected.slice(before)].sort()).toEqual([
+      "intersection",
+      "mutation",
+    ]);
+  });
+
+  it("does not construct a renderer when unmounted before the import lands", async () => {
+    const { unmount } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />,
+    );
+    unmount();
+    await Promise.resolve();
+    expect(createRenderer).not.toHaveBeenCalled();
+  });
+
+  it("stays fully transparent until the first frame is drawn", async () => {
+    let drawFirstFrame: () => void = () => {};
+    renderer.firstFrame = new Promise<void>((resolve) => {
+      drawFirstFrame = resolve;
+    });
+    const onReady = vi.fn();
+    const { container } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={onReady} />,
+    );
+    const box = container.firstElementChild as HTMLElement;
+
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+    expect(box.style.opacity).toBe("0");
+
+    drawFirstFrame();
+    await waitFor(() => expect(box.style.opacity).toBe("0.3"));
+    expect(onReady).toHaveBeenCalledOnce();
+    renderer.firstFrame = Promise.resolve();
+  });
+
+  it("never fades in when the renderer fails before drawing", async () => {
+    renderer.firstFrame = Promise.reject(new Error("device lost"));
+    const { container } = render(
+      <HeroOceanBackground onError={vi.fn()} onReady={vi.fn()} />,
+    );
+    const box = container.firstElementChild as HTMLElement;
+
+    await waitFor(() => expect(createRenderer).toHaveBeenCalled());
+    await Promise.resolve();
+    expect(box.style.opacity).toBe("0");
+    renderer.firstFrame = Promise.resolve();
+  });
+
+  it("reports a construction failure to the caller instead of throwing", async () => {
+    const onError = vi.fn();
+    createRenderer.mockImplementationOnce(() => {
+      throw new Error("no device");
+    });
+    render(<HeroOceanBackground onError={onError} onReady={vi.fn()} />);
+    await waitFor(() => expect(onError).toHaveBeenCalled());
+  });
+});