@mohou/host 1.0.20

package/src/theme/layout.ts

@@ -0,0 +1,42 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Theme file names and pin sentinels. Spell them here, not at each call site. */
+export const themeLayout = {
+  appCss: 'theme.css',
+  appPin: 'theme.json',
+  followHost: '__global__',
+  appFile: '__local__',
+  customPrefix: 'theme-',
+  customSuffix: '.css',
+} as const
+
+const CUSTOM_ID = /^[a-z0-9-]+$/
+
+export function appThemeCss(appDir: string): string {
+  return path.join(appDir, themeLayout.appCss)
+}
+
+export function appThemePin(appDir: string): string {
+  return path.join(appDir, themeLayout.appPin)
+}
+
+export function customThemePath(themesDir: string, id: string): string {
+  return path.join(themesDir, `${themeLayout.customPrefix}${id}${themeLayout.customSuffix}`)
+}
+
+/** Shipped theme files. Same contract as a custom file. Ids come from the filenames. */
+export function builtinThemesDir(): string {
+  return fileURLToPath(new URL('../../themes', import.meta.url))
+}
+
+export function builtinThemePath(id: string): string {
+  return customThemePath(builtinThemesDir(), id)
+}
+
+/** Parse `theme-<id>.css`. A name that does not match is not a palette id. */
+export function customThemeId(filename: string): string | undefined {
+  if (!filename.startsWith(themeLayout.customPrefix) || !filename.endsWith(themeLayout.customSuffix)) return undefined
+  const id = filename.slice(themeLayout.customPrefix.length, -themeLayout.customSuffix.length)
+  return CUSTOM_ID.test(id) ? id : undefined
+}

package/src/theme/paint.ts

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises'
+
+import type { AppPin } from './pin.ts'
+import { themeTokens } from './tokens.ts'
+import { parseThemeCss } from './parse.ts'
+import { appThemeCss, builtinThemePath, customThemePath } from './layout.ts'
+
+export interface FirstPaint {
+  source: 'app-file' | 'custom' | 'builtin' | 'host'
+  paletteId: string | null
+  ignored?: string
+  light: Record<string, string>
+  dark: Record<string, string>
+  style: string
+}
+
+/**
+ * Choose the palette that paints the first frame. Token names are copied, not renamed.
+ * A file that fails to parse is ignored. The next source in order is used.
+ * @param input - pin, host palette id, and the directories that hold theme files
+ */
+export async function resolveFirstPaint(input: {
+  appDir: string
+  pin: AppPin
+  hostPalette: string
+  themesDir: string
+}): Promise<FirstPaint> {
+  if (input.pin.kind === 'follow-host') return await hostPaint(input.hostPalette, input.themesDir)
+  if (input.pin.kind === 'palette') {
+    const chosen = await readPalette(input.themesDir, input.pin.id)
+    if (chosen !== undefined) return chosen
+  }
+  const local = await readPaint(appThemeCss(input.appDir), 'app', 'app-file')
+  const ignored = input.pin.kind === 'palette'
+    ? `custom palette ${input.pin.id} was ignored`
+    : input.pin.kind === 'app-file' ? 'app theme.css was ignored' : undefined
+  if (local !== undefined) return { ...local, ...ignored === undefined ? {} : { ignored } }
+  const host = await hostPaint(input.hostPalette, input.themesDir)
+  return { ...host, ...ignored === undefined ? {} : { ignored } }
+}
+
+/** Both modes from one theme file. The picker applies this without reloading a document. */
+export function styleFromThemeCss(css: string): string {
+  return firstPaintStyle(varsFor(css, 'light'), varsFor(css, 'dark'))
+}
+
+/** CSS to bake into the first HTML response. Empty when the source has no file. */
+export function firstPaintStyle(light: Record<string, string>, dark: Record<string, string>): string {
+  return `${block('light', light)}${block('dark', dark)}`
+}
+
+async function hostPaint(paletteId: string, themesDir: string): Promise<FirstPaint> {
+  return await readPalette(themesDir, paletteId) ?? { source: 'host', paletteId, light: {}, dark: {}, style: '' }
+}
+
+async function readPalette(themesDir: string, id: string): Promise<FirstPaint | undefined> {
+  const custom = await readPaint(customThemePath(themesDir, id), id, 'custom')
+  if (custom !== undefined) return { ...custom, paletteId: id }
+  const builtin = await readPaint(builtinThemePath(id), id, 'builtin')
+  return builtin === undefined ? undefined : { ...builtin, paletteId: id }
+}
+
+async function readPaint(
+  file: string,
+  fallbackName: string,
+  source: 'app-file' | 'custom' | 'builtin',
+): Promise<FirstPaint | undefined> {
+  const css = await readFile(file, 'utf8').catch(() => undefined)
+  if (css === undefined) return undefined
+  const parsed = parseThemeCss(css, fallbackName)
+  if (!parsed.ok) return undefined
+  const light = varsFor(css, 'light')
+  const dark = varsFor(css, 'dark')
+  return { source, paletteId: null, light, dark, style: firstPaintStyle(light, dark) }
+}
+
+function varsFor(css: string, mode: 'light' | 'dark'): Record<string, string> {
+  const body = modeBlock(css, mode)
+  if (body === undefined) return {}
+  const vars: Record<string, string> = {}
+  for (const token of themeTokens) {
+    const value = tokenValue(body, token)
+    if (value === undefined) continue
+    vars[`--${token}`] = value
+  }
+  return vars
+}
+
+function modeBlock(css: string, mode: 'light' | 'dark'): string | undefined {
+  const at = css.indexOf(`data-mode="${mode}"`)
+  if (at < 0) return undefined
+  const open = css.indexOf('{', at)
+  const close = open < 0 ? -1 : css.indexOf('}', open)
+  if (open < 0 || close < 0) return undefined
+  return css.slice(open + 1, close)
+}
+
+function tokenValue(block: string, token: string): string | undefined {
+  const match = new RegExp(`(?:^|[\\s;{])--${token}\\s*:\\s*([^;\\n]+)`).exec(block)
+  const value = match?.[1]?.trim()
+  return value === undefined || value.length === 0 ? undefined : value
+}
+
+function block(mode: 'light' | 'dark', vars: Record<string, string>): string {
+  const body = Object.entries(vars).map(([name, value]) => `${name}:${value}`).join(';')
+  if (body.length === 0) return ''
+  return `:root[data-mode="${mode}"]{${body}}`
+}

package/src/theme/parse.ts

@@ -0,0 +1,58 @@
+import { requiredThemeTokens } from './tokens.ts'
+
+/** Token names required in both modes. A short name such as `--bg` does not count. */
+
+export interface ParsedTheme {
+  /** Display name for English (and fallback). */
+  name: string
+  /** Optional Chinese display name. */
+  nameZh?: string
+}
+
+/**
+ * Admit a theme file. A missing required key ignores the file. It is not partially applied.
+ * @param css - file text
+ * @param fallbackName - id used when the header has no name
+ */
+export function parseThemeCss(css: string, fallbackName: string): { ok: true; theme: ParsedTheme } | { ok: false; reason: string } {
+  for (const mode of ['light', 'dark'] as const) {
+    const block = modeBlock(css, mode)
+    if (block === undefined) return { ok: false, reason: `missing ${mode} mode` }
+    for (const key of requiredThemeTokens) {
+      if (!hasShort(block, key)) return { ok: false, reason: `missing --${key} in ${mode}` }
+    }
+  }
+  return { ok: true, theme: headerNames(css, fallbackName) }
+}
+
+function modeBlock(css: string, mode: 'light' | 'dark'): string | undefined {
+  const at = css.indexOf(`data-mode="${mode}"`)
+  if (at < 0) return undefined
+  const open = css.indexOf('{', at)
+  const close = open < 0 ? -1 : css.indexOf('}', open)
+  if (open < 0 || close < 0) return undefined
+  return css.slice(open + 1, close)
+}
+
+function hasShort(block: string, key: string): boolean {
+  return new RegExp(`(?:^|[\\s;{])--${key}\\s*:`).test(block)
+}
+
+/**
+ * `/* name: English *\/` and optional `/* name-zh-CN: 中文 *\/`.
+ * A single `name` that is only Chinese still works as the sole label.
+ */
+function headerNames(css: string, fallbackName: string): ParsedTheme {
+  const name = headerField(css, 'name')
+  const nameZh = headerField(css, 'name-zh-CN')
+  if (name !== undefined && nameZh !== undefined) return { name, nameZh }
+  if (name !== undefined) return { name }
+  if (nameZh !== undefined) return { name: nameZh, nameZh }
+  return { name: fallbackName }
+}
+
+function headerField(css: string, field: string): string | undefined {
+  const match = new RegExp(`/\\*\\s*${field}:\\s*([^*]+?)\\s*\\*/`).exec(css)
+  const value = match?.[1]?.trim()
+  return value === undefined || value.length === 0 ? undefined : value
+}

package/src/theme/pin.ts

@@ -0,0 +1,197 @@
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises'
+
+import type { AppSummary } from '../apps/registry.ts'
+import { builtinThemesDir, customThemeId, customThemePath, themeLayout, appThemeCss, appThemePin } from './layout.ts'
+import { ThemeError } from './codes.ts'
+import { styleFromThemeCss } from './paint.ts'
+import { parseThemeCss } from './parse.ts'
+
+export type AppPin =
+  | { kind: 'default' }
+  | { kind: 'follow-host' }
+  | { kind: 'app-file' }
+  | { kind: 'palette'; id: string }
+
+export interface PaletteList {
+  palettes: Array<{ id: string; name: string; nameZh?: string; swatch: string; style: string; origin: 'builtin' | 'custom' }>
+  ignored: Array<{ file: string; reason: string }>
+}
+
+interface Registry {
+  get: (appId: string) => Promise<AppSummary>
+}
+
+/**
+ * Owner pin and palette list. Panel HTTP calls these through the loopback routes.
+ * @param registry - registered apps
+ * @param themesDir - host-global custom theme directory; creating it is allowed, listing does not require it
+ */
+export function createThemePins(registry: Registry, themesDir: string) {
+  return {
+    listPalettes: () => listPalettes(themesDir),
+    readPin: (appId: string) => readPin(registry, appId),
+    appFile: (appId: string) => appFileParsed(registry, appId),
+    readAppTheme: (appId: string) => readAppTheme(registry, appId),
+    setPin: (appId: string, pin: AppPin) => setPin(registry, themesDir, appId, pin),
+  }
+}
+
+async function listPalettes(themesDir: string): Promise<PaletteList> {
+  const palettes = await readThemeDir(builtinThemesDir(), [])
+  const ignored: PaletteList['ignored'] = []
+  const names = await readdir(themesDir).catch(() => [])
+  for (const file of names) {
+    const id = customThemeId(file)
+    if (id === undefined) {
+      ignored.push({ file, reason: 'file name is not theme-<id>.css' })
+      continue
+    }
+    const text = await readFile(customThemePath(themesDir, id), 'utf8').catch(() => undefined)
+    if (text === undefined) {
+      ignored.push({ file, reason: 'theme file is unreadable' })
+      continue
+    }
+    const parsed = parseThemeCss(text, id)
+    if (!parsed.ok) {
+      ignored.push({ file, reason: parsed.reason })
+      continue
+    }
+    const at = palettes.findIndex(item => item.id === id)
+    if (at >= 0) palettes.splice(at, 1)
+    palettes.push(paletteRow(id, parsed.theme, text, 'custom'))
+  }
+  return { palettes, ignored }
+}
+
+async function readThemeDir(dir: string, ignored: PaletteList['ignored']): Promise<PaletteList['palettes']> {
+  const palettes: PaletteList['palettes'] = []
+  const names = await readdir(dir).catch(() => [])
+  for (const file of names) {
+    const id = customThemeId(file)
+    if (id === undefined) continue
+    const text = await readFile(customThemePath(dir, id), 'utf8').catch(() => undefined)
+    if (text === undefined) continue
+    const parsed = parseThemeCss(text, id)
+    if (!parsed.ok) {
+      ignored.push({ file, reason: parsed.reason })
+      continue
+    }
+    palettes.push(paletteRow(id, parsed.theme, text, 'builtin'))
+  }
+  return palettes
+}
+
+function paletteRow(
+  id: string,
+  theme: { name: string; nameZh?: string },
+  text: string,
+  origin: 'builtin' | 'custom',
+): PaletteList['palettes'][number] {
+  return {
+    id,
+    name: theme.name,
+    ...theme.nameZh === undefined ? {} : { nameZh: theme.nameZh },
+    swatch: swatchOf(text),
+    style: styleFromThemeCss(text),
+    origin,
+  }
+}
+
+function swatchOf(css: string): string {
+  const light = css.split('[data-mode="dark"]')[0] ?? css
+  const match = /--primary:\s*([^;]+)/.exec(light)
+  const value = match?.[1]?.trim()
+  return value !== undefined && value.length > 0 ? value : '#888'
+}
+
+async function readPin(registry: Registry, appId: string): Promise<AppPin> {
+  const app = await registry.get(appId)
+  const text = await readFile(appThemePin(app.directory), 'utf8').catch(() => undefined)
+  if (text === undefined) return { kind: 'default' }
+  return admitPin(text)
+}
+
+async function setPin(registry: Registry, themesDir: string, appId: string, pin: AppPin): Promise<AppPin> {
+  const app = await registry.get(appId)
+  const file = appThemePin(app.directory)
+  if (pin.kind === 'default') {
+    await rm(file, { force: true })
+    return { kind: 'default' }
+  }
+  if (pin.kind === 'palette') await assertPalette(themesDir, pin.id)
+  if (pin.kind === 'app-file') await assertAppFile(app.directory)
+  const previous = await readFile(file, 'utf8').catch(() => undefined)
+  try {
+    await writeFile(file, `${JSON.stringify({ palette: stored(pin) })}\n`)
+    return pin
+  } catch (error) {
+    if (previous === undefined) await rm(file, { force: true })
+    else await writeFile(file, previous)
+    throw error
+  }
+}
+
+async function assertPalette(themesDir: string, id: string): Promise<void> {
+  const listed = await listPalettes(themesDir)
+  if (listed.palettes.some(item => item.id === id)) return
+  throw new ThemeError('theme-invalid', `unknown palette: ${id}`)
+}
+
+async function assertAppFile(appDir: string): Promise<void> {
+  const parsed = await readAppFile(appDir)
+  if (parsed === undefined) throw new ThemeError('theme-invalid', 'app theme.css is missing')
+  if (!parsed.ok) throw new ThemeError('theme-invalid', parsed.reason)
+}
+
+async function appFileParsed(registry: Registry, appId: string): Promise<boolean> {
+  const app = await registry.get(appId)
+  const parsed = await readAppFile(app.directory)
+  return parsed?.ok === true
+}
+
+async function readAppTheme(registry: Registry, appId: string): Promise<{
+  name?: string
+  nameZh?: string
+  swatch: string
+  style: string
+} | null> {
+  const app = await registry.get(appId)
+  const text = await readFile(appThemeCss(app.directory), 'utf8').catch(() => undefined)
+  if (text === undefined) return null
+  const parsed = parseThemeCss(text, 'app')
+  if (!parsed.ok) return null
+  const named = parsed.theme.name !== 'app'
+  return {
+    ...named ? { name: parsed.theme.name } : {},
+    ...parsed.theme.nameZh === undefined ? {} : { nameZh: parsed.theme.nameZh },
+    swatch: swatchOf(text),
+    style: styleFromThemeCss(text),
+  }
+}
+
+async function readAppFile(appDir: string) {
+  const text = await readFile(appThemeCss(appDir), 'utf8').catch(() => undefined)
+  if (text === undefined) return undefined
+  return parseThemeCss(text, themeLayout.appFile)
+}
+
+function stored(pin: Exclude<AppPin, { kind: 'default' }>): string {
+  if (pin.kind === 'follow-host') return themeLayout.followHost
+  if (pin.kind === 'app-file') return themeLayout.appFile
+  return pin.id
+}
+
+function admitPin(text: string): AppPin {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text) as unknown
+  } catch {
+    return { kind: 'default' }
+  }
+  if (typeof parsed !== 'object' || parsed === null || !('palette' in parsed) || typeof parsed.palette !== 'string') {
+    return { kind: 'default' }
+  }
+  if (parsed.palette === themeLayout.followHost) return { kind: 'follow-host' }
+  if (parsed.palette === themeLayout.appFile) return { kind: 'app-file' }
+  return { kind: 'palette', id: parsed.palette }
+}

package/src/theme/tokens.ts

@@ -0,0 +1,30 @@
+/**
+ * Theme tokens. The theme file declares these names. There is no second spelling.
+ * A missing optional token is omitted. No invented fallback colour.
+ */
+export const themeTokens = [
+  'background',
+  'foreground',
+  'card',
+  'card-foreground',
+  'border',
+  'muted',
+  'muted-foreground',
+  'primary',
+  'primary-foreground',
+  'secondary',
+  'secondary-foreground',
+  'accent',
+  'accent-foreground',
+  'destructive',
+  'destructive-foreground',
+  'ring',
+  'input',
+  'radius',
+  'shadow',
+] as const
+
+export type ThemeToken = (typeof themeTokens)[number]
+
+/** Required in both modes. A file missing one is ignored, not partially applied. */
+export const requiredThemeTokens = ['background', 'foreground', 'primary'] as const