@lincyaw/web 1.0.0-rc.0 → 1.0.0-rc.1

package/src/domain/themes.ts

@@ -0,0 +1,59 @@
+import { deckLocale, isRecord } from '@lincyaw/kernel'
+import { WEB_MESSAGES } from './messages.ts'
+
+export const SITE_THEME_IDS = ['course', 'docs', 'showcase'] as const
+export type SiteThemeId = typeof SITE_THEME_IDS[number]
+export type SitePageLayout = 'article' | 'landing' | 'wide'
+
+/** Public presentation options; the content and its stable identities stay in lecture.json. */
+export interface SiteThemeParams {
+  accent: 'blue' | 'teal' | 'violet' | 'amber'
+  typography: 'reading' | 'sans'
+  contentWidth: 'comfortable' | 'wide'
+  logo?: string
+  logoAlt?: string
+}
+
+export interface SiteTheme {
+  id: SiteThemeId
+  params: SiteThemeParams
+}
+
+export const SITE_THEMES: Readonly<Record<SiteThemeId, Readonly<SiteThemeParams>>> = {
+  docs: { accent: 'teal', typography: 'reading', contentWidth: 'comfortable' },
+  course: { accent: 'teal', typography: 'reading', contentWidth: 'comfortable' },
+  showcase: { accent: 'violet', typography: 'sans', contentWidth: 'wide' },
+}
+
+/** Resolve and validate the same configuration in builds, dev servers and independent documents. */
+export function siteTheme(config: Record<string, unknown>, lang?: string): SiteTheme {
+  const t = WEB_MESSAGES[deckLocale(lang)]
+  const id = config.theme ?? 'docs'
+  if (!SITE_THEME_IDS.includes(id as SiteThemeId)) throw new Error(t.unknownTheme(String(id)))
+  const defaults = SITE_THEMES[id as SiteThemeId]
+  if (config.params !== undefined && !isRecord(config.params)) throw new Error(t.invalidSiteParameter('site.params'))
+  const input = isRecord(config.params) ? config.params : {}
+  const choice = <T extends string>(key: string, values: readonly T[], fallback: T): T => {
+    const value = input[key]
+    if (value === undefined) return fallback
+    if (!values.includes(value as T)) throw new Error(t.invalidSiteParameter(`site.params.${key}`))
+    return value as T
+  }
+  const params: SiteThemeParams = {
+    accent: choice('accent', ['blue', 'teal', 'violet', 'amber'], defaults.accent),
+    typography: choice('typography', ['reading', 'sans'], defaults.typography),
+    contentWidth: choice('contentWidth', ['comfortable', 'wide'], defaults.contentWidth),
+  }
+  for (const key of ['logo', 'logoAlt'] as const) {
+    if (input[key] === undefined) continue
+    if (typeof input[key] !== 'string' || key === 'logo' && !input[key].trim()) throw new Error(t.invalidSiteParameter(`site.params.${key}`))
+    params[key] = input[key].trim()
+  }
+  return { id: id as SiteThemeId, params }
+}
+
+export function sitePageLayout(config: Record<string, unknown>, lang?: string): SitePageLayout {
+  const value = config.layout ?? 'article'
+  if (!['article', 'landing', 'wide'].includes(value as string)) throw new Error(WEB_MESSAGES[deckLocale(lang)].invalidSiteParameter('renderers.web.layout'))
+  return value as SitePageLayout
+}

package/src/domain/workspace-home.ts

@@ -0,0 +1,12 @@
+/** A document's card on the workspace site's home page. */
+export interface HomeDocument {
+  dir: string
+  title: string
+  lang?: string
+  tags?: string[]
+  href: string
+  description?: string
+  pages?: number
+  problems?: { errors: number, warnings: number }
+  sections?: { id: string, title: string, href: string }[]
+}

package/src/node/client-modules.ts

@@ -0,0 +1,92 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { isRecord } from '@lincyaw/kernel'
+import type { NodeVitePlugin, RenderContext } from '@lincyaw/kernel'
+import { packageOf } from '@lincyaw/kernel/node'
+
+const CLIENT_PLUGIN = 'src/client/plugin.ts'
+const VIEWER_PLUGIN = 'src/client/viewer.ts'
+const VITE_CONFIG = 'vite.config.ts'
+const COMPONENT = /^[^.]+\.([jt]sx?)$/
+
+export interface ClientModules {
+  restartable: boolean
+  components: Map<string, string>
+  plugins: string[]
+  viewers: { name: string, file: string }[]
+  vite: string[]
+  nodeVite: NodeVitePlugin[]
+}
+
+/** Adds the browser modules of the package at `dir` to `modules` (a plugin's components do not replace those already there). */
+export function collectBrowserModules(dir: string, name: string, modules: ClientModules, plugin: boolean, manifestDir: string | undefined = dir): void {
+  let browser = false
+  const components = join(dir, 'components')
+  if (existsSync(components)) {
+    for (const file of readdirSync(components).filter(f => COMPONENT.test(f)).sort()) {
+      browser = true
+      const name = file.replace(/\.[^.]+$/, '')
+      if (!plugin || !modules.components.has(name)) modules.components.set(name, join(components, file))
+    }
+  }
+  if (existsSync(join(dir, CLIENT_PLUGIN))) {
+    browser = true
+    modules.plugins.push(join(dir, CLIENT_PLUGIN))
+  }
+  if (existsSync(join(dir, VIEWER_PLUGIN))) {
+    browser = true
+    modules.viewers.push({ name, file: join(dir, VIEWER_PLUGIN) })
+  }
+  if (plugin && existsSync(join(dir, VITE_CONFIG))) {
+    browser = true
+    modules.vite.push(join(dir, VITE_CONFIG))
+  }
+  if (browser && !isRestartablePackage(manifestDir)) modules.restartable = false
+}
+
+/** The directory of the document's own package: its own `package.json`, else the nearest one up to the workspace's root. */
+export function deckPackage(deckDir: string, workspaceRoot: string): string | undefined {
+  for (let dir = deckDir; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'package.json'))) return dir
+    if (dir === workspaceRoot || relative(workspaceRoot, dir).startsWith('..') || dirname(dir) === dir) return undefined
+  }
+}
+
+function readManifest(dir: string): Record<string, unknown> {
+  try {
+    const pkg: unknown = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    return isRecord(pkg) ? pkg : {}
+  } catch {
+    return {}
+  }
+}
+
+export function isRestartablePackage(dir: string | undefined): boolean {
+  if (!dir) return false
+  const { presmium } = readManifest(dir)
+  return isRecord(presmium) && isRecord(presmium.preview) && presmium.preview.restartable === true
+}
+
+/** No browser modules yet. */
+export function emptyClientModules(nodeVite: NodeVitePlugin[] = []): ClientModules {
+  return { restartable: true, components: new Map(), plugins: [], viewers: [], vite: [], nodeVite }
+}
+
+/** The browser modules of the document and its plugins: components, browser and viewer plugins, Vite configurations. */
+export function clientModules(ctx: RenderContext, nodeVite: NodeVitePlugin[]): ClientModules {
+  const modules = emptyClientModules(nodeVite)
+  for (const { entry } of nodeVite) {
+    try {
+      if (!isRestartablePackage(packageOf(entry))) modules.restartable = false
+    } catch {
+      modules.restartable = false
+    }
+  }
+  for (const name of ctx.plugins) {
+    const dir = ctx.pluginDirs[name]
+    const { name: pkg } = dir ? readManifest(dir) : {}
+    if (dir) collectBrowserModules(dir, typeof pkg === 'string' ? pkg : name, modules, true)
+  }
+  collectBrowserModules(ctx.deckDir, 'deck', modules, false, deckPackage(ctx.deckDir, ctx.workspaceRoot))
+  return modules
+}

package/src/node/document-bundle.ts

@@ -0,0 +1,227 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { irBlocks } from '@lincyaw/kernel'
+import type { IRDocument, PresmiumNodePlugin } from '@lincyaw/kernel'
+import { collectBrowserModules, deckPackage, emptyClientModules, isRestartablePackage } from './client-modules.ts'
+import { quietDirectives } from './viewer-app.ts'
+
+/**
+ * A document's own browser code, apart from the viewer app that shows it: its components, browser and viewer plugins,
+ * and the document modules its plugins generate for it (`PresmiumNodePlugin.documentModules`), as one small bundle that
+ * imports React, Presmium's packages and the plugins' public subpaths by name, from the app, through its import map.
+ */
+
+const BUNDLE_MANIFEST = 'bundle.json'
+export const BUNDLE_ENTRY = 'document.js'
+const DOCUMENT_MODULE = '\0presmium-document-bundle:'
+const KEEP = 3
+
+export interface DocumentBundleInput {
+  deckDir: string
+  workspaceRoot: string
+  /** Where the document's bundles are kept, each in a directory by its key. */
+  outDir: string
+  /** The specifiers the app's import map names: never bundled. */
+  externals: string[]
+  /** The Node entries of the document's plugins, with their configuration, for their document modules. */
+  nodePlugins: { entry: string, config: Record<string, unknown> }[]
+  /** Canonical file implementations, registered by their derived runtime names. */
+  components?: DocumentComponent[]
+}
+
+export interface DocumentComponent { name: string, file: string, exportName?: string }
+
+/** Own React components are selected by the compiled definition, regardless of their directory. */
+export function documentComponents(doc: IRDocument | undefined): DocumentComponent[] {
+  const found = new Map<string, DocumentComponent>()
+  for (const section of doc?.sections ?? []) for (const block of irBlocks(section.blocks)) {
+    const node = block.node
+    if (node.type !== 'component' || node.plugin !== 'deck' || !node.definition) continue
+    const component = { name: node.name, file: node.definition.file, ...node.definition.exportName !== undefined ? { exportName: node.definition.exportName } : {} }
+    const known = found.get(component.name)
+    if (known && (known.file !== component.file || known.exportName !== component.exportName)) throw new Error(`Document component ${component.name} names multiple implementations.`)
+    found.set(component.name, component)
+  }
+  return [...found.values()]
+}
+
+export interface DocumentBundle {
+  key: string
+  dir: string
+  /** The files the bundle was built from, by path, with their size and time then. */
+  inputs: Record<string, string>
+  restartable: boolean
+  /** The names of the document's own components. */
+  components: string[]
+}
+
+interface DocumentCode {
+  key: string
+  entry: string
+  components: string[]
+  /** The document modules' sources, by id. */
+  generated: Record<string, string>
+  restartable: boolean
+}
+
+const stamp = (file: string) => {
+  try {
+    const { size, mtimeMs } = statSync(file)
+    return `${size}:${Math.trunc(mtimeMs)}`
+  } catch {
+    return 'missing'
+  }
+}
+
+/** The entry of the document's bundle and the key of what it is made of, or none when the document has no code of its own. */
+async function documentCode(input: DocumentBundleInput): Promise<DocumentCode | undefined> {
+  const modules = emptyClientModules()
+  collectBrowserModules(input.deckDir, 'deck', modules, false, deckPackage(input.deckDir, input.workspaceRoot))
+  const components = new Map([...modules.components].map(([name, file]) => [name, { file, exportName: 'default' }]))
+  if (input.components?.length && !isRestartablePackage(deckPackage(input.deckDir, input.workspaceRoot))) modules.restartable = false
+  for (const component of input.components ?? []) components.set(component.name, { file: resolve(input.deckDir, component.file), exportName: component.exportName ?? 'default' })
+  const generated: Record<string, string> = {}
+  for (const { entry, config } of input.nodePlugins) {
+    const plugin = (await import(pathToFileURL(entry).href) as { default?: PresmiumNodePlugin }).default
+    Object.assign(generated, plugin?.documentModules?.({ deckDir: input.deckDir, workspaceRoot: input.workspaceRoot, config }) ?? {})
+  }
+  if (components.size + modules.plugins.length + modules.viewers.length + Object.keys(generated).length === 0) return undefined
+  const load = (file: string) => `() => import(${JSON.stringify(file)})`
+  const ids = Object.keys(generated)
+  const entry = `${ids.map((id, i) => `import module${i} from ${JSON.stringify(id)}\n`).join('')}
+export const components = {
+${[...components].map(([name, { file, exportName }]) => `  ${JSON.stringify(name)}: () => import(${JSON.stringify(file)}).then(module => { if (!module[${JSON.stringify(exportName)}]) throw new Error(${JSON.stringify(`Document component ${name} has no export ${exportName}.`)}); return { default: module[${JSON.stringify(exportName)}] } }),`).join('\n')}
+}
+export const plugins = [${modules.plugins.map(load).join(', ')}]
+export const viewers = [${modules.viewers.map(({ name, file }) => `{ name: ${JSON.stringify(name)}, load: ${load(file)} }`).join(', ')}]
+export const documentModules = {
+${ids.map((id, i) => `  ${JSON.stringify(id)}: module${i},`).join('\n')}
+}
+export const restartable = ${modules.restartable}
+`
+  const key = createHash('sha256').update(JSON.stringify([input.externals.toSorted(), entry, generated])).digest('hex').slice(0, 16)
+  return { key, entry, generated, restartable: modules.restartable, components: [...components.keys()] }
+}
+
+function readBundle(dir: string): DocumentBundle | undefined {
+  try {
+    const bundle = JSON.parse(readFileSync(join(dir, BUNDLE_MANIFEST), 'utf8')) as DocumentBundle
+    return Object.entries(bundle.inputs).every(([file, known]) => stamp(file) === known) ? { ...bundle, components: bundle.components ?? [], dir } : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The newest bundle of the document's code (`key`) built from its files as they are now. */
+function freshBundle(outDir: string, key: string): DocumentBundle | undefined {
+  let entries: string[]
+  try {
+    entries = readdirSync(outDir).filter(entry => entry.startsWith(`${key}-`))
+  } catch {
+    return undefined
+  }
+  const builds = entries.map(entry => ({ dir: join(outDir, entry), time: statSync(join(outDir, entry)).mtimeMs })).sort((a, b) => b.time - a.time)
+  for (const { dir } of builds) {
+    const bundle = readBundle(dir)
+    if (bundle) return bundle
+  }
+  return undefined
+}
+
+/** The document's bundle as its files are now, if one was built from them. */
+export async function findDocumentBundle(input: DocumentBundleInput): Promise<DocumentBundle | null | undefined> {
+  const code = await documentCode(input)
+  if (!code) return null
+  return freshBundle(input.outDir, code.key)
+}
+
+/**
+ * Builds the document's bundle (unless it is there already); none when the document has no code of its own. Its
+ * directory is named by its code and its content, so that its files never change under their address.
+ */
+export async function buildDocumentBundle(input: DocumentBundleInput): Promise<DocumentBundle | null> {
+  const code = await documentCode(input)
+  if (!code) return null
+  const known = freshBundle(input.outDir, code.key)
+  if (known) return known
+  const work = join(input.outDir, `.build-${code.key}-${process.pid}`)
+  rmSync(work, { recursive: true, force: true })
+  mkdirSync(work, { recursive: true })
+  // Vite resolves symlinks, including macOS's /var -> /private/var temporary paths.
+  const realWork = realpathSync(work)
+  writeFileSync(join(work, 'entry.ts'), code.entry)
+  const { generated } = code
+  const externals = new Set(input.externals)
+  const inputs: Record<string, string> = {}
+  const { build } = await import('vite')
+  await build({
+    configFile: false,
+    root: input.deckDir,
+    base: './',
+    logLevel: 'warn',
+    mode: 'production',
+    esbuild: { jsx: 'automatic' },
+    publicDir: false,
+    plugins: [
+      {
+        name: 'presmium:document-bundle',
+        // Before Vite's own resolution: the app's modules stay imports by name.
+        enforce: 'pre' as const,
+        resolveId(id: string) {
+          // Headmatter aliases already load the renamed plugins. Older document code must import the same shared
+          // modules too, rather than resolving the removed packages or bundling a second copy of their runtime.
+          const shared = externals.has(id) ? id : id.replace(/^@lincyaw\/slidev-addon-/, '@lincyaw/addon-')
+          if (externals.has(shared)) return { id: shared, external: true }
+          return generated[id] === undefined ? undefined : `${DOCUMENT_MODULE}${id}`
+        },
+        load(id: string) {
+          return id.startsWith(DOCUMENT_MODULE) ? generated[id.slice(DOCUMENT_MODULE.length)] : undefined
+        },
+        generateBundle(_: unknown, bundle: Record<string, { type: string, moduleIds?: string[] }>) {
+          for (const chunk of Object.values(bundle)) {
+            for (const id of chunk.moduleIds ?? []) {
+              const file = id.replace(/[?#].*$/s, '')
+              if (file.startsWith('\0') || !existsSync(file)) continue
+              const realFile = realpathSync(file)
+              if (!realFile.startsWith(realWork + sep) && !realFile.split(sep).includes('node_modules')) inputs[realFile] = stamp(realFile)
+            }
+          }
+        },
+        onLog: quietDirectives,
+      },
+    ],
+    resolve: { dedupe: ['react', 'react-dom'] },
+    build: {
+      outDir: join(work, 'out'),
+      emptyOutDir: true,
+      target: 'es2022',
+      reportCompressedSize: false,
+      chunkSizeWarningLimit: 100_000,
+      copyPublicDir: false,
+      rollupOptions: {
+        input: { document: join(work, 'entry.ts') },
+        preserveEntrySignatures: 'strict',
+        output: {
+          format: 'es',
+          entryFileNames: BUNDLE_ENTRY,
+          chunkFileNames: 'chunks/[name]-[hash].js',
+          assetFileNames: 'assets/[name]-[hash][extname]',
+        },
+      },
+    },
+  })
+  const content = createHash('sha256').update(readFileSync(join(work, 'out', BUNDLE_ENTRY))).digest('hex').slice(0, 8)
+  const name = `${code.key}-${content}`
+  const out = join(input.outDir, name)
+  const bundle: DocumentBundle = { key: name, dir: out, inputs, restartable: code.restartable, components: code.components }
+  writeFileSync(join(work, 'out', BUNDLE_MANIFEST), `${JSON.stringify(bundle, null, 2)}\n`)
+  rmSync(out, { recursive: true, force: true })
+  renameSync(join(work, 'out'), out)
+  rmSync(work, { recursive: true, force: true })
+  // The document's last few bundles stay, for pages still loading an earlier one.
+  const builds = readdirSync(input.outDir).filter(entry => !entry.startsWith('.')).map(entry => ({ dir: join(input.outDir, entry), time: statSync(join(input.outDir, entry)).mtimeMs })).sort((a, b) => b.time - a.time)
+  for (const old of builds.slice(KEEP)) rmSync(old.dir, { recursive: true, force: true })
+  return bundle
+}

package/src/node/landing-template.ts

@@ -0,0 +1,34 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { mapHtmlUrls } from '@lincyaw/kernel'
+import { build } from 'vite'
+import { SITE_CONTENT_ELEMENT } from '../domain/index.ts'
+import type { SiteContent } from '../domain/index.ts'
+
+/** A website template is an ordinary Vite HTML entry, with its own CSS and modules. */
+export async function buildLandingTemplate(file: string, workDir: string, base: string, content: SiteContent, workspaceRoot: string): Promise<{ html: string, dir: string }> {
+  const dir = join(workDir, 'template')
+  const data = JSON.stringify(content).replace(/</g, '\\u003c')
+  await build({
+    configFile: false,
+    root: dirname(file),
+    base,
+    publicDir: join(workspaceRoot, 'public'),
+    logLevel: 'silent',
+    plugins: [{
+      name: 'presmium-site-content',
+      transformIndexHtml: { order: 'pre', handler: () => [{ tag: 'script', attrs: { id: SITE_CONTENT_ELEMENT, type: 'application/json' }, children: data, injectTo: 'head' }] },
+    }],
+    build: { outDir: dir, emptyOutDir: true, copyPublicDir: false, assetsDir: '_landing/assets', rollupOptions: { input: file } },
+  })
+  const html = mapHtmlUrls(readFileSync(join(dir, basename(file)), 'utf8'), url => url.startsWith('/') && !url.startsWith('//') && !url.startsWith(base) ? `${base}${url.slice(1)}` : undefined)
+  return { html, dir }
+}
+
+export function writeLandingTemplate(output: { html: string, dir: string }, outDir: string, prefix = ''): void {
+  // Only emitted assets are shared; the entry itself is mounted as the site's index.html.
+  if (existsSync(join(output.dir, '_landing'))) cpSync(join(output.dir, '_landing'), join(outDir, '_landing'), { recursive: true, force: true })
+  const index = join(outDir, prefix, 'index.html')
+  mkdirSync(dirname(index), { recursive: true })
+  writeFileSync(index, output.html)
+}

package/src/node/landing.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+import { ABSOLUTE_URL, deckLocale, DOCUMENT_ENTRY, isRecord, safeDecodeURIComponent } from '@lincyaw/kernel'
+import type { IRDocument, RenderContext, SiteSpec } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
+import { parseLandingPage, WEB_MESSAGES } from '../domain/index.ts'
+import type { HomeDocument, SiteContent, SiteLandingPage } from '../domain/index.ts'
+import { publishedFile } from './publish.ts'
+import { documentLinkOf, documentPage, siteLanguage, siteTitle } from './site-model.ts'
+
+export type IndependentLanding = { kind: 'page', page: SiteLandingPage, source: string } | { kind: 'template', file: string }
+
+/** Resolve website pages from their own source, independently of the document compiler. */
+export function loadLanding(site: SiteSpec, ctx: RenderContext): IndependentLanding | undefined {
+  const input = site.config.landing
+  if (input === undefined || typeof input === 'string') return undefined
+  const fail = (key: string): never => { throw new Error(WEB_MESSAGES[deckLocale(siteLanguage(site))].invalidSiteParameter(key)) }
+  if (!isRecord(input) || site.home !== undefined) return fail('site.landing')
+  const file = (value: unknown, key: string, extension: string) => {
+    if (typeof value !== 'string' || !value.trim()) return fail(key)
+    const path = resolve(ctx.workspaceRoot, value)
+    if (!existsSync(path) || !statSync(path).isFile() || extname(path).toLowerCase() !== extension || !isInside(realpathSync(path), realpathSync(ctx.workspaceRoot))) return fail(key)
+    return path
+  }
+  if ('source' in input && 'template' in input) return fail('site.landing')
+  if ('template' in input) return { kind: 'template', file: file(input.template, 'site.landing.template', '.html') }
+  if ('source' in input) {
+    const source = file(input.source, 'site.landing.source', '.json')
+    let value: unknown
+    try { value = JSON.parse(readFileSync(source, 'utf8')) } catch { return fail('site.landing.source') }
+    return { kind: 'page', page: parseLandingPage(value, siteLanguage(site)), source }
+  }
+  return { kind: 'page', page: parseLandingPage(input, siteLanguage(site)), source: join(ctx.workspaceRoot, 'presmium.workspace.yaml') }
+}
+
+/** Local media belongs to the page source; site-absolute navigation belongs to the deployment base. */
+export function publishLanding(landing: Extract<IndependentLanding, { kind: 'page' }>, site: SiteSpec, ctx: RenderContext, outDir = ctx.outDir, base = ctx.base, docs: ReadonlyMap<string, IRDocument> = new Map(site.documents.flatMap(entry => entry.doc ? [[entry.dir, entry.doc] as const] : []))): SiteLandingPage {
+  const page = structuredClone(landing.page)
+  const source = { file: landing.source, line: 1 }
+  const publish = (value: string, link = false): string => {
+    if (ABSOLUTE_URL.test(value) || value.startsWith('#')) return value
+    if (value.startsWith('/')) return `${ctx.base}${value.slice(1)}`
+    if (link) {
+      const reference = documentLinkOf(ctx)(source, value)
+      if (reference) {
+        const href = documentPage(site, ctx.base, docs)(reference)
+        if (href) return href
+        throw new Error(WEB_MESSAGES[deckLocale(siteLanguage(site))].invalidSiteParameter(`site.landing: ${value}`))
+      }
+      const path = value.replace(/[?#].*$/s, '')
+      if (!extname(path)) return `${ctx.base}${value.replace(/^\.\//, '')}`
+    }
+    const file = resolve(dirname(landing.source), safeDecodeURIComponent(value.replace(/[?#].*$/s, '')))
+    if (existsSync(file) && basename(realpathSync(file)) === DOCUMENT_ENTRY) throw new Error(WEB_MESSAGES[deckLocale(siteLanguage(site))].invalidSiteParameter(`site.landing: ${value}`))
+    const result = publishedFile(ctx, outDir, base, source, value)
+    if (!result) throw new Error(WEB_MESSAGES[deckLocale(siteLanguage(site))].invalidSiteParameter(`site.landing: ${value}`))
+    return result
+  }
+  const actions = (items: { link: string }[] | undefined) => items?.forEach(action => { action.link = publish(action.link, true) })
+  if (page.hero) {
+    if (page.hero.image) page.hero.image = publish(page.hero.image)
+    actions(page.hero.actions)
+  }
+  for (const section of page.sections) {
+    if (section.type === 'features') for (const item of section.items) {
+      if (item.image) item.image = publish(item.image)
+      if (item.link) item.link = publish(item.link, true)
+    }
+    if (section.type === 'media') {
+      section.src = publish(section.src)
+      if (section.poster) section.poster = publish(section.poster)
+      if (section.captions) section.captions = Object.fromEntries(Object.entries(section.captions).map(([lang, url]) => [lang, publish(url)]))
+    }
+    if (section.type === 'cta') actions(section.actions)
+  }
+  return page
+}
+
+/** The public content collection available to a free-form HTML template. */
+export function siteContent(site: SiteSpec, base: string, lang: string, documents: HomeDocument[]): SiteContent {
+  return { schemaVersion: 1, title: siteTitle(site, lang), base, lang, documents: documents.map(({ dir, title, href, description, lang, tags, pages }) => ({ id: dir, title, href, description, lang, tags, pages })) }
+}

package/src/node/offline.ts

@@ -1,16 +1,29 @@
 import { createHash } from 'node:crypto'
 import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
-import { join, sep } from 'node:path'
+import { basename, join, sep } from 'node:path'
+import { OFFLINE_REQUESTS } from '@lincyaw/kernel'
 import { SERVICE_WORKER, urlPath } from '../domain/index.ts'
 import { MEDIA } from './publish.ts'
+import { APP_DIR, CODE_DIR } from './site-files.ts'
 
-const MESSAGES = { runtimes: 'presmium:offline-runtimes', save: 'presmium:save-offline' }
+interface OfflineCache {
+  prefix: string
+  cache: string
+  urls: string[]
+  runtimeCache: string
+  runtimes: string[]
+  runtimeBytes: number
+  base: string
+  app: string
+}
 
-function source(cache: string, urls: string[], runtimeCache: string, runtimes: string[], runtimeBytes: number, base: string): string {
+function source({ prefix, cache, urls, runtimeCache, runtimes, runtimeBytes, base, app }: OfflineCache): string {
   return `// Generated by @lincyaw/web.
 const CACHE = ${JSON.stringify(cache)}
+const PREFIX = ${JSON.stringify(prefix)}
 const RUNTIME_CACHE = ${JSON.stringify(runtimeCache)}
 const BASE = ${JSON.stringify(base)}
+const APP = ${JSON.stringify(app)}
 const URLS = ${JSON.stringify(urls)}
 const RUNTIMES = ${JSON.stringify(runtimes)}
 const RUNTIME_BYTES = ${runtimeBytes}
@@ -22,7 +35,7 @@ self.addEventListener('install', (event) => {
 
 self.addEventListener('activate', (event) => {
   event.waitUntil(caches.keys()
-    .then(keys => Promise.all(keys.filter(key => key.startsWith('presmium-web-') && key !== CACHE && key !== RUNTIME_CACHE).map(key => caches.delete(key))))
+    .then(keys => Promise.all(keys.filter(key => key.startsWith(PREFIX) && key !== CACHE && key !== RUNTIME_CACHE).map(key => caches.delete(key))))
     .then(() => self.clients.claim()))
 })
 
@@ -70,9 +83,9 @@ self.addEventListener('message', (event) => {
   const port = event.ports[0]
   const type = event.data && event.data.type
   if (!port) return
-  if (type === ${JSON.stringify(MESSAGES.runtimes)}) {
+  if (type === ${JSON.stringify(OFFLINE_REQUESTS.runtimes)}) {
     event.waitUntil(saved().then(done => port.postMessage({ bytes: RUNTIME_BYTES, saved: done })))
-  } else if (type === ${JSON.stringify(MESSAGES.save)}) {
+  } else if (type === ${JSON.stringify(OFFLINE_REQUESTS.save)}) {
     event.waitUntil(save().then(() => port.postMessage({ ok: true }), () => port.postMessage({ ok: false })))
   }
 })
@@ -80,12 +93,12 @@ self.addEventListener('message', (event) => {
 self.addEventListener('fetch', (event) => {
   const { request } = event
   const url = new URL(request.url)
-  if (request.method !== 'GET' || url.origin !== self.location.origin || !url.pathname.startsWith(BASE)) return
+  if (request.method !== 'GET' || url.origin !== self.location.origin || !(url.pathname.startsWith(BASE) || url.pathname.startsWith(APP))) return
   if (RUNTIME_PATHS.has(url.pathname)) {
     url.search = ''
     url.hash = ''
     event.respondWith(runtime(url.href))
-  } else if (url.pathname.startsWith(BASE + 'assets/')) {
+  } else if (url.pathname.startsWith(APP) || url.pathname.startsWith(BASE + ${JSON.stringify(`${CODE_DIR}/`)})) {
     event.respondWith(cached(request).then(hit => hit || fetch(request)))
   } else {
     event.respondWith(fetch(request).catch(() => cached(request).then(hit => hit || Response.error())))
@@ -115,8 +128,12 @@ function files(dir: string): string[] {
 
 const isRuntime = (file: string) => /^(?:pyodide|wasi|presmium\/jax-js)\//.test(file) && !/(?:^|\/)LICENSES?$/.test(file)
 
-export function writeServiceWorker(outDir: string, base: string): void {
-  const list = files(outDir).map(file => file.split(sep).join('/'))
+/**
+ * Writes the document's service worker: it keeps the document's files and the viewer app's (`app`, below the site's
+ * path, shared with the site's other documents) for reading offline, and the plugins' run-time files on request.
+ */
+export function writeServiceWorker(outDir: string, base: string, app: { dir: string, url: string }): void {
+  const list = files(outDir).filter(file => !file.startsWith(`${APP_DIR}${sep}`)).map(file => file.split(sep).join('/'))
   const shell = list.filter(file => !isRuntime(file))
   const runtimes = list.filter(isRuntime)
   const hash = (names: string[]) => {
@@ -125,6 +142,12 @@ export function writeServiceWorker(outDir: string, base: string): void {
     return digest.digest('hex').slice(0, 12)
   }
   const urls = (names: string[]) => names.map(file => file.split('/')).map(parts => base + (parts[0] === MEDIA ? parts.map(encodeURIComponent).join('/') : urlPath(parts.join('/'))))
+  const appFiles = files(app.dir).map(file => app.url + urlPath(file.split(sep).join('/')))
   const bytes = runtimes.reduce((sum, file) => sum + statSync(join(outDir, file)).size, 0)
-  writeFileSync(join(outDir, SERVICE_WORKER), source(`presmium-web-${hash(shell)}`, urls(shell), `presmium-web-runtimes-${hash(runtimes)}`, urls(runtimes), bytes, base))
+  const scope = createHash('sha256').update(base).digest('hex').slice(0, 16)
+  const prefix = `presmium-web-${scope}-`
+  writeFileSync(join(outDir, SERVICE_WORKER), source({
+    prefix, cache: `${prefix}${hash(shell)}-${basename(app.dir)}`, urls: [...urls(shell), ...appFiles],
+    runtimeCache: `${prefix}runtimes-${hash(runtimes)}`, runtimes: urls(runtimes), runtimeBytes: bytes, base, app: app.url,
+  }))
 }