@scalebun/react-native 1.0.0 → 1.0.2

package/src/features/engage/__test-support__/reactNativeStub.js

@@ -1,40 +1,40 @@
-/**
- * Minimal react-native stub for Node-run unit tests.
- *
- * The engage renderer-selection tests import the view/provider modules to assert
- * the PROMPT_RENDERERS registry and pure answer-assembly logic. They never render
- * a tree, so the components only need to exist as value references for compiled
- * React.createElement calls — no native runtime is required.
- */
-
-const passthrough = (name) => {
-    const Comp = () => null;
-    Comp.displayName = name;
-    return Comp;
-};
-
-module.exports = {
-    Modal: passthrough('Modal'),
-    View: passthrough('View'),
-    Text: passthrough('Text'),
-    TextInput: passthrough('TextInput'),
-    Pressable: passthrough('Pressable'),
-    Image: passthrough('Image'),
-    Platform: { OS: 'ios', select: (obj) => (obj ? obj.ios ?? obj.default : undefined) },
-    NativeModules: {},
-    useWindowDimensions: () => ({ width: 390, height: 844, scale: 3, fontScale: 1 }),
-    StyleSheet: { create: (styles) => styles },
-    AppState: {
-        currentState: 'active',
-        addEventListener: () => ({ remove: () => {} }),
-        removeEventListener: () => {},
-    },
-    // Native module specs resolve through TurboModuleRegistry.get(). Under Node it
-    // returns null so the SDK takes its graceful no-native path (e.g. StorageBackend
-    // falls back to the in-memory backend). Tests that need a native module inject a
-    // fake directly into the class under test.
-    TurboModuleRegistry: {
-        get: () => null,
-        getEnforcing: () => null,
-    },
-};
+/**
+ * Minimal react-native stub for Node-run unit tests.
+ *
+ * The engage renderer-selection tests import the view/provider modules to assert
+ * the PROMPT_RENDERERS registry and pure answer-assembly logic. They never render
+ * a tree, so the components only need to exist as value references for compiled
+ * React.createElement calls — no native runtime is required.
+ */
+
+const passthrough = (name) => {
+    const Comp = () => null;
+    Comp.displayName = name;
+    return Comp;
+};
+
+module.exports = {
+    Modal: passthrough('Modal'),
+    View: passthrough('View'),
+    Text: passthrough('Text'),
+    TextInput: passthrough('TextInput'),
+    Pressable: passthrough('Pressable'),
+    Image: passthrough('Image'),
+    Platform: { OS: 'ios', select: (obj) => (obj ? obj.ios ?? obj.default : undefined) },
+    NativeModules: {},
+    useWindowDimensions: () => ({ width: 390, height: 844, scale: 3, fontScale: 1 }),
+    StyleSheet: { create: (styles) => styles },
+    AppState: {
+        currentState: 'active',
+        addEventListener: () => ({ remove: () => {} }),
+        removeEventListener: () => {},
+    },
+    // Native module specs resolve through TurboModuleRegistry.get(). Under Node it
+    // returns null so the SDK takes its graceful no-native path (e.g. StorageBackend
+    // falls back to the in-memory backend). Tests that need a native module inject a
+    // fake directly into the class under test.
+    TurboModuleRegistry: {
+        get: () => null,
+        getEnforcing: () => null,
+    },
+};

package/src/features/engage/attachmentCapture.ts

@@ -1,45 +1,45 @@
-/**
- * ScaleBun SDK — Engage attachment capture (P3-e)
- *
- * Screenshot attachments REUSE the replay capture pipeline rather than forking a
- * second one: `bridgeAdapter.captureScreenshot` runs the native FrameCaptureManager,
- * which applies PrivacyMaskProcessor (text inputs masked by default). So the bytes
- * are ALREADY PII-masked — we never produce an unmasked screenshot here. The result
- * is a base64 frame the EngageTransport presigns + PUTs direct to storage.
- */
-
-import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
-import { logger } from '../../core/logger/internalLogger';
-import type { EngageAttachmentDraft } from './engageTypes';
-
-/**
- * Capture a masked screenshot of the current screen as a feedback attachment.
- * Returns null if the native capture is unavailable or fails (the prompt still
- * submits without the attachment — capture is best-effort, never blocking).
- */
-export async function captureScreenshotAttachment(): Promise<EngageAttachmentDraft | null> {
-    try {
-        const frame = await bridgeAdapter.captureScreenshot('engage-feedback-attachment');
-        if (!frame || !frame.base64) {
-            logger.warn('[Engage] screenshot capture returned no frame');
-            return null;
-        }
-        const mime = typeof frame.format === 'string' && frame.format.includes('png')
-            ? 'image/png'
-            : 'image/jpeg';
-        return {
-            kind: 'screenshot',
-            base64: frame.base64,
-            mime,
-            width: frame.width,
-            height: frame.height,
-            byteSize: frame.sizeBytes,
-            // Native FrameCaptureManager masks text inputs by default — this path is
-            // always masked, so the flag is truthfully true.
-            masked: true,
-        };
-    } catch (err: any) {
-        logger.warn(`[Engage] screenshot capture failed: ${err?.message}`);
-        return null;
-    }
-}
+/**
+ * ScaleBun SDK — Engage attachment capture (P3-e)
+ *
+ * Screenshot attachments REUSE the replay capture pipeline rather than forking a
+ * second one: `bridgeAdapter.captureScreenshot` runs the native FrameCaptureManager,
+ * which applies PrivacyMaskProcessor (text inputs masked by default). So the bytes
+ * are ALREADY PII-masked — we never produce an unmasked screenshot here. The result
+ * is a base64 frame the EngageTransport presigns + PUTs direct to storage.
+ */
+
+import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
+import { logger } from '../../core/logger/internalLogger';
+import type { EngageAttachmentDraft } from './engageTypes';
+
+/**
+ * Capture a masked screenshot of the current screen as a feedback attachment.
+ * Returns null if the native capture is unavailable or fails (the prompt still
+ * submits without the attachment — capture is best-effort, never blocking).
+ */
+export async function captureScreenshotAttachment(): Promise<EngageAttachmentDraft | null> {
+    try {
+        const frame = await bridgeAdapter.captureScreenshot('engage-feedback-attachment');
+        if (!frame || !frame.base64) {
+            logger.warn('[Engage] screenshot capture returned no frame');
+            return null;
+        }
+        const mime = typeof frame.format === 'string' && frame.format.includes('png')
+            ? 'image/png'
+            : 'image/jpeg';
+        return {
+            kind: 'screenshot',
+            base64: frame.base64,
+            mime,
+            width: frame.width,
+            height: frame.height,
+            byteSize: frame.sizeBytes,
+            // Native FrameCaptureManager masks text inputs by default — this path is
+            // always masked, so the flag is truthfully true.
+            masked: true,
+        };
+    } catch (err: any) {
+        logger.warn(`[Engage] screenshot capture failed: ${err?.message}`);
+        return null;
+    }
+}

package/src/features/engage/captureVoiceAttachment.ts

@@ -1,81 +1,81 @@
-/**
- * ScaleBun SDK — Engage voice-note capture (Slice D4)
- *
- * Voice notes REUSE the same presign→PUT→metadata pipeline as screenshots — the
- * only new piece is the native mic recorder (AAC/.m4a, ≤30s hard-capped natively).
- * On stop, transcription runs through the swappable `TranscriptionProvider` seam
- * (default: on-device native STT, no network/creds). The returned transcript is a
- * PREFILL: the caller shows it editable and only sets `transcriptApproved` after
- * the user explicitly approves the final wording — nothing is sent before that.
- *
- * The 30s cap is enforced in THREE places (recorder UI auto-stop, native recorder
- * setMaxDuration/forDuration, backend duration validation). This function trusts
- * the native cap and surfaces the real recorded `durationMs`.
- */
-
-import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
-import { logger } from '../../core/logger/internalLogger';
-import type { EngageAttachmentDraft } from './engageTypes';
-import { getTranscriptionProvider } from './transcription/TranscriptionProvider';
-
-/** Hard cap mirrored from native recorders (Android 30000 / iOS 30000). */
-export const VOICE_MAX_DURATION_MS = 30_000;
-
-/** Begin a voice note. Best-effort — native handles mic permission prompt. */
-export async function startVoiceAttachment(): Promise<void> {
-    await bridgeAdapter.startVoiceRecording();
-}
-
-/** Cancel an in-progress recording, discarding bytes. */
-export async function cancelVoiceAttachment(): Promise<void> {
-    try {
-        await bridgeAdapter.cancelVoiceRecording();
-    } catch (err: any) {
-        logger.warn(`[Engage] voice cancel failed: ${err?.message}`);
-    }
-}
-
-/**
- * Stop recording, run on-device transcription, and return a voice attachment draft
- * (transcript NOT yet approved). Returns null if nothing was recorded or capture
- * is unavailable (the prompt can still submit without a voice note).
- *
- * The returned `durationMs` is the REAL recorded duration; it is also clamped to
- * the hard cap as a final SDK-side guard before the backend's own validation.
- */
-export async function stopVoiceAttachment(): Promise<EngageAttachmentDraft | null> {
-    try {
-        const clip = await bridgeAdapter.stopVoiceRecording();
-        if (!clip || !clip.base64) {
-            logger.warn('[Engage] voice recording returned no clip');
-            return null;
-        }
-
-        const durationMs = Math.max(0, Math.min(clip.durationMs ?? 0, VOICE_MAX_DURATION_MS - 1));
-
-        const { transcript } = await getTranscriptionProvider().transcribe({
-            base64: clip.base64,
-            mime: clip.mime,
-            durationMs,
-            byteSize: clip.byteSize,
-            nativeTranscript: clip.transcript,
-            nativeAvailable: clip.transcriptAvailable,
-        });
-
-        return {
-            kind: 'voice',
-            base64: clip.base64,
-            mime: clip.mime || 'audio/mp4',
-            byteSize: clip.byteSize,
-            durationMs,
-            // Recorder captures the user's own voice intentionally; no screen PII.
-            masked: true,
-            transcript,
-            // Caller flips this to true ONLY after explicit user approval.
-            transcriptApproved: false,
-        };
-    } catch (err: any) {
-        logger.warn(`[Engage] voice capture failed: ${err?.message}`);
-        return null;
-    }
-}
+/**
+ * ScaleBun SDK — Engage voice-note capture (Slice D4)
+ *
+ * Voice notes REUSE the same presign→PUT→metadata pipeline as screenshots — the
+ * only new piece is the native mic recorder (AAC/.m4a, ≤30s hard-capped natively).
+ * On stop, transcription runs through the swappable `TranscriptionProvider` seam
+ * (default: on-device native STT, no network/creds). The returned transcript is a
+ * PREFILL: the caller shows it editable and only sets `transcriptApproved` after
+ * the user explicitly approves the final wording — nothing is sent before that.
+ *
+ * The 30s cap is enforced in THREE places (recorder UI auto-stop, native recorder
+ * setMaxDuration/forDuration, backend duration validation). This function trusts
+ * the native cap and surfaces the real recorded `durationMs`.
+ */
+
+import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
+import { logger } from '../../core/logger/internalLogger';
+import type { EngageAttachmentDraft } from './engageTypes';
+import { getTranscriptionProvider } from './transcription/TranscriptionProvider';
+
+/** Hard cap mirrored from native recorders (Android 30000 / iOS 30000). */
+export const VOICE_MAX_DURATION_MS = 30_000;
+
+/** Begin a voice note. Best-effort — native handles mic permission prompt. */
+export async function startVoiceAttachment(): Promise<void> {
+    await bridgeAdapter.startVoiceRecording();
+}
+
+/** Cancel an in-progress recording, discarding bytes. */
+export async function cancelVoiceAttachment(): Promise<void> {
+    try {
+        await bridgeAdapter.cancelVoiceRecording();
+    } catch (err: any) {
+        logger.warn(`[Engage] voice cancel failed: ${err?.message}`);
+    }
+}
+
+/**
+ * Stop recording, run on-device transcription, and return a voice attachment draft
+ * (transcript NOT yet approved). Returns null if nothing was recorded or capture
+ * is unavailable (the prompt can still submit without a voice note).
+ *
+ * The returned `durationMs` is the REAL recorded duration; it is also clamped to
+ * the hard cap as a final SDK-side guard before the backend's own validation.
+ */
+export async function stopVoiceAttachment(): Promise<EngageAttachmentDraft | null> {
+    try {
+        const clip = await bridgeAdapter.stopVoiceRecording();
+        if (!clip || !clip.base64) {
+            logger.warn('[Engage] voice recording returned no clip');
+            return null;
+        }
+
+        const durationMs = Math.max(0, Math.min(clip.durationMs ?? 0, VOICE_MAX_DURATION_MS - 1));
+
+        const { transcript } = await getTranscriptionProvider().transcribe({
+            base64: clip.base64,
+            mime: clip.mime,
+            durationMs,
+            byteSize: clip.byteSize,
+            nativeTranscript: clip.transcript,
+            nativeAvailable: clip.transcriptAvailable,
+        });
+
+        return {
+            kind: 'voice',
+            base64: clip.base64,
+            mime: clip.mime || 'audio/mp4',
+            byteSize: clip.byteSize,
+            durationMs,
+            // Recorder captures the user's own voice intentionally; no screen PII.
+            masked: true,
+            transcript,
+            // Caller flips this to true ONLY after explicit user approval.
+            transcriptApproved: false,
+        };
+    } catch (err: any) {
+        logger.warn(`[Engage] voice capture failed: ${err?.message}`);
+        return null;
+    }
+}

package/src/features/engage/engageCoachmarkTour.ts

@@ -1,120 +1,120 @@
-import type {
-    InAppCoachmarkPlacement,
-    InAppCoachmarkStep,
-    InAppCta,
-    InAppRenderSpec,
-} from './engageTypes';
-
-const PLACEMENTS = new Set<InAppCoachmarkPlacement>([
-    'auto',
-    'top',
-    'bottom',
-    'left',
-    'right',
-]);
-
-const recordOf = (value: unknown): Record<string, unknown> | null =>
-    value !== null && typeof value === 'object' && !Array.isArray(value)
-        ? value as Record<string, unknown>
-        : null;
-
-const textOf = (value: unknown): string | undefined => {
-    if (typeof value !== 'string') return undefined;
-    const valueTrimmed = value.trim();
-    return valueTrimmed || undefined;
-};
-
-const placementOf = (value: unknown): InAppCoachmarkPlacement | undefined =>
-    typeof value === 'string' && PLACEMENTS.has(value as InAppCoachmarkPlacement)
-        ? value as InAppCoachmarkPlacement
-        : undefined;
-
-const ctaOf = (value: unknown): InAppCta | undefined => {
-    const raw = recordOf(value);
-    const label = textOf(raw?.label);
-    const action = raw?.action;
-    if (!label || (action !== 'dismiss' && action !== 'link' && action !== 'custom')) {
-        return undefined;
-    }
-    const deepLink = textOf(raw?.deepLink);
-    return { label, action, ...(deepLink ? { deepLink } : {}) };
-};
-
-/**
- * Normalize the additive multi-step contract while keeping every legacy
- * single-anchor campaign valid. Invalid authored rows are ignored; if no valid
- * row remains, the legacy top-level fields are used as a one-step tour.
- */
-export function normalizeCoachmarkSteps(spec: InAppRenderSpec): InAppCoachmarkStep[] {
-    const ext = spec.ext ?? {};
-    const rawSteps = Array.isArray(ext.steps) ? ext.steps : [];
-    const steps: InAppCoachmarkStep[] = [];
-
-    rawSteps.forEach((value, index) => {
-        const raw = recordOf(value);
-        const anchorKey = textOf(raw?.anchorKey);
-        if (!raw || !anchorKey) return;
-        const title = textOf(raw.title) ?? (index === 0 ? textOf(spec.title) : undefined);
-        const body = textOf(raw.body) ?? (index === 0 ? textOf(spec.body) : undefined);
-        // A structured stop without explanatory copy is malformed. It is safer
-        // to omit it than to spotlight a control with an empty card.
-        if (!body) return;
-        const placement = placementOf(raw.placement) ??
-            (index === 0 ? placementOf(ext.placement) : undefined) ??
-            'auto';
-        const cta = ctaOf(raw.cta) ?? (index === 0 ? spec.cta : undefined);
-        steps.push({
-            anchorKey,
-            ...(title ? { title } : {}),
-            body,
-            placement,
-            ...(cta ? { cta } : {}),
-        });
-    });
-
-    if (steps.length > 0) return steps;
-
-    const legacy = normalizeLegacyAnchoredStep(spec);
-    return legacy ? [legacy] : [];
-}
-
-/** Legacy anchored payload, intentionally ignoring `ext.steps` (plain tooltips never tour). */
-export function normalizeLegacyAnchoredStep(spec: InAppRenderSpec): InAppCoachmarkStep | null {
-    const ext = spec.ext ?? {};
-    const anchorKey = textOf(ext.anchorKey);
-    if (!anchorKey) return null;
-    return {
-        anchorKey,
-        ...(textOf(spec.title) ? { title: textOf(spec.title) } : {}),
-        body: textOf(spec.body) ?? '',
-        placement: placementOf(ext.placement) ?? 'auto',
-        ...(spec.cta ? { cta: spec.cta } : {}),
-    };
-}
-
-export type AnchoredSurfaceKind = 'spotlight' | 'tooltip';
-
-/** Only the canonical coachmark variant owns a modal scrim/spotlight. */
-export function resolveAnchoredSurfaceKind(variantKey?: string): AnchoredSurfaceKind {
-    return variantKey === 'coachmark_spotlight' ? 'spotlight' : 'tooltip';
-}
-
-export function resolveCoachmarkStepIndex(
-    currentIndex: number,
-    stepCount: number,
-    direction: 'next' | 'back',
-): number {
-    if (stepCount <= 0) return 0;
-    const delta = direction === 'next' ? 1 : -1;
-    return Math.max(0, Math.min(currentIndex + delta, stepCount - 1));
-}
-
-export const coachmarkAnchorError = (anchorKey: string): string =>
-    `anchor_not_found:${anchorKey}`;
-
-export type CoachmarkFinishMode = 'cta' | 'complete';
-
-/** Link/custom actions remain clicks; an ordinary Finish is a completion. */
-export function resolveCoachmarkFinishMode(cta?: InAppCta): CoachmarkFinishMode {
-    return cta && cta.action !== 'dismiss' ? 'cta' : 'complete';
-}
+import type {
+    InAppCoachmarkPlacement,
+    InAppCoachmarkStep,
+    InAppCta,
+    InAppRenderSpec,
+} from './engageTypes';
+
+const PLACEMENTS = new Set<InAppCoachmarkPlacement>([
+    'auto',
+    'top',
+    'bottom',
+    'left',
+    'right',
+]);
+
+const recordOf = (value: unknown): Record<string, unknown> | null =>
+    value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : null;
+
+const textOf = (value: unknown): string | undefined => {
+    if (typeof value !== 'string') return undefined;
+    const valueTrimmed = value.trim();
+    return valueTrimmed || undefined;
+};
+
+const placementOf = (value: unknown): InAppCoachmarkPlacement | undefined =>
+    typeof value === 'string' && PLACEMENTS.has(value as InAppCoachmarkPlacement)
+        ? value as InAppCoachmarkPlacement
+        : undefined;
+
+const ctaOf = (value: unknown): InAppCta | undefined => {
+    const raw = recordOf(value);
+    const label = textOf(raw?.label);
+    const action = raw?.action;
+    if (!label || (action !== 'dismiss' && action !== 'link' && action !== 'custom')) {
+        return undefined;
+    }
+    const deepLink = textOf(raw?.deepLink);
+    return { label, action, ...(deepLink ? { deepLink } : {}) };
+};
+
+/**
+ * Normalize the additive multi-step contract while keeping every legacy
+ * single-anchor campaign valid. Invalid authored rows are ignored; if no valid
+ * row remains, the legacy top-level fields are used as a one-step tour.
+ */
+export function normalizeCoachmarkSteps(spec: InAppRenderSpec): InAppCoachmarkStep[] {
+    const ext = spec.ext ?? {};
+    const rawSteps = Array.isArray(ext.steps) ? ext.steps : [];
+    const steps: InAppCoachmarkStep[] = [];
+
+    rawSteps.forEach((value, index) => {
+        const raw = recordOf(value);
+        const anchorKey = textOf(raw?.anchorKey);
+        if (!raw || !anchorKey) return;
+        const title = textOf(raw.title) ?? (index === 0 ? textOf(spec.title) : undefined);
+        const body = textOf(raw.body) ?? (index === 0 ? textOf(spec.body) : undefined);
+        // A structured stop without explanatory copy is malformed. It is safer
+        // to omit it than to spotlight a control with an empty card.
+        if (!body) return;
+        const placement = placementOf(raw.placement) ??
+            (index === 0 ? placementOf(ext.placement) : undefined) ??
+            'auto';
+        const cta = ctaOf(raw.cta) ?? (index === 0 ? spec.cta : undefined);
+        steps.push({
+            anchorKey,
+            ...(title ? { title } : {}),
+            body,
+            placement,
+            ...(cta ? { cta } : {}),
+        });
+    });
+
+    if (steps.length > 0) return steps;
+
+    const legacy = normalizeLegacyAnchoredStep(spec);
+    return legacy ? [legacy] : [];
+}
+
+/** Legacy anchored payload, intentionally ignoring `ext.steps` (plain tooltips never tour). */
+export function normalizeLegacyAnchoredStep(spec: InAppRenderSpec): InAppCoachmarkStep | null {
+    const ext = spec.ext ?? {};
+    const anchorKey = textOf(ext.anchorKey);
+    if (!anchorKey) return null;
+    return {
+        anchorKey,
+        ...(textOf(spec.title) ? { title: textOf(spec.title) } : {}),
+        body: textOf(spec.body) ?? '',
+        placement: placementOf(ext.placement) ?? 'auto',
+        ...(spec.cta ? { cta: spec.cta } : {}),
+    };
+}
+
+export type AnchoredSurfaceKind = 'spotlight' | 'tooltip';
+
+/** Only the canonical coachmark variant owns a modal scrim/spotlight. */
+export function resolveAnchoredSurfaceKind(variantKey?: string): AnchoredSurfaceKind {
+    return variantKey === 'coachmark_spotlight' ? 'spotlight' : 'tooltip';
+}
+
+export function resolveCoachmarkStepIndex(
+    currentIndex: number,
+    stepCount: number,
+    direction: 'next' | 'back',
+): number {
+    if (stepCount <= 0) return 0;
+    const delta = direction === 'next' ? 1 : -1;
+    return Math.max(0, Math.min(currentIndex + delta, stepCount - 1));
+}
+
+export const coachmarkAnchorError = (anchorKey: string): string =>
+    `anchor_not_found:${anchorKey}`;
+
+export type CoachmarkFinishMode = 'cta' | 'complete';
+
+/** Link/custom actions remain clicks; an ordinary Finish is a completion. */
+export function resolveCoachmarkFinishMode(cta?: InAppCta): CoachmarkFinishMode {
+    return cta && cta.action !== 'dismiss' ? 'cta' : 'complete';
+}