madeonsol-x402 4.2.0 → 4.3.0

package/dist/terminal-watch.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Framework-agnostic terminal snapshot/stream bridge (#534).
+ *
+ * A shared SDK socket supplies push frames. Snapshot reads happen once after
+ * the named subscription is ACKED, then only on coalesced, named invalidations.
+ * This deliberately NEVER patches REST module data from unrelated clocks.
+ *
+ * Instantiate once per selected token, reusing one existing stream connection.
+ * The controller never closes that shared stream on dispose().
+ */
+import { type TerminalWatchPlan, type TerminalModule, type TerminalChain, type TerminalTier } from "./terminal-policy.js";
+export interface TerminalStreamFrame {
+    channel?: string;
+    event?: string;
+    sub_id?: string;
+    id?: string;
+    data?: unknown;
+    ts?: number;
+    replayed?: boolean;
+    snapshot?: boolean;
+}
+/** Adaptable to the existing MadeOnSolStream / RobinhoodChainStream overloads. */
+export interface TerminalStreamPort {
+    subscribe(opts: {
+        subId: string;
+        channels: string[];
+        filters: Record<string, unknown>;
+    }): unknown;
+    unsubscribe(subId: string): unknown;
+    on(event: string, listener: (...args: unknown[]) => unknown): unknown;
+    off(event: string, listener: (...args: unknown[]) => unknown): unknown;
+}
+export interface TerminalModuleResponse {
+    status: "ready" | "partial_history" | "unverified" | "unavailable" | "timeout";
+    reason: string | null;
+    as_of: string | null;
+    data?: Record<string, unknown>;
+}
+export interface TerminalSnapshotResponse {
+    chain: TerminalChain;
+    address: string;
+    generated_at: string;
+    modules: Partial<Record<TerminalModule, TerminalModuleResponse>>;
+}
+export type TerminalPhase = "idle" | "awaiting_subscribe" | "bootstrapping" | "live" | "degraded" | "stopped";
+export interface TerminalView {
+    phase: TerminalPhase;
+    address: string;
+    chain: TerminalChain;
+    /** Untouched REST modules; use the latest live frame as a separate overlay. */
+    snapshot: TerminalSnapshotResponse | null;
+    live: Partial<Record<TerminalModule, TerminalStreamFrame>>;
+    /** A known event or gap may have made a cached module stale. */
+    stale: TerminalModule[];
+    /** A module without an adequate existing WS source is snapshot-only. */
+    no_push: TerminalModule[];
+    /** A stream interruption or refusal must be visible to the terminal. */
+    incomplete: boolean;
+    last_error: string | null;
+}
+export interface TerminalViewOptions {
+    chain: TerminalChain;
+    address: string;
+    tier: TerminalTier;
+    include: readonly TerminalModule[];
+    /** Full RHC DEX firehose (all tokens) is high-bandwidth; opt in explicitly. */
+    includeRhcFirehose?: boolean;
+    /** KOL channels are unscoped broadcasts; opt in only with bandwidth budget. */
+    includeKolBroadcast?: boolean;
+    subId: string;
+    stream: TerminalStreamPort;
+    /** The existing keyed REST .tokenIntelligence(address, {include}) call. */
+    read: (include: readonly TerminalModule[]) => Promise<TerminalSnapshotResponse>;
+    onChange?: (view: TerminalView) => void;
+    onLive?: (frame: TerminalStreamFrame, module: TerminalModule) => void;
+    /** Min seconds per module before another HTTP refresh (default 15s). */
+    minModuleRefreshMs?: number;
+    /** Debounce and coalesce changed modules (default 750ms). */
+    debounceMs?: number;
+    now?: () => number;
+}
+/** Bounded by nine modules and one frame per live overlay; never a trade queue. */
+export declare class TerminalTokenView {
+    readonly plan: TerminalWatchPlan;
+    private readonly opts;
+    private readonly listeners;
+    private readonly dirty;
+    private readonly stale;
+    private readonly seen;
+    private readonly live;
+    private readonly gen;
+    private readonly lastRead;
+    private readonly now;
+    private timer;
+    private timerAt;
+    private busy;
+    /** If the socket ACK arrives while a prior REST read is still unresolved,
+     * the latest post-ACK snapshot must run after that read settles. */
+    private pendingBootstrap;
+    private subscribed;
+    private epoch;
+    private phase;
+    private incomplete;
+    /** An observed historical gap survives a new REST snapshot and reconnect. */
+    private gapUnresolved;
+    private lastError;
+    private snapshot;
+    constructor(options: TerminalViewOptions);
+    getView(): TerminalView;
+    /** Registers handlers BEFORE opening the stream; first REST read waits for ACK. */
+    start(): void;
+    /** Consumer-initiated refresh, useful after a known unrecoverable gap. */
+    refresh(): void;
+    /**
+     * The caller must independently reconcile an unrecoverable event interval
+     * BEFORE clearing the visible gap. A fresh snapshot is not that evidence.
+     */
+    acknowledgeHistoricalRecovery(): void;
+    dispose(): void;
+    private isStopped;
+    private emit;
+    private listen;
+    private onSubscribed;
+    private onWarning;
+    private onGap;
+    private onFrame;
+    private markStale;
+    private clearTimer;
+    private schedule;
+    private flush;
+    private fetchModules;
+}
+/** A named subscription prevents overwriting an integrator's other filters. */
+export declare function createTerminalTokenView(options: TerminalViewOptions): TerminalTokenView;
+//# sourceMappingURL=terminal-watch.d.ts.map

package/dist/terminal-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-watch.d.ts","sourceRoot":"","sources":["../src/terminal-watch.ts"],"names":[],"mappings":"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"}

package/dist/terminal-watch.js

@@ -0,0 +1,413 @@
+/* Mirrored from src/lib/terminal-realtime/watch.ts; see SDK parity tests. */
+/**
+ * Framework-agnostic terminal snapshot/stream bridge (#534).
+ *
+ * A shared SDK socket supplies push frames. Snapshot reads happen once after
+ * the named subscription is ACKED, then only on coalesced, named invalidations.
+ * This deliberately NEVER patches REST module data from unrelated clocks.
+ *
+ * Instantiate once per selected token, reusing one existing stream connection.
+ * The controller never closes that shared stream on dispose().
+ */
+import { planTerminalWatch, rulesForEvent, TERMINAL_MODULE_COSTS, } from "./terminal-policy.js";
+const ACK_SUBSCRIBE = "subscribed";
+const MAX_DEDUPE_IDS = 512;
+/** Bounded by nine modules and one frame per live overlay; never a trade queue. */
+export class TerminalTokenView {
+    plan;
+    opts;
+    listeners = new Map();
+    dirty = new Set();
+    stale = new Set();
+    seen = new Map();
+    live = {};
+    gen = new Map();
+    lastRead = new Map();
+    now;
+    timer = null;
+    timerAt = 0;
+    busy = false;
+    /** If the socket ACK arrives while a prior REST read is still unresolved,
+     * the latest post-ACK snapshot must run after that read settles. */
+    pendingBootstrap = false;
+    subscribed = false;
+    epoch = 0;
+    phase = "idle";
+    incomplete = false;
+    /** An observed historical gap survives a new REST snapshot and reconnect. */
+    gapUnresolved = false;
+    lastError = null;
+    snapshot = null;
+    constructor(options) {
+        if (!/^[A-Za-z0-9_.-]{1,64}$/.test(options.subId) || options.subId === "default") {
+            throw new Error("named_sub_id_required");
+        }
+        const n = options.minModuleRefreshMs ?? 15_000;
+        const d = options.debounceMs ?? 750;
+        if (!Number.isFinite(n) || n < 1_000 || n > 600_000 ||
+            !Number.isFinite(d) || d < 0 || d > 30_000)
+            throw new Error("invalid_refresh_budget");
+        this.plan = planTerminalWatch(options);
+        this.opts = options;
+        this.now = options.now ?? Date.now;
+        for (const m of this.plan.include)
+            this.gen.set(m, 0);
+    }
+    getView() {
+        return {
+            phase: this.phase, address: this.plan.address, chain: this.plan.chain,
+            snapshot: this.snapshot,
+            live: { ...this.live },
+            stale: [...this.stale],
+            no_push: [...this.plan.modules_without_push],
+            incomplete: this.incomplete,
+            last_error: this.lastError,
+        };
+    }
+    /** Registers handlers BEFORE opening the stream; first REST read waits for ACK. */
+    start() {
+        if (this.phase !== "idle")
+            throw new Error("already_started");
+        this.phase = this.plan.channels.length ? "awaiting_subscribe" : "bootstrapping";
+        this.emit();
+        if (!this.plan.channels.length) {
+            void this.fetchModules(this.plan.include, true);
+            return;
+        }
+        this.listen("*", (data, frame) => this.onFrame(frame));
+        this.listen(ACK_SUBSCRIBE, (_channels, ack) => this.onSubscribed(ack));
+        this.listen("close", () => {
+            if (this.phase === "stopped")
+                return;
+            // A fetch launched on the old socket can no longer be trusted.
+            this.epoch++;
+            this.pendingBootstrap = false;
+            this.subscribed = false;
+            this.incomplete = true;
+            this.phase = "awaiting_subscribe";
+            this.markStale(this.plan.include);
+            this.clearTimer();
+            this.emit();
+        });
+        this.listen("warning", (warn) => this.onWarning(warn));
+        this.listen("gap", (gap) => this.onGap(gap));
+        this.listen("fatal", () => {
+            this.subscribed = false;
+            this.incomplete = true;
+            this.phase = "degraded";
+            this.markStale(this.plan.include);
+            this.clearTimer();
+            this.emit();
+        });
+        this.opts.stream.subscribe({
+            subId: this.opts.subId,
+            channels: [...this.plan.channels],
+            filters: this.plan.filters,
+        });
+    }
+    /** Consumer-initiated refresh, useful after a known unrecoverable gap. */
+    refresh() {
+        if (this.phase === "idle" || this.phase === "stopped")
+            throw new Error("watch_not_active");
+        this.markStale(this.plan.include);
+        for (const m of this.plan.include)
+            this.dirty.add(m);
+        this.schedule(0);
+    }
+    /**
+     * The caller must independently reconcile an unrecoverable event interval
+     * BEFORE clearing the visible gap. A fresh snapshot is not that evidence.
+     */
+    acknowledgeHistoricalRecovery() {
+        if (!this.gapUnresolved || this.phase === "stopped")
+            return;
+        this.gapUnresolved = false;
+        this.incomplete = !this.subscribed;
+        if (this.lastError === "stream_gap")
+            this.lastError = null;
+        if (!this.incomplete && this.snapshot)
+            this.phase = "live";
+        this.emit();
+    }
+    dispose() {
+        if (this.phase === "stopped")
+            return;
+        this.epoch++;
+        this.pendingBootstrap = false;
+        this.phase = "stopped";
+        this.subscribed = false;
+        this.clearTimer();
+        for (const [event, fn] of this.listeners)
+            this.opts.stream.off(event, fn);
+        this.listeners.clear();
+        if (this.plan.channels.length)
+            this.opts.stream.unsubscribe(this.opts.subId);
+        this.emit();
+    }
+    isStopped() { return this.phase === "stopped"; }
+    // A throwing UI callback must never leave the controller half-updated.
+    emit() { try {
+        this.opts.onChange?.(this.getView());
+    }
+    catch { /* consumer */ } }
+    listen(event, cb) {
+        this.listeners.set(event, cb);
+        this.opts.stream.on(event, cb);
+    }
+    onSubscribed(ack) {
+        if (this.phase === "stopped" || !ack || ack.sub_id !== this.opts.subId)
+            return;
+        const channels = Array.isArray(ack.channels) ? ack.channels : [];
+        // A partial or silently rejected subscription cannot be treated as live.
+        if (!this.plan.channels.every(ch => channels.includes(ch))) {
+            this.incomplete = true;
+            this.subscribed = false;
+            this.lastError = "subscription_incomplete";
+            this.phase = "degraded";
+            this.markStale(this.plan.include);
+            this.emit();
+            return;
+        }
+        // Invalidate any in-flight REST read from before this ACK/reconnect.
+        this.epoch++;
+        this.subscribed = true;
+        // Re-ACK proves a live subscription again, not that old trade events
+        // reported missing by the SDK have been reconstructed.
+        this.incomplete = this.gapUnresolved;
+        this.lastError = this.gapUnresolved ? "stream_gap" : null;
+        this.clearTimer();
+        // A re-subscribe after reconnect ALWAYS re-reads a bounded snapshot. We
+        // cannot compare clocks from REST and WS as one total-order watermark.
+        this.phase = "bootstrapping";
+        this.pendingBootstrap = true;
+        for (const m of this.plan.include)
+            this.dirty.add(m);
+        this.emit();
+        if (!this.busy) {
+            this.pendingBootstrap = false;
+            void this.fetchModules(this.plan.include, true);
+        }
+    }
+    onWarning(value) {
+        if (!value || typeof value !== "object" || this.phase === "stopped")
+            return;
+        const w = value;
+        // Named-subscription warnings always carry sub_id; one without it belongs
+        // to the connection default subscription, not this terminal view.
+        if (w.sub_id !== this.opts.subId)
+            return;
+        if (["channels_rejected", "channels_revoked", "named_subscriptions_unsupported", "invalid_filters",
+            // The server refuses the whole subscribe with these and sends NO ack.
+            "too_many_subscriptions", "invalid_sub_id", "unknown_sub_id"].includes(String(w.code))) {
+            // An already-started read cannot certify a revoked/invalid connection.
+            this.epoch++;
+            this.pendingBootstrap = false;
+            this.subscribed = false;
+            this.incomplete = true;
+            this.lastError = String(w.code);
+            this.phase = "degraded";
+            this.clearTimer();
+            this.markStale(this.plan.include);
+            this.emit();
+        }
+    }
+    onGap(value) {
+        if (this.phase === "stopped" || !value || typeof value !== "object")
+            return;
+        const gap = value;
+        const entries = gap.channels && typeof gap.channels === "object" ? Object.keys(gap.channels) : [];
+        const belongs = entries.length === 0 || entries.some(ch => ch.startsWith(this.opts.subId + "/") || (ch === this.opts.subId));
+        if (!belongs)
+            return;
+        this.gapUnresolved = true;
+        this.incomplete = true;
+        this.lastError = "stream_gap";
+        this.phase = "degraded";
+        this.markStale(this.plan.include);
+        // If the gap arrives during a REST fetch it must not let that fetch clear
+        // stale just because a frame did not increment the generation.
+        for (const m of this.plan.include)
+            this.gen.set(m, (this.gen.get(m) ?? 0) + 1);
+        // Snapshot resync is bounded, but not proof that missing historical events
+        // (KOL, executed trades) can be reconstructed. Keep incomplete=true.
+        if (this.subscribed) {
+            for (const m of this.plan.include)
+                this.dirty.add(m);
+            this.schedule(0);
+        }
+        this.emit();
+    }
+    onFrame(frame) {
+        if (!frame || this.phase === "stopped" || frame.sub_id !== this.opts.subId)
+            return;
+        const matches = rulesForEvent(frame, this.plan);
+        if (!matches.length)
+            return;
+        if (frame.id) {
+            const key = this.opts.subId + ":" + frame.channel + ":" + frame.id;
+            if (this.seen.has(key))
+                return;
+            this.seen.set(key, this.now());
+            if (this.seen.size > MAX_DEDUPE_IDS)
+                this.seen.delete(this.seen.keys().next().value);
+        }
+        for (const rule of matches) {
+            if (rule.delivery === "overlay") {
+                // State ticks carry no cursor; never let a late/replayed tick replace
+                // a newer overlay that is already on screen.
+                const prev = this.live[rule.module];
+                if (prev && typeof prev.ts === "number" && typeof frame.ts === "number" && frame.ts < prev.ts)
+                    continue;
+                this.live[rule.module] = frame;
+                try {
+                    this.opts.onLive?.(frame, rule.module);
+                }
+                catch { /* consumer */ }
+            }
+            else {
+                this.markStale([rule.module]);
+                this.dirty.add(rule.module);
+                // Only an INVALIDATION may make an in-flight read stale. An overlay tick
+                // supersedes the REST price on screen; counting it would re-read the
+                // snapshot module after every read on any actively traded token.
+                this.gen.set(rule.module, (this.gen.get(rule.module) ?? 0) + 1);
+            }
+        }
+        this.emit();
+        // A degraded view (visible gap, failed read) must keep refreshing its
+        // invalidated modules on a subscribed socket; schedule() refuses otherwise.
+        if ((this.phase === "live" || this.phase === "degraded") && this.dirty.size > 0)
+            this.schedule();
+    }
+    markStale(modules) {
+        for (const m of modules)
+            this.stale.add(m);
+    }
+    clearTimer() {
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    schedule(delay) {
+        if (this.phase === "stopped" || this.phase === "idle" || this.busy ||
+            (this.plan.channels.length > 0 && !this.subscribed))
+            return;
+        const now = this.now();
+        const minGap = this.opts.minModuleRefreshMs ?? 15_000;
+        // Wake when the FIRST dirty module is eligible; flush() skips the others
+        // until their own budget allows, then reschedules.
+        let earliest = Infinity;
+        for (const m of this.dirty)
+            earliest = Math.min(earliest, (this.lastRead.get(m) ?? -Infinity) + minGap - now);
+        if (!Number.isFinite(earliest))
+            earliest = 0;
+        const wait = Math.max(delay ?? (this.opts.debounceMs ?? 750), earliest, 0);
+        // A pending flush may only be moved EARLIER, never later. A trailing-edge
+        // debounce reset on every event can starve a hot mint forever when trades
+        // arrive faster than debounceMs, leaving token intelligence permanently stale.
+        if (this.timer !== null) {
+            if (now + wait >= this.timerAt)
+                return;
+            clearTimeout(this.timer);
+        }
+        this.timerAt = now + wait;
+        this.timer = setTimeout(() => { this.timer = null; void this.flush(); }, wait);
+    }
+    async flush() {
+        if (this.busy || this.phase === "stopped" || this.dirty.size === 0)
+            return;
+        if (this.plan.channels.length > 0 && !this.subscribed)
+            return;
+        const modules = [];
+        const now = this.now();
+        const minGap = this.opts.minModuleRefreshMs ?? 15_000;
+        let cost = 0;
+        for (const m of this.dirty) {
+            // Newer invalidations may join a timer that was scheduled for an older
+            // module. They must still honour their OWN per-module refresh budget.
+            if (now < (this.lastRead.get(m) ?? -Infinity) + minGap)
+                continue;
+            const next = TERMINAL_MODULE_COSTS[m];
+            if (modules.length >= 5 || cost + next > 8)
+                break;
+            modules.push(m);
+            cost += next;
+        }
+        if (!modules.length) {
+            this.schedule();
+            return;
+        }
+        for (const m of modules)
+            this.dirty.delete(m);
+        await this.fetchModules(modules, false);
+    }
+    async fetchModules(modules, initial) {
+        if (this.busy || this.phase === "stopped")
+            return;
+        this.busy = true;
+        // The initial ACK already put all modules in dirty. Consume that batch
+        // before the read; a new frame during I/O can add a fresh invalidation.
+        for (const m of modules)
+            this.dirty.delete(m);
+        const epoch = this.epoch;
+        const seen = new Map(modules.map(m => [m, this.gen.get(m) ?? 0]));
+        const now = this.now();
+        for (const m of modules)
+            this.lastRead.set(m, now);
+        try {
+            const incoming = await this.opts.read(modules);
+            if (this.isStopped() || epoch !== this.epoch)
+                return;
+            if (incoming.chain !== this.plan.chain ||
+                (this.plan.chain === "solana" ? incoming.address !== this.plan.address :
+                    incoming.address.toLowerCase() !== this.plan.address))
+                throw new Error("snapshot_identity_mismatch");
+            if (!incoming.modules || typeof incoming.modules !== "object")
+                throw new Error("invalid_snapshot_modules");
+            for (const m of modules)
+                if (!incoming.modules[m])
+                    throw new Error("missing_snapshot_module:" + m);
+            this.snapshot = this.snapshot && !initial
+                ? { ...incoming, modules: { ...this.snapshot.modules, ...incoming.modules } }
+                : incoming;
+            for (const m of modules) {
+                if ((this.gen.get(m) ?? 0) === seen.get(m))
+                    this.stale.delete(m);
+                else
+                    this.dirty.add(m);
+            }
+            this.lastError = null;
+            this.phase = this.incomplete ? "degraded" : "live";
+        }
+        catch (error) {
+            if (this.isStopped() || epoch !== this.epoch)
+                return;
+            this.lastError = error instanceof Error ? error.message : "snapshot_failed";
+            this.markStale(modules);
+            this.phase = "degraded";
+            // Do not automatically retry a failed DB/RPC call: the next event or an
+            // explicit refresh can trigger another, still rate-limited, request.
+        }
+        finally {
+            this.busy = false;
+            if (!this.isStopped()) {
+                this.emit();
+                if (this.pendingBootstrap && this.subscribed) {
+                    // A reconnect occurred while the old read was busy. Only the NEW
+                    // post-ACK full snapshot can establish a fresh baseline; a targeted
+                    // merge onto the old one is not sufficient.
+                    this.pendingBootstrap = false;
+                    void this.fetchModules(this.plan.include, true);
+                }
+                else if (this.dirty.size > 0 && this.subscribed) {
+                    this.schedule();
+                }
+            }
+        }
+    }
+}
+/** A named subscription prevents overwriting an integrator's other filters. */
+export function createTerminalTokenView(options) {
+    return new TerminalTokenView(options);
+}
+//# sourceMappingURL=terminal-watch.js.map

package/dist/terminal-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-watch.js","sourceRoot":"","sources":["../src/terminal-watch.ts"],"names":[],"mappings":"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"}

package/dist/terminal.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Solana terminal integration over existing REST + managed WebSocket (#534).
+ *
+ * A shared SDK socket is REQUIRED. We do not open a socket per token widget,
+ * and no REST module is refetched on every price tick. Each terminal must use
+ * its own explicit named subscription, and each disconnect/replay gap is visible.
+ *
+ * This adapter does NOT make the selected token's historical capture complete.
+ */
+import type { MadeOnSolREST } from "./index.js";
+import type { MadeOnSolStream } from "./stream.js";
+import type { TokenIntelligenceModuleId } from "./types.js";
+import { type TerminalStreamPort, type TerminalTokenView, type TerminalView, type TerminalStreamFrame } from "./terminal-watch.js";
+import type { TerminalTier, TerminalModule } from "./terminal-policy.js";
+export interface SolanaTerminalWatchOptions {
+    /** Caller-selected modules, obeying existing API budget (at most 5, cost <=8). */
+    include: readonly TokenIntelligenceModuleId[];
+    /** Account's current tier. Server still enforces its authoritative entitlement. */
+    tier: TerminalTier;
+    /** Reuse ONE existing client.stream() across terminal widgets. */
+    stream: MadeOnSolStream;
+    /** Unique per shared connection, 1..64 chars, A-Z a-z 0-9 _ . - */
+    subId: string;
+    /** Subscribe to global, unscoped KOL broadcasts (may be high bandwidth). */
+    includeKolBroadcast?: boolean;
+    /** Min interval between REST refreshes for any invalidated module. Default 15s. */
+    minModuleRefreshMs?: number;
+    debounceMs?: number;
+    /** Snapshot, stale module names, live overlays and historical gap status. */
+    onChange?: (view: TerminalView) => void;
+    onLive?: (frame: TerminalStreamFrame, module: TerminalModule) => void;
+}
+/**
+ * The existing stream's public `on` overloads use specific event signatures.
+ * Narrowly adapt those overloads to the small event-port used by the shared
+ * controller, without changing stream/client behavior.
+ *
+ * Exported for BROWSER terminals that must not hold an API key: pair it with
+ * `createTerminalTokenView({ stream: terminalStreamPort(stream), read })`, where
+ * `stream` gets its short-lived token from your backend (`getToken`) and `read`
+ * calls your backend, which calls the keyed intelligence endpoint.
+ */
+export declare function terminalStreamPort(stream: MadeOnSolStream): TerminalStreamPort;
+/** Creates an active, terminal-scoped view; returns a handle with dispose(). */
+export declare function createSolanaTerminalWatch(client: MadeOnSolREST, mint: string, options: SolanaTerminalWatchOptions): TerminalTokenView;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAA2B,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAC/E,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEzE,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,OAAO,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC9C,mFAAmF;IACnF,IAAI,EAAE,YAAY,CAAC;IACnB,kEAAkE;IAClE,MAAM,EAAE,eAAe,CAAC;IACxB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CACvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,kBAAkB,CAa9E;AAED,gFAAgF;AAChF,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,0BAA0B,GAClC,iBAAiB,CA2BnB"}