explico 0.3.0 → 0.5.0

package/src/compiler/exports/standalone-html.ts

@@ -0,0 +1,963 @@
+import { build } from 'esbuild';
+import {
+  mkdir,
+  readFile,
+  rename,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import { Buffer } from 'node:buffer';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  parse,
+  serialize,
+  type DefaultTreeAdapterMap,
+} from 'parse5';
+
+import type { Manifest } from '../manifest';
+
+type HtmlNode = DefaultTreeAdapterMap['node'];
+type HtmlParent = DefaultTreeAdapterMap['parentNode'];
+type HtmlChild = DefaultTreeAdapterMap['childNode'];
+type HtmlElement = DefaultTreeAdapterMap['element'];
+type HtmlText = DefaultTreeAdapterMap['textNode'];
+
+const HTML_NAMESPACE =
+  'http://www.w3.org/1999/xhtml' as HtmlElement['namespaceURI'];
+const CSS_URL = /url\(\s*(?:(["'])(.*?)\1|([^)]*?))\s*\)/giu;
+const CSS_IMPORT =
+  /@import\s+(?:url\(\s*(?:(["'])(.*?)\1|([^)]*?))\s*\)|(["'])(.*?)\4)\s*([^;]*);/giu;
+const LOCAL_IMPORT =
+  /(?:\bimport\s*\(\s*|\bfrom\s+)(["'])(?!data:)([^"']+)\1/gu;
+
+const MIME_TYPES: Readonly<Record<string, string>> = {
+  '.avif': 'image/avif',
+  '.gif': 'image/gif',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.mp3': 'audio/mpeg',
+  '.mp4': 'video/mp4',
+  '.ogg': 'audio/ogg',
+  '.otf': 'font/otf',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.ttf': 'font/ttf',
+  '.wasm': 'application/wasm',
+  '.wav': 'audio/wav',
+  '.webm': 'video/webm',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+const STANDALONE_STYLE = `
+html[data-explico-standalone] {
+  min-width: 0;
+}
+html[data-explico-standalone] body {
+  display: block;
+  margin: 0;
+  min-width: 0;
+}
+html[data-explico-standalone] main {
+  margin-inline: auto;
+  max-width: calc(var(--sl-content-width, 45rem) + 3rem);
+  min-width: 0;
+  width: 100%;
+}
+html[data-explico-standalone] main > .content-panel {
+  padding-inline: 1.5rem;
+}
+html[data-explico-standalone] .sl-skip-link:focus {
+  z-index: 10000;
+}
+html[data-explico-standalone] .explico-standalone-theme {
+  align-items: center;
+  background: var(--sl-color-bg-nav, var(--sl-color-bg));
+  border: 1px solid var(--sl-color-gray-5);
+  border-radius: 0.5rem;
+  box-shadow: var(--sl-shadow-md);
+  display: flex;
+  inset-block-start: 0.75rem;
+  inset-inline-end: 0.75rem;
+  padding: 0.3rem 0.45rem;
+  position: fixed;
+  z-index: 100;
+}
+@media print {
+  html[data-explico-standalone] .explico-standalone-theme {
+    display: none;
+  }
+}
+@media (max-width: 30rem) {
+  html[data-explico-standalone] main > .content-panel {
+    padding-inline: 1rem;
+  }
+}
+`;
+
+const STANDALONE_THEME_SCRIPT = `(() => {
+  const root = document.documentElement;
+  const picker = document.querySelector('[data-explico-standalone-theme] select');
+  if (!(picker instanceof HTMLSelectElement)) return;
+  const media = window.matchMedia('(prefers-color-scheme: light)');
+  const parse = (value) => value === 'light' || value === 'dark' ? value : 'auto';
+  const apply = (theme) => {
+    picker.value = theme;
+    window.StarlightThemeProvider?.updatePickers(theme);
+    root.dataset.theme = theme === 'auto' ? (media.matches ? 'light' : 'dark') : theme;
+  };
+  picker.addEventListener('change', () => apply(parse(picker.value)));
+  media.addEventListener('change', () => {
+    if (picker.value === 'auto') apply('auto');
+  });
+  apply('auto');
+})();`;
+
+/** Inputs for producing one standalone lesson from Astro's final HTML. */
+export interface StandaloneLessonInput {
+  readonly html: string;
+  readonly sourceFile: string;
+  readonly outputRoot: string;
+  readonly lessonSlug: string;
+  readonly canonicalBaseUrl?: string;
+}
+
+interface BrowserBundle {
+  readonly code: string;
+  readonly css: readonly string[];
+}
+
+interface RegistryRequest {
+  readonly path: string;
+  readonly exportPath: readonly string[];
+  readonly key: string;
+  readonly island: HtmlElement;
+  readonly attributeName: string;
+}
+
+interface ExportContext {
+  readonly outputRoot: string;
+  readonly sourceFile: string;
+  readonly assetData: Map<string, string>;
+}
+
+function isElement(node: HtmlNode): node is HtmlElement {
+  return 'tagName' in node;
+}
+
+function childrenOf(node: HtmlNode): readonly HtmlChild[] {
+  return 'childNodes' in node ? node.childNodes : [];
+}
+
+function walk(node: HtmlNode, visit: (node: HtmlNode) => void): void {
+  visit(node);
+  for (const child of childrenOf(node)) walk(child, visit);
+  if (isElement(node) && node.tagName === 'template') {
+    const template = node as DefaultTreeAdapterMap['template'];
+    for (const child of template.content.childNodes) walk(child, visit);
+  }
+}
+
+function elements(root: HtmlNode, predicate?: (node: HtmlElement) => boolean): HtmlElement[] {
+  const found: HtmlElement[] = [];
+  walk(root, (node) => {
+    if (isElement(node) && (predicate?.(node) ?? true)) found.push(node);
+  });
+  return found;
+}
+
+function firstElement(root: HtmlNode, tagName: string): HtmlElement {
+  const found = elements(root, (node) => node.tagName === tagName)[0];
+  if (!found) throw new Error(`Standalone HTML source has no <${tagName}> element.`);
+  return found;
+}
+
+function attribute(node: HtmlElement, name: string): string | undefined {
+  return node.attrs.find((entry) => entry.name === name)?.value;
+}
+
+function hasClass(node: HtmlElement, name: string): boolean {
+  return (attribute(node, 'class') ?? '').split(/\s+/u).includes(name);
+}
+
+function setAttribute(node: HtmlElement, name: string, value = ''): void {
+  const existing = node.attrs.find((entry) => entry.name === name);
+  if (existing) existing.value = value;
+  else node.attrs.push({ name, value });
+}
+
+function removeAttribute(node: HtmlElement, name: string): void {
+  const index = node.attrs.findIndex((entry) => entry.name === name);
+  if (index !== -1) node.attrs.splice(index, 1);
+}
+
+function removeNode(node: HtmlElement): void {
+  const parent = node.parentNode;
+  if (!parent || !('childNodes' in parent)) return;
+  const index = parent.childNodes.indexOf(node);
+  if (index !== -1) parent.childNodes.splice(index, 1);
+  node.parentNode = null;
+}
+
+function textElement(tagName: string, text: string): HtmlElement {
+  const element: HtmlElement = {
+    nodeName: tagName,
+    tagName,
+    attrs: [],
+    namespaceURI: HTML_NAMESPACE,
+    parentNode: null,
+    childNodes: [],
+  };
+  const textNode: HtmlText = {
+    nodeName: '#text',
+    value: text,
+    parentNode: element,
+  };
+  element.childNodes.push(textNode);
+  return element;
+}
+
+function append(parent: HtmlParent, child: HtmlChild): void {
+  parent.childNodes.push(child);
+  if ('parentNode' in child) child.parentNode = parent;
+}
+
+function replaceNode(node: HtmlElement, replacement: HtmlElement): void {
+  const parent = node.parentNode;
+  if (!parent || !('childNodes' in parent)) {
+    throw new Error(`Cannot replace detached <${node.tagName}>.`);
+  }
+  const index = parent.childNodes.indexOf(node);
+  if (index === -1) throw new Error(`Cannot find <${node.tagName}> in its parent.`);
+  replacement.parentNode = parent;
+  parent.childNodes[index] = replacement;
+  node.parentNode = null;
+}
+
+function textContent(node: HtmlElement): string {
+  return node.childNodes
+    .filter((child): child is HtmlText => child.nodeName === '#text')
+    .map((child) => child.value)
+    .join('');
+}
+
+function setTextContent(node: HtmlElement, text: string): void {
+  node.childNodes.splice(0, node.childNodes.length);
+  const child: HtmlText = { nodeName: '#text', value: text, parentNode: node };
+  node.childNodes.push(child);
+}
+
+function insideRoot(path: string, root: string): boolean {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !rel.startsWith(sep));
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function cleanReference(reference: string): string {
+  return reference.split(/[?#]/u, 1)[0] ?? '';
+}
+
+function isEmbeddedReference(reference: string): boolean {
+  return /^(?:data:|#)/iu.test(reference.trim());
+}
+
+function hasScheme(reference: string): boolean {
+  return /^[a-z][a-z\d+.-]*:/iu.test(reference.trim());
+}
+
+async function resolveLocalFile(
+  reference: string,
+  declaringFile: string,
+  outputRoot: string,
+): Promise<string> {
+  const trimmed = reference.trim();
+  if (!trimmed || isEmbeddedReference(trimmed)) {
+    throw new Error(`Expected a local file reference, received ${JSON.stringify(reference)}.`);
+  }
+  if (trimmed.startsWith('//') || hasScheme(trimmed)) {
+    throw new Error(
+      `Standalone HTML cannot load remote render dependency ${JSON.stringify(reference)}.`,
+    );
+  }
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(cleanReference(trimmed));
+  } catch {
+    throw new Error(`Malformed asset URL in standalone HTML: ${JSON.stringify(reference)}.`);
+  }
+
+  const candidates: string[] = [];
+  if (decoded.startsWith('/')) {
+    const segments = decoded.split('/').filter(Boolean);
+    for (let index = 0; index < segments.length; index += 1) {
+      candidates.push(resolve(outputRoot, ...segments.slice(index)));
+    }
+  } else {
+    candidates.push(resolve(dirname(declaringFile), decoded));
+  }
+
+  for (const candidate of candidates) {
+    if (insideRoot(candidate, outputRoot) && (await isFile(candidate))) return candidate;
+  }
+  throw new Error(
+    `Standalone HTML could not resolve render dependency ${JSON.stringify(reference)} ` +
+      `from ${relative(outputRoot, declaringFile)}.`,
+  );
+}
+
+function mimeType(path: string): string {
+  const type = MIME_TYPES[extname(path).toLowerCase()];
+  if (!type) {
+    throw new Error(
+      `Standalone HTML does not know the MIME type for ${JSON.stringify(path)}.`,
+    );
+  }
+  return type;
+}
+
+async function assetDataUrl(path: string, context: ExportContext): Promise<string> {
+  const cached = context.assetData.get(path);
+  if (cached) return cached;
+  const data = `data:${mimeType(path)};base64,${(await readFile(path)).toString('base64')}`;
+  context.assetData.set(path, data);
+  return data;
+}
+
+function splitCssSources(value: string): string[] {
+  const sources: string[] = [];
+  let start = 0;
+  let depth = 0;
+  let quote = '';
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index] ?? '';
+    if (quote) {
+      if (character === quote && value[index - 1] !== '\\') quote = '';
+    } else if (character === '"' || character === "'") {
+      quote = character;
+    } else if (character === '(') {
+      depth += 1;
+    } else if (character === ')') {
+      depth = Math.max(0, depth - 1);
+    } else if (character === ',' && depth === 0) {
+      sources.push(value.slice(start, index).trim());
+      start = index + 1;
+    }
+  }
+  sources.push(value.slice(start).trim());
+  return sources.filter(Boolean);
+}
+
+/** Prefer one modern font payload instead of embedding every fallback format. */
+function modernFontSources(css: string): string {
+  return css.replace(/@font-face\s*\{[\s\S]*?\}/giu, (block) =>
+    block.replace(/\bsrc\s*:\s*([^;]+);/iu, (declaration, value: string) => {
+      const sources = splitCssSources(value);
+      const modern = sources.find(
+        (source) => /format\(\s*["']?woff2["']?\s*\)/iu.test(source) || /\.woff2(?:[?#"')]|$)/iu.test(source),
+      );
+      return modern ? `src: ${modern};` : declaration;
+    }),
+  );
+}
+
+async function inlineCssUrls(
+  css: string,
+  declaringFile: string,
+  context: ExportContext,
+  importStack: ReadonlySet<string> = new Set(),
+): Promise<string> {
+  let imported = '';
+  let importIndex = 0;
+  const importPattern = new RegExp(CSS_IMPORT.source, CSS_IMPORT.flags);
+  for (
+    let match = importPattern.exec(css);
+    match;
+    match = importPattern.exec(css)
+  ) {
+    imported += css.slice(importIndex, match.index);
+    const reference = (match[2] ?? match[3] ?? match[5] ?? '').trim();
+    if (reference.startsWith('data:')) {
+      imported += match[0];
+    } else {
+      const path = await resolveLocalFile(reference, declaringFile, context.outputRoot);
+      if (importStack.has(path)) {
+        throw new Error(
+          `Standalone HTML found a circular CSS @import through ${relative(context.outputRoot, path)}.`,
+        );
+      }
+      const nested = await inlineCssUrls(await readFile(path, 'utf8'), path, context, new Set([...importStack, path]));
+      const media = (match[6] ?? '').trim();
+      imported += media ? `@media ${media}{${nested}}` : nested;
+    }
+    importIndex = match.index + match[0].length;
+  }
+  imported += css.slice(importIndex);
+
+  const source = modernFontSources(imported);
+  let rewritten = '';
+  let lastIndex = 0;
+  CSS_URL.lastIndex = 0;
+  for (let match = CSS_URL.exec(source); match; match = CSS_URL.exec(source)) {
+    rewritten += source.slice(lastIndex, match.index);
+    const reference = (match[2] ?? match[3] ?? '').trim();
+    if (!reference || isEmbeddedReference(reference)) {
+      rewritten += match[0];
+    } else {
+      const file = await resolveLocalFile(reference, declaringFile, context.outputRoot);
+      rewritten += `url("${await assetDataUrl(file, context)}")`;
+    }
+    lastIndex = match.index + match[0].length;
+  }
+  return rewritten + source.slice(lastIndex);
+}
+
+async function bundleBrowserGraph(
+  entryPaths: readonly string[],
+  requests: readonly RegistryRequest[],
+  context: ExportContext,
+): Promise<BrowserBundle> {
+  const moduleIds = new Map<string, string>();
+  for (const request of requests) {
+    if (!moduleIds.has(request.path)) {
+      moduleIds.set(request.path, `standaloneModule${moduleIds.size}`);
+    }
+  }
+  const entryImports = entryPaths.map((path) => `import ${JSON.stringify(path)};`);
+  const moduleImports = [...moduleIds].map(
+    ([path, identifier]) => `import * as ${identifier} from ${JSON.stringify(path)};`,
+  );
+  const assignments = requests.map((request) => {
+    const identifier = moduleIds.get(request.path)!;
+    const selected = request.exportPath.reduce(
+      (expression, part) => `${expression}[${JSON.stringify(part)}]`,
+      identifier,
+    );
+    return `standaloneRegistry[${JSON.stringify(request.key)}] = ${selected};`;
+  });
+  const source = [
+    ...entryImports,
+    ...moduleImports,
+    `const standaloneRegistry = globalThis[Symbol.for('explico.standalone.modules')] = Object.create(null);`,
+    ...assignments,
+  ].join('\n');
+
+  const result = await build({
+    absWorkingDir: context.outputRoot,
+    bundle: true,
+    format: 'esm',
+    stdin: {
+      contents: source,
+      loader: 'js',
+      resolveDir: context.outputRoot,
+      sourcefile: 'explico-standalone-browser-entry.js',
+    },
+    legalComments: 'none',
+    loader: {
+      '.avif': 'dataurl',
+      '.gif': 'dataurl',
+      '.jpeg': 'dataurl',
+      '.jpg': 'dataurl',
+      '.mp3': 'dataurl',
+      '.mp4': 'dataurl',
+      '.ogg': 'dataurl',
+      '.otf': 'dataurl',
+      '.png': 'dataurl',
+      '.svg': 'dataurl',
+      '.ttf': 'dataurl',
+      '.wasm': 'dataurl',
+      '.wav': 'dataurl',
+      '.webm': 'dataurl',
+      '.webp': 'dataurl',
+      '.woff': 'dataurl',
+      '.woff2': 'dataurl',
+    },
+    logLevel: 'silent',
+    outdir: join(context.outputRoot, '.explico-browser-bundle'),
+    platform: 'browser',
+    target: 'es2022',
+    write: false,
+  });
+  const javascript = result.outputFiles.find((file) => file.path.endsWith('.js'));
+  if (!javascript) {
+    throw new Error('Browser bundler produced no JavaScript for the standalone lesson.');
+  }
+  const unsupported = result.outputFiles.filter(
+    (file) => !file.path.endsWith('.js') && !file.path.endsWith('.css'),
+  );
+  if (unsupported.length > 0) {
+    throw new Error(
+      `Browser bundler emitted unsupported standalone assets for ` +
+        `the lesson: ${unsupported.map((file) => file.path).join(', ')}.`,
+    );
+  }
+  const code = javascript.text.replace(/<\/script/giu, '<\\/script');
+  return {
+    code,
+    css: result.outputFiles
+      .filter((file) => file.path.endsWith('.css'))
+      .map((file) => file.text),
+  };
+}
+
+function inferBasePrefix(document: HtmlNode): string {
+  for (const node of elements(document)) {
+    for (const name of ['href', 'src', 'component-url', 'renderer-url']) {
+      const value = attribute(node, name);
+      if (!value?.startsWith('/')) continue;
+      const marker = value.indexOf('/astro-assets/');
+      if (marker !== -1) return `${value.slice(0, marker)}/`;
+    }
+  }
+  return '/';
+}
+
+function normalizedPagePath(pathname: string): string {
+  return pathname.replace(/\/index\.html$/iu, '/').replace(/\.html$/iu, '').replace(/\/+$/u, '');
+}
+
+function rewriteCourseLink(
+  href: string,
+  lessonSlug: string,
+  basePrefix: string,
+  canonicalBaseUrl: string | undefined,
+): string {
+  const trimmed = href.trim();
+  if (!trimmed || trimmed.startsWith('#')) return href;
+  if (/^(?:https?:|mailto:|tel:)/iu.test(trimmed) || trimmed.startsWith('//')) return href;
+  if (hasScheme(trimmed)) {
+    throw new Error(`Standalone HTML cannot publish local navigation URL ${JSON.stringify(href)}.`);
+  }
+
+  const pagePath = `${basePrefix}${lessonSlug}/`.replace(/\/{2,}/gu, '/');
+  const resolved = new URL(trimmed, `https://explico.invalid${pagePath}`);
+  if (normalizedPagePath(resolved.pathname) === normalizedPagePath(pagePath)) {
+    return `${resolved.search}${resolved.hash}` || '#_top';
+  }
+  if (!canonicalBaseUrl) {
+    throw new Error(
+      `Lesson ${lessonSlug} links outside itself (${JSON.stringify(href)}), so ` +
+        '`lessonExports.canonicalBaseUrl` is required for standalone HTML.',
+    );
+  }
+  let coursePath = resolved.pathname;
+  if (coursePath.startsWith(basePrefix)) coursePath = coursePath.slice(basePrefix.length);
+  const canonical = new URL(coursePath.replace(/^\/+/, ''), canonicalBaseUrl);
+  canonical.search = resolved.search;
+  canonical.hash = resolved.hash;
+  return canonical.toString();
+}
+
+function reduceToLessonShell(document: HtmlNode): void {
+  const html = firstElement(document, 'html');
+  const body = firstElement(document, 'body');
+  const main = firstElement(body, 'main');
+  const skipLink = elements(body, (node) => hasClass(node, 'sl-skip-link'))[0];
+  const themeSelect = elements(
+    body,
+    (node) => node.tagName === 'starlight-theme-select',
+  )[0];
+
+  for (const chrome of elements(main, (node) => attribute(node, 'data-explico-export-chrome') !== undefined)) {
+    removeNode(chrome);
+  }
+  removeAttribute(main, 'data-pagefind-body');
+  setAttribute(html, 'data-explico-standalone');
+  removeAttribute(html, 'data-has-sidebar');
+  removeAttribute(html, 'data-has-toc');
+
+  body.childNodes.splice(0, body.childNodes.length);
+  if (skipLink) append(body, skipLink);
+  if (themeSelect) {
+    const themeControl = textElement('div', '');
+    themeControl.childNodes.splice(0, themeControl.childNodes.length);
+    setAttribute(themeControl, 'class', 'explico-standalone-theme');
+    setAttribute(themeControl, 'data-explico-standalone-theme');
+    setAttribute(themeControl, 'role', 'group');
+    setAttribute(themeControl, 'aria-label', 'Appearance');
+    append(themeControl, themeSelect);
+    append(body, themeControl);
+    const themeScript = textElement('script', STANDALONE_THEME_SCRIPT);
+    setAttribute(themeScript, 'data-explico-standalone-theme-script');
+    append(body, themeScript);
+  }
+  append(body, main);
+}
+
+async function inlineStyles(document: HtmlNode, context: ExportContext): Promise<void> {
+  for (const link of elements(document, (node) => node.tagName === 'link')) {
+    const rel = (attribute(link, 'rel') ?? '').toLowerCase().split(/\s+/u);
+    if (rel.includes('stylesheet')) {
+      const href = attribute(link, 'href');
+      if (!href) throw new Error('Standalone HTML found a stylesheet without href.');
+      const path = await resolveLocalFile(href, context.sourceFile, context.outputRoot);
+      const style = textElement(
+        'style',
+        (await inlineCssUrls(await readFile(path, 'utf8'), path, context)).replace(
+          /<\/style/giu,
+          '<\\/style',
+        ),
+      );
+      const media = attribute(link, 'media');
+      if (media) setAttribute(style, 'media', media);
+      replaceNode(link, style);
+    } else if (
+      rel.some((value) =>
+        ['icon', 'modulepreload', 'preload', 'prefetch'].includes(value),
+      )
+    ) {
+      removeNode(link);
+    }
+  }
+
+  for (const style of elements(document, (node) => node.tagName === 'style')) {
+    setTextContent(
+      style,
+      (await inlineCssUrls(textContent(style), context.sourceFile, context)).replace(
+        /<\/style/giu,
+        '<\\/style',
+      ),
+    );
+  }
+}
+
+async function inlineScripts(document: HtmlNode, context: ExportContext): Promise<void> {
+  const head = firstElement(document, 'head');
+  const entryPaths: string[] = [];
+  let insertionPoint: HtmlElement | undefined;
+  for (const script of elements(document, (node) => node.tagName === 'script')) {
+    const src = attribute(script, 'src');
+    if (!src) continue;
+    const path = await resolveLocalFile(src, context.sourceFile, context.outputRoot);
+    const source = await readFile(path, 'utf8');
+    // Astro's page-prefetch entry belongs to navigation that the lesson shell
+    // intentionally removed. Keeping it would turn link hover into networking.
+    if (source.includes('dataset.astroPrefetch') && source.includes('prefetch')) {
+      removeNode(script);
+      continue;
+    }
+    entryPaths.push(path);
+    if (!insertionPoint) insertionPoint = script;
+    else removeNode(script);
+  }
+
+  const requests: RegistryRequest[] = [];
+  let requestNumber = 0;
+  for (const island of elements(document, (node) => node.tagName === 'astro-island')) {
+    for (const name of ['component-url', 'renderer-url', 'before-hydration-url']) {
+      const reference = attribute(island, name);
+      if (!reference) continue;
+      const path = await resolveLocalFile(reference, context.sourceFile, context.outputRoot);
+      const key = `module-${requestNumber++}`;
+      requests.push({
+        path,
+        exportPath:
+          name === 'component-url'
+            ? (attribute(island, 'component-export') ?? 'default').split('.')
+            : name === 'renderer-url'
+              ? ['default']
+              : [],
+        key,
+        island,
+        attributeName: name,
+      });
+      if (name === 'component-url') setAttribute(island, 'component-export', 'default');
+    }
+  }
+
+  if (entryPaths.length === 0 && requests.length === 0) return;
+  const bundle = await bundleBrowserGraph(entryPaths, requests, context);
+  for (const css of bundle.css) {
+    append(
+      head,
+      textElement(
+        'style',
+        (await inlineCssUrls(css, context.sourceFile, context)).replace(
+          /<\/style/giu,
+          '<\\/style',
+        ),
+      ),
+    );
+  }
+
+  const graphScript = insertionPoint ?? textElement('script', '');
+  removeAttribute(graphScript, 'src');
+  removeAttribute(graphScript, 'integrity');
+  removeAttribute(graphScript, 'crossorigin');
+  setAttribute(graphScript, 'type', 'module');
+  setAttribute(graphScript, 'data-explico-standalone-browser-graph');
+  setTextContent(graphScript, bundle.code);
+  if (!insertionPoint) append(head, graphScript);
+
+  for (const request of requests) {
+    const adapter =
+      `const registry=globalThis[Symbol.for('explico.standalone.modules')];` +
+      `if(!registry)throw new Error('Explico standalone module registry is unavailable');` +
+      `const value=registry[${JSON.stringify(request.key)}];export{value as default};`;
+    setAttribute(
+      request.island,
+      request.attributeName,
+      `data:text/javascript;base64,${Buffer.from(adapter).toString('base64')}`,
+    );
+  }
+}
+
+async function inlineResourceAttribute(
+  node: HtmlElement,
+  name: string,
+  context: ExportContext,
+): Promise<void> {
+  const reference = attribute(node, name);
+  if (!reference || isEmbeddedReference(reference)) return;
+  const path = await resolveLocalFile(reference, context.sourceFile, context.outputRoot);
+  setAttribute(node, name, await assetDataUrl(path, context));
+}
+
+function parseSourceSet(value: string): readonly { url: string; descriptor: string }[] {
+  const candidates = value.match(/(?:[^\s,]+)(?:\s+(?:\d+w|\d+(?:\.\d+)?x))?/gu) ?? [];
+  return candidates.map((candidate) => {
+    const [url = '', descriptor = ''] = candidate.trim().split(/\s+/, 2);
+    return { url, descriptor };
+  });
+}
+
+async function inlineMedia(document: HtmlNode, context: ExportContext): Promise<void> {
+  const resources: Readonly<Record<string, readonly string[]>> = {
+    audio: ['src'],
+    embed: ['src'],
+    img: ['src'],
+    input: ['src'],
+    link: ['href'],
+    object: ['data'],
+    source: ['src'],
+    track: ['src'],
+    video: ['src', 'poster'],
+  };
+  for (const node of elements(document)) {
+    if (node.tagName === 'iframe' && attribute(node, 'src')) {
+      throw new Error(
+        'Standalone HTML does not support an iframe src; use self-contained semantic DOM instead.',
+      );
+    }
+    const names = resources[node.tagName] ?? [];
+    for (const name of names) await inlineResourceAttribute(node, name, context);
+    if (node.tagName === 'use' || node.tagName === 'image') {
+      for (const name of ['href', 'xlink:href']) {
+        const reference = attribute(node, name);
+        if (!reference || isEmbeddedReference(reference)) continue;
+        const hash = reference.includes('#') ? `#${reference.split('#').slice(1).join('#')}` : '';
+        const path = await resolveLocalFile(
+          reference,
+          context.sourceFile,
+          context.outputRoot,
+        );
+        setAttribute(node, name, `${await assetDataUrl(path, context)}${hash}`);
+      }
+    }
+    for (const name of ['srcset', 'imagesrcset']) {
+      const value = attribute(node, name);
+      if (!value) continue;
+      const inlined: string[] = [];
+      for (const candidate of parseSourceSet(value)) {
+        const path = await resolveLocalFile(
+          candidate.url,
+          context.sourceFile,
+          context.outputRoot,
+        );
+        inlined.push(
+          `${await assetDataUrl(path, context)}${candidate.descriptor ? ` ${candidate.descriptor}` : ''}`,
+        );
+      }
+      setAttribute(node, name, inlined.join(', '));
+    }
+    const style = attribute(node, 'style');
+    if (style) setAttribute(node, 'style', await inlineCssUrls(style, context.sourceFile, context));
+  }
+}
+
+function rewriteNavigation(
+  document: HtmlNode,
+  lessonSlug: string,
+  basePrefix: string,
+  canonicalBaseUrl: string | undefined,
+): void {
+  for (const anchor of elements(document, (node) => node.tagName === 'a')) {
+    const href = attribute(anchor, 'href');
+    if (href) {
+      setAttribute(
+        anchor,
+        'href',
+        rewriteCourseLink(href, lessonSlug, basePrefix, canonicalBaseUrl),
+      );
+    }
+  }
+  for (const node of elements(document)) {
+    const href = attribute(node, 'data-notation-href');
+    if (href) {
+      setAttribute(
+        node,
+        'data-notation-href',
+        rewriteCourseLink(href, lessonSlug, basePrefix, canonicalBaseUrl),
+      );
+    }
+  }
+}
+
+function auditStandaloneHtml(html: string, lessonSlug: string): void {
+  const document = parse(html);
+  const failures: string[] = [];
+  for (const node of elements(document)) {
+    if (node.tagName === 'script' && attribute(node, 'src')) {
+      failures.push(`<script src=${JSON.stringify(attribute(node, 'src'))}>`);
+    }
+    if (node.tagName === 'link') {
+      const rel = (attribute(node, 'rel') ?? '').toLowerCase();
+      if (/\b(?:stylesheet|modulepreload|preload|prefetch)\b/u.test(rel)) {
+        failures.push(`<link rel=${JSON.stringify(rel)}>`);
+      }
+    }
+    if (node.tagName === 'astro-island') {
+      for (const name of ['component-url', 'renderer-url', 'before-hydration-url']) {
+        const value = attribute(node, name);
+        if (value && !value.startsWith('data:text/javascript;base64,')) {
+          failures.push(`<astro-island ${name}=${JSON.stringify(value)}>`);
+        }
+      }
+    }
+    for (const name of ['src', 'poster', 'data', 'srcset', 'imagesrcset']) {
+      const value = attribute(node, name);
+      if (value && !value.startsWith('data:') && !value.startsWith('#')) {
+        failures.push(`<${node.tagName} ${name}=${JSON.stringify(value)}>`);
+      }
+    }
+    if (node.tagName === 'use' || node.tagName === 'image') {
+      for (const name of ['href', 'xlink:href']) {
+        const value = attribute(node, name);
+        if (value && !value.startsWith('data:') && !value.startsWith('#')) {
+          failures.push(`<${node.tagName} ${name}=${JSON.stringify(value)}>`);
+        }
+      }
+    }
+    const css =
+      node.tagName === 'style' ? textContent(node) : (attribute(node, 'style') ?? '');
+    CSS_IMPORT.lastIndex = 0;
+    for (let match = CSS_IMPORT.exec(css); match; match = CSS_IMPORT.exec(css)) {
+      const value = (match[2] ?? match[3] ?? match[5] ?? '').trim();
+      if (value && !value.startsWith('data:')) failures.push(`CSS @import ${value}`);
+    }
+    CSS_URL.lastIndex = 0;
+    for (let match = CSS_URL.exec(css); match; match = CSS_URL.exec(css)) {
+      const value = (match[2] ?? match[3] ?? '').trim();
+      if (value && !isEmbeddedReference(value)) failures.push(`CSS url(${value})`);
+    }
+    if (node.tagName === 'script') {
+      const code = textContent(node);
+      LOCAL_IMPORT.lastIndex = 0;
+      const imported = LOCAL_IMPORT.exec(code)?.[2];
+      if (imported) failures.push(`JavaScript import ${JSON.stringify(imported)}`);
+      if (
+        attribute(node, 'data-explico-standalone-browser-graph') !== undefined &&
+        /\bimport\s*\(/u.test(code)
+      ) {
+        failures.push('unbundled dynamic import in browser graph');
+      }
+      if (/new\s+(?:Shared)?Worker\s*\(\s*["']/u.test(code)) {
+        failures.push('literal worker URL');
+      }
+      if (/new\s+URL\s*\(\s*["'][^"']+["']\s*,\s*import\.meta\.url/u.test(code)) {
+        failures.push('import.meta.url asset');
+      }
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(
+      `Standalone HTML audit failed for ${lessonSlug}: ${[...new Set(failures)].join(', ')}.`,
+    );
+  }
+}
+
+/** Build one fully inlined lesson document without writing it. */
+export async function buildStandaloneLessonHtml(
+  input: StandaloneLessonInput,
+): Promise<string> {
+  const outputRoot = resolve(input.outputRoot);
+  const sourceFile = resolve(input.sourceFile);
+  if (!insideRoot(sourceFile, outputRoot)) {
+    throw new Error('Standalone lesson source must be inside Astro build output.');
+  }
+  const context: ExportContext = {
+    outputRoot,
+    sourceFile,
+    assetData: new Map(),
+  };
+  const document = parse(input.html);
+  const basePrefix = inferBasePrefix(document);
+  reduceToLessonShell(document);
+  const head = firstElement(document, 'head');
+  const exportStyle = textElement('style', STANDALONE_STYLE);
+  setAttribute(exportStyle, 'data-explico-standalone-style');
+  append(head, exportStyle);
+  rewriteNavigation(
+    document,
+    input.lessonSlug,
+    basePrefix,
+    input.canonicalBaseUrl,
+  );
+  await inlineStyles(document, context);
+  await inlineScripts(document, context);
+  await inlineMedia(document, context);
+
+  const html = serialize(document);
+  auditStandaloneHtml(html, input.lessonSlug);
+  return html;
+}
+
+async function lessonSourceFile(outputRoot: string, slug: string): Promise<string> {
+  const candidates = [join(outputRoot, slug, 'index.html'), join(outputRoot, `${slug}.html`)];
+  for (const candidate of candidates) if (await isFile(candidate)) return candidate;
+  throw new Error(
+    `Standalone HTML could not find Astro's built page for ${slug}; tried ` +
+      candidates.map((path) => relative(outputRoot, path)).join(', '),
+  );
+}
+
+/** Emit all opt-in lesson HTML artifacts from Astro's completed static output. */
+export async function writeStandaloneLessonExports(
+  directory: URL,
+  manifest: Manifest,
+): Promise<void> {
+  if (!manifest.lessonExports.standaloneHtml) return;
+  const outputRoot = fileURLToPath(directory);
+  const pending: { target: string; temporary: string; html: string }[] = [];
+  for (const lesson of manifest.lessons) {
+    const sourceFile = await lessonSourceFile(outputRoot, lesson.slug);
+    const target = join(outputRoot, 'downloads', `${lesson.slug}.html`);
+    pending.push({
+      target,
+      temporary: `${target}.tmp-${process.pid}`,
+      html: await buildStandaloneLessonHtml({
+        html: await readFile(sourceFile, 'utf8'),
+        sourceFile,
+        outputRoot,
+        lessonSlug: lesson.slug,
+        canonicalBaseUrl: manifest.lessonExports.canonicalBaseUrl,
+      }),
+    });
+  }
+
+  // Nothing is published until every lesson has passed the asset audit.
+  for (const artifact of pending) {
+    await mkdir(dirname(artifact.target), { recursive: true });
+    await writeFile(artifact.temporary, artifact.html, 'utf8');
+  }
+  for (const artifact of pending) await rename(artifact.temporary, artifact.target);
+}