@sandustry-modding/types 0.3.1 → 0.4.0

package/src/sandkit/api/tech.d.ts

@@ -13,7 +13,8 @@ export namespace tech {
    * Return a tech definition by string id.
    *
    * @param techId - Tech entry identifier.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.getDefinitionById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDefinitionById(techId: TechGridId): TechDefinition | undefined;
 
@@ -22,7 +23,15 @@ export namespace tech {
    *
    * @param techId - Tech entry identifier.
    * @param updates - Fields to merge into the definition.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.updateDefinition`
+   *
+   * @example
+   * ```ts
+   * api.tech.updateDefinition("exampleTech", {
+   *   cost: 200,
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function updateDefinition(techId: TechGridId, updates: Partial<TechDefinition>): void;
 
@@ -31,13 +40,26 @@ export namespace tech {
    *
    * @param techId - Tech entry identifier.
    * @param definition - Full tech definition to register.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.registerDefinition`
+   *
+   * @example
+   * ```ts
+   * api.tech.registerDefinition("exampleTech", {
+   *   name: "Example research",
+   *   nameKey: "mods|example|techName",
+   *   description: "Unlocks the example machine.",
+   *   descriptionKey: "mods|example|techDescription",
+   *   cost: 100,
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function registerDefinition(techId: TechGridId, definition: TechDefinition): void;
 
   /**
    * @deprecated Use {@link registerDefinition} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.tech.registerDefinition`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function addDefinition(techId: TechGridId, definition: TechDefinition): void;
 
@@ -47,7 +69,17 @@ export namespace tech {
    * @param techId - Tech grid node id.
    * @param definition - Tech definition for the node.
    * @param options - Parent node id and optional preferred grid position.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.registerNode`
+   *
+   * @example
+   * ```ts
+   * const position = api.tech.registerNode(
+   *   "exampleTech",
+   *   techDefinition,
+   *   { parentId: parentTechId },
+   * );
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function registerNode(techId: TechGridId, definition: TechDefinition, options: { parentId: TechGridId; preferredPosition?: TechGridPosition; }): TechGridPosition;
 
@@ -55,7 +87,8 @@ export namespace tech {
    * Return true when a tech entry is locked.
    *
    * @param techId - Tech entry id (string or numeric enum).
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.isLockedById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isLockedById(techId: TechGridId): boolean;
 
@@ -64,7 +97,8 @@ export namespace tech {
    *
    * @param techId - Tech entry id (string or numeric enum).
    * @param locked - When true, the tech cannot be purchased.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.setLockedById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setLockedById(techId: TechGridId, locked: boolean): void;
 
@@ -72,7 +106,8 @@ export namespace tech {
    * Return true when a tech entry has been researched.
    *
    * @param techId - Tech entry id (string or numeric enum).
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.isResearchedById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isResearchedById(techId: TechGridId): boolean;
 
@@ -83,7 +118,15 @@ export namespace tech {
      *
      * @param techId - Built-in or custom tech id.
      * @param unlocks - Optional structure and item ids to unlock.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.tech.conservatory.appendUnlock`
+     *
+     * @example
+     * ```ts
+     * api.tech.conservatory.appendUnlock(sandkit.enums.Tech.SignalDevices, {
+     *   structures: ["exampleSensor"],
+     * });
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function appendUnlock(techId: TechGridId, unlocks: ConservatoryUnlocks): void;
   }
@@ -96,10 +139,31 @@ export namespace tech {
 
   /** Tech definition shape. */
   export interface TechDefinition {
+    /** Plain display name (when not using {@link nameKey}). */
+    name?: string;
     /** Display name translation key. */
     nameKey?: string;
+    /** Plain description (when not using {@link descriptionKey}). */
+    description?: string;
     /** Description translation key. */
     descriptionKey?: string;
+    /**
+     * Research cost.
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
+     */
+    cost?: number;
+    /** Currency used for {@link cost} (for example `"gold"`). */
+    currencyType?: string;
+    /** Tech tree branch id (often copied from the parent node). */
+    branch?: string;
+    /** Content unlocked when this tech is researched. */
+    unlocks?: {
+      structures?: readonly string[];
+      items?: readonly string[];
+    };
+    /** Prerequisite tech ids. */
+    requires?: readonly string[];
     [key: string]: unknown;
   }
 

package/src/sandkit/api/terrains.d.ts

@@ -17,7 +17,8 @@ export namespace terrains {
   export import getTypeById = shared.api.terrains.getTypeById;
   /**
    * @deprecated Use {@link getTypeById} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.getTypeById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import getTypeFromId = shared.api.terrains.getTypeFromId;
   /** Look up the definition for a terrain type. */
@@ -48,7 +49,7 @@ export namespace terrains {
   /**
    * Terrain definition shape with typed element interactions.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.register`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export interface TerrainDefinition extends Omit<shared.api.terrains.TerrainDefinition, "interactions"> {
     /** Tooltip interactions shown for this terrain. */
@@ -60,7 +61,8 @@ export namespace terrains {
    *
    * @param definition - Terrain definition to register.
    * @returns Object with the assigned `cellType`.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.register`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function register(definition: TerrainDefinition): { cellType: TerrainType; };
 
@@ -69,7 +71,8 @@ export namespace terrains {
    *
    * @param cellTypeOrId - Numeric cell type or terrain string id.
    * @param partial - Fields to merge onto the definition.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.updateDefinition`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function updateDefinition(cellTypeOrId: TerrainRef, partial: Partial<TerrainDefinition>): void;
 
@@ -80,13 +83,15 @@ export namespace terrains {
    * @param cellY - Grid row of the target cell.
    * @param terrainTypeOrId - Numeric cell type or terrain string id.
    * @param options - Optional mutation flags.
-   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.createAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function createAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
 
   /**
    * @deprecated Use {@link createAtCell} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.createAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function createAtCellWhenIdle(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
 
@@ -97,13 +102,15 @@ export namespace terrains {
    * @param cellY - Grid row of the target cell.
    * @param terrainTypeOrId - Numeric cell type or terrain string id.
    * @param options - Optional mutation flags.
-   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.replaceAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
 
   /**
    * @deprecated Use {@link replaceAtCell} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.replaceAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function replaceAtCellWhenIdle(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
 
@@ -113,13 +120,15 @@ export namespace terrains {
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param options - Optional mutation flags.
-   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.removeAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function removeAtCell(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
 
   /**
    * @deprecated Use {@link removeAtCell} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.removeAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function removeAtCellWhenIdle(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
 
@@ -129,19 +138,22 @@ export namespace terrains {
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param hitPoints - New hit point value.
-   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.setHitPointsAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function setHitPointsAtCell(...args: [...CellCoordinates, hitPoints: number]): void;
 
   /**
    * @deprecated Use {@link setHitPointsAtCell} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.setHitPointsAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function setHpAtCell(...args: [...CellCoordinates, hitPoints: number]): boolean;
 
   /**
    * @deprecated Use {@link setHitPointsAtCell} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.setHitPointsAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function setHpAtCellWhenIdle(...args: [...CellCoordinates, hitPoints: number]): void;
 }

package/src/sandkit/api/triggers.d.ts

@@ -10,6 +10,16 @@ export namespace triggers {
    * Register a repeating trigger with interval and callback.
    * @param triggerId - Unique trigger identifier.
    * @param definition - Interval in ticks and callback to invoke.
+   *
+   * @example
+   * ```ts
+   * api.triggers.register("example:update", {
+   *   intervalMs: 250,
+   *   callback: (trigger, deltaTimeMs) => {
+   *     updateExample(trigger, deltaTimeMs);
+   *   },
+   * });
+   * ```
    */
   export function register(triggerId: string, definition: MainTriggerDefinition): void;
 

package/src/sandkit/api/ui.d.ts

@@ -10,8 +10,112 @@ import type { ComponentId as ComponentIdEnum } from "../enums/index";
 import { shared } from "../../shared";
 import type { LooseString } from "../../shared/nominal";
 
+/**
+ * @example api.ui.components.ActionSlot
+ * ```ts
+ * const slot = sandkit.react.createElement(
+ *   api.ui.components.ActionSlot,
+ *   { source, slotIndex: 0, keyLabel: "1" },
+ * );
+ * ```
+ *
+ * @example api.ui.components.Button
+ * ```ts
+ * const button = sandkit.react.createElement(
+ *   api.ui.components.Button,
+ *   { onClick: openPanel },
+ *   "Open",
+ * );
+ * ```
+ *
+ * @example api.ui.components.Panel
+ * ```ts
+ * const panel = sandkit.react.createElement(
+ *   api.ui.components.Panel,
+ *   { title: "Options" },
+ *   "Panel content",
+ * );
+ * ```
+ *
+ * @example api.ui.hotbar.createBankSource
+ * ```ts
+ * const source = api.ui.hotbar.createBankSource({
+ *   bankOffset: 1,
+ *   minimumBankCount: 2,
+ * });
+ * ```
+ *
+ * @example api.ui.hotbar.useHotbar
+ * ```ts
+ * const hotbar = api.ui.hotbar.useHotbar();
+ * console.log(
+ *   hotbar.bankCount,
+ *   hotbar.activeBankIndex,
+ *   hotbar.activeSlotIndex,
+ * );
+ * ```
+ *
+ * @example api.ui.overrides.register
+ * ```ts
+ * const overrideHandle = api.ui.overrides.register(
+ *   "resources",
+ *   (Original) => sandkit.react.createElement(
+ *     sandkit.react.Fragment,
+ *     null,
+ *     sandkit.react.createElement(Original),
+ *     sandkit.react.createElement(ResourceAddon),
+ *   ),
+ * );
+ * ```
+ *
+ * @example api.ui.regions.mount
+ * ```ts
+ * const mountHandle = api.ui.regions.mount(
+ *   "hotbar",
+ *   "extra-actions",
+ *   {
+ *     placement: "docked",
+ *     order: 0,
+ *     render: () => sandkit.react.createElement(ExtraActions),
+ *   },
+ * );
+ * ```
+ *
+ * @example api.ui.regions.mountHandle.update
+ * ```ts
+ * mountHandle.update({
+ *   order: 10,
+ *   render: () => sandkit.react.createElement(UpdatedActions),
+ * });
+ * ```
+ *
+ * @example api.ui.select
+ * ```ts
+ * const selected = await api.ui.select(
+ *   [
+ *     { label: "Sand", value: "sand" },
+ *     { label: "Fluxite", value: "fluxite" },
+ *   ],
+ *   { title: "Select element", defaultValue: "sand", buttonLabel: "Choose" },
+ * );
+ * ```
+ *
+ * @example api.ui.useGameEvent
+ * ```ts
+ * api.ui.useGameEvent("resource:collected", (payload) => {
+ *   console.log(payload.resourceId, payload.amount);
+ * });
+ * ```
+ */
 export namespace ui {
-  /** Show a toast message. */
+  /**
+   * Show a toast message.
+   *
+   * @example Main entry
+   * ```ts
+   * api.ui.toast({ key: "mods|example|saved" });
+   * ```
+   */
   export import toast = shared.api.ui.toast;
   /** Localized text value for UI strings. */
   export import LocalizedText = shared.api.ui.LocalizedText;
@@ -39,6 +143,14 @@ export namespace ui {
    * @param message - Dialog body text.
    * @param title - Optional dialog title.
    * @returns Promise that resolves when the user dismisses the dialog.
+   *
+   * @example
+   * ```ts
+   * await api.ui.alert(
+   *   { key: "mods|example|details" },
+   *   { key: "mods|example|title" },
+   * );
+   * ```
    */
   export function alert(message: LocalizedText, title?: LocalizedText): Promise<void>;
 
@@ -47,6 +159,13 @@ export namespace ui {
    * @param message - Dialog body text.
    * @param title - Optional dialog title.
    * @returns Promise that resolves with true when confirmed, or false when cancelled.
+   *
+   * @example
+   * ```ts
+   * const confirmed = await api.ui.confirm(
+   *   { key: "mods|example|confirm" },
+   * );
+   * ```
    */
   export function confirm(message: LocalizedText, title?: LocalizedText): Promise<boolean>;
 
@@ -58,6 +177,14 @@ export namespace ui {
    * @param title - Optional dialog title.
    * @param allowCopy - When true, allow copying the result from the dialog.
    * @returns Promise that resolves with entered text, or null when cancelled.
+   *
+   * @example
+   * ```ts
+   * const value = await api.ui.prompt(
+   *   { key: "mods|example|enterValue" },
+   *   "",
+   * );
+   * ```
    */
   export function prompt(message: LocalizedText, defaultValue?: string, placeholder?: LocalizedText, title?: LocalizedText, allowCopy?: boolean): Promise<string | null>;
 
@@ -99,12 +226,30 @@ export namespace ui {
      * React hook for a focusable UI element in a scope.
      * @param options - Focus registration and neighbor wiring.
      * @returns Ref, focus state, and a focus helper.
+     *
+     * @example
+     * ```ts
+     * const focusable = api.ui.navigation.useFocusable({
+     *   id: "example-button",
+     *   scope: "example-scope",
+     *   onActivate: openExample,
+     * });
+     * ```
      */
     export function useFocusable<T extends HTMLElement = HTMLDivElement>(options: FocusOptions): Focusable<T>;
 
     /**
      * React hook to register a focus scope with back handling.
      * @param options - Scope id, priority, default focus, and back handler.
+     *
+     * @example
+     * ```ts
+     * api.ui.navigation.useFocusScope({
+     *   id: "example-scope",
+     *   active: true,
+     *   priority: 10,
+     * });
+     * ```
      */
     export function useFocusScope(options: { readonly id: string; readonly active: boolean; readonly priority?: number; readonly defaultId?: string; readonly onBack?: (() => boolean | void); }): void;
 

package/src/sandkit/api/upgrades.d.ts

@@ -41,7 +41,8 @@ export namespace upgrades {
    * @param itemId - Parent item id.
    * @param upgradeId - Upgrade id within the item.
    * @param level - Level to set.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.upgrades.setLevelById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setLevelById(itemId: string, upgradeId: string, level: number): void;
 

package/src/sandkit/api/utils.d.ts

@@ -13,7 +13,8 @@ export namespace utils {
    *
    * @param pointA - First point.
    * @param pointB - Second point.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getDistance`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDistance(pointA: Vector2, pointB: Vector2): number;
 
@@ -22,7 +23,8 @@ export namespace utils {
    *
    * @param pointA - Origin point.
    * @param pointB - Target point.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getDirection`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDirection(pointA: Vector2, pointB: Vector2): Vector2;
 
@@ -31,7 +33,8 @@ export namespace utils {
    *
    * @param pointA - Origin point.
    * @param pointB - Target point.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getAngle`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getAngle(pointA: Vector2, pointB: Vector2): number;
 
@@ -40,13 +43,15 @@ export namespace utils {
    *
    * @param pointA - Line start in cell coordinates.
    * @param pointB - Line end in cell coordinates.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getCoordinatesBetweenCells`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getCoordinatesBetweenCells(pointA: Vector2, pointB: Vector2): Vector2[];
 
   /**
    * @deprecated Use {@link getCoordinatesBetweenCells} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.utils.getCoordinatesBetweenCells`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getCoordinatesBetweenPoints(pointA: Vector2, pointB: Vector2): Vector2[];
 }

package/src/sandkit/api/world.d.ts

@@ -13,38 +13,39 @@ import { pickups as pickupsNs } from "./pickups";
 
 /**
  * @deprecated Use {@link grid} instead.
- * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid`
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace world {
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.getCellIdAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import getCellIdAtCell = grid.getCellIdAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.isCellEmptyAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import isCellEmptyAtCell = grid.isCellEmptyAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.isTerrainAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import isTerrainAtCell = grid.isTerrainAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.reportActivityAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import reportActivityAtCell = grid.reportActivityAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.excavateAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import excavateAtCell = grid.excavateAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.getDimensions`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import getDimensions = grid.getDimensions;
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.ExcavateOptions` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import ExcavateOptions = grid.ExcavateOptions;
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.CellId` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import CellId = grid.CellId;
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.GridDimensions` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import GridDimensions = grid.GridDimensions;
 
   /**
@@ -52,54 +53,58 @@ export namespace world {
    *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.revealFogAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import revealFogAtCell = grid.revealFogAtCell;
 
   /**
    * @deprecated Use {@link grid.mutate} instead.
-   * @see https://sandustry.com/sandkit.html#mutations-heading
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.mutate`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function runWhenSimulationIdle(callback: () => void): void;
 
   /**
    * @deprecated Use {@link grid.redrawAroundCell} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.redrawAroundCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function redrawAroundCellWhenIdle(...args: [...CellCoordinates, range: number]): void;
 
   /**
    * @deprecated Use {@link pickups} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export namespace pickups {
-    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.spawnAtWorld` */
+    /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
     export import spawnAtWorld = pickupsNs.spawnAtWorld;
-    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.remove` */
+    /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
     export import destroy = pickupsNs.destroy;
-    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.pickUp` */
+    /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
     export import pickUp = pickupsNs.pickUp;
-    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.getAll` */
+    /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
     export import getAll = pickupsNs.getAll;
-    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.getById` */
+    /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
     export import getById = pickupsNs.getById;
-    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.remove` */
+    /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
     export import remove = pickupsNs.remove;
   }
 
   /**
    * @deprecated Use {@link pickups.PickupType} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.PickupType`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import WorldItemType = pickupsNs.WorldItemType;
 
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.PickupType` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import PickupType = pickupsNs.PickupType;
 
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.WorldItemLight` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import WorldItemLight = pickupsNs.WorldItemLight;
 
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.WorldItem` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import WorldItem = pickupsNs.WorldItem;
 }

package/src/sandkit/index.d.ts

@@ -18,7 +18,18 @@ import type { SandkitEnums } from "./enums";
 import type { SandkitReact } from "./react";
 import type { SandkitState } from "./engine/state";
 
-/** Shape of the host-injected `sandkit` free variable in mod `main.js`. */
+/**
+ * Shape of the host-injected `sandkit` free variable in mod `main.js`.
+ *
+ * @example Accessing the API
+ * ```ts
+ * const api = sandkit.api; // Stable API
+ *
+ * // Unstable engine escape hatch
+ * const engineApi = sandkit.engine.api;
+ * const engineState = sandkit.engine.state;
+ * ```
+ */
 export type Sandkit = {
   /** Public mod API. See {@link sandkit.api}. */
   api: SandkitApi;