@oxy.so/bloom 7.0.1 → 7.1.0

package/src/agent-avatar/ProceduralAvatar.tsx

@@ -0,0 +1,303 @@
+import {
+  memo,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+import {
+  AccessibilityInfo,
+  AppState,
+  PixelRatio,
+  Platform,
+  type View,
+} from 'react-native';
+import { useReducedMotion } from 'react-native-reanimated';
+import { useMessages } from '../locale/messages';
+import { StyledView } from '../styles/styled-primitives';
+import { drawAvatar } from './artwork';
+import { advanceAttention, createAttention } from './attention';
+import { advanceBlink, createBlink } from './blink';
+import { AvatarDrawingObserver } from './context';
+import { DrawingContext } from './drawing';
+import { ENTRANCE_SECONDS } from './entrance';
+import {
+  easeFace,
+  expressionRig,
+  faceAtSize,
+  gazeAngles,
+  type FaceRig,
+} from './face';
+import { AGENT_AVATAR_MESSAGES } from './messages';
+import type { ShapeMorph } from './shape-morph';
+import { Drawing } from './SvgDrawing';
+import type { AgentAvatarProps } from './types';
+import { advanceWander, createWander } from './wander';
+import { WORKING_SECONDS } from './working';
+
+const TAU = Math.PI * 2;
+const randomSeed = () => {
+  if (globalThis.crypto?.getRandomValues)
+    return globalThis.crypto.getRandomValues(new Uint32Array(1))[0]!;
+  return Math.floor(Math.random() * 4294967296) >>> 0;
+};
+
+/** Animated procedural artwork; shared geometry, face rig and materials across platforms. */
+function AgentAvatarComponent({
+  config,
+  size = 64,
+  paused = false,
+  label,
+  locale,
+  entranceKey,
+  workingKey,
+  workingCycles = 1,
+  className,
+  style,
+  accessibilityLabel,
+  testID,
+}: AgentAvatarProps) {
+  const { messages } = useMessages(AGENT_AVATAR_MESSAGES, locale);
+  const initialReduced = useReducedMotion();
+  const [reduced, setReduced] = useState(initialReduced);
+  useEffect(() => {
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      setReduced,
+    );
+    const media =
+      Platform.OS === 'web' && typeof matchMedia !== 'undefined'
+        ? matchMedia('(prefers-reduced-motion: reduce)')
+        : undefined;
+    const change = () => setReduced(media!.matches);
+    media?.addEventListener('change', change);
+    if (media) change();
+    return () => {
+      subscription?.remove?.();
+      media?.removeEventListener('change', change);
+    };
+  }, []);
+  const backingSize = Math.round(size * Math.min(PixelRatio.get() || 1, 2));
+  const root = useRef<View>(null);
+  const randomized = useRef(false);
+  const state = useRef<{
+    phase: number;
+    blink: ReturnType<typeof createBlink>;
+    wander: ReturnType<typeof createWander>;
+    attention: ReturnType<typeof createAttention>;
+    shapeMorph: ShapeMorph;
+    expression?: FaceRig;
+    face?: FaceRig;
+    velocity: Partial<FaceRig>;
+    gaze?: [number, number];
+    entrance: { key?: number; elapsed: number };
+    working: { key?: number; elapsed: number };
+  } | null>(null);
+  if (!state.current) {
+    const seed = config.seed >>> 0;
+    state.current = {
+      phase: (seed / 4294967296) * TAU,
+      blink: createBlink(seed),
+      wander: createWander(seed ^ config.seed, config.family === 'fold'),
+      attention: createAttention(seed ^ config.seed),
+      shapeMorph: { started: 0, active: false },
+      velocity: {},
+      entrance: { elapsed: ENTRANCE_SECONDS },
+      working: { elapsed: WORKING_SECONDS },
+    };
+  }
+  const renderDrawing = () => {
+    const context = new DrawingContext(),
+      s = state.current!;
+    const appearance = faceAtSize(config, size),
+      target = expressionRig(appearance);
+    drawAvatar(
+      context,
+      appearance,
+      s.phase,
+      s.face ?? target,
+      s.gaze ?? gazeAngles(appearance, s.phase, target),
+      size,
+      s.entrance.elapsed,
+      s.working.elapsed,
+      undefined,
+      Math.max(1, Math.floor(workingCycles)),
+      backingSize,
+    );
+    return context;
+  };
+  const [drawing, setDrawing] = useState(renderDrawing);
+  const observeDrawing = useContext(AvatarDrawingObserver);
+  useLayoutEffect(() => {
+    observeDrawing?.(drawing);
+  }, [observeDrawing, drawing]);
+  useEffect(() => {
+    const s = state.current!,
+      cycles = Math.max(1, Math.floor(workingCycles));
+    if (!randomized.current) {
+      s.wander = createWander(
+        randomSeed() ^ config.seed,
+        config.family === 'fold',
+      );
+      const seed = randomSeed();
+      s.phase = (seed / 4294967296) * TAU;
+      s.blink = createBlink(seed);
+      s.attention = createAttention(randomSeed() ^ config.seed);
+      randomized.current = true;
+    }
+    const duration = WORKING_SECONDS * cycles,
+      appearance = faceAtSize(config, size),
+      target = expressionRig(appearance);
+    if (s.entrance.key !== entranceKey)
+      s.entrance = {
+        key: entranceKey,
+        elapsed: entranceKey === undefined || paused ? ENTRANCE_SECONDS : 0,
+      };
+    if (s.working.key !== workingKey) {
+      s.working = {
+        key: workingKey,
+        elapsed: workingKey === undefined || paused ? duration : 0,
+      };
+      if (workingKey !== undefined) s.entrance.elapsed = ENTRANCE_SECONDS;
+    }
+    if (config.idle || workingKey === undefined) s.working.elapsed = duration;
+    s.expression ??= s.face ?? target;
+    s.face ??= target;
+    s.gaze ??= gazeAngles(appearance, s.phase, target, s.wander.point);
+    const frozen = paused || reduced || config.motion === 0;
+    if (reduced || config.motion === 0) {
+      s.entrance.elapsed = ENTRANCE_SECONDS;
+      s.working.elapsed = duration;
+    }
+    if (frozen) {
+      s.shapeMorph = { started: 0, active: false };
+      s.face = target;
+      s.expression = target;
+      s.velocity = {};
+      if (!paused || config.lookAt !== 'wander')
+        s.gaze = gazeAngles(appearance, s.phase, target, s.wander.point);
+    }
+    const draw = () => {
+      const context = new DrawingContext();
+      drawAvatar(
+        context,
+        appearance,
+        s.phase,
+        s.face!,
+        s.gaze!,
+        size,
+        s.entrance.elapsed,
+        s.working.elapsed,
+        frozen ? undefined : s.shapeMorph,
+        cycles,
+        backingSize,
+      );
+      setDrawing(context);
+    };
+    let frame = 0,
+      last = 0,
+      visible = true,
+      active = AppState.currentState !== 'background',
+      transitioning = true;
+    const tick = (now: number) => {
+      if (!last) last = now;
+      if (now - last >= (transitioning ? 16 : 32)) {
+        if (visible && active) {
+          const milliseconds = Math.min(now - last, 64),
+            seconds = milliseconds / 1000;
+          s.entrance.elapsed = Math.min(
+            ENTRANCE_SECONDS,
+            s.entrance.elapsed + seconds,
+          );
+          s.working.elapsed = Math.min(duration, s.working.elapsed + seconds);
+          const base = easeFace(
+            s.expression ?? target,
+            target,
+            s.velocity,
+            seconds,
+          );
+          s.expression = base;
+          transitioning =
+            (Object.keys(target) as (keyof FaceRig)[]).some(
+              (key) => base[key] !== target[key],
+            ) || s.shapeMorph.active;
+          s.face =
+            config.family === 'fold' || base.smile > 0.2
+              ? advanceAttention(
+                  s.attention,
+                  (seconds * 8) / config.duration,
+                  base,
+                  appearance,
+                )
+              : base;
+          s.face.blink = config.idle ? 1 : advanceBlink(s.blink, seconds);
+          transitioning ||= s.blink.blinking;
+          s.phase = (s.phase + (seconds * TAU) / config.duration) % TAU;
+          if (!config.idle && config.lookAt === 'wander')
+            advanceWander(
+              s.wander,
+              (seconds * 8) / config.duration,
+              config.family === 'fold',
+            );
+          const aim = gazeAngles(appearance, s.phase, s.face, s.wander.point),
+            ease = 1 - Math.exp(-milliseconds / 85);
+          s.gaze = [
+            s.gaze![0] + (aim[0] - s.gaze![0]) * ease,
+            s.gaze![1] + (aim[1] - s.gaze![1]) * ease,
+          ];
+          draw();
+        }
+        last = now;
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    const subscription = AppState.addEventListener('change', (next) => {
+      active = next === 'active';
+      last = 0;
+    });
+    let observer: IntersectionObserver | undefined;
+    if (
+      Platform.OS === 'web' &&
+      typeof IntersectionObserver !== 'undefined' &&
+      root.current instanceof Element
+    ) {
+      observer = new IntersectionObserver((entries) => {
+        visible = entries[0]?.isIntersecting ?? true;
+      });
+      observer.observe(root.current);
+    }
+    draw();
+    if (!frozen) frame = requestAnimationFrame(tick);
+    return () => {
+      cancelAnimationFrame(frame);
+      subscription?.remove?.();
+      observer?.disconnect();
+    };
+  }, [
+    config,
+    size,
+    backingSize,
+    paused,
+    reduced,
+    entranceKey,
+    workingKey,
+    workingCycles,
+  ]);
+  return (
+    <StyledView
+      ref={root}
+      className={className}
+      style={[{ width: size, height: size, maxWidth: '100%' }, style]}
+      accessible
+      accessibilityRole="image"
+      accessibilityLabel={accessibilityLabel ?? label ?? messages.label}
+      testID={testID}
+    >
+      <Drawing context={drawing} size={size} />
+    </StyledView>
+  );
+}
+
+export const ProceduralAvatar = memo(AgentAvatarComponent);
+ProceduralAvatar.displayName = 'AgentAvatar';

package/src/agent-avatar/artwork.ts

@@ -6,7 +6,7 @@ import type { AvatarConfig } from './model';
 import type { ShapeMorph } from './shape-morph';
 import { WORKING_SECONDS, workingPose } from './working';
 const TAU = Math.PI * 2;
-function silhouette(c: AvatarConfig, phase: number) {
+export function avatarSilhouette(c: AvatarConfig, phase: number) {
   const path = new DrawingPath();
   if (c.family === 'alien') {
     const sx =
@@ -123,7 +123,7 @@ export function drawAvatar(
     return;
   }
   ctx.save();
-  ctx.clip(silhouette(c, phase));
+  ctx.clip(avatarSilhouette(c, phase));
   const color = (offset: number, light: number, alpha = 1) =>
     `hsla(${c.hue + offset},${c.saturation}%,${light}%,${alpha})`;
   ctx.fillStyle = color(0, c.material === 'solid' ? 55 : 58);
@@ -186,7 +186,7 @@ export function drawAvatar(
   ctx.restore();
   if (c.face) {
     ctx.save();
-    ctx.clip(silhouette(c, phase));
+    ctx.clip(avatarSilhouette(c, phase));
     drawFace(ctx, c, phase, rig, gaze, cssSize);
     ctx.restore();
     if (c.idle) drawSleepMarks(ctx, c, phase, gaze);

package/src/agent-avatar/avatar-color.ts

@@ -0,0 +1,17 @@
+import type { AvatarConfig } from './model';
+
+export function avatarHex(
+  c: Pick<AvatarConfig, 'hue' | 'saturation' | 'lightness'>,
+) {
+  const light = (c.lightness ?? 76) / 100,
+    a = (c.saturation / 100) * Math.min(light, 1 - light);
+  const channel = (n: number) => {
+    const k = (n + c.hue / 30) % 12;
+    return Math.round(
+      255 * (light - a * Math.max(-1, Math.min(k - 3, 9 - k, 1))),
+    )
+      .toString(16)
+      .padStart(2, '0');
+  };
+  return `#${channel(0)}${channel(8)}${channel(4)}`;
+}

package/src/agent-avatar/character-html.ts

@@ -0,0 +1,21 @@
+/** Escape script delimiters in saved recipes; never interpolate appearance text as HTML. */
+export const scriptJson = (value: unknown) =>
+  JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+
+export function characterHtml(runtimeUrl: string, props: unknown) {
+  return `<!doctype html><html><head><meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no"><style>html,body{margin:0;width:100%;height:100%;overflow:hidden;background:transparent}canvas{display:block;width:100%;height:100%;touch-action:none}</style></head><body><canvas id="avatar"></canvas><script type="module">
+let controller, latest=${scriptJson(props)};
+const report = type => window.ReactNativeWebView.postMessage(type);
+window.updateCharacter = value => { latest=value; try { controller?.update(value); } catch { report('error'); } };
+try {
+ const {createAvatar}=await import(${scriptJson(runtimeUrl)});
+ controller=await createAvatar(document.querySelector('canvas'),latest,{onReady:()=>report('ready'),onError:()=>report('error'),onCapabilities:value=>report('capabilities:'+JSON.stringify(value))});
+ controller.update(latest);
+ report('loaded');
+} catch { report('error'); }
+window.addEventListener('pagehide',()=>controller?.dispose(),{once:true});
+</script></body></html>`;
+}

package/src/agent-avatar/character-runtime-module.ts

@@ -0,0 +1,37 @@
+/** Native Metro cannot analyze import(variable); load the optional browser module as a module script. */
+const registryKey = Symbol.for('bloom.character.runtimes');
+const pending = new Map<string, Promise<unknown>>();
+export function loadCharacterRuntime<T>(url: string): Promise<T> {
+  const resolved = new URL(url, document.baseURI).href;
+  const registry = (
+    globalThis as unknown as Record<symbol, Map<string, unknown>>
+  )[registryKey];
+  const existing = registry?.get(resolved);
+  if (existing) return Promise.resolve(existing as T);
+  const request = pending.get(resolved);
+  if (request) return request as Promise<T>;
+  const promise = new Promise<unknown>((resolve, reject) => {
+    const script = document.createElement('script');
+    script.type = 'module';
+    script.src = resolved;
+    script.onload = () => {
+      script.remove();
+      const loaded = (
+        globalThis as unknown as Record<symbol, Map<string, unknown>>
+      )[registryKey]?.get(resolved);
+      if (loaded) resolve(loaded);
+      else {
+        pending.delete(resolved);
+        reject(new Error('Invalid character runtime module'));
+      }
+    };
+    script.onerror = () => {
+      script.remove();
+      pending.delete(resolved);
+      reject(new Error('Character runtime could not be loaded'));
+    };
+    document.head.appendChild(script);
+  });
+  pending.set(resolved, promise);
+  return promise as Promise<T>;
+}

package/src/agent-avatar/character-webview.ts

@@ -0,0 +1,24 @@
+import type { ComponentType, Ref } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type CharacterWebViewHandle = { injectJavaScript(script: string): void };
+type Props = {
+  ref?: Ref<CharacterWebViewHandle>;
+  source: { html: string; baseUrl: string };
+  style: StyleProp<ViewStyle>;
+  scrollEnabled: boolean;
+  javaScriptEnabled: boolean;
+  originWhitelist: string[];
+  onMessage(event: { nativeEvent: { data: string } }): void;
+};
+let cached: ComponentType<Props> | null | undefined;
+export function characterWebView() {
+  if (cached !== undefined) return cached;
+  try {
+    const module = require('react-native-webview');
+    cached = module.WebView as ComponentType<Props>;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}

package/src/agent-avatar/config-character.ts

@@ -0,0 +1,40 @@
+/** Catalog parts extend the existing avatar recipe without discarding its shape or expression fields. */
+export type AvatarCharacterCategory = 'shape' | 'color' | 'eyes' | 'eyewear' | 'accessory';
+
+export type AvatarCharacterConfig = {
+  preset: string;
+  selections?: Partial<Record<AvatarCharacterCategory, string>>;
+  /** Custom body RGB accepted by the original renderer, stored as lowercase #RRGGBB. */
+  bodyColor?: string;
+};
+
+const categories: readonly AvatarCharacterCategory[] = ['shape', 'color', 'eyes', 'eyewear', 'accessory'];
+const validId = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0 && value.length <= 63;
+
+/** Validate the JSON boundary before passing saved configuration to the optional renderer. */
+export function parseCharacterConfig(value: unknown): AvatarCharacterConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Invalid character configuration.');
+  const candidate = value as Record<string, unknown>;
+  if (!validId(candidate.preset)) throw new Error('Invalid character preset.');
+  const result: AvatarCharacterConfig = { preset: candidate.preset };
+  if (candidate.bodyColor !== undefined) {
+    if (typeof candidate.bodyColor !== 'string' || candidate.bodyColor.length !== 7 || !/^#[0-9a-f]{6}$/i.test(candidate.bodyColor))
+      throw new Error('Invalid character body color.');
+    result.bodyColor = candidate.bodyColor.toLowerCase();
+  }
+  if (candidate.selections !== undefined) {
+    if (!candidate.selections || typeof candidate.selections !== 'object' || Array.isArray(candidate.selections))
+      throw new Error('Invalid character selections.');
+    const selections: NonNullable<AvatarCharacterConfig['selections']> = {};
+    for (const [category, id] of Object.entries(candidate.selections)) {
+      if (!categories.includes(category as AvatarCharacterCategory) || !validId(id))
+        throw new Error('Invalid character selection.');
+      selections[category as AvatarCharacterCategory] = id;
+    }
+    result.selections = selections;
+  }
+  if ('state' in candidate) throw new Error('Opaque character state is not supported.');
+  return result;
+}

package/src/agent-avatar/context.ts

@@ -5,3 +5,16 @@ import type { DrawingContext } from './drawing';
 export const AvatarDrawingObserver = createContext<
   ((drawing: DrawingContext) => void) | null
 >(null);
+
+export type CharacterCapabilities = {
+  key: string;
+  available: Record<string, boolean>;
+  selected: Record<string, string>;
+};
+/** The application hosts the optional renderer assets at this module URL. */
+export const CharacterRuntimeContext = createContext<{
+  runtimeUrl?: string;
+  capabilities?: CharacterCapabilities;
+  capabilitiesByKey?: ReadonlyMap<string, CharacterCapabilities>;
+  reportCapabilities?: (value: CharacterCapabilities) => void;
+}>({});

package/src/agent-avatar/index.ts

@@ -24,4 +24,7 @@ export {
   parsePreset,
 } from './model';
 export type { AvatarConfig, AvatarFamily, AvatarPreset } from './model';
-export type { AgentAvatarProps } from './types';
+export type { AgentAvatarProps, AgentAvatarProviderProps } from './types';
+
+export { AgentAvatarProvider } from './AgentAvatarProvider';
+export type { AvatarCharacterConfig, AvatarCharacterCategory } from './config-character';

package/src/agent-avatar/legacy-contours.ts

@@ -0,0 +1,76 @@
+import { avatarSilhouette } from './artwork';
+import { DrawingContext, type DrawingPath, type Point } from './drawing';
+import { expressionRig } from './face';
+import { drawFold } from './fold';
+import type { AvatarConfig } from './model';
+import type { ShapeMorph } from './shape-morph';
+
+/** Sample the existing artwork, so a migrated silhouette has one source of truth. */
+function samplePath(path: DrawingPath): Point[] {
+  const points: Point[] = [];
+  let current: Point = [0, 0];
+  for (const { kind, values: v } of path.commands) {
+    if (kind === 'M' || kind === 'L') {
+      current = [v[0]!, v[1]!];
+      points.push(current);
+    } else if (kind === 'C' || kind === 'Q') {
+      const from = current;
+      for (let step = 1; step <= 24; step++) {
+        const t = step / 24,
+          u = 1 - t;
+        current =
+          kind === 'C'
+            ? [
+                u ** 3 * from[0] +
+                  3 * u * u * t * v[0]! +
+                  3 * u * t * t * v[2]! +
+                  t ** 3 * v[4]!,
+                u ** 3 * from[1] +
+                  3 * u * u * t * v[1]! +
+                  3 * u * t * t * v[3]! +
+                  t ** 3 * v[5]!,
+              ]
+            : [
+                u * u * from[0] + 2 * u * t * v[0]! + t * t * v[2]!,
+                u * u * from[1] + 2 * u * t * v[1]! + t * t * v[3]!,
+              ];
+        points.push(current);
+      }
+    } else if (kind !== 'Z') {
+      throw new Error('Unsupported legacy contour command');
+    }
+  }
+  return points;
+}
+
+/** Engine coordinates: Y upwards, the existing circular body's radius is one. */
+export function legacyContours(config: AvatarConfig): Point[][] {
+  const rest = { ...config, motion: 0, idle: false, face: false };
+  if (rest.family !== 'fold') {
+    return [
+      samplePath(avatarSilhouette(rest, 0)).map(([x, y]) => [x / 83, -y / 83]),
+    ];
+  }
+  const morph: ShapeMorph = { started: 0, active: false };
+  drawFold(
+    new DrawingContext(),
+    rest,
+    0,
+    expressionRig(rest),
+    [0, 0],
+    200,
+    null,
+    0,
+    1,
+    0,
+    morph,
+  );
+  const geometry = morph.last!;
+  const direction = rest.foldDirection === 'left' ? -1 : 1;
+  return [geometry.paper, geometry.back].map((path) =>
+    samplePath(path).map(([x, y]) => [
+      (x * geometry.sx * direction) / 83,
+      -y / 83,
+    ]),
+  );
+}