@rezless/vm 0.1.0

package/dist/script.d.ts

@@ -0,0 +1,248 @@
+import type { Script as Ast } from '@rezless/parser';
+import type { BuiltinImpl, ChatEntry, CallEntry } from './runtime.js';
+import type { HttpRequestEntry } from './builtins/http.js';
+import type { ListenEntry } from './builtins/listen.js';
+import type { LinkedMessageEntry } from './builtins/linked.js';
+import type { DataserverRequestEntry } from './builtins/dataserver.js';
+import type { LinksetDataEntry } from './builtins/linksetdata.js';
+import type { CoverageReport } from './coverage.js';
+import type { LslType, LslValue } from './values/types.js';
+import { ScriptClockView } from './clock.js';
+import { Linkset } from './linkset.js';
+import { Prim } from './prim.js';
+export interface ScriptOptions {
+    /** Filename used in diagnostics; defaults to "<inline>". */
+    readonly filename?: string;
+    /**
+     * Seed for the script's PRNG (used by llFrand and friends). Default 1.
+     * Pin a seed per test if you need deterministic random output.
+     */
+    readonly randomSeed?: number;
+    /** Owner key returned by llGetOwner. Defaults to NULL_KEY. */
+    readonly owner?: string;
+    /** Prim key returned by llGetKey. Defaults to a deterministic per-script key. */
+    readonly objectKey?: string;
+    /** Prim name returned by llGetObjectName. Defaults to "Object". */
+    readonly objectName?: string;
+    /** Script name returned by llGetScriptName. Defaults to filename basename or "script". */
+    readonly scriptName?: string;
+    /**
+     * Host prim. If omitted, a 1-prim default linkset is auto-allocated. Pass
+     * a prim that's already been added to a Linkset to opt into multi-script.
+     */
+    readonly host?: Prim;
+    /**
+     * Original LSL source — kept on the script for LCOV / Istanbul line maps
+     * when coverage is enabled. loadScript() supplies this automatically.
+     */
+    readonly source?: string;
+    /**
+     * Enable coverage collection on this script. When true, `script.coverage`
+     * returns a snapshot after each test; default false (zero overhead).
+     */
+    readonly coverage?: boolean;
+}
+/**
+ * Public handle for a loaded LSL script. Tests interact almost entirely
+ * with this surface: drive events via fire(), inspect chat / calls,
+ * override functions via mock(), read or seed globals.
+ */
+export declare class Script {
+    private readonly ast;
+    private readonly state;
+    private readonly mocks;
+    private readonly globals;
+    private readonly userFunctions;
+    private readonly handlersByState;
+    private started;
+    /** Per-script clock facade (timer state + time reference). */
+    readonly clockView: ScriptClockView;
+    readonly host: Prim;
+    readonly linkset: Linkset;
+    readonly scriptName: string;
+    /** When false, drainQueue parks events instead of delivering them. */
+    running: boolean;
+    /** Events parked while `running === false`; replayed when re-enabled. */
+    readonly parkedEvents: Array<{
+        at: number;
+        event: string;
+        payload: Record<string, unknown>;
+    }>;
+    constructor(ast: Ast, options?: ScriptOptions);
+    /** Current virtual time in milliseconds since linkset construction. */
+    get now(): number;
+    /**
+     * Advance the linkset clock by `ms` and fire every queued event whose
+     * scheduled time is ≤ the new now (across all scripts in the linkset).
+     * Convenience pass-through to `linkset.advanceTime`.
+     */
+    advanceTime(ms: number): void;
+    /**
+     * Configured recurring timer interval in seconds, or 0 if no timer is
+     * registered. Mirrors `llSetTimerEvent`'s most recent argument.
+     */
+    get timerInterval(): number;
+    /** Current LSL state name. */
+    get currentState(): string;
+    /**
+     * Coverage report snapshot, or null when coverage is disabled. Each call
+     * returns a fresh frozen object — safe to retain across further fire()s
+     * without seeing later mutations.
+     */
+    get coverage(): CoverageReport | null;
+    /** Captured chat output (llSay/llShout/llWhisper/llOwnerSay/...). */
+    get chat(): ReadonlyArray<ChatEntry>;
+    /** Universal log of every ll* call this script has made. Filter with callsOf(name). */
+    get calls(): ReadonlyArray<CallEntry>;
+    /** Filtered call log: only entries for `name`. */
+    callsOf(name: string): ReadonlyArray<CallEntry>;
+    /** Captured outgoing HTTP requests from `llHTTPRequest`. */
+    get httpRequests(): ReadonlyArray<HttpRequestEntry>;
+    /**
+     * Feed a response to a previously captured HTTP request. Schedules an
+     * `http_response` event for immediate delivery.
+     */
+    respondToHttp(key: string, response: {
+        status: number;
+        body?: string;
+        metadata?: ReadonlyArray<unknown>;
+    }): void;
+    /** Convenience: respond to the most recent HTTP request. */
+    respondToLastHttp(response: {
+        status: number;
+        body?: string;
+        metadata?: ReadonlyArray<unknown>;
+    }): void;
+    /** Currently active listen registrations (from `llListen`). */
+    get listens(): ReadonlyArray<ListenEntry>;
+    /** Captured llMessageLinked invocations originating from this script. */
+    get linkedMessages(): ReadonlyArray<LinkedMessageEntry>;
+    /** Drop every captured outgoing linked-message entry for this script. */
+    clearLinkedMessages(): void;
+    /** Captured pending dataserver requests (llRequestAgentData and friends). */
+    get dataserverRequests(): ReadonlyArray<DataserverRequestEntry>;
+    /**
+     * Feed a value back to a pending dataserver request. Schedules a
+     * `dataserver` event with the request key and a string value.
+     */
+    respondToDataserver(key: string, value: string): void;
+    /** Convenience: respond to the most recent dataserver request. */
+    respondToLastDataserver(value: string): void;
+    /** Currently displayed floating text (from llSetText). null if unset. */
+    get text(): {
+        text: string;
+        color: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        alpha: number;
+    } | null;
+    /** Object description from llSetObjectDesc. */
+    get objectDesc(): string;
+    /**
+     * Read-only view of the Linkset Data store. Tests can iterate to assert on
+     * keys / values / protection. Modify via the LSL builtins or seedLinksetData.
+     */
+    get linksetData(): ReadonlyMap<string, LinksetDataEntry>;
+    /**
+     * White-box helper: pre-populate the Linkset Data store without going
+     * through llLinksetDataWrite. Does not fire linkset_data events.
+     */
+    seedLinksetData(entries: Iterable<readonly [string, {
+        value: string;
+        password?: string;
+    }]>): void;
+    /** True once `llDie()` has been called. Subsequent fire() calls are no-ops. */
+    get dead(): boolean;
+    /**
+     * Match chat against this script's listens and queue `listen` events for
+     * every match. Does not drain — caller does that. Used by Linkset.deliverChat
+     * for cross-script delivery.
+     */
+    matchChatListens(opts: {
+        channel: number;
+        name: string;
+        key: string;
+        message: string;
+    }): void;
+    /**
+     * Deliver chat to this script only. Linkset-wide delivery (every listening
+     * script in the linkset) is `linkset.deliverChat`.
+     */
+    deliverChat(opts: {
+        channel: number;
+        name: string;
+        key: string;
+        message: string;
+    }): void;
+    /**
+     * Override an `ll*` function for the lifetime of this Script. Replaces
+     * any built-in or stub of the same name.
+     */
+    mock(name: string, impl: BuiltinImpl): void;
+    /** Read a global variable's current value. White-box hook for tests. */
+    global(name: string): LslValue;
+    /** Seed a global variable. The value is coerced to the global's declared type. */
+    setGlobal(name: string, value: LslValue, type?: LslType): void;
+    /**
+     * Drive an event into the current state.
+     *
+     * `payload` is keyed by the event's documented parameter names (per kwdb).
+     * The handler's declared parameters bind by position to the event spec, so
+     * the user's chosen names don't have to match.
+     *
+     * Synchronous: runs the handler to completion before returning, including
+     * any state transitions triggered by `state foo;` (state_exit / change /
+     * state_entry chain runs before fire() returns).
+     *
+     * If the current state has no handler for `eventName`, this is a no-op
+     * — matches LSL behavior of silently dropping unhandled events.
+     */
+    fire(eventName: string, payload?: Record<string, unknown>): void;
+    /**
+     * Run state_entry of the default state. If the script has been auto-started
+     * (e.g. by an earlier fire), this is a no-op.
+     */
+    start(): void;
+    /**
+     * Reset the script as if `llResetScript` had been called: clear globals,
+     * reseed them from the AST initializers, return to the default state,
+     * cancel timers, and run state_entry. Used internally when llResetScript
+     * is invoked from inside a handler; tests can also call it directly.
+     */
+    reset(): void;
+    /**
+     * Internal: invoked by `Linkset.drainQueue` to deliver one queued event.
+     * The synthetic `__reset` event triggers a sibling-initiated reset
+     * (scheduled by `llResetOtherScript`).
+     */
+    deliver(event: string, payload: Record<string, unknown>): void;
+    /**
+     * Push a detected context (if the payload includes `detected`) for the
+     * duration of `fn`, so llDetectedKey / Name / Pos / etc. inside the
+     * handler resolve to the right entries.
+     */
+    private withDetected;
+    /**
+     * Run a handler and process any state-change signal it raises.
+     *
+     * LSL semantics: when a handler executes `state foo;`, control leaves the
+     * handler immediately, the current state's `state_exit` fires, the state
+     * changes, then the new state's `state_entry` fires. We mirror that here
+     * with a small loop so that a `state_exit` or `state_entry` that itself
+     * does `state foo;` continues the chain correctly.
+     */
+    private runHandler;
+    /**
+     * Mark this script as dead and cancel its timer. Used by llDie to bring
+     * down every script in the linkset. Idempotent.
+     */
+    markDead(): void;
+    /**
+     * Replay any events parked while this script was disabled. Caller is
+     * responsible for advancing the linkset clock if needed afterwards.
+     */
+    resumeParked(): void;
+}
+//# sourceMappingURL=script.d.ts.map

package/dist/script.d.ts.map

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