@s2script/sdk 0.27.0 → 0.27.1

package/config.d.ts

@@ -1,7 +1,7 @@
 /** @s2script/config — typed access to the plugin's materialized config. NO runtime code. */
 /** A materialized config value: a scalar, or a nested section object of further values. */
 export type ConfigValue = string | number | boolean | { [k: string]: ConfigValue };
-/** The whole materialized config: top-level keys to {@link ConfigValue}s. Passed to `ctx.config.onChange`. */
+/** The whole materialized config: top-level keys to {@link ConfigValue}s. Passed to `config.onChange` handlers. */
 export type Config = Record<string, ConfigValue>;
 /**
  * Typed access to this plugin's materialized config values (declared under `s2script.config` in the manifest).
@@ -25,7 +25,7 @@ export declare const config: {
   writeFile(name: string, content: string): void;
   /**
    * Fires when this plugin's config file is re-materialized on disk. Ledgered per plugin.
-   * Not load-window-gated (safe from `OnPluginStart` or from `ctx.config.onChange`).
+   * Not load-window-gated (safe from `OnPluginStart` or from a `config.onChange` handler).
    */
   onChange(handler: (cfg: Config) => void): void;
 };

package/contracts/workshop.d.ts

@@ -10,7 +10,7 @@
  *
  * @example
  * import type { WorkshopService } from "@s2script/sdk/contracts/workshop";
- * const ws = ctx.tryUse<WorkshopService>("workshop");
+ * const ws = tryUse<WorkshopService>("workshop"); // in OnPluginStart
  * if (ws) {
  *   const map = await ws.currentMap();
  *   console.log(map ? `${map.title} (${map.id})` : "not a workshop map");

package/db.d.ts

@@ -15,9 +15,16 @@ export interface ExecuteResult {
 
 /** A driver-owned connection — what a {@link Driver} hands back from {@link Driver.connect}. */
 export interface DriverConnection {
-  /** Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. */
+  /**
+   * Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. Rejects
+   * with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance; `DatabaseResultTooLarge`
+   * when rows or retained bytes exceed the configured limit.
+   */
   query(sql: string, params?: SqlValue[]): Promise<Row[]>;
-  /** Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?` placeholders. */
+  /**
+   * Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?`
+   * placeholders. Rejects with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance.
+   */
   execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
   /** Close the underlying connection. */
   close(): Promise<void>;
@@ -40,9 +47,16 @@ export interface Driver {
 }
 /** A live database connection (delegates to its driver). */
 export interface Database {
-  /** Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. */
+  /**
+   * Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. Rejects
+   * with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance; `DatabaseResultTooLarge`
+   * when rows or retained bytes exceed the configured limit.
+   */
   query(sql: string, params?: SqlValue[]): Promise<Row[]>;
-  /** Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?` placeholders. */
+  /**
+   * Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?`
+   * placeholders. Rejects with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance.
+   */
   execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
   /** Close the connection. */
   close(): Promise<void>;

package/events.d.ts

@@ -67,7 +67,7 @@ export declare const Events: {
    * re-firing a rebuilt copy per viewer does not.
    *
    * @example
-   * ctx.events.onPre("player_death", () => {
+   * hook.onPre("player_death", () => {
    *   Events.setRecipients(traitorSlots);   // only Traitors see the kill
    *   return HookResult.Handled;
    * });

package/http.d.ts

@@ -34,7 +34,9 @@ export interface Response {
  * @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.
+ * @throws Rejects on a network error or timeout, or with `AsyncQueueFull` / `AsyncPayloadTooLarge`
+ * before acceptance. `HttpResponseTooLarge` when the retained UTF-8 body plus headers exceed the
+ * configured limit.
  * @example
  * import { fetch } from "@s2script/sdk/http";
  * const r = await fetch("https://httpbin.org/get", { timeoutMs: 15000 });

package/interfaces.d.ts

@@ -5,7 +5,7 @@ import type { HookResultValue } from "./events";
  */
 
 /**
- * Handle returned by `ctx.publish(name, impl)`: lets the producer emit forwarded
+ * Handle returned by `publish(name, impl)`: lets the producer emit forwarded
  * events to every plugin subscribed to this interface via its `on(event, …)`.
  */
 export interface PublishHandle {
@@ -133,8 +133,10 @@ export type TypedInterfaceHandle<C> = ContractMethods<C> & {
 };
 
 /** A consumer-owned registration. Repeated disposal is a no-op. */
-export interface Subscription { dispose(): void; }
+export interface Subscription { /** Remove this exact registration. Idempotent. */
+dispose(): void; }
 /** Resources owned by one synchronous optional-provider attachment. */
 export interface AttachmentScope {
+  /** Return the resource and retain its disposer for this attachment. */
   own<T extends { dispose(): void }>(resource: T): T;
 }

package/menu.d.ts

@@ -51,7 +51,6 @@ export interface MenuCancelEvent {
  * 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 HUD menu is open
  * m.addItem("hp", "Heal to 100");
  * m.addItem("noclip", "Toggle Noclip");
  * m.onSelect(e => { console.log(`picked ${e.info} (slot ${e.slot})`); });
@@ -65,8 +64,12 @@ export declare class Menu {
   style: MenuStyle;
   /** Append an auto Exit control (default true). */
   exitButton: boolean;
-  /** When true, a renderer that supports it (the CS2 HUD renderer) freezes the player's movement
-   *  while the menu is open and restores it on close. Default false. */
+  /**
+   * When true, a renderer that supports it may freeze the player's movement while the menu is open
+   * and restore it on close. Default false. The CS2 center renderer currently ignores this and
+   * does not freeze movement — freezing is disabled until the menu surface can guarantee it is
+   * interactive. The chat renderer also ignores it.
+   */
   freezePlayer: boolean;
   /** `"immediate"` (default) arms cursor on open. `"tab"` paints first and waits for Tab. */
   activation: MenuActivation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "license": "MIT OR Apache-2.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",

package/plugin.d.ts

@@ -32,7 +32,7 @@ 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"));
+   * hook.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). */
@@ -158,7 +158,7 @@ export interface CtxTranslations {
    * client's language, then English), so list your own set before any shared one if you want to be
    * able to override a shared phrase.
    *
-   * @example ctx.translations.load("basecomm", "common");
+   * @example translations.load("basecomm", "common");
    */
   load(...names: string[]): void;
 }
@@ -250,7 +250,11 @@ export interface PluginContext {
   use<T extends object>(
     name: keyof InterfaceContracts extends never ? string : never
   ): InterfaceHandle<T>;
-  /** Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished. */
+  /**
+   * Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished.
+   * One-shot lookup — does not track later availability. Prefer watchOptional to follow a provider
+   * across load and reload.
+   */
   tryUse<N extends keyof InterfaceContracts>(
     name: N
   ): TypedInterfaceHandle<InterfaceContracts[N]> | null;
@@ -305,10 +309,10 @@ export interface PluginHooks {
  * The {@link GameEvent} is valid only synchronously.
  */
 export declare const hook: {
-  /** Post-phase (`ctx.events.on`). */
+  /** Post-phase game-event subscribe. The GameEvent is valid only synchronously. */
   on(name: string, handler: (ev: GameEvent) => void): void;
   /**
-   * Pre-phase (`ctx.events.onPre`). Return {@link HookResultValue} `Handled`/`Stop` to suppress
+   * Pre-phase game-event subscribe. Return {@link HookResultValue} `Handled`/`Stop` to suppress
    * the client broadcast.
    */
   onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
@@ -365,7 +369,8 @@ export declare function use<T extends object>(
 ): InterfaceHandle<T>;
 /**
  * Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished.
- * Load-window only. Same contract as {@link PluginContext.tryUse}.
+ * Load-window only. One-shot lookup — does not track later availability. Same contract as
+ * {@link PluginContext.tryUse}.
  */
 export declare function tryUse<N extends keyof InterfaceContracts>(
   name: N
@@ -383,7 +388,7 @@ export declare const topmenu: CtxTopMenu;
 /**
  * Load-window phrase-file declaration. Same contract as {@link PluginContext.translations}.
  * Throws after settle. `s2s build` / `sync-phrase-types.mjs` collect `translations.load(...)`
- * the same way they collect `ctx.translations.load(...)`.
+ * the same way they collect `translations.load(...)`.
  */
 export declare const translations: CtxTranslations;
 

package/topmenu.d.ts

@@ -37,7 +37,7 @@ export interface TopMenuSnapshot {
 }
 /**
  * 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.
+ * through {@link TopMenu.select}; items are contributed by plugins via `topmenu`.
  * @example
  * import { TopMenu } from "@s2script/sdk/topmenu";
  * const snap = TopMenu.snapshot();

package/unsafe.d.ts

@@ -74,7 +74,7 @@ export declare const Engine: {
    * gate (same class of reasons as {@link Engine.call}, plus a missing `validate` or an unknown
    * thunk shape). Guard once at load; the returned function records the handler and lazily
    * installs the detour. The owner is always the calling plugin — you cannot subscribe to
-   * another plugin's hook through this factory (game-package hooks hang off `ctx.*`).
+   * another plugin's hook through this factory (game-package hooks are the `@s2script/cs2` exports such as `players` and `gameRules`).
    */
   hook<K extends keyof EngineHooks>(name: K): EngineHooks[K] | null;
   /** Why a hook descriptor is unavailable; `"available"` when it resolved. */

package/usercmd.d.ts

@@ -7,16 +7,16 @@
 import type { QAngle } from "./math";
 
 /**
- * A block-scoped view of the CURRENT tick's usercmd (valid only during a `ctx.clients.onRunCmd`
+ * A block-scoped view of the CURRENT tick's usercmd (valid only during an `OnPlayerRunCmd`
  * 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/cookbook/src/recipes/usercmd.ts:27 — read this tick's input
- * ctx.clients.onRunCmd((cmd: UserCmdView, info: { slot: number }) => {
+ * // read this tick's input
+ * export function OnPlayerRunCmd(cmd: UserCmdView, info: { slot: number }): void {
  *   console.log(`slot=${info.slot} fwd=${cmd.forwardMove} btn=${cmd.buttons}`);
- * });
+ * }
  */
 export interface UserCmdView {
   /** +forward / -back. Normalized to roughly [-1, 1] (not the legacy ±450 units). */

package/ws.d.ts

@@ -9,7 +9,10 @@ export interface WebSocket {
   /** Register a handler for a transport error; `err` is the error text. */
   onError(handler: (err: string) => void): void;
   /** Send a text frame. */
-  /** Returns false if closed, oversized, or the connection/global outbound budget is full. */
+  /**
+   * Send a text frame. Returns false if closed, oversized, or the connection/global outbound
+   * budget is full.
+   */
   send(data: string): boolean;
   /** Close the connection. */
   close(): void;