@fixback/expo 0.1.0

package/dist/identity.js

@@ -0,0 +1,46 @@
+/**
+ * The Public Reporter's stable, first-party anonymous id — the mobile
+ * counterpart of `packages/sdk/src/identity.ts`.
+ *
+ * When the host app does not supply its own identity, the SDK establishes a
+ * per-device id and persists it (AsyncStorage on React Native), so repeated
+ * boots from the same device are one Reporter. Persistence is best-effort: if
+ * storage is unavailable or failing, we fall back to an ephemeral id rather
+ * than throw — the SDK must never disturb the host app. The storage key is the
+ * web SDK's, so the shape stays recognisable across clients.
+ */
+export const ANONYMOUS_ID_STORAGE_KEY = "fixback.anonymousId";
+/** A random id: a UUID where the platform offers one, else a compact fallback. */
+export function generateAnonymousId() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function") {
+        try {
+            return c.randomUUID();
+        }
+        catch {
+            // Fall through to the compact fallback.
+        }
+    }
+    return `fb-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Return this device's anonymous id, creating and persisting one on first use.
+ * Any storage failure — absent module, quota, corrupted value — yields an
+ * ephemeral id for this session instead of an error.
+ */
+export async function ensureAnonymousId(storage) {
+    if (!storage)
+        return generateAnonymousId();
+    try {
+        const existing = await storage.getItem(ANONYMOUS_ID_STORAGE_KEY);
+        if (typeof existing === "string" && existing.length > 0)
+            return existing;
+        const id = generateAnonymousId();
+        await storage.setItem(ANONYMOUS_ID_STORAGE_KEY, id);
+        return id;
+    }
+    catch {
+        // Storage blocked or absent — an ephemeral id keeps this boot working.
+        return generateAnonymousId();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fixback/expo — the Fixback capture SDK for Expo / React Native apps.
+ *
+ * Shake the device to report feedback with trace Evidence; uncaught errors
+ * report themselves. Spec 0004; decision record ADR-0021.
+ */
+export { Fixback, FixbackProvider, useFixback, type FixbackHandle, type FixbackProviderProps, } from "./FixbackProvider";
+export { canonicalizeOrigin, createFixbackClient, DEFAULT_API_URL, DEFAULT_SHAKE_SAMPLE_INTERVAL_MS, type ComposerContext, type ComposerDraft, type FixbackAdapters, type FixbackClient, type FixbackOptions, type FixbackStatus, type ShakeOptions, } from "./client";
+export type { BootAnswer, CaptureConfig, IdentityInputs, ProjectGate, ReporterTier, } from "./boot";
+export type { CaptureEnvironment, FeedbackSource, ReportContent, } from "./report";
+export type { Breadcrumb, BreadcrumbCategory, BreadcrumbLevel, BeforeBreadcrumb, } from "./breadcrumbs";
+export type { BeforeSend } from "./scrub";
+export { createShakeDetector, DEFAULT_SHAKE_TUNING, type ShakeDetector, type ShakeSample, type ShakeTuning, } from "./shake";
+export type { RecordedFeedback, ScreenshotFile, SubmitResult, } from "./submit";
+export { EXPO_SDK_VERSION } from "./version";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @fixback/expo — the Fixback capture SDK for Expo / React Native apps.
+ *
+ * Shake the device to report feedback with trace Evidence; uncaught errors
+ * report themselves. Spec 0004; decision record ADR-0021.
+ */
+export { Fixback, FixbackProvider, useFixback, } from "./FixbackProvider";
+export { canonicalizeOrigin, createFixbackClient, DEFAULT_API_URL, DEFAULT_SHAKE_SAMPLE_INTERVAL_MS, } from "./client";
+export { createShakeDetector, DEFAULT_SHAKE_TUNING, } from "./shake";
+export { EXPO_SDK_VERSION } from "./version";

package/dist/report.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The ingest **feedback** content wire-contract, vendored, plus the helpers
+ * that assemble it from what a Reporter composed — kept file-parallel with
+ * `packages/sdk/src/report.ts` (ADR-0021). The mobile slice carries no
+ * `annotation` (element picking and drawing are web-only today, spec 0004 §G);
+ * every content field is optional on the server, so the payload simply omits it.
+ */
+import type { Breadcrumb } from "./breadcrumbs";
+/**
+ * Where a Feedback came from — a human in the composer (`reporter`, the
+ * default) or the SDK's automatic error capture (`auto`). Mirrors the server's
+ * `FEEDBACK_SOURCES`; the server derives trust independently.
+ */
+export type FeedbackSource = "reporter" | "auto";
+/** The capture environment recorded alongside a report. */
+export interface CaptureEnvironment {
+    readonly viewportWidth?: number;
+    readonly viewportHeight?: number;
+    readonly browser?: string;
+    readonly sdkVersion?: string;
+}
+/**
+ * The JSON content of a feedback submission — the object serialised into the
+ * multipart `payload` part next to the `key` and identity evidence. Every
+ * field is optional: none of it feeds the server's trust decision. The
+ * screenshot is a separate binary part, never part of this JSON.
+ */
+export interface ReportContent {
+    readonly comment?: string;
+    /**
+     * The Reporter's self-provided display **name / email** — display only,
+     * never a trust signal; the server derives the tier from identity evidence
+     * alone and ignores these.
+     */
+    readonly reporterName?: string;
+    readonly reporterEmail?: string;
+    /** On mobile: `<origin>/<screen>` when a screen was tracked, else the origin. */
+    readonly url?: string;
+    readonly environment?: CaptureEnvironment;
+    /** The masked breadcrumb trace buffer that rode on this report. */
+    readonly trace?: readonly Breadcrumb[];
+    /**
+     * Provenance. Omitted for a manual report — the transport stamps the
+     * `reporter` default on the wire; set to `auto` by the SDK's error capture.
+     */
+    readonly source?: FeedbackSource;
+    /** For `source: auto` only — the SDK's per-session error fingerprint. */
+    readonly errorSignature?: string;
+    /** For `source: auto` only — the running occurrence count within the session. */
+    readonly occurrences?: number;
+}
+/** What the composer hands to {@link assembleContent} when the Reporter sends. */
+export interface ReportDraft {
+    readonly comment?: string;
+    readonly url?: string;
+    readonly environment?: CaptureEnvironment;
+    readonly trace?: readonly Breadcrumb[];
+    /** The Reporter's self-provided display name / email, if the SDK holds them. */
+    readonly reporterName?: string;
+    readonly reporterEmail?: string;
+}
+/** What the platform adapter reads off the device for the environment. */
+export interface EnvironmentInputs {
+    /** The app window's dimensions in points, from `Dimensions.get("window")`. */
+    readonly windowWidth?: number;
+    readonly windowHeight?: number;
+    /** The platform description, e.g. `ios 17.4` (`Platform.OS` + `Platform.Version`). */
+    readonly os?: string;
+}
+/**
+ * Build the capture environment from what the adapter read off the device. A
+ * dimension is recorded only when it is a positive number (the server rejects
+ * `0` via `int().positive()`); the `browser` field — the server's free-form
+ * client string — carries a `react-native <os>` description.
+ */
+export declare function collectEnvironment(inputs: EnvironmentInputs, sdkVersion: string): CaptureEnvironment;
+/**
+ * The server's hard bounds on the display-only reporter fields
+ * (`feedbackContentBody` in `apps/api/src/ingest/ingest.controller.ts`). An
+ * over-long value fails the whole submission with a 400 there, and unlike the
+ * web SDK — whose onboarding input is the source — these arrive as free-form
+ * init options, so the client clamps rather than lets one oversized display
+ * string swallow every report.
+ */
+export declare const MAX_REPORTER_NAME_LENGTH = 200;
+export declare const MAX_REPORTER_EMAIL_LENGTH = 320;
+/**
+ * Assemble the ingest content from what the Reporter composed. Empty pieces
+ * are dropped rather than sent as blanks: a whitespace-only comment or an
+ * empty environment is simply omitted, so the payload carries only what was
+ * actually provided (mirroring the server's all-optional content).
+ */
+export declare function assembleContent(draft: ReportDraft): ReportContent;

package/dist/report.js

@@ -0,0 +1,67 @@
+/**
+ * The ingest **feedback** content wire-contract, vendored, plus the helpers
+ * that assemble it from what a Reporter composed — kept file-parallel with
+ * `packages/sdk/src/report.ts` (ADR-0021). The mobile slice carries no
+ * `annotation` (element picking and drawing are web-only today, spec 0004 §G);
+ * every content field is optional on the server, so the payload simply omits it.
+ */
+/**
+ * Build the capture environment from what the adapter read off the device. A
+ * dimension is recorded only when it is a positive number (the server rejects
+ * `0` via `int().positive()`); the `browser` field — the server's free-form
+ * client string — carries a `react-native <os>` description.
+ */
+export function collectEnvironment(inputs, sdkVersion) {
+    const env = {};
+    const width = inputs.windowWidth;
+    if (typeof width === "number" && width > 0)
+        env.viewportWidth = Math.round(width);
+    const height = inputs.windowHeight;
+    if (typeof height === "number" && height > 0) {
+        env.viewportHeight = Math.round(height);
+    }
+    const os = typeof inputs.os === "string" ? inputs.os.trim() : "";
+    env.browser = os ? `react-native ${os}` : "react-native";
+    if (sdkVersion.length > 0)
+        env.sdkVersion = sdkVersion;
+    return env;
+}
+/**
+ * The server's hard bounds on the display-only reporter fields
+ * (`feedbackContentBody` in `apps/api/src/ingest/ingest.controller.ts`). An
+ * over-long value fails the whole submission with a 400 there, and unlike the
+ * web SDK — whose onboarding input is the source — these arrive as free-form
+ * init options, so the client clamps rather than lets one oversized display
+ * string swallow every report.
+ */
+export const MAX_REPORTER_NAME_LENGTH = 200;
+export const MAX_REPORTER_EMAIL_LENGTH = 320;
+/**
+ * Assemble the ingest content from what the Reporter composed. Empty pieces
+ * are dropped rather than sent as blanks: a whitespace-only comment or an
+ * empty environment is simply omitted, so the payload carries only what was
+ * actually provided (mirroring the server's all-optional content).
+ */
+export function assembleContent(draft) {
+    const content = {};
+    const comment = draft.comment?.trim();
+    if (comment)
+        content.comment = comment;
+    const reporterName = draft.reporterName?.trim();
+    if (reporterName) {
+        content.reporterName = reporterName.slice(0, MAX_REPORTER_NAME_LENGTH);
+    }
+    const reporterEmail = draft.reporterEmail?.trim();
+    if (reporterEmail) {
+        content.reporterEmail = reporterEmail.slice(0, MAX_REPORTER_EMAIL_LENGTH);
+    }
+    if (draft.url)
+        content.url = draft.url;
+    if (draft.environment && Object.keys(draft.environment).length > 0) {
+        content.environment = draft.environment;
+    }
+    // Only a non-empty trace rides along — an empty buffer is simply omitted.
+    if (draft.trace && draft.trace.length > 0)
+        content.trace = draft.trace;
+    return content;
+}

package/dist/scrub.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The single client-side **scrub choke point** every report passes through
+ * before transport — a verbatim port of `packages/sdk/src/scrub.ts` (spec 0003
+ * §C; ADR-0021 keeps the two clients file-parallel).
+ *
+ * Masking is the SDK's job, done on the device before anything leaves it. The
+ * default scrubbers are **on**: they strip credentials, query strings, and
+ * bearer tokens from URLs, and redact obvious PII (emails, long digit runs,
+ * bearer tokens) from crumb and error text. The result is then handed to an
+ * optional per-project hook that can mutate it further or drop the whole report
+ * by returning `null`. The hook is **synchronous and network-free** by
+ * contract, and both manual (composer) and automatic (error-capture) reports
+ * run through the very same choke point.
+ */
+import type { ReportContent } from "./report";
+/** The per-project client scrub hook. Return `null` to drop the whole report. */
+export type BeforeSend = (draft: ReportContent) => ReportContent | null;
+/** Options for {@link runBeforeSend}. */
+export interface BeforeSendOptions {
+    /** The per-project hook, run **after** the default scrubbers. */
+    readonly hook?: BeforeSend | null;
+    /** Run the built-in default scrubbers first. Defaults to `true`. */
+    readonly scrub?: boolean;
+}
+/**
+ * Redact obvious PII from free text: email addresses, `Bearer <token>` /
+ * `token <value>` pairs, and long digit runs. Conservative by design — it keeps
+ * the shape of the message readable while removing the sensitive spans.
+ */
+export declare function redactPii(text: string): string;
+/**
+ * Strip the sensitive parts of a URL: userinfo credentials, the entire query
+ * string, a token-bearing fragment (one that carries `key=value`), and PII in
+ * the **path segments**. Plain hash routes (`#/checkout`) are kept. Works on
+ * absolute and relative URLs alike, with no dependency and no throw. The host
+ * (authority) is never redacted.
+ */
+export declare function scrubUrl(url: string): string;
+/**
+ * Apply the built-in default scrubbers to a report draft: strip the report URL,
+ * and scrub every crumb's URLs and redact PII from its text. The Reporter's own
+ * `comment` is intentionally left untouched — it is authored on purpose, not
+ * scraped. The screenshot is handled elsewhere (composer preview + removal,
+ * spec 0004 §C); this is the final URL/PII sweep.
+ */
+export declare function applyDefaultScrub(draft: ReportContent): ReportContent;
+/**
+ * Run the report draft through the client scrub choke point: the default
+ * scrubbers first (unless `scrub` is `false`), then the optional per-project
+ * hook. Returns the scrubbed (and possibly hook-mutated) draft, or `null` when
+ * the hook drops the report. A hook that throws is treated as a no-op — the
+ * already-scrubbed draft is kept, so a buggy hook never breaks the report path
+ * nor leaks unscrubbed data.
+ */
+export declare function runBeforeSend(draft: ReportContent, options?: BeforeSendOptions): ReportContent | null;

package/dist/scrub.js

@@ -0,0 +1,184 @@
+/**
+ * The single client-side **scrub choke point** every report passes through
+ * before transport — a verbatim port of `packages/sdk/src/scrub.ts` (spec 0003
+ * §C; ADR-0021 keeps the two clients file-parallel).
+ *
+ * Masking is the SDK's job, done on the device before anything leaves it. The
+ * default scrubbers are **on**: they strip credentials, query strings, and
+ * bearer tokens from URLs, and redact obvious PII (emails, long digit runs,
+ * bearer tokens) from crumb and error text. The result is then handed to an
+ * optional per-project hook that can mutate it further or drop the whole report
+ * by returning `null`. The hook is **synchronous and network-free** by
+ * contract, and both manual (composer) and automatic (error-capture) reports
+ * run through the very same choke point.
+ */
+/** A digit run at least this long is treated as sensitive (phone, card, id). */
+const MIN_DIGIT_RUN = 7;
+const EMAIL_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+const DIGIT_RUN_RE = new RegExp(`\\d{${MIN_DIGIT_RUN},}`, "g");
+const BEARER_RE = /\b(bearer|token)\s+[\w.\-~+/]+=*/gi;
+/** An http(s) URL embedded in free text (e.g. a console log line). */
+const URL_IN_TEXT_RE = /\bhttps?:\/\/[^\s"'<>]+/gi;
+/**
+ * Redact obvious PII from free text: email addresses, `Bearer <token>` /
+ * `token <value>` pairs, and long digit runs. Conservative by design — it keeps
+ * the shape of the message readable while removing the sensitive spans.
+ */
+export function redactPii(text) {
+    if (typeof text !== "string" || text.length === 0)
+        return text;
+    return text
+        .replace(EMAIL_RE, "[redacted-email]")
+        .replace(BEARER_RE, (_match, keyword) => `${keyword} [redacted]`)
+        .replace(DIGIT_RUN_RE, "[redacted-number]");
+}
+/**
+ * Redact PII from the **path** portion of a URL: emails and long digit runs in
+ * path (or fragment-route) segments. Deliberately narrower than
+ * {@link redactPii}: no bearer/token rule and only ever applied to the
+ * post-authority remainder, so a host or port with digits is never touched.
+ */
+function redactPathPii(pathAndBeyond) {
+    return pathAndBeyond
+        .replace(EMAIL_RE, "[redacted-email]")
+        .replace(DIGIT_RUN_RE, "[redacted-number]");
+}
+/**
+ * Strip the sensitive parts of a URL: userinfo credentials, the entire query
+ * string, a token-bearing fragment (one that carries `key=value`), and PII in
+ * the **path segments**. Plain hash routes (`#/checkout`) are kept. Works on
+ * absolute and relative URLs alike, with no dependency and no throw. The host
+ * (authority) is never redacted.
+ */
+export function scrubUrl(url) {
+    if (typeof url !== "string" || url.length === 0)
+        return url;
+    let out = url;
+    // Drop userinfo credentials: scheme://user:pass@host → scheme://host
+    out = out.replace(/(^[a-z][a-z0-9+.-]*:\/\/)[^/@?#]*@/i, "$1");
+    // Drop the query string entirely (everything from '?' up to a '#').
+    out = out.replace(/\?[^#]*/, "");
+    // Drop a token-bearing fragment (it carries '='); keep plain hash routes.
+    out = out.replace(/#.*$/, (fragment) => fragment.includes("=") ? "" : fragment);
+    // Redact PII in the path (and any kept fragment route), never in the authority.
+    const absolute = out.match(/^([a-z][a-z0-9+.-]*:\/\/[^/?#]*)([\s\S]*)$/i);
+    if (absolute)
+        return absolute[1] + redactPathPii(absolute[2] ?? "");
+    const protocolRelative = out.match(/^(\/\/[^/?#]*)([\s\S]*)$/);
+    if (protocolRelative) {
+        return protocolRelative[1] + redactPathPii(protocolRelative[2] ?? "");
+    }
+    // A relative URL is all path — redact the whole thing.
+    return redactPathPii(out);
+}
+function scrubCrumbData(data) {
+    const next = { ...data };
+    if (typeof next.url === "string")
+        next.url = scrubUrl(next.url);
+    if (typeof next.from === "string")
+        next.from = scrubUrl(next.from);
+    if (typeof next.to === "string")
+        next.to = scrubUrl(next.to);
+    return next;
+}
+/** Scrub a crumb's free-text message: strip URL query strings, then redact PII. */
+function scrubMessage(message) {
+    return redactPii(message.replace(URL_IN_TEXT_RE, (url) => scrubUrl(url)));
+}
+/**
+ * Scrub the string leaves of a structured console-arg value — the value a
+ * `json` arg carries. Walks arrays and plain objects, applying the same
+ * URL-strip + PII redaction as a crumb message to every nested string.
+ */
+function scrubArgValue(value) {
+    if (typeof value === "string")
+        return scrubMessage(value);
+    if (Array.isArray(value))
+        return value.map(scrubArgValue);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            out[key] = scrubArgValue(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Scrub one structured console argument: redact PII / strip URL query strings
+ * from a `string` value, from every string leaf of a `json` value, and from an
+ * `error` value's `message` and `stack`. Other tags carry no free text.
+ */
+function scrubConsoleArg(arg) {
+    switch (arg.t) {
+        case "string":
+            return typeof arg.v === "string" ? { t: "string", v: scrubMessage(arg.v) } : arg;
+        case "json":
+            return { t: "json", v: scrubArgValue(arg.v) };
+        case "error": {
+            if (!arg.v || typeof arg.v !== "object")
+                return arg;
+            const v = arg.v;
+            const next = { ...v };
+            if (typeof next.message === "string")
+                next.message = scrubMessage(next.message);
+            if (typeof next.stack === "string")
+                next.stack = scrubMessage(next.stack);
+            return { t: "error", v: next };
+        }
+        default:
+            return arg;
+    }
+}
+function scrubCrumb(crumb) {
+    const next = { ...crumb };
+    if (typeof next.message === "string")
+        next.message = scrubMessage(next.message);
+    if (next.data)
+        next.data = scrubCrumbData(next.data);
+    // A rich network crumb carries its scrubbed URL at the top level — sweep it
+    // again here (idempotent) so the choke point holds wherever the URL rode.
+    if (typeof next.url === "string")
+        next.url = scrubUrl(next.url);
+    // A console crumb's structured args carry the same free text as its preview.
+    if (Array.isArray(next.args))
+        next.args = next.args.map(scrubConsoleArg);
+    return next;
+}
+/**
+ * Apply the built-in default scrubbers to a report draft: strip the report URL,
+ * and scrub every crumb's URLs and redact PII from its text. The Reporter's own
+ * `comment` is intentionally left untouched — it is authored on purpose, not
+ * scraped. The screenshot is handled elsewhere (composer preview + removal,
+ * spec 0004 §C); this is the final URL/PII sweep.
+ */
+export function applyDefaultScrub(draft) {
+    const next = { ...draft };
+    if (typeof next.url === "string")
+        next.url = scrubUrl(next.url);
+    if (next.trace && next.trace.length > 0) {
+        next.trace = next.trace.map(scrubCrumb);
+    }
+    return next;
+}
+/**
+ * Run the report draft through the client scrub choke point: the default
+ * scrubbers first (unless `scrub` is `false`), then the optional per-project
+ * hook. Returns the scrubbed (and possibly hook-mutated) draft, or `null` when
+ * the hook drops the report. A hook that throws is treated as a no-op — the
+ * already-scrubbed draft is kept, so a buggy hook never breaks the report path
+ * nor leaks unscrubbed data.
+ */
+export function runBeforeSend(draft, options = {}) {
+    const current = options.scrub === false ? draft : applyDefaultScrub(draft);
+    const hook = options.hook;
+    if (!hook)
+        return current;
+    try {
+        const result = hook(current);
+        return result ?? null;
+    }
+    catch {
+        return current;
+    }
+}

package/dist/shake.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The pure **shake detector** — the mobile launcher's brain (spec 0004 §B,
+ * ADR-0021). It consumes raw accelerometer samples (in g, gravity included, as
+ * `expo-sensors` reports them) and fires `onShake` when a deliberate shake is
+ * recognised: enough acceleration-magnitude **peaks** over a threshold, close
+ * enough together, debounced so one sustained swing counts once, with a
+ * cooldown so a single shake never double-opens the composer.
+ *
+ * Kept free of any React Native import so the recogniser is unit-tested
+ * deterministically; the sensor wiring lives in `adapters.ts`.
+ */
+/** One accelerometer reading, in g per axis, stamped with an epoch-ms time. */
+export interface ShakeSample {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    /** Epoch milliseconds when the sample was taken. */
+    readonly at: number;
+}
+/** The tunable numbers of the recogniser — spec 0004 §B's defaults. */
+export interface ShakeTuning {
+    /** A sample's magnitude must reach this (in g) to count as a peak. */
+    readonly thresholdG: number;
+    /** How many peaks within {@link windowMs} fire a shake. */
+    readonly minPeaks: number;
+    /** The sliding window peaks must fall inside. */
+    readonly windowMs: number;
+    /** Two peaks closer than this are one swing — debounce. */
+    readonly minGapMs: number;
+    /** After firing, ignore everything for this long. */
+    readonly cooldownMs: number;
+}
+/** The default tuning: a deliberate shake, not a bump or a phone put down hard. */
+export declare const DEFAULT_SHAKE_TUNING: ShakeTuning;
+/** Configuration for {@link createShakeDetector}. */
+export interface ShakeDetectorOptions extends Partial<ShakeTuning> {
+    /** Called once per recognised shake. A throwing callback is swallowed. */
+    readonly onShake: () => void;
+}
+/** A live shake recogniser. */
+export interface ShakeDetector {
+    /** Feed one accelerometer sample. */
+    sample(sample: ShakeSample): void;
+    /** Forget accumulated peaks and any cooldown. */
+    reset(): void;
+}
+/**
+ * Create a shake recogniser. The peak list is pruned to the sliding window on
+ * every sample, so memory stays bounded however long the app runs.
+ */
+export declare function createShakeDetector(options: ShakeDetectorOptions): ShakeDetector;

package/dist/shake.js

@@ -0,0 +1,79 @@
+/**
+ * The pure **shake detector** — the mobile launcher's brain (spec 0004 §B,
+ * ADR-0021). It consumes raw accelerometer samples (in g, gravity included, as
+ * `expo-sensors` reports them) and fires `onShake` when a deliberate shake is
+ * recognised: enough acceleration-magnitude **peaks** over a threshold, close
+ * enough together, debounced so one sustained swing counts once, with a
+ * cooldown so a single shake never double-opens the composer.
+ *
+ * Kept free of any React Native import so the recogniser is unit-tested
+ * deterministically; the sensor wiring lives in `adapters.ts`.
+ */
+/** The default tuning: a deliberate shake, not a bump or a phone put down hard. */
+export const DEFAULT_SHAKE_TUNING = {
+    thresholdG: 2.0,
+    minPeaks: 3,
+    windowMs: 900,
+    minGapMs: 70,
+    cooldownMs: 2000,
+};
+function tuned(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+}
+/**
+ * Create a shake recogniser. The peak list is pruned to the sliding window on
+ * every sample, so memory stays bounded however long the app runs.
+ */
+export function createShakeDetector(options) {
+    const thresholdG = tuned(options.thresholdG, DEFAULT_SHAKE_TUNING.thresholdG);
+    const minPeaks = Math.max(1, Math.floor(tuned(options.minPeaks, DEFAULT_SHAKE_TUNING.minPeaks)));
+    const windowMs = tuned(options.windowMs, DEFAULT_SHAKE_TUNING.windowMs);
+    const minGapMs = tuned(options.minGapMs, DEFAULT_SHAKE_TUNING.minGapMs);
+    const cooldownMs = tuned(options.cooldownMs, DEFAULT_SHAKE_TUNING.cooldownMs);
+    /** Epoch-ms times of the peaks inside the current window. */
+    let peaks = [];
+    let lastPeakAt = Number.NEGATIVE_INFINITY;
+    let lastFiredAt = Number.NEGATIVE_INFINITY;
+    return {
+        sample(sample) {
+            const { x, y, z, at } = sample;
+            if (!Number.isFinite(x) ||
+                !Number.isFinite(y) ||
+                !Number.isFinite(z) ||
+                !Number.isFinite(at)) {
+                return;
+            }
+            // Everything inside the cooldown is ignored — including peak bookkeeping,
+            // so the tail of the shake that fired can't seed the next window.
+            if (at - lastFiredAt < cooldownMs)
+                return;
+            const magnitude = Math.sqrt(x * x + y * y + z * z);
+            if (magnitude < thresholdG)
+                return;
+            // Debounce: a sustained swing above the threshold is one peak, not many.
+            if (at - lastPeakAt < minGapMs)
+                return;
+            lastPeakAt = at;
+            peaks.push(at);
+            const cutoff = at - windowMs;
+            peaks = peaks.filter((t) => t >= cutoff);
+            if (peaks.length >= minPeaks) {
+                peaks = [];
+                lastFiredAt = at;
+                try {
+                    options.onShake();
+                }
+                catch {
+                    // The gesture must never throw into the host app.
+                }
+            }
+        },
+        reset() {
+            peaks = [];
+            lastPeakAt = Number.NEGATIVE_INFINITY;
+            lastFiredAt = Number.NEGATIVE_INFINITY;
+        },
+    };
+}