Make the repo production-ready: contract tests, CI, docs, release

src/lib/effects/contract.test.ts adds 195 cases pinning the effect
system's invariants: registry length and order match GLOW_VARIANTS,
every module parses, every selector is gated on its own [data-glow],
every keyframe and @Property name carries its module's namespace
(prefix map recorded in the test), and a measured performance cap
bounds infinite animations per state. CI gains a reusable checks
workflow (svelte-check, vitest, both builds, packaging with publint,
pack-smoke) called from a new ci.yml on pushes and PRs, a manual
release.yml publishing to npm with provenance, and the Pages deploy
now depends on the same gate. README is rewritten as the package
story — install, quick start, per-effect imports with the measured
24 KB single-effect footprint, the customization seams, the custom
effect authoring path, and the full 39-effect table. Release hygiene:
CONTRACT.md ships in the tarball, repository/homepage/keywords metadata
added, npm publish --dry-run audited clean at 0.1.0, and the
prefers-reduced-motion parity decision is recorded as a labeled
follow-up in CONTRACT.md.

Author: DonPrus

.github/workflows/checks.yml

@@ -0,0 +1,43 @@
+# Reusable check suite for @ui4ai/light-input. Every entry point (CI on push/PR, the Pages deploy,
+# and the manual npm release) calls this so the exact same gate guards all of them — no drift
+# between "what CI runs" and "what actually ships".
+name: Checks
+
+on:
+  workflow_call:
+
+jobs:
+  verify:
+    name: svelte-check · tests · build · package · pack-smoke
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check (svelte-check)
+        run: npm run check
+
+      - name: Unit + contract tests
+        run: npm test
+
+      - name: Build demo (client)
+        run: npm run build
+
+      - name: Build GitHub Pages demo
+        run: npm run build:pages
+
+      - name: Package the library (svelte-package + publint)
+        run: npm run package
+
+      - name: Packaging smoke test (tarball + isolation + SSR)
+        run: npm run pack-smoke

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+# Continuous integration: run the full check suite on every push to main and every PR targeting
+# main. This is the gate that must be green before the Pages deploy runs and before a release can
+# be cut. See checks.yml for the actual steps.
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+# Cancel superseded runs on the same ref (a new push to a branch/PR obsoletes the previous one).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: Checks
+    uses: ./.github/workflows/checks.yml

.github/workflows/pages.yml

@@ -16,8 +16,15 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Gate the deploy on the same suite CI runs (svelte-check, tests, build, package, pack-smoke).
+  # A red gate blocks the site update instead of shipping a broken demo.
+  checks:
+    name: Checks
+    uses: ./.github/workflows/checks.yml
+
   build:
     name: Build static demo
+    needs: checks
     runs-on: ubuntu-latest
 
     steps:
@@ -33,12 +40,6 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Check
-        run: npm run check
-
-      - name: Test
-        run: npm test -- --run
-
       - name: Build GitHub Pages demo
         run: npm run build:pages
 

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+# Manual npm release for @ui4ai/light-input.
+#
+# Trigger from the Actions tab (workflow_dispatch). It runs the FULL check suite first and only
+# publishes if every check passes, so a broken tree can never ship.
+#
+# One-time setup required in the repo settings:
+#   • Secret  NPM_TOKEN  — an npm automation/granular token with publish rights to the
+#     @ui4ai scope (Settings → Secrets and variables → Actions → New repository secret).
+#   • The workflow publishes with --provenance, which needs the `id-token: write` permission
+#     granted below and a runner on npm ≥ 9.5 (Node 24 ships a newer npm — fine).
+#
+# Versioning is manual: bump `version` in package.json (e.g. `npm version minor`) and push before
+# running this. The publish step is idempotent-safe — npm refuses to republish an existing version,
+# so a re-run after a partial failure will not double-publish.
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: 'Run npm publish with --dry-run only (no upload)'
+        type: boolean
+        default: false
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  # Reuse the exact CI gate. Publishing is blocked unless this succeeds.
+  checks:
+    name: Checks
+    uses: ./.github/workflows/checks.yml
+
+  publish:
+    name: Publish to npm
+    needs: checks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # required for npm provenance
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # `prepublishOnly` (check + test + package) runs automatically as part of `npm publish`,
+      # building dist/ and re-validating before anything is uploaded.
+      - name: Publish (dry run)
+        if: ${{ inputs.dry-run }}
+        run: npm publish --provenance --access public --dry-run
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish
+        if: ${{ !inputs.dry-run }}
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CONTRACT.md

@@ -281,6 +281,30 @@ its entrance pose. If your effect adds infinite motion on other layers, add a ma
 `.stage[data-glow='my-effect'][data-light-flow='off'] … { animation: none }` so "flow off" is
 honored.
 
+### `prefers-reduced-motion` — current parity (FOLLOW-UP)
+
+Known limitation for `0.1.0`, recorded here so it is not mistaken for a bug. `core.css` carries a
+`@media (prefers-reduced-motion: reduce)` block that sets `animation: none` on the base anatomy
+(`.field::before`, `.caret`, `.torch-beam`, `.beam`, `.next-word`, `.tail`). Those rules are (0,2,0),
+so a per-effect module's own animation — set at `.stage[data-glow='x'] .field[data-glow] .beam-veil`
+(0,5,0) — **overrides** the reduced-motion kill. Net effect today: the default torch layers quiet
+down under reduced-motion, but each effect's signature animations keep running (a deliberate
+visual-identity choice, not real support).
+
+**If your effect must honor reduced-motion**, add your own scoped kill:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+	.stage[data-glow='my-effect'] .field[data-glow] .beam-veil,
+	.stage[data-glow='my-effect'] .field[data-glow] .beam-hot {
+		animation: none;
+	}
+}
+```
+
+Making this the package default for all 39 effects (emitting the scoped `animation: none` at (0,5,0)
+under the media query in every module) is a tracked follow-up.
+
 ---
 
 ## 7. The var()-in-custom-property pitfall (read this)