@remnic/capture-screen 9.24.0

package/dist/index.d.ts

@@ -0,0 +1,710 @@
+import http from 'node:http';
+
+/** Package-wide constants for @remnic/capture-screen. */
+/**
+ * Reported by GET /v1/health. Kept in sync with package.json by the release
+ * tooling; the health endpoint tolerates drift because the connector never
+ * gates on an exact match (it reads `ok`).
+ */
+declare const CAPTURE_SCREEN_VERSION = "9.14.0";
+/** Loopback default; capture is local-first (charter). */
+declare const DEFAULT_HOST = "127.0.0.1";
+declare const DEFAULT_PORT = 4341;
+/** Spool schema version, persisted in the `meta` table. */
+declare const SPOOL_SCHEMA_VERSION = 1;
+
+/**
+ * Error taxonomy for @remnic/capture-screen.
+ *
+ * Two authored-message classes, mirroring @remnic/capture-audio: configuration
+ * problems and caller-correctable input. Both carry operator-safe messages
+ * (never foreign error text, never captured screen text, never credentials).
+ * The HTTP layer maps CaptureInputError to 400; anything else is a backend
+ * fault (500).
+ */
+/** Config load/validation failure — surfaced loudly, never silently defaulted. */
+declare class CaptureConfigError extends Error {
+    constructor(message: string);
+}
+/** Caller-correctable request/CLI input — maps to HTTP 400. */
+declare class CaptureInputError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Daemon config (`~/.remnic/capture-screen/screen.json`), created by
+ * `remnic-capture-screen init`. Strict and loud: an absent field takes the
+ * documented default, but a present-but-invalid value throws CaptureConfigError
+ * (no silent defaulting). Ports are integers in [1, 65535]; string arrays
+ * (deny-lists, terminal-app globs, redaction patterns) reject non-string
+ * members.
+ *
+ * Deny-lists, terminal-app globs, and redaction patterns here are ADDITIVE to
+ * the built-in defaults (see denylist.ts / redact.ts / capture.ts).
+ */
+interface DaemonConfig {
+    host: string;
+    port: number;
+    spoolRetentionDays: number;
+    simhashThreshold: number;
+    dedupTtlSeconds: number;
+    sessionGapSeconds: number;
+    maxNodes: number;
+    maxDwellSeconds: number;
+    /** Live capture loop: poll interval (ms) for foreground-change detection. */
+    pollIntervalMs: number;
+    /** Live capture loop: settle window (ms) after a foreground change. */
+    settleMs: number;
+    /** Live capture loop: idle re-sample cadence (seconds). */
+    idleFallbackSeconds: number;
+    /** Additive deny-list globs (checked in addition to the built-in defaults). */
+    denyApps: string[];
+    denyTitles: string[];
+    denyUrls: string[];
+    /** Additive terminal-class app globs (route to OCR). */
+    terminalApps: string[];
+    /** Additive user redaction regex source strings. */
+    redactionPatterns: string[];
+}
+declare function defaultDaemonConfig(): DaemonConfig;
+declare function parseDaemonConfig(raw: unknown): DaemonConfig;
+declare function loadDaemonConfig(configPath: string): DaemonConfig;
+declare function serializeDaemonConfig(cfg: DaemonConfig): string;
+
+/** Filesystem layout for the capture working directory. */
+interface CapturePaths {
+    baseDir: string;
+    configPath: string;
+    spoolPath: string;
+    tokenPath: string;
+    pidPath: string;
+    logPath: string;
+}
+/** Expand a leading `~` / `~/` to the home directory; other paths pass through. */
+declare function expandTilde(p: string): string;
+/**
+ * Root of the capture working directory. `REMNIC_CAPTURE_SCREEN_DIR` overrides
+ * the default `~/.remnic/capture-screen` (tests and multi-instance setups point
+ * it at a scratch dir). A leading `~` expands to the home directory.
+ */
+declare function captureBaseDir(env?: NodeJS.ProcessEnv): string;
+declare function capturePaths(baseDir?: string): CapturePaths;
+
+/**
+ * Bearer-token lifecycle. The daemon auto-generates a 256-bit token on first
+ * use and stores it 0600; a pre-existing file is re-chmod'd 0600 defensively
+ * because a world-readable token is a credential leak. The token is REQUIRED on
+ * every request (even on loopback) so another local user cannot read captured
+ * screen text off 127.0.0.1.
+ */
+declare function generateToken(): string;
+declare function loadOrCreateToken(tokenPath: string): string;
+/** Constant-time compare; unequal lengths short-circuit to false. */
+declare function tokensMatch(expected: string, presented: string): boolean;
+/** Parse `Authorization: Bearer <token>`; returns null when absent/malformed. */
+declare function bearerFromHeader(header: string | string[] | undefined): string | null;
+
+/**
+ * Request-input validation for the HTTP surface. Every failure raises
+ * CaptureInputError, which the daemon maps to HTTP 400 — invalid date,
+ * timezone, limit, or cursor is rejected loudly, never silently defaulted. The
+ * keyset cursor is an opaque base64url token over the (capturedAtUtc, id) tuple
+ * the snapshots query orders by, so pagination stays stable across snapshots
+ * that share a capture instant.
+ */
+/** Validate a YYYY-MM-DD calendar date (rejects e.g. 2026-02-30). */
+declare function parseSnapshotDate(value: string | null | undefined): string;
+/** Validate an IANA timezone by attempting to build a formatter for it. */
+declare function assertValidTimezone(value: string | null | undefined): string;
+/** Absent limit → default; present-but-invalid → 400. */
+declare function parseLimit(value: string | null | undefined): number;
+interface Cursor {
+    capturedAtUtc: string;
+    id: number;
+}
+declare function encodeCursor(capturedAtUtc: string, id: number): string;
+/** Absent cursor → null (first page); malformed cursor → 400. */
+declare function decodeCursor(value: string | null | undefined): Cursor | null;
+
+/**
+ * DST-aware local-day window. Inlined from @remnic/core's activity digest
+ * (capture-screen is à-la-carte and depends on nothing at runtime). Returns the
+ * half-open [startUtc, endUtc) UTC instants bounding a local calendar day in an
+ * IANA timezone, correct across spring-forward (skipped midnight) and fall-back
+ * (repeated midnight) transitions.
+ */
+/** Half-open [startUtc, endUtc) UTC ISO bounds of a local day. */
+declare function activityDayWindow(date: string, timezone: string): {
+    startUtc: string;
+    endUtc: string;
+};
+
+/**
+ * 64-bit word-shingle SimHash for near-duplicate screen-text detection.
+ * Text is lower-cased and tokenized to Unicode letter/number runs (so CJK,
+ * Cyrillic, and other non-ASCII scripts tokenize instead of collapsing to an
+ * empty set), then shingled into overlapping 2-word grams. Each gram is hashed
+ * with 64-bit FNV-1a; the signed
+ * per-bit vote across all grams yields a 64-bit fingerprint whose Hamming
+ * distance tracks textual similarity: identical text → distance 0, a small edit
+ * → a small distance, unrelated text → a large distance. Everything is BigInt
+ * so the full 64 bits are exact.
+ */
+/** 64-bit SimHash fingerprint of `text` (0n for empty/whitespace-only text). */
+declare function simhash(text: string): bigint;
+/** Hamming distance between two 64-bit fingerprints (0..64). */
+declare function hammingDistance(a: bigint, b: bigint): number;
+/** Fixed-width 16-char hex rendering (wire/simhash column form). */
+declare function simhashToHex(h: bigint): string;
+declare function simhashFromHex(hex: string): bigint;
+
+/**
+ * Per-window near-duplicate suppression. Keyed by (app, windowTitle): for each
+ * window we remember the last STORED snapshot's SimHash and capture instant. A
+ * new snapshot of the same window is stored only when it is meaningfully
+ * different (Hamming distance > threshold) OR enough time has elapsed since the
+ * last store (ttlSeconds), so a long unchanging window is refreshed periodically
+ * while a stream of near-identical scroll states collapses to a few rows.
+ * Distinct windows never dedup against each other (independent cache entries).
+ *
+ * The clock is the snapshot's own capturedAt (passed in as ms), never a
+ * wall-clock read — so replay/fixtures are deterministic.
+ */
+declare class DedupCache {
+    #private;
+    constructor(threshold: number, ttlSeconds: number);
+    /** Seed the last-stored fingerprint for a window (used to prime from the spool). */
+    seed(app: string, windowTitle: string, hash: bigint, atMs: number): void;
+    /**
+     * Decide whether a snapshot should be stored, updating the cache when it is.
+     * First snapshot of a window always stores. A negative elapsed (out-of-order
+     * capture) stores defensively rather than dropping data.
+     */
+    shouldStore(app: string, windowTitle: string, hash: bigint, atMs: number): boolean;
+}
+
+/**
+ * Capture-time deny-lists, checked FIRST — before any text extraction, hashing,
+ * or spool write. A match records NOTHING (not even metadata): the snapshot is
+ * dropped whole. Three independent lists, each glob/substring matched
+ * case-insensitively: application name, window title, and browser URL. Built-in
+ * defaults cover common secret managers and private-browsing windows; the
+ * user's config entries are additive.
+ */
+/** Secret managers whose windows must never be captured. */
+declare const DEFAULT_DENY_APPS: readonly string[];
+/** Private/incognito window-title heuristics (browsers signal these in the title). */
+declare const DEFAULT_DENY_TITLES: readonly string[];
+/** No default URL denials — URL patterns are user-supplied (site-specific). */
+declare const DEFAULT_DENY_URLS: readonly string[];
+interface DenyLists {
+    apps: readonly string[];
+    titles: readonly string[];
+    urls: readonly string[];
+}
+interface DenyCandidate {
+    app: string;
+    windowTitle: string;
+    browserUrl?: string | null;
+}
+/** Compile a `*`/`?` glob to an anchored, case-insensitive RegExp. */
+declare function globToRegExp(glob: string): RegExp;
+/** True when `value` matches any glob in `patterns` (case-insensitive). */
+declare function matchesAnyGlob(patterns: readonly string[], value: string): boolean;
+/**
+ * The first deny rule that fires for this candidate, or null. Built-in defaults
+ * are always checked in addition to the user lists. The returned string names
+ * the rule (`app:1Password*`, `title:*incognito*`, `url:...`) for the
+ * `test-snapshot` diagnostic.
+ */
+declare function matchDenyRule(candidate: DenyCandidate, lists: DenyLists): string | null;
+
+/**
+ * Daemon-side redaction, applied to snapshot text BEFORE it is hashed or
+ * written to the spool. Built-in patterns catch US SSNs and payment-card
+ * numbers (13–19 digits, optionally space/dash grouped, Luhn-valid); the user's
+ * `redactionPatterns` (regex source strings) are applied in addition. Every
+ * match is replaced with a fixed placeholder so the redacted text is stable
+ * (identical inputs dedup identically).
+ */
+declare const REDACTION_PLACEHOLDER = "[REDACTED]";
+/** Compile user regex source strings once; an invalid pattern fails loudly. */
+declare function compileRedactionPatterns(sources: readonly string[]): RegExp[];
+/** Apply built-in (SSN, card) then user redactions to `text`. */
+declare function redactText(text: string, userPatterns?: readonly RegExp[]): string;
+
+/**
+ * Accessibility-tree text extraction. Walks a macOS AX-tree JSON snapshot and
+ * concatenates the visible text, with three safety filters baked in:
+ *
+ *   - AXSecureTextField nodes are skipped entirely (never read a password box),
+ *     including their subtree.
+ *   - Off-screen nodes (`offScreen: true`) are skipped with their subtree — text
+ *     the user cannot see is not "on screen".
+ *   - Traversal is bounded to `maxNodes` visited nodes, so a pathological tree
+ *     cannot exhaust memory/CPU; the result is flagged `truncated` when the cap
+ *     is hit.
+ *
+ * The shape is intentionally permissive: real AX dumps carry many roles and the
+ * text can live on any of value/title/description/label. Unknown fields are
+ * ignored.
+ */
+declare const SECURE_ROLE = "AXSecureTextField";
+interface AxNode {
+    role?: string;
+    value?: string;
+    title?: string;
+    description?: string;
+    label?: string;
+    offScreen?: boolean;
+    children?: AxNode[];
+}
+interface AxExtractResult {
+    text: string;
+    /** Nodes actually visited (bounded by maxNodes). */
+    nodes: number;
+    /** True when the maxNodes cap stopped traversal before the tree was exhausted. */
+    truncated: boolean;
+}
+/**
+ * Extract visible, non-secure text from an AX tree. Iterative DFS with an
+ * explicit stack so a deep tree cannot overflow the call stack, and a visited
+ * counter that enforces the node cap.
+ */
+declare function extractAxText(root: AxNode, maxNodes: number): AxExtractResult;
+
+/**
+ * SQLite spool — the daemon's local buffer of captured screen snapshots.
+ *
+ * Uses the built-in `node:sqlite` driver (no native dependency), keeping
+ * @remnic/capture-screen à-la-carte: installing it pulls zero extra runtime
+ * packages. WAL mode + foreign keys are enabled per connection.
+ *
+ * Schema (names/semantics fixed by issue #1899):
+ *   snapshots(id, captured_at_utc, app_name, window_title, browser_url NULL,
+ *             text, text_source (ax or ocr), content_hash UNIQUE, simhash,
+ *             superseded_by NULL -> snapshots(id))
+ *   meta(key, value)
+ *
+ * `content_hash` is UNIQUE and inserts are INSERT OR IGNORE, so re-ingesting an
+ * identical snapshot is a content no-op (kill-9 / replay idempotency).
+ * Supersession links the previous non-superseded snapshot of the same
+ * (app, window) session to its replacement, so a consumer can skip stale states.
+ * The read API pages by a stable (captured_at_utc, id) keyset over a half-open
+ * local-day window.
+ */
+type TextSource = "ax" | "ocr";
+interface SnapshotInput {
+    capturedAtUtc: string;
+    app: string;
+    windowTitle: string;
+    browserUrl?: string | null;
+    text: string;
+    textSource: TextSource;
+    contentHash: string;
+    simhash: string;
+}
+interface InsertResult {
+    id: number;
+    inserted: boolean;
+    /** Id of the prior snapshot this insert superseded, or null. */
+    supersededId: number | null;
+}
+interface DaemonSnapshot {
+    id: number;
+    capturedAtUtc: string;
+    app: string;
+    windowTitle: string;
+    browserUrl: string | null;
+    text: string;
+    textSource: TextSource;
+    contentHash: string;
+    simhash: string;
+    supersededBy: number | null;
+}
+interface SnapshotPage {
+    snapshots: DaemonSnapshot[];
+    nextCursor: string | null;
+}
+interface QuerySnapshotsOptions {
+    date: string;
+    timezone: string;
+    cursor?: string | null;
+    limit: number;
+}
+interface WindowFingerprint {
+    app: string;
+    windowTitle: string;
+    simhash: string;
+    capturedAtUtc: string;
+}
+declare class Spool {
+    #private;
+    constructor(location: string);
+    close(): void;
+    meta(key: string): string | null;
+    setMeta(key: string, value: string): void;
+    /**
+     * Insert a snapshot. Idempotent by content_hash (INSERT OR IGNORE): a repeat
+     * returns the existing row's id with `inserted:false` and performs no
+     * supersession. On a genuinely new row, the previous non-superseded snapshot
+     * of the same (app, window) captured within `sessionGapSeconds` is marked
+     * superseded_by this row.
+     */
+    insertSnapshot(input: SnapshotInput, sessionGapSeconds: number): InsertResult;
+    getSnapshot(id: number): DaemonSnapshot | null;
+    countSnapshots(): number;
+    /**
+     * Snapshots whose capture instant falls in the half-open [start, end) UTC
+     * window of the requested local day, paged by the stable (captured_at_utc, id)
+     * keyset. The id tiebreak keeps pagination correct across snapshots that
+     * share a capture instant.
+     */
+    querySnapshots(opts: QuerySnapshotsOptions): SnapshotPage;
+    /** All snapshots in a local day's window, ordered — the basis for /v1/stats. */
+    daySnapshots(date: string, timezone: string): DaemonSnapshot[];
+    /** Latest non-superseded fingerprint per (app, window) — primes the dedup cache. */
+    latestFingerprints(): WindowFingerprint[];
+    /** Retention janitor: drop snapshots older than `days` (cutoff from `nowMs`). Returns rows removed. */
+    pruneOlderThan(days: number, nowMs?: number): number;
+}
+
+/**
+ * Capture-time processing pipeline (pure, hardware-free). A raw candidate —
+ * frontmost app/window plus either an AX tree or pre-extracted text — is turned
+ * into a decision: dropped by a deny rule, skipped (OCR unavailable / deduped),
+ * or a fully-formed spool snapshot. The steps, in order:
+ *
+ *   1. Deny-lists FIRST — a match records NOTHING (not even metadata).
+ *   2. Text: pre-extracted text is used as-is; otherwise the AX tree is walked
+ *      (secure fields + off-screen nodes excluded, bounded to maxNodes). A
+ *      terminal-class window, or an AX tree with no visible text, routes to the
+ *      OCR seam; when OCR is unavailable the snapshot is skipped (reflected in
+ *      health) rather than crashing.
+ *   3. Redaction — SSN/card + user patterns, before hashing or storage.
+ *   4. Dedup — per-window SimHash gate (threshold / TTL).
+ *   5. Content hash — length-prefixed SHA-256 so control chars can't collide.
+ *
+ * The OCR step is a seam (an injected callback), so the daemon wires the native
+ * helper while tests inject a fake without any macOS binary.
+ */
+
+/** Terminal-class apps whose windows expose no useful AX text (route to OCR). */
+declare const DEFAULT_TERMINAL_APPS: readonly string[];
+/**
+ * True when `app` is a terminal-class window (routes to OCR — terminals expose
+ * no useful AX text). `includeDefaults` prepends DEFAULT_TERMINAL_APPS; pass
+ * false when `terminalApps` is already the merged list.
+ */
+declare function isTerminalApp(app: string, terminalApps: readonly string[], includeDefaults?: boolean): boolean;
+/** A raw capture candidate before processing. Provide `text` OR `ax`. */
+interface CaptureCandidate {
+    capturedAtUtc: string;
+    app: string;
+    windowTitle: string;
+    browserUrl?: string | null;
+    /** Pre-extracted text (skips AX walking); source defaults to "ax". */
+    text?: string;
+    textSource?: TextSource;
+    /** Accessibility tree to extract from when `text` is absent. */
+    ax?: AxNode;
+}
+type CaptureDecision = {
+    action: "denied";
+    rule: string;
+} | {
+    action: "skipped";
+    reason: "ocr-unavailable" | "dedup";
+} | {
+    action: "store";
+    snapshot: SnapshotInput;
+};
+/** OCR seam: returns extracted text for a candidate, or null when unavailable. */
+type OcrFn = (candidate: CaptureCandidate) => string | null;
+interface ContentHashFields {
+    capturedAtUtc: string;
+    app: string;
+    windowTitle: string;
+    browserUrl: string | null;
+    text: string;
+    textSource: string;
+}
+/**
+ * SHA-256 over length-prefixed fields so control characters (incl. NUL) in the
+ * captured text cannot make two distinct snapshots collide — a collision would
+ * silently drop a valid capture via the UNIQUE content_hash + INSERT OR IGNORE.
+ */
+declare function contentHash(fields: ContentHashFields): string;
+declare class CaptureProcessor {
+    #private;
+    constructor(config: DaemonConfig, ocr?: OcrFn);
+    /** Seed the dedup cache from prior spool state so restarts don't re-store. */
+    seed(app: string, windowTitle: string, simhashHex: string, capturedAtUtc: string): void;
+    process(candidate: CaptureCandidate): CaptureDecision;
+}
+interface AppStat {
+    app: string;
+    seconds: number;
+    snapshotCount: number;
+}
+interface DayStats {
+    date: string;
+    timezone: string;
+    snapshotCount: number;
+    totalSeconds: number;
+    apps: AppStat[];
+}
+/**
+ * Per-app time attribution for a day. Each snapshot is credited the gap to the
+ * next snapshot (capped at maxDwellSeconds); the final snapshot contributes no
+ * dwell (no following instant to bound it). Apps sort by seconds desc, then name.
+ */
+declare function computeStats(snapshots: DaemonSnapshot[], date: string, timezone: string, maxDwellSeconds: number): DayStats;
+
+/**
+ * Native-helper seam. The actual screen reader is a platform Swift binary
+ * shipped separately as `@remnic/capture-native-<platform>-<arch>`, exporting a
+ * `helperBinaryPath`. This module resolves that binary, spawns it, and parses
+ * its JSON — with two hard rules:
+ *
+ *   - A MISSING helper package NEVER surfaces as a raw MODULE_NOT_FOUND: it
+ *     resolves to `{ binaryPath: null, hint }` with an actionable install hint,
+ *     and the daemon reports axAvailable/ocrAvailable = false (degraded but
+ *     honest).
+ *   - Every helper invocation is bounded and its output validated: a nonzero
+ *     exit, empty output, or invalid/partial JSON throws a sanitized
+ *     CaptureInputError, never a crash and never foreign text.
+ *
+ * `REMNIC_CAPTURE_HELPER_BIN` overrides resolution with an explicit binary path
+ * (manual installs and the hardware-free test seam, which points it at a fake
+ * script emitting canned JSON).
+ */
+
+interface HelperResolution {
+    /** Absolute path to the helper binary, or null when unavailable. */
+    binaryPath: string | null;
+    /** Operator-facing install hint when unavailable, else null. */
+    hint: string | null;
+}
+/** The npm package that would provide the helper for this platform/arch. */
+declare function helperPackageName(platform?: string, arch?: string): string;
+/**
+ * Resolve the helper binary path. Order: explicit env override, then the
+ * computed platform package (dynamic import), then unavailable-with-hint. A
+ * missing or broken package degrades gracefully — it never throws.
+ */
+declare function resolveHelperBinaryPath(env?: NodeJS.ProcessEnv): Promise<HelperResolution>;
+/** Run a helper subcommand and return its parsed JSON, or throw a sanitized error. */
+declare function runHelperCommand(binaryPath: string, args: string[], timeoutMs?: number): Promise<unknown>;
+interface AxSnapshotOptions {
+    frontmost?: boolean;
+    pid?: number;
+    maxNodes?: number;
+}
+/**
+ * The helper's `ax-snapshot` payload: the frontmost window's context (app,
+ * title, optional browser URL) plus its accessibility tree. The tree is
+ * permissive (see AxNode); window context lets the daemon build a capture
+ * candidate without a separate frontmost-window query.
+ */
+interface AxSnapshot {
+    app: string;
+    windowTitle: string;
+    browserUrl?: string | null;
+    tree: AxNode;
+}
+interface OcrWindowOptions {
+    frontmost?: boolean;
+    windowId?: string;
+}
+/** Thin wrapper over a resolved helper binary. */
+declare class NativeHelper {
+    readonly binaryPath: string;
+    constructor(binaryPath: string);
+    /** `<helper> ax-snapshot [--frontmost|--pid N] [--max-nodes N]` -> window + AX tree JSON. */
+    axSnapshot(opts?: AxSnapshotOptions): Promise<AxSnapshot>;
+    /** `<helper> ocr-window [--frontmost|--window ID]` -> `{ text }` JSON. */
+    ocrWindow(opts?: OcrWindowOptions): Promise<string>;
+}
+
+/**
+ * Live capture cycle: one snapshot fetched through the native helper and run
+ * through the processing pipeline. Shared by `test-snapshot` (which prints the
+ * decision without storing) and available to a future capture scheduler.
+ *
+ * The routing (AX vs OCR) happens here because the native OCR call is async
+ * while the processor's OCR seam is sync: a terminal-class or AX-empty window
+ * has its OCR text fetched eagerly, then handed to the processor as
+ * pre-extracted text. When OCR fails, the candidate is left text-less so the
+ * processor skips it (ocr-unavailable) rather than storing empty AX text.
+ */
+
+declare function captureViaHelper(helper: NativeHelper, processor: CaptureProcessor, config: DaemonConfig, capturedAtUtc: string): Promise<CaptureDecision>;
+
+/**
+ * `--replay <dir>` ingestion. Feeds synthetic candidate snapshots through the
+ * FULL capture pipeline (deny-lists, AX/secure-field extraction, OCR routing,
+ * redaction, dedup, supersession) into the spool — the CI-friendly, hardware-
+ * free path that exercises every capture-time rule without a native helper.
+ *
+ * Each `*.json` fixture is either a single candidate or an array of them:
+ *
+ *   {
+ *     "capturedAtUtc": "2026-07-20T15:00:00.000Z",
+ *     "app": "Safari",
+ *     "windowTitle": "Example",
+ *     "browserUrl": "https://example.com",      // optional
+ *     "text": "already extracted text",          // optional; OR provide "ax"
+ *     "textSource": "ax",                        // optional; "ax" | "ocr"
+ *     "ax": { "role": "AXWindow", "children": [ ... ] }  // optional AX tree
+ *   }
+ *
+ * Candidates are processed in ascending capturedAt order (ties broken by file
+ * order) so dedup/TTL behave deterministically regardless of how fixtures are
+ * split across files. Ingestion is idempotent by content hash.
+ */
+
+interface ReplayResult {
+    files: number;
+    candidates: number;
+    stored: number;
+    denied: number;
+    deduped: number;
+    ocrSkipped: number;
+    superseded: number;
+    /** True when a cooperative cancel (AbortSignal) stopped ingestion early. */
+    aborted: boolean;
+}
+/** Commit size between event-loop yields in the responsive ingester. */
+declare const REPLAY_COMMIT_BATCH = 25;
+/** Synchronous ingest: validate the whole directory, then process it all. */
+declare function ingestReplayDir(spool: Spool, dir: string, config: DaemonConfig, ocr?: OcrFn): ReplayResult;
+/**
+ * Responsive ingest: validate up front (atomic), then process in bounded
+ * batches with an event-loop yield between them so a co-hosted HTTP server
+ * stays responsive during a large replay.
+ */
+declare function ingestReplayDirResponsive(spool: Spool, dir: string, config: DaemonConfig, options?: {
+    signal?: AbortSignal;
+    ocr?: OcrFn;
+}): Promise<ReplayResult>;
+
+/**
+ * Loopback-only HTTP daemon. Serves the spool over three read-only routes:
+ *
+ *   GET /v1/health     → liveness + capture status + AX/OCR availability
+ *   GET /v1/snapshots  → snapshots for a local day (keyset paged; wire shape
+ *                        consumed by @remnic/core's ActivityHttpSourceClient)
+ *   GET /v1/stats      → per-app time attribution for a local day
+ *
+ * Security: capture-screen serves PLAIN HTTP and has no TLS contract, so it
+ * refuses to bind a non-loopback host — captured screen text must never cross
+ * the network in cleartext. Every request MUST carry `Authorization: Bearer
+ * <token>` matching the daemon token, even on loopback, so another local user
+ * cannot read snapshots off 127.0.0.1. Input errors are 400; anything
+ * unexpected is 500 with no foreign text.
+ */
+
+interface DaemonDeps {
+    spool: Spool;
+    config: DaemonConfig;
+    token: string;
+    /** Live capture status for /v1/health; false until the capture layer runs. */
+    capturing?: boolean;
+    /** Native-helper capabilities (false when the helper is unavailable). */
+    axAvailable?: boolean;
+    ocrAvailable?: boolean;
+    /** Operator-facing hint surfaced on /v1/health when the helper is missing. */
+    helperHint?: string | null;
+}
+interface DaemonHandle {
+    server: http.Server;
+    host: string;
+    port: number;
+    url: string;
+    close(): Promise<void>;
+}
+declare function createRequestHandler(deps: DaemonDeps): http.RequestListener;
+declare function startDaemon(deps: DaemonDeps): Promise<DaemonHandle>;
+
+/**
+ * Daemon process control: an atomic, identity-bearing pid file plus liveness
+ * probing.
+ *
+ * The pid file is JSON `{ pid, instanceId, startedAtIso, host, port }` written
+ * via a temp-file + rename so a reader never sees a partial write, and reads
+ * are tolerant of a concurrent delete. `instanceId` (the spool instance id)
+ * lets `stop`/`status` confirm — over the authenticated health endpoint — that
+ * the recorded pid really is our daemon before signalling it, which guards
+ * against PID reuse. Removal is owner-checked so a late shutdown can't delete a
+ * newer daemon's control file.
+ */
+interface PidRecord {
+    pid: number;
+    /** Daemon instance id (spool instance_id) for cross-process identity; null when unknown. */
+    instanceId: string | null;
+    /** ISO timestamp the record was written. */
+    startedAtIso: string;
+    /** Effective bound host, when known (so status/stop reach the daemon the CLI actually started). */
+    host: string | null;
+    /** Effective bound port, when known. */
+    port: number | null;
+}
+interface PidWriteOptions {
+    instanceId?: string | null;
+    startedAtIso?: string;
+    host?: string | null;
+    port?: number | null;
+}
+/** Atomically write the pid record (temp file + rename) — no partial reads. */
+declare function writePidFile(pidPath: string, pid: number, options?: PidWriteOptions): void;
+/** Read the pid record; a missing file or a partial/concurrent write returns null. */
+declare function readPidRecord(pidPath: string): PidRecord | null;
+/** Convenience accessor: the recorded pid, or null. */
+declare function readPidFile(pidPath: string): number | null;
+/** Liveness via signal 0. ESRCH → gone; EPERM → alive but owned by another user. */
+declare function isProcessAlive(pid: number): boolean;
+/** Remove the pid file unconditionally (stale reclaim). */
+declare function removePidFile(pidPath: string): void;
+/**
+ * Remove the pid file only when it still records `pid`. Prevents a late
+ * shutdown or `stop` from deleting a NEWER daemon's control file after a
+ * restart or PID reuse.
+ */
+declare function removePidFileIfOwner(pidPath: string, pid: number): void;
+
+/**
+ * `remnic-capture-screen` CLI. Subcommands:
+ *   init | start | stop | status | install-service | logs | test-snapshot
+ *
+ * `start --replay <dir>` feeds synthetic fixtures through the full capture
+ * pipeline + HTTP API (the CI-friendly, hardware-free path). Live capture needs
+ * the native helper (@remnic/capture-native-*); where it is absent the daemon
+ * still serves the spool and reports axAvailable/ocrAvailable = false.
+ *
+ * The bearer token comes from the environment (REMNIC_CAPTURE_TOKEN), never
+ * argv: a long-lived daemon's argv is world-readable via `ps`/`/proc`, so a
+ * token on the command line would let any local account read captured screen
+ * text. `--auth-token` is rejected. When the env var is unset, the token file
+ * created by `init` is used instead.
+ */
+
+interface CliIo {
+    argv: string[];
+    env?: NodeJS.ProcessEnv;
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+}
+/**
+ * Run replay ingestion as a supervised task AFTER the daemon is ready. Never
+ * throws: success/failure is surfaced via the spool's `replay_status` meta
+ * (also on /v1/health) and the daemon log, so a slow/failed replay never kills
+ * the daemon or retracts its readiness.
+ */
+declare function superviseReplay(spool: Spool, replayDir: string, config: DaemonConfig, io: {
+    stdout: (l: string) => void;
+    stderr: (l: string) => void;
+}, signal?: AbortSignal): Promise<void>;
+declare function runCapture(io: CliIo): Promise<number>;
+
+export { type AppStat, type AxExtractResult, type AxNode, type AxSnapshot, type AxSnapshotOptions, CAPTURE_SCREEN_VERSION, type CaptureCandidate, CaptureConfigError, type CaptureDecision, CaptureInputError, type CapturePaths, CaptureProcessor, type CliIo, type Cursor, DEFAULT_DENY_APPS, DEFAULT_DENY_TITLES, DEFAULT_DENY_URLS, DEFAULT_HOST, DEFAULT_PORT, DEFAULT_TERMINAL_APPS, type DaemonConfig, type DaemonDeps, type DaemonHandle, type DaemonSnapshot, type DayStats, DedupCache, type DenyCandidate, type DenyLists, type HelperResolution, type InsertResult, NativeHelper, type OcrFn, type OcrWindowOptions, type PidRecord, type QuerySnapshotsOptions, REDACTION_PLACEHOLDER, REPLAY_COMMIT_BATCH, type ReplayResult, SECURE_ROLE, SPOOL_SCHEMA_VERSION, type SnapshotInput, type SnapshotPage, Spool, type TextSource, type WindowFingerprint, activityDayWindow, assertValidTimezone, bearerFromHeader, captureBaseDir, capturePaths, captureViaHelper, compileRedactionPatterns, computeStats, contentHash, createRequestHandler, decodeCursor, defaultDaemonConfig, encodeCursor, expandTilde, extractAxText, generateToken, globToRegExp, hammingDistance, helperPackageName, ingestReplayDir, ingestReplayDirResponsive, isProcessAlive, isTerminalApp, loadDaemonConfig, loadOrCreateToken, matchDenyRule, matchesAnyGlob, parseDaemonConfig, parseLimit, parseSnapshotDate, readPidFile, readPidRecord, redactText, removePidFile, removePidFileIfOwner, resolveHelperBinaryPath, runCapture, runHelperCommand, serializeDaemonConfig, simhash, simhashFromHex, simhashToHex, startDaemon, superviseReplay, tokensMatch, writePidFile };