@classytic/labs 0.1.0 → 0.3.0

package/dist/language/ui.d.mts

@@ -5,7 +5,7 @@ import { ReactNode } from "react";
 /**
  * True once the browser's TTS voice list is populated (it loads async).
  *
- * Starts `false` — NOT seeded from `getVoices()` — so the first client render
+ * Starts `false`, NOT seeded from `getVoices()`, so the first client render
  * matches the server (where there's no `speechSynthesis`). Seeding from the
  * live voice list would make a TTS-only item render its speaker button on the
  * client but not the server → a hydration mismatch that forces React to
@@ -14,11 +14,21 @@ import { ReactNode } from "react";
  */
 declare function useVoicesReady(): boolean;
 /**
- * A speaker button — renders nothing if the item can't be voiced.
+ * The speaker glyph, a crisp inline SVG (not the 🔊 emoji, which renders
+ * inconsistently across platforms and can't be theme-coloured or stroke-matched).
+ * Inherits `currentColor` + sizes to `1em`, so it tracks the button's colour/size.
+ */
+declare function SpeakerGlyph({
+  size
+}: {
+  size?: number;
+}): ReactNode;
+/**
+ * A speaker button, renders nothing if the item can't be voiced.
  *
  * `audioUrl` items can voice on the server too (no browser needed), so they
  * render the button consistently across SSR/hydration. Browser-TTS items only
- * become voiceable once `voicesReady` flips post-mount — gating on it (instead
+ * become voiceable once `voicesReady` flips post-mount, gating on it (instead
  * of querying `window.speechSynthesis` during render) keeps the first client
  * render identical to the server.
  */
@@ -29,12 +39,26 @@ declare function Speaker({
   item: DeckItem;
   lang: string;
 }): ReactNode;
+/** Prominent but compact audio action for listening-led activities. */
+declare function ListenButton({
+  item,
+  lang,
+  label,
+  onPlay
+}: {
+  item: DeckItem;
+  lang: string;
+  label?: string;
+  onPlay?: () => void;
+}): ReactNode;
 /** A word tile coloured by part of speech, with an optional L1 gloss beneath. */
 declare function Tile({
   pos,
   text,
   gloss,
   dir,
+  lang,
+  glossLang,
   selected,
   dimmed,
   onClick,
@@ -44,10 +68,12 @@ declare function Tile({
   text: string;
   gloss?: string;
   dir?: 'ltr' | 'rtl';
+  lang?: string;
+  glossLang?: string;
   selected?: boolean;
   dimmed?: boolean;
   onClick?: () => void;
   ariaLabel?: string;
 }): ReactNode;
 //#endregion
-export { Speaker, Tile, useVoicesReady };
+export { ListenButton, Speaker, SpeakerGlyph, Tile, useVoicesReady };

package/dist/language/ui.mjs

@@ -1,12 +1,14 @@
 'use client';
 
+import { ActionButton } from "../kit/controls.mjs";
 import { POS_LABEL, hasVoiceFor, speak } from "./deck.mjs";
 import { useEffect, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Button } from "@/components/ui/button";
 
 //#region src/language/ui.tsx
 /**
-* Shared DOM UI for the language labs — Speaker button + POS-coloured Tile.
+* Shared DOM UI for the language labs, Speaker button + POS-coloured Tile.
 * Themed via the `.lang-*` classes shipped in `@classytic/labs/styles.css`
 * (POS colours come from `--lang-pos-*` tokens). Kept here, not in the generic
 * `kit/controls`, so non-language labs pay nothing for it.
@@ -14,7 +16,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * True once the browser's TTS voice list is populated (it loads async).
 *
-* Starts `false` — NOT seeded from `getVoices()` — so the first client render
+* Starts `false`, NOT seeded from `getVoices()`, so the first client render
 * matches the server (where there's no `speechSynthesis`). Seeding from the
 * live voice list would make a TTS-only item render its speaker button on the
 * client but not the server → a hydration mismatch that forces React to
@@ -35,37 +37,73 @@ function useVoicesReady() {
 	return ready;
 }
 /**
-* A speaker button — renders nothing if the item can't be voiced.
+* The speaker glyph, a crisp inline SVG (not the 🔊 emoji, which renders
+* inconsistently across platforms and can't be theme-coloured or stroke-matched).
+* Inherits `currentColor` + sizes to `1em`, so it tracks the button's colour/size.
+*/
+function SpeakerGlyph({ size = 15 }) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 24 24",
+		width: size,
+		height: size,
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: 2,
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": true,
+		focusable: "false",
+		children: [
+			/* @__PURE__ */ jsx("path", { d: "M11 5 6 9H2v6h4l5 4V5z" }),
+			/* @__PURE__ */ jsx("path", { d: "M15.5 8.5a5 5 0 0 1 0 7" }),
+			/* @__PURE__ */ jsx("path", { d: "M18.8 5.2a9 9 0 0 1 0 13.6" })
+		]
+	});
+}
+/**
+* A speaker button, renders nothing if the item can't be voiced.
 *
 * `audioUrl` items can voice on the server too (no browser needed), so they
 * render the button consistently across SSR/hydration. Browser-TTS items only
-* become voiceable once `voicesReady` flips post-mount — gating on it (instead
+* become voiceable once `voicesReady` flips post-mount, gating on it (instead
 * of querying `window.speechSynthesis` during render) keeps the first client
 * render identical to the server.
 */
 function Speaker({ item, lang }) {
 	const voicesReady = useVoicesReady();
 	if (!(Boolean(item.audioUrl) || voicesReady && hasVoiceFor(lang))) return null;
-	return /* @__PURE__ */ jsx("button", {
+	return /* @__PURE__ */ jsx(Button, {
 		type: "button",
+		size: "icon-sm",
+		variant: "ghost",
 		className: "lang-speak",
 		"aria-label": `Play pronunciation of ${item.term}`,
 		onClick: (e) => {
 			e.stopPropagation();
 			speak(item, lang);
 		},
-		children: /* @__PURE__ */ jsx("span", {
-			"aria-hidden": true,
-			children: "🔊"
-		})
+		children: /* @__PURE__ */ jsx(SpeakerGlyph, {})
+	});
+}
+/** Prominent but compact audio action for listening-led activities. */
+function ListenButton({ item, lang, label = "Play audio", onPlay }) {
+	const voicesReady = useVoicesReady();
+	return /* @__PURE__ */ jsxs(ActionButton, {
+		className: "lang-audio-action",
+		onClick: () => {
+			if (speak(item, lang)) onPlay?.();
+		},
+		disabled: !(Boolean(item.audioUrl) || voicesReady && hasVoiceFor(lang)),
+		children: [/* @__PURE__ */ jsx(SpeakerGlyph, { size: 17 }), /* @__PURE__ */ jsx("span", { children: label })]
 	});
 }
 /** A word tile coloured by part of speech, with an optional L1 gloss beneath. */
-function Tile({ pos = "other", text, gloss, dir = "ltr", selected, dimmed, onClick, ariaLabel }) {
+function Tile({ pos = "other", text, gloss, dir = "ltr", lang, glossLang, selected, dimmed, onClick, ariaLabel }) {
 	const style = { "--pos": `var(--lang-pos-${pos})` };
 	const label = ariaLabel ?? `${text}${gloss ? `, ${gloss}` : ""} (${POS_LABEL[pos]})`;
-	return /* @__PURE__ */ jsxs("button", {
+	return /* @__PURE__ */ jsxs(Button, {
 		type: "button",
+		variant: "outline",
 		className: "lang-tile",
 		style,
 		"data-sel": selected ? "true" : void 0,
@@ -76,13 +114,15 @@ function Tile({ pos = "other", text, gloss, dir = "ltr", selected, dimmed, onCli
 		children: [/* @__PURE__ */ jsx("span", {
 			className: "lang-tile-text",
 			dir,
+			lang,
 			children: text
 		}), gloss ? /* @__PURE__ */ jsx("span", {
 			className: "lang-tile-gloss",
+			lang: glossLang,
 			children: gloss
 		}) : null]
 	});
 }
 
 //#endregion
-export { Speaker, Tile, useVoicesReady };
+export { ListenButton, Speaker, SpeakerGlyph, Tile, useVoicesReady };

package/dist/language/word-match/preset.d.mts

@@ -10,13 +10,17 @@ interface WordMatchProps {
   show?: 'translation' | 'icon';
   title?: string;
   prompt?: string;
+  objectives?: string[];
+  hints?: string[];
 }
 declare function WordMatchLab({
   deck,
   count,
   show,
   title,
-  prompt
+  prompt,
+  objectives,
+  hints: hintList
 }: WordMatchProps): ReactNode;
 //#endregion
 export { WordMatchLab, WordMatchProps };

package/dist/language/word-match/preset.mjs

@@ -1,25 +1,26 @@
 'use client';
 
-import { StatusPill } from "../../kit/controls.mjs";
-import { LabFrame, LiveRegion } from "../../kit/frame.mjs";
-import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { Activity } from "../../kit/activity.mjs";
+import { HintLadder, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
 import { dirFor, seededShuffle } from "../deck.mjs";
 import { Icon } from "../icon.mjs";
 import { Speaker } from "../ui.mjs";
+import { LanguageActivity } from "../activity.mjs";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Button } from "@/components/ui/button";
 
 //#region src/language/word-match/preset.tsx
 /**
-* WordMatch — pair each word with its meaning (or picture).
+* WordMatch, pair each word with its meaning (or picture).
 *
 * Tap a word on the left, then its match on the right; a correct pair locks
-* green, a wrong pair flashes. Right side shows the translation, or — for kids /
-* concrete vocab — the item's icon (emoji/SVG), which is where image-based
+* green, a wrong pair flashes. Right side shows the translation, or, for kids /
+* concrete vocab, the item's icon (emoji/SVG), which is where image-based
 * learning genuinely helps (dual coding). Reads its whole content from a `Deck`,
 * so a new language pair is just new data.
 */
-function WordMatchLab({ deck, count, show = "translation", title = "Match the pairs", prompt = "Tap a word, then tap its match." }) {
+function WordMatchLab({ deck, count, show = "translation", title = "Match the pairs", prompt = "Tap a word, then tap its match.", objectives, hints: hintList }) {
 	const n = Math.min(count ?? 6, deck.items.length);
 	const items = useMemo(() => deck.items.slice(0, n), [deck, n]);
 	const rightOrder = useMemo(() => seededShuffle(items.map((_, i) => i), n * 13 + 5), [items, n]);
@@ -27,29 +28,33 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 	const transDir = dirFor(deck.transLang);
 	const [matched, setMatched] = useState(/* @__PURE__ */ new Set());
 	const [pending, setPending] = useState(null);
-	const [wrong, setWrong] = useState(null);
+	const [wrong, setWrong] = useState(/* @__PURE__ */ new Set());
+	const [announcement, setAnnouncement] = useState("");
 	const wrongTimer = useRef(null);
 	useEffect(() => {
 		setMatched(/* @__PURE__ */ new Set());
 		setPending(null);
-		setWrong(null);
+		setWrong(/* @__PURE__ */ new Set());
+		setAnnouncement("");
 	}, [items]);
 	useEffect(() => () => {
 		if (wrongTimer.current) clearTimeout(wrongTimer.current);
 	}, []);
 	const allDone = matched.size === items.length && items.length > 0;
+	const hints = useHints(hintList);
 	useCheckpoint({
 		solved: allDone,
 		activity: "word-match",
 		score: {
 			raw: items.length,
 			max: items.length
-		}
+		},
+		hintsUsed: hints.count
 	});
-	const flashWrong = (idx) => {
-		setWrong(idx);
+	const flashWrong = (cells) => {
+		setWrong(new Set(cells.map((cell) => `${cell.side}${cell.idx}`)));
 		if (wrongTimer.current) clearTimeout(wrongTimer.current);
-		wrongTimer.current = setTimeout(() => setWrong(null), 520);
+		wrongTimer.current = setTimeout(() => setWrong(/* @__PURE__ */ new Set()), 520);
 	};
 	const tap = (side, idx) => {
 		if (matched.has(idx)) return;
@@ -58,6 +63,7 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 				side,
 				idx
 			});
+			setAnnouncement("First item selected. Choose its match.");
 			return;
 		}
 		if (pending.side === side) {
@@ -65,18 +71,23 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 				side,
 				idx
 			});
+			setAnnouncement("Selection changed. Choose from the other column.");
 			return;
 		}
 		if (pending.idx === idx) {
 			setMatched((m) => new Set(m).add(idx));
 			setPending(null);
+			setAnnouncement(`Matched ${items[idx]?.term ?? "pair"}.`);
 		} else {
-			flashWrong(idx);
-			flashWrong(pending.idx);
+			flashWrong([{
+				side,
+				idx
+			}, pending]);
 			setPending(null);
+			setAnnouncement("Those do not match. Try another pair.");
 		}
 	};
-	const cellState = (side, idx) => matched.has(idx) ? "ok" : wrong === idx ? "no" : pending && pending.side === side && pending.idx === idx ? "sel" : "idle";
+	const cellState = (side, idx) => matched.has(idx) ? "ok" : wrong.has(`${side}${idx}`) ? "no" : pending && pending.side === side && pending.idx === idx ? "sel" : "idle";
 	const figure = /* @__PURE__ */ jsxs("div", {
 		className: "lang-lab",
 		children: [/* @__PURE__ */ jsxs("div", {
@@ -86,8 +97,9 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 				"aria-label": "words",
 				children: items.map((it, i) => /* @__PURE__ */ jsxs("div", {
 					className: "lang-match-row",
-					children: [/* @__PURE__ */ jsxs("button", {
+					children: [/* @__PURE__ */ jsxs(Button, {
 						type: "button",
+						variant: "outline",
 						className: "lang-match-cell",
 						"data-state": cellState("L", i),
 						disabled: matched.has(i),
@@ -96,6 +108,7 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 						children: [/* @__PURE__ */ jsx("span", {
 							className: "lang-cell-text",
 							dir: termDir,
+							lang: deck.termLang,
 							children: it.term
 						}), it.transliteration ? /* @__PURE__ */ jsx("span", {
 							className: "lang-cell-sub",
@@ -111,8 +124,9 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 				"aria-label": "matches",
 				children: rightOrder.map((i) => {
 					const it = items[i];
-					return /* @__PURE__ */ jsx("button", {
+					return /* @__PURE__ */ jsx(Button, {
 						type: "button",
+						variant: "outline",
 						className: "lang-match-cell",
 						"data-state": cellState("R", i),
 						disabled: matched.has(i),
@@ -126,20 +140,24 @@ function WordMatchLab({ deck, count, show = "translation", title = "Match the pa
 						}) : /* @__PURE__ */ jsx("span", {
 							className: "lang-cell-text",
 							dir: transDir,
+							lang: deck.transLang,
 							children: it.translation
 						})
 					}, `R${i}`);
 				})
 			})]
-		}), /* @__PURE__ */ jsx(LiveRegion, { children: allDone ? "All pairs matched" : "" })]
+		}), /* @__PURE__ */ jsx(Activity.LiveRegion, { children: allDone ? "All pairs matched" : announcement })]
 	});
-	return /* @__PURE__ */ jsx(LabFrame, {
+	return /* @__PURE__ */ jsx(LanguageActivity, {
 		title,
 		prompt,
-		aside: /* @__PURE__ */ jsx(StatusPill, {
-			ok: allDone,
-			children: allDone ? "✓ All matched" : `${matched.size} / ${items.length} matched`
+		objectives,
+		progress: /* @__PURE__ */ jsx(Activity.ItemProgress, {
+			done: matched.size,
+			total: items.length,
+			label: "All matched"
 		}),
+		footer: hintList?.length ? /* @__PURE__ */ jsx(HintLadder, { hints }) : void 0,
 		children: figure
 	});
 }

package/dist/logic/ChipScene.d.mts

@@ -0,0 +1,30 @@
+import { ChipId, ChipResult, Wire } from "./ic.mjs";
+import { ReactNode } from "react";
+
+//#region src/logic/ChipScene.d.ts
+interface ChipSceneProps {
+  chip: ChipId;
+  wires: Wire[];
+  inputs: {
+    A: boolean;
+    B: boolean;
+  };
+  result: ChipResult;
+  /** Pin waiting for the other end of a jumper. */
+  pending?: number | null;
+  onPin?: (pin: number) => void;
+  onSwitch?: (which: 'A' | 'B') => void;
+  label: string;
+}
+declare function ChipScene({
+  chip,
+  wires,
+  inputs,
+  result,
+  pending,
+  onPin,
+  onSwitch,
+  label
+}: ChipSceneProps): ReactNode;
+//#endregion
+export { ChipScene, ChipSceneProps };