docs: amend Constitution Principle II for tsc --noEmit

- Constitution II: permit `tsc --noEmit` with allowJs/checkJs as a
  CI/dev-time check and encourage JSDoc + `// @ts-check`; emit-mode
  TypeScript, .ts/.tsx source, JSX, frameworks, and bundlers stay
  forbidden in core. Bump version 1.0.0 -> 1.1.0.
- Constitution IV: add static/slopsmith.d.ts to the stable-contract
  surface -- breaking changes need a "Migration notes" CHANGELOG entry.
- CHANGELOG: note the typecheck step + ambient .d.ts under [Unreleased].
- CLAUDE.md: point the Frontend Conventions section at slopsmith.d.ts
  as the typed plugin-contract source of truth.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
byrongamatos
2026-06-18 00:33:22 -07:00
committed by Bret Mogilefsky
co-authored by Claude Opus 4.7
parent 6f433d9cea
commit de7ced6429
3 changed files with 24 additions and 6 deletions
+22 -6
View File
@@ -41,12 +41,17 @@ is Tailwind CSS, served as a prebuilt static stylesheet
(`static/tailwind.min.css`, regenerated by `scripts/build-tailwind.sh`)
— never the runtime Play CDN, whose on-the-fly JIT rescans the DOM on
the main thread and caused sustained frame drops with the 3D highway
(slopsmith-desktop#110). No React, Vue, Svelte, bundler, transpiler, or
TypeScript appears in the core static tree, and no build step runs on
the serve path: the Tailwind build is a maintainer-only one-shot whose
output is committed, so Docker / desktop / end users never build. New
features extend `app.js` and the existing globals (`window.playSong`,
`window.showScreen`, `window.createHighway`, `window.slopsmith`).
(slopsmith-desktop#110). No React, Vue, Svelte, bundler, or transpiler
appears in the core static tree, and no build step runs on the serve
path: the Tailwind build is a maintainer-only one-shot whose output is
committed, so Docker / desktop / end users never build. `tsc --noEmit`
with `allowJs` / `checkJs` is permitted as a CI / dev-time type check
— JSDoc type annotations and `// @ts-check` directives in core `.js`
files are encouraged. TypeScript stays a dev-only devDependency; emit
-mode TypeScript, `.ts` / `.tsx` source, JSX, frameworks, and bundlers
remain forbidden in core. New features extend `app.js` and the existing
globals (`window.playSong`, `window.showScreen`,
`window.createHighway`, `window.slopsmith`).
**Non-negotiable rules**
@@ -63,6 +68,11 @@ features extend `app.js` and the existing globals (`window.playSong`,
and does not re-apply the base reset core already provides. Plugins
MUST NOT load the Tailwind Play CDN (or any runtime CSS JIT) — the
same no-CDN, build-free-at-serve rule that binds core binds plugins.
- `tsc --noEmit` with `allowJs` / `checkJs` is permitted as a CI /
dev-time type check. JSDoc type annotations and `// @ts-check`
directives in core `.js` files are encouraged. TypeScript stays a
dev-only devDependency — emit-mode TypeScript, `.ts` / `.tsx` source,
JSX, frameworks, and bundlers remain forbidden in core.
- New UI state lives in `localStorage` (or a backend endpoint), not in a
framework store.
- Naming: camelCase JS, kebab-case CSS, snake_case plugin IDs. Player
@@ -117,6 +127,12 @@ format. Both must keep playing across releases.
- Existing arrangement IDs, sloppak manifests, and the highway
WebSocket message shape are stable contracts. Breaking changes
require a CHANGELOG entry under "Migration notes".
- The plugin-facing JS contracts — `window.slopsmith`, `window.highway`,
the highway WebSocket message shape, and the `setRenderer`
visualization contract — are declared in `static/slopsmith.d.ts` and
form part of this stable-contract surface. The `.d.ts` is the typed
source of truth; a breaking change to it requires the same CHANGELOG
entry under "Migration notes".
### V. Pure-Function Core Libraries, Tested