@thanh01.pmt/curriculum-kit 1.4.17 → 1.4.20

package/dist/index.cjs

@@ -1597,10 +1597,91 @@ var slideProductionWorkflow_exports = {};
 __export(slideProductionWorkflow_exports, {
   GeneratedSlideArraySchema: () => exports.GeneratedSlideArraySchema,
   GeneratedSlideSchema: () => exports.GeneratedSlideSchema,
+  HybridBlueprintArraySchema: () => exports.HybridBlueprintArraySchema,
+  HybridBlueprintItemSchema: () => exports.HybridBlueprintItemSchema,
+  HybridDeckSlideArraySchema: () => exports.HybridDeckSlideArraySchema,
+  HybridDeckSlideSchema: () => exports.HybridDeckSlideSchema,
+  HybridPipelineError: () => exports.HybridPipelineError,
   SlideBlueprintArraySchema: () => exports.SlideBlueprintArraySchema,
   SlideBlueprintItemSchema: () => exports.SlideBlueprintItemSchema,
-  executeSlideProductionWorkflow: () => executeSlideProductionWorkflow
+  executeSlideProductionWorkflow: () => executeSlideProductionWorkflow,
+  extractJsonArray: () => extractJsonArray,
+  validateHybridDeckSlides: () => validateHybridDeckSlides
 });
+function extractJsonArray(raw) {
+  if (!raw) return { error: "empty response" };
+  let text = raw.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+  text = text.replace(/^```(?:json)?\s*/m, "").replace(/```\s*$/m, "").trim();
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start < 0 || end <= start) {
+    return {
+      error: "no JSON array span found",
+      head: text.slice(0, 300),
+      tail: text.slice(-300)
+    };
+  }
+  const span = text.slice(start, end + 1);
+  try {
+    return { value: JSON.parse(span) };
+  } catch {
+  }
+  try {
+    return { value: JSON.parse(jsonrepair.jsonrepair(span)) };
+  } catch (e) {
+    return {
+      error: "JSON.parse/jsonrepair failed: " + String(e?.message || e).slice(0, 120),
+      head: text.slice(0, 300),
+      tail: text.slice(-300)
+    };
+  }
+}
+function validateHybridDeckSlides(slides, blueprint) {
+  const v = [];
+  if (blueprint.length > 0 && slides.length !== blueprint.length) {
+    v.push(`slide count mismatch: got ${slides.length}, blueprint requires ${blueprint.length}`);
+  }
+  slides.forEach((s, i) => {
+    const n = i + 1;
+    const title = typeof s?.title === "string" ? s.title : "";
+    if (!title.trim()) v.push(`slide ${n}: missing/empty title`);
+    else if (title.length > 150) v.push(`slide ${n}: title too long (${title.length} chars, max 150) \u2014 repetition-loop guard`);
+    const notes = typeof s?.notes === "string" ? s.notes.trim() : "";
+    if (notes.length < 80) v.push(`slide ${n}: presenter notes missing or too short (${notes.length} chars, min 80)`);
+    const code = s?.slots?.code;
+    if (typeof code === "string") {
+      if (code.length > 6e3) v.push(`slide ${n}: code block too long (${code.length} chars, max 6000)`);
+      if (/\/\/\s*TODO|<CODE>|your code here/i.test(code)) v.push(`slide ${n}: placeholder code detected (TODO/<CODE>)`);
+    }
+  });
+  return v.slice(0, 10);
+}
+async function inferTextJson(schema, systemPrompt, userPrompt, options, label) {
+  const model = getAIModel(options.modelOptions);
+  try {
+    const { text, finishReason } = await ai.generateText({
+      model,
+      system: systemPrompt || void 0,
+      prompt: userPrompt,
+      maxOutputTokens: options.maxOutputTokens ?? 65536
+    });
+    const extracted = extractJsonArray(text);
+    if (!("value" in extracted) || extracted.value === void 0) {
+      console.warn(
+        `[SlideProductionWorkflow] ${label}: JSON extraction failed (${extracted.error}); finish=${finishReason}`,
+        extracted.head ? `head=${String(extracted.head).slice(0, 150)}` : ""
+      );
+      return null;
+    }
+    const validated = schema.safeParse(extracted.value);
+    if (validated.success) return validated.data;
+    console.warn(`[SlideProductionWorkflow] ${label}: output failed schema validation:`, validated.error?.message);
+    return null;
+  } catch (err) {
+    console.warn(`[SlideProductionWorkflow] ${label}: generateText failed:`, err?.message || err);
+    return null;
+  }
+}
 async function inferStructured(schema, systemPrompt, userPrompt, options, label) {
   try {
     const model = getAIModel(options.modelOptions);
@@ -1642,9 +1723,142 @@ async function inferStructured(schema, systemPrompt, userPrompt, options, label)
     return null;
   }
 }
+function normalizeBlueprintItems(items) {
+  return items.sort((a, b) => (a.slideIndex ?? 0) - (b.slideIndex ?? 0)).map((item, idx) => ({
+    slideIndex: idx + 1,
+    clusterId: item.clusterId ?? Math.floor(idx / 5) + 1,
+    clusterTitle: item.clusterTitle || "Cluster",
+    lessonPhase: item.lessonPhase || "Content",
+    layoutId: item.layoutId,
+    title: item.title,
+    pedagogicalGoal: item.pedagogicalGoal || "",
+    contentFocus: item.contentFocus || [],
+    codeSnippetIntent: item.codeSnippetIntent ?? void 0,
+    visualIntent: item.visualIntent ?? void 0
+  }));
+}
+function buildHybridDeckPrompts(params) {
+  const { lessonFlow, blueprint, skillPrompt, language, languageDirective, headingDirective } = params;
+  const blueprintText = JSON.stringify(
+    blueprint.map((s) => ({
+      slideIndex: s.slideIndex,
+      lessonPhase: s.lessonPhase,
+      layoutId: s.layoutId,
+      title: s.title,
+      pedagogicalGoal: s.pedagogicalGoal,
+      contentFocus: s.contentFocus,
+      codeSnippetIntent: s.codeSnippetIntent ?? void 0,
+      visualIntent: s.visualIntent ?? void 0
+    })),
+    null,
+    1
+  );
+  const phasesContent = lessonFlow.phases.length > 0 ? lessonFlow.phases.map((p) => `### ${p.phaseName}
+${p.content}`).join("\n\n") : lessonFlow.rawContent;
+  const systemPrompt = [
+    skillPrompt,
+    languageDirective,
+    headingDirective,
+    `
+### OPERATIONAL GROUND RULES (FULL-DECK AUTHORING):
+1. **EXACT COUNT: author EXACTLY ${blueprint.length} slide objects \u2014 ONE per blueprint item, SAME ORDER, SAME layoutId.** Do NOT merge, skip, reorder, or add slides.
+2. **ZERO ABBREVIATION / NO "// TODO"**: All code snippets MUST be real, fully authored, compilable code relevant to "${lessonFlow.lessonTitle}". Never write placeholders, stubs, or "<CODE>".
+3. **MANDATORY 3-PART PRESENTER NOTES ON EVERY SLIDE (120+ chars)**: SCRIPT (60-90s spoken talk track with an intuitive analogy), COLD CALL / CHECK (one targeted understanding question), SCAFFOLDING / GOTCHA (one common misconception or bug).
+4. Titles must be < 100 characters \u2014 never repeat or loop text.
+5. Output ONLY the JSON array. No prose, no markdown fences.
+`.trim()
+  ].filter(Boolean).join("\n\n");
+  const userPrompt = `
+### BLUEPRINT (${blueprint.length} slides \u2014 AUTHOR ALL OF THEM, in this exact order):
+${blueprintText}
+
+### LESSON GROUND TRUTH:
+- Lesson Title: "${lessonFlow.lessonTitle}"
+- Target Duration: ${lessonFlow.estimatedDuration}
+- Pedagogy: "${lessonFlow.pedagogicalModel.toUpperCase()}"
+- Language: "${language}"
+
+### LESSON PHASE CONTENT (SOURCE OF TRUTH FOR REAL CONTENT):
+${phasesContent.slice(0, 16e3)}
+
+---
+
+### OUTPUT:
+A single JSON array of exactly ${blueprint.length} slide objects:
+\`\`\`json
+[
+  {
+    "id": "slide-1",
+    "layoutId": "${blueprint[0]?.layoutId || "split-concept-code"}",
+    "title": "${blueprint[0]?.title || "Slide Title"}",
+    "slots": { "...layout-specific slots with REAL content..." },
+    "notes": "SCRIPT: ...\\nCOLD CALL: ...\\nSCAFFOLDING: ..."
+  }
+]
+\`\`\`
+`.trim();
+  return { systemPrompt, userPrompt };
+}
+async function runHybridPipeline(ctx) {
+  const { lessonFlow, blueprintPrompt, skillPrompt, language, languageDirective, headingDirective, maxRetries, options, onProgress } = ctx;
+  let blueprint = null;
+  for (let attempt = 1; attempt <= maxRetries && !blueprint; attempt++) {
+    onProgress?.("@illustrator", `[1/4] L\u1EADp D\xE0n \xFD Slides \u2014 hybrid blueprint (l\u1EA7n ${attempt}/${maxRetries})...`);
+    const parsed = await inferTextJson(exports.HybridBlueprintArraySchema, "", blueprintPrompt, options, `hybrid-blueprint#${attempt}`);
+    if (parsed && parsed.length > 0) {
+      blueprint = normalizeBlueprintItems(parsed);
+    } else if (attempt < maxRetries) {
+      onProgress?.("@illustrator", `\u26A0\uFE0F Hybrid blueprint l\u1EA7n ${attempt}/${maxRetries} l\u1ED7i \u2014 th\u1EED l\u1EA1i...`, { type: "warning" });
+    }
+  }
+  if (!blueprint || blueprint.length === 0) {
+    throw new exports.HybridPipelineError(`blueprint failed after ${maxRetries} attempts`);
+  }
+  onProgress?.("@illustrator", `[1/4] D\xE0n \xFD ${blueprint.length} slides ho\xE0n t\u1EA5t \u2014 chuy\u1EC3n sang authoring to\xE0n deck...`);
+  const { systemPrompt, userPrompt } = buildHybridDeckPrompts({
+    lessonFlow,
+    blueprint,
+    skillPrompt,
+    language,
+    languageDirective,
+    headingDirective
+  });
+  let slides = null;
+  let lastViolations = [];
+  for (let attempt = 1; attempt <= maxRetries && !slides; attempt++) {
+    onProgress?.("@illustrator", `[2/4] Sinh chi ti\u1EBFt to\xE0n b\u1ED9 ${blueprint.length} slides trong 1 l\u1EA7n g\u1ECDi (l\u1EA7n ${attempt}/${maxRetries})...`);
+    const feedback = attempt > 1 && lastViolations.length > 0 ? `
+
+### \u26A0\uFE0F PREVIOUS ATTEMPT REJECTED \u2014 fix these violations:
+${lastViolations.map((x) => "- " + x).join("\n")}
+Return exactly ${blueprint.length} slides, same order as the blueprint.` : "";
+    const parsed = await inferTextJson(exports.HybridDeckSlideArraySchema, systemPrompt, userPrompt + feedback, options, `hybrid-author#${attempt}`);
+    if (!parsed || parsed.length === 0) {
+      lastViolations = ["Output missing, empty, or not a valid JSON array of slide objects"];
+    } else {
+      const violations = validateHybridDeckSlides(parsed, blueprint);
+      if (violations.length === 0) {
+        slides = parsed;
+        break;
+      }
+      lastViolations = violations;
+    }
+    if (attempt < maxRetries) {
+      onProgress?.("@illustrator", `\u26A0\uFE0F Deck authoring l\u1EA7n ${attempt}/${maxRetries} vi ph\u1EA1m guardrails \u2014 retry v\u1EDBi corrective feedback...`, {
+        type: "warning",
+        violations: lastViolations
+      });
+    }
+  }
+  if (!slides) {
+    throw new exports.HybridPipelineError(
+      `deck authoring failed after ${maxRetries} attempts. Last violations: ${lastViolations.slice(0, 3).join("; ")}`
+    );
+  }
+  return { slides, blueprint };
+}
 async function executeSlideProductionWorkflow(options) {
   const {
-    lessonMarkdown,
     lessonCode,
     lessonTitle,
     targetSlideCount,
@@ -1655,6 +1869,7 @@ async function executeSlideProductionWorkflow(options) {
     maxRetries = 3,
     onProgress
   } = options;
+  const engineRequested = options.engine ?? "hybrid";
   let presentationKitSkills = null;
   let presentationKitCore = null;
   try {
@@ -1665,117 +1880,140 @@ async function executeSlideProductionWorkflow(options) {
     presentationKitCore = await import('@thanh01.pmt/presentation-kit');
   } catch {
   }
-  const countLabel = targetSlideCount ? `${targetSlideCount} ` : "h\u1EEFu c\u01A1 ";
-  onProgress?.("@illustrator", `[1/4] Ph\xE2n t\xEDch m\u1EA1ch b\xE0i gi\u1EA3ng LESSON & L\u1EADp D\xE0n \xFD ${countLabel}Slides...`);
-  const lessonFlow = parseLessonFlow(lessonMarkdown);
+  const lessonFlow = parseLessonFlow(options.lessonMarkdown);
   const getStylePreset = presentationKitSkills?.getStylePreset;
   const stylePreset = getStylePreset ? getStylePreset(stylePresetId) : { name: "Blue Professional" };
+  const skillPrompt = presentationKitSkills?.getFrontendSlidesSkillPrompt ? presentationKitSkills.getFrontendSlidesSkillPrompt({ stylePresetId }) : "";
   const blueprintPrompt = buildSlideBlueprintPrompt({
     lessonFlow,
     targetSlideCount,
     stylePresetName: stylePreset?.name || "Blue Professional"
   });
-  const blueprintItems = await pRetry__default.default(
-    async () => {
-      const items = await inferStructured(
-        exports.SlideBlueprintArraySchema,
-        "",
-        blueprintPrompt,
-        options,
-        "blueprint"
-      );
-      if (!items || items.length === 0) {
-        throw new Error("Blueprint generation returned empty or schema-invalid output");
-      }
-      return items.sort((a, b) => a.slideIndex - b.slideIndex).map((item, idx) => ({
-        ...item,
-        slideIndex: idx + 1,
-        clusterId: item.clusterId || Math.floor(idx / 5) + 1,
-        clusterTitle: item.clusterTitle || "Cluster",
-        lessonPhase: item.lessonPhase || "Content",
-        pedagogicalGoal: item.pedagogicalGoal || "",
-        contentFocus: item.contentFocus || []
-      }));
-    },
-    {
-      retries: maxRetries - 1,
-      onFailedAttempt: (err) => {
-        onProgress?.("@illustrator", `\u26A0\uFE0F Blueprint attempt ${err.attemptNumber}/${maxRetries} failed \u2014 retrying...`, {
-          type: "warning"
-        });
+  let blueprintItems;
+  let allGeneratedSlides;
+  let engineUsed = engineRequested;
+  const hybridResult = engineRequested === "hybrid" ? await runHybridPipeline({
+    lessonFlow,
+    blueprintPrompt,
+    skillPrompt,
+    language,
+    languageDirective,
+    headingDirective,
+    maxRetries,
+    options,
+    onProgress
+  }).catch((hybridErr) => {
+    console.warn(`[SlideProductionWorkflow] Hybrid engine failed: ${hybridErr?.message || hybridErr} \u2014 falling back to chunked pipeline.`);
+    onProgress?.("@illustrator", `\u26A0\uFE0F Hybrid engine l\u1ED7i \u2014 chuy\u1EC3n sang chunked pipeline (per-cluster)...`, { type: "warning" });
+    return null;
+  }) : null;
+  if (hybridResult) {
+    blueprintItems = hybridResult.blueprint;
+    allGeneratedSlides = hybridResult.slides.map((s, idx) => ({
+      id: s.id || `slide-${idx + 1}`,
+      layoutId: s.layoutId,
+      title: s.title,
+      slots: s.slots || {},
+      notes: s.notes || ""
+    }));
+  } else {
+    engineUsed = "chunked";
+    const countLabel = targetSlideCount ? `${targetSlideCount} ` : "h\u1EEFu c\u01A1 ";
+    onProgress?.("@illustrator", `[1/4] Ph\xE2n t\xEDch m\u1EA1ch b\xE0i gi\u1EA3ng LESSON & L\u1EADp D\xE0n \xFD ${countLabel}Slides...`);
+    blueprintItems = await pRetry__default.default(
+      async () => {
+        const items = await inferStructured(
+          exports.SlideBlueprintArraySchema,
+          "",
+          blueprintPrompt,
+          options,
+          "blueprint"
+        );
+        if (!items || items.length === 0) {
+          throw new Error("Blueprint generation returned empty or schema-invalid output");
+        }
+        return normalizeBlueprintItems(items);
+      },
+      {
+        retries: maxRetries - 1,
+        onFailedAttempt: (err) => {
+          onProgress?.("@illustrator", `\u26A0\uFE0F Blueprint attempt ${err.attemptNumber}/${maxRetries} failed \u2014 retrying...`, {
+            type: "warning"
+          });
+        }
       }
-    }
-  );
-  const clustersMap = /* @__PURE__ */ new Map();
-  for (const item of blueprintItems) {
-    const cId = item.clusterId || Math.floor((item.slideIndex - 1) / 5) + 1;
-    if (!clustersMap.has(cId)) clustersMap.set(cId, []);
-    clustersMap.get(cId).push(item);
-  }
-  const clusters = Array.from(clustersMap.entries()).sort(([a], [b]) => a - b);
-  const skillPrompt = presentationKitSkills?.getFrontendSlidesSkillPrompt ? presentationKitSkills.getFrontendSlidesSkillPrompt({ stylePresetId }) : "";
-  const allGeneratedSlides = [];
-  const failedClusters = [];
-  let clusterIdx = 0;
-  for (const [cId, clusterSlides] of clusters) {
-    clusterIdx++;
-    const clusterTitle = clusterSlides[0]?.clusterTitle || `Giai \u0111o\u1EA1n ${clusterIdx}`;
-    onProgress?.("@illustrator", `[2/4] Sinh chi ti\u1EBFt C\u1EE5m ${clusterIdx}/${clusters.length}: "${clusterTitle}" (${clusterSlides.length} slides)...`);
-    const clusterPhaseNames = new Set(clusterSlides.map((s) => s.lessonPhase.toLowerCase()));
-    const matchingPhases = lessonFlow.phases.filter((p) => clusterPhaseNames.has(p.phaseName.toLowerCase()));
-    const lessonExcerpt = matchingPhases.length > 0 ? matchingPhases.map((p) => `### ${p.phaseName}
+    );
+    const clustersMap = /* @__PURE__ */ new Map();
+    for (const item of blueprintItems) {
+      const cId = item.clusterId || Math.floor((item.slideIndex - 1) / 5) + 1;
+      if (!clustersMap.has(cId)) clustersMap.set(cId, []);
+      clustersMap.get(cId).push(item);
+    }
+    const clusters = Array.from(clustersMap.entries()).sort(([a], [b]) => a - b);
+    allGeneratedSlides = [];
+    const failedClusters = [];
+    let clusterIdx = 0;
+    for (const [cId, clusterSlides] of clusters) {
+      clusterIdx++;
+      const clusterTitle = clusterSlides[0]?.clusterTitle || `Giai \u0111o\u1EA1n ${clusterIdx}`;
+      onProgress?.("@illustrator", `[2/4] Sinh chi ti\u1EBFt C\u1EE5m ${clusterIdx}/${clusters.length}: "${clusterTitle}" (${clusterSlides.length} slides)...`);
+      const clusterPhaseNames = new Set(clusterSlides.map((s) => s.lessonPhase.toLowerCase()));
+      const matchingPhases = lessonFlow.phases.filter((p) => clusterPhaseNames.has(p.phaseName.toLowerCase()));
+      const lessonExcerpt = matchingPhases.length > 0 ? matchingPhases.map((p) => `### ${p.phaseName}
 ${p.content}`).join("\n\n") : lessonFlow.rawContent.slice(0, 3500);
-    const { systemPrompt, userPrompt } = buildSlideBatchPrompt({
-      clusterId: cId,
-      clusterTitle,
-      clusterSlides,
-      lessonFlow,
-      lessonExcerpt,
-      skillPrompt,
-      language,
-      languageDirective,
-      headingDirective
-    });
-    try {
-      const batchSlides = await pRetry__default.default(
-        async () => {
-          const slides = await inferStructured(
-            exports.GeneratedSlideArraySchema,
-            systemPrompt,
-            userPrompt,
-            options,
-            `cluster-${cId}`
-          );
-          if (!slides || slides.length === 0) {
-            throw new Error(`Cluster ${cId} returned empty or schema-invalid output`);
-          }
-          return slides;
-        },
-        {
-          retries: maxRetries - 1,
-          onFailedAttempt: (err) => {
-            onProgress?.("@illustrator", `\u26A0\uFE0F C\u1EE5m ${clusterIdx} l\u1EA7n ${err.attemptNumber}/${maxRetries} l\u1ED7i \u2014 retry ri\xEAng c\u1EE5m n\xE0y...`, {
-              type: "warning"
-            });
+      const { systemPrompt, userPrompt } = buildSlideBatchPrompt({
+        clusterId: cId,
+        clusterTitle,
+        clusterSlides,
+        lessonFlow,
+        lessonExcerpt,
+        skillPrompt,
+        language,
+        languageDirective,
+        headingDirective
+      });
+      try {
+        const batchSlides = await pRetry__default.default(
+          async () => {
+            const slides = await inferStructured(
+              exports.GeneratedSlideArraySchema,
+              systemPrompt,
+              userPrompt,
+              options,
+              `cluster-${cId}`
+            );
+            if (!slides || slides.length === 0) {
+              throw new Error(`Cluster ${cId} returned empty or schema-invalid output`);
+            }
+            return slides;
+          },
+          {
+            retries: maxRetries - 1,
+            onFailedAttempt: (err) => {
+              onProgress?.("@illustrator", `\u26A0\uFE0F C\u1EE5m ${clusterIdx} l\u1EA7n ${err.attemptNumber}/${maxRetries} l\u1ED7i \u2014 retry ri\xEAng c\u1EE5m n\xE0y...`, {
+                type: "warning"
+              });
+            }
           }
-        }
+        );
+        allGeneratedSlides.push(...batchSlides);
+      } catch (clusterErr) {
+        failedClusters.push(cId);
+        console.error(`[SlideProductionWorkflow] Cluster ${cId} permanently failed after ${maxRetries} attempts:`, clusterErr?.message || clusterErr);
+      }
+    }
+    if (failedClusters.length > 0) {
+      throw new Error(
+        `[SlideProductionWorkflow] Failed to generate ${failedClusters.length}/${clusters.length} cluster(s) (clusterId: ${failedClusters.join(", ")}) after ${maxRetries} attempts each. Aborting to prevent placeholder/degraded slide output. Review provider keys/model availability and retry.`
       );
-      allGeneratedSlides.push(...batchSlides);
-    } catch (clusterErr) {
-      failedClusters.push(cId);
-      console.error(`[SlideProductionWorkflow] Cluster ${cId} permanently failed after ${maxRetries} attempts:`, clusterErr?.message || clusterErr);
     }
   }
-  if (failedClusters.length > 0) {
-    throw new Error(
-      `[SlideProductionWorkflow] Failed to generate ${failedClusters.length}/${clusters.length} cluster(s) (clusterId: ${failedClusters.join(", ")}) after ${maxRetries} attempts each. Aborting to prevent placeholder/degraded slide output. Review provider keys/model availability and retry.`
-    );
-  }
   onProgress?.("@illustrator", `[3/4] Chu\u1EA9n h\xF3a b\u1ED1 c\u1EE5c v\xE0 bi\xEAn d\u1ECBch 1920\xD71080 Stage Deck (${allGeneratedSlides.length} slides)...`);
   const normalizer = presentationKitCore?.normalizeSlideSlots;
   const normalizedSlides = allGeneratedSlides.map((s, idx) => {
     const base = normalizer ? normalizer(s) : s;
     if (!base.id) base.id = `slide-${idx + 1}`;
+    if (!base.slots || typeof base.slots !== "object") base.slots = {};
     return base;
   });
   const deckJson = {
@@ -1785,16 +2023,19 @@ ${p.content}`).join("\n\n") : lessonFlow.rawContent.slice(0, 3500);
     slides: normalizedSlides
   };
   let compiledHtml;
-  const compiler = presentationKitCore?.compileHtmlDeck;
-  if (compiler) {
-    try {
-      const compiled = compiler(deckJson);
-      if (compiled?.html) {
-        compiledHtml = compiled.html;
-      }
-    } catch (compErr) {
-      console.warn(`[SlideProductionWorkflow] Failed compiling HTML deck:`, compErr?.message || compErr);
+  try {
+    let compiled = null;
+    if (typeof presentationKitCore?.compileHtmlDeckAsync === "function") {
+      compiled = await presentationKitCore.compileHtmlDeckAsync(deckJson);
+    }
+    if (!compiled?.html && typeof presentationKitCore?.compileHtmlDeck === "function") {
+      compiled = presentationKitCore.compileHtmlDeck(deckJson);
     }
+    if (compiled?.html) {
+      compiledHtml = compiled.html;
+    }
+  } catch (compErr) {
+    console.warn(`[SlideProductionWorkflow] Failed compiling HTML deck:`, compErr?.message || compErr);
   }
   const markdownWrapper = `---
 id: "SLIDE_${lessonCode}"
@@ -1818,10 +2059,11 @@ ${JSON.stringify(deckJson, null, 2)}
     compiledHtml,
     markdownWrapper,
     blueprint: blueprintItems,
-    slideCount: normalizedSlides.length
+    slideCount: normalizedSlides.length,
+    engine: engineUsed
   };
 }
-exports.SlideBlueprintItemSchema = void 0; exports.SlideBlueprintArraySchema = void 0; exports.GeneratedSlideSchema = void 0; exports.GeneratedSlideArraySchema = void 0;
+var LAYOUT_ID_ENUM; exports.SlideBlueprintItemSchema = void 0; exports.SlideBlueprintArraySchema = void 0; exports.GeneratedSlideSchema = void 0; exports.GeneratedSlideArraySchema = void 0; exports.HybridBlueprintItemSchema = void 0; exports.HybridBlueprintArraySchema = void 0; exports.HybridDeckSlideSchema = void 0; exports.HybridDeckSlideArraySchema = void 0; exports.HybridPipelineError = void 0;
 var init_slideProductionWorkflow = __esm({
   "src/services/slideProductionWorkflow.ts"() {
     init_lessonFlowParser();
@@ -1829,37 +2071,61 @@ var init_slideProductionWorkflow = __esm({
     init_slideBatchPrompt();
     init_provider_factory();
     init_streamRunner();
+    LAYOUT_ID_ENUM = zod.z.enum([
+      "hero-cover",
+      "split-concept-code",
+      "two-columns-compare",
+      "three-cards-grid",
+      "timeline-steps",
+      "metric-callout",
+      "checkpoint-quiz",
+      "tiered-practice-3cards",
+      "summary-takeaways"
+    ]);
     exports.SlideBlueprintItemSchema = zod.z.object({
       slideIndex: zod.z.number().int().min(1),
-      clusterId: zod.z.number().int().min(1).default(1),
-      clusterTitle: zod.z.string().default("Cluster"),
-      lessonPhase: zod.z.string().default("Content"),
-      layoutId: zod.z.enum([
-        "hero-cover",
-        "split-concept-code",
-        "two-columns-compare",
-        "three-cards-grid",
-        "timeline-steps",
-        "metric-callout",
-        "checkpoint-quiz",
-        "tiered-practice-3cards",
-        "summary-takeaways"
-      ]),
+      clusterId: zod.z.number().int().min(1).nullish().default(1),
+      clusterTitle: zod.z.string().nullish().default("Cluster"),
+      lessonPhase: zod.z.string().nullish().default("Content"),
+      layoutId: LAYOUT_ID_ENUM,
       title: zod.z.string().min(1),
-      pedagogicalGoal: zod.z.string().default(""),
-      contentFocus: zod.z.array(zod.z.string()).default([]),
-      codeSnippetIntent: zod.z.string().optional(),
-      visualIntent: zod.z.string().optional()
+      pedagogicalGoal: zod.z.string().nullish().default(""),
+      contentFocus: zod.z.array(zod.z.string()).nullish().default([]),
+      codeSnippetIntent: zod.z.string().nullish(),
+      visualIntent: zod.z.string().nullish()
     });
     exports.SlideBlueprintArraySchema = zod.z.array(exports.SlideBlueprintItemSchema);
     exports.GeneratedSlideSchema = zod.z.object({
-      id: zod.z.string().optional(),
-      layoutId: zod.z.string(),
+      id: zod.z.string().nullish(),
+      layoutId: zod.z.string().min(1),
       title: zod.z.string().min(1),
-      slots: zod.z.record(zod.z.any()).default({}),
-      notes: zod.z.string().default("")
+      slots: zod.z.record(zod.z.any()).nullish().default({}),
+      notes: zod.z.string().nullish().default("")
     });
     exports.GeneratedSlideArraySchema = zod.z.array(exports.GeneratedSlideSchema);
+    exports.HybridBlueprintItemSchema = zod.z.object({
+      slideIndex: zod.z.number().int().min(1),
+      clusterId: zod.z.number().int().min(1).nullish(),
+      clusterTitle: zod.z.string().nullish(),
+      lessonPhase: zod.z.string().nullish(),
+      layoutId: LAYOUT_ID_ENUM,
+      title: zod.z.string().min(1).max(300),
+      pedagogicalGoal: zod.z.string().nullish().default(""),
+      contentFocus: zod.z.array(zod.z.string()).nullish().default([]),
+      codeSnippetIntent: zod.z.string().nullish(),
+      visualIntent: zod.z.string().nullish()
+    });
+    exports.HybridBlueprintArraySchema = zod.z.array(exports.HybridBlueprintItemSchema);
+    exports.HybridDeckSlideSchema = zod.z.object({
+      id: zod.z.string().nullish(),
+      layoutId: zod.z.string().min(1),
+      title: zod.z.string().min(1).max(300),
+      slots: zod.z.record(zod.z.any()).nullish().default({}),
+      notes: zod.z.string().nullish().default("")
+    });
+    exports.HybridDeckSlideArraySchema = zod.z.array(exports.HybridDeckSlideSchema);
+    exports.HybridPipelineError = class extends Error {
+    };
   }
 });
 var LearningObjectiveRowSchema = zod.z.object({
@@ -10688,8 +10954,310 @@ ${lines.join("\n")}
 - For example: if canonical section is "Computational Thinking Focus", your heading must be "## [REQUIRED] ${headings["Computational Thinking Focus"] || "Computational Thinking Focus"}".`;
 }
 
+// src/services/curriculumHorizon.ts
+init_errors();
+var DETAILED_BRIDGE_WINDOW = 2;
+var BOUNDARY_PEEK_WINDOW = 2;
+function parseAllSessions(plan, frameworkMarkdown) {
+  if (plan) {
+    const rawSessions = Array.isArray(plan.sessions) ? plan.sessions : Array.isArray(plan) ? plan : [];
+    if (rawSessions.length > 0) {
+      return rawSessions.map((s, idx) => ({
+        id: s.id || `L${String(idx + 1).padStart(2, "0")}`,
+        order: typeof s.order === "number" ? s.order : idx + 1,
+        title: s.title || "",
+        prose_objective: s.prose_objective || s.objective || "",
+        new_keywords: Array.isArray(s.new_keywords) ? s.new_keywords : Array.isArray(s.keywords) ? s.keywords : [],
+        prerequisite_keywords: Array.isArray(s.prerequisite_keywords) ? s.prerequisite_keywords : [],
+        depth_assignments: Array.isArray(s.depth_assignments) ? s.depth_assignments : []
+      }));
+    }
+  }
+  if (frameworkMarkdown && typeof frameworkMarkdown === "string") {
+    const lines = frameworkMarkdown.split("\n");
+    let headerCols = [];
+    const sessions = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("|")) continue;
+      const cols = trimmed.split("|").slice(1, -1).map((c) => c.trim());
+      const lower = cols.map((c) => c.toLowerCase());
+      if (lower.some((c) => c.includes("lesson code") || c === "m\xE3 b\xE0i" || c.includes("m\xE3 b\xE0i h\u1ECDc"))) {
+        headerCols = cols;
+        continue;
+      }
+      if (/^[-: |]+$/.test(trimmed.slice(1, -1))) continue;
+      if (cols.length < 3) continue;
+      let lessonCode = "";
+      let title = "";
+      let objective = "";
+      let concept = "";
+      let keywordsStr = "";
+      if (headerCols.length > 0) {
+        const col = (name) => {
+          const idx = headerCols.findIndex((h) => h.toLowerCase().includes(name));
+          return idx >= 0 ? cols[idx] || "" : "";
+        };
+        lessonCode = (col("lesson code") || col("m\xE3 b\xE0i") || cols[1] || "").replace(/\*\*/g, "").trim();
+        title = (col("title") || col("t\xEAn") || cols[2] || "").replace(/\*\*/g, "").trim();
+        objective = col("learning objective") || col("objective") || col("m\u1EE5c ti\xEAu") || "";
+        concept = col("key concept") || col("concept") || col("kh\xE1i ni\u1EC7m") || "";
+        keywordsStr = col("keywords") || col("t\u1EEB kh\xF3a") || "";
+      } else {
+        lessonCode = (cols[1] || "").replace(/\*\*/g, "").trim();
+        title = (cols[2] || "").replace(/\*\*/g, "").trim();
+        objective = cols[5] || "";
+        concept = cols[4] || "";
+      }
+      if (lessonCode && /^[A-Za-z0-9_\-]+$/.test(lessonCode)) {
+        const keywords = keywordsStr ? keywordsStr.split(/[,;\n]/).map((k) => k.trim().replace(/^`|`$/g, "")).filter(Boolean) : concept ? concept.split(/[,;\n]/).map((k) => k.trim().replace(/^`|`$/g, "")).filter(Boolean) : [];
+        sessions.push({
+          id: lessonCode,
+          order: sessions.length + 1,
+          title: title || lessonCode,
+          prose_objective: objective,
+          new_keywords: keywords
+        });
+      }
+    }
+    if (sessions.length > 0) {
+      return sessions;
+    }
+  }
+  return [];
+}
+async function extractCurriculumHorizon(opts) {
+  const { plan, frameworkMarkdown, targetLessonId, storage, projectId } = opts;
+  const sessions = parseAllSessions(plan, frameworkMarkdown);
+  if (sessions.length === 0) {
+    throw new exports.CurriculumError({
+      errorCode: "ERR_LESSON_NOT_IN_SOT",
+      lessonId: targetLessonId,
+      message: `[CurriculumHorizon] No sessions could be parsed from CURRICULUM_PLAN.json or CURRICULUM_FRAMEWORK.md. Fail fast \u2014 cannot construct curriculum horizon without SOT.`,
+      suggestedAction: "Ensure CURRICULUM_PLAN.json or CURRICULUM_FRAMEWORK.md is generated and contains valid sessions.",
+      retryable: false
+    });
+  }
+  const targetCodePattern = new RegExp("^" + targetLessonId.replace(/_/g, "[_-]") + "$", "i");
+  const targetIndex = sessions.findIndex(
+    (s) => s.id === targetLessonId || targetCodePattern.test(s.id)
+  );
+  if (targetIndex < 0) {
+    throw new exports.CurriculumError({
+      errorCode: "ERR_LESSON_NOT_IN_SOT",
+      lessonId: targetLessonId,
+      message: `[CurriculumHorizon] Lesson "${targetLessonId}" was not found among the ${sessions.length} planned sessions. Fail fast \u2014 refusing to generate unanchored lesson.`,
+      suggestedAction: `Check lesson id against planned sessions: [${sessions.map((s) => s.id).join(", ")}]`,
+      retryable: false
+    });
+  }
+  const currentSession = sessions[targetIndex];
+  const compactEnd = Math.max(0, targetIndex - DETAILED_BRIDGE_WINDOW);
+  const compactSessions = sessions.slice(0, compactEnd);
+  const masteredKeywords = Array.from(
+    new Set(
+      compactSessions.flatMap((s) => s.new_keywords || []).map((k) => k.trim()).filter(Boolean)
+    )
+  );
+  const masteredConcepts = Array.from(
+    new Set(
+      compactSessions.map((s) => s.title || s.prose_objective || "").map((t) => t.trim()).filter(Boolean)
+    )
+  );
+  const bridgeStart = Math.max(0, targetIndex - DETAILED_BRIDGE_WINDOW);
+  const bridgeSessions = sessions.slice(bridgeStart, targetIndex);
+  const detailedBridge = [];
+  for (const session of bridgeSessions) {
+    const bridgeIndex = sessions.indexOf(session) + 1;
+    const bridge = {
+      lessonId: session.id,
+      lessonIndex: bridgeIndex,
+      title: session.title,
+      proseObjective: session.prose_objective,
+      keywords: session.new_keywords || []
+    };
+    if (storage && projectId) {
+      try {
+        const candidates = [
+          `_content/${session.id.replace(/_L\d+$/, "")}/LESSON_${session.id}.md`,
+          `_content/LESSON_${session.id}.md`,
+          `LESSON_${session.id}.md`
+        ];
+        let lessonMd = "";
+        for (const c of candidates) {
+          try {
+            const raw = await storage.readArtifact(projectId, c);
+            if (raw) {
+              lessonMd = raw;
+              break;
+            }
+          } catch {
+          }
+        }
+        if (lessonMd) {
+          const ledger = extractSymbolLedger(lessonMd);
+          if (ledger.primarySymbol || ledger.entryFileName || ledger.keySymbols.length > 0) {
+            bridge.symbolLedger = {
+              primaryStructOrClass: ledger.primarySymbol,
+              mainEntryFile: ledger.entryFileName,
+              keyVariables: ledger.keySymbols
+            };
+          }
+        }
+      } catch {
+      }
+    }
+    detailedBridge.push(bridge);
+  }
+  const peekStart = targetIndex + 1;
+  const peekEnd = Math.min(sessions.length, peekStart + BOUNDARY_PEEK_WINDOW);
+  const boundaryPeek = sessions.slice(peekStart, peekEnd).map((s, idx) => ({
+    lessonId: s.id,
+    lessonIndex: peekStart + idx + 1,
+    title: s.title,
+    keywords: s.new_keywords || []
+  }));
+  return {
+    targetLessonId,
+    targetLessonIndex: targetIndex + 1,
+    totalLessons: sessions.length,
+    targetTitle: currentSession.title,
+    targetKeywords: currentSession.new_keywords || [],
+    compactMasterySet: {
+      masteredKeywords,
+      masteredConcepts
+    },
+    detailedBridge,
+    boundaryPeek
+  };
+}
+function renderHorizonPromptBlock(horizon) {
+  const {
+    targetLessonId,
+    targetLessonIndex,
+    totalLessons,
+    targetTitle,
+    targetKeywords,
+    compactMasterySet,
+    detailedBridge,
+    boundaryPeek
+  } = horizon;
+  const lines = [
+    `# \u{1F9ED} CURRICULUM HORIZON & SCAFFOLDING MATRIX (Lesson ${targetLessonIndex}/${totalLessons}: "${targetTitle}" [${targetLessonId}])`
+  ];
+  if (compactMasterySet.masteredKeywords.length > 0 || compactMasterySet.masteredConcepts.length > 0) {
+    const rawKeywords = compactMasterySet.masteredKeywords;
+    const displayedKeywords = rawKeywords.length > 20 ? rawKeywords.slice(-20) : rawKeywords;
+    const vocab = displayedKeywords.map((k) => `\`${k}\``).join(", ");
+    const moreSuffix = rawKeywords.length > 20 ? ` *(+${rawKeywords.length - 20} earlier terms)*` : "";
+    const concepts = compactMasterySet.masteredConcepts.length > 0 ? `
+- **Prior Concept Foundations:** ${compactMasterySet.masteredConcepts.slice(-3).join("; ")}` : "";
+    lines.push(
+      `
+## 1. \u{1F393} MASTERED VOCABULARY (Prior Lessons 1..${Math.max(1, targetLessonIndex - 3)} \u2014 Compact Set):`,
+      `- **Mastered Terms & Syntax:** ${vocab || "(Core fundamentals)"}${moreSuffix}${concepts}`
+    );
+  } else if (targetLessonIndex === 1) {
+    lines.push(
+      `
+## 1. \u{1F393} PRIOR KNOWLEDGE FRONTIER:`,
+      `- **Entry Point:** Inaugural lesson (Lesson 1/${totalLessons}). Students have no prior course vocabulary. All concepts must be introduced from baseline.`
+    );
+  }
+  if (detailedBridge.length > 0) {
+    lines.push(`
+## 2. \u{1F309} IMMEDIATE PREDECESSOR CONTEXT (Bridge Lessons):`);
+    for (const bridge of detailedBridge) {
+      lines.push(`### Lesson ${bridge.lessonIndex} (${bridge.lessonId}): ${bridge.title}`);
+      if (bridge.proseObjective) {
+        const obj = bridge.proseObjective.length > 120 ? bridge.proseObjective.slice(0, 117) + "..." : bridge.proseObjective;
+        lines.push(`- **Objective:** ${obj}`);
+      }
+      if (bridge.keywords.length > 0) {
+        lines.push(`- **Keywords:** ${bridge.keywords.map((k) => `\`${k}\``).join(", ")}`);
+      }
+      if (bridge.symbolLedger) {
+        const parts = [];
+        if (bridge.symbolLedger.primaryStructOrClass) {
+          parts.push(`Primary Struct: \`${bridge.symbolLedger.primaryStructOrClass}\``);
+        }
+        if (bridge.symbolLedger.mainEntryFile) {
+          parts.push(`Entry File: \`${bridge.symbolLedger.mainEntryFile}\``);
+        }
+        if (bridge.symbolLedger.keyVariables?.length) {
+          parts.push(`Symbols: ${bridge.symbolLedger.keyVariables.map((v) => `\`${v}\``).join(", ")}`);
+        }
+        if (parts.length > 0) {
+          lines.push(`- **Code Symbol Ledger:** ${parts.join(" | ")}`);
+        }
+      }
+    }
+    lines.push(
+      `\u{1F449} INSTRUCTION: Seamlessly connect the opening Hook and Guided Practice by referencing the student's recent work from Lesson ${detailedBridge[detailedBridge.length - 1]?.lessonIndex}.`
+    );
+  }
+  const currentKeywordsStr = targetKeywords.length > 0 ? targetKeywords.map((k) => `\`${k}\``).join(", ") : "`Current Lesson Concepts`";
+  lines.push(
+    `
+## 3. \u{1F3AF} ALLOWED DESIGN SPACE (Positive-Only Allow List):`,
+    `- **Student Toolkit:** Mastered Vocabulary + Immediate Bridge Keywords + Current Lesson Scope (${currentKeywordsStr}).`,
+    `- **MANDATE:** ALL extension challenges (EXT), hands-on activities (ACT), and assessment questions (QUIZ) MUST be 100% solvable using ONLY items within this toolkit. Do NOT require unintroduced APIs!`
+  );
+  if (boundaryPeek.length > 0) {
+    const nextLesson = boundaryPeek[0];
+    const nextKeywords = nextLesson.keywords.length > 0 ? nextLesson.keywords.map((k) => `\`${k}\``).join(", ") : "upcoming features";
+    lines.push(
+      `
+## 4. \u{1F6A7} BOUNDARY (Next Lesson Peek):`,
+      `- **Upcoming Lesson ${nextLesson.lessonIndex} ("${nextLesson.title}"):** Introduces ${nextKeywords}.`,
+      `- **BOUNDARY MANDATE:** These concepts are NOT yet available to the student. Do not introduce or require these future concepts.`
+    );
+  }
+  return lines.join("\n");
+}
+function validateHorizonCompliance(artifactContent, horizon) {
+  const issues = [];
+  const forbiddenMatches = [];
+  if (!artifactContent || horizon.boundaryPeek.length === 0) {
+    return { compliant: true, issues: [], forbiddenMatches: [] };
+  }
+  const contentLower = artifactContent.toLowerCase();
+  const immediateNext = horizon.boundaryPeek[0];
+  if (immediateNext && immediateNext.keywords.length > 0) {
+    for (const kw of immediateNext.keywords) {
+      const trimmed = kw.trim().toLowerCase();
+      if (trimmed.length <= 2) continue;
+      const pattern = new RegExp(`\\b${trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+      if (pattern.test(contentLower)) {
+        const inMastered = horizon.compactMasterySet.masteredKeywords.some(
+          (m) => m.toLowerCase() === trimmed
+        );
+        const inBridge = horizon.detailedBridge.some(
+          (b) => b.keywords.some((bk) => bk.toLowerCase() === trimmed)
+        );
+        const inCurrent = horizon.targetKeywords.some(
+          (ck) => ck.toLowerCase() === trimmed
+        );
+        if (!inMastered && !inBridge && !inCurrent) {
+          forbiddenMatches.push(kw);
+          issues.push(
+            `Artifact contains boundary concept "${kw}" scheduled for future Lesson ${immediateNext.lessonIndex} ("${immediateNext.title}").`
+          );
+        }
+      }
+    }
+  }
+  return {
+    compliant: issues.length === 0,
+    issues,
+    forbiddenMatches
+  };
+}
+
 // src/services/contextBuilder.ts
 var DEFAULT_LESSON_PRIORITIES = [
+  "Symbol & Identifier Ledger",
+  "Artifact Contract",
   "A. Lesson Design Plan",
   "B. Lesson Flow",
   "Learning Objectives & Evidence",
@@ -10908,6 +11476,12 @@ function normalizeHeading(str) {
   return str.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
 }
 function findCanonicalFuzzy(norm) {
+  if (norm.includes("symbol") || norm.includes("identifier ledger") || norm.includes("dinh danh")) {
+    return "Symbol & Identifier Ledger";
+  }
+  if (norm.includes("artifact contract") || norm.includes("hop dong hoc lieu")) {
+    return "Artifact Contract";
+  }
   if (norm.includes("lesson design plan") || norm.includes("ke hoach thiet ke")) {
     return "A. Lesson Design Plan";
   }
@@ -10958,6 +11532,39 @@ function deriveArtifactTypeFromFileName(fileName) {
   const token = base.match(/^([A-Z][A-Z0-9_]*?)(?=_|$)/);
   return token ? token[1] : void 0;
 }
+function extractSymbolLedger(lessonMarkdown) {
+  const result = {
+    keySymbols: [],
+    rawBlock: ""
+  };
+  if (!lessonMarkdown) return result;
+  const ledgerMatch = lessonMarkdown.match(/###?\s*(?:Symbol & Identifier Ledger|Bảng Định Danh|Artifact Contract)[\s\S]*?(?=\n##|\n---|$)/i);
+  if (ledgerMatch) {
+    result.rawBlock = ledgerMatch[0].trim();
+  }
+  const structMatch = lessonMarkdown.match(/(?:Primary Struct|Primary Class|Primary Function|Main Component|Primary Module|Struct chính|Class chính|Hàm chính)[:\s*`]+([A-Za-z0-9_]+)/i);
+  if (structMatch) {
+    result.primarySymbol = structMatch[1];
+    result.keySymbols.push(structMatch[1]);
+  } else {
+    const codeStructMatch = lessonMarkdown.match(/(?:struct|class|interface|type|def|function)\s+([A-Za-z0-9_]+)/);
+    if (codeStructMatch) {
+      const sym = codeStructMatch[1];
+      result.primarySymbol = sym;
+      result.keySymbols.push(sym);
+    }
+  }
+  const fileMatch = lessonMarkdown.match(/(?:Entry File|Source File|Target File|Tên file mã nguồn)[:\s*`]+([A-Za-z0-9_\-\.]+\.[a-z0-9_]+)/i);
+  if (fileMatch) {
+    result.entryFileName = fileMatch[1];
+  } else {
+    const codeFileComment = lessonMarkdown.match(/(?:\/\/\s*|#\s*|\/\*\s*)([A-Za-z0-9_\-]+\.[a-zA-Z0-9]+)/);
+    if (codeFileComment) {
+      result.entryFileName = codeFileComment[1];
+    }
+  }
+  return result;
+}
 
 // src/services/knowledgeExpositionService.ts
 var EXPOSITION_REL = (lessonCode) => "_sot/expositions/" + lessonCode + ".md";
@@ -10977,8 +11584,22 @@ var DEPTH_RULES = {
   cio: "Write WHAT + WHY + HOW: include the mechanism, step by step, still technology-independent.",
   sio: "Write WHAT + WHY + HOW + SPECIFIC: include concrete implementations and how the real project keywords are used."
 };
-function buildSystemPrompt(targetLanguage = "vi") {
+function buildDomainLexiconGuardrail(techStack, hardwarePlatform) {
+  const targetTech = (techStack || "").trim();
+  const targetHw = (hardwarePlatform || "").trim();
+  const platformAnchor = [targetTech, targetHw].filter(Boolean).join(" | ");
+  if (!platformAnchor) {
+    return `- \u{1F512} TECHNICAL DOMAIN ANCHOR: Strictly adhere to the declared curriculum domain. Use ONLY native, standard, idiomatic syntax and mechanisms. Strictly FORBIDDEN from using foreign paradigms, cross-domain jargon, or hallucinated APIs.`;
+  }
+  return `- \u{1F512} STRICT DOMAIN & TECHNICAL PLATFORM ANCHOR:
+  \u2022 Declared Platform: "${platformAnchor}"
+  \u2022 NATIVE PARADIGM ONLY: You MUST strictly use standard, idiomatic syntax, conventions, naming patterns, and mental models of "${platformAnchor}".
+  \u2022 ANTI-CONTAMINATION INVARIANT: Strictly FORBIDDEN from importing or using syntax, units, keywords, tags, or concepts from unrelated/foreign ecosystems (e.g., do NOT leak Web/HTML/CSS tags or units into native mobile/embedded stacks, do NOT leak dynamic scripting into statically typed systems, do NOT use hardware/circuit terminology in pure-software courses).
+  \u2022 REAL APIS ONLY: Every method, modifier, property, and API referenced must exist in the standard SDK of "${platformAnchor}".`;
+}
+function buildSystemPrompt(targetLanguage = "vi", techStack, hardwarePlatform) {
   const langDirective = buildLanguageDirective(targetLanguage);
+  const domainGuardrails = buildDomainLexiconGuardrail(techStack, hardwarePlatform);
   return [
     "You write KNOWLEDGE_EXPOSITION: self-study reading material for a student in a teacherless program.",
     "Rules:",
@@ -10987,6 +11608,7 @@ function buildSystemPrompt(targetLanguage = "vi") {
     "3. Respect each concept depth target (ULO/CIO/SIO) \u2014 do not overshoot.",
     "4. Student-facing only: no teacher instructions, no classroom management text.",
     "5. Output the full markdown document following the provided section skeleton exactly (headers and placeholders preserved).",
+    domainGuardrails,
     langDirective
   ].join("\n");
 }
@@ -11023,7 +11645,7 @@ function buildUserPrompt(session, plan, glossary, targetLanguage = "vi", slcMark
   ].filter(Boolean).join("\n");
 }
 async function ensureKnowledgeExposition(options) {
-  const { projectId, lessonCode, plan, glossary, llmFn, storage } = options;
+  const { projectId, lessonCode, plan, glossary, llmFn, storage, techStack, hardwarePlatform } = options;
   const session = plan.sessions.find((s) => s.id === lessonCode);
   if (!session) throw new Error("Session " + lessonCode + " not found in plan " + plan.plan_id);
   const existing = await storage.readArtifact(projectId, EXPOSITION_REL(lessonCode));
@@ -11038,7 +11660,7 @@ async function ensureKnowledgeExposition(options) {
   }
   const targetLanguage = options.targetLanguage || plan.translation?.target_language || "vi";
   const content = (await llmFn(
-    buildSystemPrompt(targetLanguage),
+    buildSystemPrompt(targetLanguage, techStack, hardwarePlatform),
     buildUserPrompt(session, plan, glossary, targetLanguage, options.slcMarkdown)
   )).trim();
   if (content.length < 200) {
@@ -11108,6 +11730,18 @@ async function ensureExpositionForLesson(storage, projectId, lessonCode, options
   }
   const scopedTerms = new Set(plan.glossary_scope.find((g) => g.session_id === lessonCode)?.terms ?? []);
   glossary = glossary.filter((g) => scopedTerms.has(g.term));
+  let hw = options.hardwarePlatform;
+  let tech = options.techStack;
+  if (!hw || !tech) {
+    try {
+      const lpRaw = await storage.readSotDocument(projectId, "LEARNER_PROFILE.md");
+      if (lpRaw) {
+        const hwMatch = lpRaw.match(/(?:Student Equipment|Hardware|Platform|Thiết bị)[:\s*`]+([^\n\r]+)/i);
+        if (hwMatch && !hw) hw = hwMatch[1].trim();
+      }
+    } catch {
+    }
+  }
   const { runCurriculumAIInference: runCurriculumAIInference2 } = await Promise.resolve().then(() => (init_streamRunner(), streamRunner_exports));
   const targetLang = options.targetLanguage || plan.translation?.target_language || "vi";
   const result = await ensureKnowledgeExposition({
@@ -11117,6 +11751,8 @@ async function ensureExpositionForLesson(storage, projectId, lessonCode, options
     glossary,
     targetLanguage: targetLang,
     slcMarkdown: options.slcMarkdown,
+    techStack: tech,
+    hardwarePlatform: hw,
     llmFn: async (systemPrompt, userPrompt) => {
       const runnerOpts = options.customInference ? { customInference: options.customInference } : {};
       const out = await runCurriculumAIInference2(
@@ -25143,7 +25779,11 @@ type: "LESSON_EDP"
 
 ### 3. Resource Map (Slide, Handout, Starter Code, Lab Tools)
 ### 4. Assessment Map (Rubric criteria, formative checkpoints, remediation paths)
-### 5. Artifact Contract (Detailed specifications for ACT, SLIDE, QUIZ)
+### 5. Artifact Contract & Code Symbol Ledger
+- **Primary Struct / Class / Component:** [Explicit canonical identifier e.g. ProfileCardView]
+- **Entry Source File:** [Explicit file name e.g. ProfileCardView.swift]
+- **Key Functions & State Variables:** [Canonical identifiers used across all student activities]
+- **Artifact Specifications:** [Deliverable requirements for ACT, SLIDE, QUIZ, GUIDE, WKS, CODE, EXT]
 
 ---
 
@@ -25193,7 +25833,11 @@ type: "LESSON_GENERAL"
 
 ### 3. Resource Map
 ### 4. Assessment Map
-### 5. Artifact Contract
+### 5. Artifact Contract & Code Symbol Ledger
+- **Primary Struct / Class / Component:** [Explicit canonical identifier e.g. MainComponent]
+- **Entry Source File:** [Explicit file name e.g. MainComponent.ext]
+- **Key Functions & State Variables:** [Canonical identifiers used across all student activities]
+- **Artifact Specifications:** [Deliverable requirements for ACT, SLIDE, QUIZ, GUIDE, WKS, CODE, EXT]
 
 ---
 
@@ -25241,7 +25885,11 @@ type: "LESSON_5E"
 
 ### 3. Resource Map
 ### 4. Assessment Map
-### 5. Artifact Contract (Detailed specifications for ACT, SLIDE, QUIZ, GUIDE)
+### 5. Artifact Contract & Code Symbol Ledger
+- **Primary Struct / Class / Component:** [Explicit canonical identifier e.g. MainComponent]
+- **Entry Source File:** [Explicit file name e.g. MainComponent.ext]
+- **Key Functions & State Variables:** [Canonical identifiers used across all student activities]
+- **Artifact Specifications:** [Deliverable requirements for ACT, SLIDE, QUIZ, GUIDE, WKS, CODE, EXT]
 
 ---
 
@@ -25420,6 +26068,32 @@ async function produceSingleLesson(storage, projectId, lessonId, options = {}) {
 
 [CURRICULUM FRAMEWORK EXCERPT]:
 ${buildFrameworkExcerptForLesson(framework, lessonId)}`;
+  let horizon = null;
+  let horizonBlock = "";
+  try {
+    let planObj = null;
+    const planRaw = await storage.readArtifact(projectId, "_sot/CURRICULUM_PLAN.json");
+    if (planRaw) {
+      try {
+        planObj = JSON.parse(planRaw);
+      } catch {
+      }
+    }
+    horizon = await extractCurriculumHorizon({
+      plan: planObj,
+      frameworkMarkdown: framework,
+      targetLessonId: lessonCode,
+      storage,
+      projectId
+    });
+    if (horizon) {
+      horizonBlock = `
+
+${renderHorizonPromptBlock(horizon)}`;
+    }
+  } catch (hErr) {
+    console.warn(`[produceSingleLesson] Notice: Curriculum Horizon extraction:`, hErr?.message || hErr);
+  }
   const glossaryBlock = glossaryContext ? `
 
 [GLOSSARY TERMS (use these exact definitions)]:
@@ -25440,7 +26114,7 @@ ${sessionSliceContext}` : "";
 ${sg}
 
 [REFERENCE PACK GROUND TRUTH]:
-${ref}${standardsBlock}${glossaryBlock}${expositionBlock}${sessionSliceBlock}`;
+${ref}${standardsBlock}${glossaryBlock}${expositionBlock}${sessionSliceBlock}${horizonBlock}`;
   let commonContext = assembleCommonContext(effectiveRefPack, effectiveStyleGuide);
   const MAX_COMPOSITE_PROMPT_CHARS = 3e4;
   const runnerOptions = options.customInference ? { customInference: options.customInference } : {};
@@ -25816,17 +26490,23 @@ ${currentContent}` }],
     artifactType: "LESSON"
   });
   const lessonExcerpt = lessonExcerptResult.excerpt;
-  const lessonInjectionMeta = {
-    source: "LESSON",
+  ({
     verified: lessonExcerptResult.verified,
     sectionAware: lessonExcerptResult.sectionAware,
     issues: lessonExcerptResult.issues
-  };
-  lessonInjection = lessonInjectionMeta;
+  });
+  const symbolLedger = extractSymbolLedger(lessonContent);
+  const symbolLedgerBlock = symbolLedger.primarySymbol ? `
+
+[MANDATORY CODE SYMBOL REGISTRY (Inherited from LESSON Plan)]:
+- Primary Struct / Class / Component: \`${symbolLedger.primarySymbol}\`
+- Entry Source File: \`${symbolLedger.entryFileName || symbolLedger.primarySymbol}\`
+- Key Identifiers to inherit verbatim: ${symbolLedger.keySymbols.map((s) => `\`${s}\``).join(", ")}
+- INVARIANT: You MUST use these exact identifier names in all code examples, exercises, and test assertions. Do NOT invent new struct/class names!` : "";
   const satelliteContext = `${commonContext}
 
 [CANONICAL LESSON PLAN (${pedagogyLabel})]:
-${lessonExcerpt}`;
+${lessonExcerpt}${symbolLedgerBlock}`;
   const judgeSat = (sat, content) => {
     if (gateModeFor(gates, sat) !== "LLM_JUDGE") return Promise.resolve();
     return judgeSatelliteArtifact({
@@ -26329,6 +27009,12 @@ ${buildHeadingDirective("CODE", slcMarkdown, targetLang)}`;
       c3: "### Challenge 3: [Name] (Difficulty: \u2B50\u2B50\u2B50\u2B50\u2B50) \u2014 Extension Milestones (Level 1: Ninja \u2192 Level 2: Guru \u2192 Level 3: Master)",
       meta: "## [REQUIRED] Metacognitive Deep Dive & Engineering Trade-offs"
     };
+    const zpdCeilingPrompt = horizon ? `
+4. \u{1F3AF} CURRICULUM HORIZON ALLOWED SPACE & BOUNDARY MANDATE:
+   - Student's COMPLETE allowed toolkit = Mastered Vocabulary + Immediate Bridge + Current Lesson Scope (${horizon.targetKeywords.join(", ") || "Current Lesson Concepts"}).
+   - All extension challenges MUST be 100% solvable using ONLY items within this toolkit.
+   ${horizon.boundaryPeek.length > 0 ? `- STRICT BOUNDARY: Upcoming Lesson ${horizon.boundaryPeek[0].lessonIndex} introduces "${horizon.boundaryPeek[0].title}" (${horizon.boundaryPeek[0].keywords.join(", ")}). These are STRICTLY OUT OF SCOPE. Do NOT introduce or require these future APIs.` : ""}` : `
+4. ZPD SCOPE: Focus on architectural edge cases, algorithmic optimization, and creative variations within current and past lesson concepts.`;
     const extPrompt = `You are @activity (Lead STEM Specialist & Differentiated Extension Designer).
 Based on Master Lesson Plan \`LESSON_${lessonCode}.md\`, author the advanced extension challenge: \`EXT_${lessonCode}.md\`.
 
@@ -26360,6 +27046,7 @@ ${extHeadings.sub}
    - ${extHeadings.c3}
    - ${extHeadings.meta}
 3. Output 100% clean Markdown directly \u2014 NO code fences around the document.
+${zpdCeilingPrompt}
 
 ${languageDirective}
 
@@ -26890,6 +27577,29 @@ async function generateSingleArtifact(req) {
   const artifactSpecializedPrompt = getArtifactSpecializedInvariants(artifactType, {
     ...req,
     studentCount});
+  const techStack = req.config?.techStack || req.hardwarePlatform?.[0] || "Declared Technical Domain";
+  const domainGuardrail = buildDomainLexiconGuardrail(techStack, hwStr);
+  const symbolLedger = contextSot.lessonPlan ? extractSymbolLedger(contextSot.lessonPlan) : null;
+  const symbolLedgerPrompt = symbolLedger?.primarySymbol ? `
+7. MANDATORY CODE SYMBOL REGISTRY (Inherited from Canonical LESSON):
+   - Primary Struct / Class: \`${symbolLedger.primarySymbol}\`
+   - Entry Source File: \`${symbolLedger.entryFileName || symbolLedger.primarySymbol + ".swift"}\`
+   - Key Identifiers to inherit: ${symbolLedger.keySymbols.map((s) => `\`${s}\``).join(", ")}
+   - INVARIANT: You MUST use these exact identifier names in all code examples, exercises, and starter templates. Do NOT invent conflicting struct or class names.` : "";
+  let horizon = contextSot.horizon || null;
+  if (!horizon && (contextSot.plan || contextSot.framework) && lessonId) {
+    try {
+      horizon = await extractCurriculumHorizon({
+        plan: contextSot.plan,
+        frameworkMarkdown: contextSot.framework,
+        targetLessonId: lessonId
+      });
+    } catch {
+    }
+  }
+  const horizonPrompt = horizon ? `
+
+${renderHorizonPromptBlock(horizon)}` : "";
   const systemPrompt = `You are ${meta.persona}, an expert Curriculum & Pedagogical Specialist in the Curriculum OS Multi-Agent Team.
 Your task is to author a canonical, publication-grade learning artifact of type "${artifactType.toUpperCase()}".
 
@@ -26900,7 +27610,10 @@ ${headingDirective}
 3. PEDAGOGICAL GROUNDING: Strictly align with the ${pedagogy.toUpperCase()} model, Bloom's Revised Taxonomy, and IEEE/ACM CS2023 guidelines.
 4. SCAFFOLDING LEVEL: "${scaffoldingLevel.toUpperCase()}".${scaffoldingRule}
 5. TARGET AUDIENCE: ${gradeLevel ? `Grade ${gradeLevel}, ` : ""}${targetAge} on ${hwStr}.${deviceRule}${classDynamicsRule}${extraContextRule}
-6. OUTPUT INTEGRITY: Output clean Markdown starting directly with YAML frontmatter. Do not wrap entire response in triple backticks.${artifactSpecializedPrompt}${mediaPolicy ? `
+6. DOMAIN & TECH STACK GUARDRAILS:
+${domainGuardrail}
+${symbolLedgerPrompt}
+8. OUTPUT INTEGRITY: Output clean Markdown starting directly with YAML frontmatter. Do not wrap entire response in triple backticks.${artifactSpecializedPrompt}${horizonPrompt}${mediaPolicy ? `
 
 IMAGE PLANNING (media ledger) \u2014 QUOTA GEN: t\u1ED1i \u0111a ${mediaPolicy.maxGenImagesPerArtifact} \u1EA3nh AI cho artifact n\xE0y (\u1EA3nh search kho kh\xF4ng gi\u1EDBi h\u1EA1n).
 Khi n\u1ED9i dung c\u1EA7n minh h\u1ECDa (diagram quy tr\xECnh, s\u01A1 \u0111\u1ED3 kh\xE1i ni\u1EC7m, step-by-step visual), ch\xE8n placeholder \u0111\xFAng format [IMAGE: slug] (slug ch\u1EEF th\u01B0\u1EDDng-g\u1EA1ch ngang, unique trong b\xE0i, vd img-for-loop-diagram) T\u1EA0I \u0110\xDANG CH\u1ED6 c\u1EA7n \u1EA3nh, tr\xEAn d\xF2ng ri\xEAng. KH\xD4NG t\u1EF1 sinh \u1EA3nh, KH\xD4NG d\xF9ng markdown image \u2014 placeholder s\u1EBD \u0111\u01B0\u1EE3c thay b\u1EB1ng \u1EA3nh th\u1EADt sau khi Media Curator duy\u1EC7t. Ch\u1EC9 \u0111\u1EB7t cho \u1EA3nh TH\u1EF0C S\u1EF0 c\u1EA7n thi\u1EBFt.` : ""}`;
@@ -27380,6 +28093,20 @@ ${includeUnitTests ? "- Unit Testing: Provide automated assertions or test runne
 1. **CLASS-SCALED INVENTORY FOR ${studentCount} STUDENTS**:
    - Exact quantities calculated for ${studentCount} students.
    - Component specifications, estimated unit cost, and affordable alternatives.`;
+    case "ext": {
+      const zpdCeilingRule = `- \u{1F3AF} CURRICULUM HORIZON ALLOWED SPACE & BOUNDARY MANDATE:
+  \u2022 SCOPE LOCK: All extension challenges MUST be 100% solvable using ONLY items from the student's Mastered Vocabulary and Current Lesson Scope.
+  \u2022 STRICTLY FORBIDDEN: NEVER introduce unintroduced APIs or mechanisms from upcoming lessons (No complex event buses, No remote network/API calls, No persistent databases, No async concurrency, No out-of-scope hardware/sensors unless explicitly part of the allowed toolkit).`;
+      return `
+### \u{1F680} EXTENSION CHALLENGE ARCHITECTURE INVARIANTS:
+${zpdCeilingRule}
+1. **STRUCTURED 3-TIER CHALLENGES**:
+   - Challenge 1 (Mission Briefing): High-stakes real-world scenario applying today's concepts.
+   - Challenge 2 (Architectural Constraints & Edge Cases): Deeper technical rules without violating prerequisite boundaries.
+   - Challenge 3 (Extension Milestones): Progressive milestones (Level 1: Novice \u2192 Level 2: Advanced \u2192 Level 3: Master).
+2. **METACOGNITIVE & ENGINEERING TRADE-OFFS**:
+   - Explicit reflection prompts evaluating architectural choices, code maintainability, and design patterns.`;
+    }
     case "lesson": {
       const lessonDuration = cfg.lessonDuration || 90;
       const pedagogicalModel = cfg.pedagogicalModel || req.pedagogy || "5e";
@@ -31203,6 +31930,7 @@ exports.buildCurriculumContext = buildCurriculumContext;
 exports.buildCurriculumPlan = buildCurriculumPlan;
 exports.buildDeliveryPackages = buildDeliveryPackages;
 exports.buildDiagnosticQuizPrompt = buildDiagnosticQuizPrompt;
+exports.buildDomainLexiconGuardrail = buildDomainLexiconGuardrail;
 exports.buildExpositionContext = buildExpositionContext;
 exports.buildExpositionExcerpt = buildExpositionExcerpt;
 exports.buildExtensionPrompt = buildExtensionPrompt;
@@ -31248,11 +31976,14 @@ exports.executeCurriculumCommand = executeCurriculumCommand;
 exports.executeSlideProductionWorkflow = executeSlideProductionWorkflow;
 exports.exportAllProjectQuizzes = exportAllProjectQuizzes;
 exports.expositionCacheKey = expositionCacheKey;
+exports.extractCurriculumHorizon = extractCurriculumHorizon;
+exports.extractJsonArray = extractJsonArray;
 exports.extractScopeSequenceRows = extractScopeSequenceRows;
 exports.extractSectionHeadingsFromSLC = extractSectionHeadingsFromSLC;
 exports.extractSessionSlice = extractSessionSlice;
 exports.extractStandardRefs = extractStandardRefs;
 exports.extractStreamChunk = extractStreamChunk;
+exports.extractSymbolLedger = extractSymbolLedger;
 exports.extractThoughtAndContent = extractThoughtAndContent;
 exports.findStandardStatement = findStandardStatement;
 exports.formatQuizzesToCsv = formatQuizzesToCsv;
@@ -31305,6 +32036,7 @@ exports.loadSotTemplate = loadSotTemplate;
 exports.normalizePlanningGraph = normalizePlanningGraph;
 exports.normalizeSlcContract = normalizeSlcContract;
 exports.packagerTools = packagerTools;
+exports.parseAllSessions = parseAllSessions;
 exports.parseGateSettings = parseGateSettings;
 exports.parseQuizMarkdown = parseQuizMarkdown;
 exports.parseRoadmapJsonToProjectPayload = parseRoadmapJsonToProjectPayload;
@@ -31314,6 +32046,7 @@ exports.publishToGitHub = publishToGitHub;
 exports.publishToSupabase = publishToSupabase;
 exports.rankGenCandidates = rankGenCandidates;
 exports.renderFrameworkFromPlan = renderFrameworkFromPlan;
+exports.renderHorizonPromptBlock = renderHorizonPromptBlock;
 exports.renderMediaPlaceholder = renderMediaPlaceholder;
 exports.researcherTools = researcherTools;
 exports.resolveGateSettings = resolveGateSettings;
@@ -31350,6 +32083,8 @@ exports.uploadAssetToBucket = uploadAssetToBucket;
 exports.validateArtifactDependencies = validateArtifactDependencies;
 exports.validateCurriculumPlan = validateCurriculumPlan;
 exports.validateFrameworkPack = validateFrameworkPack;
+exports.validateHorizonCompliance = validateHorizonCompliance;
+exports.validateHybridDeckSlides = validateHybridDeckSlides;
 exports.validateMarkdownTables = validateMarkdownTables;
 exports.validateMermaidSyntax = validateMermaidSyntax;
 exports.withAutoRepair = withAutoRepair;