@parallax-rn/sdk 0.0.0-stage → 0.1.0-beta.3

package/LICENSE

@@ -0,0 +1,72 @@
+PARALLAX LICENSE (BETA TERMS, VERSION 1, 2026-10-28)
+
+Copyright (c) 2026 Valiantsin Tsikhamirau. All rights reserved.
+Contact: zemantservices@gmail.com, https://parallax-rn.dev
+
+1. Definitions
+"Software" means this package of Parallax for React Native, including its code, documentation and any updates the Licensor supplies. "You" means the person or
+organization that installs or uses the Software. "Licensor" means Valiantsin Tsikhamirau, the author of the Software. "Your Applications" means software that You
+develop or maintain.
+
+2. Grant of license
+The Licensor grants You a worldwide, non-exclusive, non-transferable, revocable, royalty-free license, free of charge, to install and use the Software
+for Your own personal or internal business purposes, including the commercial development, testing and debugging of Your Applications. This includes:
+(a) adding the in-app SDK and the Babel plugin of the Software to Your Applications as development dependencies;
+(b) building, distributing and selling Your Applications, even when a build of Your Application contains code of the SDK or of the Babel plugin, as long
+    as that code stays a part of Your Application and is not offered on its own;
+(c) keeping copies of the Software in Your organization's internal package mirrors, registries, caches, continuous integration systems, lock files and
+    vendored dependency folders, for use under this license by Your own staff and contractors;
+(d) installing it on any number of machines used by You, Your staff or Your contractors working on Your Applications.
+
+3. Restrictions
+Except as this license expressly allows or as mandatory law allows despite this limit, You may not:
+(a) modify, adapt, translate or create derivative works of the Software;
+(b) distribute, sublicense, sell, rent, lease, lend, host as a service or otherwise make the Software or any part of it available to others outside Your
+    organization, including by publishing it to a public package registry or repository, except as section 2 allows;
+(c) reverse engineer, decompile or disassemble the Software, or try to obtain its source code;
+(d) use the Software, its output or its documentation to build, train or benchmark a product or service that competes with the Software, or give the
+    Software to a person for that purpose;
+(e) remove or change any copyright, license or other notice in the Software.
+
+4. Third-party components
+The Software contains third-party components under their own licenses, listed in the file THIRD_PARTY_NOTICES where the package contains one. Those licenses,
+not this one, govern those components.
+
+5. Ownership
+The Software is licensed, not sold. The Licensor keeps all rights not expressly granted. This license grants no right to the Licensor's name or marks.
+Your Applications, their data and the output of Your agents stay Yours.
+
+6. Data
+The Software runs on Your machine. It has no account, no telemetry and no analytics, and it does not send data to the Licensor. What it reads from Your
+application and simulator or emulator (the screen, the component tree, logs, errors, network requests, state and navigation) is returned to the AI agent
+You connect to it, such as Claude Code or Codex, and that agent sends what it receives to its own provider under that provider's terms. The Licensor does
+not control that. The Software removes known secrets from network and state data before an agent receives them; logs and errors are passed on as Your
+application wrote them.
+
+7. Beta software
+The Software is a beta. It may change, stop working or be withdrawn at any time, and later versions may come under different terms, including paid terms
+for some parts. A version You received under this license stays under this license.
+
+8. Termination
+This license ends automatically if You breach it. Then You must stop using the Software and delete all copies, except copies inside builds of Your
+Applications that section 2(b) allows. You may end it at any time by deleting the Software. Sections 3, 5, 9, 10 and 11 survive.
+
+9. No warranty
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NON-INFRINGEMENT.
+
+10. Limitation of liability
+TO THE EXTENT THE LAW ALLOWS, THE LICENSOR IS NOT LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR LOST PROFITS OR DATA,
+ARISING FROM THE SOFTWARE OR ITS USE, AND THE LICENSOR'S TOTAL LIABILITY IS LIMITED TO THE AMOUNT YOU PAID FOR THE SOFTWARE (ZERO FOR THE FREE LICENSE).
+NOTHING IN THIS LICENSE LIMITS LIABILITY FOR INTENT OR GROSS NEGLIGENCE, OR ANY LIABILITY THAT CANNOT BE LIMITED BY LAW.
+
+11. General
+(a) Governing law and courts. This license is governed by the law of the Republic of Belarus, without regard to its conflict of laws rules. The courts of
+    Minsk, Belarus, have jurisdiction over any dispute about it. If You are a consumer, nothing in this license takes away a protection that the law of the
+    country where You live gives You and that cannot be waived by agreement, including Your right to bring a claim in Your own courts.
+(b) Severability. If a court finds a part of this license invalid, that part is limited to the minimum extent needed and the rest stays in force.
+(c) Entire agreement. This license is the entire agreement between You and the Licensor about the Software and replaces any earlier statement about it.
+    A paid tier, if one is offered later, comes with its own terms.
+(d) Export. You must comply with the export control and sanctions laws that apply to You when You use or move the Software.
+(e) No waiver. If the Licensor does not enforce a term, the Licensor keeps the right to enforce it later.
+(f) Language. This license is written in English; a translation is for convenience only.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @parallax-rn/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The dev-only code that runs inside the React Native app. Its only dependency is `@parallax-rn/protocol`; importing it has no side effects. Everything the SDK touches (console, `ErrorUtils`, timers, the push binding) goes through one `HostGlobal` interface, so it compiles without Node or DOM types and is tested against a fake host.
+
+## Wiring
+```js
+if (__DEV__) {
+  require('@parallax-rn/sdk').start();
+}
+```
+Metro removes the whole branch from a release bundle (checked: `node scripts/verify-metro-resolution.mjs --guarded sdk <toolchain dir>`; the release bundle contains no SDK code). As a second guard `start()` does nothing and returns `false` when `__DEV__ === false`. The plugin (`@parallax-rn/babel-plugin`, later step) will emit this wiring itself; `doctor` reports whether it is present.
+
+## What it does
+- **Console capture** for `debug`, `log`, `info`, `warn`, `error`. The original method always runs first, with the same arguments and `this`; capture happens afterwards in a guarded block, so a failing or re-entrant capture never reaches the app. LogBox, Metro logs and the DevTools console behave as without the SDK.
+- **Uncaught errors** through `ErrorUtils.setGlobalHandler`; the previously installed handler is always called (fatal and non-fatal), so the red box still appears.
+- **Ring buffers** (logs 1000, errors 100) are the source of truth. Entries get a `seq` that starts at 1; a server that attaches late, or after a reload or reconnect, drains by cursor.
+- **Push** through the `__PARALLAX_RN_PUSH__` binding (decision 0010): string payloads only, `typeof` checked before every call (the binding does not exist until a session adds it), bursts coalesced for 50 ms (errors at once), a batch split at 100 entries or about 100000 characters. Pushing only lowers latency; a missed push loses nothing.
+- **Caps** per entry: message 4000 and stack 8000 characters; a cut entry is marked `truncated: true`. These are limits on memory and push size, separate from the 500-character limit on what an agent receives from a tool.
+- **Commands**: `registerCommand(name, handler, { description, argsHint })` (registering a name again replaces it; Fast Refresh re-runs modules) and the built-in `parallax.ping`.
+- `stop()` restores the console methods and the error handler (a wrapper installed by someone else after ours is left in place and ours just stops capturing).
+
+## The API object
+`globalThis.__PARALLAX_RN__.sdk` has `handshake()`, `drain(requestJson)`, `commands()` and `call(requestJson)`. Each takes a JSON string (or nothing) and returns a JSON string; `call` returns a promise of one, because command handlers may be async. Note (spike 0007): on RN's Hermes `Runtime.evaluate` ignores `awaitPromise`, so a client cannot simply await `call`; how the client settles it is open in S5.
+
+## Limits
+`DEFAULT_LIMITS` in `src/limits.ts`, overridable per `createSdk({ limits })`. Values come from spike 0007 (about 2 MB worst-case memory, p95 push latency at most 77 ms at 480 lines/s).
+
+## Hermes note
+Do not create closures inside a `for (const x of ...)` loop body in this package: Hermes evaluates code received through `Runtime.evaluate` without per-iteration bindings (found in spike 0007). Put the body in a function.
+
+## License
+Proprietary and free to use (decision 0014): see `LICENSE` in the package. The text is the beta terms, version 1. Tested on React Native 0.87.1.

package/dist/commands.d.ts

@@ -0,0 +1,15 @@
+import type { CommandInfo, CommandResult } from '@parallax-rn/protocol';
+export type CommandHandler = (args: unknown) => unknown;
+export interface CommandMeta {
+    readonly description?: string;
+    /** A short human-readable description of the arguments, for example `{ id: string }`. */
+    readonly argsHint?: string;
+}
+export declare class CommandRegistry {
+    private readonly entries;
+    /** Registers a command; registering the same name again replaces it (Fast Refresh re-runs modules). Returns an unregister function. */
+    register(name: string, handler: CommandHandler, meta?: CommandMeta): () => void;
+    list(): CommandInfo[];
+    call(name: string, args: unknown): Promise<CommandResult>;
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandRegistry = void 0;
+class CommandRegistry {
+    constructor() {
+        this.entries = new Map();
+    }
+    /** Registers a command; registering the same name again replaces it (Fast Refresh re-runs modules). Returns an unregister function. */
+    register(name, handler, meta = {}) {
+        if (typeof name !== 'string' || name.trim() === '')
+            throw new TypeError('a command needs a non-empty name');
+        if (typeof handler !== 'function')
+            throw new TypeError('a command needs a handler function');
+        const entry = { handler, meta };
+        this.entries.set(name, entry);
+        return () => {
+            if (this.entries.get(name) === entry)
+                this.entries.delete(name);
+        };
+    }
+    list() {
+        const list = [];
+        this.entries.forEach((entry, name) => {
+            const info = { name };
+            if (entry.meta.description !== undefined)
+                info.description = entry.meta.description;
+            if (entry.meta.argsHint !== undefined)
+                info.argsHint = entry.meta.argsHint;
+            list.push(info);
+        });
+        return list;
+    }
+    async call(name, args) {
+        const entry = this.entries.get(name);
+        if (!entry)
+            return { ok: false, error: { code: 'command_not_found', message: `No command named "${name}" is registered.` } };
+        try {
+            const value = await entry.handler(args);
+            const text = JSON.stringify(value === undefined ? null : value);
+            if (text === undefined)
+                return { ok: false, error: { code: 'command_failed', message: 'The command result is not JSON-serializable.' } };
+            return { ok: true, value: JSON.parse(text) };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'The command failed.';
+            return { ok: false, error: { code: 'command_failed', message } };
+        }
+    }
+}
+exports.CommandRegistry = CommandRegistry;

package/dist/console-capture.d.ts

@@ -0,0 +1,7 @@
+import { type HostGlobal } from './host.js';
+import type { LogLevel } from '@parallax-rn/protocol';
+export interface Installed {
+    uninstall(): void;
+}
+export declare function installConsoleCapture(host: HostGlobal, onLog: (level: LogLevel, args: unknown[]) => void): Installed;
+//# sourceMappingURL=console-capture.d.ts.map

package/dist/console-capture.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installConsoleCapture = installConsoleCapture;
+// Captures console output without disturbing it: the original method always runs first with the same arguments and `this`,
+// so LogBox, Metro logs and the DevTools console behave exactly as without the SDK. A failing capture never reaches the app.
+const host_js_1 = require("./host.js");
+function installConsoleCapture(host, onLog) {
+    const target = host.console;
+    const restores = [];
+    let active = true;
+    let capturing = false;
+    // One function per level instead of closures created in the loop body: Hermes evaluates code it receives through
+    // Runtime.evaluate without per-iteration bindings, so every closure in a `for (const level of ...)` loop saw the last level.
+    function wrapLevel(console, level) {
+        const original = console[level];
+        if (typeof original !== 'function')
+            return;
+        const wrapper = function (...args) {
+            try {
+                return original.apply(this, args);
+            }
+            finally {
+                if (active && !capturing) {
+                    capturing = true;
+                    try {
+                        onLog(level, args);
+                    }
+                    catch {
+                        /* capture must never break the app */
+                    }
+                    finally {
+                        capturing = false;
+                    }
+                }
+            }
+        };
+        console[level] = wrapper;
+        restores.push(() => {
+            // someone may have wrapped console after us: then leave their wrapper in place and just stop capturing
+            if (console[level] === wrapper)
+                console[level] = original;
+        });
+    }
+    if (target) {
+        for (const level of host_js_1.CONSOLE_LEVELS)
+            wrapLevel(target, level);
+    }
+    return {
+        uninstall() {
+            active = false;
+            for (const restore of restores)
+                restore();
+            restores.length = 0;
+        },
+    };
+}

package/dist/error-capture.d.ts

@@ -0,0 +1,4 @@
+import type { HostGlobal } from './host.js';
+import type { Installed } from './console-capture.js';
+export declare function installErrorCapture(host: HostGlobal, onError: (error: unknown, isFatal: boolean) => void): Installed | null;
+//# sourceMappingURL=error-capture.d.ts.map

package/dist/error-capture.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installErrorCapture = installErrorCapture;
+function installErrorCapture(host, onError) {
+    const utils = host.ErrorUtils;
+    if (!utils || typeof utils.getGlobalHandler !== 'function' || typeof utils.setGlobalHandler !== 'function')
+        return null;
+    const previous = utils.getGlobalHandler();
+    let active = true;
+    const handler = (error, isFatal) => {
+        if (active) {
+            try {
+                onError(error, isFatal === true);
+            }
+            catch {
+                /* capture must never break error handling */
+            }
+        }
+        if (typeof previous === 'function')
+            previous(error, isFatal);
+    };
+    utils.setGlobalHandler(handler);
+    return {
+        uninstall() {
+            active = false;
+            if (typeof utils.getGlobalHandler === 'function' && utils.getGlobalHandler() === handler && typeof utils.setGlobalHandler === 'function' && previous) {
+                utils.setGlobalHandler(previous);
+            }
+        },
+    };
+}

package/dist/format.d.ts

@@ -0,0 +1,10 @@
+export interface Capped {
+    readonly text: string;
+    readonly truncated: boolean;
+}
+/** Cuts the text to `max` characters (the last one becomes an ellipsis) and says whether it did. */
+export declare function cap(text: string, max: number): Capped;
+/** One argument as it appears in a console line: strings as they are, Errors with their stack, everything else inspected. */
+export declare function formatArg(value: unknown): string;
+export declare function formatArgs(args: readonly unknown[]): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,92 @@
+"use strict";
+// Turns console arguments and thrown values into bounded text. It must never throw and never loop on cycles.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cap = cap;
+exports.formatArg = formatArg;
+exports.formatArgs = formatArgs;
+const MAX_NODES = 200;
+const MAX_DEPTH = 3;
+/** Cuts the text to `max` characters (the last one becomes an ellipsis) and says whether it did. */
+function cap(text, max) {
+    if (text.length <= max)
+        return { text, truncated: false };
+    return { text: max > 1 ? text.slice(0, max - 1) + '…' : text.slice(0, max), truncated: true };
+}
+function describeFunction(fn) {
+    const name = fn.name;
+    return typeof name === 'string' && name ? `[Function ${name}]` : '[Function]';
+}
+function inspect(value, depth, seen, budget) {
+    if (budget.nodes-- <= 0)
+        return '…';
+    switch (typeof value) {
+        case 'string':
+            return JSON.stringify(value);
+        case 'number':
+        case 'boolean':
+        case 'undefined':
+            return String(value);
+        case 'bigint':
+            return `${String(value)}n`;
+        case 'symbol':
+            return String(value);
+        case 'function':
+            return describeFunction(value);
+    }
+    if (value === null)
+        return 'null';
+    if (seen.indexOf(value) !== -1)
+        return '[Circular]';
+    if (value instanceof Error)
+        return `${value.name}: ${value.message}`;
+    if (value instanceof Date)
+        return isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString();
+    if (depth >= MAX_DEPTH)
+        return Array.isArray(value) ? '[Array]' : '[Object]';
+    seen.push(value);
+    try {
+        if (Array.isArray(value)) {
+            const parts = [];
+            for (let i = 0; i < value.length && budget.nodes > 0; i++)
+                parts.push(inspect(value[i], depth + 1, seen, budget));
+            return `[${parts.join(', ')}${parts.length < value.length ? ', …' : ''}]`;
+        }
+        const keys = Object.keys(value);
+        const parts = [];
+        for (let i = 0; i < keys.length && budget.nodes > 0; i++) {
+            const key = keys[i];
+            // an accessor is not called: reading it could run the app's code a second time (a getter with a side effect, or one that is slow)
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor !== undefined && !('value' in descriptor) && (descriptor.get !== undefined || descriptor.set !== undefined)) {
+                parts.push(`${key}: [Getter]`);
+                continue;
+            }
+            parts.push(`${key}: ${inspect(value[key], depth + 1, seen, budget)}`);
+        }
+        const ctor = value.constructor;
+        const name = typeof (ctor === null || ctor === void 0 ? void 0 : ctor.name) === 'string' && ctor.name !== 'Object' ? `${ctor.name} ` : '';
+        return `${name}{${parts.join(', ')}${parts.length < keys.length ? ', …' : ''}}`;
+    }
+    finally {
+        seen.pop();
+    }
+}
+/** One argument as it appears in a console line: strings as they are, Errors with their stack, everything else inspected. */
+function formatArg(value) {
+    try {
+        if (typeof value === 'string')
+            return value;
+        if (value instanceof Error)
+            return typeof value.stack === 'string' && value.stack ? value.stack : `${value.name}: ${value.message}`;
+        return inspect(value, 0, [], { nodes: MAX_NODES });
+    }
+    catch {
+        return '[unprintable]';
+    }
+}
+function formatArgs(args) {
+    const parts = [];
+    for (let i = 0; i < args.length; i++)
+        parts.push(formatArg(args[i]));
+    return parts.join(' ');
+}

package/dist/host.d.ts

@@ -0,0 +1,19 @@
+import type { LogLevel } from '@parallax-rn/protocol';
+export type ConsoleMethod = (...args: unknown[]) => unknown;
+export type ErrorHandler = (error: unknown, isFatal?: boolean) => void;
+export interface HostGlobal {
+    __DEV__?: boolean;
+    console?: {
+        [level: string]: unknown;
+    };
+    ErrorUtils?: {
+        getGlobalHandler?: () => ErrorHandler | undefined;
+        setGlobalHandler?: (handler: ErrorHandler) => void;
+    };
+    setTimeout?: (callback: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+    [name: string]: unknown;
+}
+export declare const CONSOLE_LEVELS: readonly LogLevel[];
+export declare function defaultHost(): HostGlobal;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSOLE_LEVELS = void 0;
+exports.defaultHost = defaultHost;
+exports.CONSOLE_LEVELS = ['debug', 'log', 'info', 'warn', 'error'];
+function defaultHost() {
+    return globalThis;
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { CommandHandler, CommandMeta } from './commands.js';
+import type { NavigationRefLike } from './navigation.js';
+import type { StoreOptions } from './stores.js';
+/** Starts capturing console output and uncaught errors. Returns false and does nothing when `__DEV__` is false. */
+export declare const start: () => boolean;
+export declare const stop: () => void;
+export declare const isStarted: () => boolean;
+/** Registers a command the agent can run; registering the same name again replaces it. Returns an unregister function. */
+export declare const registerCommand: (name: string, handler: CommandHandler, meta?: CommandMeta) => (() => void);
+/** Follows a React Navigation container ref (`createNavigationContainerRef()`, Expo Router's `useNavigationContainerRef()`): the agent reads the route and its history. Returns the stop function. */
+export declare const registerNavigation: (ref: NavigationRefLike) => (() => void);
+/** Follows a Redux or Zustand store (anything with `getState()` and `subscribe()`) as the source `state:<name>`; `{ actions: true }` also records the last Redux action type. Returns an unregister function. */
+export declare const registerStore: (name: string, store: unknown, options?: StoreOptions) => (() => void);
+/** Follows a TanStack Query client as the source `query:<name>`. Returns an unregister function. */
+export declare const registerQueryClient: (name: string, client: unknown) => (() => void);
+export { createSdk } from './sdk.js';
+export type { Sdk, SdkOptions } from './sdk.js';
+export type { CommandHandler, CommandMeta } from './commands.js';
+export type { NavigationRefLike } from './navigation.js';
+export type { StoreOptions } from './stores.js';
+export { DEFAULT_LIMITS } from './limits.js';
+export type { SdkLimits } from './limits.js';
+export { SDK_VERSION } from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = exports.DEFAULT_LIMITS = exports.createSdk = exports.registerQueryClient = exports.registerStore = exports.registerNavigation = exports.registerCommand = exports.isStarted = exports.stop = exports.start = void 0;
+// Public surface of @parallax-rn/sdk. Importing it has no side effects; call `start()` behind `__DEV__`:
+//   if (__DEV__) { require('@parallax-rn/sdk').start(); }
+const sdk_js_1 = require("./sdk.js");
+const sdk = (0, sdk_js_1.createSdk)();
+/** Starts capturing console output and uncaught errors. Returns false and does nothing when `__DEV__` is false. */
+const start = () => sdk.start();
+exports.start = start;
+const stop = () => sdk.stop();
+exports.stop = stop;
+const isStarted = () => sdk.started;
+exports.isStarted = isStarted;
+/** Registers a command the agent can run; registering the same name again replaces it. Returns an unregister function. */
+const registerCommand = (name, handler, meta) => sdk.registerCommand(name, handler, meta);
+exports.registerCommand = registerCommand;
+/** Follows a React Navigation container ref (`createNavigationContainerRef()`, Expo Router's `useNavigationContainerRef()`): the agent reads the route and its history. Returns the stop function. */
+const registerNavigation = (ref) => sdk.registerNavigation(ref);
+exports.registerNavigation = registerNavigation;
+/** Follows a Redux or Zustand store (anything with `getState()` and `subscribe()`) as the source `state:<name>`; `{ actions: true }` also records the last Redux action type. Returns an unregister function. */
+const registerStore = (name, store, options) => sdk.registerStore(name, store, options);
+exports.registerStore = registerStore;
+/** Follows a TanStack Query client as the source `query:<name>`. Returns an unregister function. */
+const registerQueryClient = (name, client) => sdk.registerQueryClient(name, client);
+exports.registerQueryClient = registerQueryClient;
+var sdk_js_2 = require("./sdk.js");
+Object.defineProperty(exports, "createSdk", { enumerable: true, get: function () { return sdk_js_2.createSdk; } });
+var limits_js_1 = require("./limits.js");
+Object.defineProperty(exports, "DEFAULT_LIMITS", { enumerable: true, get: function () { return limits_js_1.DEFAULT_LIMITS; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_js_1.SDK_VERSION; } });

package/dist/limits.d.ts

@@ -0,0 +1,31 @@
+export interface SdkLimits {
+    /** Entries kept per stream: the history a late client can drain. */
+    readonly logCapacity: number;
+    readonly errorCapacity: number;
+    /** Requests kept by the network capture (plan 0013, Part B). */
+    readonly networkCapacity: number;
+    /** Transitions kept of the `navigation` source. */
+    readonly navigationCapacity: number;
+    /** Characters of one request or response body (a longer one is cut and says so), of one header value, and of a request's call-site stack. */
+    readonly networkBodyChars: number;
+    readonly networkHeaderChars: number;
+    readonly networkStackChars: number;
+    /** Store snapshots (plan 0013, 13.9): entries kept per store, the character budget and depth of one snapshot, the budget of one query's data, and the throttle between snapshots. */
+    readonly storeCapacity: number;
+    readonly stateMaxChars: number;
+    readonly stateMaxDepth: number;
+    readonly queryDataMaxChars: number;
+    readonly snapshotIntervalMs: number;
+    /** Per-entry caps in characters; a cut entry is marked `truncated`. Separate from the tool-output limit an agent sees. */
+    readonly maxMessageChars: number;
+    readonly maxStackChars: number;
+    /** One push carries at most this many entries and about this many characters. */
+    readonly maxBatchEntries: number;
+    readonly maxBatchChars: number;
+    /** Bursts are coalesced for this long before a push (errors are pushed at once). */
+    readonly flushIntervalMs: number;
+    /** Default and upper bound of entries per stream returned by one drain call. */
+    readonly drainLimit: number;
+}
+export declare const DEFAULT_LIMITS: SdkLimits;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LIMITS = void 0;
+exports.DEFAULT_LIMITS = {
+    logCapacity: 1000,
+    errorCapacity: 100,
+    // ponytail: a count, not a byte budget (the plan's 2 MB): typical bodies are far under the cap, the worst case is 300 x 2 bodies; measure on a real app (L27) and add a byte budget if it matters
+    networkCapacity: 300,
+    navigationCapacity: 100,
+    networkBodyChars: 32000,
+    networkHeaderChars: 2000,
+    networkStackChars: 4000,
+    storeCapacity: 50,
+    stateMaxChars: 32000,
+    stateMaxDepth: 6,
+    queryDataMaxChars: 2000,
+    snapshotIntervalMs: 200,
+    maxMessageChars: 4000,
+    maxStackChars: 8000,
+    maxBatchEntries: 100,
+    maxBatchChars: 100000,
+    flushIntervalMs: 50,
+    drainLimit: 500,
+};

package/dist/navigation.d.ts

@@ -0,0 +1,26 @@
+import { type NavigationEntry } from '@parallax-rn/protocol';
+/** What a container ref must have: React Navigation's `createNavigationContainerRef()` and Expo Router's `useNavigationContainerRef()` both do. */
+export interface NavigationRefLike {
+    getRootState(): unknown;
+    addListener(event: 'state', listener: () => void): unknown;
+}
+export declare const NAV_LIMITS: {
+    readonly depth: 8;
+    readonly routes: 50;
+    readonly paramDepth: 3;
+    readonly keys: 30;
+    readonly chars: 200;
+    readonly rootStateChars: 16000;
+};
+/** Params without secrets: keys by the picker's word rule, values shaped like a credential, long strings cut, depth and width capped, getters and functions never run. */
+export declare function scrubParams(value: unknown, depth?: number, seen?: object[]): unknown;
+/** A route's `path` (a deep link) with the value of every secret-looking query parameter masked. */
+export declare function scrubPath(path: string): string;
+/** The entry for one root state: the focused route (the deepest one following each navigator's `index`), its params and path, the route names from the root, the reduced state (dropped past 16,000 characters). Null: no routes. */
+export declare function entryOf(rootState: unknown): NavigationEntry | null;
+/**
+ * Follows a container ref: `emit` gets an entry now and after every state change that differs from the last one. Returns the stop function. A ref that throws is ignored (the
+ * app must never see the SDK fail).
+ */
+export declare function followNavigation(ref: NavigationRefLike, emit: (entry: NavigationEntry) => void): () => void;
+//# sourceMappingURL=navigation.d.ts.map