handzon-core 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Core framework for Handzon — layouts, components, content + AI libs, and server runtime (handlers, DB, auth, migration runner) consumed by Handzon scaffolds.",
   "publishConfig": {
     "access": "public"

package/src/collections.ts

@@ -20,6 +20,7 @@ import { join, relative, resolve } from "node:path";
 import type { Loader } from "astro/loaders";
 import { glob } from "astro/loaders";
 import { createHeroMediaSchema } from "./lib/heroMedia";
+import { collectProgressItemIds, validateProgressItemIds } from "./lib/progress/progressItems";
 import { createTutorialIconSchema } from "./lib/tutorialIcon";
 
 const TUTORIALS_REL = "src/content/tutorials";
@@ -219,7 +220,6 @@ export function stepsLoader(): Loader {
     name: "handzon-steps",
     load: async (args) => {
       await inner.load(args);
-      const checkpointRe = /<Checkpoint\b[^>]*\bid\s*=\s*(?:"([^"]+)"|'([^']+)'|\{`([^`]+)`\})/g;
       const trackIdCache = new Map<string, Promise<string[]>>();
       for (const value of args.store.values()) {
         const { tutorialSlug } = parseStepCollectionId(value.id);
@@ -229,17 +229,11 @@ export function stepsLoader(): Loader {
         const trackIds = await trackIdsPromise;
         const body = value.body ?? "";
         validateTrackIdsInBody({ body, entryId: value.id, trackIds });
+        validateProgressItemIds({ body, entryId: value.id });
 
         const verify = (value.data as { verify?: TrackScoped<VerifySpec> } | undefined)?.verify;
         if (!verify) continue;
-        const ids = new Set<string>();
-        checkpointRe.lastIndex = 0;
-        for (;;) {
-          const m = checkpointRe.exec(body);
-          if (m === null) break;
-          const id = m[1] ?? m[2] ?? m[3];
-          if (id) ids.add(id);
-        }
+        const ids = collectProgressItemIds(body).Checkpoint;
 
         if (isTrackMap(verify, isVerifySpec)) {
           validateTrackMapCoverage({

package/src/components/Sidebar.astro

@@ -16,7 +16,7 @@ interface Props {
 const { tutorial, steps, currentStepSlug } = Astro.props;
 const slug = tutorial.id;
 ---
-<aside class="sidebar" aria-label="Tutorial steps">
+<aside class="sidebar" aria-label="Tutorial steps" data-gated={tutorial.data.gated ? "true" : "false"}>
   {/* Top block: back link, title, progress. Stays fixed while the
    * step list below scrolls when there are many steps. */}
   <div class="sb-top">
@@ -77,10 +77,11 @@ const slug = tutorial.id;
       const isCurrent = stepSlug === currentStepSlug;
       return (
         <li class={isCurrent ? "is-current" : ""} data-step-slug={stepSlug}>
-          <a href={withBase(`/${slug}/${stepSlug}`)}>
+          <a href={withBase(`/${slug}/${stepSlug}`)} data-step-link="true">
             <span class="sb-check" data-step-key={`${slug}/${stepSlug}`}></span>
             <span class="sb-name">{step.data.title}</span>
             {step.data.duration && <span class="sb-dur">{step.data.duration}</span>}
+            <span class="sb-lock" aria-hidden="true">Locked</span>
           </a>
         </li>
       );
@@ -91,13 +92,17 @@ const slug = tutorial.id;
 {/* Pre-paint: mirror the persisted progress state into the SSR sidebar
     before hydrated modules run, avoiding a step-change flash from
     0 / unchecked to the learner's real progress. */}
-<script is:inline define:vars={{ storageKey: STORAGE_KEY, tutorialSlug: slug, totalSteps: steps.length }}>
+<script is:inline define:vars={{ storageKey: STORAGE_KEY, tutorialSlug: slug, totalSteps: steps.length, tutorialSteps: steps.map((step) => parseStepId(step.id).stepSlug), gated: tutorial.data.gated }}>
   (function () {
     try {
       var raw = window.localStorage.getItem(storageKey);
       var state = raw ? JSON.parse(raw) : null;
       var steps = (state && state.steps) || {};
       var completed = 0;
+      var firstIncomplete = tutorialSteps.find(function (slug) {
+        return steps[tutorialSlug + "/" + slug] !== "complete";
+      });
+      var lockStart = gated && firstIncomplete ? tutorialSteps.indexOf(firstIncomplete) + 1 : -1;
 
       document.querySelectorAll("[data-step-key]").forEach(function (el) {
         var key = el.getAttribute("data-step-key");
@@ -105,6 +110,12 @@ const slug = tutorial.id;
         el.setAttribute("data-done", done ? "true" : "false");
         if (done && key.indexOf(tutorialSlug + "/") === 0) completed += 1;
       });
+      if (lockStart > 0) {
+        tutorialSteps.slice(lockStart).forEach(function (slug) {
+          var item = document.querySelector('[data-step-slug="' + slug + '"]');
+          if (item) item.setAttribute("data-locked", "true");
+        });
+      }
 
       var progress = document.querySelector(".sidebar .progress");
       if (!progress) return;
@@ -125,14 +136,50 @@ const slug = tutorial.id;
 <script>
   // Hydrate per-step check marks from localStorage without an island.
   import { getStore } from "../lib/progress/local";
+  import { lockedStepSlugs } from "../lib/progress/gating";
+
+  const sidebar = document.querySelector<HTMLElement>(".sidebar");
+  const tutorialSlug = sidebar?.querySelector<HTMLElement>("[data-step-key]")?.dataset.stepKey?.split("/")[0];
+  const gated = sidebar?.dataset.gated === "true";
+  const tutorialSteps = Array.from(document.querySelectorAll<HTMLElement>("[data-step-slug]")).map(
+    (el) => el.dataset.stepSlug!,
+  );
+
+  sidebar?.addEventListener("click", (e) => {
+    const link = (e.target as Element).closest<HTMLAnchorElement>(
+      "[data-step-link][aria-disabled='true']",
+    );
+    if (link) e.preventDefault();
+  });
+
   function refresh() {
     const store = getStore();
     const state = store.get();
+    const locked =
+      gated && tutorialSlug
+        ? new Set(lockedStepSlugs({ tutorialSlug, stepSlugs: tutorialSteps, steps: state.steps }))
+        : new Set<string>();
     document.querySelectorAll<HTMLElement>("[data-step-key]").forEach((el) => {
       const key = el.dataset.stepKey as `${string}/${string}`;
       const done = state.steps[key] === "complete";
       el.dataset.done = done ? "true" : "false";
     });
+    document.querySelectorAll<HTMLElement>("[data-step-slug]").forEach((el) => {
+      const stepSlug = el.dataset.stepSlug!;
+      const link = el.querySelector<HTMLAnchorElement>("[data-step-link]");
+      const isLocked = locked.has(stepSlug);
+      el.dataset.locked = isLocked ? "true" : "false";
+      if (!link) return;
+      if (isLocked) {
+        link.setAttribute("aria-disabled", "true");
+        link.setAttribute("tabindex", "-1");
+        link.setAttribute("title", "Complete previous steps to unlock this step.");
+      } else {
+        link.removeAttribute("aria-disabled");
+        link.removeAttribute("tabindex");
+        link.removeAttribute("title");
+      }
+    });
   }
   refresh();
   getStore().subscribe(refresh);
@@ -227,6 +274,14 @@ const slug = tutorial.id;
     background: var(--color-surface);
     color: var(--color-fg);
   }
+  .sb-steps li[data-locked="true"] a {
+    cursor: not-allowed;
+    opacity: 0.48;
+  }
+  .sb-steps li[data-locked="true"] a:hover {
+    background: transparent;
+    box-shadow: none;
+  }
   .sb-steps li.is-current a {
     background: color-mix(in oklab, var(--color-accent) 40%, var(--color-bg));
     color: var(--color-fg);
@@ -253,4 +308,18 @@ const slug = tutorial.id;
     font-weight: 400;
     letter-spacing: 0.02em;
   }
+  .sb-lock {
+    display: none;
+    position: absolute;
+    right: 1rem;
+    bottom: 0.45rem;
+    color: var(--color-muted);
+    font-family: var(--font-mono);
+    font-size: 0.68em;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+  .sb-steps li[data-locked="true"] .sb-lock {
+    display: inline;
+  }
 </style>

package/src/layouts/TutorialLayout.astro

@@ -140,6 +140,7 @@ const trackBootstrap =
     id="tt-route"
     data-tutorial-slug={tutorial.id}
     data-step-slug={currentStepSlug}
+    data-tutorial-gated={tutorial.data.gated ? "true" : "false"}
     data-tutorial-title={tutorial.data.title}
     data-tutorial-steps={JSON.stringify(stepSlugs)}
     hidden
@@ -168,6 +169,8 @@ const trackBootstrap =
     // import so Vite resolves the path alias correctly; define:vars +
     // dynamic import("~/...") bypasses Vite's resolver and the browser
     // can't load the module.
+    import { withBase } from "../lib/base";
+    import { firstIncompletePrerequisite } from "../lib/progress/gating";
     import { getStore } from "../lib/progress/local";
     import { deriveStepCompletion } from "../lib/progress/stepCompletion";
     import type { StepKey } from "../lib/progress/types";
@@ -180,86 +183,99 @@ const trackBootstrap =
         route.dataset.tutorialSteps ?? "[]",
       ) as string[];
       const store = getStore();
+      const redirectStep =
+        route.dataset.tutorialGated === "true"
+          ? firstIncompletePrerequisite({
+              tutorialSlug,
+              stepSlugs: tutorialSteps,
+              stepSlug,
+              steps: store.get().steps,
+            })
+          : undefined;
 
-      // Mark last-visited + tutorial "started" on every mount. The
-      // started branch is idempotent: it only writes the timestamp the
-      // first time per learner, so /api/progress sees one POST per
-      // tutorial — not one per page view.
-      store.set((s) => {
-        const nextLastVisited = {
-          ...s.lastVisited,
-          [tutorialSlug]: { step: stepSlug, ts: Date.now() },
-        };
-        if (s.tutorials[tutorialSlug]?.started) {
-          return { ...s, lastVisited: nextLastVisited };
-        }
-        return {
-          ...s,
-          lastVisited: nextLastVisited,
-          tutorials: {
-            ...s.tutorials,
-            [tutorialSlug]: {
-              ...s.tutorials[tutorialSlug],
-              started: Date.now(),
+      if (redirectStep && redirectStep !== stepSlug) {
+        window.location.replace(withBase(`/${tutorialSlug}/${redirectStep}`));
+      } else {
+        // Mark last-visited + tutorial "started" on every mount. The
+        // started branch is idempotent: it only writes the timestamp the
+        // first time per learner, so /api/progress sees one POST per
+        // tutorial — not one per page view.
+        store.set((s) => {
+          const nextLastVisited = {
+            ...s.lastVisited,
+            [tutorialSlug]: { step: stepSlug, ts: Date.now() },
+          };
+          if (s.tutorials[tutorialSlug]?.started) {
+            return { ...s, lastVisited: nextLastVisited };
+          }
+          return {
+            ...s,
+            lastVisited: nextLastVisited,
+            tutorials: {
+              ...s.tutorials,
+              [tutorialSlug]: {
+                ...s.tutorials[tutorialSlug],
+                started: Date.now(),
+              },
             },
-          },
-        };
-      });
+          };
+        });
 
-      function readCompletionItemIds(selector: string, attr: string) {
-        const activeTrack = document.documentElement.dataset.track;
-        const ids = Array.from(document.querySelectorAll<HTMLElement>(selector))
-          .map((el) => {
-            const trackPanel = el.closest<HTMLElement>("[data-track-panel]");
-            if (activeTrack && trackPanel?.dataset.trackPanel !== activeTrack) return null;
-            return el.dataset[attr];
-          })
-          .filter((id): id is string => !!id);
-        return Array.from(new Set(ids));
-      }
+        function readCompletionItemIds(selector: string, attr: string) {
+          const activeTrack = document.documentElement.dataset.track;
+          const ids = Array.from(document.querySelectorAll<HTMLElement>(selector))
+            .map((el) => {
+              const trackPanel = el.closest<HTMLElement>("[data-track-panel]");
+              if (activeTrack && trackPanel?.dataset.trackPanel !== activeTrack) return null;
+              return el.dataset[attr];
+            })
+            .filter((id): id is string => !!id);
+          return Array.from(new Set(ids));
+        }
 
-      function recomputeStepCompletion() {
-        const completion = deriveStepCompletion(store.get(), {
-          quizIds: readCompletionItemIds("[data-quiz-id]", "quizId"),
-          checkpointIds: readCompletionItemIds("[data-checkpoint-id]", "checkpointId"),
-        });
-        if (completion === null) return;
-        store.set((s) => {
-          if (s.steps[stepKey] === completion) return s;
-          return { ...s, steps: { ...s.steps, [stepKey]: completion } };
-        });
-      }
+        function recomputeStepCompletion() {
+          const completion = deriveStepCompletion(store.get(), {
+            quizIds: readCompletionItemIds("[data-quiz-id]", "quizId"),
+            checkpointIds: readCompletionItemIds("[data-checkpoint-id]", "checkpointId"),
+          });
+          if (completion === null) return;
+          store.set((s) => {
+            if (s.steps[stepKey] === completion) return s;
+            return { ...s, steps: { ...s.steps, [stepKey]: completion } };
+          });
+        }
 
-      recomputeStepCompletion();
-      document.addEventListener("hz:step-item", recomputeStepCompletion);
-      store.subscribe(recomputeStepCompletion);
+        recomputeStepCompletion();
+        document.addEventListener("hz:step-item", recomputeStepCompletion);
+        store.subscribe(recomputeStepCompletion);
 
-      // Watch for tutorial completion: once every step in the embedded
-      // list flips to "complete", record the "completed" event exactly
-      // once. Re-runs on store changes so finishing the last step on a
-      // mid-tutorial page (rare) still triggers it.
-      function checkCompletion() {
-        const s = store.get();
-        if (s.tutorials[tutorialSlug]?.completed) return;
-        if (tutorialSteps.length === 0) return;
-        const allDone = tutorialSteps.every(
-          (slug) => s.steps[`${tutorialSlug}/${slug}` as `${string}/${string}`] === "complete",
-        );
-        if (allDone) {
-          store.set((cur) => ({
-            ...cur,
-            tutorials: {
-              ...cur.tutorials,
-              [tutorialSlug]: {
-                ...cur.tutorials[tutorialSlug],
-                completed: Date.now(),
+        // Watch for tutorial completion: once every step in the embedded
+        // list flips to "complete", record the "completed" event exactly
+        // once. Re-runs on store changes so finishing the last step on a
+        // mid-tutorial page (rare) still triggers it.
+        function checkCompletion() {
+          const s = store.get();
+          if (s.tutorials[tutorialSlug]?.completed) return;
+          if (tutorialSteps.length === 0) return;
+          const allDone = tutorialSteps.every(
+            (slug) => s.steps[`${tutorialSlug}/${slug}` as `${string}/${string}`] === "complete",
+          );
+          if (allDone) {
+            store.set((cur) => ({
+              ...cur,
+              tutorials: {
+                ...cur.tutorials,
+                [tutorialSlug]: {
+                  ...cur.tutorials[tutorialSlug],
+                  completed: Date.now(),
+                },
               },
-            },
-          }));
+            }));
+          }
         }
+        checkCompletion();
+        store.subscribe(checkCompletion);
       }
-      checkCompletion();
-      store.subscribe(checkCompletion);
     }
   </script>
 </BaseLayout>

package/src/lib/progress/gating.ts

@@ -0,0 +1,44 @@
+import type { ProgressState, StepKey } from "./types";
+
+type StepStatusMap = ProgressState["steps"];
+
+interface GatingInput {
+  tutorialSlug: string;
+  stepSlugs: string[];
+  steps: StepStatusMap;
+}
+
+interface StepGateInput extends GatingInput {
+  stepSlug: string;
+}
+
+const stepKey = (tutorialSlug: string, stepSlug: string): StepKey => `${tutorialSlug}/${stepSlug}`;
+
+export function firstIncompleteStep({ tutorialSlug, stepSlugs, steps }: GatingInput) {
+  return stepSlugs.find((slug) => steps[stepKey(tutorialSlug, slug)] !== "complete");
+}
+
+export function firstIncompletePrerequisite({
+  tutorialSlug,
+  stepSlugs,
+  stepSlug,
+  steps,
+}: StepGateInput) {
+  const targetIndex = stepSlugs.indexOf(stepSlug);
+  if (targetIndex <= 0) return undefined;
+  return stepSlugs
+    .slice(0, targetIndex)
+    .find((slug) => steps[stepKey(tutorialSlug, slug)] !== "complete");
+}
+
+export function canVisitGatedStep(input: StepGateInput) {
+  if (!input.stepSlugs.includes(input.stepSlug)) return true;
+  return !firstIncompletePrerequisite(input);
+}
+
+export function lockedStepSlugs({ tutorialSlug, stepSlugs, steps }: GatingInput) {
+  const firstIncomplete = firstIncompleteStep({ tutorialSlug, stepSlugs, steps });
+  if (!firstIncomplete) return [];
+  const lockStart = stepSlugs.indexOf(firstIncomplete) + 1;
+  return stepSlugs.slice(lockStart);
+}

package/src/lib/progress/progressItems.ts

@@ -0,0 +1,69 @@
+const PROGRESS_ITEM_COMPONENTS = ["Checkpoint", "Quiz"] as const;
+
+type ProgressItemComponent = (typeof PROGRESS_ITEM_COMPONENTS)[number];
+
+export type ProgressItemIds = Record<ProgressItemComponent, Set<string>>;
+
+const emptyProgressItemIds = (): ProgressItemIds => ({
+  Checkpoint: new Set<string>(),
+  Quiz: new Set<string>(),
+});
+
+function stripFencedCodeBlocks(body: string): string {
+  return body.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1\s*$/gm, "");
+}
+
+function readAttribute(tag: string, attribute: string): string | undefined {
+  const attrRe = new RegExp(`\\b${attribute}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|\\{\`([^\`]+)\`\\})`);
+  const match = attrRe.exec(tag);
+  return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+
+function readTag(source: string, start: number): { tag: string; end: number } | null {
+  let quote: '"' | "'" | "`" | null = null;
+  for (let i = start + 1; i < source.length; i++) {
+    const char = source[i];
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === ">") return { tag: source.slice(start, i + 1), end: i + 1 };
+  }
+  return null;
+}
+
+function findProgressItemTags(body: string) {
+  const source = stripFencedCodeBlocks(body);
+  const tags: Array<{ component: ProgressItemComponent; tag: string }> = [];
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] !== "<" || !/[A-Za-z]/.test(source[i + 1] ?? "")) continue;
+    const tag = readTag(source, i);
+    if (!tag) continue;
+    const match = /^<(Checkpoint|Quiz)\b/.exec(tag.tag);
+    if (match) tags.push({ component: match[1] as ProgressItemComponent, tag: tag.tag });
+    i = tag.end - 1;
+  }
+  return tags;
+}
+
+export function validateProgressItemIds({ body, entryId }: { body: string; entryId: string }) {
+  for (const { component, tag } of findProgressItemTags(body)) {
+    if (readAttribute(tag, "id")) continue;
+    throw new Error(
+      `[handzon] step ${entryId}: <${component}> must include an explicit id because it contributes to progress. Use id="<step-area>/<concept>" so learner progress survives content edits.`,
+    );
+  }
+}
+
+export function collectProgressItemIds(body: string): ProgressItemIds {
+  const ids = emptyProgressItemIds();
+  for (const { component, tag } of findProgressItemTags(body)) {
+    const id = readAttribute(tag, "id");
+    if (id) ids[component].add(id);
+  }
+  return ids;
+}