@scalebun-release/react-native 2.5.0

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

@@ -0,0 +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,
+    },
+};

package/src/features/engage/attachmentCapture.ts

@@ -0,0 +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;
+    }
+}

package/src/features/engage/captureVoiceAttachment.ts

@@ -0,0 +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;
+    }
+}

package/src/features/engage/engageCoachmarkTour.ts

@@ -0,0 +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';
+}

package/src/features/engage/engageGameLogic.ts

@@ -0,0 +1,347 @@
+import type {
+  InAppGameAction,
+  InAppGameRequest,
+  InAppGameResult,
+  InAppGameVariantKey,
+  InAppRenderSpec,
+} from "./engageTypes";
+
+const GAME_ACTIONS: Readonly<Record<InAppGameVariantKey, InAppGameAction>> = {
+  spin_wheel: "play",
+  scratch_card: "play",
+  slot_reward: "play",
+  mystery_box: "play",
+  progress_unlock: "load",
+  streak_reward: "load",
+  daily_check_in: "check_in",
+  quiz_card: "submit_quiz",
+};
+
+const gameRecord = (value: unknown): Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+const gameString = (value: unknown): string =>
+  typeof value === "string" ? value.trim() : "";
+
+export function isInAppGameVariant(value: unknown): value is InAppGameVariantKey {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(GAME_ACTIONS, value);
+}
+
+export function inAppGameActionFor(value: unknown): InAppGameAction | null {
+  return isInAppGameVariant(value) ? GAME_ACTIONS[value] : null;
+}
+
+/** Presentation-declared ids are validation hints, never probability or grant logic. */
+export function inAppGameAllowedOutcomeIds(spec: InAppRenderSpec): string[] {
+  const ext = gameRecord(spec.ext);
+  const sources = [ext.outcomes, ext.rewards, ext.segments];
+  const ids = sources.flatMap((source) =>
+    (Array.isArray(source) ? source : []).map((item) => {
+      const value = gameRecord(item);
+      return gameString(value.id ?? value.value ?? value.code);
+    }),
+  );
+  return [...new Set(ids.filter(Boolean))];
+}
+
+/** Build a correctly discriminated host request from the mounted game. */
+export function buildInAppGameRequest(input: {
+  campaignId: string;
+  gameKey: string;
+  variantKey: InAppGameVariantKey;
+  attemptId: string;
+  attempt: number;
+  payload?: Record<string, unknown>;
+  allowedOutcomeIds?: string[];
+}): InAppGameRequest {
+  const base = {
+    campaignId: input.campaignId,
+    gameKey: input.gameKey,
+    attemptId: input.attemptId,
+    attempt: Math.max(1, Math.floor(input.attempt)),
+    ...(input.payload ? { input: input.payload } : {}),
+    ...(input.allowedOutcomeIds?.length
+      ? { allowedOutcomeIds: input.allowedOutcomeIds }
+      : {}),
+  };
+  switch (input.variantKey) {
+    case "spin_wheel":
+    case "scratch_card":
+    case "slot_reward":
+    case "mystery_box":
+      return { ...base, variantKey: input.variantKey, action: "play" };
+    case "progress_unlock":
+    case "streak_reward":
+      return { ...base, variantKey: input.variantKey, action: "load" };
+    case "daily_check_in":
+      return { ...base, variantKey: input.variantKey, action: "check_in" };
+    case "quiz_card":
+      return { ...base, variantKey: input.variantKey, action: "submit_quiz" };
+  }
+}
+
+/** Reject malformed, mismatched, or presentation-incompatible backend results. */
+export function validateInAppGameResult(
+  request: InAppGameRequest,
+  value: unknown,
+): InAppGameResult {
+  const result = gameRecord(value);
+  if (gameString(result.attemptId) !== request.attemptId) {
+    throw new Error("Game result attemptId does not match the request");
+  }
+  if (result.status === "unavailable") {
+    return {
+      attemptId: request.attemptId,
+      status: "unavailable",
+      ...(typeof result.retryable === "boolean" ? { retryable: result.retryable } : {}),
+      ...(gameString(result.message) ? { message: gameString(result.message) } : {}),
+    };
+  }
+  if (result.status !== "resolved") throw new Error("Game result status is invalid");
+  const rawOutcome = gameRecord(result.outcome);
+  const id = gameString(rawOutcome.id);
+  if (!id) throw new Error("Game result outcome.id is required");
+  const segmentId = gameString(rawOutcome.segmentId);
+  const segmentIndex = rawOutcome.segmentIndex;
+  if (
+    segmentIndex !== undefined &&
+    (typeof segmentIndex !== "number" || !Number.isInteger(segmentIndex) || segmentIndex < 0)
+  ) {
+    throw new Error("Game result segmentIndex is invalid");
+  }
+  const allowed = request.allowedOutcomeIds ?? [];
+  const indexedSegmentId = typeof segmentIndex === "number" ? allowed[segmentIndex] : undefined;
+  if (allowed.length > 0 && !allowed.includes(segmentId || indexedSegmentId || id)) {
+    throw new Error("Game result is not one of the authored outcomes");
+  }
+  const symbols = Array.isArray(rawOutcome.symbols)
+    ? rawOutcome.symbols.map(gameString).filter(Boolean)
+    : undefined;
+  if (rawOutcome.symbols !== undefined && (!symbols || symbols.length === 0 || symbols.length > 3)) {
+    throw new Error("Game result symbols are invalid");
+  }
+  const state = rawOutcome.state;
+  if (state !== undefined && (state === null || typeof state !== "object" || Array.isArray(state))) {
+    throw new Error("Game result state is invalid");
+  }
+  const rawValue = rawOutcome.value;
+  const hasValue =
+    typeof rawValue === "string" ||
+    typeof rawValue === "number" ||
+    typeof rawValue === "boolean";
+  return {
+    attemptId: request.attemptId,
+    status: "resolved",
+    outcome: {
+      id,
+      ...(gameString(rawOutcome.label) ? { label: gameString(rawOutcome.label) } : {}),
+      ...(segmentId ? { segmentId } : {}),
+      ...(typeof segmentIndex === "number" ? { segmentIndex } : {}),
+      ...(symbols ? { symbols } : {}),
+      ...(state ? { state: state as Record<string, unknown> } : {}),
+      ...(hasValue ? { value: rawValue as string | number | boolean } : {}),
+      ...(gameString(rawOutcome.receiptId) ? { receiptId: gameString(rawOutcome.receiptId) } : {}),
+    },
+  };
+}
+
+/** Send Test/live preview only: normalize the dashboard's authored mock result. */
+export function authoredPreviewGameResult(
+  request: InAppGameRequest,
+  spec: InAppRenderSpec,
+): InAppGameResult | null {
+  const ext = gameRecord(spec.ext);
+  const nested = gameRecord(ext.resultState ?? ext.result ?? ext.reward);
+  const commonLabel = gameString(
+    ext.rewardValue ?? ext.prize ?? ext.rewardResult ?? ext.resultReward ??
+      ext.reward ?? nested.label ?? nested.title ?? nested.name ?? ext.resultState,
+  );
+  const commonId = gameString(
+    ext.outcomeId ?? ext.resultId ?? ext.winningId ?? ext.segmentId ??
+      nested.id ?? nested.value,
+  );
+  let outcome: Record<string, unknown> | null = null;
+  switch (request.variantKey) {
+    case "spin_wheel": {
+      const segmentIndex = [ext.winningIndex, ext.resultIndex, ext.selectedIndex, nested.index]
+        .find((value) => typeof value === "number" && Number.isInteger(value) && value >= 0);
+      const segment = typeof segmentIndex === "number" && Array.isArray(ext.segments)
+        ? gameRecord(ext.segments[segmentIndex])
+        : {};
+      const segmentId = gameString(
+        ext.winningId ?? ext.segmentId ?? nested.segmentId ?? nested.id ??
+          segment.id ?? segment.value ?? segment.code,
+      );
+      if (!segmentId && segmentIndex === undefined && !commonLabel) return null;
+      outcome = {
+        id: commonId || segmentId || `preview_segment_${segmentIndex}`,
+        ...(commonLabel ? { label: commonLabel } : {}),
+        ...(segmentId ? { segmentId } : {}),
+        ...(typeof segmentIndex === "number" ? { segmentIndex } : {}),
+      };
+      break;
+    }
+    case "slot_reward": {
+      const symbols = Array.isArray(ext.resultSymbols)
+        ? ext.resultSymbols.map(gameString).filter(Boolean)
+        : [];
+      if (symbols.length === 0) return null;
+      outcome = {
+        id: commonId || `preview_${symbols.join("_")}`,
+        symbols,
+        ...(commonLabel ? { label: commonLabel } : {}),
+      };
+      break;
+    }
+    case "scratch_card":
+    case "mystery_box":
+      if (!commonLabel && !commonId) return null;
+      outcome = { id: commonId || "preview_reward", ...(commonLabel ? { label: commonLabel } : {}) };
+      break;
+    case "progress_unlock":
+    case "streak_reward":
+    case "daily_check_in":
+      outcome = {
+        id: commonId || "preview_state",
+        ...(commonLabel ? { label: commonLabel } : {}),
+        state: { ...ext },
+      };
+      break;
+    case "quiz_card":
+      if (!commonId && !commonLabel) return null;
+      outcome = { id: commonId || "preview_quiz", ...(commonLabel ? { label: commonLabel } : {}) };
+      break;
+  }
+  return validateInAppGameResult(request, {
+    attemptId: request.attemptId,
+    status: "resolved",
+    outcome,
+  });
+}
+
+export function boundedInt(
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const number = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+  return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+export function scratchCellAt(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  columns: number,
+  rows: number,
+): number | null {
+  if (
+    ![x, y, width, height, columns, rows].every(Number.isFinite) ||
+    width <= 0 ||
+    height <= 0 ||
+    columns <= 0 ||
+    rows <= 0 ||
+    x < 0 ||
+    y < 0 ||
+    x >= width ||
+    y >= height
+  ) return null;
+  const column = Math.floor((x / width) * columns);
+  const row = Math.floor((y / height) * rows);
+  return row * columns + column;
+}
+
+export function addScratchedCell(
+  cells: readonly number[],
+  cell: number | null,
+): number[] {
+  if (cell === null || cells.includes(cell)) return [...cells];
+  return [...cells, cell].sort((a, b) => a - b);
+}
+
+export function scratchProgress(cells: readonly number[], total: number): number {
+  if (!Number.isFinite(total) || total <= 0) return 0;
+  const limit = Math.floor(total);
+  const valid = cells.filter(
+    (cell) => Number.isInteger(cell) && cell >= 0 && cell < limit,
+  );
+  return Math.max(0, Math.min(1, new Set(valid).size / limit));
+}
+
+export function clampPage(offset: number, width: number, count: number): number {
+  if (!Number.isFinite(offset) || !Number.isFinite(width) || width <= 0 || count <= 0) return 0;
+  return Math.max(0, Math.min(Math.floor(count) - 1, Math.round(offset / width)));
+}
+
+export function wheelTargetAngle(
+  segmentCount: number,
+  selectedIndex: number,
+  fromAngle: number,
+  minimumTurns = 5,
+): number {
+  const count = boundedInt(segmentCount, 1, 1, 100);
+  const index = boundedInt(selectedIndex, 0, 0, count - 1);
+  const turns = boundedInt(minimumTurns, 1, 1, 20);
+  const slice = 360 / count;
+  const normalizedFrom = ((fromAngle % 360) + 360) % 360;
+  const target = (360 - index * slice) % 360;
+  const alignment = (target - normalizedFrom + 360) % 360;
+  return fromAngle + turns * 360 + alignment;
+}
+
+export function toggleGameSelection(
+  selected: readonly number[],
+  index: number,
+  multiple: boolean,
+): number[] {
+  if (!Number.isInteger(index) || index < 0) return [...selected];
+  if (!multiple) return [index];
+  return selected.includes(index)
+    ? selected.filter((value) => value !== index)
+    : [...selected, index].sort((a, b) => a - b);
+}
+
+export function gradeGameAnswer(
+  selected: readonly number[],
+  correct: readonly number[],
+): boolean {
+  if (selected.length === 0 || correct.length === 0) return false;
+  const actual = [...new Set(selected)].sort((a, b) => a - b);
+  const expected = [...new Set(correct)].sort((a, b) => a - b);
+  return actual.length === expected.length && actual.every((value, index) => value === expected[index]);
+}
+
+export function scoreGameAnswer(
+  currentScore: number,
+  correct: boolean,
+  alreadyLocked: boolean,
+  totalQuestions: number,
+): number {
+  const total = boundedInt(totalQuestions, 1, 1, 100);
+  const current = boundedInt(currentScore, 0, 0, total);
+  return alreadyLocked || !correct ? current : Math.min(total, current + 1);
+}
+
+export interface SlotOutcome {
+  symbols: string[];
+  authored: boolean;
+}
+
+export function resolveSlotOutcome(
+  reels: readonly (readonly string[])[],
+  authoredSymbols: readonly string[],
+): SlotOutcome {
+  const boundedReels = reels.slice(0, 3);
+  const validAuthored =
+    authoredSymbols.length >= boundedReels.length &&
+    boundedReels.every((reel, index) => reel.includes(authoredSymbols[index] ?? ""));
+  return {
+    symbols: boundedReels.map((reel, index) =>
+      validAuthored ? authoredSymbols[index] ?? "★" : reel[0] ?? "★",
+    ),
+    authored: validAuthored,
+  };
+}