Add JSDoc-to-d.ts publishing pipeline

- Add deno task dts (tsc + dts-bundle-generator + fix-phaser-dts) and dts:check
- Add mod.d.ts artifact with @ts-self-types pragma in mod.js
- Update CI to run dts:check, publish to regenerate before publishing
- Reorganize CONTEXT.md by directory hierarchy, document pipeline
- Add JSDoc type annotations to PropEngine
- Add tsconfig.json, tsconfig.bundle.json, scripts/fix-phaser-dts.ts

Author: gandazgul

.github/workflows/publish.yml

@@ -16,4 +16,5 @@ jobs:
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x
-      - run: deno publish --allow-slow-types
+      - run: deno task dts # regenerate the bundled mod.d.ts from JSDoc
+      - run: deno publish

.gitignore

@@ -1,4 +1,7 @@
+.history/
+
 node_modules/
 dist/
+types/
+
 .DS_Store
-.history/

CONTEXT.md

@@ -88,18 +88,25 @@ To work on a game and the engine side by side without publishing, map the packag
 ## Development
 
 ```bash
-deno task ci      # lint + fmt:check + check + test
+deno task ci      # lint + fmt:check + check + dts:check + test
 deno task test
+deno task dts     # regenerate the bundled mod.d.ts from JSDoc
 ```
 
+## Types
+
+The engine is authored in JavaScript with JSDoc. To ship real types (and satisfy JSR fast-check without
+`--allow-slow-types`), `deno task dts` compiles the JSDoc to declarations with `tsc`, rolls them into a single
+self-contained `mod.d.ts`, and `mod.js` points at it via `// @ts-self-types`. `deno task dts:check` (run in CI)
+regenerates it and fails if the committed `mod.d.ts` is stale, so types can never drift from the source.
+
 ## Publishing
 
 ```bash
-deno publish --allow-slow-types
+deno task dts && deno publish
 ```
 
-Requires the `@caper` scope on JSR. The engine is authored in JavaScript with JSDoc types, so JSR ships it with "slow
-types" (no generated `.d.ts`); `--allow-slow-types` acknowledges that.
+Requires the `@caper` scope on JSR. Pushing a `v*` tag runs this via `.github/workflows/publish.yml`.
 
 ## License
 

README.md

@@ -15,11 +15,14 @@
     },
     "tasks": {
         "check": "deno check mod.js src/",
+        "types": "deno run -A npm:typescript/bin/tsc -p tsconfig.json",
+        "dts": "deno task types && deno run -A npm:dts-bundle-generator@9 -o mod.d.ts --project tsconfig.bundle.json --no-check types/mod.d.ts && deno run --allow-read=mod.d.ts --allow-write=mod.d.ts scripts/fix-phaser-dts.ts",
+        "dts:check": "deno task dts && git diff --exit-code mod.d.ts",
         "test": "deno test --permit-no-files --allow-read src/",
         "lint": "deno lint",
         "fmt": "deno fmt mod.js src/ docs/ README.md deno.json",
         "fmt:check": "deno fmt --check mod.js src/ docs/ README.md deno.json",
-        "ci": "deno task lint && deno task fmt:check && deno task check && deno task test"
+        "ci": "deno task lint && deno task fmt:check && deno task check && deno task dts:check && deno task test"
     },
     "imports": {
         "@std/assert": "jsr:@std/assert@^1.0.19",
@@ -28,7 +31,8 @@
     },
     "exclude": [
         "node_modules/",
-        "dist/"
+        "dist/",
+        "types/"
     ],
     "fmt": {
         "indentWidth": 4,
@@ -37,6 +41,9 @@
         "singleQuote": false
     },
     "lint": {
+        "exclude": [
+            "mod.d.ts"
+        ],
         "rules": {
             "exclude": [
                 "no-window-prefix",