@s2script/sdk 0.3.0 → 0.5.0

package/entity.d.ts

@@ -2,21 +2,28 @@
  * @s2script/entity — author-time type stubs for the injected entity API.
  * NO runtime code: the engine injects the implementation at load time.
  */
-import type { HookResultValue } from "./events";
 
 /**
- * A serial-gated handle to a live entity. Wraps the `__s2_ent_ref_*` natives; the raw
- * entity pointer never crosses to JS. All accessors degrade safely (return null/false)
- * when the entity slot has been reused or the ops table is absent.
+ * A host-liveness-gated handle to a live entity. `id` is a HOST-MINTED monotonic liveness
+ * id — liveness is decided by the host's books (fed by engine create/delete notifications,
+ * cleared at map transition), NEVER by reading the entity's own memory. Every access
+ * re-resolves: books first, then identity-slot validation, instance last. A stale ref
+ * degrades to null/false — including across a changelevel.
+ *
+ * The framework mints every `EntityRef`; plugin code never constructs one (the constructor
+ * is intentionally not part of the public surface — a hand-built ref is the "raw ref across
+ * time" footgun). Obtain refs from the engine (events, `findByClass`, `readHandle`, …).
  */
 export declare class EntityRef {
   readonly index: number;
-  readonly serial: number;
+  /** The host-minted liveness id for this ref (books key). Not the raw engine serial. */
+  readonly id: number;
   /** This entity's targetname (`CEntityIdentity::m_name`) — e.g. a map trigger's `"map_start"`. `""` if
    *  the entity has no targetname; `null` if the ref is stale/invalid. */
   readonly name: string | null;
-  constructor(index: number, serial: number);
-  /** True iff the slot's current serial still matches the captured serial. */
+  /** @internal The host mints refs; this is not part of the public API surface. */
+  private constructor();
+  /** True iff the host's books say live AND the identity slot still matches. */
   isValid(): boolean;
   /** Read an i32 at `offset` bytes into the entity, or null if the ref is stale. */
   readInt32(offset: number): number | null;
@@ -68,9 +75,9 @@ export declare class EntityRef {
    *  is null. */
   readFloatsChain(ptrOffs: number[], finalOff: number, count: number): number[] | null;
   /** Follow a pointer chain (each an offset), then read a scalar at `finalOff`. null if the root is stale or any
-   *  hop is null. `readHandleVia` decodes a handle field → a serial-gated EntityRef; vectors use readFloatsChain. */
+   *  hop is null. `readHandleVia` decodes a handle field → a liveness-gated EntityRef; vectors use readFloatsChain. */
   readInt32Via(pathOffs: number[], finalOff: number): number | null;
-  /** Write an int32 at the end of a pointer chain (each hop deref'd, serial-gated at the root). Returns
+  /** Write an int32 at the end of a pointer chain (each hop deref'd, liveness-gated at the root). Returns
    *  false on a stale ref or a null hop. Used to clear a flag on a pointer-referenced sub-object. */
   writeInt32Via(pathOffs: number[], finalOff: number, value: number): boolean;
   readInt8Via(pathOffs: number[], finalOff: number): number | null;
@@ -83,7 +90,7 @@ export declare class EntityRef {
   readUInt64Via(pathOffs: number[], finalOff: number): bigint | null;
   readInt64Via(pathOffs: number[], finalOff: number): bigint | null;
   readHandleVia(pathOffs: number[], finalOff: number): EntityRef | null;
-  /** Write a scalar through a pointer chain (write mirror of `read*Via`). Serial-gated at the root;
+  /** Write a scalar through a pointer chain (write mirror of `read*Via`). Liveness-gated at the root;
    *  returns false on a stale ref, an unresolved hop, or a bad offset/kind. Does NOT notifyStateChanged —
    *  the caller decides (many sub-object fields, e.g. the fire gate, are server-authoritative).
    *  (`writeInt32Via` is declared above alongside `readInt32Via`.) */
@@ -93,6 +100,8 @@ export declare class EntityRef {
   readHandle(offset: number): EntityRef | null;
   /** Notify the engine that the field at `offset` changed (triggers network replication). No-op if stale. */
   notifyStateChanged(offset: number): void;
+  /** Raw identity-slot flags (engine m_flags), or null when stale/unavailable. Bit meanings are game-specific. */
+  identityFlags(): number | null;
   /** DispatchSpawn this created entity. With keyvalues, the entity's own Spawn() parses them (the
    *  SourceMod DispatchKeyValue / CSSharp DispatchSpawn(kv) mechanism). Returns false if stale,
    *  unresolved, or the keyvalue map is rejected (non-finite number, unsupported value type, empty
@@ -109,7 +118,7 @@ export declare class EntityRef {
    *  `trigger_multiple` needs a model to build the physics volume that fires touch. Returns false
    *  if the op is unavailable or the ref is stale. */
   setModel(name: string): boolean;
-  /** Read a CUtlVector<CHandle> at (ptrOffs chain -> vectorOff) as live serial-gated EntityRefs.
+  /** Read a CUtlVector<CHandle> at (ptrOffs chain -> vectorOff) as live liveness-gated EntityRefs.
    *  Follows the pointer chain, reads count@+0 / elements@+8, caps at maxCount. [] if stale/unresolved. */
   readHandleVector(ptrOffs: number[], vectorOff: number, maxCount?: number): EntityRef[];
   /** Fire an entity input (e.g. "Kill"/"Ignite"/"SetHealth"/"Enable"/"Open"/"FireUser1"/"AddOutput")
@@ -146,31 +155,7 @@ export interface OutputEvent {
   delay: number;
 }
 
-/**
- * Hook Source 2 entity outputs (`func_button`→`OnPressed`, `trigger_multiple`→`OnStartTouch`,
- * `logic_relay`→`OnTrigger`, …) via a `FireOutputInternal` detour. `classname`/`output` accept `"*"`
- * wildcards. The handler runs SYNCHRONOUSLY (may block): returning a `HookResultValue >= Handled`
- * (2/3) SUPPRESSES the output — the original `FireOutputInternal` call is skipped.
- */
 export declare const Entity: {
-  onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
-  /**
-   * Fire when the engine CREATES an entity of `className` (`"*"` = all) — earliest hook; the entity is
-   * barely constructed, schema fields may be zero/default. The handler receives the serial-gated
-   * `entity` (may be `null`) plus its `className`. Prefer `onSpawn` to read fields.
-   */
-  onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
-  /**
-   * Fire after the engine SPAWNS an entity of `className` (`"*"` = all) — `Spawn()` has run, so schema
-   * fields/keyvalues are populated. The useful hook for reading state.
-   */
-  onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
-  /**
-   * Fire as the engine DELETES an entity of `className` (`"*"` = all). The entity is still readable
-   * during the synchronous handler; a stashed ref reads `null` once the slot is freed (serial gate),
-   * never garbage.
-   */
-  onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
-  /** Find every entity whose designer-name (class) exactly matches `className`. Returns serial-gated refs. */
+  /** Find every entity whose designer-name (class) exactly matches `className`. Returns liveness-gated refs. */
   findByClass(className: string): EntityRef[];
 };

package/events.d.ts

@@ -26,19 +26,6 @@ export declare const HookResult: { readonly Continue: 0; readonly Changed: 1; re
 export type HookResultValue = 0 | 1 | 2 | 3;
 
 export declare const Events: {
-  /** Subscribe to a game event by name. The handler runs synchronously when the event fires. */
-  on(name: string, handler: (ev: GameEvent) => void): void;
-  /**
-   * Unsubscribe from a game event by name.
-   *
-   * **Note:** `off` removes ALL of the calling plugin's handlers for the given event name —
-   * handler identity is NOT compared. This matches the engine-op semantics: the mux removes
-   * every subscription the current plugin holds for `name` in one call. Avoid double-subscribing
-   * the same name with different handlers if you need selective removal.
-   */
-  off(name: string, handler: (ev: GameEvent) => void): void;
-  /** Pre-hook: runs before the event broadcasts; may read+modify `ev` and return a HookResult to block. */
-  onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
   /** Fire a game event. 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. */

package/interfaces.d.ts

@@ -4,33 +4,10 @@
  */
 
 /**
- * Handle returned by {@link publishInterface}: lets the producer emit forwarded
+ * Handle returned by `ctx.publish(name, impl)`: lets the producer emit forwarded
  * events to every plugin subscribed to this interface via its `on(event, …)`.
  */
 export interface PublishHandle {
   /** Emit a forwarded event to all consumers subscribed via `interface.on(event, …)`. */
   emit(event: string, payload: unknown): void;
 }
-
-/**
- * Publish a typed inter-plugin interface under `name`. `impl`'s methods become the
- * natives consumers call (`interface.method(...)`); the returned handle's `emit` fans
- * forwarded events out to consumers' `on(event, …)` subscriptions.
- *
- * The interface's VERSION is injected by the host from this plugin's manifest
- * `publishes` map — never passed here, and never written in TypeScript source.
- * Publishing a name the manifest does not declare is refused at load.
- *
- * `impl` is generic over `object` rather than `Record<string, Function>` so that a
- * producer can bind it to its contract — `const impl: Zones = {…}` — which is what
- * actually proves the implementation matches the published `.d.ts`. A TypeScript
- * `interface` has no implicit index signature (only a `type` alias does), so a
- * `Record<…>` parameter would reject every interface-typed contract. The host
- * enumerates `impl`'s own function properties; non-function properties are ignored.
- *
- * Auto-ledgered: the interface is withdrawn (and hard-dep consumers degraded) on unload.
- */
-export declare function publishInterface<T extends object>(
-  name: string,
-  impl: T,
-): PublishHandle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.3.0",
+  "version": "0.5.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",
   "bin": {
@@ -14,7 +14,9 @@
   "dependencies": {
     "esbuild": "^0.25.0",
     "adm-zip": "^0.5.16",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "eslint": "^10.7.0",
+    "@s2script/eslint-plugin": "0.2.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7"
@@ -64,9 +66,6 @@
     "./events": {
       "types": "./events.d.ts"
     },
-    "./frame": {
-      "types": "./frame.d.ts"
-    },
     "./http": {
       "types": "./http.d.ts"
     },
@@ -82,6 +81,9 @@
     "./net": {
       "types": "./net.d.ts"
     },
+    "./plugin": {
+      "types": "./plugin.d.ts"
+    },
     "./plugins": {
       "types": "./plugins.d.ts"
     },

package/plugin.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @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).
+ *
+ * See docs/superpowers/specs/2026-07-20-L1-lifecycle-v2-design.md §1-§3 for the full contract.
+ */
+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 { Config } from "./config";
+import type { PublishHandle } from "./interfaces";
+import type { TopMenuItem } from "./topmenu";
+import type { PrecacheContext } from "./sound";
+import type { UserCmdView } from "./usercmd";
+
+export interface CtxEvents {
+  on(name: string, handler: (ev: GameEvent) => void): void;
+  onPre(name: string, handler: (ev: GameEvent) => HookResultValue | void): void;
+}
+/**
+ * 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
+ * replay (replaying `onConnect` for pre-existing clients would fire auth/ban/reservation logic
+ * out of its real order).
+ */
+export interface CtxClients {
+  onConnect(handler: (client: Client) => void | Promise<void>): void;
+  onPutInServer(handler: (client: Client) => void | Promise<void>): void;
+  onActive(handler: (client: Client) => void | Promise<void>): void;
+  onFullyConnect(handler: (client: Client) => void | Promise<void>): void;
+  onDisconnect(handler: (client: Client) => void): void;
+  onSettingsChanged(handler: (client: Client) => void): void;
+  onVoice(handler: (client: Client) => void): void;
+  onCookiesCached(handler: (client: Client) => void): void;
+  onSay(handler: (slot: number, text: string, teamonly: boolean) => HookResultValue | void): void;
+  onRunCmd(handler: (cmd: UserCmdView, info: { slot: number }) => HookResultValue | void): void;
+}
+export interface CtxEntities {
+  onCreate(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  onSpawn(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  onDelete(className: string, handler: (entity: EntityRef | null, className: string) => void): void;
+  onOutput(classname: string, output: string, handler: (ev: OutputEvent) => HookResultValue | void): void;
+  onDamage(handler: (info: DamageInfo) => HookResultValue | void): void;
+}
+export interface CtxServer {
+  onGameFrame(fn: () => void, opts?: { priority?: "high" | "normal" | "low" | "monitor" }): void;
+  onMapStart(handler: (mapName: string) => void): void;
+  onPrecache(handler: (pc: PrecacheContext) => void): void;
+}
+export interface CtxCommands {
+  register(name: string, handler: (cmd: CommandInvocation) => void): void;
+  registerServer(name: string, handler: (cmd: CommandInvocation) => void): void;
+  registerAdmin(name: string, flags: number, handler: (cmd: CommandInvocation) => void): void;
+}
+export interface CtxConfig { onChange(handler: (cfg: Config) => void): void; }
+export interface CtxTopMenu {
+  addCategory(name: string): void;
+  addItem(category: string, item: TopMenuItem): void;
+}
+
+/** A producer-backed inter-plugin interface: its methods, plus forward subscriptions. */
+export type InterfaceHandle<T extends object> = T & {
+  /** Subscribe to a producer forward. Load-window only (buffered, armed at Active) — like every registration. */
+  on(event: string, handler: (payload: any) => void): void;
+};
+
+export interface Scope {
+  readonly events: CtxEvents;
+  readonly clients: CtxClients;
+  readonly entities: CtxEntities;
+  readonly server: CtxServer;
+  /** Remove every subscription this scope holds; the scope stays usable (re-register on next open). */
+  clear(): void;
+  /** clear() + permanently retire the scope. Idempotent. */
+  dispose(): void;
+  readonly disposed: boolean;
+}
+
+export interface PluginContext {
+  /** This plugin's id (manifest `id`). */
+  readonly id: string;
+  /** The revived hot-reload handoff (the previous instance's `state()` return), or undefined. */
+  readonly previous: unknown;
+  readonly events: CtxEvents;
+  readonly clients: CtxClients;
+  readonly entities: CtxEntities;
+  readonly server: CtxServer;
+  readonly commands: CtxCommands;
+  readonly config: CtxConfig;
+  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. */
+  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;
+  /** Allocate a disposable subscription scope (load-window only — the capability originates at load). */
+  createScope(): Scope;
+}
+
+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. */
+  state?(): unknown;
+}
+export type PluginFactory = (ctx: PluginContext) => void | PluginHooks | Promise<void | PluginHooks>;
+export interface PluginDefinition { readonly __s2plugin: 1; }
+export declare function plugin(factory: PluginFactory): PluginDefinition;

package/plugins.d.ts

@@ -2,8 +2,18 @@
 export interface PluginInfo {
   /** the plugin id (from its manifest). */
   readonly id: string;
-  /** true = running; false = manually unloaded (on disk but not running, via `unload`). */
+  /** true = running; false = not running (loading, waiting, failed, or manually unloaded). Exactly
+   * `state === "running"`. */
   readonly loaded: boolean;
+  /** the plugin's lifecycle state (L1 lifecycle v2):
+   * - `"running"`  — Active (factory settled, armed).
+   * - `"loading"`  — an in-flight factory load (async factory not yet settled).
+   * - `"waiting"`  — parked until a hard-dependency producer is published (or a ~30s timeout).
+   * - `"failed"`   — the load failed (bad artifact, throwing/rejecting factory, publishes mismatch,
+   *                  or a load timeout); the plugin is NOT running.
+   * - `"unloaded"` — on disk but manually unloaded via `unload` (not auto-reloaded until `load`/`reload`).
+   */
+  readonly state: "running" | "loading" | "waiting" | "failed" | "unloaded";
 }
 export declare const Plugins: {
   /** Every loaded/unloaded plugin. */

package/server.d.ts

@@ -27,13 +27,6 @@ export declare const Server: {
     min?: number;
     max?: number;
   }): boolean;
-  /**
-   * Subscribe to map start (fires on every server map startup — the framework event that replaces
-   * polling `Server.mapName` on OnGameFrame). Boot-loaded plugins receive the first map's fire;
-   * a plugin hot-loaded mid-map does NOT get a synthetic fire for the current map — read
-   * `Server.mapName` at load. Torn down automatically on plugin unload.
-   */
-  onMapStart(handler: (mapName: string) => void): void;
   /** The server's configured max client count (`GetMaxClients()`). `0` if unavailable. */
   readonly maxPlayers: number;
   /** The current map name (`GetMapName()`, the BSP). `""` if unavailable. */

package/sound.d.ts

@@ -28,8 +28,4 @@ export declare const Sound: {
    *  function / stale source entity / an empty `recipients` array). An all-bot-skipped recipient
    *  set still emits to nobody (a real engine call, may return a nonzero GUID). */
   emit(name: string, opts?: SoundEmitOptions): number;
-  /** Subscribe to the session resource-manifest build (fires at map load / mapchange). Register
-   *  custom .vsndevts/.vsnd content here so a later emit can play it. A plugin hot-loaded mid-map
-   *  gets its first fire at the NEXT map change. */
-  onPrecache(handler: (ctx: PrecacheContext) => void): void;
 };

package/topmenu.d.ts

@@ -14,10 +14,6 @@ export interface TopMenuSnapshot {
   items: { id: string; category: string; name: string; flags: number }[];
 }
 export declare const TopMenu: {
-  /** Register a category (idempotent; order = first-registration order). */
-  addCategory(name: string): void;
-  /** Register/replace an item under a category (auto-creates the category). */
-  addItem(category: string, item: TopMenuItem): void;
   /** All categories + item metadata (no handlers) — the adminmenu renderer reads this. */
   snapshot(): TopMenuSnapshot;
   /** Fire an item's onSelect (dispatched post-frame to the owner's context). */

package/usercmd.d.ts

@@ -5,14 +5,14 @@
  * Source2-shared concept (`usercmd.proto`), so this module is engine-generic.
  */
 import type { QAngle } from "./math";
-import type { HookResultValue } from "./events";
 
 /**
- * A block-scoped view of the CURRENT tick's usercmd (valid only during a `UserCmd.onRun` handler —
- * a stashed `Cmd` used after the handler returns, or across an `await`, reads/writes nothing).
- * There is exactly ONE `Cmd` instance for the whole process; every handler call operates on it.
+ * A block-scoped view of the CURRENT tick's usercmd (valid only during a `ctx.clients.onRunCmd`
+ * handler — a stashed `UserCmdView` used after the handler returns, or across an `await`,
+ * reads/writes nothing). There is exactly ONE `UserCmdView` instance for the whole process; every
+ * handler call operates on it.
  */
-export interface Cmd {
+export interface UserCmdView {
   /** +forward / -back. Normalized to roughly [-1, 1] (not the legacy ±450 units). */
   forwardMove: number;
   /**
@@ -36,16 +36,3 @@ export interface Cmd {
    */
   clearSubtickMoves(): void;
 }
-
-export declare const UserCmd: {
-  /**
-   * Subscribe to the per-tick input hook. The handler runs SYNCHRONOUSLY during the engine's
-   * usercmd processing, once per player per batched tick; `cmd` is the singleton, block-scoped
-   * current usercmd and `ctx.slot` is the firing player's 0-based slot.
-   *
-   * Return a `HookResultValue >= Handled` to SUPPRESS this tick's input (the game processes a
-   * zeroed/idle command instead); return `Continue`/`undefined` to let the (possibly modified)
-   * command through unblocked.
-   */
-  onRun(handler: (cmd: Cmd, ctx: { slot: number }) => HookResultValue | void): void;
-};

package/frame.d.ts

@@ -1,13 +0,0 @@
-/**
- * @s2script/frame — author-time type stubs for the per-frame subscription API.
- * NO runtime code: the engine injects the implementation at load time.
- */
-
-export interface SubscribeOptions {
-  priority?: number;
-}
-
-export declare const OnGameFrame: {
-  /** Register a callback that fires every game frame. */
-  subscribe(fn: () => void, opts?: SubscribeOptions): void;
-};