@s2script/sdk 0.26.0 → 0.27.1

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.26.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/sdkhooks.d.ts

@@ -55,7 +55,11 @@ export declare const UseType: {
  * that is not a member here throws.
  */
 export declare const SDKHookType: {
-  /** Pre-apply damage (`DispatchTraceAttack`). Mutate {@link DamageInfo.damage} in place. */
+  /**
+   * Pre-apply damage, provided by the selected game package (CS2: `CBaseEntity::TakeDamageOld`).
+   * Mutate {@link DamageInfo.damage} in place. {@link SDKHook} returns `false` when no game package
+   * provides damage hooks.
+   */
   readonly OnTakeDamage: "OnTakeDamage";
   /**
    * CheckTransmit mux (wiki `SDKHook_SetTransmit`). `Handled` / `Stop` hide this entity from this
@@ -112,8 +116,8 @@ export declare const SDKHookType: {
   /** `CanBeAutobalanced`. Return a boolean (not {@link HookResultValue}); last defined wins. */
   readonly CanBeAutobalanced: "CanBeAutobalanced";
   /**
-   * Post-apply damage (`DispatchTraceAttack` after the original). {@link DamageInfo} is read-only
-   * for effect; mutations are not written back. Return is ignored.
+   * Post-apply damage (after the original ran), provided by the selected game package.
+   * {@link DamageInfo} is read-only for effect; `damage` assignment is ignored. Return is ignored.
    */
   readonly OnTakeDamagePost: "OnTakeDamagePost";
   /**
@@ -126,7 +130,7 @@ export declare const SDKHookType: {
   readonly OnTakeDamageAlivePost: "OnTakeDamageAlivePost";
   /**
    * `TraceAttack` pre ({@link TraceAttackInfo}). No distinct CS2 virtual yet — {@link SDKHook}
-   * returns `false` (OnTakeDamage remains the DTA mux).
+   * returns `false` (use OnTakeDamage).
    */
   readonly TraceAttack: "TraceAttack";
   /**
@@ -220,8 +224,9 @@ export declare function SDKHook(
   callback: (info: DamageInfo) => HookResultValue | void,
 ): boolean;
 /**
- * Post-apply damage. {@link DamageInfo} is a read of the live info after the original ran.
- * Return is ignored; Handled does not zero the hit (that is the pre-hook).
+ * Post-apply damage. {@link DamageInfo} reads the info after the original ran; it is valid only
+ * during the synchronous callback. Return is ignored; Handled does not zero the hit (that is the
+ * pre-hook).
  */
 export declare function SDKHook(
   entity: EntityRef | null,

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

@@ -22,6 +22,32 @@ export interface EngineCalls {}
  */
 export interface EngineHooks {}
 
+/** Generated bindings augment this map from gamedata/functions.jsonc. */
+export interface EngineFunctions {}
+
+export interface FunctionStatus {
+  readonly canonicalId: string;
+  readonly availability: 'available' | 'unavailable';
+  readonly reason: string | null;
+  readonly hookObservation: 'not-requested' | 'pending' | 'active' | 'failed';
+  readonly provenance: {
+    readonly archiveHash: string;
+    readonly baseContractHash: string;
+    readonly appliedOverrides: readonly { readonly path: string; readonly sha256: string }[];
+    readonly finalTargetHash: string;
+    readonly resolverReceipt: string;
+    readonly required: boolean;
+  };
+}
+
+export interface Disposable { dispose(): boolean; }
+
+export interface FunctionSubscription extends Disposable {
+  readonly status: 'pending' | 'active' | 'failed' | 'disposed';
+  readonly reason: string | null;
+  dispose(): boolean;
+}
+
 /**
  * Plugin-declared engine calls and inbound hooks, resolved from this plugin's own gamedata.
  *
@@ -34,6 +60,7 @@ export interface EngineHooks {}
  * if (onFoo) onFoo((view) => { view.reason = 0; });
  */
 export declare const Engine: {
+  function<K extends keyof EngineFunctions>(name: K): EngineFunctions[K];
   /**
    * The declared call, or `null` when its descriptor failed a load-time gate (signature miss,
    * validator rejection, slot outside `.text`, missing platform entry, or the plugin is not
@@ -47,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;