@lxpack/validators 0.1.1 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![License](https://img.shields.io/github/license/eddiethedean/lxpack)](https://github.com/eddiethedean/lxpack/blob/main/LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 
-Zod schemas and filesystem validation for LXPack course manifests.
+Zod schemas and filesystem validation for LXPack course manifests — including flow, variables, and component lessons (v0.2.0).
 
 Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime.
 
@@ -14,6 +14,7 @@ Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learni
 | CLI | [`@lxpack/cli`](../cli/README.md) |
 | Packaging | [`@lxpack/scorm`](../scorm/README.md) |
 | Runtime | [`@lxpack/runtime`](../runtime/README.md) |
+| Components | [`@lxpack/components`](../components/README.md) |
 
 ## Install
 
@@ -44,7 +45,9 @@ if (!result.valid) {
   const { manifest } = result;
   const bundle = await buildRuntimeAssessmentBundle("/path/to/my-course", manifest);
   // bundle.assessments — learner-facing questions (no correct flags)
-  // bundle.answerKeys — scoring keys for the runtime (embedded at build time)
+  // bundle.answerKeys — scoring keys for the runtime
+  // bundle.configs — maxAttempts, shuffleChoices, showFeedback per assessment
+  // bundle.feedback — questionId → explanation text for feedback modes
 }
 ```
 
@@ -65,6 +68,14 @@ if (Array.isArray(loaded)) {
 const parsed = courseManifestSchema.safeParse(manifestObject);
 ```
 
+### Flow validation
+
+```ts
+import { validateFlow, detectFlowCycles, collectActivityIds } from "@lxpack/validators";
+```
+
+`validateCourse` runs flow checks when `manifest.flow` is present: valid `goto` targets, known condition shapes, and cycle detection.
+
 ### Safe path resolution
 
 ```ts
@@ -78,34 +89,43 @@ isPathContained(courseDir, abs); // true if inside course root
 
 | Export | Description |
 |--------|-------------|
-| `validateCourse(dir)` | Parse `course.yaml`, validate schema, check files, symlink containment |
+| `validateCourse(dir)` | Parse `course.yaml`, validate schema, flow, files, symlink containment |
 | `loadManifest(courseDir)` | Load and parse `course.yaml` |
-| `buildRuntimeAssessmentBundle(dir, manifest)` | Load assessments; split learner view vs answer keys |
-| `toLearnerAssessment(assessment)` | Strip `correct` / `explanation` from one assessment |
+| `buildRuntimeAssessmentBundle(dir, manifest)` | Load assessments; split learner view, keys, configs, feedback |
+| `toLearnerAssessment(assessment)` | Strip `correct` from choices; extract config and feedback maps |
+| `validateFlow(manifest)` | Flow rule and target validation |
+| `detectFlowCycles(flow)` | Cycle detection for branching graphs |
+| `collectActivityIds(manifest)` | Lesson and assessment IDs for flow targets |
+| `conditionSchema`, `flowRuleSchema` | Zod schemas for flow conditions and rules |
+| `BUILTIN_COMPONENT_IDS`, `isBuiltinComponentId` | Allowed built-in component lesson IDs |
 | `resolveCoursePath(dir, relativePath)` | Resolve a path safely inside the course directory |
 | `isPathContained(root, target)` | Whether `target` stays under `root` |
 | `courseManifestSchema` | Zod schema for the full course manifest |
-| `lessonSchema`, `assessmentSchema`, … | Strict sub-schemas for manifest sections |
-| `CourseManifest`, `Lesson`, `Assessment`, `LearnerAssessment`, `RuntimeAssessmentBundle` | TypeScript types |
+| `lessonSchema`, `assessmentSchema`, `variableDefSchema`, … | Strict sub-schemas |
+| `CourseManifest`, `Lesson`, `Assessment`, `FlowRule`, `VariableDef`, `RuntimeAssessmentBundle` | TypeScript types |
 
 ## What gets validated
 
-- Manifest shape (lessons, assessments, tracking rules)
-- Lesson types: `markdown` (`file`) and `html` (`path`)
-- Assessment YAML: strict MCQ schemas (`correct` on exactly one choice per question)
+- Manifest shape: lessons, assessments, optional `variables` and `flow`, tracking rules
+- Lesson types: `markdown` (`file`), `html` (`path`), `component` (`component` + optional `props`)
+- Component IDs: built-in IDs or course overrides under `components/<id>/`
+- Flow rules: condition grammar, `goto` targets that reference known activity IDs, acyclic flow (warnings for cycles)
+- Assessment YAML: strict MCQ schemas; optional `maxAttempts`, `shuffleChoices`, `showFeedback`; `explanation` per question
 - Duplicate lesson IDs
 - Path containment — referenced files must stay inside the course directory (including via symlinks)
-- On-disk assets: files exist and assessments paths are regular files
+- On-disk assets: files exist and assessment paths are regular files
 
 ## Assessment packaging
 
 Author assessments live as YAML under `assessments/` in the course repo. At build/preview time:
 
 1. `buildRuntimeAssessmentBundle()` reads each assessment file.
-2. **Learner payload** — questions and choices without `correct` or `explanation`.
+2. **Learner payload** — questions and choices without `correct` flags.
 3. **Answer keys** — `questionId → choiceId` map for scoring.
+4. **Configs** — per-assessment quiz behavior (`maxAttempts`, `shuffleChoices`, `showFeedback`).
+5. **Feedback** — `questionId → explanation` for immediate/end feedback (not shipped as separate files).
 
-The CLI and [`@lxpack/scorm`](../scorm/README.md) embed both in the HTML config JSON. Exported ZIPs **do not** include `assessments/` files, so answer keys are not fetchable as static assets.
+The CLI and [`@lxpack/scorm`](../scorm/README.md) embed all of this in the HTML config JSON. Exported ZIPs **do not** include `assessments/` files, so answer keys are not fetchable as static assets.
 
 ## Development
 
@@ -120,6 +140,8 @@ pnpm --filter @lxpack/validators typecheck
 ## Links
 
 - [LXPack repository](https://github.com/eddiethedean/lxpack)
+- [Documentation index](https://github.com/eddiethedean/lxpack/blob/main/docs/README.md)
+- [Technical specification](https://github.com/eddiethedean/lxpack/blob/main/docs/SPEC.md)
 - [Changelog](https://github.com/eddiethedean/lxpack/blob/main/CHANGELOG.md)
 
 ## License

package/dist/index.d.ts

@@ -1,5 +1,35 @@
 import { z } from 'zod';
 
+type Condition = {
+    variable: {
+        eq: [string, string | number | boolean];
+    };
+} | {
+    assessment: {
+        passed: string;
+    };
+} | {
+    interaction: {
+        done: string;
+    };
+} | {
+    all: Condition[];
+} | {
+    any: Condition[];
+};
+declare const conditionSchema: z.ZodType<Condition>;
+declare const flowRuleSchema: z.ZodObject<{
+    when: z.ZodType<Condition, z.ZodTypeDef, Condition>;
+    goto: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    when: Condition;
+    goto: string;
+}, {
+    when: Condition;
+    goto: string;
+}>;
+type FlowRule = z.infer<typeof flowRuleSchema>;
+
 declare const assessmentQuestionSchema: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
     prompt: z.ZodString;
@@ -60,13 +90,13 @@ declare const markdownLessonSchema: z.ZodObject<{
     file: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    id: string;
     type: "markdown";
+    id: string;
     file: string;
     title?: string | undefined;
 }, {
-    id: string;
     type: "markdown";
+    id: string;
     file: string;
     title?: string | undefined;
 }>;
@@ -76,29 +106,48 @@ declare const htmlLessonSchema: z.ZodObject<{
     path: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    id: string;
     path: string;
     type: "html";
+    id: string;
     title?: string | undefined;
 }, {
-    id: string;
     path: string;
     type: "html";
+    id: string;
     title?: string | undefined;
 }>;
+declare const componentLessonSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"component">;
+    component: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    title: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "component";
+    id: string;
+    component: string;
+    title?: string | undefined;
+    props?: Record<string, unknown> | undefined;
+}, {
+    type: "component";
+    id: string;
+    component: string;
+    title?: string | undefined;
+    props?: Record<string, unknown> | undefined;
+}>;
 declare const lessonSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     id: z.ZodString;
     type: z.ZodLiteral<"markdown">;
     file: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    id: string;
     type: "markdown";
+    id: string;
     file: string;
     title?: string | undefined;
 }, {
-    id: string;
     type: "markdown";
+    id: string;
     file: string;
     title?: string | undefined;
 }>, z.ZodObject<{
@@ -107,20 +156,42 @@ declare const lessonSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     path: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    id: string;
     path: string;
     type: "html";
+    id: string;
     title?: string | undefined;
 }, {
-    id: string;
     path: string;
     type: "html";
+    id: string;
     title?: string | undefined;
+}>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"component">;
+    component: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    title: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "component";
+    id: string;
+    component: string;
+    title?: string | undefined;
+    props?: Record<string, unknown> | undefined;
+}, {
+    type: "component";
+    id: string;
+    component: string;
+    title?: string | undefined;
+    props?: Record<string, unknown> | undefined;
 }>]>;
+declare const showFeedbackSchema: z.ZodDefault<z.ZodEnum<["immediate", "end", "never"]>>;
 declare const assessmentSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     passingScore: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodOptional<z.ZodNumber>;
+    shuffleChoices: z.ZodOptional<z.ZodBoolean>;
+    showFeedback: z.ZodOptional<z.ZodDefault<z.ZodEnum<["immediate", "end", "never"]>>>;
     questions: z.ZodArray<z.ZodEffects<z.ZodObject<{
         id: z.ZodString;
         prompt: z.ZodString;
@@ -189,6 +260,9 @@ declare const assessmentSchema: z.ZodObject<{
         explanation?: string | undefined;
     }[];
     title?: string | undefined;
+    maxAttempts?: number | undefined;
+    shuffleChoices?: boolean | undefined;
+    showFeedback?: "never" | "immediate" | "end" | undefined;
 }, {
     id: string;
     questions: {
@@ -203,6 +277,9 @@ declare const assessmentSchema: z.ZodObject<{
     }[];
     title?: string | undefined;
     passingScore?: number | undefined;
+    maxAttempts?: number | undefined;
+    shuffleChoices?: boolean | undefined;
+    showFeedback?: "never" | "immediate" | "end" | undefined;
 }>;
 declare const assessmentRefSchema: z.ZodObject<{
     id: z.ZodString;
@@ -214,6 +291,16 @@ declare const assessmentRefSchema: z.ZodObject<{
     id: string;
     file: string;
 }>;
+declare const variableDefSchema: z.ZodObject<{
+    default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    type: z.ZodOptional<z.ZodEnum<["string", "number", "boolean"]>>;
+}, "strict", z.ZodTypeAny, {
+    default: string | number | boolean;
+    type?: "string" | "number" | "boolean" | undefined;
+}, {
+    default: string | number | boolean;
+    type?: "string" | "number" | "boolean" | undefined;
+}>;
 declare const trackingSchema: z.ZodOptional<z.ZodObject<{
     completion: z.ZodOptional<z.ZodObject<{
         threshold: z.ZodDefault<z.ZodNumber>;
@@ -238,6 +325,7 @@ declare const runtimeConfigSchema: z.ZodOptional<z.ZodObject<{
 }, {
     theme?: string | undefined;
 }>>;
+
 declare const courseManifestSchema: z.ZodObject<{
     title: z.ZodString;
     version: z.ZodString;
@@ -266,19 +354,39 @@ declare const courseManifestSchema: z.ZodObject<{
             threshold?: number | undefined;
         } | undefined;
     }>>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        type: z.ZodOptional<z.ZodEnum<["string", "number", "boolean"]>>;
+    }, "strict", z.ZodTypeAny, {
+        default: string | number | boolean;
+        type?: "string" | "number" | "boolean" | undefined;
+    }, {
+        default: string | number | boolean;
+        type?: "string" | "number" | "boolean" | undefined;
+    }>>>;
+    flow: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        when: z.ZodType<Condition, z.ZodTypeDef, Condition>;
+        goto: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        when: Condition;
+        goto: string;
+    }, {
+        when: Condition;
+        goto: string;
+    }>, "many">>;
     lessons: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         id: z.ZodString;
         type: z.ZodLiteral<"markdown">;
         file: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
-        id: string;
         type: "markdown";
+        id: string;
         file: string;
         title?: string | undefined;
     }, {
-        id: string;
         type: "markdown";
+        id: string;
         file: string;
         title?: string | undefined;
     }>, z.ZodObject<{
@@ -287,15 +395,33 @@ declare const courseManifestSchema: z.ZodObject<{
         path: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
-        id: string;
         path: string;
         type: "html";
+        id: string;
         title?: string | undefined;
     }, {
-        id: string;
         path: string;
         type: "html";
+        id: string;
+        title?: string | undefined;
+    }>, z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"component">;
+        component: z.ZodString;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        type: "component";
+        id: string;
+        component: string;
+        title?: string | undefined;
+        props?: Record<string, unknown> | undefined;
+    }, {
+        type: "component";
+        id: string;
+        component: string;
         title?: string | undefined;
+        props?: Record<string, unknown> | undefined;
     }>]>, "many">;
     assessments: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -311,15 +437,21 @@ declare const courseManifestSchema: z.ZodObject<{
     title: string;
     version: string;
     lessons: ({
-        id: string;
         type: "markdown";
+        id: string;
         file: string;
         title?: string | undefined;
     } | {
-        id: string;
         path: string;
         type: "html";
+        id: string;
         title?: string | undefined;
+    } | {
+        type: "component";
+        id: string;
+        component: string;
+        title?: string | undefined;
+        props?: Record<string, unknown> | undefined;
     })[];
     description?: string | undefined;
     runtime?: {
@@ -330,6 +462,14 @@ declare const courseManifestSchema: z.ZodObject<{
             threshold: number;
         } | undefined;
     } | undefined;
+    variables?: Record<string, {
+        default: string | number | boolean;
+        type?: "string" | "number" | "boolean" | undefined;
+    }> | undefined;
+    flow?: {
+        when: Condition;
+        goto: string;
+    }[] | undefined;
     assessments?: {
         id: string;
         file: string;
@@ -338,15 +478,21 @@ declare const courseManifestSchema: z.ZodObject<{
     title: string;
     version: string;
     lessons: ({
-        id: string;
         type: "markdown";
+        id: string;
         file: string;
         title?: string | undefined;
     } | {
-        id: string;
         path: string;
         type: "html";
+        id: string;
+        title?: string | undefined;
+    } | {
+        type: "component";
+        id: string;
+        component: string;
         title?: string | undefined;
+        props?: Record<string, unknown> | undefined;
     })[];
     description?: string | undefined;
     runtime?: {
@@ -357,6 +503,14 @@ declare const courseManifestSchema: z.ZodObject<{
             threshold?: number | undefined;
         } | undefined;
     } | undefined;
+    variables?: Record<string, {
+        default: string | number | boolean;
+        type?: "string" | "number" | "boolean" | undefined;
+    }> | undefined;
+    flow?: {
+        when: Condition;
+        goto: string;
+    }[] | undefined;
     assessments?: {
         id: string;
         file: string;
@@ -366,6 +520,14 @@ type CourseManifest = z.infer<typeof courseManifestSchema>;
 type Lesson = z.infer<typeof lessonSchema>;
 type Assessment = z.infer<typeof assessmentSchema>;
 type AssessmentRef = z.infer<typeof assessmentRefSchema>;
+type VariableDef = z.infer<typeof variableDefSchema>;
+type ComponentLesson = z.infer<typeof componentLessonSchema>;
+type ShowFeedback = z.infer<typeof showFeedbackSchema>;
+
+/** Built-in component ids shipped in @lxpack/components */
+declare const BUILTIN_COMPONENT_IDS: readonly ["callout", "image-card", "checklist"];
+type BuiltinComponentId = (typeof BUILTIN_COMPONENT_IDS)[number];
+declare function isBuiltinComponentId(id: string): id is BuiltinComponentId;
 
 declare function formatErrorMessage(err: unknown): string;
 declare function formatIssuePath(path: PropertyKey[]): string;
@@ -399,6 +561,11 @@ declare function loadManifest(courseDir: string): Promise<{
 } | ValidationIssue[]>;
 declare function validateCourse(courseDir: string): Promise<ValidationResult>;
 
+declare function collectActivityIds(manifest: CourseManifest): Set<string>;
+declare function validateFlow(manifest: CourseManifest): ValidationIssue[];
+/** Detect simple goto cycles (same-target chains). */
+declare function detectFlowCycles(flow: FlowRule[]): string[];
+
 interface LearnerChoice {
     id: string;
     text: string;
@@ -414,14 +581,26 @@ interface LearnerAssessment {
     passingScore: number;
     questions: LearnerQuestion[];
 }
+interface AssessmentRuntimeConfig {
+    maxAttempts: number;
+    shuffleChoices: boolean;
+    showFeedback: ShowFeedback;
+}
+interface QuestionFeedback {
+    [questionId: string]: string | undefined;
+}
 interface RuntimeAssessmentBundle {
     assessments: Record<string, LearnerAssessment>;
     answerKeys: Record<string, Record<string, string>>;
+    configs: Record<string, AssessmentRuntimeConfig>;
+    feedback: Record<string, QuestionFeedback>;
 }
 declare function toLearnerAssessment(assessment: Assessment): {
     learner: LearnerAssessment;
     answerKey: Record<string, string>;
+    config: AssessmentRuntimeConfig;
+    feedback: QuestionFeedback;
 };
 declare function buildRuntimeAssessmentBundle(courseDir: string, manifest: CourseManifest): Promise<RuntimeAssessmentBundle>;
 
-export { type Assessment, type AssessmentRef, type CourseManifest, type LearnerAssessment, type LearnerChoice, type LearnerQuestion, type Lesson, type RuntimeAssessmentBundle, type ValidationIssue, type ValidationResult, assertResolvedPathContained, assessmentQuestionSchema, assessmentRefSchema, assessmentSchema, buildRuntimeAssessmentBundle, courseManifestSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, isPathContained, lessonSchema, loadManifest, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, toLearnerAssessment, trackingSchema, validateCourse };
+export { type Assessment, type AssessmentRef, type AssessmentRuntimeConfig, BUILTIN_COMPONENT_IDS, type BuiltinComponentId, type ComponentLesson, type Condition, type CourseManifest, type FlowRule, type LearnerAssessment, type LearnerChoice, type LearnerQuestion, type Lesson, type QuestionFeedback, type RuntimeAssessmentBundle, type ShowFeedback, type ValidationIssue, type ValidationResult, type VariableDef, assertResolvedPathContained, assessmentQuestionSchema, assessmentRefSchema, assessmentSchema, buildRuntimeAssessmentBundle, collectActivityIds, componentLessonSchema, conditionSchema, courseManifestSchema, detectFlowCycles, flowRuleSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, isBuiltinComponentId, isPathContained, lessonSchema, loadManifest, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, showFeedbackSchema, toLearnerAssessment, trackingSchema, validateCourse, validateFlow, variableDefSchema };

package/dist/index.js

@@ -1,69 +1,240 @@
 // src/schemas.ts
+import { z as z2 } from "zod";
+
+// src/conditions.ts
 import { z } from "zod";
-var choiceSchema = z.object({
-  id: z.string().min(1),
-  text: z.string().min(1),
-  correct: z.boolean().optional()
+var baseConditionSchema = z.union([
+  z.object({
+    variable: z.object({
+      eq: z.tuple([
+        z.string().min(1),
+        z.union([z.string(), z.number(), z.boolean()])
+      ])
+    })
+  }).strict(),
+  z.object({
+    assessment: z.object({
+      passed: z.string().min(1)
+    })
+  }).strict(),
+  z.object({
+    interaction: z.object({
+      done: z.string().min(1)
+    })
+  }).strict()
+]);
+var conditionSchema = z.lazy(
+  () => z.union([
+    ...baseConditionSchema.options,
+    z.object({ all: z.array(conditionSchema) }).strict(),
+    z.object({ any: z.array(conditionSchema) }).strict()
+  ])
+);
+var flowRuleSchema = z.object({
+  when: conditionSchema,
+  goto: z.string().min(1)
+}).strict();
+
+// src/schemas.ts
+var choiceSchema = z2.object({
+  id: z2.string().min(1),
+  text: z2.string().min(1),
+  correct: z2.boolean().optional()
 }).strict();
-var assessmentQuestionSchema = z.object({
-  id: z.string().min(1),
-  prompt: z.string().min(1),
-  choices: z.array(choiceSchema).min(1),
-  explanation: z.string().optional()
+var assessmentQuestionSchema = z2.object({
+  id: z2.string().min(1),
+  prompt: z2.string().min(1),
+  choices: z2.array(choiceSchema).min(1),
+  explanation: z2.string().optional()
 }).strict().superRefine((question, ctx) => {
   const correctCount = question.choices.filter((c) => c.correct === true).length;
   if (correctCount !== 1) {
     ctx.addIssue({
-      code: z.ZodIssueCode.custom,
+      code: z2.ZodIssueCode.custom,
       message: "Each question must have exactly one correct choice",
       path: ["choices"]
     });
   }
 });
-var markdownLessonSchema = z.object({
-  id: z.string().min(1),
-  type: z.literal("markdown"),
-  file: z.string().min(1),
-  title: z.string().optional()
+var markdownLessonSchema = z2.object({
+  id: z2.string().min(1),
+  type: z2.literal("markdown"),
+  file: z2.string().min(1),
+  title: z2.string().optional()
+}).strict();
+var htmlLessonSchema = z2.object({
+  id: z2.string().min(1),
+  type: z2.literal("html"),
+  path: z2.string().min(1),
+  title: z2.string().optional()
 }).strict();
-var htmlLessonSchema = z.object({
-  id: z.string().min(1),
-  type: z.literal("html"),
-  path: z.string().min(1),
-  title: z.string().optional()
+var componentLessonSchema = z2.object({
+  id: z2.string().min(1),
+  type: z2.literal("component"),
+  component: z2.string().min(1),
+  props: z2.record(z2.unknown()).optional(),
+  title: z2.string().optional()
 }).strict();
-var lessonSchema = z.discriminatedUnion("type", [
+var lessonSchema = z2.discriminatedUnion("type", [
   markdownLessonSchema,
-  htmlLessonSchema
+  htmlLessonSchema,
+  componentLessonSchema
 ]);
-var assessmentSchema = z.object({
-  id: z.string().min(1),
-  title: z.string().optional(),
-  passingScore: z.number().min(0).max(1).default(0.7),
-  questions: z.array(assessmentQuestionSchema).min(1)
+var showFeedbackSchema = z2.enum(["immediate", "end", "never"]).default("never");
+var assessmentSchema = z2.object({
+  id: z2.string().min(1),
+  title: z2.string().optional(),
+  passingScore: z2.number().min(0).max(1).default(0.7),
+  maxAttempts: z2.number().int().min(1).optional(),
+  shuffleChoices: z2.boolean().optional(),
+  showFeedback: showFeedbackSchema.optional(),
+  questions: z2.array(assessmentQuestionSchema).min(1)
+}).strict();
+var assessmentRefSchema = z2.object({
+  id: z2.string().min(1),
+  file: z2.string().min(1)
 }).strict();
-var assessmentRefSchema = z.object({
-  id: z.string().min(1),
-  file: z.string().min(1)
+var variableDefSchema = z2.object({
+  default: z2.union([z2.string(), z2.number(), z2.boolean()]),
+  type: z2.enum(["string", "number", "boolean"]).optional()
 }).strict();
-var trackingSchema = z.object({
-  completion: z.object({
-    threshold: z.number().min(0).max(1).default(0.9)
+var trackingSchema = z2.object({
+  completion: z2.object({
+    threshold: z2.number().min(0).max(1).default(0.9)
   }).strict().optional()
 }).strict().optional();
-var runtimeConfigSchema = z.object({
-  theme: z.string().default("modern")
+var runtimeConfigSchema = z2.object({
+  theme: z2.string().default("modern")
 }).strict().optional();
-var courseManifestSchema = z.object({
-  title: z.string().min(1),
-  version: z.string().min(1),
-  description: z.string().optional(),
+var courseManifestSchema = z2.object({
+  title: z2.string().min(1),
+  version: z2.string().min(1),
+  description: z2.string().optional(),
   runtime: runtimeConfigSchema,
   tracking: trackingSchema,
-  lessons: z.array(lessonSchema).min(1),
-  assessments: z.array(assessmentRefSchema).optional()
+  variables: z2.record(variableDefSchema).optional(),
+  flow: z2.array(flowRuleSchema).optional(),
+  lessons: z2.array(lessonSchema).min(1),
+  assessments: z2.array(assessmentRefSchema).optional()
 }).strict();
 
+// src/components.ts
+var BUILTIN_COMPONENT_IDS = [
+  "callout",
+  "image-card",
+  "checklist"
+];
+function isBuiltinComponentId(id) {
+  return BUILTIN_COMPONENT_IDS.includes(id);
+}
+
+// src/flow-validate.ts
+function collectActivityIds(manifest) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const lesson of manifest.lessons) {
+    ids.add(lesson.id);
+  }
+  for (const ref of manifest.assessments ?? []) {
+    ids.add(ref.id);
+  }
+  return ids;
+}
+function collectConditionRefs(condition, refs) {
+  if ("variable" in condition && condition.variable?.eq) {
+    refs.variables.add(condition.variable.eq[0]);
+  }
+  if ("assessment" in condition && condition.assessment?.passed) {
+    refs.assessments.add(condition.assessment.passed);
+  }
+  if ("interaction" in condition && condition.interaction?.done) {
+    refs.interactions.add(condition.interaction.done);
+  }
+  if ("all" in condition && condition.all) {
+    for (const c of condition.all) collectConditionRefs(c, refs);
+  }
+  if ("any" in condition && condition.any) {
+    for (const c of condition.any) collectConditionRefs(c, refs);
+  }
+}
+function validateFlow(manifest) {
+  const issues = [];
+  const flow = manifest.flow;
+  if (!flow?.length) return issues;
+  const activityIds = collectActivityIds(manifest);
+  const manifestVars = new Set(Object.keys(manifest.variables ?? {}));
+  flow.forEach((rule, index) => {
+    const path = `flow[${index}]`;
+    if (!activityIds.has(rule.goto)) {
+      issues.push({
+        path: `${path}.goto`,
+        message: `Unknown activity id: ${rule.goto}`,
+        severity: "error"
+      });
+    }
+    const refs = {
+      variables: /* @__PURE__ */ new Set(),
+      assessments: /* @__PURE__ */ new Set(),
+      interactions: /* @__PURE__ */ new Set()
+    };
+    collectConditionRefs(rule.when, refs);
+    for (const v of refs.variables) {
+      if (!manifestVars.has(v)) {
+        issues.push({
+          path: `${path}.when`,
+          message: `Unknown variable in condition: ${v}`,
+          severity: "error"
+        });
+      }
+    }
+    for (const a of refs.assessments) {
+      if (!activityIds.has(a)) {
+        issues.push({
+          path: `${path}.when`,
+          message: `Unknown assessment in condition: ${a}`,
+          severity: "error"
+        });
+      }
+    }
+    for (const i of refs.interactions) {
+      if (!activityIds.has(i)) {
+        issues.push({
+          path: `${path}.when`,
+          message: `Unknown interaction/lesson id in condition: ${i}`,
+          severity: "warning"
+        });
+      }
+    }
+  });
+  return issues;
+}
+function detectFlowCycles(flow) {
+  const gotoOf = /* @__PURE__ */ new Map();
+  flow.forEach((rule, i) => gotoOf.set(i, rule.goto));
+  const errors = [];
+  const visited = /* @__PURE__ */ new Set();
+  for (let start = 0; start < flow.length; start++) {
+    if (visited.has(start)) continue;
+    const chain = /* @__PURE__ */ new Set();
+    let i = start;
+    while (i !== void 0 && i < flow.length) {
+      const ruleIndex = i;
+      if (chain.has(ruleIndex)) {
+        errors.push(`Flow rule cycle detected involving flow[${ruleIndex}]`);
+        break;
+      }
+      if (visited.has(ruleIndex)) break;
+      chain.add(ruleIndex);
+      visited.add(ruleIndex);
+      const target = gotoOf.get(ruleIndex);
+      const nextIdx = flow.findIndex(
+        (_, idx) => idx > ruleIndex && flow[idx].goto === target
+      );
+      i = nextIdx >= 0 ? nextIdx : void 0;
+    }
+  }
+  return errors;
+}
+
 // src/validate.ts
 import { existsSync, realpathSync, statSync } from "fs";
 import { isAbsolute, join, relative, resolve } from "path";
@@ -185,6 +356,37 @@ async function validateCourse(courseDir) {
           severity: "error"
         });
       }
+    } else if (lesson.type === "component") {
+      if (!isBuiltinComponentId(lesson.component)) {
+        const resolved = resolveCoursePath(
+          resolvedDir,
+          join("components", lesson.component)
+        );
+        if (!resolved.ok) {
+          issues.push({
+            path: `lessons.${lesson.id}.component`,
+            message: resolved.message,
+            severity: "error"
+          });
+          continue;
+        }
+        if (!existsSync(resolved.path)) {
+          issues.push({
+            path: `lessons.${lesson.id}.component`,
+            message: `Unknown component "${lesson.component}" and no override at components/${lesson.component}`,
+            severity: "error"
+          });
+          continue;
+        }
+        const contained = assertResolvedPathContained(resolvedDir, resolved.path);
+        if (!contained.ok) {
+          issues.push({
+            path: `lessons.${lesson.id}.component`,
+            message: contained.message,
+            severity: "error"
+          });
+        }
+      }
     } else if (lesson.type === "html") {
       const resolved = resolveCoursePath(resolvedDir, lesson.path);
       if (!resolved.ok) {
@@ -339,6 +541,33 @@ async function validateCourse(courseDir) {
       });
     }
   }
+  issues.push(...validateFlow(manifest));
+  if (manifest.variables) {
+    for (const [name, def] of Object.entries(manifest.variables)) {
+      const t = def.type;
+      if (t === "string" && typeof def.default !== "string") {
+        issues.push({
+          path: `variables.${name}.default`,
+          message: "Default must be a string when type is string",
+          severity: "error"
+        });
+      }
+      if (t === "number" && typeof def.default !== "number") {
+        issues.push({
+          path: `variables.${name}.default`,
+          message: "Default must be a number when type is number",
+          severity: "error"
+        });
+      }
+      if (t === "boolean" && typeof def.default !== "boolean") {
+        issues.push({
+          path: `variables.${name}.default`,
+          message: "Default must be a boolean when type is boolean",
+          severity: "error"
+        });
+      }
+    }
+  }
   return {
     valid: issues.filter((i) => i.severity === "error").length === 0,
     manifest,
@@ -351,11 +580,15 @@ import { readFile as readFile2 } from "fs/promises";
 import { parse as parseYaml2 } from "yaml";
 function toLearnerAssessment(assessment) {
   const answerKey = {};
+  const feedback = {};
   const questions = assessment.questions.map((q) => {
     const correct = q.choices.find((c) => c.correct === true);
     if (correct) {
       answerKey[q.id] = correct.id;
     }
+    if (q.explanation) {
+      feedback[q.id] = q.explanation;
+    }
     return {
       id: q.id,
       prompt: q.prompt,
@@ -369,12 +602,20 @@ function toLearnerAssessment(assessment) {
       passingScore: assessment.passingScore,
       questions
     },
-    answerKey
+    answerKey,
+    config: {
+      maxAttempts: assessment.maxAttempts ?? 1,
+      shuffleChoices: assessment.shuffleChoices ?? false,
+      showFeedback: assessment.showFeedback ?? "never"
+    },
+    feedback
   };
 }
 async function buildRuntimeAssessmentBundle(courseDir, manifest) {
   const assessments = {};
   const answerKeys = {};
+  const configs = {};
+  const feedback = {};
   for (const ref of manifest.assessments ?? []) {
     const resolved = resolveCoursePath(courseDir, ref.file);
     if (!resolved.ok) {
@@ -393,29 +634,41 @@ async function buildRuntimeAssessmentBundle(courseDir, manifest) {
         `Assessment file id "${parsed.data.id}" does not match manifest ref "${ref.id}"`
       );
     }
-    const { learner, answerKey } = toLearnerAssessment(parsed.data);
-    assessments[ref.id] = learner;
-    answerKeys[ref.id] = answerKey;
+    const built = toLearnerAssessment(parsed.data);
+    assessments[ref.id] = built.learner;
+    answerKeys[ref.id] = built.answerKey;
+    configs[ref.id] = built.config;
+    feedback[ref.id] = built.feedback;
   }
-  return { assessments, answerKeys };
+  return { assessments, answerKeys, configs, feedback };
 }
 export {
+  BUILTIN_COMPONENT_IDS,
   assertResolvedPathContained,
   assessmentQuestionSchema,
   assessmentRefSchema,
   assessmentSchema,
   buildRuntimeAssessmentBundle,
+  collectActivityIds,
+  componentLessonSchema,
+  conditionSchema,
   courseManifestSchema,
+  detectFlowCycles,
+  flowRuleSchema,
   formatErrorMessage,
   formatIssuePath,
   htmlLessonSchema,
+  isBuiltinComponentId,
   isPathContained,
   lessonSchema,
   loadManifest,
   markdownLessonSchema,
   resolveCoursePath,
   runtimeConfigSchema,
+  showFeedbackSchema,
   toLearnerAssessment,
   trackingSchema,
-  validateCourse
+  validateCourse,
+  validateFlow,
+  variableDefSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lxpack/validators",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Course manifest validation for LXPack",
   "license": "Apache-2.0",
   "repository": {