Fix ADT packaging, v2 preview cache-busting, and asset migration (#70)

* Fix ADT packaging: quiz data-id collision, text catalog, preview improvements

- Rename assets/web → assets/adt and update all references
- Fix quiz flash/disappear bug: use _que suffix for question text catalog IDs
  to avoid data-id collision between section and question elements
- Always build text catalog fresh during packaging; persist only if changed
- Build text catalog on-the-fly in preview route for accurate quiz data
- Add dynamic quiz page rendering to adt-preview route
- Move repackage button from PreviewView content area to sidebar nav
- Add page_number to quiz entries in pages.json
- Add esbuild JS bundle build step to packaging pipeline
- Remove pre-built bundle in favor of esbuild-based bundling

* Fix quiz packaging edge case and strengthen package-web tests

Author: nicpottier

apps/api/src/app.ts

@@ -38,7 +38,7 @@ const configPath = path.resolve(
   process.env.CONFIG_PATH ?? path.join(projectRoot, "config.yaml")
 )
 const webAssetsDir = path.resolve(
-  process.env.WEB_ASSETS_DIR ?? path.join(projectRoot, "assets", "web")
+  process.env.WEB_ASSETS_DIR ?? path.join(projectRoot, "assets", "adt")
 )
 
 const pipelineRunner = createPipelineRunner()

apps/api/src/routes/adt-preview.ts

@@ -7,7 +7,9 @@ import {
   WebRenderingOutput,
   type TextCatalogOutput,
   type GlossaryOutput,
+  type QuizGenerationOutput,
   type TTSOutput,
+  type Quiz,
 } from "@adt/types"
 import { createBookStorage, type Storage } from "@adt/storage"
 import {
@@ -18,6 +20,10 @@ import {
   buildGlossaryJson,
   getBaseLanguage,
   normalizeLocale,
+  renderQuizHtml,
+  buildQuizAnswers,
+  buildTextCatalog,
+  pad3,
 } from "@adt/pipeline"
 
 // ---------------------------------------------------------------------------
@@ -44,6 +50,7 @@ const MIME_TYPES: Record<string, string> = {
   ".wav": "audio/wav",
   ".ogg": "audio/ogg",
   ".map": "application/json",
+  ".dic": "application/octet-stream",
 }
 
 function getMimeType(filePath: string): string {
@@ -54,7 +61,7 @@ function getMimeType(filePath: string): string {
 // Caches (built lazily per book)
 // ---------------------------------------------------------------------------
 
-const tailwindCssCache = new Map<string, string>()
+// No Tailwind cache — preview is a dev tool; staleness causes more pain than rebuild cost
 
 // ---------------------------------------------------------------------------
 // Helpers to read book data from storage
@@ -72,16 +79,21 @@ function getBookTitle(storage: Storage): string {
   return metadata?.title ?? "ADT Preview"
 }
 
-function getTextCatalog(storage: Storage): TextCatalogOutput | undefined {
-  const row = storage.getLatestNodeData("text-catalog", "book")
-  return row?.data as TextCatalogOutput | undefined
+function getTextCatalog(storage: Storage): TextCatalogOutput {
+  const pages = storage.getPages()
+  return buildTextCatalog(storage, pages)
 }
 
 function getGlossary(storage: Storage): GlossaryOutput | undefined {
   const row = storage.getLatestNodeData("glossary", "book")
   return row?.data as GlossaryOutput | undefined
 }
 
+function getQuizData(storage: Storage): QuizGenerationOutput | undefined {
+  const row = storage.getLatestNodeData("quiz-generation", "book")
+  return row?.data as QuizGenerationOutput | undefined
+}
+
 function buildTextsMap(
   storage: Storage,
   lang: string,
@@ -109,14 +121,38 @@ function buildTextsMap(
   return textsMap
 }
 
-/** Build the pages.json manifest from all rendered pages */
+/** Build the pages.json manifest from all rendered pages, interleaving quiz pages */
 function buildPagesManifest(storage: Storage): Array<{ section_id: string; href: string }> {
   const pages = storage.getPages()
+  const quizData = getQuizData(storage)
+
+  // Build a map from afterPageId -> quizzes for interleaving
+  const quizzesByAfterPageId = new Map<string, Quiz[]>()
+  if (quizData?.quizzes) {
+    for (const quiz of quizData.quizzes) {
+      const existing = quizzesByAfterPageId.get(quiz.afterPageId) ?? []
+      existing.push(quiz)
+      quizzesByAfterPageId.set(quiz.afterPageId, existing)
+    }
+  }
+
   const list: Array<{ section_id: string; href: string }> = []
   for (const page of pages) {
     const renderRow = storage.getLatestNodeData("web-rendering", page.pageId)
-    if (renderRow) {
-      list.push({ section_id: page.pageId, href: `${page.pageId}.html` })
+    if (!renderRow) continue
+    const parsed = WebRenderingOutput.safeParse(renderRow.data)
+    if (!parsed.success || parsed.data.sections.length === 0) continue
+
+    list.push({ section_id: page.pageId, href: `${page.pageId}.html` })
+
+    // Insert quiz pages after this page
+    const quizzes = quizzesByAfterPageId.get(page.pageId)
+    if (quizzes) {
+      for (const quiz of quizzes) {
+        const quizIndex = quizData!.quizzes.indexOf(quiz)
+        const quizId = `qz${pad3(quizIndex + 1)}`
+        list.push({ section_id: quizId, href: `${quizId}.html` })
+      }
     }
   }
   return list
@@ -179,6 +215,12 @@ export function createAdtPreviewRoutes(
 ): Hono {
   const app = new Hono()
 
+  // Disable browser caching for all preview responses — this is a dev tool
+  app.use("*", async (c, next) => {
+    await next()
+    c.header("Cache-Control", "no-store")
+  })
+
   // Helper: resolve book + validate
   function resolveBook(label: string) {
     const safeLabel = parseBookLabel(label)
@@ -252,31 +294,39 @@ export function createAdtPreviewRoutes(
     return c.body(NAV_HTML)
   })
 
-  // /content/tailwind_output.css
+  // /content/tailwind_output.css — rebuilt on every request (no cache, dev tool)
   app.get("/books/:label/adt-preview/content/tailwind_output.css", async (c) => {
     const { safeLabel } = resolveBook(c.req.param("label"))
 
-    let css = tailwindCssCache.get(safeLabel)
-    if (!css) {
-      const storage = createBookStorage(safeLabel, booksDir)
-      try {
-        const pages = storage.getPages()
-        let allHtml = ""
-        for (const page of pages) {
-          const renderRow = storage.getLatestNodeData("web-rendering", page.pageId)
-          if (renderRow) {
-            const parsed = WebRenderingOutput.safeParse(renderRow.data)
-            if (parsed.success) {
-              const { html } = combineSections(parsed.data)
-              allHtml += html + "\n"
-            }
+    const storage = createBookStorage(safeLabel, booksDir)
+    let css: string
+    try {
+      const pages = storage.getPages()
+      let allHtml = ""
+      for (const page of pages) {
+        const renderRow = storage.getLatestNodeData("web-rendering", page.pageId)
+        if (renderRow) {
+          const parsed = WebRenderingOutput.safeParse(renderRow.data)
+          if (parsed.success) {
+            const { html } = combineSections(parsed.data)
+            allHtml += html + "\n"
           }
         }
-        css = await buildPreviewTailwindCss(allHtml, webAssetsDir)
-        tailwindCssCache.set(safeLabel, css)
-      } finally {
-        storage.close()
       }
+
+      // Include quiz HTML so Tailwind scans quiz classes
+      const quizData = getQuizData(storage)
+      const catalog = getTextCatalog(storage)
+      if (quizData?.quizzes) {
+        for (let i = 0; i < quizData.quizzes.length; i++) {
+          const quizId = `qz${pad3(i + 1)}`
+          allHtml += renderQuizHtml(quizData.quizzes[i], quizId, catalog) + "\n"
+        }
+      }
+
+      css = await buildPreviewTailwindCss(allHtml, webAssetsDir)
+    } finally {
+      storage.close()
     }
 
     c.header("Content-Type", "text/css")
@@ -393,6 +443,42 @@ export function createAdtPreviewRoutes(
     const pageId = filename.replace(/\.html$/, "")
 
     return withStorage(label, (storage) => {
+      const title = getBookTitle(storage)
+      const language = getBookLanguage(storage)
+
+      // Check if this is a quiz page (qzNNN)
+      const quizMatch = pageId.match(/^qz(\d{3})$/)
+      if (quizMatch) {
+        const quizIndex = parseInt(quizMatch[1], 10) - 1
+        const quizData = getQuizData(storage)
+        if (!quizData?.quizzes || quizIndex < 0 || quizIndex >= quizData.quizzes.length) {
+          throw new HTTPException(404, { message: `No quiz data for: ${pageId}` })
+        }
+        const quiz = quizData.quizzes[quizIndex]
+        const catalog = getTextCatalog(storage)
+
+        const quizHtmlContent = renderQuizHtml(quiz, pageId, catalog)
+        // Determine page index from the manifest
+        const manifest = buildPagesManifest(storage)
+        const manifestIndex = manifest.findIndex((e) => e.section_id === pageId)
+
+        const html = renderPageHtml({
+          content: quizHtmlContent,
+          language,
+          sectionId: pageId,
+          pageTitle: title,
+          pageIndex: manifestIndex >= 0 ? manifestIndex + 1 : 1,
+          activityAnswers: buildQuizAnswers(quiz, pageId),
+          hasMath: false,
+          bundleVersion: "1",
+          skipContentWrapper: true,
+        })
+
+        c.header("Content-Type", "text/html; charset=utf-8")
+        return c.body(html)
+      }
+
+      // Regular content page
       const renderRow = storage.getLatestNodeData("web-rendering", pageId)
       if (!renderRow) {
         throw new HTTPException(404, { message: `No rendering data for page: ${pageId}` })
@@ -404,30 +490,17 @@ export function createAdtPreviewRoutes(
       }
 
       const { html: sectionHtml, activityAnswers } = combineSections(parsed.data)
-      const title = getBookTitle(storage)
-      const language = getBookLanguage(storage)
 
-      // Determine page index from all rendered pages
-      const pages = storage.getPages()
-      let pageIndex = 1
-      let idx = 0
-      for (const p of pages) {
-        const row = storage.getLatestNodeData("web-rendering", p.pageId)
-        if (row) {
-          idx++
-          if (p.pageId === pageId) {
-            pageIndex = idx
-            break
-          }
-        }
-      }
+      // Determine page index from manifest (includes quiz pages)
+      const manifest = buildPagesManifest(storage)
+      const manifestIndex = manifest.findIndex((e) => e.section_id === pageId)
 
       const html = renderPageHtml({
         content: sectionHtml,
         language,
         sectionId: pageId,
         pageTitle: title,
-        pageIndex,
+        pageIndex: manifestIndex >= 0 ? manifestIndex + 1 : 1,
         activityAnswers,
         hasMath: false,
         bundleVersion: "1",

apps/api/src/routes/books.ts

@@ -31,6 +31,7 @@ const MIME_TYPES: Record<string, string> = {
   ".ttf": "font/ttf",
   ".ico": "image/x-icon",
   ".webp": "image/webp",
+  ".dic": "application/octet-stream",
 }
 
 export function createBookRoutes(
@@ -304,6 +305,9 @@ export function createBookRoutes(
   })
 
   // GET /books/:label/adt/* — Serve packaged ADT static files
+  // Supports an optional cache-bust version segment: /adt/v-{ts}/page.html
+  // The version segment is stripped before resolving files, so all relative
+  // URLs (pages, assets, content) carry the same bust automatically.
   // When no file path is given, redirect to the first page.
   app.get("/books/:label/adt/*", (c) => {
     const { label } = c.req.param()
@@ -325,7 +329,11 @@ export function createBookRoutes(
     const adtPrefix = `/books/${safeLabel}/adt/`
     const reqPath = c.req.path
     const prefixIdx = reqPath.indexOf(adtPrefix)
-    const filePath = prefixIdx >= 0 ? reqPath.slice(prefixIdx + adtPrefix.length) : ""
+    let filePath = prefixIdx >= 0 ? reqPath.slice(prefixIdx + adtPrefix.length) : ""
+
+    // Strip optional cache-bust version segment (e.g. "v-1708300000000/" or "v-1708300000000")
+    filePath = filePath.replace(/^v-[^/]+\/?/, "")
+
     if (!filePath) {
       // Root request — redirect to first page
       const pagesPath = path.join(adtDir, "content", "pages.json")
@@ -338,8 +346,10 @@ export function createBookRoutes(
       if (pages.length === 0) {
         throw new HTTPException(404, { message: "ADT has no pages" })
       }
-      const qs = new URL(c.req.url).search
-      return c.redirect(`/api/books/${safeLabel}/adt/${pages[0].href}${qs}`)
+      // Preserve the version segment in the redirect
+      const versionMatch = reqPath.match(/\/adt\/(v-[^/]+)/)
+      const versionPrefix = versionMatch ? `${versionMatch[1]}/` : ""
+      return c.redirect(`/api/books/${safeLabel}/adt/${versionPrefix}${pages[0].href}`)
     }
 
     const resolvedPath = path.resolve(adtDir, filePath)

apps/studio/src/components/storyboard/PageEditPanel.tsx

@@ -518,7 +518,7 @@ export const PageEditPanel = forwardRef<PageEditPanelHandle, PageEditPanelProps>
                   </div>
                 ) : adtPreview && combinedHtml ? (
                   <iframe
-                    src={`/api/books/${label}/adt-preview/${pageId}.html`}
+                    src={`/api/books/${label}/adt/v-${Date.now()}/${pageId}.html`}
                     className="h-full min-h-[600px] w-full rounded border"
                     title="ADT Preview"
                     allow="autoplay"

apps/studio/src/components/v2/StepSidebar.tsx

@@ -10,6 +10,7 @@ import {
   Languages,
   Eye,
   Settings,
+  RotateCcw,
   FileDown,
   ChevronDown,
   Loader2,
@@ -243,8 +244,8 @@ export function StepSidebar({
                 </span>
               </Link>
 
-              {/* Settings gear icon (only for active step, not for book) */}
-              {isActive && step.slug !== "book" && (
+              {/* Action button (only for active step, not for book) */}
+              {isActive && step.slug !== "book" && step.slug !== "preview" && (
                 <Button
                   variant="ghost"
                   size="icon"
@@ -266,6 +267,20 @@ export function StepSidebar({
                   </Link>
                 </Button>
               )}
+              {isActive && step.slug === "preview" && (
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className={cn(
+                    "w-6 h-6 rounded shrink-0 hidden lg:inline-flex group-hover/sidebar:inline-flex [&_svg]:size-3.5",
+                    "hover:bg-black/5 text-current opacity-50 hover:opacity-100"
+                  )}
+                  onClick={() => window.dispatchEvent(new CustomEvent("adt:repackage"))}
+                  title="Re-package ADT"
+                >
+                  <RotateCcw className="w-3.5 h-3.5" />
+                </Button>
+              )}
             </div>
 
             {/* Settings sub-tabs (extract only, when settings active) */}