@s2script/sdk 0.4.0 → 0.5.1

package/entity.d.ts

@@ -2,21 +2,30 @@
  * @s2script/entity — author-time type stubs for the injected entity API.
  * NO runtime code: the engine injects the implementation at load time.
  */
-import type { HookResultValue } from "./events";
 
 /**
- * A serial-gated handle to a live entity. Wraps the `__s2_ent_ref_*` natives; the raw
- * entity pointer never crosses to JS. All accessors degrade safely (return null/false)
- * when the entity slot has been reused or the ops table is absent.
+ * A host-liveness-gated handle to a live entity. `id` is a HOST-MINTED monotonic liveness
+ * id — liveness is decided by the host's books (fed by engine create/delete notifications,
+ * cleared at map transition), NEVER by reading the entity's own memory. Every access
+ * re-resolves: books first, then identity-slot validation, instance last. A stale ref
+ * degrades to null/false — including across a changelevel.
+ *
+ * The framework mints every `EntityRef`; plugin code never constructs one (the constructor
+ * is intentionally not part of the public surface — a hand-built ref is the "raw ref across
+ * time" footgun). Obtain refs from the engine (events, `findByClass`, `readHandle`, …).
  */
 export declare class EntityRef {
+  /** This entity's slot index in the game entity system. Paired with the host-minted
+   *  {@link EntityRef.id} for slot validation (books first, then identity-slot match). */
   readonly index: number;
-  readonly serial: number;
+  /** The host-minted liveness id for this ref (books key). Not the raw engine serial. */
+  readonly id: number;
   /** This entity's targetname (`CEntityIdentity::m_name`) — e.g. a map trigger's `"map_start"`. `""` if
    *  the entity has no targetname; `null` if the ref is stale/invalid. */
   readonly name: string | null;
-  constructor(index: number, serial: number);
-  /** True iff the slot's current serial still matches the captured serial. */
+  /** @internal The host mints refs; this is not part of the public API surface. */
+  private constructor();
+  /** True iff the host's books say live AND the identity slot still matches. */
   isValid(): boolean;
   /** Read an i32 at `offset` bytes into the entity, or null if the ref is stale. */
   readInt32(offset: number): number | null;
@@ -68,31 +77,45 @@ export declare class EntityRef {
    *  is null. */
   readFloatsChain(ptrOffs: number[], finalOff: number, count: number): number[] | null;
   /** Follow a pointer chain (each an offset), then read a scalar at `finalOff`. null if the root is stale or any
-   *  hop is null. `readHandleVia` decodes a handle field → a serial-gated EntityRef; vectors use readFloatsChain. */
+   *  hop is null. `readHandleVia` decodes a handle field → a liveness-gated EntityRef; vectors use readFloatsChain. */
   readInt32Via(pathOffs: number[], finalOff: number): number | null;
-  /** Write an int32 at the end of a pointer chain (each hop deref'd, serial-gated at the root). Returns
+  /** Write an int32 at the end of a pointer chain (each hop deref'd, liveness-gated at the root). Returns
    *  false on a stale ref or a null hop. Used to clear a flag on a pointer-referenced sub-object. */
   writeInt32Via(pathOffs: number[], finalOff: number, value: number): boolean;
+  /** Read an i8 (sign-extended) at the end of a pointer chain (each hop deref'd, liveness-gated at the root); null if the root is stale or any hop is null. */
   readInt8Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read an i16 (sign-extended) through a pointer chain; null if the root is stale or any hop is null. */
   readInt16Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a u8 through a pointer chain; null if the root is stale or any hop is null. */
   readUInt8Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a u16 through a pointer chain; null if the root is stale or any hop is null. */
   readUInt16Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a u32 through a pointer chain; null if the root is stale or any hop is null. */
   readUInt32Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read an f32 through a pointer chain; null if the root is stale or any hop is null. */
   readFloat32Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a bool through a pointer chain; null if the root is stale or any hop is null. */
   readBoolVia(pathOffs: number[], finalOff: number): boolean | null;
+  /** Read a u64 as a BigInt through a pointer chain; null if the root is stale or any hop is null. */
   readUInt64Via(pathOffs: number[], finalOff: number): bigint | null;
+  /** Read an i64 as a BigInt through a pointer chain; null if the root is stale or any hop is null. */
   readInt64Via(pathOffs: number[], finalOff: number): bigint | null;
+  /** Decode a `CEntityHandle` at the end of a pointer chain into a liveness-gated {@link EntityRef}; null if the root is stale, any hop is null, or the handle is dead. */
   readHandleVia(pathOffs: number[], finalOff: number): EntityRef | null;
-  /** Write a scalar through a pointer chain (write mirror of `read*Via`). Serial-gated at the root;
+  /** Write a scalar through a pointer chain (write mirror of `read*Via`). Liveness-gated at the root;
    *  returns false on a stale ref, an unresolved hop, or a bad offset/kind. Does NOT notifyStateChanged —
    *  the caller decides (many sub-object fields, e.g. the fire gate, are server-authoritative).
    *  (`writeInt32Via` is declared above alongside `readInt32Via`.) */
   writeFloat32Via(pathOffs: number[], finalOff: number, value: number): boolean;
+  /** Write a bool through a pointer chain (write mirror of {@link EntityRef.readBoolVia}; shares the
+   *  no-notify semantics on {@link EntityRef.writeFloat32Via}). False on a stale ref, an unresolved hop, or a bad offset/kind. */
   writeBoolVia(pathOffs: number[], finalOff: number, value: boolean): boolean;
   /** Read a `CEntityHandle` at `offset`, decode it, and return a live `EntityRef` — or null if stale/invalid. */
   readHandle(offset: number): EntityRef | null;
   /** Notify the engine that the field at `offset` changed (triggers network replication). No-op if stale. */
   notifyStateChanged(offset: number): void;
+  /** Raw identity-slot flags (engine m_flags), or null when stale/unavailable. Bit meanings are game-specific. */
+  identityFlags(): number | null;
   /** DispatchSpawn this created entity. With keyvalues, the entity's own Spawn() parses them (the
    *  SourceMod DispatchKeyValue / CSSharp DispatchSpawn(kv) mechanism). Returns false if stale,
    *  unresolved, or the keyvalue map is rejected (non-finite number, unsupported value type, empty
@@ -109,7 +132,7 @@ export declare class EntityRef {
    *  `trigger_multiple` needs a model to build the physics volume that fires touch. Returns false
    *  if the op is unavailable or the ref is stale. */
   setModel(name: string): boolean;
-  /** Read a CUtlVector<CHandle> at (ptrOffs chain -> vectorOff) as live serial-gated EntityRefs.
+  /** Read a CUtlVector<CHandle> at (ptrOffs chain -> vectorOff) as live liveness-gated EntityRefs.
    *  Follows the pointer chain, reads count@+0 / elements@+8, caps at maxCount. [] if stale/unresolved. */
   readHandleVector(ptrOffs: number[], vectorOff: number, maxCount?: number): EntityRef[];
   /** Fire an entity input (e.g. "Kill"/"Ignite"/"SetHealth"/"Enable"/"Open"/"FireUser1"/"AddOutput")
@@ -129,7 +152,12 @@ export type EntityKeyValueMap = { [key: string]: string | number | boolean };
 /** Create a new entity by class name. WITHOUT keyvalues: create only — set fields, then call
  *  `.spawn()`. WITH keyvalues: create + DispatchSpawn(keyvalues) in one call — a non-null result is
  *  a LIVE, SPAWNED entity (on spawn failure the entity is removed and null returned). The created
- *  entity is game-world-owned (NOT auto-removed on plugin unload) — the plugin owns cleanup. */
+ *  entity is game-world-owned (NOT auto-removed on plugin unload) — the plugin owns cleanup.
+ *  @example
+ *  import { createEntity } from "@s2script/sdk/entity";
+ *  const wt = createEntity("point_worldtext", { message: "s2-ekv-proof", fullbright: true });
+ *  if (wt) wt.remove();
+ */
 export declare function createEntity(className: string, keyvalues?: EntityKeyValueMap): EntityRef | null;
 
 /** The payload delivered to an `Entity.onOutput` handler. */
@@ -147,30 +175,13 @@ export interface OutputEvent {
 }
 
 /**
- * Hook Source 2 entity outputs (`func_button`→`OnPressed`, `trigger_multiple`→`OnStartTouch`,
- * `logic_relay`→`OnTrigger`, …) via a `FireOutputInternal` detour. `classname`/`output` accept `"*"`
- * wildcards. The handler runs SYNCHRONOUSLY (may block): returning a `HookResultValue >= Handled`
- * (2/3) SUPPRESSES the output — the original `FireOutputInternal` call is skipped.
+ * Entry point for entity lookup by class name.
+ * @example
+ * import { Entity } from "@s2script/sdk/entity";
+ * const triggers = Entity.findByClass("trigger_multiple");
+ * for (const t of triggers) console.log(t.index, t.name);
  */
 export declare const Entity: {
-  onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
-  /**
-   * Fire when the engine CREATES an entity of `className` (`"*"` = all) — earliest hook; the entity is
-   * barely constructed, schema fields may be zero/default. The handler receives the serial-gated
-   * `entity` (may be `null`) plus its `className`. Prefer `onSpawn` to read fields.
-   */
-  onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
-  /**
-   * Fire after the engine SPAWNS an entity of `className` (`"*"` = all) — `Spawn()` has run, so schema
-   * fields/keyvalues are populated. The useful hook for reading state.
-   */
-  onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
-  /**
-   * Fire as the engine DELETES an entity of `className` (`"*"` = all). The entity is still readable
-   * during the synchronous handler; a stashed ref reads `null` once the slot is freed (serial gate),
-   * never garbage.
-   */
-  onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
-  /** Find every entity whose designer-name (class) exactly matches `className`. Returns serial-gated refs. */
+  /** Find every entity whose designer-name (class) exactly matches `className`. Returns liveness-gated refs. */
   findByClass(className: string): EntityRef[];
 };

package/events.d.ts

@@ -3,18 +3,27 @@
 /** A live game-event accessor. Valid ONLY during the synchronous handler — read fields before any `await`;
  *  a stashed GameEvent used later reads defaults. The raw engine event never crosses to JS. */
 export declare class GameEvent {
+  /** The event's name (e.g. `"player_death"`). */
   readonly name: string;
+  /** Read an integer field. `0` if absent or non-integer. */
   getInt(key: string): number;
+  /** Read a float field. `0` if absent or non-float. */
   getFloat(key: string): number;
+  /** Read a boolean field. `false` if absent. */
   getBool(key: string): boolean;
+  /** Read a string field. `""` if absent. */
   getString(key: string): string;
   /** A 64-bit field as a decimal string (SM-parity, wire-safe). */
   getUint64(key: string): string;
   /** A player field (e.g. "userid"/"attacker") as a 0-based slot, or -1 if absent. Resolve with Player.fromSlot. */
   getPlayerSlot(key: string): number;
+  /** Overwrite an integer field on the live event (valid only in the synchronous handler). */
   setInt(key: string, value: number): void;
+  /** Overwrite a float field on the live event (valid only in the synchronous handler). */
   setFloat(key: string, value: number): void;
+  /** Overwrite a boolean field on the live event (valid only in the synchronous handler). */
   setBool(key: string, value: boolean): void;
+  /** Overwrite a string field on the live event (valid only in the synchronous handler). */
   setString(key: string, value: string): void;
   /** Set a 64-bit field from a decimal string (SM-parity, wire-safe). */
   setUint64(key: string, value: string): void;
@@ -22,23 +31,27 @@ export declare class GameEvent {
 
 /** Collapsed pre-hook result. Return from an `onPre` handler; `Handled`/`Stop` suppress the client
  *  broadcast (server still processes). Returning nothing = `Continue`. */
-export declare const HookResult: { readonly Continue: 0; readonly Changed: 1; readonly Handled: 2; readonly Stop: 3 };
+export declare const HookResult: {
+  /** No change — proceed normally. Equivalent to returning nothing. */
+  readonly Continue: 0;
+  /** Fields were modified in place; proceed with the changes (the client broadcast still happens). */
+  readonly Changed: 1;
+  /** Suppress the client broadcast (the server still processes the event). */
+  readonly Handled: 2;
+  /** Suppress the client broadcast AND stop running lower-priority handlers. The collapse takes the MAX. */
+  readonly Stop: 3;
+};
+/** The numeric union an `onPre` handler may return — one of the {@link HookResult} values. */
 export type HookResultValue = 0 | 1 | 2 | 3;
 
+/**
+ * Fire and target game events from JS.
+ * @example
+ * import { Events } from "@s2script/sdk/events";
+ * // plugins/playercommands/src/plugin.ts:78 — announce a name change
+ * Events.fire("player_changename", { userid: p.userId, oldname, newname });
+ */
 export declare const Events: {
-  /** Subscribe to a game event by name. The handler runs synchronously when the event fires. */
-  on(name: string, handler: (ev: GameEvent) => void): void;
-  /**
-   * Unsubscribe from a game event by name.
-   *
-   * **Note:** `off` removes ALL of the calling plugin's handlers for the given event name —
-   * handler identity is NOT compared. This matches the engine-op semantics: the mux removes
-   * every subscription the current plugin holds for `name` in one call. Avoid double-subscribing
-   * the same name with different handlers if you need selective removal.
-   */
-  off(name: string, handler: (ev: GameEvent) => void): void;
-  /** Pre-hook: runs before the event broadcasts; may read+modify `ev` and return a HookResult to block. */
-  onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
   /** Fire a game event. Returns the engine FireEvent result. */
   fire(name: string, fields?: Record<string, number | string | boolean | bigint>, dontBroadcast?: boolean): boolean;
   /** Fire a game event to ONE client (SourceMod FireToClient). Same field type-inference as `fire`. Returns false on miss. */

package/globals.d.ts

@@ -3,7 +3,12 @@
 // typecheck gate as a root file so plugins that use these globals WITHOUT importing type-check against
 // the real sandbox — NOT lib.dom (the sandbox has no window/document/etc.).
 
-/** The engine-injected console (a subset of the browser/node console). */
+/**
+ * The engine-injected console (a subset of the browser/node console). Global — no import needed.
+ * @example
+ * // plugins/antiflood/src/plugin.ts:48 — write a line to the server console/log
+ * console.log("[antiflood] onLoad — chat flood protection active");
+ */
 declare const console: {
   log(...data: any[]): void;
   error(...data: any[]): void;

package/http.d.ts

@@ -1,11 +1,42 @@
 /** @s2script/http — async HTTP. NO runtime code (injected as __s2pkg_http). */
-export interface FetchOptions { method?: string; headers?: Record<string, string>; body?: string; timeoutMs?: number; }
+
+/** Options for {@link fetch}. */
+export interface FetchOptions {
+  /** HTTP method (e.g. `"GET"`, `"POST"`). @defaultValue `"GET"` */
+  method?: string;
+  /** Request headers as a name→value map. */
+  headers?: Record<string, string>;
+  /** Request body (already-serialized string; set your own `content-type`). */
+  body?: string;
+  /** Abort the request after this many milliseconds. @defaultValue no timeout */
+  timeoutMs?: number;
+}
+
+/** The response from a {@link fetch} call — a copied snapshot (no live socket). */
 export interface Response {
-  readonly status: number; readonly ok: boolean; readonly statusText: string;
+  /** HTTP status code (e.g. `200`, `404`). */
+  readonly status: number;
+  /** True iff {@link Response.status} is in the 2xx range. */
+  readonly ok: boolean;
+  /** HTTP status reason phrase (e.g. `"Not Found"`). */
+  readonly statusText: string;
+  /** Response headers as a lower-cased name→value map. */
   readonly headers: Record<string, string>;
+  /** The response body decoded as text. */
   text(): string;
+  /** Parse the response body as JSON into `T` (throws on invalid JSON). */
   json<T = unknown>(): T;
 }
-/** Perform an HTTP request off the game thread. Rejects on a network error / timeout; an HTTP
- *  status (incl. 4xx/5xx) RESOLVES with ok=false. */
+
+/**
+ * Perform an HTTP request off the game thread.
+ * @param url - Absolute `http(s)://` URL.
+ * @param options - Method, headers, body, and timeout (see {@link FetchOptions}).
+ * @returns Resolves for ANY HTTP response — a 4xx/5xx resolves with `ok=false`, it does not reject.
+ * @throws Rejects only on a network error or timeout.
+ * @example
+ * import { fetch } from "@s2script/sdk/http";
+ * const r = await fetch("https://httpbin.org/get", { timeoutMs: 15000 });
+ * if (r.ok) console.log(r.json<{ url: string }>().url);
+ */
 export declare function fetch(url: string, options?: FetchOptions): Promise<Response>;

package/interfaces.d.ts

@@ -4,33 +4,17 @@
  */
 
 /**
- * Handle returned by {@link publishInterface}: lets the producer emit forwarded
+ * Handle returned by `ctx.publish(name, impl)`: lets the producer emit forwarded
  * events to every plugin subscribed to this interface via its `on(event, …)`.
  */
 export interface PublishHandle {
-  /** Emit a forwarded event to all consumers subscribed via `interface.on(event, …)`. */
+  /**
+   * Emit a forwarded event to all consumers subscribed via `interface.on(event, …)`. The payload is
+   * structured-copied across the context boundary (JSON, EntityRef-aware — never a live reference).
+   * @example
+   * import type { PublishHandle } from "@s2script/sdk/interfaces";
+   * // plugins/zones/src/plugin.ts:30 — notify consumers a zone was created
+   * iface.emit("created", { zone: z.name, min: z.min, max: z.max, tags: z.tags });
+   */
   emit(event: string, payload: unknown): void;
 }
-
-/**
- * Publish a typed inter-plugin interface under `name`. `impl`'s methods become the
- * natives consumers call (`interface.method(...)`); the returned handle's `emit` fans
- * forwarded events out to consumers' `on(event, …)` subscriptions.
- *
- * The interface's VERSION is injected by the host from this plugin's manifest
- * `publishes` map — never passed here, and never written in TypeScript source.
- * Publishing a name the manifest does not declare is refused at load.
- *
- * `impl` is generic over `object` rather than `Record<string, Function>` so that a
- * producer can bind it to its contract — `const impl: Zones = {…}` — which is what
- * actually proves the implementation matches the published `.d.ts`. A TypeScript
- * `interface` has no implicit index signature (only a `type` alias does), so a
- * `Record<…>` parameter would reject every interface-typed contract. The host
- * enumerates `impl`'s own function properties; non-function properties are ignored.
- *
- * Auto-ledgered: the interface is withdrawn (and hard-dep consumers degraded) on unload.
- */
-export declare function publishInterface<T extends object>(
-  name: string,
-  impl: T,
-): PublishHandle;

package/math.d.ts

@@ -3,23 +3,37 @@
  * NO runtime code: the engine injects the implementation (core prelude) at load time.
  */
 
-/** A 3-component vector value (a copied snapshot; never a live pointer). */
+/**
+ * A 3-component vector value (a copied snapshot; never a live pointer).
+ * @example
+ * import { Vector } from "@s2script/sdk/math";
+ * const start = new Vector(0, 0, 100);
+ * console.log(start.length());
+ */
 export declare class Vector {
+  /** The X component. */
   x: number;
+  /** The Y component. */
   y: number;
+  /** The Z component. */
   z: number;
   constructor(x: number, y: number, z: number);
   /** Euclidean magnitude — e.g. speed from a velocity vector. */
   length(): number;
+  /** Format as `"Vector(x, y, z)"` (for logging). */
   toString(): string;
 }
 
 /** A Source 2 Euler angle value (x=pitch, y=yaw, z=roll), a copied snapshot. */
 export declare class QAngle {
+  /** Pitch, in degrees. */
   x: number;
+  /** Yaw, in degrees. */
   y: number;
+  /** Roll, in degrees. */
   z: number;
   constructor(x: number, y: number, z: number);
+  /** Format as `"QAngle(x, y, z)"` (for logging). */
   toString(): string;
 }
 

package/menu.d.ts

@@ -1,12 +1,62 @@
 /** @s2script/menu — interactive player menus (chat + center backends). NO runtime code (injected at load). */
-export declare const enum MenuStyle { Chat = "chat", Center = "center" }
-export declare const enum MenuCancelReason { Exit = 0, Timeout = 1, Disconnect = 2, NewMenu = 3 }
 
-export interface MenuSelectEvent { readonly slot: number; readonly item: number; readonly info: string; readonly display: string; }
-export interface MenuCancelEvent { readonly slot: number; readonly reason: MenuCancelReason; }
+/** The display backend a {@link Menu} renders through — the value of {@link Menu.style}. */
+export declare const enum MenuStyle {
+  /** Chat-log backend: numbered lines printed to chat, picked by typing the number. */
+  Chat = "chat",
+  /** CS2 center-screen HTML backend: W/S move the cursor, E selects; re-painted each tick. */
+  Center = "center",
+}
+/** Why a menu closed without a selection — the {@link MenuCancelEvent.reason}. */
+export declare const enum MenuCancelReason {
+  /** The player chose the Exit control (or `close`/`cancel` was called). */
+  Exit = 0,
+  /** The `display` seconds elapsed with no selection. */
+  Timeout = 1,
+  /** The player left the server. */
+  Disconnect = 2,
+  /** A newer menu was shown to the same slot, superseding this one. */
+  NewMenu = 3,
+}
+
+/** Payload for {@link Menu.onSelect} — the item a player picked. */
+export interface MenuSelectEvent {
+  /** 0-based player slot that made the selection. */
+  readonly slot: number;
+  /** 0-based index of the chosen item within the menu's item list. */
+  readonly item: number;
+  /** The `info` string the item was added with — the machine key, returned to your handler. */
+  readonly info: string;
+  /** The visible label the item was added with. */
+  readonly display: string;
+}
+/** Payload for {@link Menu.onCancel} — a menu that closed without a selection. */
+export interface MenuCancelEvent {
+  /** 0-based player slot whose menu closed. */
+  readonly slot: number;
+  /** Why it closed (see {@link MenuCancelReason}). */
+  readonly reason: MenuCancelReason;
+}
 
+/**
+ * A slot-based interactive menu. Add items, wire {@link Menu.onSelect}/{@link Menu.onCancel},
+ * then {@link Menu.display} to a player slot. The model paginates automatically (7 items per chat
+ * page) and picks a renderer by {@link Menu.style}, falling back to Chat when the style's renderer
+ * is unregistered. Only one menu is active per slot; displaying a new one supersedes the old
+ * ({@link MenuCancelReason.NewMenu}).
+ * @example
+ * import { Menu, MenuStyle } from "@s2script/sdk/menu";
+ * const m = new Menu("s2script Menu Demo");
+ * m.style = MenuStyle.Center;
+ * m.freezePlayer = true;                 // freeze movement while the WASD menu is open (nav still works)
+ * m.addItem("hp", "Heal to 100");
+ * m.addItem("noclip", "Toggle Noclip");
+ * m.onSelect(e => { console.log(`picked ${e.info} (slot ${e.slot})`); });
+ * m.display(slot, 30);
+ */
 export declare class Menu {
   constructor(title?: string);
+  /** Heading shown above the item list. */
   title: string;
   /** Which registered renderer to use. Falls back to Chat if the style's renderer is unregistered. */
   style: MenuStyle;
@@ -18,7 +68,9 @@ export declare class Menu {
   freezePlayer: boolean;
   /** (info, display) — `info` is returned to onSelect; `display` is shown. */
   addItem(info: string, display: string, opts?: { disabled?: boolean }): void;
+  /** Register the callback fired when a player picks an item. Replaces any previous handler. */
   onSelect(handler: (e: MenuSelectEvent) => void): void;
+  /** Register the callback fired when the menu closes without a selection (see {@link MenuCancelReason}). Replaces any previous handler. */
   onCancel(handler: (e: MenuCancelEvent) => void): void;
   /** Show to a 0-based slot for `seconds` (0 = until selection/cancel/disconnect). */
   display(slot: number, seconds?: number): void;
@@ -28,11 +80,44 @@ export declare class Menu {
   static registerRenderer(name: string, renderer: MenuRenderer): void;
 }
 
+/** A live display of one menu to one slot, passed to a {@link MenuRenderer}. Owns the page/cursor state and exposes the input verbs a renderer drives. */
 export interface MenuSession {
+  /** 0-based player slot this session is displayed to. */
   readonly slot: number;
+  /** The resolved snapshot the renderer paints: heading, per-line state, and 0-based page position. */
   view(): { title: string; lines: MenuLine[]; page: number; pageCount: number; exit: boolean };
+  /** Chat idiom: apply a number-key press against the current view (1..7 select, 8=Back, 9=Next, 0=Exit). */
   pickNumber(n: number): void;
-  moveUp(): void; moveDown(): void; confirm(): void; cancel(): void;
+  /** Center idiom: move the cursor up over the current page's nav targets (items + Back/Next/Exit), wrapping. */
+  moveUp(): void;
+  /** Center idiom: move the cursor down over the current page's nav targets, wrapping. */
+  moveDown(): void;
+  /** Center idiom: activate the current cursor target (select an item, paginate, or exit). */
+  confirm(): void;
+  /** Close this session with an {@link MenuCancelReason.Exit}. */
+  cancel(): void;
+}
+/** One rendered line of a {@link MenuSession} view. */
+export interface MenuLine {
+  /** The line's visible text. */
+  text: string;
+  /** The chat number key ("1".."0") that picks this line, or null for an unselectable/disabled line. */
+  key: string | null;
+  /** True if this line is a selectable item. */
+  selectable: boolean;
+  /** True if the center cursor is currently on this line (the renderer highlights it). */
+  cursor?: boolean;
+  /** For a control line, which control it is: `"back"`, `"next"`, or `"exit"` (absent on item lines). */
+  control?: string;
+  /** For an item line, its 0-based index into the menu's item list (absent on control lines). */
+  index?: number;
+}
+/** A display backend for {@link Menu} — registered via {@link Menu.registerRenderer}, driven with a {@link MenuSession}. */
+export interface MenuRenderer {
+  /** Show the session for the first time (the menu just opened). */
+  open(session: MenuSession): void;
+  /** Re-paint the session after a page/cursor change. */
+  update(session: MenuSession): void;
+  /** Tear down the display for `slot` (the menu closed). */
+  close(slot: number): void;
 }
-export interface MenuLine { text: string; key: string | null; selectable: boolean; cursor?: boolean; control?: string; index?: number; }
-export interface MenuRenderer { open(session: MenuSession): void; update(session: MenuSession): void; close(slot: number): void; }

package/net.d.ts

@@ -1,19 +1,43 @@
 /** @s2script/net — engine-generic raw TCP + UDP sockets (binary), off the game thread. */
+
+/** A connected TCP client socket — a per-plugin handle over a copied byte stream (no live socket crosses to JS). */
 export interface TcpSocket {
+  /** Send bytes; a `string` is sent as its UTF-8 encoding. */
   send(data: Uint8Array | string): void;
+  /** Register a handler invoked for each inbound chunk of bytes. */
   onData(handler: (bytes: Uint8Array) => void): void;
+  /** Register a handler for the peer closing the connection. */
   onClose(handler: () => void): void;
+  /** Register a handler for a transport error; `err` is the error text. */
   onError(handler: (err: string) => void): void;
+  /** Close the connection. */
   close(): void;
 }
+/** A bound UDP socket — a per-plugin handle for connectionless datagrams. */
 export interface UdpSocket {
+  /** Send a datagram to `host:port`; a `string` is sent as its UTF-8 encoding. */
   sendTo(host: string, port: number, data: Uint8Array | string): void;
+  /** Register a handler invoked for each inbound datagram; `from` is the sender's address. */
   onMessage(handler: (from: { host: string; port: number }, bytes: Uint8Array) => void): void;
+  /** Close the socket. */
   close(): void;
 }
+/** Entry point for opening raw TCP + UDP sockets. */
 export declare const Net: {
-  /** Connect a TCP client. Rejects on connect failure. */
+  /**
+   * Connect a TCP client to `host:port` off the game thread.
+   * @returns Resolves on connect with the live {@link TcpSocket} handle.
+   * @throws Rejects on connect failure (refused, unreachable, DNS error).
+   * @example
+   * import { Net } from "@s2script/sdk/net";
+   * const sock = await Net.connectTcp("127.0.0.1", 9000);
+   * sock.onData((bytes) => console.log("got " + bytes.length + " bytes"));
+   * sock.send("hello");
+   */
   connectTcp(host: string, port: number): Promise<TcpSocket>;
-  /** Bind a UDP socket on an ephemeral local port. */
+  /**
+   * Bind a UDP socket on an ephemeral local port.
+   * @returns Resolves with the bound {@link UdpSocket} handle.
+   */
   udp(): Promise<UdpSocket>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",
   "bin": {
@@ -14,7 +14,9 @@
   "dependencies": {
     "esbuild": "^0.25.0",
     "adm-zip": "^0.5.16",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "eslint": "^10.7.0",
+    "@s2script/eslint-plugin": "0.2.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7"
@@ -64,9 +66,6 @@
     "./events": {
       "types": "./events.d.ts"
     },
-    "./frame": {
-      "types": "./frame.d.ts"
-    },
     "./http": {
       "types": "./http.d.ts"
     },
@@ -82,6 +81,9 @@
     "./net": {
       "types": "./net.d.ts"
     },
+    "./plugin": {
+      "types": "./plugin.d.ts"
+    },
     "./plugins": {
       "types": "./plugins.d.ts"
     },