@s2script/sdk 0.4.0 → 0.5.1

package/plugin.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @s2script/sdk/plugin — the typed plugin artifact: `plugin(factory)`, the load-scoped `PluginContext`,
+ * and `Scope`. NO runtime code: the engine injects the implementation at load time
+ * (`__s2pkg_plugin`, resolved via the existing `@s2script/sdk/*` prefix strip).
+ *
+ * See docs/superpowers/specs/2026-07-20-L1-lifecycle-v2-design.md §1-§3 for the full contract.
+ */
+import type { GameEvent, HookResultValue } from "./events";
+import type { Client } from "./clients";
+import type { EntityRef, OutputEvent } from "./entity";
+import type { DamageInfo } from "./damage";
+import type { CommandInvocation } from "./commands";
+import type { Config } from "./config";
+import type { PublishHandle } from "./interfaces";
+import type { TopMenuItem } from "./topmenu";
+import type { PrecacheContext } from "./sound";
+import type { UserCmdView } from "./usercmd";
+
+/** Game-event subscriptions on this plugin's load-scope ({@link PluginContext.events}). */
+export interface CtxEvents {
+  /**
+   * Subscribe to a fired game event (post-phase). The {@link GameEvent} is valid only synchronously.
+   * @example
+   * // plugins/disabled/nextmap/src/plugin.ts:133
+   * ctx.events.on("round_end", () => console.log("round ended"));
+   */
+  on(name: string, handler: (ev: GameEvent) => void): void;
+  /** Pre-hook a game event: return a {@link HookResultValue} (`Handled`/`Stop` suppress the client broadcast). */
+  onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
+}
+/**
+ * Handlers fire for clients that connect AFTER Active. To cover already-connected clients, seed
+ * explicitly in the factory: `for (const c of Clients.all()) { … }` — there is no framework
+ * replay (replaying `onConnect` for pre-existing clients would fire auth/ban/reservation logic
+ * out of its real order).
+ */
+export interface CtxClients {
+  /** A client began connecting (pre-auth). */
+  onConnect(handler: (client: Client) => void | Promise<void>): void;
+  /** A client's entity was put in the server (`ClientPutInServer`). */
+  onPutInServer(handler: (client: Client) => void | Promise<void>): void;
+  /** A client became fully active (in-game, receiving snapshots). */
+  onActive(handler: (client: Client) => void | Promise<void>): void;
+  /** A client finished authenticating (Steam ticket validated). */
+  onFullyConnect(handler: (client: Client) => void | Promise<void>): void;
+  /** A client disconnected. */
+  onDisconnect(handler: (client: Client) => void): void;
+  /** A client's convars/settings changed (`ClientSettingsChanged`). */
+  onSettingsChanged(handler: (client: Client) => void): void;
+  /** A client sent a voice packet (per-frame while speaking). */
+  onVoice(handler: (client: Client) => void): void;
+  /** A client's persisted cookies finished loading and are now readable. */
+  onCookiesCached(handler: (client: Client) => void): void;
+  /** A client sent chat: return a {@link HookResultValue} to suppress it. @param teamonly - team-channel say. */
+  onSay(handler: (slot: number, text: string, teamonly: boolean) => HookResultValue | void): void;
+  /** Per-tick usercmd hook (SM `OnPlayerRunCmd`): read/modify {@link UserCmdView}; return `Handled` to block the tick. */
+  onRunCmd(handler: (cmd: UserCmdView, info: { slot: number }) => HookResultValue | void): void;
+}
+/** Entity lifecycle + damage subscriptions on this plugin's load-scope ({@link PluginContext.entities}). */
+export interface CtxEntities {
+  /** An entity of `className` was created (not yet spawned). @param className - match, or `"*"` for all. */
+  onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** An entity of `className` spawned (post-`DispatchSpawn`). */
+  onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** An entity of `className` is being deleted; the ref goes stale right after. */
+  onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  /** Hook a named entity output (`FireOutputInternal`); return a {@link HookResultValue} to suppress it. */
+  onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
+  /**
+   * Damage pre-hook (SDKHooks-equivalent): read/modify {@link DamageInfo}; return `Handled` semantics via `info`.
+   * @example
+   * // plugins/basecommands/src/plugin.ts:81 — halve incoming damage
+   * ctx.entities.onDamage((info) => { info.damage = info.damage / 2; });
+   */
+  onDamage(handler: (info: DamageInfo) => HookResultValue | void): void;
+}
+/** Per-frame + map/precache hooks on this plugin's load-scope ({@link PluginContext.server}). */
+export interface CtxServer {
+  /** Run `fn` every game frame. @param opts - `priority` orders it within the frame (`monitor` runs last, read-only). */
+  onGameFrame(fn: () => void, opts?: { priority?: "high" | "normal" | "low" | "monitor" }): void;
+  /** A new map became live; `mapName` is the BSP name. */
+  onMapStart(handler: (mapName: string) => void): void;
+  /** Precache window — register models/sounds to precache for the current map. */
+  onPrecache(handler: (pc: PrecacheContext) => void): void;
+}
+/** Console/chat command registration on this plugin's load-scope ({@link PluginContext.commands}). */
+export interface CtxCommands {
+  /** Register a public command (any client may run it). */
+  register(name: string, handler: (cmd: CommandInvocation) => void): void;
+  /** Register a server-only command (console/rcon, not client-runnable). */
+  registerServer(name: string, handler: (cmd: CommandInvocation) => void): void;
+  /** Register an admin command gated by `flags` (an `ADMFLAG` bitmask; fail-safe default-deny). */
+  registerAdmin(name: string, flags: number, handler: (cmd: CommandInvocation) => void): void;
+}
+/** Config live-reload subscription on this plugin's load-scope ({@link PluginContext.config}). */
+export interface CtxConfig {
+  /** Fires when the plugin's config file is re-materialized on disk; re-read values inside. */
+  onChange(handler: (cfg: Config) => void): void;
+}
+/** TopMenu (adminmenu) contribution on this plugin's load-scope ({@link PluginContext.topmenu}). */
+export interface CtxTopMenu {
+  /** Add (or reuse) a top-level menu category. */
+  addCategory(name: string): void;
+  /** Add an item under an existing category. */
+  addItem(category: string, item: TopMenuItem): void;
+}
+
+/** A producer-backed inter-plugin interface: its methods, plus forward subscriptions. */
+export type InterfaceHandle<T extends object> = T & {
+  /** Subscribe to a producer forward. Load-window only (buffered, armed at Active) — like every registration. */
+  on(event: string, handler: (payload: any) => void): void;
+};
+
+/**
+ * A disposable bundle of subscriptions ({@link PluginContext.createScope}). Registering through a scope
+ * lets you drop the whole group at once with {@link Scope.clear} without unloading the plugin.
+ */
+export interface Scope {
+  /** Game-event subscriptions bound to this scope. */
+  readonly events: CtxEvents;
+  /** Client-lifecycle subscriptions bound to this scope. */
+  readonly clients: CtxClients;
+  /** Entity/damage subscriptions bound to this scope. */
+  readonly entities: CtxEntities;
+  /** Per-frame/map subscriptions bound to this scope. */
+  readonly server: CtxServer;
+  /** Remove every subscription this scope holds; the scope stays usable (re-register on next open). */
+  clear(): void;
+  /** clear() + permanently retire the scope. Idempotent. */
+  dispose(): void;
+  /** True once {@link Scope.dispose} has run. */
+  readonly disposed: boolean;
+}
+
+/**
+ * The load-scoped context passed to a plugin's {@link PluginFactory}. Its sub-objects register every
+ * subscription; all registration is load-window only (buffered, armed at Active).
+ */
+export interface PluginContext {
+  /** This plugin's id (manifest `id`). */
+  readonly id: string;
+  /** The revived hot-reload handoff (the previous instance's `state()` return), or undefined. */
+  readonly previous: unknown;
+  /** Game-event subscriptions ({@link CtxEvents}). */
+  readonly events: CtxEvents;
+  /** Client-lifecycle subscriptions ({@link CtxClients}). */
+  readonly clients: CtxClients;
+  /** Entity/damage subscriptions ({@link CtxEntities}). */
+  readonly entities: CtxEntities;
+  /** Per-frame/map/precache subscriptions ({@link CtxServer}). */
+  readonly server: CtxServer;
+  /** Console/chat command registration ({@link CtxCommands}). */
+  readonly commands: CtxCommands;
+  /** Config live-reload subscription ({@link CtxConfig}). */
+  readonly config: CtxConfig;
+  /** TopMenu (adminmenu) contribution ({@link CtxTopMenu}). */
+  readonly topmenu: CtxTopMenu;
+  /** Publish this plugin's manifest-declared interface. Buffered; goes live at Active. */
+  publish<T extends object>(name: string, impl: T): PublishHandle;
+  /** Resolve a HARD dep (must be in `pluginDependencies`). Immediate — the proxy is callable inside the factory. */
+  use<T extends object>(name: string): InterfaceHandle<T>;
+  /** Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished. */
+  tryUse<T extends object>(name: string): InterfaceHandle<T> | null;
+  /** Allocate a disposable subscription scope (load-window only — the capability originates at load). */
+  createScope(): Scope;
+}
+
+/** Optional lifecycle hooks a {@link PluginFactory} may return to participate in unload + hot-reload. */
+export interface PluginHooks {
+  /** Best-effort cleanup at unload (the ledger remains the teardown authority). */
+  onUnload?(): void;
+  /** Hot-reload handoff capture; JSON-serialized (EntityRef-aware) and revived as the next instance's ctx.previous. */
+  state?(): unknown;
+}
+/**
+ * A plugin's body: called once at load with the {@link PluginContext}, optionally returning
+ * {@link PluginHooks}. May be async (the load waits for it to settle).
+ */
+export type PluginFactory = (ctx: PluginContext) => void | PluginHooks | Promise<void | PluginHooks>;
+/** The opaque artifact {@link plugin} returns; a module must `export default` it to be a valid plugin. */
+export interface PluginDefinition {
+  /** Brand tag proving this object came from {@link plugin} (host-checked at load). */
+  readonly __s2plugin: 1;
+}
+/**
+ * Define a plugin from its factory. `export default` the result — the host calls the factory once at load.
+ * @example
+ * import { plugin } from "@s2script/sdk/plugin";
+ * // examples/greeter-plugin/src/plugin.ts:8
+ * export default plugin((ctx) => {
+ *   const handle = ctx.publish("@demo/greeter", impl);
+ *   ctx.server.onGameFrame(() => handle.emit("greeted", { slot: 0 }));
+ * });
+ */
+export declare function plugin(factory: PluginFactory): PluginDefinition;

package/plugins.d.ts

@@ -1,10 +1,29 @@
 /** @s2script/plugins — runtime plugin management (the SM `sm plugins` backend). NO runtime code (injected). */
+
+/** A snapshot of one plugin's identity and lifecycle state, as returned by {@link Plugins.list}. */
 export interface PluginInfo {
   /** the plugin id (from its manifest). */
   readonly id: string;
-  /** true = running; false = manually unloaded (on disk but not running, via `unload`). */
+  /** true = running; false = not running (loading, waiting, failed, or manually unloaded). Exactly
+   * `state === "running"`. */
   readonly loaded: boolean;
+  /** the plugin's lifecycle state (L1 lifecycle v2):
+   * - `"running"`  — Active (factory settled, armed).
+   * - `"loading"`  — an in-flight factory load (async factory not yet settled).
+   * - `"waiting"`  — parked until a hard-dependency producer is published (or a ~30s timeout).
+   * - `"failed"`   — the load failed (bad artifact, throwing/rejecting factory, publishes mismatch,
+   *                  or a load timeout); the plugin is NOT running.
+   * - `"unloaded"` — on disk but manually unloaded via `unload` (not auto-reloaded until `load`/`reload`).
+   */
+  readonly state: "running" | "loading" | "waiting" | "failed" | "unloaded";
 }
+/**
+ * Enumerate and drive the plugin set at runtime (list / load / unload / reload).
+ * @example
+ * import { Plugins } from "@s2script/sdk/plugins";
+ * // plugins/basecommands/src/plugin.ts:126 — sm plugins list
+ * for (const p of Plugins.list()) cmd.reply(p.id + " — " + p.state);
+ */
 export declare const Plugins: {
   /** Every loaded/unloaded plugin. */
   list(): PluginInfo[];

package/server.d.ts

@@ -1,4 +1,12 @@
 /** @s2script/server — server control (run console commands, query map validity). NO runtime code (injected at load). */
+
+/**
+ * Server console + globals: run commands, register/read/set cvars, and query map/time state.
+ * @example
+ * import { Server } from "@s2script/sdk/server";
+ * // plugins/basecommands/src/plugin.ts:46 — sm_map
+ * Server.command("changelevel " + map);
+ */
 export declare const Server: {
   /** Run `cmd` at the server console (queued; executes next frame). */
   command(cmd: string): void;
@@ -27,13 +35,6 @@ export declare const Server: {
     min?: number;
     max?: number;
   }): boolean;
-  /**
-   * Subscribe to map start (fires on every server map startup — the framework event that replaces
-   * polling `Server.mapName` on OnGameFrame). Boot-loaded plugins receive the first map's fire;
-   * a plugin hot-loaded mid-map does NOT get a synthetic fire for the current map — read
-   * `Server.mapName` at load. Torn down automatically on plugin unload.
-   */
-  onMapStart(handler: (mapName: string) => void): void;
   /** The server's configured max client count (`GetMaxClients()`). `0` if unavailable. */
   readonly maxPlayers: number;
   /** The current map name (`GetMapName()`, the BSP). `""` if unavailable. */

package/sound.d.ts

@@ -1,6 +1,7 @@
 /** @s2script/sound — engine-generic sound: emit a named SoundEvent + register custom precache paths. */
 import type { EntityRef } from "./entity";
 
+/** Options for {@link Sound.emit} — the source entity, recipient slots, and volume. */
 export interface SoundEmitOptions {
   /** Source entity (serial-gated; a stale ref emits nothing and returns 0). Omitted -> worldspawn
    *  (a global/2D sound). */
@@ -22,14 +23,18 @@ export interface PrecacheContext {
   add(path: string): boolean;
 }
 
+/**
+ * Engine-generic sound entry point — play a named SoundEvent to some or all clients.
+ * @example
+ * import { Sound } from "@s2script/sdk/sound";
+ * // global 2D broadcast to every valid client (worldspawn source):
+ * const guid = Sound.emit("MyPack.Ping");
+ * if (guid === 0) console.log("emit failed (unresolved name / stale source)");
+ */
 export declare const Sound: {
   /** Play a named SoundEvent (the engine resolves name->hash; built-in soundevents need no
    *  precache). Returns the engine sound GUID (nonzero) or 0 on failure (unresolved engine
    *  function / stale source entity / an empty `recipients` array). An all-bot-skipped recipient
    *  set still emits to nobody (a real engine call, may return a nonzero GUID). */
   emit(name: string, opts?: SoundEmitOptions): number;
-  /** Subscribe to the session resource-manifest build (fires at map load / mapchange). Register
-   *  custom .vsndevts/.vsnd content here so a later emit can play it. A plugin hot-loaded mid-map
-   *  gets its first fire at the NEXT map change. */
-  onPrecache(handler: (ctx: PrecacheContext) => void): void;
 };

package/timers.d.ts

@@ -3,7 +3,13 @@
  * NO runtime code: the engine injects the implementation at load time.
  */
 
-/** Await a delay of `ms` milliseconds before continuing. */
+/**
+ * Await a delay of `ms` milliseconds before continuing. Tick-integrated (resumes on a game frame).
+ * @example
+ * import { delay } from "@s2script/sdk/timers";
+ * // plugins/funcommands/src/plugin.ts:77 — sm_freeze auto-unfreeze after `secs`
+ * delay(secs * 1000).then(() => { const q = Player.fromSlot(slot); if (q && q.pawn) q.pawn.moveType = WALK; });
+ */
 export declare function delay(ms: number): Promise<void>;
 /** Yield to the next microtick. */
 export declare function nextTick(): Promise<void>;

package/topmenu.d.ts

@@ -1,4 +1,6 @@
 /** @s2script/topmenu — the extensible admin/top menu registry. NO runtime code (injected at load). */
+
+/** A single registered top-menu entry (an admin command surfaced in the adminmenu). */
 export interface TopMenuItem {
   /** Plugin-namespaced unique id, e.g. "playercommands:slap". A duplicate id replaces. */
   id: string;
@@ -9,15 +11,24 @@ export interface TopMenuItem {
   /** Runs in THIS plugin's context when an admin selects the item; receives the admin's 0-based slot. */
   onSelect: (adminSlot: number) => void;
 }
+/** A handler-free copy of the whole registry — what a menu renderer reads to build the display. */
 export interface TopMenuSnapshot {
+  /** All category names, in registration order. */
   categories: string[];
+  /** Every registered item's metadata (no `onSelect`), tagged with its category. */
   items: { id: string; category: string; name: string; flags: number }[];
 }
+/**
+ * The shared admin/top-menu registry — renderers read {@link TopMenu.snapshot} and dispatch picks
+ * through {@link TopMenu.select}; items are contributed by plugins via their own ctx.topmenu.
+ * @example
+ * import { TopMenu } from "@s2script/sdk/topmenu";
+ * const snap = TopMenu.snapshot();
+ * for (const cat of snap.categories) renderCategory(cat);
+ * // when the admin picks an item id, dispatch it back to its owner plugin:
+ * m.onSelect(e => { TopMenu.select(e.info, slot); });
+ */
 export declare const TopMenu: {
-  /** Register a category (idempotent; order = first-registration order). */
-  addCategory(name: string): void;
-  /** Register/replace an item under a category (auto-creates the category). */
-  addItem(category: string, item: TopMenuItem): void;
   /** All categories + item metadata (no handlers) — the adminmenu renderer reads this. */
   snapshot(): TopMenuSnapshot;
   /** Fire an item's onSelect (dispatched post-frame to the owner's context). */

package/trace.d.ts

@@ -57,6 +57,14 @@ export interface TraceOptions {
   ignoreEntity?: EntityRef;
 }
 
+/**
+ * Ray-tracing entry point — `line`/`ray`/`hull` traces over the Source 2 physics scene.
+ * @example
+ * import { Trace } from "@s2script/sdk/trace";
+ * import { Vector } from "@s2script/sdk/math";
+ * const down = Trace.line(new Vector(o.x, o.y, o.z + 500), new Vector(o.x, o.y, o.z - 100));
+ * if (down.didHit) console.log(down.fraction, down.endPos);
+ */
 export declare const Trace: {
   /** A line trace from `start` to `end`. */
   line(start: Vector, end: Vector, opts?: TraceOptions): TraceHit;

package/translations.d.ts

@@ -1,5 +1,15 @@
 /** @s2script/translations — SourceMod-style i18n (per-client language, phrase files, {1} formatting). */
+
+/** A phrase set: key → template string, where `{1}`/`{2}`/… are positional substitution slots. */
 export type Phrases = Record<string, string>;
+/**
+ * SourceMod-style translation registry: seed a default phrase set, override it per language from
+ * `translations/<code>/<name>.phrases.json`, then translate a key for a given client's language.
+ * @example
+ * import { Translations } from "@s2script/sdk/translations";
+ * Translations.load("trdemo", { Greeting: "Hello {1}", Bye: "Goodbye {1}" });
+ * console.log(Translations.translate(-1, "Greeting", "world")); // "Hello world"
+ */
 export declare const Translations: {
   /** Register a phrase set: `seed` is the built-in English default; translations/<code>/<name>.phrases.json overrides per language. */
   load(name: string, seed: Phrases): void;

package/transmit.d.ts

@@ -3,6 +3,7 @@
  *  engine-side hook enforces it every snapshot — zero JS runs in the per-client hot path. */
 import type { EntityRef } from "./entity";
 
+/** Hot-path measurement counters returned by {@link Transmit.stats}. */
 export interface TransmitStats {
   /** CheckTransmit invocations observed since load/reset. */
   snapshots: number;
@@ -16,6 +17,13 @@ export interface TransmitStats {
   nsMax: number;
 }
 
+/**
+ * Declarative per-client entity visibility: hide an entity from some viewers, enforced engine-side each snapshot.
+ * @example
+ * import { Transmit } from "@s2script/sdk/transmit";
+ * // examples/transmit-demo/src/plugin.ts:58 — show `prop` ONLY to one viewer slot
+ * const ok = Transmit.setVisibleTo(prop, [slot]);
+ */
 export declare const Transmit: {
   /** Replace this plugin's visibility rule for `entity`: it is transmitted ONLY to the given viewer
    *  slots (an empty array = hidden from everyone). Multiple plugins AND-merge — an entity reaches a

package/usercmd.d.ts

@@ -5,14 +5,20 @@
  * Source2-shared concept (`usercmd.proto`), so this module is engine-generic.
  */
 import type { QAngle } from "./math";
-import type { HookResultValue } from "./events";
 
 /**
- * A block-scoped view of the CURRENT tick's usercmd (valid only during a `UserCmd.onRun` handler —
- * a stashed `Cmd` used after the handler returns, or across an `await`, reads/writes nothing).
- * There is exactly ONE `Cmd` instance for the whole process; every handler call operates on it.
+ * A block-scoped view of the CURRENT tick's usercmd (valid only during a `ctx.clients.onRunCmd`
+ * handler — a stashed `UserCmdView` used after the handler returns, or across an `await`,
+ * reads/writes nothing). There is exactly ONE `UserCmdView` instance for the whole process; every
+ * handler call operates on it.
+ * @example
+ * import type { UserCmdView } from "@s2script/sdk/usercmd";
+ * // examples/usercmd-demo/src/plugin.ts:21 — read this tick's input
+ * ctx.clients.onRunCmd((cmd: UserCmdView, info: { slot: number }) => {
+ *   console.log(`slot=${info.slot} fwd=${cmd.forwardMove} btn=${cmd.buttons}`);
+ * });
  */
-export interface Cmd {
+export interface UserCmdView {
   /** +forward / -back. Normalized to roughly [-1, 1] (not the legacy ±450 units). */
   forwardMove: number;
   /**
@@ -36,16 +42,3 @@ export interface Cmd {
    */
   clearSubtickMoves(): void;
 }
-
-export declare const UserCmd: {
-  /**
-   * Subscribe to the per-tick input hook. The handler runs SYNCHRONOUSLY during the engine's
-   * usercmd processing, once per player per batched tick; `cmd` is the singleton, block-scoped
-   * current usercmd and `ctx.slot` is the firing player's 0-based slot.
-   *
-   * Return a `HookResultValue >= Handled` to SUPPRESS this tick's input (the game processes a
-   * zeroed/idle command instead); return `Continue`/`undefined` to let the (possibly modified)
-   * command through unblocked.
-   */
-  onRun(handler: (cmd: Cmd, ctx: { slot: number }) => HookResultValue | void): void;
-};

package/usermessages.d.ts

@@ -3,9 +3,13 @@ import type { HookResultValue } from "./events";
 /** A general protobuf user-message builder. Build then send in one synchronous burst. */
 export class UserMessage {
   constructor(name: string);
+  /** Set an integer field. Returns `this` for chaining. */
   setInt(field: string, value: number): this;
+  /** Set a float field. Returns `this` for chaining. */
   setFloat(field: string, value: number): this;
+  /** Set a string field. Returns `this` for chaining. */
   setString(field: string, value: string): this;
+  /** Set a boolean field. Returns `this` for chaining. */
   setBool(field: string, value: boolean): this;
   /** Infer the setter from the JS value type. */
   set(field: string, value: number | string | boolean): this;
@@ -28,15 +32,29 @@ export interface UserMessageView {
   readonly recipients: number[];
   /** protobuf TextFormat dump — the documented FALLBACK for unmapped messages only; prefer typed reads. */
   readonly debugString: string;
+  /** Whether `path` is present on the current message. Dotted nested paths supported ("origin.x"). */
   hasField(path: string): boolean;
   /** Scalar int read (int32/uint32/fixed32/enum; bool as 0/1). Dotted nested paths supported
    *  ("origin.x" walks sub-messages). null = no such field / repeated / no current message. */
   readInt(path: string): number | null;
+  /** Scalar float read (float/double). Dotted nested paths supported. null if absent/repeated/no message. */
   readFloat(path: string): number | null;
+  /** Scalar bool read. Dotted nested paths supported. null if absent/repeated/no message. */
   readBool(path: string): boolean | null;
+  /** Scalar string/bytes read. Dotted nested paths supported. null if absent/repeated/no message. */
   readString(path: string): string | null;
 }
 
+/**
+ * Intercept outbound user messages before delivery (read typed fields, optionally suppress the send).
+ * @example
+ * import { UserMessages } from "@s2script/sdk/usermessages";
+ * import { HookResult, type HookResultValue } from "@s2script/sdk/events";
+ * // examples/usermsg-demo/src/plugin.ts:15 — blanket-block radio text
+ * UserMessages.onPre("CCSUsrMsg_RadioText", (m): HookResultValue | void => {
+ *   if (blockRadio) return HookResult.Handled;
+ * });
+ */
 export declare const UserMessages: {
   /** Pre-hook an outbound user message by unscoped name (partial match, SayText2-style; the view
    *  carries the canonical name). Runs SYNCHRONOUSLY before delivery. Return >= HookResult.Handled

package/votes.d.ts

@@ -1,6 +1,17 @@
 /** @s2script/votes — chat-ballot voting with revote + an optional live center tally. NO runtime code (injected at load). */
-export interface VoteResult { readonly winner: number | null; readonly counts: number[]; readonly total: number; }
+
+/** The outcome delivered to {@link VoteConfig.onEnd} when a vote ends. */
+export interface VoteResult {
+  /** 0-based index of the winning option, or null on a tie or zero votes. */
+  readonly winner: number | null;
+  /** Per-option vote counts, parallel to {@link VoteConfig.options}. */
+  readonly counts: number[];
+  /** Total votes cast. */
+  readonly total: number;
+}
+/** Configuration for {@link Vote.start}. */
 export interface VoteConfig {
+  /** The question shown to voters. */
   question: string;
   /** 2..9 options (chat votes are single-digit). */
   options: string[];
@@ -8,13 +19,45 @@ export interface VoteConfig {
   duration: number;
   /** show a live center tally (default false — the SM chat-only way). */
   showLiveTally?: boolean;
+  /** Called once when the vote ends (or is exhausted), with the tallied {@link VoteResult}. It may start a new vote (the lock is released first). */
   onEnd: (result: VoteResult) => void;
 }
-export interface VoteTally { question: string; options: { label: string; count: number }[]; total: number; secondsLeft: number; }
-export interface VoteTallyRenderer { show(slot: number, tally: VoteTally): void; clear(slot: number): void; }
+/** A per-tick snapshot of an in-progress vote, handed to a {@link VoteTallyRenderer}. */
+export interface VoteTally {
+  /** The question being voted on. */
+  question: string;
+  /** Each option's label and current vote count. */
+  options: { label: string; count: number }[];
+  /** Total votes cast so far. */
+  total: number;
+  /** Seconds remaining before the vote ends. */
+  secondsLeft: number;
+}
+/** A live-tally display backend for votes — registered via {@link Vote.registerTallyRenderer}. */
+export interface VoteTallyRenderer {
+  /** Show/update the running tally for `slot`. */
+  show(slot: number, tally: VoteTally): void;
+  /** Remove the tally display for `slot` (the vote ended or the player left). */
+  clear(slot: number): void;
+}
+/**
+ * The voting entry point — one active chat-ballot vote at a time, tallied on close.
+ * @example
+ * import { Vote } from "@s2script/sdk/votes";
+ * Vote.start({
+ *   question: `Kick ${name}?`,
+ *   options: ["Yes", "No"],
+ *   duration: 20,
+ *   showLiveTally: true,
+ *   onEnd: (r) => {
+ *     if (r.winner === 0 && r.counts[0] > r.total / 2) kick(name);
+ *   },
+ * });
+ */
 export declare const Vote: {
   /** Start a vote (chat ballot to all connected players). Returns false if one is already active. */
   start(config: VoteConfig): boolean;
+  /** True while a vote is running (the single-vote lock is held). */
   isActive(): boolean;
   /** Abort the active vote (no onEnd). */
   cancel(): void;

package/ws.d.ts

@@ -1,12 +1,29 @@
 /** @s2script/ws — client WebSocket. NO runtime code (injected as __s2pkg_ws). */
+
+/** An open WebSocket connection — a per-plugin handle over a copied message stream (no live socket crosses to JS). */
 export interface WebSocket {
+  /** Register a handler invoked for each inbound text frame. */
   onMessage(handler: (data: string) => void): void;
+  /** Register a handler for connection close; `code`/`reason` come from the close frame. */
   onClose(handler: (code: number, reason: string) => void): void;
+  /** Register a handler for a transport error; `err` is the error text. */
   onError(handler: (err: string) => void): void;
+  /** Send a text frame. */
   send(data: string): void;
+  /** Close the connection. */
   close(): void;
 }
+/** Entry point for opening WebSocket connections. */
 export declare const WebSocket: {
-  /** Connect to a WebSocket server (wss:// for TLS). Resolves on the open handshake; rejects on connect failure. */
+  /**
+   * Connect to a WebSocket server (`wss://` for TLS) off the game thread.
+   * @returns Resolves on the open handshake with the live {@link WebSocket} handle.
+   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error).
+   * @example
+   * import { WebSocket } from "@s2script/sdk/ws";
+   * const ws = await WebSocket.connect("wss://ws.postman-echo.com/raw");
+   * ws.onMessage((data) => { console.log("echo:", data); ws.close(); });
+   * ws.send("hello-from-s2script");
+   */
   connect(url: string): Promise<WebSocket>;
 };

package/frame.d.ts

@@ -1,13 +0,0 @@
-/**
- * @s2script/frame — author-time type stubs for the per-frame subscription API.
- * NO runtime code: the engine injects the implementation at load time.
- */
-
-export interface SubscribeOptions {
-  priority?: number;
-}
-
-export declare const OnGameFrame: {
-  /** Register a callback that fires every game frame. */
-  subscribe(fn: () => void, opts?: SubscribeOptions): void;
-};