@sandustry-modding/types 0.3.0 → 0.3.1

package/{docs/Changelog.md → CHANGELOG.md}

@@ -5,6 +5,18 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-08-27
+
+### Fixed
+
+- Deep package imports such as `@sandustry-modding/types/sandkit/engine` (Node `exports` `*` matches one path segment; map file and `index.d.ts` targets under `src/`)
+- Ship root `CHANGELOG.md` and `LICENSE` in the npm tarball
+- Document ambient setup with `/// <reference types="@sandustry-modding/types" />` (do not list this package under `compilerOptions.types`)
+
+### Added
+
+- `npm run validate` gate: declaration typecheck, unit tests, and packed-tarball consumer probes
+
 ## [0.3.0] - 2026-08-27
 
 ### Changed
@@ -40,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ambient `sandkit` free variable and type aliases via `global.d.ts`
 - Docsify API reference generated from the declarations
 
+[0.3.1]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.3.1
 [0.3.0]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.3.0
 [0.2.0]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.2.0
 [0.1.1]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandustry-modding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -37,31 +37,17 @@ Declaration files use `export namespace` because it is the usual `.d.ts` pattern
 npm install @sandustry-modding/types
 ```
 
-### Project config (preferred)
+### Ambient types (preferred)
 
-Add the package to `compilerOptions.types` in `tsconfig.json` or `jsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "types": ["@sandustry-modding/types"]
-  }
-}
-```
-
-If you already list other packages in `types` (for example `"react"` or `"node"`), keep those entries and add `"@sandustry-modding/types"` to the same array. A non-empty `types` list replaces TypeScript’s default auto-inclusion of all `@types/*` packages.
-
-`jsconfig.json` uses the same shape for JavaScript mods.
-
-### Per-file reference
-
-You can also pull the ambient types into one file:
+Pull the host `sandkit` ambient into your project with a triple-slash reference. Put it at the top of `main.js` / `worker.js`, or in a small ambient `.d.ts` that your `tsconfig` / `jsconfig` includes:
 
 ```ts
 /// <reference types="@sandustry-modding/types" />
 ```
 
-That triple-slash directive works in `.ts` and `.js` (including checked JS with `checkJs`). Put it at the top of `main.js` / `worker.js`, or in a small ambient `.d.ts` included by your project.
+That works in `.ts` and `.js` (including checked JS with `checkJs`).
+
+Do **not** list `@sandustry-modding/types` under `compilerOptions.types`. That list only loads packages from `node_modules/@types` (for example `"react"` or `"node"`).
 
 Deep declaration modules are also available, for example:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandustry-modding/types",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "TypeScript declarations and API docs for the Sandustry Sandkit host API",
   "license": "MIT",
   "repository": {
@@ -17,14 +17,61 @@
       "types": "./src/global.d.ts"
     },
     "./package.json": "./package.json",
-    "./*": {
-      "types": "./src/*"
+    "./sandkit": {
+      "types": "./src/sandkit/index.d.ts"
+    },
+    "./sandkit/*": {
+      "types": [
+        "./src/sandkit/*.d.ts",
+        "./src/sandkit/*/index.d.ts"
+      ]
+    },
+    "./sandkit/*/*": {
+      "types": [
+        "./src/sandkit/*/*.d.ts",
+        "./src/sandkit/*/*/index.d.ts"
+      ]
+    },
+    "./sandkit/*/*/*": {
+      "types": [
+        "./src/sandkit/*/*/*.d.ts",
+        "./src/sandkit/*/*/*/index.d.ts"
+      ]
+    },
+    "./shared": {
+      "types": "./src/shared/index.d.ts"
+    },
+    "./shared/*": {
+      "types": [
+        "./src/shared/*.d.ts",
+        "./src/shared/*/index.d.ts"
+      ]
+    },
+    "./shared/*/*": {
+      "types": [
+        "./src/shared/*/*.d.ts",
+        "./src/shared/*/*/index.d.ts"
+      ]
+    },
+    "./worker": {
+      "types": "./src/worker/index.d.ts"
+    },
+    "./worker/*": {
+      "types": [
+        "./src/worker/*.d.ts",
+        "./src/worker/*/index.d.ts"
+      ]
+    },
+    "./worker/*/*": {
+      "types": [
+        "./src/worker/*/*.d.ts",
+        "./src/worker/*/*/index.d.ts"
+      ]
     }
   },
   "files": [
     "src/**/*.d.ts",
     "CHANGELOG.md",
-    "docs/Changelog.md",
     "LICENSE",
     "README.md"
   ],
@@ -33,7 +80,10 @@
     "docs:api": "node scripts/generate-api-docs.mjs",
     "docs:serve": "npx --yes docsify-cli serve docs",
     "test": "node --test scripts/api-search.test.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify-package": "node scripts/verify-package.mjs",
+    "validate": "npm run typecheck && npm test && npm run verify-package",
+    "prepack": "npm run validate"
   },
   "devDependencies": {
     "@types/react": "^18.3.1",

package/docs/README.md

@@ -1,62 +0,0 @@
-# Sandkit API
-
-> [!WARNING]
-> **Unofficial** community docs. Not affiliated with Lantto Games, Hooded Horse, or the [official Sandustry wiki](https://wiki.hoodedhorse.com/Sandustry/Sandustry_Official_Wiki). See the [official Sandkit docs](https://sandustry.com/sandkit.html).
-
-Community TypeScript reference for the live Sandustry `sandkit` host API. Package: [`@sandustry-modding/types`](https://www.npmjs.com/package/@sandustry-modding/types).
-
-## Start here
-
-| Go to | When you need |
-| --- | --- |
-| [Namespaces](modules.md) | Browse namespaces by group |
-| [Full API reference](full.md) | All namespaces on one page |
-| [Main thread](api/sandkit.api.md) | `main.js` APIs (`sandkit.api`) |
-| [Worker thread](api/sandkit.api.worker.md) | `worker.js` APIs (subset + direct mutations) |
-| [Engine](api/sandkit.engine.md) | Escape hatch (`sandkit.engine`) |
-| [Enums](api/sandkit.enums.md) | Runtime enum values |
-| [React](api/sandkit.react.md) | HUD JSX helpers |
-
-## Install types
-
-```bash
-npm install @sandustry-modding/types
-```
-
-### Project config (preferred)
-
-In `tsconfig.json` or `jsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "types": ["@sandustry-modding/types"]
-  }
-}
-```
-
-If `types` already lists other packages (for example `"react"` or `"node"`), add `"@sandustry-modding/types"` to that array. A non-empty `types` list replaces auto-inclusion of all `@types/*` packages.
-
-### Per-file reference
-
-```ts
-/// <reference types="@sandustry-modding/types" />
-```
-
-Works in `.ts` and `.js` (including checked JS). Put it at the top of a source file, or in an ambient `.d.ts` included by the project.
-
-Use the ambient `sandkit` free name in `main.js`. In `worker.js`, type the API as `WorkerSandkitApi` — worker and main surfaces overlap but are not interchangeable.
-
-## Also useful
-
-- [Official Sandkit docs](https://sandustry.com/sandkit.html)
-- [Sandustry Mod Template](https://sandustry-modding.github.io/SandustryModTemplate/#/)
-- [Official Sandustry wiki](https://wiki.hoodedhorse.com/Sandustry/Sandustry_Official_Wiki)
-
-## Regenerate
-
-From the package repo root:
-
-```bash
-npm run docs:api
-```