@s2script/sdk 0.21.0 → 0.23.0

package/entity.d.ts

@@ -220,7 +220,7 @@ export type EntityKeyValueMap = { [key: string]: string | number | boolean };
  */
 export declare function createEntity(className: string, keyvalues?: EntityKeyValueMap): EntityRef | null;
 
-/** The payload delivered to an `Entity.onOutput` handler. */
+/** The payload delivered to an `onOutput` handler. */
 export interface OutputEvent {
   /** The output's name (e.g. "OnTrigger", "OnPressed", "OnStartTouch"). */
   output: string;

package/events.d.ts

@@ -52,9 +52,9 @@ export type HookResultValue = 0 | 1 | 2 | 3;
  * Events.fire("player_changename", { userid: p.userId, oldname, newname });
  */
 export declare const Events: {
-  /** Fire a game event. Returns the engine FireEvent result. */
+  /** Fire a game event (SourceMod `FireEvent`). Other plugins' `on` / `onPre`
+   *  handlers run before this returns. 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. */
   /**
    * Restrict the event currently being pre-dispatched to `slots`, instead of hiding it from everyone.
    *
@@ -73,6 +73,7 @@ export declare const Events: {
    * });
    */
   setRecipients(slots: readonly number[]): void;
-
+  /** Fire a game event to ONE client (SourceMod `FireToClient`). Does not go through
+   *  `IGameEventManager2::FireEvent` (no `onPre`). Returns false on miss. */
   fireToClient(slot: number, name: string, fields?: Record<string, string | number | boolean | bigint>): boolean;
 };

package/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `@s2script/sdk` — the engine-generic authoring barrel.
+ *
+ * Subpath imports (`@s2script/sdk/commands`, `@s2script/sdk/plugin`, …) stay valid.
+ * This root re-exports the same names so a plugin can write:
+ *
+ *   import { command, hook, HookResult, ADMFLAG } from "@s2script/sdk";
+ *
+ * `Player` / `Pawn` / CS2 schema types are NOT here — they live on `@s2script/cs2`.
+ * `@s2script/sdk/unsafe` stays a deliberate subpath (not re-exported).
+ *
+ * NO runtime code in this file: the engine injects `globalThis.__s2pkg_sdk` at load
+ * (`__s2require("@s2script/sdk")`).
+ */
+
+export * from "./admin";
+export * from "./bans";
+export * from "./chat";
+export * from "./clients";
+export * from "./commands";
+export * from "./config";
+export * from "./cookies";
+export * from "./damage";
+export * from "./db";
+export * from "./entity";
+export * from "./events";
+export * from "./http";
+export * from "./interfaces";
+export * from "./math";
+export * from "./menu";
+export * from "./net";
+export * from "./phrases";
+export * from "./plugin";
+export * from "./plugins";
+export * from "./sdkhooks";
+export * from "./server";
+export * from "./sound";
+export * from "./timers";
+export * from "./topmenu";
+export * from "./trace";
+export * from "./translations";
+export * from "./transmit";
+export * from "./usercmd";
+export * from "./usermessages";
+export * from "./voice";
+export * from "./votes";
+export * from "./ws";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "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",
@@ -13,7 +13,7 @@
     "test": "node --experimental-strip-types --no-warnings --test test/*.test.mjs"
   },
   "dependencies": {
-    "@s2script/eslint-plugin": "0.2.0",
+    "@s2script/eslint-plugin": "0.2.1",
     "esbuild": "^0.25.0",
     "eslint": "^10.7.0",
     "typescript": "^5.6.0"
@@ -35,6 +35,9 @@
     "contracts"
   ],
   "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    },
     "./admin": {
       "types": "./admin.d.ts"
     },
@@ -92,6 +95,9 @@
     "./plugins": {
       "types": "./plugins.d.ts"
     },
+    "./sdkhooks": {
+      "types": "./sdkhooks.d.ts"
+    },
     "./server": {
       "types": "./server.d.ts"
     },

package/phrases.d.ts

@@ -6,13 +6,14 @@
  * from the phrase files you load.
  *
  * @example
- * export default plugin((ctx) => {
- *   ctx.translations.load("basecomm", "common");
+ * import { translations } from "@s2script/sdk";
+ * export function OnPluginStart(): void {
+ *   translations.load("basecomm", "common");
  *
  *   cmd.replyT("Usage Gag");            // ok — in translations/basecomm.phrases.json
  *   cmd.replyT("No matching players");  // ok — in translations/common.phrases.json
  *   cmd.replyT("Usage Gagg");           // compile error — no such key in either
- * });
+ * }
  *
  * ## Writing phrases
  *
@@ -29,7 +30,7 @@
  *
  * ## How the checking works
  *
- * The build reads your `ctx.translations.load(...)` call and writes `src/phrases.generated.d.ts`,
+ * The build reads your `translations.load(...)` call and writes `src/phrases.generated.d.ts`,
  * filling in {@link PhraseKeys} with the keys of exactly those files. Load a file and its keys
  * become valid; don't, and they don't — so a forgotten `load` is a compile error rather than raw key
  * text printed to a player at runtime. SourceMod enforces the same rule, but only when it happens.

package/plugin.d.ts

@@ -1,15 +1,15 @@
 /**
- * @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).
+ * @s2script/sdk/plugin — load-window authoring (`hook`, `publish`, `translations`, `Scope`)
+ * and the internal load-scoped {@link PluginContext} types. NO runtime code: the engine injects
+ * the implementation at load time (`__s2pkg_plugin`).
  *
- * See docs/superpowers/specs/2026-07-20-L1-lifecycle-v2-design.md §1-§3 for the full contract.
+ * The plugin artifact is `export function OnPluginStart` (plus optional named publics).
+ * See docs/superpowers/specs/2026-08-30-drop-plugin-factory-design.md.
  */
 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 { CommandHandler } from "./commands";
 import type { Config } from "./config";
 import type { PublishHandle } from "./interfaces";
 import type { TopMenuItem } from "./topmenu";
@@ -30,7 +30,7 @@ export interface CtxEvents {
 }
 /**
  * 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
+ * explicitly in OnPluginStart: `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).
  */
@@ -56,7 +56,7 @@ export interface CtxClients {
   /** 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}). */
+/** Entity lifecycle / I/O 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;
@@ -66,17 +66,9 @@ export interface CtxEntities {
   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). */
   /**
    * Run `fn` every game frame.
    *
@@ -97,11 +89,11 @@ export interface CtxServer {
 /** 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(name: string, handler: CommandHandler): void;
   /** Register a server-only command (console/rcon, not client-runnable). */
-  registerServer(name: string, handler: (cmd: CommandInvocation) => void): void;
+  registerServer(name: string, handler: CommandHandler): 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;
+  registerAdmin(name: string, flags: number, handler: CommandHandler): void;
   /**
    * Observe an existing CLIENT command by name — SourceMod's `AddCommandListener`.
    *
@@ -162,7 +154,7 @@ export interface Scope {
   readonly events: CtxEvents;
   /** Client-lifecycle subscriptions bound to this scope. */
   readonly clients: CtxClients;
-  /** Entity/damage subscriptions bound to this scope. */
+  /** Entity lifecycle / I/O subscriptions bound to this scope. */
   readonly entities: CtxEntities;
   /** Per-frame/map subscriptions bound to this scope. */
   readonly server: CtxServer;
@@ -175,8 +167,9 @@ export interface Scope {
 }
 
 /**
- * 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).
+ * The load-scoped context the host builds for one plugin load. Public authoring uses
+ * {@link hook} / {@link command} / named publics instead of receiving this object.
+ * {@link Scope} reuses the same subscription namespaces.
  */
 export interface PluginContext {
   /** This plugin's id (manifest `id`). */
@@ -187,7 +180,7 @@ export interface PluginContext {
   readonly events: CtxEvents;
   /** Client-lifecycle subscriptions ({@link CtxClients}). */
   readonly clients: CtxClients;
-  /** Entity/damage subscriptions ({@link CtxEntities}). */
+  /** Entity lifecycle / I/O subscriptions ({@link CtxEntities}). */
   readonly entities: CtxEntities;
   /** Per-frame/map/precache subscriptions ({@link CtxServer}). */
   readonly server: CtxServer;
@@ -201,7 +194,7 @@ export interface PluginContext {
   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. */
+  /** Resolve a HARD dep (must be in `pluginDependencies`). Immediate — the proxy is callable during OnPluginStart. */
   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;
@@ -209,31 +202,98 @@ export interface PluginContext {
   createScope(): Scope;
 }
 
-/** Optional lifecycle hooks a {@link PluginFactory} may return to participate in unload + hot-reload. */
+/** Optional lifecycle hooks a plugin may return to participate in unload + hot-reload.
+ *  Public authoring uses `export function OnPluginEnd` / `OnPluginState` instead. */
 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. */
+  /** Hot-reload handoff capture; JSON-serialized (EntityRef-aware) and revived as the next instance's {@link 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).
+ * Named publics the host finds on `module.exports` (missing export = not subscribed):
+ *
+ * Plugin: `OnPluginStart` / `OnPluginEnd` / `OnPluginState` / `OnAllPluginsLoaded` / `OnConfigsExecuted`
+ * Map/frame: `OnMapStart(map)` / `OnMapEnd()` / `OnGameFrame()` / `OnPrecache(pc)`
+ * Client: `OnClientConnected` / `PutInServer` / `Active` / `PostAdminCheck` / `Disconnect` /
+ *   `SayCommand` / `SettingsChanged` / `Voice` / `CookiesCached` / `OnPlayerRunCmd`
+ * Entity: `OnEntityCreated` / `OnEntitySpawned` / `OnEntityDestroyed`
+ *
+ * `OnGameFrame` is SourceMod's public (before simulation). Post-simulation paint is
+ * {@link Scope}'s `server.onGameFrame(fn, { phase: "post" })` — Metamod's post hook, not a SM public.
+ * Filtered entity I/O is {@link onOutput}, not a public — SourceMod `HookEntityOutput`.
+ * Per-entity damage is `SDKHook` (`SDKHookType.OnTakeDamage`), not a named public.
  */
-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;
-}
+
+/**
+ * Game-event catalog. Load-window only — throws after settle (same window as {@link command}).
+ *
+ * `hook.on` is post-fire; `hook.onPre` is pre (`Handled`/`Stop` suppress the client broadcast).
+ * The {@link GameEvent} is valid only synchronously.
+ */
+export declare const hook: {
+  /** Post-phase (`ctx.events.on`). */
+  on(name: string, handler: (ev: GameEvent) => void): void;
+  /**
+   * Pre-phase (`ctx.events.onPre`). Return {@link HookResultValue} `Handled`/`Stop` to suppress
+   * the client broadcast.
+   */
+  onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
+};
+
+/**
+ * Load-window entity I/O subscribe (SourceMod `HookEntityOutput`). Keyed by `(classname, output)`
+ * at the native mux — use `"*"` for either side. Throws after settle.
+ */
+export declare function onOutput(
+  classname: string,
+  output: string,
+  handler: (ev: OutputEvent) => HookResultValue | void,
+): void;
+
+/**
+ * The revived hot-reload handoff (the previous instance's `OnPluginState` return), or `undefined`.
+ * Load-window only.
+ */
+export declare function previous(): unknown;
+/**
+ * This plugin's id (manifest `id`). Load-window only.
+ */
+export declare function pluginId(): string;
+
+/**
+ * Allocate a disposable subscription scope. Load-window only — same contract as
+ * {@link PluginContext.createScope}.
+ */
+export declare function createScope(): Scope;
+
+/**
+ * Publish this plugin's manifest-declared interface. Load-window only (buffered, armed at Active).
+ * Same contract as {@link PluginContext.publish}.
+ */
+export declare function publish<T extends object>(name: string, impl: T): PublishHandle;
+/**
+ * Resolve a HARD dep (must be in `pluginDependencies`). Load-window only.
+ * Same contract as {@link PluginContext.use}. Prefer `import { greet } from "@demo/greeter"` for
+ * the producer-as-import form; `use()` remains the explicit load-window form and the optional-dep path.
+ */
+export declare function use<T extends object>(name: string): InterfaceHandle<T>;
+/**
+ * Resolve an OPTIONAL dep (must be in `optionalPluginDependencies`); null while unpublished.
+ * Load-window only. Same contract as {@link PluginContext.tryUse}.
+ */
+export declare function tryUse<T extends object>(name: string): InterfaceHandle<T> | null;
+
+/**
+ * Load-window TopMenu contribution. Same contract as {@link PluginContext.topmenu}.
+ * Throws after settle.
+ */
+export declare const topmenu: CtxTopMenu;
+
 /**
- * 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 }));
- * });
+ * 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(...)`.
  */
-export declare function plugin(factory: PluginFactory): PluginDefinition;
+export declare const translations: CtxTranslations;