@s2script/sdk 0.23.0 → 0.25.0

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.23.0",
+  "version": "0.25.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",

package/plugin.d.ts

@@ -12,7 +12,7 @@ import type { EntityRef, OutputEvent } from "./entity";
 import type { CommandHandler } from "./commands";
 import type { Config } from "./config";
 import type { PublishHandle } from "./interfaces";
-import type { TopMenuItem } from "./topmenu";
+import type { TopMenuItem, TopMenuTab } from "./topmenu";
 import type { PrecacheContext } from "./sound";
 import type { UserCmdView } from "./usercmd";
 
@@ -133,9 +133,14 @@ export interface CtxConfig {
 }
 /** TopMenu (adminmenu) contribution on this plugin's load-scope ({@link PluginContext.topmenu}). */
 export interface CtxTopMenu {
-  /** Add (or reuse) a top-level menu category. */
+  /** Add (or reuse) a top-level menu category. Same as {@link CtxTopMenu.addTab} with `id === title`. */
   addCategory(name: string): void;
-  /** Add an item under an existing category. */
+  /**
+   * Declare this plugin's dashboard tab. The hub (`sm_admin` / `sm_menu`) paints one tab per
+   * distinct id that still has a visible item. Call before {@link CtxTopMenu.addItem}.
+   */
+  addTab(tab: TopMenuTab): void;
+  /** Add an item under a tab id (or a legacy shared category name). */
   addItem(category: string, item: TopMenuItem): void;
 }
 

package/topmenu.d.ts

@@ -1,5 +1,18 @@
 /** @s2script/topmenu — the extensible admin/top menu registry. NO runtime code (injected at load). */
 
+export type TopMenuSheet = "admin" | "menu";
+
+/**
+ * A plugin-owned dashboard tab. `id` is the {@link TopMenuItem} grouping key (`addItem` first
+ * argument); `title` is what the hub paints on the tab bar.
+ */
+export interface TopMenuTab {
+  /** Stable id, e.g. `"playercommands"`. A duplicate id updates the title. */
+  id: string;
+  /** Tab label. Defaults to {@link TopMenuTab.id}. */
+  title?: string;
+}
+
 /** A single registered top-menu entry (an admin command surfaced in the adminmenu). */
 export interface TopMenuItem {
   /** Plugin-namespaced unique id, e.g. "playercommands:slap". A duplicate id replaces. */
@@ -8,15 +21,19 @@ export interface TopMenuItem {
   name: string;
   /** Required ADMFLAG bit mask (adminmenu hides items the caller lacks flags for). */
   flags: number;
+  /** Sheets in which this item is rendered. Defaults to the admin sheet. */
+  sheets?: TopMenuSheet[];
   /** Runs in THIS plugin's context when an admin selects the item; receives the admin's 0-based slot. */
   onSelect: (adminSlot: number) => void;
 }
 /** A handler-free copy of the whole registry — what a menu renderer reads to build the display. */
 export interface TopMenuSnapshot {
-  /** All category names, in registration order. */
+  /** Tab ids, in registration order. Same sequence as {@link TopMenuSnapshot.tabs}. */
   categories: string[];
-  /** Every registered item's metadata (no `onSelect`), tagged with its category. */
-  items: { id: string; category: string; name: string; flags: number }[];
+  /** Dashboard tabs with display titles. `addCategory(name)` is `{ id: name, title: name }`. */
+  tabs: { id: string; title: string }[];
+  /** Every registered item's metadata (no `onSelect`), tagged with its tab id (`category`). */
+  items: { id: string; category: string; name: string; flags: number; sheets: TopMenuSheet[] }[];
 }
 /**
  * The shared admin/top-menu registry — renderers read {@link TopMenu.snapshot} and dispatch picks

package/votes.d.ts

@@ -17,7 +17,7 @@ export interface VoteConfig {
   options: string[];
   /** seconds. */
   duration: number;
-  /** show a live center tally (default false — the SM chat-only way). */
+  /** show a live center tally (ignored when a tally renderer is registered — CS2 always paints the rail). */
   showLiveTally?: boolean;
   /** Called once when the vote ends (or is exhausted), with the tallied {@link VoteResult}. It may start a new vote (the lock is released first). */
   onEnd: (result: VoteResult) => void;
@@ -32,6 +32,8 @@ export interface VoteTally {
   total: number;
   /** Seconds remaining before the vote ends. */
   secondsLeft: number;
+  /** This slot's 0-based cast, or null if they have not voted yet. */
+  choice: number | null;
 }
 /** A live-tally display backend for votes — registered via {@link Vote.registerTallyRenderer}. */
 export interface VoteTallyRenderer {
@@ -61,6 +63,6 @@ export declare const Vote: {
   isActive(): boolean;
   /** Abort the active vote (no onEnd). */
   cancel(): void;
-  /** Register the live-tally renderer (the CS2 center-HTML renderer). */
+  /** Register the live-tally renderer (the CS2 right-side rail). */
   registerTallyRenderer(renderer: VoteTallyRenderer): void;
 };