tessera-learn 0.0.9 → 0.0.11

package/src/plugin/layout.ts

@@ -1,55 +1,10 @@
-import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-const VIRTUAL_LAYOUT_ID = 'virtual:tessera-layout';
-const RESOLVED_LAYOUT_ID = '\0' + VIRTUAL_LAYOUT_ID;
+import type { Plugin } from 'vite';
+import { createOverridePlugin } from './override-plugin.js';
 
 export function tesseraLayoutPlugin(): Plugin {
-  let projectRoot: string;
-
-  return {
+  return createOverridePlugin({
     name: 'tessera:layout',
-    enforce: 'pre',
-
-    configResolved(config: ResolvedConfig) {
-      projectRoot = config.root;
-    },
-
-    resolveId(id) {
-      if (id === VIRTUAL_LAYOUT_ID) return RESOLVED_LAYOUT_ID;
-      return null;
-    },
-
-    load(id) {
-      if (id !== RESOLVED_LAYOUT_ID) return null;
-      const layoutPath = resolve(projectRoot, 'layout.svelte');
-      if (existsSync(layoutPath)) {
-        // Register the file with Vite so edits trigger HMR / build --watch
-        // re-runs. Only add when the file actually exists — calling
-        // addWatchFile on a non-existent path makes Vite's importAnalysis
-        // try to resolve it as a real import.
-        this.addWatchFile(layoutPath);
-        const normalized = layoutPath.replace(/\\/g, '/');
-        return `export { default } from '${normalized}';`;
-      }
-      return `export default null;`;
-    },
-
-    configureServer(server: ViteDevServer) {
-      const layoutPath = resolve(projectRoot, 'layout.svelte');
-      // Only react to add/unlink: those flip the virtual module's load() output
-      // between `export default null` and `export { default } from '...'`. A
-      // `change` event leaves that output identical and is handled by Svelte's
-      // own HMR for the underlying file — full-reloading on every edit would
-      // wipe in-page state for no reason.
-      server.watcher.on('all', (event, filePath) => {
-        if (filePath !== layoutPath) return;
-        if (event !== 'add' && event !== 'unlink') return;
-        const mod = server.moduleGraph.getModuleById(RESOLVED_LAYOUT_ID);
-        if (mod) server.moduleGraph.invalidateModule(mod);
-        server.ws.send({ type: 'full-reload' });
-      });
-    },
-  };
+    virtualId: 'virtual:tessera-layout',
+    projectFile: 'layout.svelte',
+  });
 }

package/src/plugin/manifest.ts

@@ -105,6 +105,29 @@ export function extractDefaultExportObjectLiteral(source: string): string | null
   return extractObjectLiteral(source, startIndex);
 }
 
+export type CourseConfigRead =
+  | { ok: true; config: Record<string, any> }
+  | { ok: false; reason: 'missing' | 'no-export' | 'parse-error'; error?: unknown };
+
+/**
+ * Read and JSON5-parse the `export default { ... }` literal from a project's
+ * course.config.js. Shared by the build plugin and the validator so the read,
+ * cache, and parse rules live in one place. The discriminated `reason` lets
+ * callers that care (export, validation) emit precise errors while callers
+ * that just need a value can fall back on `!ok`.
+ */
+export function readCourseConfig(projectRoot: string): CourseConfigRead {
+  const configPath = resolve(projectRoot, 'course.config.js');
+  if (!existsSync(configPath)) return { ok: false, reason: 'missing' };
+  const objectStr = extractDefaultExportObjectLiteral(readSourceFileCached(configPath));
+  if (!objectStr) return { ok: false, reason: 'no-export' };
+  try {
+    return { ok: true, config: JSON5.parse(objectStr) };
+  } catch (error) {
+    return { ok: false, reason: 'parse-error', error };
+  }
+}
+
 /**
  * Read a _meta.js file and extract its default export object.
  * Uses the same JSON5 approach as pageConfig extraction — find the object literal
@@ -173,11 +196,14 @@ export function extractPageConfig(filePath: string): { title?: string; quiz?: Qu
 }
 
 /**
- * Extract an object literal from source starting at the opening brace.
- * Tracks brace depth to find the matching closing brace.
+ * Extract a balanced `{...}` or `[...]` span starting at the opening bracket,
+ * skipping strings and comments. Returns the substring (inclusive) or null if
+ * the open char is wrong or no matching close is found. Shared by manifest
+ * extraction, _meta/pageConfig parsing, and the validator's tag-prop parser.
  */
 export function extractObjectLiteral(source: string, startIndex: number): string | null {
-  if (source[startIndex] !== '{') return null;
+  const open = source[startIndex];
+  if (open !== '{' && open !== '[') return null;
 
   let depth = 0;
   let inString: string | null = null;
@@ -222,8 +248,8 @@ export function extractObjectLiteral(source: string, startIndex: number): string
       continue;
     }
 
-    if (char === '{') depth++;
-    if (char === '}') {
+    if (char === '{' || char === '[') depth++;
+    if (char === '}' || char === ']') {
       depth--;
       if (depth === 0) {
         return source.slice(startIndex, i + 1);

package/src/plugin/override-plugin.ts

@@ -0,0 +1,68 @@
+import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
+import { normalizePath } from 'vite';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface OverridePluginOptions {
+  name: string;
+  virtualId: string;
+  projectFile: string;
+  /** Built-in re-exported when the project file is absent; null export otherwise. */
+  builtinFile?: string;
+}
+
+/**
+ * A virtual module that resolves to a project-root override file when present,
+ * and to the built-in (or a null export) otherwise. Shared by the layout and
+ * quiz plugins — they differ only in the virtual id, file name, and built-in.
+ */
+export function createOverridePlugin({
+  name,
+  virtualId,
+  projectFile,
+  builtinFile,
+}: OverridePluginOptions): Plugin {
+  const resolvedId = '\0' + virtualId;
+  const fallback = builtinFile
+    ? `export { default } from '${normalizePath(builtinFile)}';`
+    : 'export default null;';
+  let filePath: string;
+
+  return {
+    name,
+    enforce: 'pre',
+
+    configResolved(config: ResolvedConfig) {
+      filePath = resolve(config.root, projectFile);
+    },
+
+    resolveId(id) {
+      if (id === virtualId) return resolvedId;
+      return null;
+    },
+
+    load(id) {
+      if (id !== resolvedId) return null;
+      if (existsSync(filePath)) {
+        // Only watch when it exists — addWatchFile on a missing path makes
+        // Vite's importAnalysis try to resolve it as a real import.
+        this.addWatchFile(filePath);
+        return `export { default } from '${normalizePath(filePath)}';`;
+      }
+      return fallback;
+    },
+
+    configureServer(server: ViteDevServer) {
+      // Only add/unlink flips load()'s output between the override and the
+      // fallback; a `change` leaves it identical and Svelte's own HMR handles
+      // the underlying file.
+      server.watcher.on('all', (event, changed) => {
+        if (changed !== filePath) return;
+        if (event !== 'add' && event !== 'unlink') return;
+        const mod = server.moduleGraph.getModuleById(resolvedId);
+        if (mod) server.moduleGraph.invalidateModule(mod);
+        server.ws.send({ type: 'full-reload' });
+      });
+    },
+  };
+}

package/src/plugin/quiz.ts

@@ -1,65 +1,20 @@
-import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
-import { existsSync } from 'node:fs';
+import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-
-const VIRTUAL_QUIZ_ID = 'virtual:tessera-quiz';
-const RESOLVED_QUIZ_ID = '\0' + VIRTUAL_QUIZ_ID;
+import { createOverridePlugin } from './override-plugin.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/**
- * Resolve the project's quiz shell.
- * `projectRoot/quiz.svelte` overrides the built-in `<Quiz>` if it exists,
- * otherwise the built-in is used. Mirrors `tesseraLayoutPlugin` (Phase 3A).
- */
 export function tesseraQuizPlugin(): Plugin {
-  let projectRoot: string;
-  // Resolve the built-in Quiz.svelte once. The plugin lives in
-  // `dist/plugin/quiz.js` after build and `src/plugin/quiz.ts` in source —
-  // both layouts put `Quiz.svelte` two levels up under `src/components/`.
+  // The plugin lives in `dist/plugin/quiz.js` after build and `src/plugin/quiz.ts`
+  // in source — both put `Quiz.svelte` two levels up under `src/components/`.
   const packageRoot = resolve(__dirname, '..', '..');
   const builtinQuiz = resolve(packageRoot, 'src', 'components', 'Quiz.svelte');
-
-  return {
+  return createOverridePlugin({
     name: 'tessera:quiz',
-    enforce: 'pre',
-
-    configResolved(config: ResolvedConfig) {
-      projectRoot = config.root;
-    },
-
-    resolveId(id) {
-      if (id === VIRTUAL_QUIZ_ID) return RESOLVED_QUIZ_ID;
-      return null;
-    },
-
-    load(id) {
-      if (id !== RESOLVED_QUIZ_ID) return null;
-      const userQuizPath = resolve(projectRoot, 'quiz.svelte');
-      if (existsSync(userQuizPath)) {
-        // Watch the user file so add/remove flips through HMR (see below).
-        this.addWatchFile(userQuizPath);
-        const normalized = userQuizPath.replace(/\\/g, '/');
-        return `export { default } from '${normalized}';`;
-      }
-      const normalized = builtinQuiz.replace(/\\/g, '/');
-      return `export { default } from '${normalized}';`;
-    },
-
-    configureServer(server: ViteDevServer) {
-      const userQuizPath = resolve(projectRoot, 'quiz.svelte');
-      // Only react to add/unlink — those flip the load() output between the
-      // user quiz and the built-in. A `change` event leaves the resolved
-      // module identical and is handled by Svelte's own HMR.
-      server.watcher.on('all', (event, filePath) => {
-        if (filePath !== userQuizPath) return;
-        if (event !== 'add' && event !== 'unlink') return;
-        const mod = server.moduleGraph.getModuleById(RESOLVED_QUIZ_ID);
-        if (mod) server.moduleGraph.invalidateModule(mod);
-        server.ws.send({ type: 'full-reload' });
-      });
-    },
-  };
+    virtualId: 'virtual:tessera-quiz',
+    projectFile: 'quiz.svelte',
+    builtinFile: builtinQuiz,
+  });
 }

package/src/plugin/validation.ts

@@ -3,11 +3,17 @@ import { resolve, relative } from 'node:path';
 import JSON5 from 'json5';
 import {
   extractDefaultExportObjectLiteral,
+  extractObjectLiteral,
   parsePageConfigFromSource,
   readSourceFileCached,
   ensureSvelteSuffix,
+  readCourseConfig,
 } from './manifest.js';
-import { validateAgent } from '../runtime/xapi/agent-rules.js';
+import {
+  validateAgent,
+  validateAuthCredential,
+  joinFieldError,
+} from '../runtime/xapi/agent-rules.js';
 
 // ---------- Types ----------
 
@@ -16,6 +22,16 @@ export interface ValidationResult {
   warnings: string[];
 }
 
+/** Print validation warnings (yellow) then errors (red). Shared by the dev/build plugin and the CLI. */
+export function reportValidationIssues({ errors, warnings }: ValidationResult): void {
+  for (const warning of warnings) {
+    console.warn(`\x1b[33m[tessera warning]\x1b[0m ${warning}`);
+  }
+  for (const error of errors) {
+    console.error(`\x1b[31m[tessera error]\x1b[0m ${error}`);
+  }
+}
+
 // Known top-level config fields
 const KNOWN_CONFIG_FIELDS = new Set([
   'title',
@@ -55,7 +71,7 @@ export function validateProject(projectRoot: string): ValidationResult {
   }
 
   // 2. Parse and validate config
-  const config = parseConfig(configPath, errors, warnings);
+  const config = parseConfig(projectRoot, errors, warnings);
 
   // 3. Validate pages directory
   const pagesDir = resolve(projectRoot, 'pages');
@@ -97,27 +113,25 @@ interface ParsedConfig {
 }
 
 function parseConfig(
-  configPath: string,
+  projectRoot: string,
   errors: string[],
   warnings: string[]
 ): ParsedConfig | null {
-  const objectStr = extractDefaultExportObjectLiteral(readSourceFileCached(configPath));
-  if (!objectStr) {
-    errors.push(
-      'course.config.js: could not parse — must use `export default { ... }` syntax'
-    );
-    return null;
-  }
-
-  let config: ParsedConfig;
-  try {
-    config = JSON5.parse(objectStr);
-  } catch {
-    errors.push(
-      'course.config.js: syntax error — must export a static object literal'
-    );
+  const read = readCourseConfig(projectRoot);
+  if (!read.ok) {
+    // 'missing' can't occur — validateProject checks existsSync first.
+    if (read.reason === 'no-export') {
+      errors.push(
+        'course.config.js: could not parse — must use `export default { ... }` syntax'
+      );
+    } else if (read.reason === 'parse-error') {
+      errors.push(
+        'course.config.js: syntax error — must export a static object literal'
+      );
+    }
     return null;
   }
+  const config = read.config as ParsedConfig;
 
   // Check for unknown fields
   for (const key of Object.keys(config)) {
@@ -360,16 +374,9 @@ function validateSingleXAPIEntry(
   if (auth === undefined) {
     errors.push(`course.config.js: ${label}.auth is required`);
   } else if (typeof auth === 'string') {
-    if (!auth) {
-      errors.push(`course.config.js: ${label}.auth must be a non-empty string`);
-    } else if (/^basic\s/i.test(auth)) {
-      errors.push(
-        `course.config.js: ${label}.auth must be the Basic credential value only, not the full header. Drop the 'Basic ' prefix.`
-      );
-    } else if (/^bearer\s/i.test(auth)) {
-      errors.push(
-        `course.config.js: ${label}.auth: Bearer/OAuth credentials are not supported in v1. Use Basic auth, or wrap your token-exchange in an auth function that returns a Basic credential.`
-      );
+    const authErr = validateAuthCredential(auth);
+    if (authErr) {
+      errors.push(`course.config.js: ${joinFieldError(`${label}.auth`, authErr)}`);
     } else {
       warnings.push(
         `course.config.js: ${label}.auth is a static string and will be embedded in the bundle. ` +
@@ -411,10 +418,7 @@ function validateSingleXAPIEntry(
   } else if (typeof actor === 'object' && actor !== null) {
     const err = validateAgent(actor);
     if (err) {
-      const joined = err.startsWith('.')
-        ? `${label}.actor${err}`
-        : `${label}.actor ${err}`;
-      errors.push(`course.config.js: ${joined}`);
+      errors.push(`course.config.js: ${joinFieldError(`${label}.actor`, err)}`);
     }
   } else if (typeof actor !== 'function') {
     errors.push(
@@ -834,39 +838,6 @@ type PropValue =
   | { kind: 'expr'; raw: string }
   | { kind: 'bool' };
 
-/** Extract a balanced {...} or [...] span starting at startIndex, or null. */
-function extractBalanced(source: string, startIndex: number): string | null {
-  const open = source[startIndex];
-  if (open !== '{' && open !== '[') return null;
-  let depth = 0;
-  let inString: string | null = null;
-  let escaped = false;
-  for (let i = startIndex; i < source.length; i++) {
-    const char = source[i];
-    if (escaped) {
-      escaped = false;
-      continue;
-    }
-    if (char === '\\' && inString) {
-      escaped = true;
-      continue;
-    }
-    if (inString) {
-      if (char === inString) inString = null;
-      continue;
-    }
-    if (char === '"' || char === "'" || char === '`') {
-      inString = char;
-      continue;
-    }
-    if (char === '{' || char === '[') depth++;
-    if (char === '}' || char === ']') {
-      depth--;
-      if (depth === 0) return source.slice(startIndex, i + 1);
-    }
-  }
-  return null;
-}
 
 /**
  * Parse the props of an opening tag starting just after the component name.
@@ -884,7 +855,7 @@ function parseTagProps(content: string, start: number): Map<string, PropValue> |
     if (c === '/' && content[i + 1] === '>') return props;
     // Spread / shorthand expression — skip the whole {...} block.
     if (c === '{') {
-      const block = extractBalanced(content, i);
+      const block = extractObjectLiteral(content, i);
       if (!block) return null;
       i += block.length;
       continue;
@@ -907,7 +878,7 @@ function parseTagProps(content: string, start: number): Map<string, PropValue> |
       props.set(propName, { kind: 'string', value: content.slice(i + 1, end) });
       i = end + 1;
     } else if (v === '{') {
-      const block = extractBalanced(content, i);
+      const block = extractObjectLiteral(content, i);
       if (!block) return null;
       props.set(propName, { kind: 'expr', raw: block.slice(1, -1).trim() });
       i += block.length;

package/src/runtime/App.svelte

@@ -5,14 +5,14 @@
   import UserLayout from 'virtual:tessera-layout';
   import Quiz from 'virtual:tessera-quiz';
   import { onMount, onDestroy, setContext, untrack } from 'svelte';
-  import LoadingSkeleton from './LoadingSkeleton.svelte';
+  import LoadingBar from './LoadingBar.svelte';
   import ErrorPage from './ErrorPage.svelte';
   import DefaultLayout from '../components/DefaultLayout.svelte';
   import { NavigationState } from './navigation.svelte.js';
   import { ProgressState } from './progress.svelte.js';
   import { DurationTracker } from './duration.js';
-  import { createAdapter } from './adapters/index.js';
-  import { buildXAPIClient } from './xapi/setup.js';
+  import { createAdapter } from 'virtual:tessera-adapter';
+  import { buildXAPIClient } from 'virtual:tessera-xapi-setup';
   import { registerXAPIClient } from './xapi/registry.js';
   import { TESSERA_PAGE, TESSERA_NAV, TESSERA_ADAPTER, TESSERA_USER_STATE } from './contexts.js';
 
@@ -24,12 +24,19 @@
   // can reach it.
   let xapiClient = null;
 
+  const gradedQuizIndices = new Set(
+    manifest.pages.filter(p => p.quiz?.graded).map(p => p.index)
+  );
+
   // ---- State classes ----
-  const progress = new ProgressState();
+  const progress = new ProgressState(gradedQuizIndices);
   const nav = new NavigationState(manifest, progress, config);
+  nav.setPageModules(pageModules);
   let duration = $state(new DurationTracker(0));
 
-  const gradedQuizIndices = manifest.pages.filter(p => p.quiz?.graded).map(p => p.index);
+  const onIdle = typeof window !== 'undefined' && window.requestIdleCallback
+    ? window.requestIdleCallback.bind(window)
+    : (cb) => setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 50 }), 1);
 
   // Page loading state
   let PageComponent = $state(null);
@@ -84,22 +91,20 @@
 
     const gen = ++loadGeneration;
     pageLoading = true;
-    pageError = null;
-    PageComponent = null;
-
-    // Update context for the new page
-    pageContext.quiz = page.quiz;
 
     const loader = pageModules[page.importPath];
     if (!loader) {
       console.error(`Tessera: No loader for page ${index} at ${page.importPath}`);
       pageError = new Error(`Page not found: ${page.importPath}`);
+      PageComponent = null;
       pageLoading = false;
       return;
     }
 
     loader().then(mod => {
       if (gen !== loadGeneration) return; // stale
+      pageError = null;
+      pageContext.quiz = page.quiz;
       PageComponent = mod.default;
       pageLoading = false;
       progress.markVisited(index);
@@ -109,8 +114,9 @@
       ) {
         progress.markCompleteManually();
       }
-      progress.recalculateCompletion(manifest, config);
-      progress.recalculateSuccess(manifest, config);
+      progress.recalculateCompletion(manifest.totalPages, config);
+      progress.recalculateSuccess(config);
+      onIdle(() => nav.prefetch(index + 1));
     }).catch(err => {
       if (gen !== loadGeneration) return; // stale
       console.error(`Tessera: Failed to load page ${index}`, err);
@@ -132,18 +138,25 @@
   }
 
   // ---- Branding ----
+  // Two sentinels so the validity check doesn't false-positive when the
+  // input happens to normalize to the initial fillStyle ("#000000").
   function parseColor(color) {
     if (typeof CSS !== 'undefined' && CSS.supports && !CSS.supports('color', color)) {
       return null;
     }
-    const el = document.createElement('span');
-    el.style.color = color;
-    document.documentElement.appendChild(el);
-    const computed = getComputedStyle(el).color;
-    el.remove();
-    const match = computed.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-    if (!match) return null;
-    return { r: +match[1], g: +match[2], b: +match[3] };
+    const ctx = document.createElement('canvas').getContext('2d');
+    if (!ctx) return null;
+    ctx.fillStyle = '#000';
+    ctx.fillStyle = color;
+    const onBlack = ctx.fillStyle;
+    ctx.fillStyle = '#fff';
+    ctx.fillStyle = color;
+    const onWhite = ctx.fillStyle;
+    if (onBlack !== onWhite) return null;
+    const hex = String(onBlack).match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+    if (hex) return { r: parseInt(hex[1], 16), g: parseInt(hex[2], 16), b: parseInt(hex[3], 16) };
+    const rgba = String(onBlack).match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+    return rgba ? { r: +rgba[1], g: +rgba[2], b: +rgba[3] } : null;
   }
 
   function rgbToHsl(r, g, b) {
@@ -181,8 +194,8 @@
     const { score } = e.detail;
     const pageIndex = nav.currentPageIndex;
     progress.quizCompleted(pageIndex, score);
-    progress.recalculateCompletion(manifest, config);
-    progress.recalculateSuccess(manifest, config);
+    progress.recalculateCompletion(manifest.totalPages, config);
+    progress.recalculateSuccess(config);
   }
 
   // ---- Persistence: serialize / restore ----
@@ -251,8 +264,8 @@
       progress.markCompleteManually();
     }
     // Recalculate derived state
-    progress.recalculateCompletion(manifest, config);
-    progress.recalculateSuccess(manifest, config);
+    progress.recalculateCompletion(manifest.totalPages, config);
+    progress.recalculateSuccess(config);
     // Navigate to bookmark (after state is restored so locking is correct)
     if (saved.b > 0 && saved.b < manifest.totalPages) {
       nav.goToPage(saved.b);
@@ -293,20 +306,20 @@
 
   // ---- Persistence: report score/completion/success to adapter ----
   // These are no-ops for WebAdapter but used by LMS adapters (Step 10)
+  let prevReportedScore = $state(null);
   $effect(() => {
-    const scores = progress.quizScores;
-    if (!persistenceReady || scores.size === 0) return;
-    if (gradedQuizIndices.length === 0) return;
+    void progress.version;
+    if (!persistenceReady) return;
 
-    const completedGraded = gradedQuizIndices.filter(i => scores.has(i));
-    if (completedGraded.length === 0) return;
+    const { average, attempted } = progress.gradedScore();
+    if (!attempted) return;
 
-    // Divide by total graded count — incomplete quizzes count as 0, matching
-    // the recalculateSuccess logic in progress.svelte.ts.
-    const average = completedGraded.reduce((sum, i) => sum + (scores.get(i) ?? 0), 0) / gradedQuizIndices.length;
+    const rounded = Math.round(average);
+    if (rounded === prevReportedScore) return;
+    prevReportedScore = rounded;
 
     untrack(() => {
-      adapter.setScore(Math.round(average));
+      adapter.setScore(rounded);
       // Under manual mode, success is owned by requireSuccessStatus.
       if (config.completion.mode !== 'manual') {
         adapter.setSuccessStatus(average >= config.scoring.passingScore ? 'passed' : 'failed');
@@ -463,9 +476,7 @@
 </script>
 
 {#snippet page()}
-  {#if pageLoading}
-    <LoadingSkeleton />
-  {:else if pageError}
+  {#if pageError}
     <ErrorPage error={pageError} onretry={retryPage} />
   {:else if PageComponent}
     {#if pageContext.quiz}
@@ -479,6 +490,7 @@
 {/snippet}
 
 <div id="tessera-app" data-chrome={chromeMode}>
+  <LoadingBar active={pageLoading} />
   {#if UserLayout}
     <UserLayout {page} />
   {:else if chromeMode === 'custom'}

package/src/runtime/LoadingBar.svelte

@@ -0,0 +1,47 @@
+<script>
+  import { untrack } from 'svelte';
+
+  let { active = false } = $props();
+
+  let visible = $state(false);
+  let appeared = $state(false);
+  let complete = $state(false);
+  let showSlowMessage = $state(false);
+
+  $effect(() => {
+    if (active) {
+      // Defer the bar so sub-100ms loads never flash. Add `.appear` on the
+      // next frame so the CSS transition from width:0 → 90% actually fires.
+      const appearTimer = setTimeout(() => {
+        visible = true;
+        requestAnimationFrame(() => { appeared = true; });
+      }, 100);
+      const slowTimer = setTimeout(() => { showSlowMessage = true; }, 5000);
+      return () => {
+        clearTimeout(appearTimer);
+        clearTimeout(slowTimer);
+      };
+    }
+
+    // Completing. If the bar never appeared we have nothing to finish.
+    // untrack so flipping `visible` doesn't re-trigger this effect.
+    if (!untrack(() => visible)) return;
+    complete = true;
+    const hideTimer = setTimeout(() => {
+      visible = false;
+      appeared = false;
+      complete = false;
+      showSlowMessage = false;
+    }, 220);
+    return () => clearTimeout(hideTimer);
+  });
+</script>
+
+{#if visible}
+  <div class="tessera-loading-bar" class:appear={appeared} class:complete aria-hidden="true">
+    <div class="tessera-loading-bar-fill"></div>
+  </div>
+  {#if showSlowMessage}
+    <p class="tessera-loading-bar-message" role="status">Still loading…</p>
+  {/if}
+{/if}

package/src/runtime/Sidebar.svelte

@@ -60,6 +60,8 @@
               aria-current={page.index === currentPageIndex ? 'page' : undefined}
               aria-disabled={locked ? 'true' : undefined}
               onclick={() => handlePageClick(page.index)}
+              onpointerenter={() => !locked && nav.prefetch(page.index)}
+              onfocusin={() => !locked && nav.prefetch(page.index)}
             >
               {#if locked}
                 <svg class="tessera-nav-lock-icon" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true" width="12" height="12">