@classytic/labs 0.3.0 → 0.5.0

package/dist/discrete/statement-logic/preset.mjs

@@ -2,6 +2,8 @@
 
 import { ActionButton, AssessedChoiceGroup, IconButton } from "../../kit/controls.mjs";
 import { Activity } from "../../kit/activity.mjs";
+import { Figure, HUE } from "../../kit/figure/figure.mjs";
+import { FigText } from "../../kit/figure/text.mjs";
 import { answerOptions, expectedAnswer, validateStatementRounds } from "./core.mjs";
 import { useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -41,6 +43,13 @@ const DEFAULT_STATEMENT_ROUNDS = [
 		id: "truth-context",
 		kind: "truth",
 		context: "A box contains 3 red counters and 2 blue counters.",
+		objects: [{
+			color: HUE.danger,
+			count: 3
+		}, {
+			color: "var(--stage-accent)",
+			count: 2
+		}],
 		statement: "More than half of the counters are red.",
 		answer: true,
 		explanation: "Three of the five counters are red, and 3/5 is more than one half."
@@ -49,10 +58,12 @@ const DEFAULT_STATEMENT_ROUNDS = [
 		id: "negate-all",
 		kind: "negate",
 		statement: "Every lantern is lit.",
+		itemCount: 5,
 		choices: [
 			{
 				value: "none",
-				label: "No lantern is lit."
+				label: "No lantern is lit.",
+				feedback: "\"No lantern is lit\" is a much STRONGER claim than the negation needs. To disprove \"every lantern is lit,\" one unlit lantern is already enough; the rest could still be lit."
 			},
 			{
 				value: "one-dark",
@@ -60,7 +71,8 @@ const DEFAULT_STATEMENT_ROUNDS = [
 			},
 			{
 				value: "one-lit",
-				label: "At least one lantern is lit."
+				label: "At least one lantern is lit.",
+				feedback: "This does not contradict the original claim at all. \"Every lantern is lit\" already implies at least one is lit, so this could be true right alongside the original statement -- it is not a negation of it."
 			}
 		],
 		answer: "one-dark",
@@ -187,6 +199,9 @@ function StatementLogicLab({ rounds = DEFAULT_STATEMENT_ROUNDS, startAt = 0, tit
 								/* @__PURE__ */ jsxs("span", { children: [/* @__PURE__ */ jsx("small", { children: copy.conclusion }), round.conclusion] })
 							]
 						}) : /* @__PURE__ */ jsx("blockquote", { children: round.statement }),
+						round.kind === "truth" && round.objects && /* @__PURE__ */ jsx(TruthCountersScene, { objects: round.objects }),
+						round.kind === "negate" && round.itemCount && /* @__PURE__ */ jsx(NegateItemsScene, { count: round.itemCount }),
+						round.kind === "implication" && /* @__PURE__ */ jsx(ImplicationWorldsScene, { worlds: round.worlds }),
 						/* @__PURE__ */ jsx("div", {
 							className: "statement-logic-response",
 							children: /* @__PURE__ */ jsx(AssessedChoiceGroup, {
@@ -203,7 +218,7 @@ function StatementLogicLab({ rounds = DEFAULT_STATEMENT_ROUNDS, startAt = 0, tit
 				className: "statement-logic-verdict",
 				"data-correct": correct || void 0,
 				children: [correct ? /* @__PURE__ */ jsx(Check, { "aria-hidden": "true" }) : /* @__PURE__ */ jsx(X, { "aria-hidden": "true" }), correct ? copy.correct : copy.tryAgain]
-			}), /* @__PURE__ */ jsx("p", { children: round.explanation })] }) : round.kind === "implication" ? /* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "Hint" }), /* @__PURE__ */ jsx("p", { children: copy.counterexampleHint })] }) : null,
+			}), /* @__PURE__ */ jsx("p", { children: correct ? round.explanation : options.find((o) => o.value === selected)?.feedback ?? round.explanation })] }) : round.kind === "implication" ? /* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "Hint" }), /* @__PURE__ */ jsx("p", { children: copy.counterexampleHint })] }) : null,
 			/* @__PURE__ */ jsxs(Activity.Transport, { children: [
 				/* @__PURE__ */ jsx(IconButton, {
 					label: copy.reset,
@@ -240,6 +255,124 @@ function StatementLogicLab({ rounds = DEFAULT_STATEMENT_ROUNDS, startAt = 0, tit
 		]
 	});
 }
+const COUNTER_R = 9;
+const COUNTER_GAP = 24;
+/** The counters a "truth" round's context describes, actually drawn in a box, not only named in
+* a sentence. An audit named this lab specifically: no graphics anywhere, purely text at an age
+* this concrete a scenario should be countable by eye, not only by reading. */
+function TruthCountersScene({ objects }) {
+	const perRow = 5;
+	const rows = [];
+	objects.forEach((group) => {
+		for (let i = 0; i < group.count; i++) rows.push({
+			x: 24 + rows.length % perRow * COUNTER_GAP,
+			y: 24 + Math.floor(rows.length / perRow) * COUNTER_GAP,
+			color: group.color
+		});
+	});
+	const cols = Math.min(perRow, rows.length);
+	const boxRows = Math.ceil(rows.length / perRow);
+	const w = 24 + cols * COUNTER_GAP + 12;
+	const h = 24 + boxRows * COUNTER_GAP + 4;
+	return /* @__PURE__ */ jsxs(Figure, {
+		className: "statement-logic-counters",
+		viewBox: `0 0 ${w} ${h}`,
+		label: objects.map((group) => `${group.count} counters`).join(", "),
+		domain: "math",
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: "4",
+			y: "4",
+			width: w - 8,
+			height: h - 8,
+			rx: "8",
+			fill: "none",
+			stroke: "var(--stage-muted)",
+			strokeWidth: "2"
+		}), rows.map((dot, i) => /* @__PURE__ */ jsx("circle", {
+			cx: dot.x,
+			cy: dot.y,
+			r: COUNTER_R,
+			fill: dot.color
+		}, i))]
+	});
+}
+/**
+* Each world in an implication round, drawn from its STRUCTURED premise/conclusion booleans, not
+* from parsing the label text -- so this works for any implication round an author writes, not
+* only the default "blue card with a star" example. Fill marks the premise; the glyph inside
+* marks the conclusion, so the counterexample (premise true, conclusion false) is visibly the
+* one filled card with an empty glyph.
+*/
+function ImplicationWorldsScene({ worlds }) {
+	const cardW = 84, cardH = 100;
+	const w = worlds.length * cardW + (worlds.length - 1) * 16 + 16;
+	return /* @__PURE__ */ jsx(Figure, {
+		className: "statement-logic-worlds",
+		viewBox: `0 0 ${w} 116`,
+		label: worlds.map((world) => `${world.label}: premise ${world.premiseTrue ? "true" : "false"}, conclusion ${world.conclusionTrue ? "true" : "false"}`).join(". "),
+		children: worlds.map((world, i) => {
+			const x = 8 + i * 100;
+			return /* @__PURE__ */ jsxs("g", { children: [
+				/* @__PURE__ */ jsx("rect", {
+					x,
+					y: 8,
+					width: cardW,
+					height: cardH,
+					rx: "10",
+					fill: world.premiseTrue ? "var(--stage-accent)" : "var(--stage-grid)",
+					fillOpacity: world.premiseTrue ? .22 : 1,
+					stroke: world.premiseTrue ? "var(--stage-accent)" : "var(--stage-muted)",
+					strokeWidth: "2"
+				}),
+				world.conclusionTrue ? /* @__PURE__ */ jsx("path", {
+					d: `M${x + cardW / 2} 32 l6 14 15 2 -11 10 3 15 -13 -8 -13 8 3 -15 -11 -10 15 -2 Z`,
+					fill: "var(--stage-good)"
+				}) : /* @__PURE__ */ jsx("circle", {
+					cx: x + cardW / 2,
+					cy: 54,
+					r: "16",
+					fill: "none",
+					stroke: "var(--stage-muted)",
+					strokeWidth: "3"
+				}),
+				/* @__PURE__ */ jsxs(FigText, {
+					x: x + cardW / 2,
+					y: 94,
+					anchor: "middle",
+					size: "note",
+					tone: "soft",
+					caps: false,
+					children: [
+						"P ",
+						world.premiseTrue ? "✓" : "✗",
+						" · C ",
+						world.conclusionTrue ? "✓" : "✗"
+					]
+				})
+			] }, world.id);
+		})
+	});
+}
+/** The items a "negate the universal claim" round ranges over, drawn all matching the claim (as
+* stated), so "at least one exception disproves it" is a picture a learner can point at instead
+* of an abstract rule about the word "every." */
+function NegateItemsScene({ count }) {
+	const r = 14, gap = 40, w = count * gap + 16;
+	return /* @__PURE__ */ jsx(Figure, {
+		className: "statement-logic-items",
+		viewBox: `0 0 ${w} 60`,
+		label: `${count} items, all currently matching the claim`,
+		domain: "math",
+		children: Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsx("circle", {
+			cx: 36 + i * gap,
+			cy: "30",
+			r,
+			fill: "var(--stage-good)",
+			stroke: "var(--stage-fg)",
+			strokeWidth: "1.5"
+		}, i))
+	});
+}
 
 //#endregion
 export { DEFAULT_STATEMENT_ROUNDS, StatementLogicLab };

package/dist/discrete/truth-table/index.d.mts

@@ -1 +1,2 @@
-import { TruthTableLab, TruthTableMode, TruthTableProps } from "./preset.mjs";
+import { TruthTableLab, TruthTableMode, TruthTableProps } from "./preset.mjs";
+export { TruthTableLab, type TruthTableMode, type TruthTableProps };

package/dist/discrete/truth-table/preset.d.mts

@@ -1,5 +1,4 @@
 import { ReactNode } from "react";
-
 //#region src/discrete/truth-table/preset.d.ts
 type TruthTableMode = 'show' | 'fill' | 'classify';
 interface TruthTableProps {
@@ -15,16 +14,6 @@ interface TruthTableProps {
   hints?: string[];
   controlId?: string;
 }
-declare function TruthTableLab({
-  formula,
-  compare,
-  mode: mode0,
-  breakdown,
-  title,
-  prompt,
-  objectives,
-  hints: hintList,
-  controlId
-}: TruthTableProps): ReactNode;
+declare function TruthTableLab({ formula, compare, mode: mode0, breakdown, title, prompt, objectives, hints: hintList, controlId }: TruthTableProps): ReactNode;
 //#endregion
 export { TruthTableLab, TruthTableMode, TruthTableProps };

package/dist/discrete/truth-table/preset.mjs

@@ -3,12 +3,13 @@
 import { Tex as Tex$1 } from "../../core/tex.mjs";
 import { CheckButton, Chip, StatusPill } from "../../kit/controls.mjs";
 import { Activity } from "../../kit/activity.mjs";
+import { STROKE } from "../../kit/figure/figure.mjs";
 import { ChallengeCard, HintLadder, RevealSolution, useChallenge, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
 import { Lamp, ToggleSwitch } from "../../kit/logic-gates/display.mjs";
 import { classify, compileLogic as compileLogic$1, equivalent, evalBool, logicToLatex as logicToLatex$1 } from "../index.mjs";
 import { useMemo, useState } from "react";
-import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useControlSurface, useLearner } from "@classytic/stage";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { Button } from "@/components/ui/button";
 
 //#region src/discrete/truth-table/preset.tsx
@@ -233,13 +234,15 @@ function TruthTableLab({ formula, compare, mode: mode0 = "fill", breakdown = tru
 	const finalIdx = cols.length - 1;
 	const figure = /* @__PURE__ */ jsxs(Fragment$1, { children: [
 		!compare && ast && vars.length >= 1 && vars.length <= 4 && (() => {
-			const liveOut = evalBool(ast, Object.fromEntries(vars.map((v) => [v, live[v] ?? false])));
+			const liveEnv = Object.fromEntries(vars.map((v) => [v, live[v] ?? false]));
+			const liveOut = evalBool(ast, liveEnv);
 			const flip = (v) => setLive((L) => {
 				const n = {
 					...L,
 					[v]: !(L[v] ?? false)
 				};
-				setHighlight(vars.reduce((a, vv, i) => a | (n[vv] ?? false ? 1 : 0) << vars.length - 1 - i, 0));
+				const row = vars.reduce((a, vv, i) => a | (n[vv] ?? false ? 1 : 0) << vars.length - 1 - i, 0);
+				setHighlight(row);
 				return n;
 			});
 			const sw = 54, lampX = vars.length * sw + 56;
@@ -290,7 +293,7 @@ function TruthTableLab({ formula, compare, mode: mode0 = "fill", breakdown = tru
 								x2: lampX - 18,
 								y2: 34,
 								stroke: liveOut ? "var(--stage-live)" : "var(--stage-wire)",
-								strokeWidth: 2.5,
+								strokeWidth: STROKE.edge,
 								strokeLinecap: "round"
 							}),
 							/* @__PURE__ */ jsx(Lamp, {

package/dist/discrete/venn/index.d.mts

@@ -1 +1,2 @@
-import { VennMode, VennSet, VennSetBoardLab, VennSetBoardProps } from "./preset.mjs";
+import { VennMode, VennSet, VennSetBoardLab, VennSetBoardProps } from "./preset.mjs";
+export { type VennMode, type VennSet, VennSetBoardLab, type VennSetBoardProps };

package/dist/discrete/venn/preset.d.mts

@@ -1,6 +1,6 @@
 import { Elem } from "../core/sets.mjs";
+import "../core/index.mjs";
 import { ReactNode } from "react";
-
 //#region src/discrete/venn/preset.d.ts
 interface VennSet {
   name: string;
@@ -18,15 +18,6 @@ interface VennSetBoardProps {
   hints?: string[];
   controlId?: string;
 }
-declare function VennSetBoardLab({
-  sets,
-  mode: mode0,
-  target,
-  title,
-  prompt,
-  objectives,
-  hints: hintList,
-  controlId
-}: VennSetBoardProps): ReactNode;
+declare function VennSetBoardLab({ sets, mode: mode0, target, title, prompt, objectives, hints: hintList, controlId }: VennSetBoardProps): ReactNode;
 //#endregion
 export { VennMode, VennSet, VennSetBoardLab, VennSetBoardProps };

package/dist/discrete/venn/preset.mjs

@@ -2,11 +2,13 @@
 
 import { CheckButton, Chip, IconButton, StatusPill } from "../../kit/controls.mjs";
 import { Activity } from "../../kit/activity.mjs";
+import { Figure, STROKE } from "../../kit/figure/figure.mjs";
+import { FigText } from "../../kit/figure/text.mjs";
 import { ChallengeCard, HintLadder, RevealSolution, useChallenge, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
 import { inclusionExclusion } from "../core/inclusionExclusion.mjs";
 import { useId, useMemo, useState } from "react";
-import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { compileLogic, useControlSurface, useLearner } from "@classytic/stage";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { RotateCcw } from "lucide-react";
 
 //#region src/discrete/venn/preset.tsx
@@ -167,6 +169,18 @@ const regionLabel = (sig, names) => {
 	if (inN.length === 1) return `${inN[0]} only`;
 	return inN.join(" ∩ ");
 };
+/**
+* `A∩B`, `A`, never longer than n letters plus (n-1) `∩`s -- deliberately terser than
+* `regionLabel`, which can run to a full set NAME per region ("Multiples of 3 ∩ Multiples of
+* 5") and would collide with its neighbours in the tightest 3-set regions, which sit as close as
+* ~20px apart (see `GEO3`'s own centroids). The single-letter `IE_LETTERS` are already how this
+* same file's inclusion-exclusion panel refers to each set, so this is the SAME abbreviation, not
+* a second one to keep in sync with it.
+*/
+const regionSymbol = (sig) => {
+	const letters = [...sig].map((c, i) => c === "1" ? IE_LETTERS[i] : null).filter((v) => v !== null);
+	return letters.length ? letters.join("∩") : "∅";
+};
 function VennSetBoardLab({ sets, mode: mode0 = "explore", target, title = "Sets & Venn", prompt, objectives, hints: hintList, controlId }) {
 	const n = sets.length;
 	const geo = n === 3 ? GEO3 : GEO2;
@@ -188,11 +202,13 @@ function VennSetBoardLab({ sets, mode: mode0 = "explore", target, title = "Sets
 			},
 			{
 				value: "outside",
-				label: "members outside both sets must be removed"
+				label: "members outside both sets must be removed",
+				feedback: "Members outside both sets were never counted in |A| or |B| in the first place, so there is nothing there to remove. The subtraction is about members INSIDE the overlap, counted twice."
 			},
 			{
 				value: "equal-size",
-				label: "the two sets must be made equal in size"
+				label: "the two sets must be made equal in size",
+				feedback: "Inclusion–exclusion works whatever size A and B are relative to each other -- it never adjusts their sizes. It corrects a COUNTING error (the overlap counted twice), not a size mismatch."
 			}
 		],
 		answer: "double-counted",
@@ -240,8 +256,9 @@ function VennSetBoardLab({ sets, mode: mode0 = "explore", target, title = "Sets
 		names
 	]);
 	const correct = useMemo(() => shaded.size === targetKeys.size && [...shaded].every((k) => targetKeys.has(k)), [shaded, targetKeys]);
+	const solved = mode === "shade" && checked && correct && !peeked && challenge.allCorrect;
 	useCheckpoint({
-		solved: mode === "shade" && checked && correct && !peeked && challenge.allCorrect,
+		solved,
 		activity: `venn:${title}`,
 		hintsUsed: hints.count
 	});
@@ -312,11 +329,11 @@ function VennSetBoardLab({ sets, mode: mode0 = "explore", target, title = "Sets
 	const showShade = mode === "shade";
 	const figure = /* @__PURE__ */ jsx("div", {
 		className: "venn-scene",
-		children: /* @__PURE__ */ jsxs("svg", {
+		children: /* @__PURE__ */ jsxs(Figure, {
 			className: "venn-svg",
 			viewBox: `${vx} ${vy} ${vw} ${vh}`,
-			role: "img",
-			"aria-label": `Venn diagram of ${names.join(", ")}`,
+			label: `Venn diagram of ${names.join(", ")}`,
+			domain: "math",
 			children: [
 				showShade && [...shaded].map((sig) => /* @__PURE__ */ jsx(RegionShape, {
 					sig,
@@ -333,29 +350,37 @@ function VennSetBoardLab({ sets, mode: mode0 = "explore", target, title = "Sets
 					fillOpacity: .09,
 					stroke: PALETTE[i],
 					strokeOpacity: .7,
-					strokeWidth: 2
+					strokeWidth: STROKE.edge
 				}, i)),
-				geo.labels.map((l, i) => /* @__PURE__ */ jsx("text", {
+				geo.labels.map((l, i) => /* @__PURE__ */ jsx(FigText, {
 					className: "venn-svg-label",
 					x: l.x,
 					y: l.y,
-					fill: PALETTE[i],
-					fontSize: 15,
-					fontWeight: 800,
-					textAnchor: "middle",
+					size: "label",
+					tone: i === 0 ? "hue-1" : i === 1 ? "hue-2" : "hue-3",
+					anchor: "middle",
+					caps: false,
 					children: names[i]
 				}, i)),
-				mode === "explore" && regions.filter((r) => r.count > 0 && r.sig !== "0".repeat(n)).map((r) => /* @__PURE__ */ jsx("text", {
+				mode === "explore" && regions.filter((r) => r.count > 0 && r.sig !== "0".repeat(n)).map((r) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx(FigText, {
 					className: "venn-svg-count",
 					x: r.centroid[0],
-					y: r.centroid[1],
-					fill: "var(--stage-fg)",
-					fontSize: 16,
-					fontWeight: 700,
-					textAnchor: "middle",
-					dominantBaseline: "central",
+					y: r.centroid[1] - 6,
+					size: "measure",
+					anchor: "middle",
+					baseline: "middle",
 					children: r.count
-				}, r.sig))
+				}), /* @__PURE__ */ jsx(FigText, {
+					className: "venn-svg-count-symbol",
+					x: r.centroid[0],
+					y: r.centroid[1] + 10,
+					size: "note",
+					tone: "soft",
+					anchor: "middle",
+					baseline: "middle",
+					caps: false,
+					children: regionSymbol(r.sig)
+				})] }, r.sig))
 			]
 		})
 	});

package/dist/discrete/visuals/reasoning-scenes.mjs

@@ -11,7 +11,7 @@ function DominoInductionScene({ first, last, reached, base, bridge }) {
 	const values = Array.from({ length: last - first + 1 }, (_, index) => first + index);
 	const gap = 74;
 	const startX = 50;
-	const width = Math.max(620, startX * 2 + (values.length - 1) * gap + 50);
+	const width = Math.max(620, 100 + (values.length - 1) * gap + 50);
 	return /* @__PURE__ */ jsxs(Figure, {
 		viewBox: `0 0 ${width} 210`,
 		domain: "math",

package/dist/distributed-systems/core/sharding.d.mts

@@ -0,0 +1,19 @@
+//#region src/distributed-systems/core/sharding.d.ts
+type ShardKeyId = 'customer' | 'region' | 'date';
+interface ShardRecord {
+  readonly id: string;
+  readonly customer: string;
+  readonly region: string;
+  readonly date: string;
+}
+interface ShardTrace {
+  readonly key: ShardKeyId;
+  readonly routes: readonly number[];
+  readonly loads: readonly number[];
+  readonly hottest: number;
+  readonly skew: number;
+}
+declare function routeToShard(value: string, shardCount: number): number;
+declare function traceSharding(records: readonly ShardRecord[], key: ShardKeyId, shardCount?: number): ShardTrace;
+//#endregion
+export { ShardKeyId, ShardRecord, ShardTrace, routeToShard, traceSharding };

package/dist/distributed-systems/core/sharding.mjs

@@ -0,0 +1,24 @@
+import { hashKey } from "../../algorithms/hashing.mjs";
+
+//#region src/distributed-systems/core/sharding.ts
+function routeToShard(value, shardCount) {
+	if (!value) throw new Error("Shard key cannot be empty");
+	if (!Number.isInteger(shardCount) || shardCount < 2) throw new Error("Shard count must be an integer of at least 2");
+	return hashKey(value) % shardCount;
+}
+function traceSharding(records, key, shardCount = 4) {
+	if (records.length === 0) throw new Error("Sharding needs records");
+	const routes = records.map((record) => routeToShard(record[key], shardCount));
+	const loads = Array.from({ length: shardCount }, (_, shard) => routes.filter((route) => route === shard).length);
+	const hottest = Math.max(...loads);
+	return {
+		key,
+		routes,
+		loads,
+		hottest: loads.indexOf(hottest),
+		skew: hottest / (records.length / shardCount)
+	};
+}
+
+//#endregion
+export { routeToShard, traceSharding };

package/dist/distributed-systems/foundation/shard-key.d.mts

@@ -0,0 +1,8 @@
+import { ReactNode } from "react";
+//#region src/distributed-systems/foundation/shard-key.d.ts
+declare function ShardKeyLab({ title, prompt }: {
+  readonly title?: string;
+  readonly prompt?: string;
+}): ReactNode;
+//#endregion
+export { ShardKeyLab };

package/dist/distributed-systems/foundation/shard-key.mjs

@@ -0,0 +1,103 @@
+'use client';
+
+import { Segmented } from "../../kit/controls.mjs";
+import { Activity, StepTransport } from "../../kit/activity.mjs";
+import { Stat, StatList } from "../../kit/frame.mjs";
+import { traceSharding } from "../core/sharding.mjs";
+import { ShardKeyBoard } from "../visuals/shard-key-board.mjs";
+import { useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/distributed-systems/foundation/shard-key.tsx
+const RECORDS = Array.from({ length: 12 }, (_, index) => ({
+	id: `O-${index + 1}`,
+	customer: `customer-${index + 1}`,
+	region: index < 9 ? "east" : "west",
+	date: "2026-09-16"
+}));
+const KEY_OPTIONS = [
+	{
+		value: "customer",
+		label: "Customer"
+	},
+	{
+		value: "region",
+		label: "Region"
+	},
+	{
+		value: "date",
+		label: "Date"
+	}
+];
+function ShardKeyLab({ title = "Choose the shard key", prompt = "Route the same orders with each key. Find the choice that prevents one shard from becoming a bottleneck." }) {
+	const traces = useMemo(() => ({
+		customer: traceSharding(RECORDS, "customer"),
+		region: traceSharding(RECORDS, "region"),
+		date: traceSharding(RECORDS, "date")
+	}), []);
+	const [selected, setSelected] = useState("date");
+	const [count, setCount] = useState(0);
+	const trace = traces[selected];
+	const visible = trace.routes.slice(0, count);
+	const loads = Array.from({ length: 4 }, (_, shard) => visible.filter((route) => route === shard).length);
+	const liveSkew = count === 0 ? 0 : Math.max(...loads) / (count / loads.length);
+	const completed = count === RECORDS.length;
+	const choose = (key) => {
+		setSelected(key);
+		setCount(0);
+	};
+	return /* @__PURE__ */ jsxs(Activity.Root, {
+		className: "distributed-activity distributed-shard-key",
+		focusLayout: "compact",
+		children: [
+			/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
+				eyebrow: "Distributed systems",
+				title,
+				description: prompt
+			}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
+			/* @__PURE__ */ jsxs(Activity.Workspace, { children: [/* @__PURE__ */ jsx(Activity.Canvas, {
+				label: "Orders routed among 4 shards",
+				children: /* @__PURE__ */ jsx(ShardKeyBoard, {
+					records: RECORDS,
+					traces,
+					selected,
+					count
+				})
+			}), /* @__PURE__ */ jsxs(Activity.Dock, { children: [/* @__PURE__ */ jsx(Segmented, {
+				value: selected,
+				onChange: choose,
+				options: KEY_OPTIONS,
+				ariaLabel: "Shard key"
+			}), /* @__PURE__ */ jsxs(StatList, {
+				ariaLabel: "Routing evidence",
+				children: [
+					/* @__PURE__ */ jsx(Stat, {
+						label: "Orders routed",
+						value: `${count} / ${RECORDS.length}`
+					}),
+					/* @__PURE__ */ jsx(Stat, {
+						label: "Hottest shard",
+						value: count === 0 ? "—" : `${Math.max(...loads)} orders`,
+						tone: liveSkew >= 2 ? "danger" : void 0
+					}),
+					/* @__PURE__ */ jsx(Stat, {
+						label: "Distribution",
+						value: !completed ? "Testing…" : trace.skew <= 1.4 ? "Balanced" : "Hot shard",
+						tone: !completed ? void 0 : trace.skew <= 1.4 ? "good" : "danger"
+					})
+				]
+			})] })] }),
+			/* @__PURE__ */ jsx(Activity.Transport, { children: /* @__PURE__ */ jsx(StepTransport, {
+				onReset: () => setCount(0),
+				onStep: () => setCount((value) => Math.min(RECORDS.length, value + 1)),
+				disabled: completed,
+				state: completed ? trace.skew <= 1.4 ? "Balanced distribution" : "Hot shard found" : `${count} / ${RECORDS.length} routed`,
+				resetLabel: "Clear routed orders",
+				stepLabel: "Route next order"
+			}) })
+		]
+	});
+}
+
+//#endregion
+export { ShardKeyLab };

package/dist/distributed-systems/index.d.mts

@@ -0,0 +1,4 @@
+import { ShardKeyLab } from "./foundation/shard-key.mjs";
+import { ShardKeyId, ShardRecord, ShardTrace, routeToShard, traceSharding } from "./core/sharding.mjs";
+import { ShardKeyBoard, ShardLoadMeter } from "./visuals/shard-key-board.mjs";
+export { ShardKeyBoard, type ShardKeyId, ShardKeyLab, ShardLoadMeter, type ShardRecord, type ShardTrace, routeToShard, traceSharding };

package/dist/distributed-systems/index.mjs

@@ -0,0 +1,5 @@
+import { routeToShard, traceSharding } from "./core/sharding.mjs";
+import { ShardKeyBoard, ShardLoadMeter } from "./visuals/shard-key-board.mjs";
+import { ShardKeyLab } from "./foundation/shard-key.mjs";
+
+export { ShardKeyBoard, ShardKeyLab, ShardLoadMeter, routeToShard, traceSharding };

package/dist/distributed-systems/visuals/shard-key-board.d.mts

@@ -0,0 +1,18 @@
+import { ShardKeyId, ShardRecord, ShardTrace } from "../core/sharding.mjs";
+import { ReactNode } from "react";
+//#region src/distributed-systems/visuals/shard-key-board.d.ts
+declare function ShardLoadMeter({ index, load, capacity, active, hot }: {
+  readonly index: number;
+  readonly load: number;
+  readonly capacity?: number;
+  readonly active: boolean;
+  readonly hot: boolean;
+}): ReactNode;
+declare function ShardKeyBoard({ records, traces, selected, count }: {
+  readonly records: readonly ShardRecord[];
+  readonly traces: Record<ShardKeyId, ShardTrace>;
+  readonly selected: ShardKeyId;
+  readonly count: number;
+}): ReactNode;
+//#endregion
+export { ShardKeyBoard, ShardLoadMeter };