@s2script/sdk 0.22.0 → 0.24.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/menu.d.ts

@@ -1,10 +1,13 @@
 /** @s2script/menu — interactive player menus (chat + center backends). NO runtime code (injected at load). */
 
+/** How a menu becomes interactive. Unknown values coerce to `"immediate"`. */
+export type MenuActivation = "immediate" | "tab";
+
 /** The display backend a {@link Menu} renders through — the value of {@link Menu.style}. */
 export declare const enum MenuStyle {
   /** Chat-log backend: numbered lines printed to chat, picked by typing the number. */
   Chat = "chat",
-  /** CS2 center-screen HTML backend: W/S move the cursor, E selects; re-painted each tick. */
+  /** CS2 HUD sheet (both styles paint the same center sheet on CS2). */
   Center = "center",
 }
 /** Why a menu closed without a selection — the {@link MenuCancelEvent.reason}. */
@@ -48,7 +51,7 @@ 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 WASD menu is open (nav still works)
+ * 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})`); });
@@ -62,10 +65,11 @@ export declare class Menu {
   style: MenuStyle;
   /** Append an auto Exit control (default true). */
   exitButton: boolean;
-  /** When true, a renderer that supports it (the CS2 center renderer) freezes the player's movement
-   *  while the menu is open and restores it on close — buttons still register, so WASD nav still works.
-   *  The chat renderer ignores it. Default false (movement allowed, the normal behavior). */
+  /** 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. */
   freezePlayer: boolean;
+  /** `"immediate"` (default) arms cursor on open. `"tab"` paints first and waits for Tab. */
+  activation: MenuActivation;
   /** (info, display) — `info` is returned to onSelect; `display` is shown. */
   addItem(info: string, display: string, opts?: { disabled?: boolean }): void;
   /** Register the callback fired when a player picks an item. Replaces any previous handler. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.22.0",
+  "version": "0.24.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.