@classytic/labs 0.1.0

package/dist/kit/steps.mjs

@@ -0,0 +1,57 @@
+'use client';
+
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/steps.tsx
+/**
+* In-lab stepper — teach ONE idea at a time (Brilliant-style), instead of dumping
+* a dense screen. A lab declares N steps and reveals layers/captions as the learner
+* hits Continue. Pure UI state; pair with `<StepNav>` (Back / dots / Continue).
+* (Distinct from stage's cross-block StepProgress — this is within a single lab.)
+*/
+function useSteps(total) {
+	const [step, setStep] = useState(0);
+	const clamp = (n) => Math.max(0, Math.min(total - 1, n));
+	return {
+		step: clamp(step),
+		total,
+		atStart: step <= 0,
+		atEnd: step >= total - 1,
+		next: () => setStep((s) => clamp(s + 1)),
+		prev: () => setStep((s) => clamp(s - 1)),
+		setStep: (n) => setStep(clamp(n))
+	};
+}
+function StepNav({ steps, nextLabel = "Continue", doneLabel = "Done" }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-stepnav",
+		children: [
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-btn lab-btn-ghost",
+				onClick: steps.prev,
+				disabled: steps.atStart,
+				children: "← Back"
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "lab-dots",
+				"aria-hidden": true,
+				children: Array.from({ length: steps.total }, (_, i) => /* @__PURE__ */ jsx("span", {
+					className: "lab-dot",
+					"data-on": i <= steps.step
+				}, i))
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-btn",
+				onClick: steps.next,
+				disabled: steps.atEnd,
+				children: steps.atEnd ? doneLabel : nextLabel
+			})
+		]
+	});
+}
+
+//#endregion
+export { StepNav, useSteps };

package/dist/kit/thermal.mjs

@@ -0,0 +1,289 @@
+'use client';
+
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/thermal.tsx
+const METAL = "var(--stage-metal, #8a8a8a)";
+const BG = "var(--stage-bg, #fff)";
+const FG = "var(--stage-fg, #222)";
+const GLASS = "color-mix(in oklab, var(--stage-fg) 28%, transparent)";
+/** Blue (cold) → red (hot) along a 0..1 fraction, in perceptual space. */
+function thermalColor(frac) {
+	return `color-mix(in oklab, #e23b3b ${(Math.max(0, Math.min(1, frac)) * 100).toFixed(0)}%, #2b7fff)`;
+}
+function ThermometerGlyph({ cx, top, h, frac, label }) {
+	const f = Math.max(0, Math.min(1, frac));
+	const bulbR = Math.max(9, h * .085);
+	const stemW = bulbR * .85;
+	const bulbCy = top + h - bulbR;
+	const stemTop = top + bulbR * .5;
+	const colBot = bulbCy;
+	const colTop = colBot - f * (colBot - stemTop);
+	const col = thermalColor(f);
+	const ticks = [
+		0,
+		.25,
+		.5,
+		.75,
+		1
+	].map((tk) => colBot - tk * (colBot - stemTop));
+	return /* @__PURE__ */ jsxs("g", {
+		"aria-hidden": true,
+		children: [
+			/* @__PURE__ */ jsx("circle", {
+				cx,
+				cy: bulbCy,
+				r: bulbR,
+				fill: col,
+				stroke: METAL,
+				strokeWidth: 2
+			}),
+			/* @__PURE__ */ jsx("rect", {
+				x: cx - stemW / 2,
+				y: stemTop,
+				width: stemW,
+				height: colBot - stemTop,
+				rx: stemW / 2,
+				fill: BG,
+				stroke: METAL,
+				strokeWidth: 2
+			}),
+			/* @__PURE__ */ jsx("rect", {
+				x: cx - stemW / 2 + 2.5,
+				y: colTop,
+				width: stemW - 5,
+				height: colBot - colTop,
+				fill: col
+			}),
+			/* @__PURE__ */ jsx("rect", {
+				x: cx - stemW / 2 + 2.5,
+				y: colBot - 4,
+				width: stemW - 5,
+				height: bulbR,
+				fill: col
+			}),
+			ticks.map((ty, i) => /* @__PURE__ */ jsx("line", {
+				x1: cx + stemW / 2 + 1,
+				y1: ty,
+				x2: cx + stemW / 2 + (i % 2 ? 5 : 8),
+				y2: ty,
+				stroke: METAL,
+				strokeWidth: 1.5
+			}, i)),
+			/* @__PURE__ */ jsx("rect", {
+				x: cx - stemW / 2 + 3,
+				y: stemTop + 3,
+				width: 2,
+				height: colBot - stemTop - 6,
+				rx: 1,
+				fill: "color-mix(in oklab, var(--stage-sheen, #fff) 55%, transparent)"
+			}),
+			label && /* @__PURE__ */ jsx("text", {
+				x: cx,
+				y: top - 4,
+				textAnchor: "middle",
+				fontSize: 12,
+				fontWeight: 700,
+				fill: FG,
+				children: label
+			})
+		]
+	});
+}
+function BeakerGlyph({ x, y, w, h, fillFrac, color, boiling = 0, steam = 0, iceFrac = 0, phase = 0, label }) {
+	const innerTop = y + 8;
+	const innerBot = y + h - 3;
+	const innerH = innerBot - innerTop;
+	const liq = Math.max(0, Math.min(1, fillFrac));
+	const liquidTop = innerBot - liq * innerH;
+	const lx = x + 4, rx = x + w - 4;
+	const nB = Math.round(boiling * 10);
+	const bubbles = [];
+	for (let i = 0; i < nB; i++) {
+		const fr = (phase * .7 + i * .137 * 7) % 1;
+		const by = innerBot - fr * (innerBot - liquidTop);
+		const bx = lx + 8 + i * .41 % 1 * (rx - lx - 16);
+		const r = 1.6 + i % 3;
+		bubbles.push(/* @__PURE__ */ jsx("circle", {
+			cx: bx,
+			cy: by,
+			r,
+			fill: BG,
+			opacity: .5 * (1 - fr) + .25
+		}, `b${i}`));
+	}
+	const nIce = iceFrac > .02 ? Math.max(1, Math.round(iceFrac * 5)) : 0;
+	const cubes = [];
+	for (let i = 0; i < nIce; i++) {
+		const s = (7 + i % 2 * 4) * (.5 + .5 * iceFrac);
+		const cxp = lx + 10 + (i * .37 + .1) % 1 * (rx - lx - 20);
+		const bob = Math.sin(phase * 1.4 + i) * 2;
+		const cyp = liquidTop + 3 + bob;
+		cubes.push(/* @__PURE__ */ jsxs("g", {
+			opacity: .9,
+			children: [/* @__PURE__ */ jsx("rect", {
+				x: cxp,
+				y: cyp,
+				width: s,
+				height: s,
+				rx: 2,
+				fill: "color-mix(in oklab, #cfeaff 80%, var(--stage-bg))",
+				stroke: "color-mix(in oklab, #2b7fff 40%, transparent)",
+				strokeWidth: 1
+			}), /* @__PURE__ */ jsx("line", {
+				x1: cxp + 2,
+				y1: cyp + s * .35,
+				x2: cxp + s - 2,
+				y2: cyp + s * .35,
+				stroke: "color-mix(in oklab, #2b7fff 30%, transparent)",
+				strokeWidth: 1
+			})]
+		}, `i${i}`));
+	}
+	const wisps = [];
+	if (steam > .04) for (let i = 0; i < 3; i++) {
+		const sx = x + w * (.3 + i * .2);
+		const off = (phase * 18 + i * 13) % 26;
+		const o = steam * .5 * (1 - off / 26);
+		wisps.push(/* @__PURE__ */ jsx("path", {
+			d: `M ${sx} ${y - off} q 6 -8 0 -16 q -6 -8 0 -16`,
+			fill: "none",
+			stroke: "color-mix(in oklab, var(--stage-fg) 35%, transparent)",
+			strokeWidth: 3,
+			strokeLinecap: "round",
+			opacity: Math.max(0, o)
+		}, `s${i}`));
+	}
+	return /* @__PURE__ */ jsxs("g", { children: [
+		wisps,
+		liq > .001 && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("rect", {
+			x: lx,
+			y: liquidTop,
+			width: rx - lx,
+			height: innerBot - liquidTop,
+			fill: color,
+			fillOpacity: .45
+		}), /* @__PURE__ */ jsx("ellipse", {
+			cx: (lx + rx) / 2,
+			cy: liquidTop,
+			rx: (rx - lx) / 2,
+			ry: 4,
+			fill: color,
+			fillOpacity: .7
+		})] }),
+		bubbles,
+		cubes,
+		/* @__PURE__ */ jsx("path", {
+			d: `M ${x} ${y} L ${lx} ${innerBot} Q ${x + w / 2} ${y + h + 4} ${rx} ${innerBot} L ${x + w} ${y}`,
+			fill: "none",
+			stroke: GLASS,
+			strokeWidth: 3,
+			strokeLinejoin: "round",
+			strokeLinecap: "round"
+		}),
+		/* @__PURE__ */ jsx("line", {
+			x1: x - 3,
+			y1: y,
+			x2: x + w + 3,
+			y2: y,
+			stroke: METAL,
+			strokeWidth: 3,
+			strokeLinecap: "round"
+		}),
+		label && /* @__PURE__ */ jsx("text", {
+			x: x + w / 2,
+			y: y + h + 22,
+			textAnchor: "middle",
+			fontSize: 12,
+			fontWeight: 700,
+			fill: FG,
+			children: label
+		})
+	] });
+}
+function BurnerGlyph({ cx, baseY, w, level, phase = 0 }) {
+	const flame = Math.max(0, level);
+	const cold = Math.max(0, -level);
+	const flicker = 1 + Math.sin(phase * 9) * .06;
+	const fh = flame * (w * 1.5) * flicker;
+	const fw = w * .42;
+	const tip = baseY - fh;
+	const teardrop = (scale, fill, op) => {
+		const hw = fw * scale, ht = fh * scale, ty = baseY - ht;
+		return /* @__PURE__ */ jsx("path", {
+			d: `M ${cx} ${baseY + 3} C ${cx - hw} ${baseY - ht * .4} ${cx - hw * .5} ${ty} ${cx} ${ty} C ${cx + hw * .5} ${ty} ${cx + hw} ${baseY - ht * .4} ${cx} ${baseY + 3} Z`,
+			fill,
+			opacity: op
+		});
+	};
+	return /* @__PURE__ */ jsxs("g", {
+		"aria-hidden": true,
+		children: [
+			/* @__PURE__ */ jsx("rect", {
+				x: cx - w / 2,
+				y: baseY,
+				width: w,
+				height: 9,
+				rx: 4,
+				fill: METAL
+			}),
+			/* @__PURE__ */ jsx("rect", {
+				x: cx - w / 2 - 4,
+				y: baseY + 9,
+				width: w + 8,
+				height: 4,
+				rx: 2,
+				fill: "color-mix(in oklab, var(--stage-metal) 70%, var(--stage-bg))"
+			}),
+			flame > .02 && /* @__PURE__ */ jsxs(Fragment, { children: [
+				teardrop(1.25, "color-mix(in oklab, var(--stage-warn, #e0a020) 55%, transparent)", .35),
+				teardrop(1, "var(--stage-warn, #e0a020)", .9),
+				teardrop(.6, "color-mix(in oklab, #ffd23b 80%, var(--stage-warn))", .95),
+				teardrop(.28, "color-mix(in oklab, #fff 75%, #ffd23b)", .95),
+				/* @__PURE__ */ jsx("circle", {
+					cx,
+					cy: tip,
+					r: 1.5,
+					fill: "#fff",
+					opacity: .8
+				})
+			] }),
+			cold > .02 && /* @__PURE__ */ jsx("g", {
+				opacity: .5 + cold * .45,
+				stroke: "color-mix(in oklab, #2b7fff 70%, var(--stage-bg))",
+				strokeWidth: 2,
+				strokeLinecap: "round",
+				children: [
+					-1,
+					0,
+					1
+				].map((k) => {
+					const sx = cx + k * w * .28, len = 10 + cold * 12;
+					return /* @__PURE__ */ jsxs("g", { children: [
+						/* @__PURE__ */ jsx("line", {
+							x1: sx,
+							y1: baseY + 14,
+							x2: sx,
+							y2: baseY + 14 + len
+						}),
+						/* @__PURE__ */ jsx("line", {
+							x1: sx - 4,
+							y1: baseY + 18,
+							x2: sx + 4,
+							y2: baseY + 22
+						}),
+						/* @__PURE__ */ jsx("line", {
+							x1: sx + 4,
+							y1: baseY + 18,
+							x2: sx - 4,
+							y2: baseY + 22
+						})
+					] }, k);
+				})
+			})
+		]
+	});
+}
+
+//#endregion
+export { BeakerGlyph, BurnerGlyph, ThermometerGlyph, thermalColor };

package/dist/language/agreement/index.d.mts

@@ -0,0 +1 @@
+import { AgreementItem, AgreementLab, AgreementProps } from "./preset.mjs";

package/dist/language/agreement/preset.d.mts

@@ -0,0 +1,27 @@
+import { ReactNode } from "react";
+
+//#region src/language/agreement/preset.d.ts
+interface AgreementItem {
+  /** The subject, e.g. "She" / "They" / "The boys". */
+  subject: string;
+  /** Verb-form choices, e.g. ["go", "goes"] or ["is", "are", "am"]. */
+  options: string[];
+  /** The correct form. */
+  correct: string;
+  /** Rest of the sentence after the verb, e.g. "to school". */
+  tail?: string;
+  /** One-line reason shown after a correct pick. */
+  note?: string;
+}
+interface AgreementProps {
+  items: AgreementItem[];
+  title?: string;
+  prompt?: string;
+}
+declare function AgreementLab({
+  items,
+  title,
+  prompt
+}: AgreementProps): ReactNode;
+//#endregion
+export { AgreementItem, AgreementLab, AgreementProps };

package/dist/language/agreement/preset.mjs

@@ -0,0 +1,113 @@
+'use client';
+
+import { CheckButton, StatusPill } from "../../kit/controls.mjs";
+import { ControlBar, LabFrame } from "../../kit/frame.mjs";
+import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { useEffect, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/language/agreement/preset.tsx
+/**
+* AgreementLab — make the verb agree with its subject.
+*
+* Bangla drops the present copula ("He doctor") and has no 3rd-person -s
+* ("She go"), so subject–verb agreement is a core English error. The learner
+* picks the verb form that matches the subject; on a correct pick the pair links
+* up (color + connector) and the full sentence assembles, making concord visible.
+*/
+function AgreementLab({ items, title = "Make them agree", prompt = "Pick the verb form that matches the subject." }) {
+	const [idx, setIdx] = useState(0);
+	const [picked, setPicked] = useState(null);
+	const [solvedCount, setSolvedCount] = useState(0);
+	useEffect(() => {
+		setIdx(0);
+		setPicked(null);
+		setSolvedCount(0);
+	}, [items]);
+	const item = items[idx];
+	const correct = picked !== null && item !== void 0 && picked === item.correct;
+	const total = items.length;
+	const allDone = solvedCount >= total && total > 0;
+	useCheckpoint({
+		solved: allDone,
+		activity: "agreement",
+		score: {
+			raw: total,
+			max: total
+		}
+	});
+	if (!item) return null;
+	const pick = (v) => {
+		if (correct) return;
+		setPicked(v);
+		if (v === item.correct) setSolvedCount((s) => Math.min(total, s + 1));
+	};
+	const next = () => {
+		setPicked(null);
+		setIdx((i) => Math.min(total - 1, i + 1));
+	};
+	const isLast = idx === total - 1;
+	const figure = /* @__PURE__ */ jsxs("div", {
+		className: "lang-lab",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "lang-sentence",
+				"aria-label": "sentence",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "lang-subject",
+						"data-ok": correct ? "true" : void 0,
+						children: item.subject
+					}),
+					correct ? /* @__PURE__ */ jsx("span", {
+						className: "lang-link",
+						"aria-hidden": true,
+						children: "↔"
+					}) : null,
+					/* @__PURE__ */ jsx("span", {
+						className: "lang-blank",
+						"data-state": picked === null ? "idle" : correct ? "ok" : "no",
+						children: picked ?? "▢"
+					}),
+					item.tail ? /* @__PURE__ */ jsx("span", { children: item.tail }) : null
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "lang-choices",
+				role: "group",
+				"aria-label": "verb forms",
+				children: item.options.map((v) => /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "lang-choice",
+					"data-state": picked === v ? correct ? "ok" : "no" : "idle",
+					disabled: correct,
+					onClick: () => pick(v),
+					"aria-label": v,
+					children: v
+				}, v))
+			}),
+			picked !== null && /* @__PURE__ */ jsx("p", {
+				className: "lang-why",
+				"data-state": correct ? "ok" : "no",
+				"aria-live": "polite",
+				children: correct ? item.note ?? `${item.subject} ${item.correct}${item.tail ? " " + item.tail : ""}.` : "Not quite — try another."
+			})
+		]
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		aside: /* @__PURE__ */ jsx(StatusPill, {
+			ok: allDone,
+			children: allDone ? "✓ All correct" : `${solvedCount} / ${total}`
+		}),
+		controls: correct && !isLast ? /* @__PURE__ */ jsx(ControlBar, { children: /* @__PURE__ */ jsx(CheckButton, {
+			onClick: next,
+			children: "Next"
+		}) }) : void 0,
+		children: figure
+	});
+}
+
+//#endregion
+export { AgreementLab };

package/dist/language/article-lens/index.d.mts

@@ -0,0 +1 @@
+import { Article, ArticleItem, ArticleLensLab, ArticleLensProps } from "./preset.mjs";

package/dist/language/article-lens/preset.d.mts

@@ -0,0 +1,31 @@
+import { ReactNode } from "react";
+
+//#region src/language/article-lens/preset.d.ts
+type Article = 'a' | 'an' | 'the' | '—';
+interface ArticleItem {
+  /** Text before the blank. */
+  before: string;
+  /** The noun (shown after the blank). */
+  noun: string;
+  /** Text after the noun. */
+  after?: string;
+  answer: Article;
+  /** One-line reason shown after a correct pick. */
+  why?: string;
+}
+interface ArticleLensProps {
+  items: ArticleItem[];
+  objectives?: string[];
+  hints?: string[];
+  title?: string;
+  prompt?: string;
+}
+declare function ArticleLensLab({
+  items,
+  objectives,
+  hints: hintList,
+  title,
+  prompt
+}: ArticleLensProps): ReactNode;
+//#endregion
+export { Article, ArticleItem, ArticleLensLab, ArticleLensProps };

package/dist/language/article-lens/preset.mjs

@@ -0,0 +1,125 @@
+'use client';
+
+import { CheckButton, StatusPill } from "../../kit/controls.mjs";
+import { ControlBar, LabFrame } from "../../kit/frame.mjs";
+import { HintLadder, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
+import { useEffect, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/language/article-lens/preset.tsx
+/**
+* ArticleLens — choose a / an / the / — (no article).
+*
+* Bangla has no articles, so this is the highest-novelty English error for
+* Bangla speakers. The "lens" framing: tap the article that fits, and on a
+* correct pick the rule surfaces (new → a/an, known/specific → the, general →
+* no article). Choice-based recall, distinct from the tile-building labs.
+*/
+const CHOICES = [
+	"a",
+	"an",
+	"the",
+	"—"
+];
+const RULE = {
+	a: "a → any one (new), before a consonant sound",
+	an: "an → any one (new), before a vowel sound",
+	the: "the → the specific one we both know",
+	"—": "no article → general or uncountable"
+};
+function ArticleLensLab({ items, objectives, hints: hintList, title = "Choose the article", prompt = "Bangla has no a/an/the — pick what English needs." }) {
+	const [idx, setIdx] = useState(0);
+	const [picked, setPicked] = useState(null);
+	const [solvedCount, setSolvedCount] = useState(0);
+	useEffect(() => {
+		setIdx(0);
+		setPicked(null);
+		setSolvedCount(0);
+	}, [items]);
+	const item = items[idx];
+	const correct = picked !== null && item !== void 0 && picked === item.answer;
+	const total = items.length;
+	const allDone = solvedCount >= total && total > 0;
+	const hints = useHints(hintList);
+	useCheckpoint({
+		solved: allDone,
+		activity: "article-lens",
+		score: {
+			raw: total,
+			max: total
+		},
+		hintsUsed: hints.count
+	});
+	const blank = useMemo(() => picked === null ? "▢" : picked === "—" ? "∅" : picked, [picked]);
+	if (!item) return null;
+	const pick = (a) => {
+		if (correct) return;
+		setPicked(a);
+		if (a === item.answer) setSolvedCount((s) => Math.min(total, s + 1));
+	};
+	const next = () => {
+		setPicked(null);
+		setIdx((i) => Math.min(total - 1, i + 1));
+	};
+	const isLast = idx === total - 1;
+	const figure = /* @__PURE__ */ jsxs("div", {
+		className: "lang-lab",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "lang-sentence",
+				"aria-label": "sentence",
+				children: [
+					/* @__PURE__ */ jsx("span", { children: item.before }),
+					/* @__PURE__ */ jsx("span", {
+						className: "lang-blank",
+						"data-state": picked === null ? "idle" : correct ? "ok" : "no",
+						children: blank
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "lang-noun",
+						children: item.noun
+					}),
+					item.after ? /* @__PURE__ */ jsx("span", { children: item.after }) : null
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "lang-choices",
+				role: "group",
+				"aria-label": "articles",
+				children: CHOICES.map((a) => /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "lang-choice",
+					"data-state": picked === a ? correct ? "ok" : "no" : "idle",
+					disabled: correct,
+					onClick: () => pick(a),
+					"aria-label": a === "—" ? "no article" : a,
+					children: a === "—" ? "no article" : a
+				}, a))
+			}),
+			picked !== null && /* @__PURE__ */ jsx("p", {
+				className: "lang-why",
+				"data-state": correct ? "ok" : "no",
+				"aria-live": "polite",
+				children: correct ? item.why ?? RULE[item.answer] : "Not quite — try another."
+			})
+		]
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		aside: /* @__PURE__ */ jsx(StatusPill, {
+			ok: allDone,
+			children: allDone ? "✓ All correct" : `${solvedCount} / ${total}`
+		}),
+		controls: correct && !isLast ? /* @__PURE__ */ jsx(ControlBar, { children: /* @__PURE__ */ jsx(CheckButton, {
+			onClick: next,
+			children: "Next"
+		}) }) : void 0,
+		footer: /* @__PURE__ */ jsx(HintLadder, { hints }),
+		children: figure
+	});
+}
+
+//#endregion
+export { ArticleLensLab };

package/dist/language/deck.d.mts

@@ -0,0 +1,45 @@
+import { IconValue } from "./icon.mjs";
+
+//#region src/language/deck.d.ts
+/** Part of speech — drives the Montessori-style colour coding across grammar
+ *  labs so a learner builds one consistent visual intuition. */
+type Pos = 'noun' | 'verb' | 'article' | 'adjective' | 'preposition' | 'pronoun' | 'conjunction' | 'adverb' | 'other';
+declare const POS_LABEL: Record<Pos, string>;
+interface DeckItem {
+  /** Target-language word/phrase being taught. */
+  term: string;
+  /** Its meaning in the learner's language. */
+  translation: string;
+  /** Optional romanisation / pronunciation aid (e.g. Arabic → "kitāb"). */
+  transliteration?: string;
+  /** Optional audio: an uploaded media URL OR an external URL. Never generated. */
+  audioUrl?: string;
+  /** Optional picture for kids/visual decks — an emoji string, or an `IconRef`
+   *  ({ kind:'emoji'|'svg'|'image', … }) for a registered SVG / uploaded image. */
+  icon?: IconValue;
+  /** Optional usage example (target language). */
+  example?: string;
+  tags?: string[];
+}
+interface Deck {
+  title?: string;
+  /** BCP-47 of the term side, e.g. 'en-US', 'ar', 'fr-FR', 'bn-BD'. Used for
+   *  browser-TTS voice lookup + text direction. */
+  termLang: string;
+  /** BCP-47 of the translation side. */
+  transLang: string;
+  items: DeckItem[];
+}
+type TextDir = 'ltr' | 'rtl';
+/** Text direction for a BCP-47 language tag (RTL scripts → 'rtl'). */
+declare function dirFor(lang: string): TextDir;
+declare function hasVoiceFor(lang: string): boolean;
+/** Can this item be voiced at all (own audio, or a matching browser voice)? */
+declare function canSpeak(item: DeckItem, lang: string): boolean;
+/** Play an item's audio. Returns false if nothing was playable. */
+declare function speak(item: DeckItem, lang: string): boolean;
+/** Deterministic shuffle (seeded LCG) — same input+seed → same order, so SSR
+ *  and client agree. Never uses Math.random at module scope. */
+declare function seededShuffle<T>(arr: readonly T[], seed?: number): T[];
+//#endregion
+export { Deck, DeckItem, POS_LABEL, Pos, TextDir, canSpeak, dirFor, hasVoiceFor, seededShuffle, speak };