@lssm/example.learning-journey-ui-onboarding 0.0.0-canary-20251217080011 → 0.0.0-canary-20251219202229

package/dist/examples/learning-journey-ui-shared/dist/components/XpBar.js

@@ -0,0 +1,47 @@
+'use client';
+
+import { Progress } from "../libs/ui-kit-web/dist/ui/progress.js";
+import { cn } from "../libs/ui-kit-web/dist/ui/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region ../learning-journey-ui-shared/dist/components/XpBar.js
+const sizeStyles = {
+	sm: "h-2",
+	md: "h-3",
+	lg: "h-4"
+};
+const labelSizeStyles = {
+	sm: "text-xs",
+	md: "text-sm",
+	lg: "text-base"
+};
+function XpBar({ current, max, level, showLabel = true, size = "md" }) {
+	const percentage = max > 0 ? Math.min(current / max * 100, 100) : 0;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "w-full space-y-1",
+		children: [showLabel && /* @__PURE__ */ jsxs("div", {
+			className: cn("flex items-center justify-between", labelSizeStyles[size]),
+			children: [/* @__PURE__ */ jsxs("span", {
+				className: "text-muted-foreground font-medium",
+				children: [level !== void 0 && /* @__PURE__ */ jsxs("span", {
+					className: "text-primary mr-1",
+					children: ["Lvl ", level]
+				}), "XP"]
+			}), /* @__PURE__ */ jsxs("span", {
+				className: "font-semibold",
+				children: [
+					current.toLocaleString(),
+					" / ",
+					max.toLocaleString()
+				]
+			})]
+		}), /* @__PURE__ */ jsx(Progress, {
+			value: percentage,
+			className: cn("bg-muted", sizeStyles[size])
+		})]
+	});
+}
+
+//#endregion
+export { XpBar };
+//# sourceMappingURL=XpBar.js.map

package/dist/examples/learning-journey-ui-shared/dist/components/XpBar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XpBar.js","names":[],"sources":["../../../../../../learning-journey-ui-shared/dist/components/XpBar.js"],"sourcesContent":["'use client';\n\nimport { Progress } from \"../libs/ui-kit-web/dist/ui/progress.js\";\nimport { cn } from \"../libs/ui-kit-web/dist/ui/utils.js\";\nimport { jsx, jsxs } from \"react/jsx-runtime\";\n\n//#region src/components/XpBar.tsx\nconst sizeStyles = {\n\tsm: \"h-2\",\n\tmd: \"h-3\",\n\tlg: \"h-4\"\n};\nconst labelSizeStyles = {\n\tsm: \"text-xs\",\n\tmd: \"text-sm\",\n\tlg: \"text-base\"\n};\nfunction XpBar({ current, max, level, showLabel = true, size = \"md\" }) {\n\tconst percentage = max > 0 ? Math.min(current / max * 100, 100) : 0;\n\treturn /* @__PURE__ */ jsxs(\"div\", {\n\t\tclassName: \"w-full space-y-1\",\n\t\tchildren: [showLabel && /* @__PURE__ */ jsxs(\"div\", {\n\t\t\tclassName: cn(\"flex items-center justify-between\", labelSizeStyles[size]),\n\t\t\tchildren: [/* @__PURE__ */ jsxs(\"span\", {\n\t\t\t\tclassName: \"text-muted-foreground font-medium\",\n\t\t\t\tchildren: [level !== void 0 && /* @__PURE__ */ jsxs(\"span\", {\n\t\t\t\t\tclassName: \"text-primary mr-1\",\n\t\t\t\t\tchildren: [\"Lvl \", level]\n\t\t\t\t}), \"XP\"]\n\t\t\t}), /* @__PURE__ */ jsxs(\"span\", {\n\t\t\t\tclassName: \"font-semibold\",\n\t\t\t\tchildren: [\n\t\t\t\t\tcurrent.toLocaleString(),\n\t\t\t\t\t\" / \",\n\t\t\t\t\tmax.toLocaleString()\n\t\t\t\t]\n\t\t\t})]\n\t\t}), /* @__PURE__ */ jsx(Progress, {\n\t\t\tvalue: percentage,\n\t\t\tclassName: cn(\"bg-muted\", sizeStyles[size])\n\t\t})]\n\t});\n}\n\n//#endregion\nexport { XpBar };\n//# sourceMappingURL=XpBar.js.map"],"mappings":";;;;;;;AAOA,MAAM,aAAa;CAClB,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ;AACD,MAAM,kBAAkB;CACvB,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ;AACD,SAAS,MAAM,EAAE,SAAS,KAAK,OAAO,YAAY,MAAM,OAAO,QAAQ;CACtE,MAAM,aAAa,MAAM,IAAI,KAAK,IAAI,UAAU,MAAM,KAAK,IAAI,GAAG;AAClE,QAAuB,qBAAK,OAAO;EAClC,WAAW;EACX,UAAU,CAAC,aAA6B,qBAAK,OAAO;GACnD,WAAW,GAAG,qCAAqC,gBAAgB,MAAM;GACzE,UAAU,CAAiB,qBAAK,QAAQ;IACvC,WAAW;IACX,UAAU,CAAC,UAAU,KAAK,KAAqB,qBAAK,QAAQ;KAC3D,WAAW;KACX,UAAU,CAAC,QAAQ,MAAM;KACzB,CAAC,EAAE,KAAK;IACT,CAAC,EAAkB,qBAAK,QAAQ;IAChC,WAAW;IACX,UAAU;KACT,QAAQ,gBAAgB;KACxB;KACA,IAAI,gBAAgB;KACpB;IACD,CAAC,CAAC;GACH,CAAC,EAAkB,oBAAI,UAAU;GACjC,OAAO;GACP,WAAW,GAAG,YAAY,WAAW,MAAM;GAC3C,CAAC,CAAC;EACH,CAAC"}

package/dist/examples/learning-journey-ui-shared/dist/components/index.js

@@ -0,0 +1,4 @@
+import { XpBar } from "./XpBar.js";
+import "./StreakCounter.js";
+import { BadgeDisplay } from "./BadgeDisplay.js";
+import { ViewTabs } from "./ViewTabs.js";

package/dist/examples/learning-journey-ui-shared/dist/docs/index.js

@@ -0,0 +1 @@
+import "./learning-journey-ui-shared.docblock.js";

package/dist/examples/learning-journey-ui-shared/dist/docs/learning-journey-ui-shared.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../libs/contracts/dist/docs/registry.js";
+import "../libs/contracts/dist/docs/index.js";
+
+//#region ../learning-journey-ui-shared/dist/docs/learning-journey-ui-shared.docblock.js
+registerDocBlocks([{
+	id: "docs.examples.learning-journey-ui-shared",
+	title: "Learning Journey UI — Shared",
+	summary: "Shared UI components and hooks for learning journey mini-apps.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/examples/learning-journey-ui-shared",
+	tags: [
+		"learning",
+		"ui",
+		"shared"
+	],
+	body: `## Includes\n- Hooks: useLearningProgress\n- Components: XpBar, StreakCounter, BadgeDisplay, ViewTabs\n\n## Notes\n- Keep components accessible (labels, focus, contrast).\n- Prefer design-system tokens and components.`
+}]);
+
+//#endregion
+//# sourceMappingURL=learning-journey-ui-shared.docblock.js.map

package/dist/examples/learning-journey-ui-shared/dist/docs/learning-journey-ui-shared.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-journey-ui-shared.docblock.js","names":[],"sources":["../../../../../../learning-journey-ui-shared/dist/docs/learning-journey-ui-shared.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../libs/contracts/dist/docs/registry.js\";\nimport \"../libs/contracts/dist/docs/index.js\";\n\n//#region src/docs/learning-journey-ui-shared.docblock.ts\nregisterDocBlocks([{\n\tid: \"docs.examples.learning-journey-ui-shared\",\n\ttitle: \"Learning Journey UI — Shared\",\n\tsummary: \"Shared UI components and hooks for learning journey mini-apps.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/examples/learning-journey-ui-shared\",\n\ttags: [\n\t\t\"learning\",\n\t\t\"ui\",\n\t\t\"shared\"\n\t],\n\tbody: `## Includes\\n- Hooks: useLearningProgress\\n- Components: XpBar, StreakCounter, BadgeDisplay, ViewTabs\\n\\n## Notes\\n- Keep components accessible (labels, focus, contrast).\\n- Prefer design-system tokens and components.`\n}]);\n\n//#endregion\n//# sourceMappingURL=learning-journey-ui-shared.docblock.js.map"],"mappings":";;;;AAIA,kBAAkB,CAAC;CAClB,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;CACD,MAAM;CACN,CAAC,CAAC"}

package/dist/examples/learning-journey-ui-shared/dist/hooks/index.js

@@ -0,0 +1 @@
+import { useLearningProgress } from "./useLearningProgress.js";

package/dist/examples/learning-journey-ui-shared/dist/hooks/useLearningProgress.js

@@ -0,0 +1,74 @@
+'use client';
+
+import { useCallback, useMemo, useState } from "react";
+
+//#region ../learning-journey-ui-shared/dist/hooks/useLearningProgress.js
+/** Default progress state for a new track */
+function createDefaultProgress(trackId) {
+	return {
+		trackId,
+		completedStepIds: [],
+		currentStepId: null,
+		xpEarned: 0,
+		streakDays: 0,
+		lastActivityDate: null,
+		badges: []
+	};
+}
+/** Hook for managing learning progress state */
+function useLearningProgress(track) {
+	const [progress, setProgress] = useState(() => createDefaultProgress(track.id));
+	const completeStep = useCallback((stepId) => {
+		const step = track.steps.find((s) => s.id === stepId);
+		if (!step || progress.completedStepIds.includes(stepId)) return;
+		setProgress((prev) => {
+			const newCompletedIds = [...prev.completedStepIds, stepId];
+			const xpReward = step.xpReward ?? 0;
+			const nextStep = track.steps.find((s) => !newCompletedIds.includes(s.id));
+			const isTrackComplete = newCompletedIds.length === track.steps.length;
+			const completionBonus = isTrackComplete ? track.completionRewards?.xpBonus ?? 0 : 0;
+			return {
+				...prev,
+				completedStepIds: newCompletedIds,
+				currentStepId: nextStep?.id ?? null,
+				xpEarned: prev.xpEarned + xpReward + completionBonus,
+				lastActivityDate: (/* @__PURE__ */ new Date()).toISOString(),
+				badges: isTrackComplete && track.completionRewards?.badgeKey ? [...prev.badges, track.completionRewards.badgeKey] : prev.badges
+			};
+		});
+	}, [track, progress.completedStepIds]);
+	const resetProgress = useCallback(() => {
+		setProgress(createDefaultProgress(track.id));
+	}, [track.id]);
+	const incrementStreak = useCallback(() => {
+		setProgress((prev) => ({
+			...prev,
+			streakDays: prev.streakDays + 1,
+			lastActivityDate: (/* @__PURE__ */ new Date()).toISOString()
+		}));
+	}, []);
+	return {
+		progress,
+		stats: useMemo(() => {
+			const totalSteps = track.steps.length;
+			const completedSteps = progress.completedStepIds.length;
+			const percentComplete = totalSteps > 0 ? Math.round(completedSteps / totalSteps * 100) : 0;
+			const totalXp = track.totalXp ?? track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0) + (track.completionRewards?.xpBonus ?? 0);
+			return {
+				totalSteps,
+				completedSteps,
+				remainingSteps: totalSteps - completedSteps,
+				percentComplete,
+				totalXp,
+				isComplete: completedSteps === totalSteps
+			};
+		}, [track, progress.completedStepIds]),
+		completeStep,
+		resetProgress,
+		incrementStreak
+	};
+}
+
+//#endregion
+export { useLearningProgress };
+//# sourceMappingURL=useLearningProgress.js.map

package/dist/examples/learning-journey-ui-shared/dist/hooks/useLearningProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLearningProgress.js","names":[],"sources":["../../../../../../learning-journey-ui-shared/dist/hooks/useLearningProgress.js"],"sourcesContent":["'use client';\n\nimport { useCallback, useMemo, useState } from \"react\";\n\n//#region src/hooks/useLearningProgress.ts\n/** Default progress state for a new track */\nfunction createDefaultProgress(trackId) {\n\treturn {\n\t\ttrackId,\n\t\tcompletedStepIds: [],\n\t\tcurrentStepId: null,\n\t\txpEarned: 0,\n\t\tstreakDays: 0,\n\t\tlastActivityDate: null,\n\t\tbadges: []\n\t};\n}\n/** Hook for managing learning progress state */\nfunction useLearningProgress(track) {\n\tconst [progress, setProgress] = useState(() => createDefaultProgress(track.id));\n\tconst completeStep = useCallback((stepId) => {\n\t\tconst step = track.steps.find((s) => s.id === stepId);\n\t\tif (!step || progress.completedStepIds.includes(stepId)) return;\n\t\tsetProgress((prev) => {\n\t\t\tconst newCompletedIds = [...prev.completedStepIds, stepId];\n\t\t\tconst xpReward = step.xpReward ?? 0;\n\t\t\tconst nextStep = track.steps.find((s) => !newCompletedIds.includes(s.id));\n\t\t\tconst isTrackComplete = newCompletedIds.length === track.steps.length;\n\t\t\tconst completionBonus = isTrackComplete ? track.completionRewards?.xpBonus ?? 0 : 0;\n\t\t\treturn {\n\t\t\t\t...prev,\n\t\t\t\tcompletedStepIds: newCompletedIds,\n\t\t\t\tcurrentStepId: nextStep?.id ?? null,\n\t\t\t\txpEarned: prev.xpEarned + xpReward + completionBonus,\n\t\t\t\tlastActivityDate: (/* @__PURE__ */ new Date()).toISOString(),\n\t\t\t\tbadges: isTrackComplete && track.completionRewards?.badgeKey ? [...prev.badges, track.completionRewards.badgeKey] : prev.badges\n\t\t\t};\n\t\t});\n\t}, [track, progress.completedStepIds]);\n\tconst resetProgress = useCallback(() => {\n\t\tsetProgress(createDefaultProgress(track.id));\n\t}, [track.id]);\n\tconst incrementStreak = useCallback(() => {\n\t\tsetProgress((prev) => ({\n\t\t\t...prev,\n\t\t\tstreakDays: prev.streakDays + 1,\n\t\t\tlastActivityDate: (/* @__PURE__ */ new Date()).toISOString()\n\t\t}));\n\t}, []);\n\treturn {\n\t\tprogress,\n\t\tstats: useMemo(() => {\n\t\t\tconst totalSteps = track.steps.length;\n\t\t\tconst completedSteps = progress.completedStepIds.length;\n\t\t\tconst percentComplete = totalSteps > 0 ? Math.round(completedSteps / totalSteps * 100) : 0;\n\t\t\tconst totalXp = track.totalXp ?? track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0) + (track.completionRewards?.xpBonus ?? 0);\n\t\t\treturn {\n\t\t\t\ttotalSteps,\n\t\t\t\tcompletedSteps,\n\t\t\t\tremainingSteps: totalSteps - completedSteps,\n\t\t\t\tpercentComplete,\n\t\t\t\ttotalXp,\n\t\t\t\tisComplete: completedSteps === totalSteps\n\t\t\t};\n\t\t}, [track, progress.completedStepIds]),\n\t\tcompleteStep,\n\t\tresetProgress,\n\t\tincrementStreak\n\t};\n}\n\n//#endregion\nexport { useLearningProgress };\n//# sourceMappingURL=useLearningProgress.js.map"],"mappings":";;;;;;AAMA,SAAS,sBAAsB,SAAS;AACvC,QAAO;EACN;EACA,kBAAkB,EAAE;EACpB,eAAe;EACf,UAAU;EACV,YAAY;EACZ,kBAAkB;EAClB,QAAQ,EAAE;EACV;;;AAGF,SAAS,oBAAoB,OAAO;CACnC,MAAM,CAAC,UAAU,eAAe,eAAe,sBAAsB,MAAM,GAAG,CAAC;CAC/E,MAAM,eAAe,aAAa,WAAW;EAC5C,MAAM,OAAO,MAAM,MAAM,MAAM,MAAM,EAAE,OAAO,OAAO;AACrD,MAAI,CAAC,QAAQ,SAAS,iBAAiB,SAAS,OAAO,CAAE;AACzD,eAAa,SAAS;GACrB,MAAM,kBAAkB,CAAC,GAAG,KAAK,kBAAkB,OAAO;GAC1D,MAAM,WAAW,KAAK,YAAY;GAClC,MAAM,WAAW,MAAM,MAAM,MAAM,MAAM,CAAC,gBAAgB,SAAS,EAAE,GAAG,CAAC;GACzE,MAAM,kBAAkB,gBAAgB,WAAW,MAAM,MAAM;GAC/D,MAAM,kBAAkB,kBAAkB,MAAM,mBAAmB,WAAW,IAAI;AAClF,UAAO;IACN,GAAG;IACH,kBAAkB;IAClB,eAAe,UAAU,MAAM;IAC/B,UAAU,KAAK,WAAW,WAAW;IACrC,mCAAmC,IAAI,MAAM,EAAE,aAAa;IAC5D,QAAQ,mBAAmB,MAAM,mBAAmB,WAAW,CAAC,GAAG,KAAK,QAAQ,MAAM,kBAAkB,SAAS,GAAG,KAAK;IACzH;IACA;IACA,CAAC,OAAO,SAAS,iBAAiB,CAAC;CACtC,MAAM,gBAAgB,kBAAkB;AACvC,cAAY,sBAAsB,MAAM,GAAG,CAAC;IAC1C,CAAC,MAAM,GAAG,CAAC;CACd,MAAM,kBAAkB,kBAAkB;AACzC,eAAa,UAAU;GACtB,GAAG;GACH,YAAY,KAAK,aAAa;GAC9B,mCAAmC,IAAI,MAAM,EAAE,aAAa;GAC5D,EAAE;IACD,EAAE,CAAC;AACN,QAAO;EACN;EACA,OAAO,cAAc;GACpB,MAAM,aAAa,MAAM,MAAM;GAC/B,MAAM,iBAAiB,SAAS,iBAAiB;GACjD,MAAM,kBAAkB,aAAa,IAAI,KAAK,MAAM,iBAAiB,aAAa,IAAI,GAAG;GACzF,MAAM,UAAU,MAAM,WAAW,MAAM,MAAM,QAAQ,KAAK,MAAM,OAAO,EAAE,YAAY,IAAI,EAAE,IAAI,MAAM,mBAAmB,WAAW;AACnI,UAAO;IACN;IACA;IACA,gBAAgB,aAAa;IAC7B;IACA;IACA,YAAY,mBAAmB;IAC/B;KACC,CAAC,OAAO,SAAS,iBAAiB,CAAC;EACtC;EACA;EACA;EACA"}

package/dist/examples/learning-journey-ui-shared/dist/index.js

@@ -0,0 +1,8 @@
+import { useLearningProgress } from "./hooks/useLearningProgress.js";
+import "./hooks/index.js";
+import { XpBar } from "./components/XpBar.js";
+import "./components/StreakCounter.js";
+import { BadgeDisplay } from "./components/BadgeDisplay.js";
+import { ViewTabs } from "./components/ViewTabs.js";
+import "./components/index.js";
+import "./docs/index.js";

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js

@@ -0,0 +1,16 @@
+import { registerDocBlocks } from "./registry.js";
+
+//#region ../learning-journey-ui-shared/dist/libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js
+registerDocBlocks([{
+	id: "docs.accessibility_wcag_compliance_specs",
+	title: "Accessibility & WCAG Compliance — **specs.md**",
+	summary: "> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/accessibility_wcag_compliance_specs",
+	tags: ["accessibility_wcag_compliance_specs"],
+	body: "# Accessibility & WCAG Compliance — **specs.md**\n\n> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\xA0301\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\xA0Native)**.\n\n---\n\n## 0) Scope & Principles\n\n- **Standards:** WCAG\xA02.2\xA0AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN\xA0301\xA0549 compliance by conformance to WCAG.\n- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).\n- **Rule of ARIA:** “No ARIA is better than bad ARIA.” Prefer native elements.\n- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.\n- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in `packages/lssm/libs/ui-kit-web`. Prefer those components over per‑app duplicates (`packages/*/apps/*/src/components/ui`). When missing, add to `ui-kit-web` first, then adopt app‑side.\n\n---\n\n## 1) Design Requirements (Design System & Tokens)\n\n**1.1 Color & Contrast**\n\n- Body text, icons essential to meaning: **≥\xA04.5:1**; large text (≥\xA018.66px regular / 14px bold): **≥\xA03:1**.\n- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥\xA03:1** against adjacent colors; text within components follows text ratios.\n- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.\n\n**1.2 Focus Indicators (WCAG\xA02.4.11/12)**\n\n- Every interactive element has a **visible focus** with clear offset; indicator contrast **≥\xA03:1** vs adjacent colors and indicator **area ≥\xA02\xA0CSS\xA0px** thick.\n- Focus **must not be obscured** by sticky headers/footers or scroll containers.\n\n**1.3 Motion & Preferences**\n\n- Respect `prefers-reduced-motion`: suppress large parallax, auto‑animations; provide instant alternatives.\n- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.\n\n**1.4 Target Size (2.5.8)**\n\n- Hit areas **≥\xA024×24\xA0CSS\xA0px** (web) and **≥\xA044×44\xA0dp** (mobile) unless exempt.\n\n**1.5 Typography & Layout**\n\n- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320\xA0CSS\xA0px** width.\n- Maintain clear heading hierarchy (h1…h6), one **h1** per view.\n\n- Repository baseline (Web): default body text uses Tailwind `text-lg` (≈18px). As of 2025‑09‑20, the repository bumped all Tailwind typography scale usages by +1 step (e.g., `text-sm`→`text-base`, `text-base`→`text-lg`, …, `text-8xl`→`text-9xl`). For long‑form content, default to `prose-lg`.\n- Do not use `text-xs` for body copy. Reserve `text-sm` only for non‑essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.\n- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or `leading-relaxed`/`leading-7` for body text where dense blocks appear.\n\n**1.6 Iconography & Imagery**\n\n- Decorative images: `alt=\"\"` or `aria-hidden=\"true\"`.\n- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.\n\n---\n\n## 2) Content Requirements (UX Writing)\n\n- Links say **what happens** (avoid “click here”).\n- Buttons start with verbs; avoid ambiguous labels.\n- Form labels are **visible**; placeholders are **not labels**.\n- Error messages: human + programmatic association; avoid color‑only.\n- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).\n- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).\n\n---\n\n## 3) Engineering Requirements (Web — Next.js/React)\n\n> Use and extend `packages/lssm/libs/ui-kit-web` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to `ui-kit-web` first.\n\n**3.1 Semantics & Landmarks**\n\n- Use native elements: `<button>`, `<a href>`, `<label for>`, `<fieldset>`, `<legend>`, `<table>`, etc.\n- Landmarks per page: `header`, `nav`, `main`, `aside`, `footer`. Provide a **Skip to main content** link.\n- Provide a **Route Announcer** (`aria-live=\"polite\"`) and move focus to page **h1** after navigation.\n\n**3.2 Keyboard**\n\n- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.\n- Common bindings:\n  - Space/Enter → activate button; Enter on link;\n  - Esc closes dialogs/menus;\n  - Arrow keys for lists/menus/tablists with **roving tabindex**.\n\n**3.3 Focus Management**\n\n- On route change (Next.js), move focus to the page `<h1>` or container and announce via a live region.\n- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.\n- Don’t steal focus except after explicit user action.\n\n**3.4 Forms**\n\n- Each input has a `<label>` or `aria-label`. Group related inputs with `<fieldset><legend>`.\n- Associate errors via `aria-describedby` or inline IDs; announce with `role=\"alert\"` (assertive only for critical).\n- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.\n\n**3.5 ARIA Usage**\n\n- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.\n- Ensure **name/role/value** are programmatically determinable.\n\n**3.6 Media**\n\n- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.\n- No auto‑playing audio. Auto‑playing video must be muted and pausable; provide controls.\n\n**3.7 Tables & Data**\n\n- Use `<th scope>` for headers; captions via `<caption>`; announce sorting via `aria-sort`.\n- Provide CSV/JSON export where charts are primary.\n\n**3.8 Performance & Robustness**\n\n- Avoid content shifts that move focus; reserve space or use skeletons.\n- Maintain accessible names through hydration/SSR; avoid `dangerouslySetInnerHTML` where possible.\n\n**3.9 Next.js specifics**\n\n- Use `next/link` for navigation; ensure links are **links**, not buttons.\n- `next/image` must include **alt** (empty if decorative).\n- Announce route changes with a **global live region** and shift focus to the new view.\n\n**3.10 Accessibility library integration**\n\n- Import `@lssm/lib.accessibility` at app root. It auto-imports its `styles.css` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:\n\n```tsx\n// app/layout.tsx\nimport '@lssm/lib.accessibility'; // includes tokens and provider exports\n// or if needed: import '@lssm/lib.accessibility/src/styles.css';\n```\n\n- Wrap the app with `AccessibilityProvider` and include an element with `id=\"main\"` for the skip link target.\n\n---\n\n## 3b) lssm/ui-kit-web — Component Patterns & Defaults\n\n> Source: `packages/lssm/libs/ui-kit-web/ui/*`\n\n- **Button/Input/Textarea**: Built‑in `focus-visible` rings; ensure visible labels via `FormLabel` or `aria-label`.\n- **Form** (`form.tsx`): `FormControl` wires `aria-invalid` and `aria-describedby` to `FormMessage` and `FormDescription`. Prefer `FormMessage` for inline errors. Add `role=\"alert\"` only for critical.\n- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus‑trap and return‑focus. Provide `DialogTitle` + `DialogDescription` for name/description.\n- **Select/Combobox**: Prefer `SelectTrigger` with visible label; for icon‑only triggers, supply `aria-label`. Document examples in each app.\n- **Tabs**: Use `TabsList`, `TabsTrigger`, `TabsContent`; names are programmatically determinable.\n- **Toast/Toaster**: Prefer non‑blocking announcements; map critical to assertive region; include action buttons with clear labels.\n- **Table**: Use `TableCaption`; ensure `TableHead` cells use proper `scope`. Provide `aria-sort` on sortable headers.\n- **Utilities to add (repo action)**:\n  - `SkipLink` component and pattern in layouts.\n  - `RouteAnnouncer` (`aria-live=\"polite\"`) and **FocusOnRouteChange** helper.\n  - `VisuallyHidden` wrapper (Radix visually-hidden or minimal utility).\n  - `useReducedMotion` helper; honor in animated components.\n  - Touch‑size variants (≥44×44) for interactive atoms.\n\n---\n\n## 4) Engineering Requirements (Mobile — Expo/React\xA0Native)\n\n- Set `accessibilityLabel`, `accessibilityHint`, and `accessibilityRole` on touchables.\n- Ensure **hit slop** / min size **≥\xA044×44\xA0dp**.\n- Support Dynamic Type / font scaling; no clipped text at **200%**.\n- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.\n- Group related items with `accessibilityElements` ordering; hide decoration with `accessible={false}` or `importantForAccessibility=\"no-hide-descendants\"` when appropriate.\n- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.\n\n---\n\n## 5) Component Patterns (Acceptance Rules)\n\n**Buttons & Links**\n\n- Use `<button>` for actions, `<a href>` for navigation. Provide disabled states that are perceivable beyond color.\n\n**Navigation**\n\n- Provide **Skip link**. One primary nav landmark. Indicate current page (`aria-current=\"page\"`).\n\n**Menus/Combobox/Autocomplete**\n\n- Follow ARIA patterns: focus moves into list; `aria-expanded`, `aria-controls`, `aria-activedescendant` when applicable; Esc closes; typing filters.\n\n**Modals/Dialogs**\n\n- `role=\"dialog\"` or `alertdialog` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.\n\n**Tabs**\n\n- `role=\"tablist\"`; tabs are in the tab order; arrow keys switch focus; content is `role=\"tabpanel\"` with `aria-labelledby`.\n\n**Toasts/Notifications**\n\n- Non-critical: `aria-live=\"polite\"`; critical: `role=\"alert\"` sparingly.\n\n**Infinite Scroll / “Load More”**\n\n- Provide **Load more** control; announce new content to SR; preserve keyboard position.\n\n**Drag & Drop (2.5.7)**\n\n- Provide **non‑drag** alternative (e.g., move up/down buttons).\n\n**Charts & Maps**\n\n- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.\n\n---\n\n## 6) Testing & CI (Blocking Gates)\n\n**Static & Unit**\n\n- `eslint-plugin-jsx-a11y` — error on violations.\n- `jest-axe` — unit tests for components.\n\n**Automated Integration**\n\n- `axe-core` via Playwright or Cypress on critical flows.\n- `pa11y-ci` on key routes; threshold: **0 Critical / 0 Serious** to merge.\n- Lighthouse CI a11y score **≥\xA095** on target pages.\n\n**Manual QA (per release)**\n\n- **Keyboard patrol:** navigate primary flows without mouse.\n- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.\n- **Zoom & Reflow:** 200–400% & 320\xA0px width.\n- **Color/Contrast check:** tokens in both themes.\n\n**Reporting**\n\n- A11y issues labeled: `a11y-blocker`, `a11y-bug`, `a11y-enhancement` with WCAG ref.\n\n---\n\n## 7) Repository‑Specific Adoption Plan\n\n- Centralize UI usage on `packages/lssm/libs/ui-kit-web` and de‑duplicate per‑app `components/ui` where feasible.\n- Introduce `SkipLink`, `RouteAnnouncer`, `FocusOnRouteChange`, and `VisuallyHidden` in `ui-kit-web`. Adopt in app layouts (`app/layout.tsx`) first.\n- Add `useReducedMotion` and wire into animated components (e.g., `drawer`, `tooltip`, `carousel`).\n- Add touch‑size variants to `Button`, `IconButton`, `TabsTrigger`, toggles.\n- Document Select label patterns and error association in Forms.\n\n---\n\n## 8) Code Snippets\n\n**Skip Link**\n\n```html\n<a\n  class=\"sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2\"\n  href=\"#main\"\n  >Skip to main content</a\n>\n<main id=\"main\">…</main>\n```\n\n**Dialog (Radix + shadcn/ui) — essentials**\n\n```tsx\n// Ensure label, description, focus trap, and return focus on close remain intact\n<Dialog>\n  <DialogTrigger asChild>\n    <button aria-haspopup=\"dialog\">Open settings</button>\n  </DialogTrigger>\n  <DialogContent aria-describedby=\"settings-desc\">\n    <DialogTitle>Settings</DialogTitle>\n    <p id=\"settings-desc\">Update your preferences.</p>\n    <DialogClose asChild>\n      <button>Close</button>\n    </DialogClose>\n  </DialogContent>\n</Dialog>\n```\n\n**Form error association**\n\n```tsx\n<label htmlFor=\"email\">Email</label>\n<input id=\"email\" name=\"email\" type=\"email\" aria-describedby=\"email-err\" />\n<p id=\"email-err\" role=\"alert\">Enter a valid email.</p>\n```\n\n**Route change announcement (Next.js)**\n\n```tsx\n// Add once at app root\n<div\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n  id=\"route-announcer\"\n  className=\"sr-only\"\n/>\n```\n\n---\n\n## 9) Exceptions & Waivers\n\n- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**\n\n---\n\n## 10) Ownership\n\n- **Design:** maintains token contrast, component specs.\n- **Engineering:** enforces CI gates, implements patterns.\n- **QA:** runs manual checks per release.\n- **PM:** blocks release if AA not met on user‑visible flows.\n\n---\n\n## 11) References (internalize; no external dependency at runtime)\n\n- WCAG\xA02.2 (AA), EN\xA0301\xA0549. ARIA Authoring Practices. Platform HIG (Apple, Material).\n- `packages/lssm/libs/ui-kit-web` as the canonical UI source for web.\n\n> **Bottom line:** Shipping means **accessible by default**. We don’t trade a11y for speed; we bake it into speed.\n\n---\n\n## 12) Adoption Status (2025-09-23)\n\n- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.\n- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.\n- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to `Section`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role=\"alert\" where critical.\n\n> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.\n\n---\n\n## 13) CI Hardening & Visual QA\n\n- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.\n- Unit: Run jest-axe for ui-kit-web and app-level components.\n- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).\n- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).\n- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.\n- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.\n\n### Recent additions (2025-09-26)\n\n- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with `aria-controls`, `aria-activedescendant`, `Escape`/`Tab` handling, and labelled listbox.\n- Cypress a11y tests added for furniture and incidents modules on `/modules` and operators flows; checks run axe with critical/serious impacts.\n\n## 14) Accessibility Telemetry (PostHog)\n\n- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.\n- Properties: app, route, previous_value, new_value, timestamp.\n- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.\n- Privacy: No PII; aggregate only.\n"
+}]);
+
+//#endregion
+//# sourceMappingURL=accessibility_wcag_compliance_specs.docblock.js.map

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility_wcag_compliance_specs.docblock.js","names":[],"sources":["../../../../../../../../../learning-journey-ui-shared/dist/libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"./registry.js\";\n\n//#region ../../libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js\nconst accessibility_wcag_compliance_specs_DocBlocks = [{\n\tid: \"docs.accessibility_wcag_compliance_specs\",\n\ttitle: \"Accessibility & WCAG Compliance — **specs.md**\",\n\tsummary: \"> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\\xA0301\\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\\xA0Native)**.\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/accessibility_wcag_compliance_specs\",\n\ttags: [\"accessibility_wcag_compliance_specs\"],\n\tbody: \"# Accessibility & WCAG Compliance — **specs.md**\\n\\n> **Goal:** Ship interfaces that are usable by everyone, by default. This spec sets non‑negotiable rules, checklists, and CI gates to meet **WCAG\\xA02.2 AA** (aim for AAA where low‑cost), align with **EN\\xA0301\\xA0549** (EU), and keep parity on **web (Next.js)** and **mobile (Expo/React\\xA0Native)**.\\n\\n---\\n\\n## 0) Scope & Principles\\n\\n- **Standards:** WCAG\\xA02.2\\xA0AA (incl. new 2.2 SCs: Focus Not Obscured, Focus Appearance, Target Size, Dragging Movements, Accessible Authentication, Redundant Entry). EN\\xA0301\\xA0549 compliance by conformance to WCAG.\\n- **Principles:** Perceivable, Operable, Understandable, Robust (POUR).\\n- **Rule of ARIA:** “No ARIA is better than bad ARIA.” Prefer native elements.\\n- **Definition of Done (DoD):** No Critical/Major a11y issues in CI; keyboard complete; SR (screen reader) smoke test passed; contrasts pass; acceptance criteria below satisfied.\\n- **Repo Alignment:** Web apps use **Radix Primitives + shadcn** wrappers centralized in `packages/lssm/libs/ui-kit-web`. Prefer those components over per‑app duplicates (`packages/*/apps/*/src/components/ui`). When missing, add to `ui-kit-web` first, then adopt app‑side.\\n\\n---\\n\\n## 1) Design Requirements (Design System & Tokens)\\n\\n**1.1 Color & Contrast**\\n\\n- Body text, icons essential to meaning: **≥\\xA04.5:1**; large text (≥\\xA018.66px regular / 14px bold): **≥\\xA03:1**.\\n- Interactive states (default/hover/active/disabled/focus) must maintain contrast **≥\\xA03:1** against adjacent colors; text within components follows text ratios.\\n- Provide light & dark themes with tokens that guarantee minimums. **Never rely solely on color** to convey meaning; pair with text, shape, or icon.\\n\\n**1.2 Focus Indicators (WCAG\\xA02.4.11/12)**\\n\\n- Every interactive element has a **visible focus** with clear offset; indicator contrast **≥\\xA03:1** vs adjacent colors and indicator **area ≥\\xA02\\xA0CSS\\xA0px** thick.\\n- Focus **must not be obscured** by sticky headers/footers or scroll containers.\\n\\n**1.3 Motion & Preferences**\\n\\n- Respect `prefers-reduced-motion`: suppress large parallax, auto‑animations; provide instant alternatives.\\n- Avoid motion that could trigger vestibular issues; under PRM, use fade/scale under **150ms**.\\n\\n**1.4 Target Size (2.5.8)**\\n\\n- Hit areas **≥\\xA024×24\\xA0CSS\\xA0px** (web) and **≥\\xA044×44\\xA0dp** (mobile) unless exempt.\\n\\n**1.5 Typography & Layout**\\n\\n- Support zoom to **400%** without loss of content/functionality; responsive reflow at **320\\xA0CSS\\xA0px** width.\\n- Maintain clear heading hierarchy (h1…h6), one **h1** per view.\\n\\n- Repository baseline (Web): default body text uses Tailwind `text-lg` (≈18px). As of 2025‑09‑20, the repository bumped all Tailwind typography scale usages by +1 step (e.g., `text-sm`→`text-base`, `text-base`→`text-lg`, …, `text-8xl`→`text-9xl`). For long‑form content, default to `prose-lg`.\\n- Do not use `text-xs` for body copy. Reserve `text-sm` only for non‑essential meta (timestamps, fine print) while ensuring contrast and touch targets remain compliant.\\n- When increasing font size, ensure line height supports readability. Prefer Tailwind defaults or `leading-relaxed`/`leading-7` for body text where dense blocks appear.\\n\\n**1.6 Iconography & Imagery**\\n\\n- Decorative images: `alt=\\\"\\\"` or `aria-hidden=\\\"true\\\"`.\\n- Informative images: concise, specific **alt**; complex charts require a **data table or long description**.\\n\\n---\\n\\n## 2) Content Requirements (UX Writing)\\n\\n- Links say **what happens** (avoid “click here”).\\n- Buttons start with verbs; avoid ambiguous labels.\\n- Form labels are **visible**; placeholders are **not labels**.\\n- Error messages: human + programmatic association; avoid color‑only.\\n- Authentication: allow **copy/paste**, password managers, and avoid cognitive tests alone (**3.3.7/3.3.8/3.3.9**).\\n- Avoid CAPTCHAs that block users; if unavoidable, provide **multiple alternatives** (logic-free).\\n\\n---\\n\\n## 3) Engineering Requirements (Web — Next.js/React)\\n\\n> Use and extend `packages/lssm/libs/ui-kit-web` as the default UI surface. It wraps **Radix** primitives with sensible a11y defaults (focus rings, roles, keyboard, ARIA binding). When a gap exists, add it to `ui-kit-web` first.\\n\\n**3.1 Semantics & Landmarks**\\n\\n- Use native elements: `<button>`, `<a href>`, `<label for>`, `<fieldset>`, `<legend>`, `<table>`, etc.\\n- Landmarks per page: `header`, `nav`, `main`, `aside`, `footer`. Provide a **Skip to main content** link.\\n- Provide a **Route Announcer** (`aria-live=\\\"polite\\\"`) and move focus to page **h1** after navigation.\\n\\n**3.2 Keyboard**\\n\\n- All functionality available with keyboard alone. Tab order follows DOM/visual order; **no keyboard traps**.\\n- Common bindings:\\n  - Space/Enter → activate button; Enter on link;\\n  - Esc closes dialogs/menus;\\n  - Arrow keys for lists/menus/tablists with **roving tabindex**.\\n\\n**3.3 Focus Management**\\n\\n- On route change (Next.js), move focus to the page `<h1>` or container and announce via a live region.\\n- Dialogs/menus: **trap focus** inside; return focus to invoking control on close.\\n- Don’t steal focus except after explicit user action.\\n\\n**3.4 Forms**\\n\\n- Each input has a `<label>` or `aria-label`. Group related inputs with `<fieldset><legend>`.\\n- Associate errors via `aria-describedby` or inline IDs; announce with `role=\\\"alert\\\"` (assertive only for critical).\\n- Provide **autocomplete** tokens for known fields; show **inline validation** and do not block on **onBlur** alone.\\n\\n**3.5 ARIA Usage**\\n\\n- Only when needed; match patterns (dialog, menu, combobox, tablist, listbox) per ARIA Authoring Practices.\\n- Ensure **name/role/value** are programmatically determinable.\\n\\n**3.6 Media**\\n\\n- Videos: **captions**; provide **transcripts** for audio; audio descriptions for essential visual info.\\n- No auto‑playing audio. Auto‑playing video must be muted and pausable; provide controls.\\n\\n**3.7 Tables & Data**\\n\\n- Use `<th scope>` for headers; captions via `<caption>`; announce sorting via `aria-sort`.\\n- Provide CSV/JSON export where charts are primary.\\n\\n**3.8 Performance & Robustness**\\n\\n- Avoid content shifts that move focus; reserve space or use skeletons.\\n- Maintain accessible names through hydration/SSR; avoid `dangerouslySetInnerHTML` where possible.\\n\\n**3.9 Next.js specifics**\\n\\n- Use `next/link` for navigation; ensure links are **links**, not buttons.\\n- `next/image` must include **alt** (empty if decorative).\\n- Announce route changes with a **global live region** and shift focus to the new view.\\n\\n**3.10 Accessibility library integration**\\n\\n- Import `@lssm/lib.accessibility` at app root. It auto-imports its `styles.css` via the package entry; ensure bundlers keep CSS side effects. If your app tree-shakes CSS, explicitly import the stylesheet once in your root layout:\\n\\n```tsx\\n// app/layout.tsx\\nimport '@lssm/lib.accessibility'; // includes tokens and provider exports\\n// or if needed: import '@lssm/lib.accessibility/src/styles.css';\\n```\\n\\n- Wrap the app with `AccessibilityProvider` and include an element with `id=\\\"main\\\"` for the skip link target.\\n\\n---\\n\\n## 3b) lssm/ui-kit-web — Component Patterns & Defaults\\n\\n> Source: `packages/lssm/libs/ui-kit-web/ui/*`\\n\\n- **Button/Input/Textarea**: Built‑in `focus-visible` rings; ensure visible labels via `FormLabel` or `aria-label`.\\n- **Form** (`form.tsx`): `FormControl` wires `aria-invalid` and `aria-describedby` to `FormMessage` and `FormDescription`. Prefer `FormMessage` for inline errors. Add `role=\\\"alert\\\"` only for critical.\\n- **Dialog/Sheet/Dropdown**: Use Radix wrappers for focus‑trap and return‑focus. Provide `DialogTitle` + `DialogDescription` for name/description.\\n- **Select/Combobox**: Prefer `SelectTrigger` with visible label; for icon‑only triggers, supply `aria-label`. Document examples in each app.\\n- **Tabs**: Use `TabsList`, `TabsTrigger`, `TabsContent`; names are programmatically determinable.\\n- **Toast/Toaster**: Prefer non‑blocking announcements; map critical to assertive region; include action buttons with clear labels.\\n- **Table**: Use `TableCaption`; ensure `TableHead` cells use proper `scope`. Provide `aria-sort` on sortable headers.\\n- **Utilities to add (repo action)**:\\n  - `SkipLink` component and pattern in layouts.\\n  - `RouteAnnouncer` (`aria-live=\\\"polite\\\"`) and **FocusOnRouteChange** helper.\\n  - `VisuallyHidden` wrapper (Radix visually-hidden or minimal utility).\\n  - `useReducedMotion` helper; honor in animated components.\\n  - Touch‑size variants (≥44×44) for interactive atoms.\\n\\n---\\n\\n## 4) Engineering Requirements (Mobile — Expo/React\\xA0Native)\\n\\n- Set `accessibilityLabel`, `accessibilityHint`, and `accessibilityRole` on touchables.\\n- Ensure **hit slop** / min size **≥\\xA044×44\\xA0dp**.\\n- Support Dynamic Type / font scaling; no clipped text at **200%**.\\n- Respect **Invert Colors** and **Reduce Motion**; avoid flashing.\\n- Group related items with `accessibilityElements` ordering; hide decoration with `accessible={false}` or `importantForAccessibility=\\\"no-hide-descendants\\\"` when appropriate.\\n- Test with **VoiceOver (iOS)** and **TalkBack (Android)**.\\n\\n---\\n\\n## 5) Component Patterns (Acceptance Rules)\\n\\n**Buttons & Links**\\n\\n- Use `<button>` for actions, `<a href>` for navigation. Provide disabled states that are perceivable beyond color.\\n\\n**Navigation**\\n\\n- Provide **Skip link**. One primary nav landmark. Indicate current page (`aria-current=\\\"page\\\"`).\\n\\n**Menus/Combobox/Autocomplete**\\n\\n- Follow ARIA patterns: focus moves into list; `aria-expanded`, `aria-controls`, `aria-activedescendant` when applicable; Esc closes; typing filters.\\n\\n**Modals/Dialogs**\\n\\n- `role=\\\"dialog\\\"` or `alertdialog` with **label**; focus trapped; background inert; Esc closes; return focus to trigger.\\n\\n**Tabs**\\n\\n- `role=\\\"tablist\\\"`; tabs are in the tab order; arrow keys switch focus; content is `role=\\\"tabpanel\\\"` with `aria-labelledby`.\\n\\n**Toasts/Notifications**\\n\\n- Non-critical: `aria-live=\\\"polite\\\"`; critical: `role=\\\"alert\\\"` sparingly.\\n\\n**Infinite Scroll / “Load More”**\\n\\n- Provide **Load more** control; announce new content to SR; preserve keyboard position.\\n\\n**Drag & Drop (2.5.7)**\\n\\n- Provide **non‑drag** alternative (e.g., move up/down buttons).\\n\\n**Charts & Maps**\\n\\n- Provide **table alternative** or textual summary; keyboard access to datapoints where interactive.\\n\\n---\\n\\n## 6) Testing & CI (Blocking Gates)\\n\\n**Static & Unit**\\n\\n- `eslint-plugin-jsx-a11y` — error on violations.\\n- `jest-axe` — unit tests for components.\\n\\n**Automated Integration**\\n\\n- `axe-core` via Playwright or Cypress on critical flows.\\n- `pa11y-ci` on key routes; threshold: **0 Critical / 0 Serious** to merge.\\n- Lighthouse CI a11y score **≥\\xA095** on target pages.\\n\\n**Manual QA (per release)**\\n\\n- **Keyboard patrol:** navigate primary flows without mouse.\\n- **Screen reader smoke:** NVDA (Windows) or VoiceOver (macOS/iOS) across login, navigation, forms, dialogs.\\n- **Zoom & Reflow:** 200–400% & 320\\xA0px width.\\n- **Color/Contrast check:** tokens in both themes.\\n\\n**Reporting**\\n\\n- A11y issues labeled: `a11y-blocker`, `a11y-bug`, `a11y-enhancement` with WCAG ref.\\n\\n---\\n\\n## 7) Repository‑Specific Adoption Plan\\n\\n- Centralize UI usage on `packages/lssm/libs/ui-kit-web` and de‑duplicate per‑app `components/ui` where feasible.\\n- Introduce `SkipLink`, `RouteAnnouncer`, `FocusOnRouteChange`, and `VisuallyHidden` in `ui-kit-web`. Adopt in app layouts (`app/layout.tsx`) first.\\n- Add `useReducedMotion` and wire into animated components (e.g., `drawer`, `tooltip`, `carousel`).\\n- Add touch‑size variants to `Button`, `IconButton`, `TabsTrigger`, toggles.\\n- Document Select label patterns and error association in Forms.\\n\\n---\\n\\n## 8) Code Snippets\\n\\n**Skip Link**\\n\\n```html\\n<a\\n  class=\\\"sr-only focus:not-sr-only focus-visible:outline focus-visible:ring-4 focus-visible:ring-offset-2\\\"\\n  href=\\\"#main\\\"\\n  >Skip to main content</a\\n>\\n<main id=\\\"main\\\">…</main>\\n```\\n\\n**Dialog (Radix + shadcn/ui) — essentials**\\n\\n```tsx\\n// Ensure label, description, focus trap, and return focus on close remain intact\\n<Dialog>\\n  <DialogTrigger asChild>\\n    <button aria-haspopup=\\\"dialog\\\">Open settings</button>\\n  </DialogTrigger>\\n  <DialogContent aria-describedby=\\\"settings-desc\\\">\\n    <DialogTitle>Settings</DialogTitle>\\n    <p id=\\\"settings-desc\\\">Update your preferences.</p>\\n    <DialogClose asChild>\\n      <button>Close</button>\\n    </DialogClose>\\n  </DialogContent>\\n</Dialog>\\n```\\n\\n**Form error association**\\n\\n```tsx\\n<label htmlFor=\\\"email\\\">Email</label>\\n<input id=\\\"email\\\" name=\\\"email\\\" type=\\\"email\\\" aria-describedby=\\\"email-err\\\" />\\n<p id=\\\"email-err\\\" role=\\\"alert\\\">Enter a valid email.</p>\\n```\\n\\n**Route change announcement (Next.js)**\\n\\n```tsx\\n// Add once at app root\\n<div\\n  aria-live=\\\"polite\\\"\\n  aria-atomic=\\\"true\\\"\\n  id=\\\"route-announcer\\\"\\n  className=\\\"sr-only\\\"\\n/>\\n```\\n\\n---\\n\\n## 9) Exceptions & Waivers\\n\\n- If a criterion cannot be met, file an issue with: context, attempted alternatives, WCAG reference, impact assessment, and a remediation date. **Temporary waivers only.**\\n\\n---\\n\\n## 10) Ownership\\n\\n- **Design:** maintains token contrast, component specs.\\n- **Engineering:** enforces CI gates, implements patterns.\\n- **QA:** runs manual checks per release.\\n- **PM:** blocks release if AA not met on user‑visible flows.\\n\\n---\\n\\n## 11) References (internalize; no external dependency at runtime)\\n\\n- WCAG\\xA02.2 (AA), EN\\xA0301\\xA0549. ARIA Authoring Practices. Platform HIG (Apple, Material).\\n- `packages/lssm/libs/ui-kit-web` as the canonical UI source for web.\\n\\n> **Bottom line:** Shipping means **accessible by default**. We don’t trade a11y for speed; we bake it into speed.\\n\\n---\\n\\n## 12) Adoption Status (2025-09-23)\\n\\n- web-artisan: AccessibilityProvider integrated; sr-only/forced-colors applied; 44x44 targets; forms announce errors; jest-axe and cypress-axe in place.\\n- web-strit: AccessibilityProvider integrated; forced-colors, sr-only; forms announce errors; 44x44 targets; contrast tokens and text-scale wired; jest-axe and cypress-axe in place.\\n- web-coliving: AccessibilityProvider integrated; forced-colors and focus visibility added; text-scale wired; landing pages converted to `Section`/stacks with text-lg defaults; CTA capture standardized; ESLint guard for text-xs in main content; jest-axe and cypress-axe in place. Next: audit icon-only controls and ensure 44x44 targets; add role=\\\"alert\\\" where critical.\\n\\n> CI gates: run eslint a11y, jest-axe on components, and cypress-axe on critical flows per app.\\n\\n---\\n\\n## 13) CI Hardening & Visual QA\\n\\n- Linting: Run eslint with jsx-a11y rules across all web apps; block on violations.\\n- Unit: Run jest-axe for ui-kit-web and app-level components.\\n- Integration: cypress-axe on key flows (auth, forms, dialogs, tables).\\n- Synthetic scans: pa11y-ci on critical pages (0 Critical/Serious policy).\\n- Performance/A11y audit: Lighthouse CI with a11y score >= 95 on target routes.\\n- Artifacts: Upload pa11y and Lighthouse reports per PR; annotate failures.\\n\\n### Recent additions (2025-09-26)\\n\\n- AutocompleteInput (groceries): Upgraded to ARIA combobox pattern with `aria-controls`, `aria-activedescendant`, `Escape`/`Tab` handling, and labelled listbox.\\n- Cypress a11y tests added for furniture and incidents modules on `/modules` and operators flows; checks run axe with critical/serious impacts.\\n\\n## 14) Accessibility Telemetry (PostHog)\\n\\n- Events (anonymized): a11y_pref_changed (text_scale, contrast_mode, reduce_motion), a11y_panel_opened.\\n- Properties: app, route, previous_value, new_value, timestamp.\\n- Dashboards: Adoption over time, per app/route; correlation with reduced bounce on forms.\\n- Privacy: No PII; aggregate only.\\n\"\n}];\nregisterDocBlocks(accessibility_wcag_compliance_specs_DocBlocks);\n\n//#endregion\n//# sourceMappingURL=accessibility_wcag_compliance_specs.docblock.js.map"],"mappings":";;;AAaA,kBAVsD,CAAC;CACtD,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,sCAAsC;CAC7C,MAAM;CACN,CAAC,CAC8D"}

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/index.js

@@ -0,0 +1,24 @@
+import "./registry.js";
+import "./tech-contracts.docs.js";
+import "./meta.docs.js";
+import "./accessibility_wcag_compliance_specs.docblock.js";
+import "./tech/lifecycle-stage-system.docblock.js";
+import "./tech/presentation-runtime.docblock.js";
+import "./tech/auth/better-auth-nextjs.docblock.js";
+import "./tech/schema/README.docblock.js";
+import "./tech/templates/runtime.docblock.js";
+import "./tech/workflows/overview.docblock.js";
+import "./tech/mcp-endpoints.docblock.js";
+import "./tech/vscode-extension.docblock.js";
+import "./tech/telemetry-ingest.docblock.js";
+import "./tech/contracts/openapi-export.docblock.js";
+import "./tech/studio/workspaces.docblock.js";
+import "./tech/studio/sandbox-unlogged.docblock.js";
+import "./tech/studio/workspace-ops.docblock.js";
+import "./tech/studio/project-routing.docblock.js";
+import "./tech/studio/platform-admin-panel.docblock.js";
+import "./tech/studio/learning-events.docblock.js";
+import "./tech/studio/learning-journeys.docblock.js";
+import "./tech/studio/project-access-teams.docblock.js";
+import "./tech/studio/team-invitations.docblock.js";
+import "./tech/llm/llm-integration.docblock.js";

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/meta.docs.js

@@ -0,0 +1,29 @@
+import { registerDocBlocks } from "./registry.js";
+
+//#region ../learning-journey-ui-shared/dist/libs/contracts/dist/docs/meta.docs.js
+const metaDocs = [{
+	id: "docs.meta.docblocks-process",
+	title: "DocBlocks process",
+	summary: "How to author goal/how/usage DocBlocks close to code.",
+	kind: "reference",
+	visibility: "mixed",
+	route: "/docs/meta/docblocks-process",
+	tags: ["docs", "process"],
+	body: `## DocBlocks authoring rules
+
+- Colocate docs beside implementation; avoid barrel /docs folders.
+- Split intent:
+  - **goal**: why this exists (before implementation).
+  - **how**: operational/runbook steps.
+  - **usage**: quick checklist for consumers.
+- Use \`visibility\`: public | internal | mixed.
+- Prefer routes like \`/docs/<domain>/<topic>/<kind>\`; ids mirror that.
+- Keep body Markdown LLM-friendly; avoid HTML.
+- Add owners/tags/domain/stability when known.
+- For presentations/markdown outputs, rely on TransformEngine via DocRegistry.
+- No sourcePath; DocBlocks are canonical.`
+}];
+registerDocBlocks(metaDocs);
+
+//#endregion
+//# sourceMappingURL=meta.docs.js.map

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/meta.docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.docs.js","names":[],"sources":["../../../../../../../../../learning-journey-ui-shared/dist/libs/contracts/dist/docs/meta.docs.js"],"sourcesContent":["import { registerDocBlocks } from \"./registry.js\";\n\n//#region ../../libs/contracts/dist/docs/meta.docs.js\nconst metaDocs = [{\n\tid: \"docs.meta.docblocks-process\",\n\ttitle: \"DocBlocks process\",\n\tsummary: \"How to author goal/how/usage DocBlocks close to code.\",\n\tkind: \"reference\",\n\tvisibility: \"mixed\",\n\troute: \"/docs/meta/docblocks-process\",\n\ttags: [\"docs\", \"process\"],\n\tbody: `## DocBlocks authoring rules\n\n- Colocate docs beside implementation; avoid barrel /docs folders.\n- Split intent:\n  - **goal**: why this exists (before implementation).\n  - **how**: operational/runbook steps.\n  - **usage**: quick checklist for consumers.\n- Use \\`visibility\\`: public | internal | mixed.\n- Prefer routes like \\`/docs/<domain>/<topic>/<kind>\\`; ids mirror that.\n- Keep body Markdown LLM-friendly; avoid HTML.\n- Add owners/tags/domain/stability when known.\n- For presentations/markdown outputs, rely on TransformEngine via DocRegistry.\n- No sourcePath; DocBlocks are canonical.`\n}];\nregisterDocBlocks(metaDocs);\n\n//#endregion\nexport { metaDocs };\n//# sourceMappingURL=meta.docs.js.map"],"mappings":";;;AAGA,MAAM,WAAW,CAAC;CACjB,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,QAAQ,UAAU;CACzB,MAAM;;;;;;;;;;;;;CAaN,CAAC;AACF,kBAAkB,SAAS"}

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/presentations.js

@@ -0,0 +1,72 @@
+//#region ../learning-journey-ui-shared/dist/libs/contracts/dist/docs/presentations.js
+const DEFAULT_TARGETS = [
+	"markdown",
+	"application/json",
+	"application/xml",
+	"react"
+];
+function normalizeRoute(route) {
+	if (!route.length) return "/";
+	const withLeading = route.startsWith("/") ? route : `/${route}`;
+	return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+	if (block.route) return normalizeRoute(block.route);
+	const prefix = routePrefix ?? "/docs";
+	const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+	return normalizeRoute(slug.startsWith("/") ? slug : `${prefix}/${slug}`);
+}
+function buildName(block, namespace) {
+	return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationV2(block, options) {
+	const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+	const version = block.version ?? options?.defaultVersion ?? 1;
+	const stability = block.stability ?? options?.defaultStability ?? "stable";
+	return {
+		meta: {
+			name: buildName(block, options?.namespace),
+			version,
+			description: block.summary ?? block.title,
+			tags: block.tags,
+			owners: block.owners,
+			domain: block.domain,
+			stability
+		},
+		policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : void 0,
+		source: {
+			type: "blocknotejs",
+			docJson: block.body
+		},
+		targets
+	};
+}
+function docBlockToPresentationSpec(block, options) {
+	const version = block.version ?? options?.defaultVersion ?? 1;
+	const stability = block.stability ?? options?.defaultStability ?? "stable";
+	return {
+		meta: {
+			name: buildName(block, options?.namespace),
+			version,
+			stability,
+			tags: block.tags,
+			owners: block.owners,
+			description: block.summary ?? block.title
+		},
+		content: {
+			kind: "markdown",
+			content: block.body
+		}
+	};
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+	return blocks.map((block) => ({
+		block,
+		route: deriveRoute(block, options?.routePrefix),
+		descriptor: docBlockToPresentationV2(block, options)
+	}));
+}
+
+//#endregion
+export { docBlockToPresentationSpec, docBlocksToPresentationRoutes };
+//# sourceMappingURL=presentations.js.map

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/presentations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentations.js","names":[],"sources":["../../../../../../../../../learning-journey-ui-shared/dist/libs/contracts/dist/docs/presentations.js"],"sourcesContent":["//#region ../../libs/contracts/dist/docs/presentations.js\nconst DEFAULT_TARGETS = [\n\t\"markdown\",\n\t\"application/json\",\n\t\"application/xml\",\n\t\"react\"\n];\nfunction normalizeRoute(route) {\n\tif (!route.length) return \"/\";\n\tconst withLeading = route.startsWith(\"/\") ? route : `/${route}`;\n\treturn withLeading === \"/\" ? \"/\" : withLeading.replace(/\\/+$/, \"\");\n}\nfunction deriveRoute(block, routePrefix) {\n\tif (block.route) return normalizeRoute(block.route);\n\tconst prefix = routePrefix ?? \"/docs\";\n\tconst slug = block.id.replace(/^docs\\.?/, \"\").replace(/\\./g, \"/\").replace(/\\/+/g, \"/\");\n\treturn normalizeRoute(slug.startsWith(\"/\") ? slug : `${prefix}/${slug}`);\n}\nfunction buildName(block, namespace) {\n\treturn namespace ? `${namespace}.${block.id}` : block.id;\n}\nfunction docBlockToPresentationV2(block, options) {\n\tconst targets = options?.defaultTargets ?? DEFAULT_TARGETS;\n\tconst version = block.version ?? options?.defaultVersion ?? 1;\n\tconst stability = block.stability ?? options?.defaultStability ?? \"stable\";\n\treturn {\n\t\tmeta: {\n\t\t\tname: buildName(block, options?.namespace),\n\t\t\tversion,\n\t\t\tdescription: block.summary ?? block.title,\n\t\t\ttags: block.tags,\n\t\t\towners: block.owners,\n\t\t\tdomain: block.domain,\n\t\t\tstability\n\t\t},\n\t\tpolicy: block.visibility && block.visibility !== \"public\" ? { flags: [block.visibility] } : void 0,\n\t\tsource: {\n\t\t\ttype: \"blocknotejs\",\n\t\t\tdocJson: block.body\n\t\t},\n\t\ttargets\n\t};\n}\nfunction docBlockToPresentationSpec(block, options) {\n\tconst version = block.version ?? options?.defaultVersion ?? 1;\n\tconst stability = block.stability ?? options?.defaultStability ?? \"stable\";\n\treturn {\n\t\tmeta: {\n\t\t\tname: buildName(block, options?.namespace),\n\t\t\tversion,\n\t\t\tstability,\n\t\t\ttags: block.tags,\n\t\t\towners: block.owners,\n\t\t\tdescription: block.summary ?? block.title\n\t\t},\n\t\tcontent: {\n\t\t\tkind: \"markdown\",\n\t\t\tcontent: block.body\n\t\t}\n\t};\n}\nfunction docBlocksToPresentationRoutes(blocks, options) {\n\treturn blocks.map((block) => ({\n\t\tblock,\n\t\troute: deriveRoute(block, options?.routePrefix),\n\t\tdescriptor: docBlockToPresentationV2(block, options)\n\t}));\n}\n\n//#endregion\nexport { docBlockToPresentationSpec, docBlockToPresentationV2, docBlocksToPresentationRoutes };\n//# sourceMappingURL=presentations.js.map"],"mappings":";AACA,MAAM,kBAAkB;CACvB;CACA;CACA;CACA;CACA;AACD,SAAS,eAAe,OAAO;AAC9B,KAAI,CAAC,MAAM,OAAQ,QAAO;CAC1B,MAAM,cAAc,MAAM,WAAW,IAAI,GAAG,QAAQ,IAAI;AACxD,QAAO,gBAAgB,MAAM,MAAM,YAAY,QAAQ,QAAQ,GAAG;;AAEnE,SAAS,YAAY,OAAO,aAAa;AACxC,KAAI,MAAM,MAAO,QAAO,eAAe,MAAM,MAAM;CACnD,MAAM,SAAS,eAAe;CAC9B,MAAM,OAAO,MAAM,GAAG,QAAQ,YAAY,GAAG,CAAC,QAAQ,OAAO,IAAI,CAAC,QAAQ,QAAQ,IAAI;AACtF,QAAO,eAAe,KAAK,WAAW,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO;;AAEzE,SAAS,UAAU,OAAO,WAAW;AACpC,QAAO,YAAY,GAAG,UAAU,GAAG,MAAM,OAAO,MAAM;;AAEvD,SAAS,yBAAyB,OAAO,SAAS;CACjD,MAAM,UAAU,SAAS,kBAAkB;CAC3C,MAAM,UAAU,MAAM,WAAW,SAAS,kBAAkB;CAC5D,MAAM,YAAY,MAAM,aAAa,SAAS,oBAAoB;AAClE,QAAO;EACN,MAAM;GACL,MAAM,UAAU,OAAO,SAAS,UAAU;GAC1C;GACA,aAAa,MAAM,WAAW,MAAM;GACpC,MAAM,MAAM;GACZ,QAAQ,MAAM;GACd,QAAQ,MAAM;GACd;GACA;EACD,QAAQ,MAAM,cAAc,MAAM,eAAe,WAAW,EAAE,OAAO,CAAC,MAAM,WAAW,EAAE,GAAG,KAAK;EACjG,QAAQ;GACP,MAAM;GACN,SAAS,MAAM;GACf;EACD;EACA;;AAEF,SAAS,2BAA2B,OAAO,SAAS;CACnD,MAAM,UAAU,MAAM,WAAW,SAAS,kBAAkB;CAC5D,MAAM,YAAY,MAAM,aAAa,SAAS,oBAAoB;AAClE,QAAO;EACN,MAAM;GACL,MAAM,UAAU,OAAO,SAAS,UAAU;GAC1C;GACA;GACA,MAAM,MAAM;GACZ,QAAQ,MAAM;GACd,aAAa,MAAM,WAAW,MAAM;GACpC;EACD,SAAS;GACR,MAAM;GACN,SAAS,MAAM;GACf;EACD;;AAEF,SAAS,8BAA8B,QAAQ,SAAS;AACvD,QAAO,OAAO,KAAK,WAAW;EAC7B;EACA,OAAO,YAAY,OAAO,SAAS,YAAY;EAC/C,YAAY,yBAAyB,OAAO,QAAQ;EACpD,EAAE"}

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/registry.js

@@ -0,0 +1,45 @@
+import { docBlockToPresentationSpec, docBlocksToPresentationRoutes } from "./presentations.js";
+
+//#region ../learning-journey-ui-shared/dist/libs/contracts/dist/docs/registry.js
+var DocRegistry = class {
+	routes = /* @__PURE__ */ new Map();
+	constructor(blocks = [], options) {
+		blocks.forEach((block) => this.register(block, options));
+	}
+	register(block, options) {
+		const [route] = docBlocksToPresentationRoutes([block], options);
+		if (route) this.routes.set(block.id, route);
+		return this;
+	}
+	list() {
+		return [...this.routes.values()];
+	}
+	get(id) {
+		return this.routes.get(id);
+	}
+	toRouteTuples() {
+		return this.list().map(({ route, descriptor }) => [route, descriptor]);
+	}
+	toPresentationSpecs(options) {
+		return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+	}
+};
+const requiredFields = [
+	"id",
+	"title",
+	"body",
+	"kind",
+	"visibility",
+	"route"
+];
+const defaultDocRegistry = new DocRegistry();
+function registerDocBlocks(blocks) {
+	for (const block of blocks) {
+		for (const field of requiredFields) if (!block[field]) throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+		defaultDocRegistry.register(block);
+	}
+}
+
+//#endregion
+export { registerDocBlocks };
+//# sourceMappingURL=registry.js.map

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","names":[],"sources":["../../../../../../../../../learning-journey-ui-shared/dist/libs/contracts/dist/docs/registry.js"],"sourcesContent":["import { docBlockToPresentationSpec, docBlocksToPresentationRoutes } from \"./presentations.js\";\n\n//#region ../../libs/contracts/dist/docs/registry.js\nvar DocRegistry = class {\n\troutes = /* @__PURE__ */ new Map();\n\tconstructor(blocks = [], options) {\n\t\tblocks.forEach((block) => this.register(block, options));\n\t}\n\tregister(block, options) {\n\t\tconst [route] = docBlocksToPresentationRoutes([block], options);\n\t\tif (route) this.routes.set(block.id, route);\n\t\treturn this;\n\t}\n\tlist() {\n\t\treturn [...this.routes.values()];\n\t}\n\tget(id) {\n\t\treturn this.routes.get(id);\n\t}\n\ttoRouteTuples() {\n\t\treturn this.list().map(({ route, descriptor }) => [route, descriptor]);\n\t}\n\ttoPresentationSpecs(options) {\n\t\treturn this.list().map(({ block }) => docBlockToPresentationSpec(block, options));\n\t}\n};\nconst requiredFields = [\n\t\"id\",\n\t\"title\",\n\t\"body\",\n\t\"kind\",\n\t\"visibility\",\n\t\"route\"\n];\nconst defaultDocRegistry = new DocRegistry();\nfunction registerDocBlocks(blocks) {\n\tfor (const block of blocks) {\n\t\tfor (const field of requiredFields) if (!block[field]) throw new Error(`DocBlock ${block.id ?? \"<missing id>\"} missing field ${String(field)}`);\n\t\tdefaultDocRegistry.register(block);\n\t}\n}\n\n//#endregion\nexport { DocRegistry, defaultDocRegistry, registerDocBlocks };\n//# sourceMappingURL=registry.js.map"],"mappings":";;;AAGA,IAAI,cAAc,MAAM;CACvB,yBAAyB,IAAI,KAAK;CAClC,YAAY,SAAS,EAAE,EAAE,SAAS;AACjC,SAAO,SAAS,UAAU,KAAK,SAAS,OAAO,QAAQ,CAAC;;CAEzD,SAAS,OAAO,SAAS;EACxB,MAAM,CAAC,SAAS,8BAA8B,CAAC,MAAM,EAAE,QAAQ;AAC/D,MAAI,MAAO,MAAK,OAAO,IAAI,MAAM,IAAI,MAAM;AAC3C,SAAO;;CAER,OAAO;AACN,SAAO,CAAC,GAAG,KAAK,OAAO,QAAQ,CAAC;;CAEjC,IAAI,IAAI;AACP,SAAO,KAAK,OAAO,IAAI,GAAG;;CAE3B,gBAAgB;AACf,SAAO,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,iBAAiB,CAAC,OAAO,WAAW,CAAC;;CAEvE,oBAAoB,SAAS;AAC5B,SAAO,KAAK,MAAM,CAAC,KAAK,EAAE,YAAY,2BAA2B,OAAO,QAAQ,CAAC;;;AAGnF,MAAM,iBAAiB;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;AACD,MAAM,qBAAqB,IAAI,aAAa;AAC5C,SAAS,kBAAkB,QAAQ;AAClC,MAAK,MAAM,SAAS,QAAQ;AAC3B,OAAK,MAAM,SAAS,eAAgB,KAAI,CAAC,MAAM,OAAQ,OAAM,IAAI,MAAM,YAAY,MAAM,MAAM,eAAe,iBAAiB,OAAO,MAAM,GAAG;AAC/I,qBAAmB,SAAS,MAAM"}

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js

@@ -0,0 +1,80 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../learning-journey-ui-shared/dist/libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js
+registerDocBlocks([{
+	id: "docs.tech.auth.better-auth-nextjs",
+	title: "Better Auth + Next.js integration (ContractSpec)",
+	summary: "How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/auth/better-auth-nextjs",
+	tags: [
+		"auth",
+		"better-auth",
+		"nextjs",
+		"cookies",
+		"proxy",
+		"hmr"
+	],
+	body: `# Better Auth + Next.js integration (ContractSpec)
+
+This repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).
+
+## Server config (Better Auth)
+
+- Source: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Important: \`nextCookies()\` must be the **last** plugin in the Better Auth plugin list so \`Set-Cookie\` is applied correctly in Next.js environments.
+
+## Better Auth Admin plugin
+
+ContractSpec Studio enables the Better Auth **Admin plugin** to support platform-admin user operations (list users, impersonation, etc.).
+
+- Server: \`admin()\` plugin in \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Client: \`adminClient()\` in \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+
+### PLATFORM_ADMIN ⇒ Better Auth admin role
+
+Better Auth Admin endpoints authorize via \`user.role\`. ContractSpec enforces an org-driven rule:
+
+- If the **active organization** has \`type = PLATFORM_ADMIN\`, the signed-in user is ensured to have \`User.role\` containing \`admin\`.
+- This is applied in the session creation hook and re-checked in \`assertsPlatformAdmin()\`.
+
+This keeps admin enablement deterministic and avoids manual role backfills.
+
+## Client config (React web + Expo)
+
+To avoid duplicate background refresh/polling loops in dev (Fast Refresh/HMR), the Better Auth client is implemented as a singleton cached on \`globalThis\`.
+
+- Web client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+- Native client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.native.ts\`
+
+Import guidance:
+
+- If you only need the context/hook, prefer importing from \`@lssm/bundle.contractspec-studio/presentation/providers/auth\`.
+- If you explicitly need the Better Auth client instance (e.g. admin impersonation, direct API calls), import from \`@lssm/bundle.contractspec-studio/presentation/providers/auth/client\`.
+
+## Public routes (login / signup)
+
+Public auth pages should avoid eager \`authClient\` initialization.
+
+Pattern used:
+
+- In the submit handler, dynamically import \`@lssm/bundle.contractspec-studio/presentation/providers/auth/index.web\` and call \`authClient.signIn.*\` / \`authClient.signUp.*\`.
+
+This prevents session refresh behavior from starting just because a public page rendered.
+
+## Next.js proxy auth (web-landing)
+
+The Next.js proxy/middleware is used for **redirect decisions only**. It must not perform DB-backed session reads on every request.
+
+- Source: \`packages/apps/web-landing/src/proxy.ts\`
+- Approach: cookie-only checks via Better Auth cookies helpers:
+  - \`getSessionCookie(request)\`
+  - \`getCookieCache(request)\`
+
+These checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.
+`
+}]);
+
+//#endregion
+//# sourceMappingURL=better-auth-nextjs.docblock.js.map

package/dist/examples/learning-journey-ui-shared/dist/libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth-nextjs.docblock.js","names":[],"sources":["../../../../../../../../../../../learning-journey-ui-shared/dist/libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js"],"sourcesContent":["import { registerDocBlocks } from \"../../registry.js\";\n\n//#region ../../libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js\nconst tech_auth_better_auth_nextjs_DocBlocks = [{\n\tid: \"docs.tech.auth.better-auth-nextjs\",\n\ttitle: \"Better Auth + Next.js integration (ContractSpec)\",\n\tsummary: \"How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).\",\n\tkind: \"reference\",\n\tvisibility: \"public\",\n\troute: \"/docs/tech/auth/better-auth-nextjs\",\n\ttags: [\n\t\t\"auth\",\n\t\t\"better-auth\",\n\t\t\"nextjs\",\n\t\t\"cookies\",\n\t\t\"proxy\",\n\t\t\"hmr\"\n\t],\n\tbody: `# Better Auth + Next.js integration (ContractSpec)\n\nThis repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).\n\n## Server config (Better Auth)\n\n- Source: \\`packages/bundles/contractspec-studio/src/application/services/auth.ts\\`\n- Important: \\`nextCookies()\\` must be the **last** plugin in the Better Auth plugin list so \\`Set-Cookie\\` is applied correctly in Next.js environments.\n\n## Better Auth Admin plugin\n\nContractSpec Studio enables the Better Auth **Admin plugin** to support platform-admin user operations (list users, impersonation, etc.).\n\n- Server: \\`admin()\\` plugin in \\`packages/bundles/contractspec-studio/src/application/services/auth.ts\\`\n- Client: \\`adminClient()\\` in \\`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\\`\n\n### PLATFORM_ADMIN ⇒ Better Auth admin role\n\nBetter Auth Admin endpoints authorize via \\`user.role\\`. ContractSpec enforces an org-driven rule:\n\n- If the **active organization** has \\`type = PLATFORM_ADMIN\\`, the signed-in user is ensured to have \\`User.role\\` containing \\`admin\\`.\n- This is applied in the session creation hook and re-checked in \\`assertsPlatformAdmin()\\`.\n\nThis keeps admin enablement deterministic and avoids manual role backfills.\n\n## Client config (React web + Expo)\n\nTo avoid duplicate background refresh/polling loops in dev (Fast Refresh/HMR), the Better Auth client is implemented as a singleton cached on \\`globalThis\\`.\n\n- Web client: \\`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\\`\n- Native client: \\`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.native.ts\\`\n\nImport guidance:\n\n- If you only need the context/hook, prefer importing from \\`@lssm/bundle.contractspec-studio/presentation/providers/auth\\`.\n- If you explicitly need the Better Auth client instance (e.g. admin impersonation, direct API calls), import from \\`@lssm/bundle.contractspec-studio/presentation/providers/auth/client\\`.\n\n## Public routes (login / signup)\n\nPublic auth pages should avoid eager \\`authClient\\` initialization.\n\nPattern used:\n\n- In the submit handler, dynamically import \\`@lssm/bundle.contractspec-studio/presentation/providers/auth/index.web\\` and call \\`authClient.signIn.*\\` / \\`authClient.signUp.*\\`.\n\nThis prevents session refresh behavior from starting just because a public page rendered.\n\n## Next.js proxy auth (web-landing)\n\nThe Next.js proxy/middleware is used for **redirect decisions only**. It must not perform DB-backed session reads on every request.\n\n- Source: \\`packages/apps/web-landing/src/proxy.ts\\`\n- Approach: cookie-only checks via Better Auth cookies helpers:\n  - \\`getSessionCookie(request)\\`\n  - \\`getCookieCache(request)\\`\n\nThese checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.\n`\n}];\nregisterDocBlocks(tech_auth_better_auth_nextjs_DocBlocks);\n\n//#endregion\n//# sourceMappingURL=better-auth-nextjs.docblock.js.map"],"mappings":";;;AA6EA,kBA1E+C,CAAC;CAC/C,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACL;EACA;EACA;EACA;EACA;EACA;EACA;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DN,CAAC,CACuD"}