Apply the final review fixes: value-out API, type exports, d.ts hygiene

The input text becomes a bindable value prop and acceptNextWord fires
an onaccept callback with the accepted word and resulting text — the
first integration need of any host app. CompleteFn, CaretState and
AcceptDetail are exported from the package root (CaretState moves to
input/types.ts so svelte-package emits it). Shipped .d.ts files no
longer carry CSS side-effect imports (scripts/fix-dts.mjs runs inside
npm run package), and pack-smoke now compiles a strict consumer with
skipLibCheck:false — including the README complete() sample verbatim,
which is now typed. The autofocus mount effect reads its prop
untracked so later toggles cannot steal focus; the CompletionCache
eviction guard accepts empty-string keys; postcss graduates from a
hoisting accident to a declared devDependency. Docs are brought back
to the truth: reduced-motion behavior stated as it really is, the
waiting-snippet claim scoped to the thinking indicator, minChars
strict-greater semantics documented, the npm hero image absolutized,
and the stale legacy.css bundle-order comment in core.css rewritten.

Author: DonPrus

CONTRACT.md

@@ -47,7 +47,7 @@ export const meta: EffectMeta = {
 };
 ```
 
-`defineEffect(effect)` is an identity helper: it returns its argument unchanged and, in dev, warns
+`defineEffect(effect)` is an identity helper: it returns its argument unchanged and warns at runtime
 if `meta.name` is not kebab-case (a malformed name silently matches no CSS). The `name` you choose is
 the value that lands in `data-glow` and that every selector in your `index.css` keys on — it MUST be
 globally unique across the effects a given app loads.
@@ -285,11 +285,17 @@ honored.
 
 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).
+(`.field::before`, `.caret.active`, `.caret.thinking`, `.torch-beam`, `.beam`, `.next-word`,
+`.tail`). Those rules are only (0,1,0)/(0,2,0), so they win **only where nothing outranks them**.
+
+What actually stops today: the **caret blink/think** (`.caret.active`/`.caret.thinking` at (0,2,0),
+tied by the media rule which comes later) and the **word/tail entrances** (`.next-word`/`.tail` at
+(0,1,0), same story). What keeps animating: the **torch beams** and the **field wash** — the anatomy
+that drives them is applied at `.stage[data-glow] .field[data-glow] .torch-haze` (0,5,0) and the
+field-flow `::before` at ≥(0,4,1), both of which outrank the media kill. And a per-effect module's
+own animation — set at the same (0,5,0) band — likewise **overrides** the reduced-motion kill. Net
+effect: caret and entrance motion quiet down, but the beams, field wash, and each effect's signature
+animation keep running (a deliberate visual-identity choice for now, not full support).
 
 **If your effect must honor reduced-motion**, add your own scoped kill:
 
@@ -471,11 +477,14 @@ Replaces the six `.torch-*` beams inside `.caret-origin-glow`:
 ```
 
 **Gating (important):** the `waiting` snippet renders **only where the default torch stack would** —
-i.e. only when the caret glow is shown. That means it renders when a suggestion is showing
-(`ready`, `data-mode='ready'`) or while thinking with `loadingGlow='torch'`
-(`data-mode='waiting'`). With `loadingGlow='field'` or `loadingGlow='none'`, the `.caret-origin-glow`
-wrapper is not rendered at all, so **neither the snippet nor the default beams appear** — style the
-thinking indicator via the field instead (§6).
+i.e. only inside the caret glow, and only in its `data-mode='waiting'` form: the `waiting` state
+with `loadingGlow='torch'`. While **thinking** with `loadingGlow='field'` or `loadingGlow='none'`,
+no `data-mode='waiting'` caret glow is rendered, so **neither the snippet nor the default beams
+appear** as the thinking indicator — style the field instead (§6).
+
+Note this scopes only the *thinking* indicator. When a suggestion is showing (`ready`), the caret
+glow still renders in its `data-mode='ready'` form regardless of `loadingGlow` — but that READY
+subtree is not what the `waiting` snippet targets; the snippet is for the thinking phase.
 
 ---
 
@@ -500,6 +509,13 @@ cache, monotonic stale-response guard, and the shared `AbortSignal` (which fires
 superseded or the input blurs — honor it). Return the raw completion string; the component normalizes
 it exactly like an endpoint response. `demo` mode never calls `complete`.
 
+**Cache-invalidation caveat.** The component clears its LRU cache when the completion *source* key
+changes, but that key tracks `complete` by **presence** (`fn` vs `none`), not by identity. Swapping
+one custom `complete` function for a *different* one (both truthy) does **not** clear the cache, so a
+key already cached by the previous function is still served from cache. If two custom sources can
+return different completions for the same input, force a fresh fetch by also changing `endpoint` or
+`completionMode`, or by remounting.
+
 Custom effect names + persisted settings: an app that lets users pick effects should validate a
 persisted name against the effects it actually registered (built-ins from `GLOW_VARIANTS` plus its
 own), falling back to `torch` for an unknown name — the component itself accepts any string for

README.md

@@ -1,4 +1,4 @@
-![light-input demo](static/demo.gif)
+![light-input demo](https://raw.githubusercontent.com/ui4ai/light-input/main/static/demo.gif)
 
 # @ui4ai/light-input
 
@@ -92,16 +92,22 @@ in one prop. The explicit form is the escape hatch — an explicit `glow` or `la
 machinery. When `complete` is set it replaces the `endpoint` fetch for `llm` mode:
 
 ```svelte
-<script>
-	const complete = async (text, { signal }) => {
+<script lang="ts">
+	import { GhostInput, type CompleteFn } from '@ui4ai/light-input';
+
+	const complete: CompleteFn = async (text, { signal }) => {
 		const r = await fetch('/my/endpoint', { method: 'POST', body: text, signal });
-		return (await r.json()).completion; // raw continuation; the component normalizes it
+		const data = (await r.json()) as { completion: string };
+		return data.completion; // raw continuation; the component normalizes it
 	};
 </script>
 
 <GhostInput {complete} />
 ```
 
+`CompleteFn` is exported from the package root, so your `complete` type-checks against the exact
+signature the component expects (`(text: string, ctx: { signal: AbortSignal }) => Promise<string>`).
+
 **Thinking indicator.** `loadingGlow` chooses where the "thinking" light shows while the model works:
 `"torch"` (a weak flashlight warming up from the caret — the default), `"field"` (the whole input
 warms), or `"none"` (invisible loading).
@@ -127,9 +133,12 @@ indicator's contents, and every other node stays byte-identical to the built-in
 The `waiting` snippet renders only where the default torch stack would — so with `loadingGlow="none"`
 neither the snippet nor the default beams appear (style the field instead).
 
-**Other props:** `theme` (`"dark"` | `"light"`), `lightFlow` (keep the flow/particle motion drifting;
-`false` for a steadier reveal), `completionMode` (`"llm"` | `"demo"`), `minChars` (2), `maxChars`
-(2000), `debounceMs` (260), `placeholder`, `touchAccept` (the mobile accept button).
+**Other props:** `value` (two-way bindable input text — `bind:value`), `onaccept` (callback
+`({ word, text }) => void`, fired when a word is accepted), `theme` (`"dark"` | `"light"`),
+`lightFlow` (keep the flow/particle motion drifting; `false` for a steadier reveal), `completionMode`
+(`"llm"` | `"demo"`), `minChars` (2 — compared **strictly greater-than**, so a prediction needs
+`value.trim().length > minChars`, i.e. 3+ non-space characters at the default), `maxChars` (2000),
+`debounceMs` (260), `placeholder`, `touchAccept` (the mobile accept button).
 
 ## Authoring your own effect
 
@@ -153,8 +162,8 @@ export default defineEffect({ meta }); // add `layer` for a DOM effect
 <GhostInput effect={myEffect} />
 ```
 
-`defineEffect` returns its argument unchanged and, in dev, warns if `meta.name` is not kebab-case (the
-name becomes the `data-glow` selector every rule keys on).
+`defineEffect` returns its argument unchanged and warns at runtime if `meta.name` is not kebab-case
+(the name becomes the `data-glow` selector every rule keys on).
 
 ## The effects
 
@@ -209,15 +218,16 @@ This repo is both the published library (`src/lib`) and its demo app (`src/route
 project.
 
 ```
+CONTRACT.md                 the effect-authoring reference (repo root; also shipped in the tarball)
 src/lib/                    the package (built by @sveltejs/package into dist/)
   GhostInput.svelte         the component
   input/                    the completion state machine (debounce, cache, abort, glyphs, selection)
+    types.ts                public snippet/callback types (CaretState, AcceptDetail)
   effects/
     core.css                the shared anatomy every effect builds on
     <name>/                 one folder per effect: index.css, meta.ts, index.ts, optional Layer.svelte
     index.ts                the ALL-39 registry (the ./effects entry)
     types.ts, define.ts     the effect contract types + defineEffect()
-    CONTRACT.md             the effect-authoring reference (also shipped in the tarball)
 src/routes/                 the demo app (landing gallery + a local OpenRouter proxy, not packaged)
 scripts/                    packaging + QA tooling (below)
 ```
@@ -254,13 +264,17 @@ the `@ui4ai` scope.
 
 ### Known limitation — `prefers-reduced-motion`
 
-The core anatomy honors `prefers-reduced-motion: reduce` for the default (torch) layers, but a
-per-effect module's own infinite animations **intentionally override it** — a `data-glow`-scoped
-module rule at (0,5,0) beats the media query's base-anatomy `animation: none` at (0,2,0). This is a
-deliberate parity choice for this `0.1.0`: the effects keep their visual identity, and full reduced-
-motion support (adding scoped `animation: none` under the media query for each module) is tracked as a
-follow-up. If motion sensitivity matters for your app, prefer `torch` or set `lightFlow={false}` to
-calm the flow/particle layers.
+Reduced-motion support is **partial** in `0.1.0`. `core.css` carries a
+`@media (prefers-reduced-motion: reduce)` block, but its `animation: none` rules are low-specificity
+(0,1,0)/(0,2,0), so they only win where nothing outranks them. In practice today: the **caret
+blink/think** and the **word / tail entrance** animations stop, but the **torch beams** and the
+**field wash** keep animating — the anatomy that drives them lives at `data-glow`-scoped (0,5,0)
+rules that outrank the media kill (and per-effect modules layer their own (0,5,0) animations on top).
+
+So an effect keeps its visual identity under reduced-motion rather than going still. Full parity —
+emitting a scoped `animation: none` at (0,5,0) under the media query for the core beams and every
+module — is a tracked follow-up. If motion sensitivity matters for your app, prefer `torch` and set
+`lightFlow={false}` to calm the flow/particle layers.
 
 ## License
 

package.json

@@ -74,7 +74,7 @@
 		"test": "vitest run",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-		"package": "svelte-kit sync && svelte-package && publint",
+		"package": "svelte-kit sync && svelte-package && node scripts/fix-dts.mjs && publint",
 		"prepublishOnly": "npm run check && npm test && npm run package",
 		"pack-smoke": "node scripts/pack-smoke.mjs",
 		"qa:oracle": "node scripts/qa/style-oracle.mjs",
@@ -92,6 +92,7 @@
 		"@types/node": "^25.9.3",
 		"happy-dom": "^20.10.6",
 		"playwright": "^1.61.1",
+		"postcss": "^8.5.15",
 		"publint": "^0.3.21",
 		"svelte": "^5.56.3",
 		"svelte-check": "^4.6.0",

scripts/fix-dts.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// scripts/fix-dts.mjs
+//
+// Post-`svelte-package` step: strip side-effect CSS imports from the emitted declaration files.
+//
+// svelte-package copies the component/effect source imports verbatim into the generated `.d.ts`,
+// including the side-effect CSS imports that carry the skin at runtime:
+//
+//   dist/GhostInput.svelte.d.ts    ->  import './effects/core.css';
+//   dist/effects/<name>/index.d.ts ->  import '../core.css';  +  import './index.css';
+//
+// A `.d.ts` is type-checked by any consumer whose tsconfig has `skipLibCheck: false`. TypeScript
+// then tries to resolve those `.css` specifiers as modules and fails — TS2882 ("module 'X' can only
+// be default-imported using esModuleInterop" is the sibling; the concrete failure here is TS2307
+// "cannot find module './index.css'") — a hard error the consumer never asked for. The CSS is a
+// pure runtime side effect; it has no place in the declaration graph. So we delete exactly those
+// side-effect-import lines from every shipped `.d.ts`.
+//
+// SAFETY: only whole lines that ARE a bare side-effect CSS import are removed
+// (`import '<path>.css';` / `import "<path>.css";`, leading whitespace allowed). Lines that merely
+// mention a `.css` path inside a comment or a JSDoc block (e.g. the `defineEffect` example in
+// effects/define.d.ts) are left untouched — the regex requires the line to START with `import`.
+// `.d.ts.map` files are irrelevant (they map declarations, not imports) and are left alone.
+//
+// Idempotent: running it twice is a no-op. Exits non-zero if the dist dir is missing.
+//
+// Usage: node scripts/fix-dts.mjs   (invoked by the `package` npm script after svelte-package)
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const REPO = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const DIST = path.join(REPO, 'dist');
+
+// A whole line that is a side-effect CSS import: optional indent, `import`, a quoted specifier that
+// ends in `.css`, a semicolon, optional trailing whitespace. No import binding (that would be a
+// typed import, which we never generate for CSS).
+const CSS_SIDE_EFFECT_IMPORT = /^\s*import\s+(['"])[^'"]+\.css\1\s*;\s*$/;
+
+function walk(dir) {
+	const out = [];
+	for (const entry of readdirSync(dir)) {
+		const full = path.join(dir, entry);
+		const st = statSync(full);
+		if (st.isDirectory()) out.push(...walk(full));
+		else if (full.endsWith('.d.ts')) out.push(full);
+	}
+	return out;
+}
+
+if (!existsSync(DIST)) {
+	console.error('[fix-dts] dist/ not found — run svelte-package first.');
+	process.exit(1);
+}
+
+const files = walk(DIST);
+let touched = 0;
+let removedLines = 0;
+
+for (const file of files) {
+	const src = readFileSync(file, 'utf8');
+	// Preserve the original EOL style; svelte-package emits \n.
+	const lines = src.split('\n');
+	const kept = lines.filter((line) => {
+		if (CSS_SIDE_EFFECT_IMPORT.test(line)) {
+			removedLines++;
+			return false;
+		}
+		return true;
+	});
+	if (kept.length !== lines.length) {
+		writeFileSync(file, kept.join('\n'));
+		touched++;
+	}
+}
+
+console.log(
+	`[fix-dts] scanned ${files.length} .d.ts file(s); stripped ${removedLines} side-effect CSS ` +
+		`import line(s) from ${touched} file(s).`
+);