@s2script/sdk 0.22.0 → 0.23.0

package/README.md

@@ -19,13 +19,21 @@ Copy the `.s2sp` into `addons/s2script/plugins/` on a running server and it load
 re-drop to hot-reload, delete to unload. No restart.
 
 ```ts
-import { plugin } from "@s2script/sdk/plugin";
+import { command, hook } from "@s2script/sdk";
+import type { Client } from "@s2script/sdk";
 
-export default plugin((ctx) => {
-  ctx.commands.register("hello", (cmd) => {
+export function OnPluginStart(): void {
+  command("hello", (cmd) => {
     cmd.reply("hello from s2script");
   });
-});
+  hook.on("player_spawn", (ev) => {
+    console.log("spawned", ev.getPlayerSlot("userid"));
+  });
+}
+
+export function OnClientPostAdminCheck(client: Client): void {
+  client.chat("welcome");
+}
 ```
 
 This package is **types-only** — the engine injects the implementation at load time, and

package/commands.d.ts

@@ -57,7 +57,7 @@ export interface CommandInvocation {
    *
    * @example
    * // `!help` answers in chat; `sm_help` typed at a console answers in that console.
-   * ctx.commands.register("sm_help", (cmd) => cmd.reply("[SM] Commands: …"));
+   * command("sm_help", (cmd) => { cmd.reply("[SM] Commands: …"); return HookResult.Handled; });
    */
   reply(message: string): void;
   /**
@@ -81,6 +81,53 @@ export interface CommandInvocation {
    * never in the way. */
   replyT(key: PhraseKey, ...args: (string | number)[]): void;
 }
+
+/** Alias for {@link CommandInvocation} — the SourceMod-shaped name for a parsed invocation. */
+export type Command = CommandInvocation;
+
+/**
+ * A command callback: the parsed invocation, plus an optional {@link HookResultValue}.
+ * SourceMod `Plugin_Handled` is {@link HookResult}.Handled — return it from a command you own
+ * (usage errors included; the command was still consumed). Omit the return (`void`) to continue —
+ * the same as returning {@link HookResult}.Continue. Engine SUPERCEDE-on-Continue is not this API;
+ * chat `!` vs `/` suppress is unchanged.
+ */
+export type CommandHandler = (
+  cmd: CommandInvocation,
+) => HookResultValue | void | Promise<HookResultValue | void>;
+
+/**
+ * Register a public command in the load window (SourceMod `RegConsoleCmd`).
+ * Callable only while `OnPluginStart` is running — throws after settle.
+ *
+ * `.admin` / `.server` are the `RegAdminCmd` / `RegServerCmd` shapes: name the handler anything.
+ *
+ * @example
+ * import { command, ADMFLAG, HookResult } from "@s2script/sdk";
+ * export function OnPluginStart(): void {
+ *   command.admin("sm_kick", ADMFLAG.KICK, kick);
+ * }
+ * function kick(cmd: CommandInvocation): HookResultValue {
+ *   cmd.reply("kicked");
+ *   return HookResult.Handled;
+ * }
+ */
+export declare const command: {
+  (name: string, handler: CommandHandler): void;
+  /** Register an admin command gated by `flags` (an `ADMFLAG` bitmask). */
+  admin(name: string, flags: number, handler: CommandHandler): void;
+  /** Register a server-only command (console/rcon, not client-runnable). */
+  server(name: string, handler: CommandHandler): void;
+  /**
+   * Observe an existing CLIENT command by name — SourceMod's `AddCommandListener`.
+   * Load-window only. Same contract as {@link CtxCommands.onClientCommand} (on PluginContext).
+   */
+  onClientCommand(
+    name: string,
+    handler: (slot: number, argString: string) => HookResultValue | void,
+  ): void;
+};
+
 /** A parsed chat trigger: which command + args, and whether it was the silent (`/`) trigger. */
 export interface ChatTrigger {
   /** `true` = the silent trigger (`/`, hidden); `false` = the public trigger (`!`). */
@@ -93,9 +140,9 @@ export interface ChatTrigger {
 
 /**
  * Command-registry utilities: dispatch by name, parse/route chat triggers, and enumerate the global
- * registry. Commands themselves are registered through the plugin context (`ctx.commands.register*`).
+ * registry. Commands themselves are registered in the load window via {@link command}.
  * @example
- * import { Commands } from "@s2script/sdk/commands";
+ * import { Commands } from "@s2script/sdk";
  * // sm_help backend: every registered command + its required admin flag mask.
  * const cmds = Commands.list().slice().sort((a, b) => (a.name < b.name ? -1 : 1));
  */
@@ -122,7 +169,7 @@ export declare const Commands: {
   /**
    * Observe a CLIENT command by name — SourceMod's `AddCommandListener`.
    *
-   * Unlike {@link register}, which CREATES a command, this hooks one that already exists — including
+   * Unlike {@link command}, which CREATES a command, this hooks one that already exists — including
    * commands the engine itself owns (`player_ping`, `jointeam`, `drop`, `buy`). Registering a
    * ConCommand of an engine-owned name fails outright ("unable to link multiple ConCommands named
    * X"), so this is the only way to see those.
@@ -133,7 +180,7 @@ export declare const Commands: {
    *
    * @example
    * // Middle-mouse ping opens the shop, and still places the ping.
-   * ctx.commands.onClientCommand("player_ping", (slot) => { openShop(slot); });
+   * command.onClientCommand("player_ping", (slot) => { openShop(slot); });
    */
   onClientCommand(name: string, handler: (slot: number, argString: string) => HookResultValue | void): void;
   /** Every globally-registered command with its required admin `flags`: `0` = anyone, `-1` = console/server-only,

package/config.d.ts

@@ -23,4 +23,9 @@ export declare const config: {
   readFile(name: string): string | null;
   /** Write a raw file to the configs dir (creates/overwrites). */
   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`).
+   */
+  onChange(handler: (cfg: Config) => void): void;
 };

package/damage.d.ts

@@ -1,18 +1,23 @@
 /**
- * @s2script/damage — damage pre-hooks (SDKHooks-equivalent). NO runtime code (injected at load).
- * CTakeDamageInfo is a Source 2 engine type, so this module is engine-generic (lives in core).
+ * @s2script/damage — the block-scoped {@link DamageInfo} view of a live `CTakeDamageInfo`.
+ * NO runtime code (injected at load). Engine-generic: `CTakeDamageInfo` is a Source 2 type.
+ *
+ * Subscribe with `SDKHook` (`SDKHookType.OnTakeDamage` / `OnTakeDamagePost`), not a global mux.
  */
 import type { EntityRef } from "./entity";
 
 /**
- * A block-scoped view of the current damage event (valid only inside a Damage.onPre handler).
+ * A block-scoped view of the current damage event (valid only inside an `OnTakeDamage` or
+ * `OnTakeDamagePost` SDKHook).
  * @example
- * import type { DamageInfo } from "@s2script/sdk/damage";
- * // plugins/basecommands/src/plugin.ts:81 — halve the damage (assign 0 to block it entirely)
- * ctx.entities.onDamage((info: DamageInfo) => { info.damage = info.damage / 2; });
+ * import type { DamageInfo } from "@s2script/sdk";
+ * function onTakeDamage(info: DamageInfo) { info.damage = info.damage / 2; }
  */
 export interface DamageInfo {
-  /** The damage amount (m_flDamage). Assigning MODIFIES the live damage; set to 0 to block. */
+  /**
+   * The damage amount (`m_flDamage`). On the pre-hook, assigning MODIFIES the live damage; set to
+   * 0 to block. On `OnTakeDamagePost`, assignment is ignored (the original already ran).
+   */
   damage: number;
   /** The damage-type bit flags (m_bitsDamageType). */
   readonly damageType: number;

package/dist/cli.js

@@ -3126,8 +3126,8 @@ var sharedCompilerOptionsJson = {
   noEmit: true,
   moduleResolution: "bundler",
   module: "ESNext",
-  target: "ES2020",
-  lib: ["ES2020"],
+  target: "ES2024",
+  lib: ["ES2024"],
   types: [],
   skipLibCheck: true,
   allowImportingTsExtensions: true
@@ -3139,7 +3139,7 @@ function sharedProgramOptions(tsMod) {
     allowImportingTsExtensions: sharedCompilerOptionsJson.allowImportingTsExtensions,
     moduleResolution: tsMod.ModuleResolutionKind.Bundler,
     module: tsMod.ModuleKind.ESNext,
-    target: tsMod.ScriptTarget.ES2020,
+    target: tsMod.ScriptTarget.ES2024,
     lib: sharedCompilerOptionsJson.lib.map((l2) => `lib.${l2.toLowerCase()}.d.ts`),
     types: [...sharedCompilerOptionsJson.types],
     skipLibCheck: sharedCompilerOptionsJson.skipLibCheck
@@ -3795,7 +3795,7 @@ function typecheckPlugin(pluginDir, opts) {
   const entryRel = s2.main ?? pkg.main;
   if (!entryRel) throw new Error(`typecheckPlugin: no entry point in ${join7(absDir, "package.json")}`);
   const entry = resolve6(absDir, entryRel);
-  const isAlwaysResolved = (d) => d.startsWith("@s2script/sdk/") || d === "@s2script/cs2" || d.startsWith("@s2script/cs2/");
+  const isAlwaysResolved = (d) => d === "@s2script/sdk" || d.startsWith("@s2script/sdk/") || d === "@s2script/cs2" || d.startsWith("@s2script/cs2/");
   const localDts = localDeclarationFiles(absDir);
   const locallyDeclared = declaredModules(localDts);
   const allDeclaredDeps = [
@@ -3829,10 +3829,12 @@ function typecheckPlugin(pluginDir, opts) {
     ...sharedProgramOptions(ts),
     baseUrl: packagesDir,
     paths: {
-      // Builtins are `@s2script/sdk/<cap>` → packages/sdk/<cap>.d.ts. The `@s2script/*` fallback
-      // now serves only @s2script/cs2 → packages/cs2/index.d.ts (the legacy per-package builtin
-      // dirs are deleted). tsc picks the longest matching prefix, so `@s2script/sdk/*` wins for
-      // sdk imports.
+      // Builtins: the root barrel `@s2script/sdk` → packages/sdk/index.d.ts; subpaths
+      // `@s2script/sdk/<cap>` → packages/sdk/<cap>.d.ts. The `@s2script/*` fallback serves
+      // @s2script/cs2 → packages/cs2/index.d.ts (and would also hit sdk/index.d.ts; the exact
+      // `@s2script/sdk` entry makes the barrel obvious). tsc picks the longest matching prefix,
+      // so `@s2script/sdk/*` wins for capability imports.
+      "@s2script/sdk": ["sdk/index.d.ts"],
       "@s2script/sdk/*": ["sdk/*.d.ts"],
       // Game-package SUBPATHS (e.g. @s2script/cs2/econ -> packages/cs2/econ.d.ts). Needed because
       // the `@s2script/*` fallback below maps to `<pkg>/index.d.ts`, which cannot express a
@@ -4171,31 +4173,60 @@ function isPluginContext(type) {
   const sym = type.getSymbol() ?? type.aliasSymbol;
   return sym?.getName() === "PluginContext";
 }
+function isFromPluginDts(checker, node) {
+  let sym = checker.getSymbolAtLocation(node);
+  if (sym === void 0) return false;
+  if (sym.flags & ts2.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(sym);
+    if (aliased !== void 0) sym = aliased;
+  }
+  for (const d of sym.declarations ?? []) {
+    const f = d.getSourceFile().fileName.replace(/\\/g, "/");
+    if (f.endsWith("/plugin.d.ts")) return true;
+  }
+  return false;
+}
+function recordPublishOrUse(out, method, arg0, sf, node) {
+  if (method === "publish") {
+    if (arg0 !== void 0 && ts2.isStringLiteralLike(arg0)) {
+      out.publishNames.push(arg0.text);
+    } else {
+      const { line } = sf.getLineAndCharacterOfPosition(node.getStart());
+      out.dynamicPublishSites.push(`${sf.fileName}:${line + 1}`);
+    }
+  } else if (arg0 !== void 0 && ts2.isStringLiteralLike(arg0)) {
+    out.useNames.push(arg0.text);
+  }
+}
+function recordImportSpecifier(out, spec) {
+  if (spec.startsWith(".") || spec.startsWith("@s2script/")) return;
+  out.importNames.push(spec);
+}
 function scanPluginProgram(program, pluginDir) {
   const checker = program.getTypeChecker();
-  const out = { publishNames: [], dynamicPublishSites: [], useNames: [] };
+  const out = { publishNames: [], dynamicPublishSites: [], useNames: [], importNames: [] };
   const dirPrefix = pluginDir.replace(/\\/g, "/").replace(/\/+$/, "") + "/";
   for (const sf of program.getSourceFiles()) {
     if (sf.isDeclarationFile) continue;
     if (!sf.fileName.replace(/\\/g, "/").startsWith(dirPrefix)) continue;
     const visit = (node) => {
-      if (ts2.isCallExpression(node) && ts2.isPropertyAccessExpression(node.expression)) {
-        const method = node.expression.name.text;
-        if (method === "publish" || method === "use" || method === "tryUse") {
-          const recv = checker.getTypeAtLocation(node.expression.expression);
-          if (isPluginContext(recv)) {
-            const arg0 = node.arguments[0];
-            if (method === "publish") {
-              if (arg0 !== void 0 && ts2.isStringLiteralLike(arg0)) {
-                out.publishNames.push(arg0.text);
-              } else {
-                const { line } = sf.getLineAndCharacterOfPosition(node.getStart());
-                out.dynamicPublishSites.push(`${sf.fileName}:${line + 1}`);
-              }
-            } else if (arg0 !== void 0 && ts2.isStringLiteralLike(arg0)) {
-              out.useNames.push(arg0.text);
+      if ((ts2.isImportDeclaration(node) || ts2.isExportDeclaration(node)) && node.moduleSpecifier !== void 0 && ts2.isStringLiteralLike(node.moduleSpecifier)) {
+        recordImportSpecifier(out, node.moduleSpecifier.text);
+      }
+      if (ts2.isCallExpression(node)) {
+        if (ts2.isPropertyAccessExpression(node.expression)) {
+          const method = node.expression.name.text;
+          if (method === "publish" || method === "use" || method === "tryUse") {
+            const recv = checker.getTypeAtLocation(node.expression.expression);
+            if (isPluginContext(recv)) {
+              recordPublishOrUse(out, method, node.arguments[0], sf, node);
             }
           }
+        } else if (ts2.isIdentifier(node.expression)) {
+          const name = node.expression.text;
+          if ((name === "publish" || name === "use" || name === "tryUse") && isFromPluginDts(checker, node.expression)) {
+            recordPublishOrUse(out, name, node.arguments[0], sf, node);
+          }
         }
       }
       ts2.forEachChild(node, visit);
@@ -4204,6 +4235,7 @@ function scanPluginProgram(program, pluginDir) {
   }
   out.publishNames = [...new Set(out.publishNames)];
   out.useNames = [...new Set(out.useNames)];
+  out.importNames = [...new Set(out.importNames)];
   return out;
 }
 
@@ -4569,12 +4601,14 @@ function emitHookDts(model) {
       out.push(...emitViewIface(h2));
     }
   }
-  for (const { ctxIface, hooks } of model) {
+  for (const { ctxIface, hooks, ns } of model) {
     out.push(`export interface ${ctxIface} {`);
     for (const h2 of hooks) {
       out.push(`  ${h2.name}(handler: (view: ${h2.viewIface}) => HookResultValue | void): void;`);
     }
     out.push("}", "");
+    out.push(`export declare const ${ns}: ${ctxIface};`);
+    out.push("");
   }
   out.push('declare module "@s2script/sdk/plugin" {');
   out.push("  interface PluginContext {");
@@ -4837,13 +4871,16 @@ ${lint.output}`);
   for (const used of scan.useNames) {
     if (!declaredDeps.has(used)) {
       console.warn(
-        `WARN: ctx.use/tryUse(${JSON.stringify(used)}) is not declared under s2script.pluginDependencies/optionalPluginDependencies \u2014 it will throw at runtime`
+        `WARN: use()/tryUse(${JSON.stringify(used)}) is not declared under s2script.pluginDependencies/optionalPluginDependencies \u2014 it will throw at runtime`
       );
     }
   }
+  const referenced = /* @__PURE__ */ new Set([...scan.useNames, ...scan.importNames]);
   for (const dep of declaredDeps) {
-    if (!scan.useNames.includes(dep)) {
-      console.warn(`WARN: dependency ${JSON.stringify(dep)} is declared but never ctx.use()d`);
+    if (!referenced.has(dep)) {
+      console.warn(
+        `WARN: dependency ${JSON.stringify(dep)} is declared but never ctx.use()d or imported`
+      );
     }
   }
   const { name, version } = pkg;
@@ -4871,7 +4908,7 @@ ${lint.output}`);
     platform: "neutral",
     format: "cjs",
     external,
-    target: "es2020",
+    target: "es2024",
     // platform:"neutral" defaults mainFields to EMPTY, so a workspace-sibling package that
     // declares `main` (rather than `exports`) fails to resolve with an undiagnosable error.
     // Set it explicitly so a monorepo plugin bundles whichever field the author wrote.
@@ -8071,29 +8108,33 @@ function fileDevDeps(packagesDir, game) {
 }
 function pluginSource(game) {
   if (game === "cs2") {
-    return `import { plugin } from "@s2script/sdk/plugin";
-import { Chat } from "@s2script/sdk/chat";
+    return `import { command, Chat, HookResult } from "@s2script/sdk";
+import type { Command, HookResultValue } from "@s2script/sdk";
 
-export default plugin((ctx) => {
-  ctx.commands.register("hello", (cmd) => {
-    cmd.reply("hello from s2script");
-    if (cmd.callerSlot >= 0) {
-      Chat.toSlot(cmd.callerSlot, "hello from s2script");
-    }
-  });
-});
+export function OnPluginStart(): void {
+  command("hello", hello);
+}
+
+function hello(cmd: Command): HookResultValue {
+  cmd.reply("hello from s2script");
+  if (cmd.callerSlot >= 0) {
+    Chat.toSlot(cmd.callerSlot, "hello from s2script");
+  }
+  return HookResult.Handled;
+}
 `;
   }
-  return `import { plugin } from "@s2script/sdk/plugin";
-import { delay } from "@s2script/sdk/timers";
+  return `import { delay } from "@s2script/sdk";
 
-export default plugin((ctx) => {
-  let n = 0;
-  ctx.server.onGameFrame(() => {
-    n += 1;
-  });
+let n = 0;
+
+export function OnPluginStart(): void {
   void delay(1000).then(() => console.log("s2script plugin alive; frames so far:", n));
-});
+}
+
+export function OnGameFrame(): void {
+  n += 1;
+}
 `;
 }
 var LIBRARY_ENTRY = `/** Encode a string. Replace this with the library's real surface. */

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/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.22.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;

package/sdkhooks.d.ts

@@ -0,0 +1,543 @@
+/**
+ * @s2script/sdkhooks — per-entity SDKHooks (SourceMod `SDKHook` / `SDKUnhook`).
+ * NO runtime code: the engine injects the implementation at load time.
+ */
+import type { EntityRef } from "./entity";
+import type { DamageInfo } from "./damage";
+import type { HookResultValue } from "./events";
+import type { Client } from "./clients";
+
+type TouchCallback = (entity: EntityRef, other: EntityRef | null) => HookResultValue | void;
+type TouchPostCallback = (entity: EntityRef, other: EntityRef | null) => void;
+type WeaponCallback = (entity: EntityRef, weapon: EntityRef | null) => HookResultValue | void;
+type WeaponPostCallback = (entity: EntityRef, weapon: EntityRef | null) => void;
+type ThisCallback = (entity: EntityRef) => HookResultValue | void;
+type ThisVoidCallback = (entity: EntityRef) => void;
+type FireBulletsPostCallback = (entity: EntityRef, shots: number, weaponName: string) => void;
+type ReloadPostCallback = (weapon: EntityRef, successful: boolean) => void;
+type UseCallback = (
+  entity: EntityRef,
+  activator: EntityRef | null,
+  caller: EntityRef | null,
+  type: UseTypeValue,
+  value: number,
+) => HookResultValue | void;
+type UsePostCallback = (
+  entity: EntityRef,
+  activator: EntityRef | null,
+  caller: EntityRef | null,
+  type: UseTypeValue,
+  value: number,
+) => void;
+
+/**
+ * `CBaseEntity::Use` use-type (`USE_OFF` / `USE_ON` / `USE_SET` / `USE_TOGGLE`).
+ */
+export type UseTypeValue = 0 | 1 | 2 | 3;
+
+/**
+ * `CBaseEntity::Use` use-type constants (wiki `USE_*`).
+ */
+export declare const UseType: {
+  /** `USE_OFF` — turn off. */
+  readonly Off: 0;
+  /** `USE_ON` — turn on. */
+  readonly On: 1;
+  /** `USE_SET` — set to `value`. */
+  readonly Set: 2;
+  /** `USE_TOGGLE` — toggle. */
+  readonly Toggle: 3;
+};
+
+/**
+ * Shipped SDKHook types. Wiki names without the `SDKHook_` prefix. A wiki name whose engine
+ * backing failed or is absent returns `false` from {@link SDKHook} (does not throw). A string
+ * that is not a member here throws.
+ */
+export declare const SDKHookType: {
+  /** Pre-apply damage (`DispatchTraceAttack`). Mutate {@link DamageInfo.damage} in place. */
+  readonly OnTakeDamage: "OnTakeDamage";
+  /**
+   * CheckTransmit mux (wiki `SDKHook_SetTransmit`). `Handled` / `Stop` hide this entity from this
+   * viewer. AND-merge with `Transmit.setVisibleTo`: either API can hide; SetTransmit cannot
+   * un-hide a native mask clear. There is no `SetTransmitPost`.
+   */
+  readonly SetTransmit: "SetTransmit";
+  /** `CBaseEntity::StartTouch` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly StartTouch: "StartTouch";
+  /** `CBaseEntity::Touch` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Touch: "Touch";
+  /** `CBaseEntity::EndTouch` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly EndTouch: "EndTouch";
+  /** `CBaseEntity::Blocked` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Blocked: "Blocked";
+  /** `StartTouch` post. Return is ignored. */
+  readonly StartTouchPost: "StartTouchPost";
+  /** `Touch` post. Return is ignored. */
+  readonly TouchPost: "TouchPost";
+  /** `EndTouch` post. Return is ignored. */
+  readonly EndTouchPost: "EndTouchPost";
+  /** `Blocked` post. Return is ignored. */
+  readonly BlockedPost: "BlockedPost";
+  /** `CBaseEntity::Spawn` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Spawn: "Spawn";
+  /** `Spawn` post. Return is ignored. */
+  readonly SpawnPost: "SpawnPost";
+  /** `CBaseEntity::Think` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Think: "Think";
+  /** `Think` post. Return is ignored. */
+  readonly ThinkPost: "ThinkPost";
+  /** Player `PreThink`. Return is ignored. */
+  readonly PreThink: "PreThink";
+  /** `PreThink` post. Return is ignored. */
+  readonly PreThinkPost: "PreThinkPost";
+  /** Player `PostThink`. Return is ignored. */
+  readonly PostThink: "PostThink";
+  /** `PostThink` post. Return is ignored. */
+  readonly PostThinkPost: "PostThinkPost";
+  /** `CBaseEntity::Use` pre. `Handled` / `Stop` skip the original virtual. */
+  readonly Use: "Use";
+  /** `Use` post. Return is ignored. */
+  readonly UsePost: "UsePost";
+  /** `GetMaxHealth`. Mutate `info.maxHealth`. `Handled` / `Stop` SUPERCEDE the original. */
+  readonly GetMaxHealth: "GetMaxHealth";
+  /** `ShouldCollide`. Return a boolean (not {@link HookResultValue}); last defined wins. */
+  readonly ShouldCollide: "ShouldCollide";
+  /** `VPhysicsUpdate`. Return is ignored. */
+  readonly VPhysicsUpdate: "VPhysicsUpdate";
+  /** `VPhysicsUpdate` post. Return is ignored. */
+  readonly VPhysicsUpdatePost: "VPhysicsUpdatePost";
+  /** `GroundEntChanged` post. Return is ignored. */
+  readonly GroundEntChangedPost: "GroundEntChangedPost";
+  /** `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.
+   */
+  readonly OnTakeDamagePost: "OnTakeDamagePost";
+  /**
+   * `OnTakeDamageAlive` pre. CS2 has no distinct function yet — {@link SDKHook} returns `false`.
+   */
+  readonly OnTakeDamageAlive: "OnTakeDamageAlive";
+  /**
+   * `OnTakeDamageAlive` post. CS2 has no distinct function yet — {@link SDKHook} returns `false`.
+   */
+  readonly OnTakeDamageAlivePost: "OnTakeDamageAlivePost";
+  /**
+   * `TraceAttack` pre ({@link TraceAttackInfo}). No distinct CS2 virtual yet — {@link SDKHook}
+   * returns `false` (OnTakeDamage remains the DTA mux).
+   */
+  readonly TraceAttack: "TraceAttack";
+  /**
+   * `TraceAttack` post. No distinct CS2 virtual yet — {@link SDKHook} returns `false`.
+   */
+  readonly TraceAttackPost: "TraceAttackPost";
+  /**
+   * `FireBulletsPost`. Wiki already documents this as often absent. {@link SDKHook} returns `false`
+   * until a live path is found.
+   */
+  readonly FireBulletsPost: "FireBulletsPost";
+  /** Weapon reload pre. `Handled` / `Stop` skip the original virtual. Missing VP → `false`. */
+  readonly Reload: "Reload";
+  /** Weapon reload post. `(weapon, successful)`. No bool-return thunk yet — {@link SDKHook} returns `false`. */
+  readonly ReloadPost: "ReloadPost";
+  /** `WeaponCanUse` pre. Callback is `(entity, weapon)`. Missing ItemServices VP → `false`. */
+  readonly WeaponCanUse: "WeaponCanUse";
+  /** `WeaponCanUse` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponCanUsePost: "WeaponCanUsePost";
+  /** `WeaponCanSwitchTo` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponCanSwitchTo: "WeaponCanSwitchTo";
+  /** `WeaponCanSwitchTo` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponCanSwitchToPost: "WeaponCanSwitchToPost";
+  /** `WeaponDrop` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponDrop: "WeaponDrop";
+  /** `WeaponDrop` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponDropPost: "WeaponDropPost";
+  /** `WeaponEquip` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponEquip: "WeaponEquip";
+  /** `WeaponEquip` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponEquipPost: "WeaponEquipPost";
+  /** `WeaponSwitch` pre. Callback is `(entity, weapon)`. Missing VP → `false`. */
+  readonly WeaponSwitch: "WeaponSwitch";
+  /** `WeaponSwitch` post. Return is ignored. Missing VP → `false`. */
+  readonly WeaponSwitchPost: "WeaponSwitchPost";
+};
+
+/**
+ * Block-scoped view of a `TraceAttack` callback. Mutate {@link TraceAttackInfo.damage} on the
+ * pre-hook. Valid only during the handler.
+ */
+export interface TraceAttackInfo {
+  /** Incoming damage. Mutate in place on the pre-hook. */
+  damage: number;
+  /** Damage type bits. */
+  readonly damageType: number;
+  /** Ammo type index. */
+  readonly ammoType: number;
+  /** Hitbox index. */
+  readonly hitbox: number;
+  /** Hitgroup index. */
+  readonly hitgroup: number;
+  /** Attacking entity, books-gated. */
+  readonly attacker: EntityRef | null;
+  /** Inflicting entity, books-gated. */
+  readonly inflictor: EntityRef | null;
+  /** Victim entity, books-gated. */
+  readonly victim: EntityRef | null;
+}
+
+/**
+ * Hook `entity` for `type`. Auto-unhooked on entity destroy and plugin unload.
+ *
+ * Not load-window-only — call from `OnEntityCreated`, `OnPluginStart` (ents already live), or any
+ * time you hold a live {@link EntityRef}.
+ *
+ * `OnTakeDamage`: mutate `info.damage` in place. No return needed. Return `HookResult.Handled` to
+ * zero the hit; `HookResult.Stop` to also skip later hooks.
+ *
+ * @returns `true` if the hook was recorded. `false` on `null`/stale `entity` (does not throw).
+ * @example
+ * import { SDKHook, SDKHookType, Entity } from "@s2script/sdk";
+ * import type { EntityRef, DamageInfo } from "@s2script/sdk";
+ *
+ * export function OnPluginStart(): void {
+ *   for (const pawn of Entity.findByClass("player")) {
+ *     SDKHook(pawn, SDKHookType.OnTakeDamage, onTakeDamage);
+ *   }
+ * }
+ * export function OnEntityCreated(entity: EntityRef | null, className: string): void {
+ *   if (!entity || className !== "player") return;
+ *   SDKHook(entity, SDKHookType.OnTakeDamage, onTakeDamage);
+ * }
+ * function onTakeDamage(info: DamageInfo) {
+ *   info.damage /= 2;
+ * }
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamage",
+  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).
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamagePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/**
+ * `OnTakeDamageAlive` pre. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlive",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/**
+ * `OnTakeDamageAlive` post. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlivePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/**
+ * `TraceAttack` pre. No distinct CS2 virtual yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "TraceAttack",
+  callback: (info: TraceAttackInfo) => HookResultValue | void,
+): boolean;
+/**
+ * `TraceAttack` post. No distinct CS2 virtual yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "TraceAttackPost",
+  callback: (info: TraceAttackInfo) => void,
+): boolean;
+/**
+ * `FireBulletsPost`. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "FireBulletsPost",
+  callback: FireBulletsPostCallback,
+): boolean;
+/**
+ * Touch-family pre-hook. Callback is `(entity, other)`. Omit return = Continue.
+ * `Handled` / `Stop` SUPERCEDE the original virtual (`Stop` also skips later callbacks).
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "StartTouch" | "Touch" | "EndTouch" | "Blocked",
+  callback: TouchCallback,
+): boolean;
+/**
+ * Touch-family post-hook. Return is ignored; the original virtual already ran.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "StartTouchPost" | "TouchPost" | "EndTouchPost" | "BlockedPost",
+  callback: TouchPostCallback,
+): boolean;
+/**
+ * Spawn / Think pre-hook. Callback is `(entity)`. Omit return = Continue.
+ * `Handled` / `Stop` SUPERCEDE the original virtual (`Stop` also skips later callbacks).
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "Spawn" | "Think" | "Reload",
+  callback: ThisCallback,
+): boolean;
+/**
+ * Void this-only hooks (Posts, PreThink/PostThink, VPhysicsUpdate, GroundEntChangedPost).
+ * Return is ignored.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type:
+    | "SpawnPost"
+    | "ThinkPost"
+    | "PreThink"
+    | "PreThinkPost"
+    | "PostThink"
+    | "PostThinkPost"
+    | "VPhysicsUpdate"
+    | "VPhysicsUpdatePost"
+    | "GroundEntChangedPost",
+  callback: ThisVoidCallback,
+): boolean;
+/**
+ * `Use` pre-hook. `Handled` / `Stop` SUPERCEDE the original virtual.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "Use",
+  callback: UseCallback,
+): boolean;
+/**
+ * `Use` post-hook. Return is ignored.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "UsePost",
+  callback: UsePostCallback,
+): boolean;
+/**
+ * `GetMaxHealth`. Mutate `info.maxHealth` in place. `Handled` / `Stop` SUPERCEDE with the new value.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "GetMaxHealth",
+  callback: (info: { maxHealth: number }) => HookResultValue | void,
+): boolean;
+/**
+ * `ShouldCollide`. Return a boolean (not HookResult); last defined return wins, default original.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "ShouldCollide",
+  callback: (
+    entity: EntityRef,
+    collisionGroup: number,
+    contentsMask: number,
+    originalResult: boolean,
+  ) => boolean,
+): boolean;
+/**
+ * `CanBeAutobalanced`. Return a boolean (not HookResult); last defined return wins, default original.
+ * Callback is skipped when the hooked entity has no {@link Client} — never a raw slot `0`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "CanBeAutobalanced",
+  callback: (client: Client, origRet: boolean) => boolean,
+): boolean;
+/**
+ * SetTransmit. Callback is `(entity, client)`. Omit return = Continue.
+ * `Handled` / `Stop` hide this entity from this viewer (AND-merge with `Transmit.setVisibleTo`;
+ * cannot un-hide a native mask clear). `Stop` also skips later SetTransmit callbacks on that pair.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "SetTransmit",
+  callback: (entity: EntityRef, client: Client) => HookResultValue | void,
+): boolean;
+/**
+ * Weapon-family pre-hook. Callback is `(entity, weapon)`. Omit return = Continue.
+ * `Handled` / `Stop` SUPERCEDE the original virtual. Missing ItemServices VP → `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "WeaponCanUse" | "WeaponCanSwitchTo" | "WeaponDrop" | "WeaponEquip" | "WeaponSwitch",
+  callback: WeaponCallback,
+): boolean;
+/**
+ * Weapon-family post-hook. Return is ignored. Missing VP → `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type:
+    | "WeaponCanUsePost"
+    | "WeaponCanSwitchToPost"
+    | "WeaponDropPost"
+    | "WeaponEquipPost"
+    | "WeaponSwitchPost",
+  callback: WeaponPostCallback,
+): boolean;
+/**
+ * `ReloadPost`. Callback is `(weapon, successful)`. No CS2 backing yet — always returns `false`.
+ */
+export declare function SDKHook(
+  entity: EntityRef | null,
+  type: "ReloadPost",
+  callback: ReloadPostCallback,
+): boolean;
+
+/**
+ * Remove one matching `(entity, type, callback)` hook. Callback identity is the function reference.
+ * @returns `true` if an entry was removed.
+ */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamage",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/** Remove an `OnTakeDamagePost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamagePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/** Remove an `OnTakeDamageAlive` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlive",
+  callback: (info: DamageInfo) => HookResultValue | void,
+): boolean;
+/** Remove an `OnTakeDamageAlivePost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "OnTakeDamageAlivePost",
+  callback: (info: DamageInfo) => void,
+): boolean;
+/** Remove a `TraceAttack` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "TraceAttack",
+  callback: (info: TraceAttackInfo) => HookResultValue | void,
+): boolean;
+/** Remove a `TraceAttackPost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "TraceAttackPost",
+  callback: (info: TraceAttackInfo) => void,
+): boolean;
+/** Remove a `FireBulletsPost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "FireBulletsPost",
+  callback: FireBulletsPostCallback,
+): boolean;
+/** Remove a Touch-family pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "StartTouch" | "Touch" | "EndTouch" | "Blocked",
+  callback: TouchCallback,
+): boolean;
+/** Remove a Touch-family post-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "StartTouchPost" | "TouchPost" | "EndTouchPost" | "BlockedPost",
+  callback: TouchPostCallback,
+): boolean;
+/** Remove a Spawn / Think pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "Spawn" | "Think" | "Reload",
+  callback: ThisCallback,
+): boolean;
+/** Remove a void this-only hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type:
+    | "SpawnPost"
+    | "ThinkPost"
+    | "PreThink"
+    | "PreThinkPost"
+    | "PostThink"
+    | "PostThinkPost"
+    | "VPhysicsUpdate"
+    | "VPhysicsUpdatePost"
+    | "GroundEntChangedPost",
+  callback: ThisVoidCallback,
+): boolean;
+/** Remove a `Use` pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "Use",
+  callback: UseCallback,
+): boolean;
+/** Remove a `Use` post-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "UsePost",
+  callback: UsePostCallback,
+): boolean;
+/** Remove a `GetMaxHealth` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "GetMaxHealth",
+  callback: (info: { maxHealth: number }) => HookResultValue | void,
+): boolean;
+/** Remove a `ShouldCollide` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "ShouldCollide",
+  callback: (
+    entity: EntityRef,
+    collisionGroup: number,
+    contentsMask: number,
+    originalResult: boolean,
+  ) => boolean,
+): boolean;
+/** Remove a `CanBeAutobalanced` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "CanBeAutobalanced",
+  callback: (client: Client, origRet: boolean) => boolean,
+): boolean;
+/** Remove a SetTransmit hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "SetTransmit",
+  callback: (entity: EntityRef, client: Client) => HookResultValue | void,
+): boolean;
+/** Remove a Weapon-family pre-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "WeaponCanUse" | "WeaponCanSwitchTo" | "WeaponDrop" | "WeaponEquip" | "WeaponSwitch",
+  callback: WeaponCallback,
+): boolean;
+/** Remove a Weapon-family post-hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type:
+    | "WeaponCanUsePost"
+    | "WeaponCanSwitchToPost"
+    | "WeaponDropPost"
+    | "WeaponEquipPost"
+    | "WeaponSwitchPost",
+  callback: WeaponPostCallback,
+): boolean;
+/** Remove a `ReloadPost` hook. */
+export declare function SDKUnhook(
+  entity: EntityRef | null,
+  type: "ReloadPost",
+  callback: ReloadPostCallback,
+): boolean;

package/translations.d.ts

@@ -13,13 +13,15 @@ export type Phrases = Record<string, string>;
  * for it automatically, the same rule SourceMod's `LoadTranslations` enforces:
  *
  * @example
- * export default plugin((ctx) => {
- *   ctx.translations.load("basecomm", "common");
- *   ctx.commands.registerAdmin("sm_gag", ADMFLAG.CHAT, (cmd) => {
+ * import { command, translations } from "@s2script/sdk";
+ * import { ADMFLAG } from "@s2script/sdk";
+ * export function OnPluginStart(): void {
+ *   translations.load("basecomm", "common");
+ *   command.admin("sm_gag", ADMFLAG.CHAT, (cmd) => {
  *     cmd.replyT("Usage Gag");                                  // key-checked
  *     Chat.toSlot(p.slot, Translations.translate(p.slot, "Gagged Player", n));
  *   });
- * });
+ * }
  *
  * Keys are checked against the files that plugin loads — see `@s2script/sdk/phrases`.
  */