@contractspec/example.learning-journey-registry 1.44.0

package/dist/tracks.js

@@ -0,0 +1,48 @@
+import { crmLearningTracks } from "@contractspec/example.learning-journey-crm-onboarding/track";
+import { drillTracks } from "@contractspec/example.learning-journey-duo-drills/track";
+import { ambientCoachTracks } from "@contractspec/example.learning-journey-ambient-coach/track";
+import { questTracks } from "@contractspec/example.learning-journey-quest-challenges/track";
+import { platformLearningTracks } from "@contractspec/example.learning-journey-platform-tour/track";
+import { studioLearningTracks } from "@contractspec/example.learning-journey-studio-onboarding/track";
+
+//#region src/tracks.ts
+const mapStep = (step) => ({
+	id: step.id,
+	title: step.title,
+	description: step.description,
+	completionEvent: step.completion.eventName,
+	completionCondition: step.completion,
+	xpReward: step.xpReward,
+	isRequired: step.isRequired,
+	canSkip: step.canSkip,
+	actionUrl: step.actionUrl,
+	actionLabel: step.actionLabel,
+	availability: step.availability,
+	metadata: step.metadata
+});
+const mapTrackSpecToDto = (track) => ({
+	id: track.id,
+	name: track.name,
+	description: track.description,
+	productId: track.productId,
+	targetUserSegment: track.targetUserSegment,
+	targetRole: track.targetRole,
+	totalXp: track.totalXp,
+	streakRule: track.streakRule,
+	completionRewards: track.completionRewards,
+	steps: track.steps.map(mapStep),
+	metadata: track.metadata
+});
+const learningJourneyTracks = [
+	...studioLearningTracks,
+	...platformLearningTracks,
+	...crmLearningTracks,
+	...drillTracks,
+	...ambientCoachTracks,
+	...questTracks
+];
+const onboardingTrackCatalog = learningJourneyTracks.map(mapTrackSpecToDto);
+
+//#endregion
+export { crmLearningTracks, learningJourneyTracks, mapStep, mapTrackSpecToDto, onboardingTrackCatalog, platformLearningTracks, studioLearningTracks };
+//# sourceMappingURL=tracks.js.map

package/dist/tracks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracks.js","names":["learningJourneyTracks: LearningJourneyTrackSpec[]","onboardingTrackCatalog: OnboardingTrackDto[]"],"sources":["../src/tracks.ts"],"sourcesContent":["import type {\n  LearningJourneyStepSpec,\n  LearningJourneyTrackSpec,\n  StepAvailabilitySpec,\n  StepCompletionConditionSpec,\n} from '@contractspec/module.learning-journey/track-spec';\nimport { crmLearningTracks } from '@contractspec/example.learning-journey-crm-onboarding/track';\nimport { drillTracks } from '@contractspec/example.learning-journey-duo-drills/track';\nimport { ambientCoachTracks } from '@contractspec/example.learning-journey-ambient-coach/track';\nimport { questTracks } from '@contractspec/example.learning-journey-quest-challenges/track';\nimport { platformLearningTracks } from '@contractspec/example.learning-journey-platform-tour/track';\nimport { studioLearningTracks } from '@contractspec/example.learning-journey-studio-onboarding/track';\n\nexport interface OnboardingStepDto {\n  id: string;\n  title: string;\n  description?: string;\n  completionEvent: string;\n  completionCondition?: StepCompletionConditionSpec;\n  xpReward?: number;\n  isRequired?: boolean;\n  canSkip?: boolean;\n  actionUrl?: string;\n  actionLabel?: string;\n  availability?: StepAvailabilitySpec;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface OnboardingTrackDto {\n  id: string;\n  name: string;\n  description?: string;\n  productId?: string;\n  targetUserSegment?: string;\n  targetRole?: string;\n  totalXp?: number;\n  streakRule?: LearningJourneyTrackSpec['streakRule'];\n  completionRewards?: LearningJourneyTrackSpec['completionRewards'];\n  steps: OnboardingStepDto[];\n  metadata?: Record<string, unknown>;\n}\n\nconst mapStep = (step: LearningJourneyStepSpec): OnboardingStepDto => ({\n  id: step.id,\n  title: step.title,\n  description: step.description,\n  completionEvent: step.completion.eventName,\n  completionCondition: step.completion,\n  xpReward: step.xpReward,\n  isRequired: step.isRequired,\n  canSkip: step.canSkip,\n  actionUrl: step.actionUrl,\n  actionLabel: step.actionLabel,\n  availability: step.availability,\n  metadata: step.metadata,\n});\n\nexport const mapTrackSpecToDto = (\n  track: LearningJourneyTrackSpec\n): OnboardingTrackDto => ({\n  id: track.id,\n  name: track.name,\n  description: track.description,\n  productId: track.productId,\n  targetUserSegment: track.targetUserSegment,\n  targetRole: track.targetRole,\n  totalXp: track.totalXp,\n  streakRule: track.streakRule,\n  completionRewards: track.completionRewards,\n  steps: track.steps.map(mapStep),\n  metadata: track.metadata,\n});\n\nexport const learningJourneyTracks: LearningJourneyTrackSpec[] = [\n  ...studioLearningTracks,\n  ...platformLearningTracks,\n  ...crmLearningTracks,\n  ...drillTracks,\n  ...ambientCoachTracks,\n  ...questTracks,\n];\n\nexport const onboardingTrackCatalog: OnboardingTrackDto[] =\n  learningJourneyTracks.map(mapTrackSpecToDto);\n\nexport {\n  studioLearningTracks,\n  platformLearningTracks,\n  crmLearningTracks,\n  mapStep,\n};\n"],"mappings":";;;;;;;;AA0CA,MAAM,WAAW,UAAsD;CACrE,IAAI,KAAK;CACT,OAAO,KAAK;CACZ,aAAa,KAAK;CAClB,iBAAiB,KAAK,WAAW;CACjC,qBAAqB,KAAK;CAC1B,UAAU,KAAK;CACf,YAAY,KAAK;CACjB,SAAS,KAAK;CACd,WAAW,KAAK;CAChB,aAAa,KAAK;CAClB,cAAc,KAAK;CACnB,UAAU,KAAK;CAChB;AAED,MAAa,qBACX,WACwB;CACxB,IAAI,MAAM;CACV,MAAM,MAAM;CACZ,aAAa,MAAM;CACnB,WAAW,MAAM;CACjB,mBAAmB,MAAM;CACzB,YAAY,MAAM;CAClB,SAAS,MAAM;CACf,YAAY,MAAM;CAClB,mBAAmB,MAAM;CACzB,OAAO,MAAM,MAAM,IAAI,QAAQ;CAC/B,UAAU,MAAM;CACjB;AAED,MAAaA,wBAAoD;CAC/D,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACJ;AAED,MAAaC,yBACX,sBAAsB,IAAI,kBAAkB"}

package/dist/ui/LearningMiniApp.d.ts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { LearningView } from "@contractspec/example.learning-journey-ui-shared";
+
+//#region src/ui/LearningMiniApp.d.ts
+/** Template IDs that map to learning journey tracks */
+type LearningTemplateId = 'learning-journey-duo-drills' | 'learning-journey-quest-challenges' | 'learning-journey-studio-onboarding' | 'learning-journey-platform-tour' | 'learning-journey-ambient-coach' | 'learning-journey-crm-onboarding';
+interface LearningMiniAppProps {
+  templateId: string;
+  initialView?: LearningView;
+  onViewChange?: (view: LearningView) => void;
+}
+/** Router component that picks the correct mini-app based on template ID */
+declare function LearningMiniApp({
+  templateId,
+  initialView,
+  onViewChange
+}: LearningMiniAppProps): react_jsx_runtime0.JSX.Element;
+/** Check if a template ID is a learning journey template */
+declare function isLearningTemplate(templateId: string): templateId is LearningTemplateId;
+/** Get all learning template IDs */
+declare function getLearningTemplateIds(): LearningTemplateId[];
+//#endregion
+export { LearningMiniApp, getLearningTemplateIds, isLearningTemplate };
+//# sourceMappingURL=LearningMiniApp.d.ts.map

package/dist/ui/LearningMiniApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningMiniApp.d.ts","names":[],"sources":["../../src/ui/LearningMiniApp.tsx"],"sourcesContent":[],"mappings":";;;;;KAUK,kBAAA;UA+BK,oBAAA;EA/BL,UAAA,EAAA,MAAA;EA+BK,WAAA,CAAA,EAEM,YAFc;EAOd,YAAA,CAAA,EAAA,CAAA,IAAe,EAJP,YAIO,EAAA,GAAA,IAAA;;;AAG7B,iBAHc,eAAA,CAGd;EAAA,UAAA;EAAA,WAAA;EAAA;AAAA,CAAA,EACC,oBADD,CAAA,EACqB,kBAAA,CAAA,GAAA,CAAA,OADrB;;AACqB,iBA2DP,kBAAA,CA3DO,UAAA,EAAA,MAAA,CAAA,EAAA,UAAA,IA6DN,kBA7DM;;AA2DP,iBAOA,sBAAA,CAAA,CALC,EAKyB,kBALP,EAAA"}

package/dist/ui/LearningMiniApp.js

@@ -0,0 +1,80 @@
+'use client';
+
+import { learningJourneyTracks } from "../tracks.js";
+import { useMemo } from "react";
+import { GamifiedMiniApp } from "@contractspec/example.learning-journey-ui-gamified";
+import { OnboardingMiniApp } from "@contractspec/example.learning-journey-ui-onboarding";
+import { CoachingMiniApp } from "@contractspec/example.learning-journey-ui-coaching";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/ui/LearningMiniApp.tsx
+/** Map template IDs to track IDs */
+const TEMPLATE_TO_TRACK = {
+	"learning-journey-duo-drills": "drills_language_basics",
+	"learning-journey-quest-challenges": "money_reset_7day",
+	"learning-journey-studio-onboarding": "studio_getting_started",
+	"learning-journey-platform-tour": "platform_tour",
+	"learning-journey-ambient-coach": "money_ambient_coach",
+	"learning-journey-crm-onboarding": "crm_first_win"
+};
+/** Map template IDs to mini-app type */
+const TEMPLATE_TO_APP_TYPE = {
+	"learning-journey-duo-drills": "gamified",
+	"learning-journey-quest-challenges": "gamified",
+	"learning-journey-studio-onboarding": "onboarding",
+	"learning-journey-platform-tour": "onboarding",
+	"learning-journey-ambient-coach": "coaching",
+	"learning-journey-crm-onboarding": "coaching"
+};
+/** Router component that picks the correct mini-app based on template ID */
+function LearningMiniApp({ templateId, initialView = "overview", onViewChange }) {
+	const track = useMemo(() => {
+		const trackId = TEMPLATE_TO_TRACK[templateId];
+		if (!trackId) return null;
+		return learningJourneyTracks.find((t) => t.id === trackId);
+	}, [templateId]);
+	const appType = TEMPLATE_TO_APP_TYPE[templateId];
+	if (!track) return /* @__PURE__ */ jsx("div", {
+		className: "rounded-lg border border-amber-500/50 bg-amber-500/10 p-6 text-center",
+		children: /* @__PURE__ */ jsxs("p", {
+			className: "text-amber-500",
+			children: ["Unknown learning template: ", templateId]
+		})
+	});
+	switch (appType) {
+		case "gamified": return /* @__PURE__ */ jsx(GamifiedMiniApp, {
+			track,
+			initialView,
+			onViewChange
+		});
+		case "onboarding": return /* @__PURE__ */ jsx(OnboardingMiniApp, {
+			track,
+			initialView,
+			onViewChange
+		});
+		case "coaching": return /* @__PURE__ */ jsx(CoachingMiniApp, {
+			track,
+			initialView,
+			onViewChange
+		});
+		default: return /* @__PURE__ */ jsx("div", {
+			className: "rounded-lg border border-red-500/50 bg-red-500/10 p-6 text-center",
+			children: /* @__PURE__ */ jsxs("p", {
+				className: "text-red-500",
+				children: ["Unknown app type for template: ", templateId]
+			})
+		});
+	}
+}
+/** Check if a template ID is a learning journey template */
+function isLearningTemplate(templateId) {
+	return templateId in TEMPLATE_TO_TRACK;
+}
+/** Get all learning template IDs */
+function getLearningTemplateIds() {
+	return Object.keys(TEMPLATE_TO_TRACK);
+}
+
+//#endregion
+export { LearningMiniApp, getLearningTemplateIds, isLearningTemplate };
+//# sourceMappingURL=LearningMiniApp.js.map

package/dist/ui/LearningMiniApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningMiniApp.js","names":["TEMPLATE_TO_TRACK: Record<LearningTemplateId, string>","TEMPLATE_TO_APP_TYPE: Record<\n  LearningTemplateId,\n  'gamified' | 'onboarding' | 'coaching'\n>"],"sources":["../../src/ui/LearningMiniApp.tsx"],"sourcesContent":["'use client';\n\nimport { useMemo } from 'react';\nimport { GamifiedMiniApp } from '@contractspec/example.learning-journey-ui-gamified';\nimport { OnboardingMiniApp } from '@contractspec/example.learning-journey-ui-onboarding';\nimport { CoachingMiniApp } from '@contractspec/example.learning-journey-ui-coaching';\nimport type { LearningView } from '@contractspec/example.learning-journey-ui-shared';\nimport { learningJourneyTracks } from '../tracks';\n\n/** Template IDs that map to learning journey tracks */\ntype LearningTemplateId =\n  | 'learning-journey-duo-drills'\n  | 'learning-journey-quest-challenges'\n  | 'learning-journey-studio-onboarding'\n  | 'learning-journey-platform-tour'\n  | 'learning-journey-ambient-coach'\n  | 'learning-journey-crm-onboarding';\n\n/** Map template IDs to track IDs */\nconst TEMPLATE_TO_TRACK: Record<LearningTemplateId, string> = {\n  'learning-journey-duo-drills': 'drills_language_basics',\n  'learning-journey-quest-challenges': 'money_reset_7day',\n  'learning-journey-studio-onboarding': 'studio_getting_started',\n  'learning-journey-platform-tour': 'platform_tour',\n  'learning-journey-ambient-coach': 'money_ambient_coach',\n  'learning-journey-crm-onboarding': 'crm_first_win',\n};\n\n/** Map template IDs to mini-app type */\nconst TEMPLATE_TO_APP_TYPE: Record<\n  LearningTemplateId,\n  'gamified' | 'onboarding' | 'coaching'\n> = {\n  'learning-journey-duo-drills': 'gamified',\n  'learning-journey-quest-challenges': 'gamified',\n  'learning-journey-studio-onboarding': 'onboarding',\n  'learning-journey-platform-tour': 'onboarding',\n  'learning-journey-ambient-coach': 'coaching',\n  'learning-journey-crm-onboarding': 'coaching',\n};\n\ninterface LearningMiniAppProps {\n  templateId: string;\n  initialView?: LearningView;\n  onViewChange?: (view: LearningView) => void;\n}\n\n/** Router component that picks the correct mini-app based on template ID */\nexport function LearningMiniApp({\n  templateId,\n  initialView = 'overview',\n  onViewChange,\n}: LearningMiniAppProps) {\n  // Find the track for this template\n  const track = useMemo(() => {\n    const trackId = TEMPLATE_TO_TRACK[templateId as LearningTemplateId];\n    if (!trackId) return null;\n    return learningJourneyTracks.find((t) => t.id === trackId);\n  }, [templateId]);\n\n  // Determine app type\n  const appType = TEMPLATE_TO_APP_TYPE[templateId as LearningTemplateId];\n\n  if (!track) {\n    return (\n      <div className=\"rounded-lg border border-amber-500/50 bg-amber-500/10 p-6 text-center\">\n        <p className=\"text-amber-500\">\n          Unknown learning template: {templateId}\n        </p>\n      </div>\n    );\n  }\n\n  // Render the appropriate mini-app\n  switch (appType) {\n    case 'gamified':\n      return (\n        <GamifiedMiniApp\n          track={track}\n          initialView={initialView}\n          onViewChange={onViewChange}\n        />\n      );\n    case 'onboarding':\n      return (\n        <OnboardingMiniApp\n          track={track}\n          initialView={initialView}\n          onViewChange={onViewChange}\n        />\n      );\n    case 'coaching':\n      return (\n        <CoachingMiniApp\n          track={track}\n          initialView={initialView}\n          onViewChange={onViewChange}\n        />\n      );\n    default:\n      return (\n        <div className=\"rounded-lg border border-red-500/50 bg-red-500/10 p-6 text-center\">\n          <p className=\"text-red-500\">\n            Unknown app type for template: {templateId}\n          </p>\n        </div>\n      );\n  }\n}\n\n/** Check if a template ID is a learning journey template */\nexport function isLearningTemplate(\n  templateId: string\n): templateId is LearningTemplateId {\n  return templateId in TEMPLATE_TO_TRACK;\n}\n\n/** Get all learning template IDs */\nexport function getLearningTemplateIds(): LearningTemplateId[] {\n  return Object.keys(TEMPLATE_TO_TRACK) as LearningTemplateId[];\n}\n"],"mappings":";;;;;;;;;;;AAmBA,MAAMA,oBAAwD;CAC5D,+BAA+B;CAC/B,qCAAqC;CACrC,sCAAsC;CACtC,kCAAkC;CAClC,kCAAkC;CAClC,mCAAmC;CACpC;;AAGD,MAAMC,uBAGF;CACF,+BAA+B;CAC/B,qCAAqC;CACrC,sCAAsC;CACtC,kCAAkC;CAClC,kCAAkC;CAClC,mCAAmC;CACpC;;AASD,SAAgB,gBAAgB,EAC9B,YACA,cAAc,YACd,gBACuB;CAEvB,MAAM,QAAQ,cAAc;EAC1B,MAAM,UAAU,kBAAkB;AAClC,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO,sBAAsB,MAAM,MAAM,EAAE,OAAO,QAAQ;IACzD,CAAC,WAAW,CAAC;CAGhB,MAAM,UAAU,qBAAqB;AAErC,KAAI,CAAC,MACH,QACE,oBAAC;EAAI,WAAU;YACb,qBAAC;GAAE,WAAU;cAAiB,+BACA;IAC1B;GACA;AAKV,SAAQ,SAAR;EACE,KAAK,WACH,QACE,oBAAC;GACQ;GACM;GACC;IACd;EAEN,KAAK,aACH,QACE,oBAAC;GACQ;GACM;GACC;IACd;EAEN,KAAK,WACH,QACE,oBAAC;GACQ;GACM;GACC;IACd;EAEN,QACE,QACE,oBAAC;GAAI,WAAU;aACb,qBAAC;IAAE,WAAU;eAAe,mCACM;KAC9B;IACA;;;;AAMd,SAAgB,mBACd,YACkC;AAClC,QAAO,cAAc;;;AAIvB,SAAgB,yBAA+C;AAC7D,QAAO,OAAO,KAAK,kBAAkB"}

package/dist/ui/index.d.ts

@@ -0,0 +1,2 @@
+import { LearningMiniApp, getLearningTemplateIds, isLearningTemplate } from "./LearningMiniApp.js";
+export { LearningMiniApp, getLearningTemplateIds, isLearningTemplate };

package/dist/ui/index.js

@@ -0,0 +1,3 @@
+import { LearningMiniApp, getLearningTemplateIds, isLearningTemplate } from "./LearningMiniApp.js";
+
+export { LearningMiniApp, getLearningTemplateIds, isLearningTemplate };

package/example.ts

@@ -0,0 +1 @@
+export { default } from './src/example';

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@contractspec/example.learning-journey-registry",
+  "version": "1.44.0",
+  "description": "Registry that aggregates learning journey example tracks.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./api": "./dist/api.js",
+    "./api-types": "./dist/api-types.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/learning-journey-registry.docblock": "./dist/docs/learning-journey-registry.docblock.js",
+    "./example": "./dist/example.js",
+    "./learning-journey-registry.feature": "./dist/learning-journey-registry.feature.js",
+    "./presentations": "./dist/presentations/index.js",
+    "./progress-store": "./dist/progress-store.js",
+    "./tracks": "./dist/tracks.js",
+    "./ui": "./dist/ui/index.js",
+    "./ui/LearningMiniApp": "./dist/ui/LearningMiniApp.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "test": "bun test",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "dependencies": {
+    "@contractspec/lib.schema": "1.44.0",
+    "@contractspec/lib.contracts": "1.44.0",
+    "@contractspec/example.learning-journey-ambient-coach": "1.44.0",
+    "@contractspec/example.learning-journey-duo-drills": "1.44.0",
+    "@contractspec/example.learning-journey-crm-onboarding": "1.44.0",
+    "@contractspec/example.learning-journey-platform-tour": "1.44.0",
+    "@contractspec/example.learning-journey-quest-challenges": "1.44.0",
+    "@contractspec/example.learning-journey-studio-onboarding": "1.44.0",
+    "@contractspec/example.learning-journey-ui-shared": "1.44.0",
+    "@contractspec/example.learning-journey-ui-gamified": "1.44.0",
+    "@contractspec/example.learning-journey-ui-onboarding": "1.44.0",
+    "@contractspec/example.learning-journey-ui-coaching": "1.44.0",
+    "@contractspec/module.learning-journey": "1.44.0",
+    "react": "19.2.3"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.44.0",
+    "@contractspec/tool.typescript": "1.44.0",
+    "@types/react": "^19.1.6",
+    "tsdown": "^0.18.3",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3"
+  },
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./api": "./dist/api.js",
+      "./api-types": "./dist/api-types.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/learning-journey-registry.docblock": "./dist/docs/learning-journey-registry.docblock.js",
+      "./example": "./dist/example.js",
+      "./learning-journey-registry.feature": "./dist/learning-journey-registry.feature.js",
+      "./presentations": "./dist/presentations/index.js",
+      "./progress-store": "./dist/progress-store.js",
+      "./tracks": "./dist/tracks.js",
+      "./ui": "./dist/ui/index.js",
+      "./ui/LearningMiniApp": "./dist/ui/LearningMiniApp.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/learning-journey-registry"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/api-types.ts

@@ -0,0 +1,43 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+export interface LearningEvent {
+  name: string;
+  version?: number;
+  sourceModule?: string;
+  payload?: Record<string, unknown>;
+  occurredAt?: Date;
+  learnerId: string;
+  trackId?: string;
+}
+
+export type StepStatus = 'PENDING' | 'COMPLETED';
+
+export interface StepProgress {
+  id: string;
+  status: StepStatus;
+  xpEarned: number;
+  completedAt?: Date;
+  triggeringEvent?: string;
+  eventPayload?: Record<string, unknown>;
+  occurrences?: number;
+  counterStartedAt?: Date;
+  availableAt?: Date;
+  dueAt?: Date;
+  masteryCount?: number;
+}
+
+export interface TrackProgress {
+  learnerId: string;
+  trackId: string;
+  progress: number;
+  isCompleted: boolean;
+  xpEarned: number;
+  startedAt?: Date;
+  completedAt?: Date;
+  lastActivityAt?: Date;
+  steps: StepProgress[];
+}
+
+export type TrackResolver = (
+  trackId: string
+) => LearningJourneyTrackSpec | undefined;

package/src/api.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'bun:test';
+
+import { recordEvent, getProgress, listTracks } from './api';
+import { learningJourneyTracks } from './tracks';
+
+const learnerId = 'learner-1';
+
+describe('learning journey registry api', () => {
+  it('completes studio track and applies streak bonus', () => {
+    const track = learningJourneyTracks.find(
+      (t) => t.id === 'studio_getting_started'
+    );
+    expect(track).toBeDefined();
+
+    const events = [
+      { name: 'studio.template.instantiated' },
+      { name: 'spec.changed', payload: { scope: 'sandbox' } },
+      { name: 'regeneration.completed' },
+      { name: 'module.navigated', payload: { moduleId: 'canvas' } },
+      { name: 'studio.evolution.applied' },
+    ];
+
+    events.forEach((evt) =>
+      recordEvent({
+        ...evt,
+        learnerId,
+        occurredAt: new Date(),
+      })
+    );
+
+    const progress = getProgress('studio_getting_started', learnerId);
+    expect(progress).toBeDefined();
+    if (!progress) return;
+
+    expect(progress.isCompleted).toBeTrue();
+    expect(progress.progress).toBe(100);
+    // base xp: track totalXp (110) + completion bonus (25) + streak bonus (25)
+    expect(progress.xpEarned).toBeGreaterThanOrEqual(160);
+  });
+
+  it('lists tracks with empty progress for new learner', () => {
+    const result = listTracks('new-learner');
+    expect(result.tracks.length).toBeGreaterThan(0);
+    expect(result.progress.length).toBe(0);
+  });
+});

package/src/api.ts

@@ -0,0 +1,301 @@
+import { learningJourneyTracks } from './tracks';
+import type {
+  LearningJourneyTrackSpec,
+  StepAvailabilitySpec,
+  StepCompletionConditionSpec,
+} from '@contractspec/module.learning-journey/track-spec';
+import type { LearningEvent, StepProgress, TrackProgress } from './api-types';
+import {
+  getLearnerTracks,
+  getTrackResolver,
+  initProgress,
+} from './progress-store';
+
+const getTrack = getTrackResolver(learningJourneyTracks);
+
+const matchesFilter = (
+  filter: Record<string, unknown> | undefined,
+  payload: Record<string, unknown> | undefined
+): boolean => {
+  if (!filter) return true;
+  if (!payload) return false;
+  return Object.entries(filter).every(([key, value]) => payload[key] === value);
+};
+
+const matchesBaseEvent = (
+  condition: {
+    eventName: string;
+    eventVersion?: number;
+    sourceModule?: string;
+    payloadFilter?: Record<string, unknown>;
+  },
+  event: LearningEvent
+): boolean => {
+  if (condition.eventName !== event.name) return false;
+  if (condition.eventVersion !== undefined && event.version !== undefined) {
+    if (condition.eventVersion !== event.version) return false;
+  }
+  if (
+    condition.sourceModule &&
+    event.sourceModule &&
+    condition.sourceModule !== event.sourceModule
+  ) {
+    return false;
+  }
+  return matchesFilter(
+    condition.payloadFilter,
+    event.payload as Record<string, unknown> | undefined
+  );
+};
+
+const matchesCondition = (
+  condition: StepCompletionConditionSpec,
+  event: LearningEvent,
+  step: StepProgress,
+  trackStartedAt: Date | undefined
+): {
+  matched: boolean;
+  occurrences?: number;
+  masteryCount?: number;
+} => {
+  if (condition.kind === 'count') {
+    if (!matchesBaseEvent(condition, event)) return { matched: false };
+    const occurrences = (step.occurrences ?? 0) + 1;
+    const within =
+      condition.withinHours === undefined ||
+      Boolean(
+        trackStartedAt &&
+        event.occurredAt &&
+        (event.occurredAt.getTime() - trackStartedAt.getTime()) /
+          (1000 * 60 * 60) <=
+          condition.withinHours
+      );
+    return { matched: within && occurrences >= condition.atLeast, occurrences };
+  }
+
+  if (condition.kind === 'time_window') {
+    if (!matchesBaseEvent(condition, event)) return { matched: false };
+    if (
+      condition.withinHoursOfStart !== undefined &&
+      trackStartedAt &&
+      event.occurredAt
+    ) {
+      const hoursSinceStart =
+        (event.occurredAt.getTime() - trackStartedAt.getTime()) /
+        (1000 * 60 * 60);
+      if (hoursSinceStart > condition.withinHoursOfStart) {
+        return { matched: false };
+      }
+    }
+    return { matched: true };
+  }
+
+  if (condition.kind === 'srs_mastery') {
+    if (event.name !== condition.eventName) return { matched: false };
+    const payload = event.payload as Record<string, unknown> | undefined;
+    if (!matchesFilter(condition.payloadFilter, payload)) {
+      return { matched: false };
+    }
+    const skillKey = condition.skillIdField ?? 'skillId';
+    const masteryKey = condition.masteryField ?? 'mastery';
+    const skillId = payload?.[skillKey];
+    const masteryValue = payload?.[masteryKey];
+    if (skillId === undefined || masteryValue === undefined) {
+      return { matched: false };
+    }
+    if (typeof masteryValue !== 'number') return { matched: false };
+    if (masteryValue < condition.minimumMastery) return { matched: false };
+    const masteryCount = (step.masteryCount ?? 0) + 1;
+    const required = condition.requiredCount ?? 1;
+    return { matched: masteryCount >= required, masteryCount };
+  }
+
+  return { matched: matchesBaseEvent(condition, event) };
+};
+
+const getAvailability = (
+  availability: StepAvailabilitySpec | undefined,
+  startedAt: Date | undefined
+): { availableAt?: Date; dueAt?: Date } => {
+  if (!availability || !startedAt) return {};
+
+  const baseTime = startedAt.getTime();
+  let unlockTime = baseTime;
+
+  if (availability.unlockOnDay !== undefined) {
+    unlockTime =
+      baseTime + (availability.unlockOnDay - 1) * 24 * 60 * 60 * 1000;
+  }
+
+  if (availability.unlockAfterHours !== undefined) {
+    unlockTime = baseTime + availability.unlockAfterHours * 60 * 60 * 1000;
+  }
+
+  const availableAt = new Date(unlockTime);
+  const dueAt =
+    availability.dueWithinHours !== undefined
+      ? new Date(
+          availableAt.getTime() + availability.dueWithinHours * 60 * 60 * 1000
+        )
+      : undefined;
+
+  return { availableAt, dueAt };
+};
+
+const computeProgressPercent = (steps: StepProgress[]): number => {
+  const total = steps.length || 1;
+  const done = steps.filter((s) => s.status === 'COMPLETED').length;
+  return Math.round((done / total) * 100);
+};
+
+const applyTrackCompletionBonuses = (
+  track: LearningJourneyTrackSpec,
+  progress: TrackProgress
+) => {
+  if (progress.isCompleted) return progress;
+
+  const completedAt = new Date();
+  const startedAt = progress.startedAt ?? completedAt;
+  const hoursElapsed =
+    (completedAt.getTime() - startedAt.getTime()) / (1000 * 60 * 60);
+
+  let xpEarned = progress.xpEarned;
+  const { completionRewards, streakRule } = track;
+
+  if (completionRewards?.xpBonus) {
+    xpEarned += completionRewards.xpBonus;
+  }
+
+  if (
+    streakRule?.hoursWindow !== undefined &&
+    hoursElapsed <= streakRule.hoursWindow &&
+    streakRule.bonusXp
+  ) {
+    xpEarned += streakRule.bonusXp;
+  }
+
+  return {
+    ...progress,
+    xpEarned,
+    isCompleted: true,
+    completedAt,
+    lastActivityAt: completedAt,
+  };
+};
+
+export const listTracks = (learnerId?: string) => {
+  const progressMap = learnerId ? getLearnerTracks(learnerId) : undefined;
+  const progress =
+    learnerId && progressMap
+      ? Array.from(progressMap.values())
+      : ([] as TrackProgress[]);
+
+  return {
+    tracks: learningJourneyTracks,
+    progress,
+  };
+};
+
+export const getProgress = (trackId: string, learnerId: string) => {
+  const track = getTrack(trackId);
+  if (!track) return undefined;
+
+  const map = getLearnerTracks(learnerId);
+  const existing = map.get(trackId) ?? initProgress(learnerId, track);
+  map.set(trackId, existing);
+  return existing;
+};
+
+export const recordEvent = (event: LearningEvent) => {
+  const targets =
+    event.trackId !== undefined
+      ? learningJourneyTracks.filter((t) => t.id === event.trackId)
+      : learningJourneyTracks;
+
+  const updated: TrackProgress[] = [];
+  const eventTime = event.occurredAt ?? new Date();
+
+  for (const track of targets) {
+    const map = getLearnerTracks(event.learnerId);
+    const current = map.get(track.id) ?? initProgress(event.learnerId, track);
+    const startedAt = current.startedAt ?? eventTime;
+
+    let changed = current.startedAt === undefined;
+    const steps: StepProgress[] = current.steps.map((step) => {
+      if (step.status === 'COMPLETED') return step;
+
+      const spec = track.steps.find((s) => s.id === step.id);
+      if (!spec) return step;
+
+      const { availableAt, dueAt } = getAvailability(
+        spec.availability,
+        startedAt
+      );
+      if (availableAt && eventTime < availableAt) {
+        return { ...step, availableAt, dueAt };
+      }
+      if (dueAt && eventTime > dueAt) {
+        // keep pending but note deadlines
+        return { ...step, availableAt, dueAt };
+      }
+
+      const result = matchesCondition(spec.completion, event, step, startedAt);
+
+      if (result.matched) {
+        changed = true;
+        return {
+          ...step,
+          status: 'COMPLETED',
+          xpEarned: spec.xpReward ?? 0,
+          completedAt: eventTime,
+          triggeringEvent: event.name,
+          eventPayload: event.payload,
+          occurrences: result.occurrences ?? step.occurrences,
+          masteryCount: result.masteryCount ?? step.masteryCount,
+          availableAt,
+          dueAt,
+        };
+      }
+
+      if (
+        result.occurrences !== undefined ||
+        result.masteryCount !== undefined
+      ) {
+        changed = true;
+      }
+
+      return {
+        ...step,
+        occurrences: result.occurrences ?? step.occurrences,
+        masteryCount: result.masteryCount ?? step.masteryCount,
+        availableAt,
+        dueAt,
+      };
+    });
+
+    if (!changed) {
+      continue;
+    }
+
+    const xpEarned =
+      steps.reduce((sum, s) => sum + s.xpEarned, 0) + (track.totalXp ?? 0);
+    let progress: TrackProgress = {
+      ...current,
+      steps,
+      xpEarned,
+      startedAt,
+      lastActivityAt: eventTime,
+      progress: computeProgressPercent(steps),
+    };
+
+    const allDone = steps.every((s) => s.status === 'COMPLETED');
+    if (allDone) {
+      progress = applyTrackCompletionBonuses(track, progress);
+    }
+
+    map.set(track.id, progress);
+    updated.push(progress);
+  }
+
+  return updated;
+};

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './learning-journey-registry.docblock';