@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/themes/loader.ts

@@ -0,0 +1,343 @@
+import { fileURLToPath } from "node:url"
+import { createRequire } from "node:module"
+import { dirname, resolve as resolvePath, join } from "node:path"
+import { cpSync, existsSync, readFileSync, readdirSync } from "node:fs"
+
+import type { AddonRegistry } from "@/addon/registry"
+import type { LoadedTheme } from "@/addon/api"
+import { ThemeJsonManifestSchema, type ThemeJsonManifest } from "./manifest"
+import { buildThemeCss } from "./css"
+import type { ThemeEntry } from "@/config/schemas"
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// ponytail: `here` is the themes dir when running from source
+// (`packages/cli/src/themes`) but the BUNDLE dir when running from dist
+// (`packages/cli/dist`), where the source tree isn't shipped. The dist build
+// sits one level below src/, so try the sibling src/themes fallback first —
+// this is what let the systemd unit (dist) crash on `theme: default` with
+// "not a registered theme". Each candidate is validated by the presence of
+// the `default` theme manifest so a stale candidate can never win.
+const resolveThemesRoot = (): string => {
+  const candidates = [
+    here,
+    resolvePath(here, "..", "src", "themes"),
+    resolvePath(here, "..", "..", "src", "themes"),
+  ]
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, "default", "sirenodeck.json"))) {
+      return candidate
+    }
+  }
+  return here
+}
+
+const themesRoot = resolveThemesRoot()
+
+// ponytail: sibling scan — first-party themes shipped outside the CLI package
+// (e.g. packages/themes/<name>) get registered as "sibling" so authors can
+// iterate on a theme in a separate workspace. From source `here` is
+// `<repo>/packages/cli/src/themes`, so `../../../themes` lands in
+// `<repo>/packages/themes`; from dist it's `<repo>/packages/cli/dist`, so
+// `../../themes` lands there instead.
+const siblingCandidates = [
+  resolvePath(themesRoot, "..", "..", "..", "themes"),
+  resolvePath(themesRoot, "..", "..", "themes"),
+]
+const siblingThemesRoot =
+  siblingCandidates.find((root) => existsSync(root)) ?? siblingCandidates[0]!
+
+export interface BuiltInThemeSpec {
+  name: string
+  dir: string
+}
+
+function _discoverThemesInRoot(
+  root: string,
+): ReadonlyArray<{ dir: string; name: string }> {
+  if (!existsSync(root)) return []
+  const entries = readdirSync(root, { withFileTypes: true })
+  const themes: { dir: string; name: string }[] = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const manifestPath = join(root, entry.name, "sirenodeck.json")
+    if (!existsSync(manifestPath)) continue
+    themes.push({ dir: join(root, entry.name), name: entry.name })
+  }
+  return themes
+}
+
+function _discoverThemesDir(): ReadonlyArray<{ dir: string; name: string }> {
+  return _discoverThemesInRoot(themesRoot)
+}
+
+function _discoverSiblingThemesDir(): ReadonlyArray<{
+  dir: string
+  name: string
+}> {
+  return _discoverThemesInRoot(siblingThemesRoot)
+}
+
+export const BUILT_IN_THEMES: ReadonlyArray<BuiltInThemeSpec> =
+  _discoverThemesDir().map(({ dir, name }) => ({ name, dir }))
+
+function discoverThemeManifests(): ReadonlyArray<{
+  dir: string
+  name: string
+}> {
+  return _discoverThemesDir()
+}
+
+export function readAndValidateManifest(
+  manifestPath: string,
+  expectedName?: string,
+): ThemeJsonManifest {
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8"))
+  } catch {
+    throw new Error(`Failed to parse theme manifest: ${manifestPath}`)
+  }
+  const result = ThemeJsonManifestSchema.safeParse(raw)
+  if (!result.success) {
+    throw new Error(
+      `Invalid theme manifest in ${manifestPath}: ${result.error.message}`,
+    )
+  }
+  if (expectedName !== undefined && result.data.name !== expectedName) {
+    throw new Error(
+      `Theme name '${result.data.name}' in ${manifestPath} does not match expected '${expectedName}'`,
+    )
+  }
+  return result.data
+}
+
+export function buildThemeCssFromManifest(
+  manifest: ThemeJsonManifest,
+  themeDir: string,
+): string {
+  const assetsStyles = (manifest.assets?.styles ?? ["./components.css"]).map(
+    (s) => resolvePath(themeDir, s),
+  )
+  const stylesheetContents = assetsStyles.map((p) => {
+    try {
+      return readFileSync(p, "utf8")
+    } catch {
+      return `/* stylesheet not found: ${p} */`
+    }
+  })
+  return buildThemeCss(manifest, stylesheetContents)
+}
+
+// ponytail: theme.css is emitted into the vite frontend's `.sirenodeck/`
+// dir, but its `url('./assets/...')` font/asset paths are relative to THAT
+// file — so the theme's assets/ must be copied next to it or every font 404s.
+export function copyThemeAssets(themeDir: string, cssDir: string): void {
+  const assetsDir = join(themeDir, "assets")
+  if (!existsSync(assetsDir)) return
+  cpSync(assetsDir, join(cssDir, "assets"), { recursive: true })
+}
+
+function buildLoadedTheme(
+  manifest: ThemeJsonManifest,
+  themeDir: string,
+  source:
+    | { kind: "builtin"; resolvedPath: string }
+    | { kind: "sibling"; resolvedPath: string }
+    | { kind: "local"; resolvedPath: string },
+): { theme: LoadedTheme; getCss: () => string } {
+  const uiOverridesPath = manifest["ui-overrides"]
+    ? resolvePath(themeDir, manifest["ui-overrides"])
+    : null
+
+  const theme: LoadedTheme = {
+    name: manifest.name,
+    apiVersion: manifest.apiVersion,
+    source,
+    manifestPath: join(themeDir, "sirenodeck.json"),
+    uiOverridesPath,
+    cssPath: "",
+  }
+
+  const getCss = (): string => buildThemeCssFromManifest(manifest, themeDir)
+
+  return { theme, getCss }
+}
+
+export function loadBuiltInThemes(): Array<{
+  theme: LoadedTheme
+  getCss: () => string
+}> {
+  const discovered = discoverThemeManifests()
+  return discovered.map(({ dir, name }) => {
+    const manifest = readAndValidateManifest(join(dir, "sirenodeck.json"), name)
+    return buildLoadedTheme(manifest, dir, {
+      kind: "builtin",
+      resolvedPath: dir,
+    })
+  })
+}
+
+export const registerBuiltInThemes = (registry: AddonRegistry): void => {
+  const builtIns = loadBuiltInThemes()
+  for (const { theme } of builtIns) {
+    registry.loadTheme(theme)
+  }
+}
+
+export function loadSiblingThemes(): Array<{
+  theme: LoadedTheme
+  getCss: () => string
+}> {
+  const discovered = _discoverSiblingThemesDir()
+  return discovered.map(({ dir, name }) => {
+    const manifest = readAndValidateManifest(join(dir, "sirenodeck.json"), name)
+    return buildLoadedTheme(manifest, dir, {
+      kind: "sibling",
+      resolvedPath: dir,
+    })
+  })
+}
+
+export const registerSiblingThemes = (registry: AddonRegistry): void => {
+  const siblings = loadSiblingThemes()
+  for (const { theme } of siblings) {
+    registry.loadTheme(theme)
+  }
+}
+
+export function loadThemeFromPath(
+  registry: AddonRegistry,
+  themePath: string,
+  aliasName?: string,
+): { theme: LoadedTheme; getCss: () => string } {
+  const resolvedPath = resolvePath(themePath)
+  const manifestPath = join(resolvedPath, "sirenodeck.json")
+  const manifest = readAndValidateManifest(manifestPath)
+  const { theme, getCss } = buildLoadedTheme(manifest, resolvedPath, {
+    kind: "local",
+    resolvedPath,
+  })
+  // ponytail: theme may already be registered by `registerSiblingThemes`
+  // (sibling scan at boot) or a previous load. Skip the duplicate-registration
+  // throw — the manifest-driven getCss callback is still produced either way.
+  if (registry.getTheme(theme.name) === undefined) {
+    registry.loadTheme(theme)
+  }
+  if (aliasName !== undefined && aliasName !== manifest.name) {
+    if (registry.getTheme(aliasName) === undefined) {
+      registry.loadTheme({ ...theme, name: aliasName })
+    }
+  }
+  return { theme, getCss }
+}
+
+export type ResolveThemeOptions = {
+  theme: ThemeEntry | undefined
+  packageRoots?: ReadonlyArray<string>
+}
+
+export interface ResolveThemeResult {
+  theme: LoadedTheme
+  getCss: () => string
+}
+
+/**
+ * Detect whether a string looks like a filesystem path. Strict prefix
+ * detection — only `./`, `../`, `/`, or a Windows drive letter. Anything
+ * else is treated as a registered theme name or an npm package.
+ */
+function isPathLike(s: string): boolean {
+  return (
+    s.startsWith("./") ||
+    s.startsWith("../") ||
+    s.startsWith("/") ||
+    /^[a-zA-Z]:[\\/]/.test(s)
+  )
+}
+
+/**
+ * Resolve an npm package name to its installed directory via Node's
+ * resolver. Returns null when the package isn't found.
+ */
+function resolvePackagePath(
+  name: string,
+  packageRoots: ReadonlyArray<string> = [],
+): string | null {
+  try {
+    const require = createRequire(import.meta.url)
+    const pkgJsonPath = require.resolve(`${name}/package.json`)
+    return dirname(pkgJsonPath)
+  } catch {
+    for (const root of packageRoots) {
+      const candidate = join(root, name)
+      if (existsSync(join(candidate, "package.json"))) return candidate
+    }
+    return null
+  }
+}
+
+const resolveBuiltinTheme = (
+  registry: AddonRegistry,
+  theme: LoadedTheme,
+): ResolveThemeResult => {
+  if (theme.source.kind === "builtin" || theme.source.kind === "sibling") {
+    const themeDir = dirname(theme.manifestPath)
+    const manifest = readAndValidateManifest(theme.manifestPath, theme.name)
+    return {
+      theme,
+      getCss: () => buildThemeCssFromManifest(manifest, themeDir),
+    }
+  }
+  return { theme, getCss: () => "" }
+}
+
+const resolveStringTheme = (
+  entry: string,
+  registry: AddonRegistry,
+  packageRoots: ReadonlyArray<string>,
+): ResolveThemeResult => {
+  // 1. Registered theme name (built-in auto-discovery or a previously
+  //    loaded theme). Use getTheme (returns undefined when missing);
+  //    resolveActiveTheme throws, which short-circuits the dispatcher.
+  const registered = registry.getTheme(entry)
+  if (registered) {
+    return resolveBuiltinTheme(registry, registered)
+  }
+
+  // 2. Path — `./`, `../`, `/`, or a Windows drive letter.
+  if (isPathLike(entry)) {
+    return loadThemeFromPath(registry, entry)
+  }
+
+  // 3. npm package — resolve to the installed package directory and load
+  //    the theme files inside it.
+  const packagePath = resolvePackagePath(entry, packageRoots)
+  if (packagePath !== null) {
+    return loadThemeFromPath(registry, packagePath)
+  }
+
+  throw new Error(
+    `Theme '${entry}' is not a registered theme, not a path, and not a known npm package.`,
+  )
+}
+
+export const resolveActiveTheme = (
+  registry: AddonRegistry,
+  options: ResolveThemeOptions,
+): ResolveThemeResult => {
+  const { theme: themeEntry } = options
+  if (themeEntry === undefined) {
+    const theme = registry.resolveActiveTheme(undefined)
+    return resolveBuiltinTheme(registry, theme)
+  }
+  if (typeof themeEntry === "object") {
+    const resolved = resolvePackagePath(themeEntry.src, options.packageRoots)
+    if (resolved === null)
+      throw new Error(
+        `Theme '${themeEntry.src}' is not installed. Run 'sirenodeck install ${themeEntry.src}'.`,
+      )
+    return loadThemeFromPath(registry, resolved)
+  }
+  return resolveStringTheme(themeEntry, registry, options.packageRoots ?? [])
+}

package/src/themes/manifest.ts

@@ -0,0 +1,164 @@
+import { z } from "zod"
+
+export const ThemeColorTokenSchema = z
+  .object({
+    background: z.string().min(1),
+    frame: z.string().min(1),
+    foreground: z.string().min(1),
+    "foreground-contrast": z.string().min(1),
+    primary: z.string().min(1),
+    accent: z.string().min(1),
+    muted: z.string().min(1).optional(),
+    success: z.string().min(1),
+    danger: z.string().min(1),
+  })
+  .strict()
+
+/**
+ * Required variant keys every theme must declare. Addons can rely on these
+ * five for highlights, warnings, success and error states without falling
+ * back to a hardcoded palette.
+ *
+ * Themes may declare EXTRA variants on top — those surface as `--sireno-variant-<name>-*`
+ * CSS vars and become available to user config.
+ */
+export const REQUIRED_VARIANT_KEYS = ["default", "error"] as const
+
+export type RequiredVariantKey = (typeof REQUIRED_VARIANT_KEYS)[number]
+
+const ThemeVariantTokenOverridesSchema = z
+  .object({
+    primary: z.string().min(1).optional(),
+    accent: z.string().min(1).optional(),
+    foreground: z.string().min(1).optional(),
+    "foreground-contrast": z.string().min(1).optional(),
+    success: z.string().min(1).optional(),
+    danger: z.string().min(1).optional(),
+    muted: z.string().min(1).optional(),
+  })
+  .strict()
+
+export const ThemeVariantStylesSchema = z
+  .object({
+    background: z.string().min(1),
+    border: z.string().min(1),
+    foreground: z.string().min(1),
+    glow: z.string().optional(),
+    tokens: ThemeVariantTokenOverridesSchema.optional(),
+  })
+  .strict()
+
+export const ThemeVariantsSchema = z
+  .record(z.string().min(1), ThemeVariantStylesSchema)
+  .superRefine((variants, ctx) => {
+    const missing = REQUIRED_VARIANT_KEYS.filter((k) => !(k in variants))
+    if (missing.length === 0) return
+    for (const key of missing) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: [key],
+        message: `theme manifest is missing required variant "${key}" — every theme must declare variants: { ${REQUIRED_VARIANT_KEYS.map((k) => `"${k}"`).join(", ")} } at minimum`,
+      })
+    }
+  })
+
+export const ThemeTypographyRoleSchema = z
+  .object({
+    fontFamily: z.string().min(1),
+    fontSize: z.number().positive(),
+    fontWeight: z.number().int().positive(),
+    letterSpacing: z.number().optional(),
+  })
+  .strict()
+
+export const ThemeTypographySchema = z
+  .object({
+    main_text: ThemeTypographyRoleSchema,
+    auxiliary_text: ThemeTypographyRoleSchema,
+    monospace: ThemeTypographyRoleSchema,
+  })
+  .strict()
+
+export const ThemeFontFaceSchema = z
+  .object({
+    fontFamily: z.string().min(1),
+    fontWeight: z.number().int().positive(),
+    fontStyle: z.enum(["normal", "italic", "oblique"]).default("normal"),
+    src: z.string().min(1),
+    /**
+     * Optional variable-font axes — accepts a [min, max] tuple per axis.
+     * When set, css.ts emits a single @font-face with `font-weight: from..to`
+     * shorthand so one entry can serve a range without duplicating files.
+     */
+    axes: z
+      .object({
+        weight: z.tuple([z.number().int(), z.number().int()]).optional(),
+        slant: z.tuple([z.number(), z.number()]).optional(),
+        width: z.tuple([z.number(), z.number()]).optional(),
+      })
+      .optional(),
+  })
+  .strict()
+
+export const ThemeEffectsSchema = z
+  .object({
+    glow: z
+      .object({
+        sm: z.string().min(1),
+        md: z.string().min(1),
+        lg: z.string().min(1),
+      })
+      .partial()
+      .optional(),
+    shadow: z
+      .object({
+        soft: z.string().min(1),
+        hard: z.string().min(1),
+      })
+      .partial()
+      .optional(),
+    blur: z
+      .object({
+        sm: z.string().min(1),
+        md: z.string().min(1),
+      })
+      .partial()
+      .optional(),
+  })
+  .strict()
+  .optional()
+
+export const ThemeAssetsSchema = z
+  .object({
+    styles: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+
+export const ThemeJsonManifestSchema = z
+  .object({
+    kind: z.literal("theme"),
+    apiVersion: z.number().int().positive(),
+    name: z.string().min(1),
+    version: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    colorTokens: ThemeColorTokenSchema,
+    typography: ThemeTypographySchema,
+    fonts: z.array(ThemeFontFaceSchema).default([]),
+    effects: ThemeEffectsSchema,
+    variants: ThemeVariantsSchema,
+    assets: ThemeAssetsSchema.optional(),
+    "ui-overrides": z.string().min(1).optional(),
+  })
+  .strict()
+
+export type ThemeJsonManifest = z.infer<typeof ThemeJsonManifestSchema>
+
+export type ThemeColorToken = keyof z.infer<typeof ThemeColorTokenSchema>
+
+export type ThemeTypographyRole = keyof z.infer<typeof ThemeTypographySchema>
+
+export type ThemeVariantStyles = z.infer<typeof ThemeVariantStylesSchema>
+
+export type ThemeVariantName = string
+
+export type ThemeVariants = z.infer<typeof ThemeVariantsSchema>

package/src/themes/use-resolved-theme.tsx

@@ -0,0 +1,32 @@
+import { createContext, useContext, type ReactNode } from "react"
+
+import type { LoadedTheme } from "@/addon/api"
+
+export interface ThemeContextValue {
+  name: string
+  cssPath: string
+  theme: LoadedTheme
+  colorTokens: Record<string, string> | null
+  typography: Record<string, unknown> | null
+}
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+export interface ThemeProviderProps {
+  value: ThemeContextValue
+  children: ReactNode
+}
+
+export const ThemeProvider = ({ value, children }: ThemeProviderProps) => (
+  <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+)
+
+export const useTheme = (): ThemeContextValue => {
+  const ctx = useContext(ThemeContext)
+  if (!ctx) {
+    throw new Error(
+      "useTheme must be used inside <ThemeProvider>. Ensure your app is wrapped in ThemeProvider with a resolved theme.",
+    )
+  }
+  return ctx
+}