@blario/react-native 0.0.0-stage → 0.1.0

package/src/nudge/nudge.ts

@@ -0,0 +1,100 @@
+import { isRecord, nonEmptyString, type UnknownRecord } from '../fiber/narrow.ts';
+
+export interface NudgeSender {
+  name: string;
+  subtitle: string | null;
+  avatarUrl: string | null;
+}
+
+export interface NudgeProgress {
+  total: number;
+  completed: number;
+}
+
+export interface NudgeView {
+  bubbleMessage: string;
+  continuation: boolean;
+  milestoneMessageId: number | null;
+  sessionId: number | null;
+  sender: NudgeSender | null;
+  progress: NudgeProgress | null;
+  ctaLabel: string | null;
+}
+
+interface NudgeContext {
+  milestoneMessageId: number | null;
+  sessionId: number | null;
+  continuation: boolean;
+  ctaLabel: string | null;
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === 'number' ? value : null;
+}
+
+function readSender(raw: unknown): NudgeSender | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  const name = nonEmptyString(raw.name);
+  return name === null ? null : { name, subtitle: nonEmptyString(raw.subtitle), avatarUrl: nonEmptyString(raw.avatar_url) };
+}
+
+function readProgress(raw: unknown): NudgeProgress | null {
+  if (!isRecord(raw) || typeof raw.total !== 'number' || typeof raw.completed !== 'number') {
+    return null;
+  }
+  return { total: raw.total, completed: raw.completed };
+}
+
+function readNudge(wire: UnknownRecord, context: NudgeContext): NudgeView | null {
+  const bubbleMessage = nonEmptyString(wire.bubble_message);
+  if (bubbleMessage === null) {
+    return null;
+  }
+  return {
+    bubbleMessage,
+    continuation: wire.bubble_kind === 'channel_continuation' || context.continuation,
+    milestoneMessageId: context.milestoneMessageId,
+    sessionId: context.sessionId,
+    sender: readSender(wire.bubble_sender),
+    progress: readProgress(wire.bubble_progress),
+    ctaLabel: nonEmptyString(wire.bubble_cta_label) ?? context.ctaLabel,
+  };
+}
+
+export function parseHistoryNudge(frame: UnknownRecord): NudgeView | null {
+  return readNudge(frame, {
+    milestoneMessageId: numberOrNull(frame.milestone_message_id),
+    sessionId: numberOrNull(frame.session_id),
+    continuation: false,
+    ctaLabel: null,
+  });
+}
+
+export function parseMessageNudge(frame: UnknownRecord, currentSessionId: number | null): NudgeView | null {
+  const message = isRecord(frame.message) ? frame.message : null;
+  if (message === null) {
+    return null;
+  }
+  const metadata = isRecord(message.metadata) ? message.metadata : {};
+  return readNudge(message, {
+    milestoneMessageId: numberOrNull(metadata.milestone_message_id),
+    sessionId: currentSessionId,
+    continuation: metadata.widget_bubble_kind === 'channel_continuation',
+    ctaLabel: nonEmptyString(metadata.widget_bubble_cta_label),
+  });
+}
+
+export function parseFrameNudge(frame: UnknownRecord, currentSessionId: number | null): NudgeView | null {
+  if (frame.type === 'history') {
+    return parseHistoryNudge(frame);
+  }
+  return frame.type === 'message' ? parseMessageNudge(frame, currentSessionId) : null;
+}
+
+export function initialsOf(name: string): string {
+  const parts = name.trim().split(/\s+/).filter((part) => part.length > 0);
+  const letters = parts.slice(0, 2).map((part) => part.charAt(0).toUpperCase());
+  return letters.join('');
+}

package/src/optional/expo-haptics.ts

@@ -0,0 +1,11 @@
+declare const require: (moduleName: string) => unknown;
+
+function loadExpoHaptics(): unknown {
+  try {
+    return require('expo-haptics');
+  } catch {
+    return null;
+  }
+}
+
+export const EXPO_HAPTICS: unknown = loadExpoHaptics();

package/src/optional/expo-keep-awake.ts

@@ -0,0 +1,11 @@
+declare const require: (moduleName: string) => unknown;
+
+function loadExpoKeepAwake(): unknown {
+  try {
+    return require('expo-keep-awake');
+  } catch {
+    return null;
+  }
+}
+
+export const EXPO_KEEP_AWAKE: unknown = loadExpoKeepAwake();

package/src/optional/react-native-haptic-feedback.ts

@@ -0,0 +1,11 @@
+declare const require: (moduleName: string) => unknown;
+
+function loadReactNativeHapticFeedback(): unknown {
+  try {
+    return require('react-native-haptic-feedback');
+  } catch {
+    return null;
+  }
+}
+
+export const REACT_NATIVE_HAPTIC_FEEDBACK: unknown = loadReactNativeHapticFeedback();

package/src/optional/react-native-keep-awake.ts

@@ -0,0 +1,11 @@
+declare const require: (moduleName: string) => unknown;
+
+function loadReactNativeKeepAwake(): unknown {
+  try {
+    return require('react-native-keep-awake');
+  } catch {
+    return null;
+  }
+}
+
+export const REACT_NATIVE_KEEP_AWAKE: unknown = loadReactNativeKeepAwake();

package/src/overlay/AgentOverlay.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { AGENT_OVERLAY_TEST_ID } from '../snapshot/collect.ts';
+
+export interface AgentOverlayProps {
+  children?: React.ReactNode;
+}
+
+export function AgentOverlay({ children }: AgentOverlayProps): React.JSX.Element {
+  return (
+    <View pointerEvents="box-none" testID={AGENT_OVERLAY_TEST_ID} style={StyleSheet.absoluteFill} collapsable={false}>
+      {children}
+    </View>
+  );
+}

package/src/screenshot/capture-backend.ts

@@ -0,0 +1,7 @@
+import type { ScreenshotOptions } from '../agent/frames.ts';
+
+export interface CaptureBackend {
+  name: string;
+  capturesModals: boolean;
+  capture: (target: unknown, options: ScreenshotOptions) => Promise<string>;
+}

package/src/screenshot/screenshotter.ts

@@ -0,0 +1,39 @@
+import { Platform } from 'react-native';
+
+import type { ScreenshotOptions } from '../agent/frames.ts';
+import type { CaptureBackend } from './capture-backend.ts';
+import { SKIA_MODULE, skiaBackend } from './skia.ts';
+import { VIEW_SHOT_BACKEND } from './view-shot.ts';
+
+export type ScreenshotResult = { ok: true; dataUrl: string; capturesModals: boolean } | { ok: false; reason: string };
+
+const SKIA_BACKEND = SKIA_MODULE === null ? null : skiaBackend(SKIA_MODULE, Platform.OS);
+
+export const CAPTURE_BACKEND: CaptureBackend | null = VIEW_SHOT_BACKEND ?? SKIA_BACKEND;
+
+export class Screenshotter {
+  constructor(
+    private readonly getCaptureTarget: () => unknown,
+    private readonly backend: CaptureBackend | null = CAPTURE_BACKEND,
+  ) {}
+
+  isAvailable(): boolean {
+    return this.backend !== null;
+  }
+
+  async capture(options: ScreenshotOptions): Promise<ScreenshotResult> {
+    const backend = this.backend;
+    if (backend === null) {
+      return { ok: false, reason: 'no capture module: install react-native-view-shot (or @shopify/react-native-skia on iOS)' };
+    }
+    const target = this.getCaptureTarget();
+    if (target === null || target === undefined) {
+      return { ok: false, reason: 'the provider is not mounted' };
+    }
+    try {
+      return { ok: true, dataUrl: await backend.capture(target, options), capturesModals: backend.capturesModals };
+    } catch (error) {
+      return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+}

package/src/screenshot/skia.ts

@@ -0,0 +1,107 @@
+import type { ScreenshotOptions } from '../agent/frames.ts';
+import { isFunction, isRecord } from '../fiber/narrow.ts';
+import type { CaptureBackend } from './capture-backend.ts';
+
+interface SkiaImage {
+  width: () => number;
+  height: () => number;
+  encodeToBase64: (format: number, quality: number) => string;
+  dispose: () => void;
+}
+
+interface SkiaCanvas {
+  drawImageRect: (image: SkiaImage, source: unknown, destination: unknown, paint: unknown) => void;
+}
+
+interface SkiaSurface {
+  getCanvas: () => SkiaCanvas;
+  flush: () => void;
+  makeImageSnapshot: () => SkiaImage;
+  dispose: () => void;
+}
+
+export interface SkiaModule {
+  makeImageFromView: (viewRef: { current: unknown }) => Promise<SkiaImage | null>;
+  ImageFormat: { JPEG: number };
+  Skia: {
+    Surface: { Make: (width: number, height: number) => SkiaSurface | null };
+    XYWHRect: (x: number, y: number, width: number, height: number) => unknown;
+    Paint: () => unknown;
+  };
+}
+
+declare const require: (moduleName: string) => unknown;
+
+export function isSkiaModule(value: unknown): value is SkiaModule {
+  return (
+    isRecord(value) &&
+    isFunction(value.makeImageFromView) &&
+    isRecord(value.ImageFormat) &&
+    typeof value.ImageFormat.JPEG === 'number' &&
+    isRecord(value.Skia) &&
+    isRecord(value.Skia.Surface) &&
+    isFunction(value.Skia.Surface.Make) &&
+    isFunction(value.Skia.XYWHRect) &&
+    isFunction(value.Skia.Paint)
+  );
+}
+
+function loadSkia(): SkiaModule | null {
+  try {
+    const loaded = require('@shopify/react-native-skia');
+    return isSkiaModule(loaded) ? loaded : null;
+  } catch {
+    return null;
+  }
+}
+
+function encodeScaled(skia: SkiaModule, image: SkiaImage, options: ScreenshotOptions): string {
+  const quality = Math.round(options.quality * 100);
+  const width = image.width();
+  const height = image.height();
+  if (width <= options.maxWidth) {
+    return image.encodeToBase64(skia.ImageFormat.JPEG, quality);
+  }
+  const scaledHeight = Math.round((height * options.maxWidth) / width);
+  const surface = skia.Skia.Surface.Make(options.maxWidth, scaledHeight);
+  if (surface === null) {
+    return image.encodeToBase64(skia.ImageFormat.JPEG, quality);
+  }
+  try {
+    surface
+      .getCanvas()
+      .drawImageRect(image, skia.Skia.XYWHRect(0, 0, width, height), skia.Skia.XYWHRect(0, 0, options.maxWidth, scaledHeight), skia.Skia.Paint());
+    surface.flush();
+    const scaled = surface.makeImageSnapshot();
+    try {
+      return scaled.encodeToBase64(skia.ImageFormat.JPEG, quality);
+    } finally {
+      scaled.dispose();
+    }
+  } finally {
+    surface.dispose();
+  }
+}
+
+export function skiaBackend(skia: SkiaModule, platform: string): CaptureBackend | null {
+  if (platform !== 'ios') {
+    return null;
+  }
+  return {
+    name: '@shopify/react-native-skia',
+    capturesModals: false,
+    capture: async (target, options) => {
+      const image = await skia.makeImageFromView({ current: target });
+      if (image === null) {
+        throw new Error('Skia could not capture the view');
+      }
+      try {
+        return `data:image/jpeg;base64,${encodeScaled(skia, image, options)}`;
+      } finally {
+        image.dispose();
+      }
+    },
+  };
+}
+
+export const SKIA_MODULE: SkiaModule | null = loadSkia();

package/src/screenshot/view-shot.ts

@@ -0,0 +1,41 @@
+import { isFunction, isRecord } from '../fiber/narrow.ts';
+import type { CaptureBackend } from './capture-backend.ts';
+
+interface ViewShotOptions {
+  format: 'jpg';
+  quality: number;
+  result: 'data-uri';
+  width: number;
+}
+
+interface ViewShotModule {
+  captureRef: (target: unknown, options: ViewShotOptions) => Promise<string>;
+}
+
+declare const require: (moduleName: string) => unknown;
+
+function isViewShotModule(value: unknown): value is ViewShotModule {
+  return isRecord(value) && isFunction(value.captureRef);
+}
+
+function loadViewShot(): ViewShotModule | null {
+  try {
+    const loaded = require('react-native-view-shot');
+    return isViewShotModule(loaded) ? loaded : null;
+  } catch {
+    return null;
+  }
+}
+
+function viewShotBackend(viewShot: ViewShotModule): CaptureBackend {
+  return {
+    name: 'react-native-view-shot',
+    capturesModals: false,
+    capture: (target, options) =>
+      viewShot.captureRef(target, { format: 'jpg', quality: options.quality, result: 'data-uri', width: options.maxWidth }),
+  };
+}
+
+const VIEW_SHOT = loadViewShot();
+
+export const VIEW_SHOT_BACKEND: CaptureBackend | null = VIEW_SHOT === null ? null : viewShotBackend(VIEW_SHOT);

package/src/snapshot/capture.ts

@@ -0,0 +1,163 @@
+import { currentRootFiber } from '../fiber/locate.ts';
+import type { Fiber } from '../fiber/types.ts';
+import { measureHost } from '../host/measure.ts';
+import type { Size } from '../host/rect.ts';
+import { type Candidate, collect, keepInnermostPerHost } from './collect.ts';
+import type { ElementKind } from './kinds.ts';
+import type { ScreenRef } from './navigation.ts';
+import { describeRoutes, describeScreenPath } from './route-summary.ts';
+import { ElementRegistry, type RegisteredElement } from './registry.ts';
+import { countTwins, renderLine, renderSnapshotText, twinSignature } from './render.ts';
+import { describeScrollDirections } from './scroll.ts';
+import { groupIntoLines, limitCharacters, type PositionedText } from './text-layout.ts';
+import { orderForReading } from './ordering.ts';
+import { buildView } from './view.ts';
+import { classifyVisibility, keepInTextTree, measureScrollGeometries, type ScrollGeometries } from './visibility.ts';
+import { dropWrapperDuplicates, limitOffscreen, type MeasuredCandidate } from './wrappers.ts';
+
+export interface Snapshot {
+  screen: string;
+  routes: string[];
+  text: string;
+  elements: RegisteredElement[];
+  modalOpen: boolean;
+}
+
+export interface SnapshotDependencies {
+  getAnchorFiber: () => Fiber | null;
+  registry: ElementRegistry;
+  getViewport: () => Size;
+  getExtraRoutes: () => string[];
+}
+
+export type CaptureMode = 'register' | 'peek';
+
+export interface TextTreeOptions {
+  viewportOnly: boolean;
+  maxChars: number;
+}
+
+export interface TextTree {
+  screen: string;
+  text: string;
+}
+
+const EMPTY_SNAPSHOT: Snapshot = { screen: '', routes: [], text: renderSnapshotText({ screen: '', routes: [] }, []), elements: [], modalOpen: false };
+
+export class SnapshotCapturer {
+  constructor(private readonly dependencies: SnapshotDependencies) {}
+
+  async capture(mode: CaptureMode): Promise<Snapshot> {
+    const anchor = this.dependencies.getAnchorFiber();
+    const root = anchor === null ? null : currentRootFiber(anchor);
+    if (root === null) {
+      return EMPTY_SNAPSHOT;
+    }
+    const { candidates, focusedScreens, modalOpen } = collect(root);
+    const kept = keepInnermostPerHost(candidates);
+    const geometries = await measureScrollGeometries(scrollContainersOf(kept));
+    const measured = await this.measureVisible(kept, geometries);
+    const ordered = orderForReading(dropWrapperDuplicates(measured));
+    return this.assemble(mode, ordered, geometries, { focusedScreens, modalOpen });
+  }
+
+  async captureText(options: TextTreeOptions): Promise<TextTree> {
+    const anchor = this.dependencies.getAnchorFiber();
+    const root = anchor === null ? null : currentRootFiber(anchor);
+    if (root === null) {
+      return { screen: '', text: '' };
+    }
+    const { textBlocks, focusedScreens } = collect(root);
+    const geometries = await measureScrollGeometries(textBlocks.flatMap((block) => block.scrollContainers));
+    const viewport = this.dependencies.getViewport();
+    const measured = await Promise.all(
+      textBlocks.map(async (block): Promise<PositionedText | null> => {
+        const rect = await measureHost(block.host);
+        if (rect === null || rect.width <= 0 || rect.height <= 0) {
+          return null;
+        }
+        const visibility = classifyVisibility(rect, viewport, block.scrollContainers, geometries);
+        return keepInTextTree(visibility, rect, viewport, options.viewportOnly) ? { rect, text: block.text, heading: block.heading } : null;
+      }),
+    );
+    const lines = limitCharacters(groupIntoLines(measured.filter((entry): entry is PositionedText => entry !== null)), options.maxChars);
+    const screen = describeScreenPath(focusedScreens);
+    return { screen, text: [`screen: ${screen}`, '', ...lines].join('\n') };
+  }
+
+  readFocusedScreens(): ScreenRef[] {
+    const anchor = this.dependencies.getAnchorFiber();
+    const root = anchor === null ? null : currentRootFiber(anchor);
+    return root === null ? [] : collect(root).focusedScreens;
+  }
+
+  private async measureVisible(kept: Candidate[], geometries: ScrollGeometries): Promise<MeasuredCandidate[]> {
+    const viewport = this.dependencies.getViewport();
+    const measured = await Promise.all(
+      kept.map(async (candidate): Promise<MeasuredCandidate | null> => {
+        const rect = await measureHost(candidate.host);
+        if (rect === null) {
+          return null;
+        }
+        const visibility = classifyVisibility(rect, viewport, candidate.scrollContainers, geometries);
+        if (visibility.kind === 'hidden') {
+          return null;
+        }
+        const offscreen = visibility.kind === 'offscreen' ? visibility : null;
+        return { candidate, rect, offscreen: offscreen?.direction ?? null, distance: offscreen?.distance ?? 0 };
+      }),
+    );
+    return limitOffscreen(measured.filter((entry): entry is MeasuredCandidate => entry !== null));
+  }
+
+  private assemble(
+    mode: CaptureMode,
+    ordered: MeasuredCandidate[],
+    geometries: ScrollGeometries,
+    scene: { focusedScreens: ScreenRef[]; modalOpen: boolean },
+  ): Snapshot {
+    const views = ordered.map(({ candidate, rect, offscreen }) =>
+      buildView({
+        kind: candidate.kind,
+        fiber: candidate.fiber,
+        ancestors: candidate.ancestors,
+        rect,
+        scroll: candidate.kind === 'scroll' ? describeScrollDirections(geometries.get(candidate.fiber) ?? null) : null,
+        offscreen,
+      }),
+    );
+    if (mode === 'register') {
+      this.dependencies.registry.begin();
+    }
+    const twinCounts = countTwins(views);
+    const elements: RegisteredElement[] = [];
+    const lines = views.map((view, index) => {
+      const measuredEntry = ordered[index];
+      const twins = (twinCounts.get(twinSignature(view)) ?? 1) - 1;
+      const agentId = mode === 'register' && measuredEntry !== undefined ? this.register(view.kind, measuredEntry, elements) : null;
+      return renderLine(view, agentId, twins);
+    });
+    const header = {
+      screen: describeScreenPath(scene.focusedScreens),
+      routes: describeRoutes(scene.focusedScreens, this.dependencies.getExtraRoutes()),
+    };
+    return { ...header, text: renderSnapshotText(header, lines), elements, modalOpen: scene.modalOpen };
+  }
+
+  private register(kind: ElementKind, entry: MeasuredCandidate, elements: RegisteredElement[]): string {
+    const element = this.dependencies.registry.register(kind, entry.candidate.fiber, entry.rect);
+    elements.push(element);
+    return element.agentId;
+  }
+}
+
+function scrollContainersOf(kept: Candidate[]): Set<Fiber> {
+  const containers = new Set<Fiber>();
+  for (const candidate of kept) {
+    candidate.scrollContainers.forEach((container) => containers.add(container));
+    if (candidate.kind === 'scroll') {
+      containers.add(candidate.fiber);
+    }
+  }
+  return containers;
+}

package/src/snapshot/classify.ts

@@ -0,0 +1,40 @@
+import { isFunction, isRecord } from '../fiber/narrow.ts';
+import { componentName, propsOf } from '../fiber/reader.ts';
+import { type Fiber, FiberTag } from '../fiber/types.ts';
+import type { ElementKind } from './kinds.ts';
+
+export interface ScrollInstance {
+  scrollTo: (options: { x?: number; y?: number; animated?: boolean }) => void;
+}
+
+export function scrollInstanceOf(fiber: Fiber): ScrollInstance | null {
+  if (fiber.tag !== FiberTag.ClassComponent) {
+    return null;
+  }
+  const instance = fiber.stateNode;
+  return isRecord(instance) && isFunction(instance.scrollTo) ? (instance as unknown as ScrollInstance) : null;
+}
+
+function isTextInput(fiber: Fiber, props: Readonly<Record<string, unknown>>): boolean {
+  return isFunction(props.onChangeText) || componentName(fiber) === 'TextInput';
+}
+
+export function classify(fiber: Fiber): ElementKind | null {
+  if (scrollInstanceOf(fiber) !== null) {
+    return 'scroll';
+  }
+  if (typeof fiber.type === 'string') {
+    return null;
+  }
+  const props = propsOf(fiber);
+  if (isTextInput(fiber, props)) {
+    return 'text_input';
+  }
+  if (isFunction(props.onValueChange) && typeof props.value === 'boolean') {
+    return 'switch';
+  }
+  if (isFunction(props.onPress)) {
+    return 'button';
+  }
+  return null;
+}