create-nextblock 0.14.1 → 0.14.4

package/templates/nextblock-template/lib/storage/supabase-storage.ts

@@ -1,103 +1,103 @@
-import 'server-only';
-
-import { getServiceRoleSupabaseClient } from '@nextblock-cms/db/server';
-
-import { getStorageBucket } from './provider';
-
-// Native Supabase Storage operations, authenticated with the service-role/secret key.
-// Used only when getStorageBackend() === 'supabase' (the zero-S3-key Vercel path). These
-// mirror what the S3 routes do via @aws-sdk/client-s3, so the upload → process → display
-// → delete pipeline works identically without any S3 access keys.
-
-// The public bucket is created once per process. Cache the in-flight promise (not a bare
-// boolean) so concurrent uploads share a SINGLE createBucket call instead of racing — and
-// clear it on failure so a later request can retry rather than inheriting a cached rejection.
-let bucketEnsurePromise: Promise<void> | null = null;
-
-/** Idempotently ensure a PUBLIC bucket exists for media. Safe to call concurrently. */
-export function ensureStorageBucket(): Promise<void> {
-  if (bucketEnsurePromise) return bucketEnsurePromise;
-
-  bucketEnsurePromise = (async () => {
-    const bucket = getStorageBucket();
-    if (!bucket) throw new Error('No storage bucket name is configured.');
-
-    const admin = getServiceRoleSupabaseClient();
-    // public: true is REQUIRED — media is served from /storage/v1/object/public/<bucket>,
-    // which returns 401 for a private bucket. Do not drop this flag.
-    const { error } = await admin.storage.createBucket(bucket, { public: true });
-    if (error && !/already exists|duplicate|resource already exists/i.test(error.message)) {
-      // Non-"exists" error — confirm via getBucket before treating it as fatal.
-      const { data } = await admin.storage.getBucket(bucket);
-      if (!data) {
-        throw new Error(`Could not ensure storage bucket "${bucket}": ${error.message}`);
-      }
-    }
-  })();
-
-  // On failure, drop the cached promise so the next caller retries (don't cache a rejection).
-  bucketEnsurePromise.catch(() => {
-    bucketEnsurePromise = null;
-  });
-
-  return bucketEnsurePromise;
-}
-
-/** Upload (or overwrite) an object. */
-export async function supabaseUploadObject(
-  key: string,
-  body: Buffer,
-  contentType: string,
-): Promise<void> {
-  await ensureStorageBucket();
-  const admin = getServiceRoleSupabaseClient();
-  const { error } = await admin.storage
-    .from(getStorageBucket())
-    .upload(key, body, { contentType, upsert: true });
-  if (error) {
-    throw new Error(`Supabase Storage upload failed for "${key}": ${error.message}`);
-  }
-}
-
-/** Download an object as a Buffer (used by the image processor to fetch the original). */
-export async function supabaseDownloadObject(key: string): Promise<Buffer> {
-  const admin = getServiceRoleSupabaseClient();
-  const { data, error } = await admin.storage.from(getStorageBucket()).download(key);
-  if (error || !data) {
-    throw new Error(
-      `Supabase Storage download failed for "${key}": ${error?.message ?? 'no data returned'}`,
-    );
-  }
-  return Buffer.from(await data.arrayBuffer());
-}
-
-/**
- * Create a signed upload URL for a NEW object key. The browser PUTs the file bytes to the
- * returned URL directly (the same shape as an S3 presigned PUT), so large uploads never
- * pass through the serverless function. The token is embedded in the URL.
- */
-export async function supabaseCreateSignedUpload(
-  key: string,
-): Promise<{ signedUrl: string; token: string }> {
-  await ensureStorageBucket();
-  const admin = getServiceRoleSupabaseClient();
-  const { data, error } = await admin.storage
-    .from(getStorageBucket())
-    .createSignedUploadUrl(key);
-  if (error || !data?.signedUrl) {
-    throw new Error(
-      `Supabase Storage signed upload URL failed for "${key}": ${error?.message ?? 'no URL returned'}`,
-    );
-  }
-  return { signedUrl: data.signedUrl, token: data.token };
-}
-
-/** Remove one or more objects. No-op for an empty list. */
-export async function supabaseRemoveObjects(keys: string[]): Promise<void> {
-  if (keys.length === 0) return;
-  const admin = getServiceRoleSupabaseClient();
-  const { error } = await admin.storage.from(getStorageBucket()).remove(keys);
-  if (error) {
-    throw new Error(`Supabase Storage remove failed: ${error.message}`);
-  }
-}
+import 'server-only';
+
+import { getServiceRoleSupabaseClient } from '@nextblock-cms/db/server';
+
+import { getStorageBucket } from './provider';
+
+// Native Supabase Storage operations, authenticated with the service-role/secret key.
+// Used only when getStorageBackend() === 'supabase' (the zero-S3-key Vercel path). These
+// mirror what the S3 routes do via @aws-sdk/client-s3, so the upload → process → display
+// → delete pipeline works identically without any S3 access keys.
+
+// The public bucket is created once per process. Cache the in-flight promise (not a bare
+// boolean) so concurrent uploads share a SINGLE createBucket call instead of racing — and
+// clear it on failure so a later request can retry rather than inheriting a cached rejection.
+let bucketEnsurePromise: Promise<void> | null = null;
+
+/** Idempotently ensure a PUBLIC bucket exists for media. Safe to call concurrently. */
+export function ensureStorageBucket(): Promise<void> {
+  if (bucketEnsurePromise) return bucketEnsurePromise;
+
+  bucketEnsurePromise = (async () => {
+    const bucket = getStorageBucket();
+    if (!bucket) throw new Error('No storage bucket name is configured.');
+
+    const admin = getServiceRoleSupabaseClient();
+    // public: true is REQUIRED — media is served from /storage/v1/object/public/<bucket>,
+    // which returns 401 for a private bucket. Do not drop this flag.
+    const { error } = await admin.storage.createBucket(bucket, { public: true });
+    if (error && !/already exists|duplicate|resource already exists/i.test(error.message)) {
+      // Non-"exists" error — confirm via getBucket before treating it as fatal.
+      const { data } = await admin.storage.getBucket(bucket);
+      if (!data) {
+        throw new Error(`Could not ensure storage bucket "${bucket}": ${error.message}`);
+      }
+    }
+  })();
+
+  // On failure, drop the cached promise so the next caller retries (don't cache a rejection).
+  bucketEnsurePromise.catch(() => {
+    bucketEnsurePromise = null;
+  });
+
+  return bucketEnsurePromise;
+}
+
+/** Upload (or overwrite) an object. */
+export async function supabaseUploadObject(
+  key: string,
+  body: Buffer,
+  contentType: string,
+): Promise<void> {
+  await ensureStorageBucket();
+  const admin = getServiceRoleSupabaseClient();
+  const { error } = await admin.storage
+    .from(getStorageBucket())
+    .upload(key, body, { contentType, upsert: true });
+  if (error) {
+    throw new Error(`Supabase Storage upload failed for "${key}": ${error.message}`);
+  }
+}
+
+/** Download an object as a Buffer (used by the image processor to fetch the original). */
+export async function supabaseDownloadObject(key: string): Promise<Buffer> {
+  const admin = getServiceRoleSupabaseClient();
+  const { data, error } = await admin.storage.from(getStorageBucket()).download(key);
+  if (error || !data) {
+    throw new Error(
+      `Supabase Storage download failed for "${key}": ${error?.message ?? 'no data returned'}`,
+    );
+  }
+  return Buffer.from(await data.arrayBuffer());
+}
+
+/**
+ * Create a signed upload URL for a NEW object key. The browser PUTs the file bytes to the
+ * returned URL directly (the same shape as an S3 presigned PUT), so large uploads never
+ * pass through the serverless function. The token is embedded in the URL.
+ */
+export async function supabaseCreateSignedUpload(
+  key: string,
+): Promise<{ signedUrl: string; token: string }> {
+  await ensureStorageBucket();
+  const admin = getServiceRoleSupabaseClient();
+  const { data, error } = await admin.storage
+    .from(getStorageBucket())
+    .createSignedUploadUrl(key);
+  if (error || !data?.signedUrl) {
+    throw new Error(
+      `Supabase Storage signed upload URL failed for "${key}": ${error?.message ?? 'no URL returned'}`,
+    );
+  }
+  return { signedUrl: data.signedUrl, token: data.token };
+}
+
+/** Remove one or more objects. No-op for an empty list. */
+export async function supabaseRemoveObjects(keys: string[]): Promise<void> {
+  if (keys.length === 0) return;
+  const admin = getServiceRoleSupabaseClient();
+  const { error } = await admin.storage.from(getStorageBucket()).remove(keys);
+  if (error) {
+    throw new Error(`Supabase Storage remove failed: ${error.message}`);
+  }
+}

package/templates/nextblock-template/lib/themes/buildThemeCss.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest';
+import {
+  activeThemeSlugs,
+  buildThemeCss,
+  darkSchemeSlugs,
+  defaultThemeSlug,
+  isValidThemeSlug,
+  sanitizeExtraCss,
+  type SiteTheme,
+} from './buildThemeCss';
+import { isValidTokenValue } from './tokens';
+
+function theme(overrides: Partial<SiteTheme> = {}): SiteTheme {
+  return {
+    id: 'id-1',
+    slug: 'light',
+    name: 'Light',
+    description: null,
+    icon: 'Sun',
+    color_scheme: 'light',
+    tokens: { background: '0 0% 100%', foreground: '222 47% 11%' },
+    extra_css: null,
+    is_system: true,
+    is_default: true,
+    is_active: true,
+    sort_order: 10,
+    ...overrides,
+  };
+}
+
+describe('buildThemeCss', () => {
+  it('emits the default theme on :root and every theme on :root.slug', () => {
+    const css = buildThemeCss([theme(), theme({ id: 'id-2', slug: 'dark', color_scheme: 'dark', is_default: false })]);
+    expect(css).toContain(':root {');
+    expect(css).toContain(':root.light {');
+    expect(css).toContain(':root.dark {');
+    expect(css).toContain('--background: 0 0% 100%;');
+  });
+
+  it('sets color-scheme so native form controls follow the theme', () => {
+    const css = buildThemeCss([theme({ slug: 'dark', color_scheme: 'dark' })]);
+    expect(css).toContain('color-scheme: dark;');
+  });
+
+  it('skips inactive themes entirely', () => {
+    const css = buildThemeCss([theme(), theme({ id: 'x', slug: 'retired', is_active: false, is_default: false })]);
+    expect(css).not.toContain('retired');
+  });
+
+  it('returns empty string when there is nothing active', () => {
+    expect(buildThemeCss([])).toBe('');
+    expect(buildThemeCss([theme({ is_active: false })])).toBe('');
+  });
+
+  it('falls back to the first active theme when none is marked default', () => {
+    const css = buildThemeCss([theme({ slug: 'aaa', is_default: false, tokens: { background: '1 2% 3%' } })]);
+    expect(css).toContain(':root {\n  --background: 1 2% 3%;');
+  });
+
+  // --- Injection resistance -------------------------------------------------
+
+  it('drops unknown token keys', () => {
+    const css = buildThemeCss([theme({ tokens: { background: '0 0% 100%', 'evil-key': '0 0% 0%' } })]);
+    expect(css).toContain('--background');
+    expect(css).not.toContain('evil-key');
+  });
+
+  it('drops token values that try to close the declaration', () => {
+    const css = buildThemeCss([
+      theme({ tokens: { background: '0 0% 100%; } body { display: none' } }),
+    ]);
+    expect(css).not.toContain('display: none');
+    expect(css).not.toContain('body {');
+  });
+
+  it('drops token values containing url() or markup', () => {
+    for (const bad of ['url(https://evil.test/x)', '<script>', 'red', 'expression(alert(1))']) {
+      const css = buildThemeCss([theme({ tokens: { background: bad } })]);
+      expect(css).not.toContain(bad);
+    }
+  });
+
+  it('rejects a slug that is not CSS-class safe', () => {
+    expect(isValidThemeSlug('ok-slug')).toBe(true);
+    expect(isValidThemeSlug('Bad Slug')).toBe(false);
+    expect(isValidThemeSlug('a')).toBe(false);
+    expect(isValidThemeSlug('-leading')).toBe(false);
+    expect(isValidThemeSlug('trailing-')).toBe(false);
+    expect(isValidThemeSlug('x{}')).toBe(false);
+    const css = buildThemeCss([theme({ slug: 'evil { } body' })]);
+    expect(css).toBe('');
+  });
+});
+
+describe('sanitizeExtraCss', () => {
+  it('strips markup so the <style> element cannot be closed', () => {
+    expect(sanitizeExtraCss('& h1 { color: red }</style><script>alert(1)</script>')).not.toContain('<');
+  });
+
+  it('drops a stray closing brace that would escape the theme rule', () => {
+    const out = sanitizeExtraCss('} body { display: none }');
+    expect(out.startsWith('}')).toBe(false);
+    // The `body` rule survives as a NESTED selector, which is inert, but it must
+    // not have escaped to the top level.
+    expect(out).toBe(' body { display: none }');
+  });
+
+  it('closes braces the author left open', () => {
+    expect(sanitizeExtraCss('& h1 { color: red')).toBe('& h1 { color: red}');
+  });
+
+  it('passes through legitimate nested css untouched', () => {
+    const css = '& h1 { text-shadow: 0 0 5px hsl(var(--primary)); }';
+    expect(sanitizeExtraCss(css)).toBe(css);
+  });
+
+  it('is applied by buildThemeCss', () => {
+    const css = buildThemeCss([theme({ extra_css: '& h1 { color: red }</style>' })]);
+    expect(css).not.toContain('</style>');
+    expect(css).toContain('& h1 { color: red }');
+  });
+});
+
+describe('isValidTokenValue', () => {
+  it('accepts hsl triplets for colours and lengths for radius', () => {
+    expect(isValidTokenValue('background', '222 47% 11%')).toBe(true);
+    expect(isValidTokenValue('background', '211.55, 50.26%, 37.84%')).toBe(true);
+    expect(isValidTokenValue('radius', '0.75rem')).toBe(true);
+    expect(isValidTokenValue('radius', '0px')).toBe(true);
+    expect(isValidTokenValue('radius', '0')).toBe(true);
+  });
+
+  it('rejects the wrong shape for the token kind', () => {
+    expect(isValidTokenValue('background', '#ffffff')).toBe(false);
+    expect(isValidTokenValue('radius', '222 47% 11%')).toBe(false);
+    expect(isValidTokenValue('unknown-token', '222 47% 11%')).toBe(false);
+  });
+});
+
+describe('theme wiring helpers', () => {
+  const themes = [
+    theme({ id: '1', slug: 'light', sort_order: 10, is_default: true }),
+    theme({ id: '2', slug: 'dark', color_scheme: 'dark', sort_order: 20, is_default: false }),
+    theme({ id: '3', slug: 'vibrant', color_scheme: 'dark', sort_order: 30, is_default: false, is_system: false }),
+  ];
+
+  it('reports which slugs use a dark palette', () => {
+    // Deliberately NOT a "slug + .dark class" map: next-themes applies its value
+    // with a single classList.add(), and DOMTokenList.add throws
+    // InvalidCharacterError on a string containing a space.
+    expect(darkSchemeSlugs(themes)).toEqual(['dark', 'vibrant']);
+  });
+
+  it('orders slugs by sort_order', () => {
+    expect(activeThemeSlugs(themes)).toEqual(['light', 'dark', 'vibrant']);
+  });
+
+  it('reports the default slug and falls back safely', () => {
+    expect(defaultThemeSlug(themes)).toBe('light');
+    expect(defaultThemeSlug([])).toBe('light');
+    expect(defaultThemeSlug([theme({ slug: 'only', is_default: false })])).toBe('only');
+  });
+});

package/templates/nextblock-template/lib/themes/buildThemeCss.ts

@@ -0,0 +1,124 @@
+import { isThemeTokenKey, isValidTokenValue } from './tokens';
+
+export interface SiteTheme {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  icon: string;
+  color_scheme: 'light' | 'dark';
+  tokens: Record<string, string>;
+  extra_css: string | null;
+  is_system: boolean;
+  is_default: boolean;
+  is_active: boolean;
+  sort_order: number;
+}
+
+/** Matches the DB CHECK constraint on site_themes.slug. */
+export const THEME_SLUG_PATTERN = /^[a-z][a-z0-9-]{0,38}[a-z0-9]$/;
+
+export function isValidThemeSlug(slug: string): boolean {
+  return THEME_SLUG_PATTERN.test(slug);
+}
+
+/**
+ * Strip anything that could break out of the surrounding <style> element or
+ * escape the theme's own nesting block. Author-supplied CSS is ADMIN-only, but
+ * it is interpolated into `dangerouslySetInnerHTML`, so it is still untrusted.
+ *
+ * `<` is removed outright — no legitimate theme CSS needs it, and it is the only
+ * way to write `</style>`. Unbalanced braces are dropped so a stray `}` cannot
+ * close the theme rule and leak declarations into the global scope.
+ */
+export function sanitizeExtraCss(css: string): string {
+  const withoutMarkup = css.replace(/[<>]/g, '');
+  let depth = 0;
+  let out = '';
+  for (const char of withoutMarkup) {
+    if (char === '{') {
+      depth += 1;
+    } else if (char === '}') {
+      if (depth === 0) continue; // Would close the theme rule — drop it.
+      depth -= 1;
+    }
+    out += char;
+  }
+  // Close anything the author left open so the next rule is not swallowed.
+  return out + '}'.repeat(depth);
+}
+
+function declarationsFor(theme: SiteTheme): string {
+  const entries = Object.entries(theme.tokens ?? {})
+    .filter(([key, value]) => isThemeTokenKey(key) && typeof value === 'string' && isValidTokenValue(key, value))
+    .map(([key, value]) => `  --${key}: ${value.trim()};`);
+  entries.push(`  color-scheme: ${theme.color_scheme === 'dark' ? 'dark' : 'light'};`);
+  return entries.join('\n');
+}
+
+function ruleFor(selector: string, theme: SiteTheme): string {
+  const body = declarationsFor(theme);
+  const extra = theme.extra_css?.trim() ? `\n${sanitizeExtraCss(theme.extra_css.trim())}` : '';
+  return `${selector} {\n${body}${extra}\n}`;
+}
+
+/**
+ * Render every theme to CSS for injection into <head>.
+ *
+ * Emitted as `:root.<slug>` (specificity 0,2,0) rather than `.<slug>` (0,1,0) so
+ * database themes always win over the fallback palette still shipped in
+ * libs/ui/src/styles/theme.css for standalone consumers of @nextblock-cms/ui,
+ * regardless of stylesheet order.
+ *
+ * The default theme is additionally emitted on bare `:root` so the very first
+ * paint — before next-themes' blocking script adds the class — already uses the
+ * right palette instead of flashing the library fallback.
+ */
+export function buildThemeCss(themes: SiteTheme[]): string {
+  const active = themes.filter((theme) => theme.is_active && isValidThemeSlug(theme.slug));
+  if (active.length === 0) return '';
+
+  const blocks: string[] = [];
+  const fallback = active.find((theme) => theme.is_default) ?? active[0];
+  if (fallback) {
+    blocks.push(ruleFor(':root', fallback));
+  }
+  for (const theme of active) {
+    blocks.push(ruleFor(`:root.${theme.slug}`, theme));
+  }
+  return blocks.join('\n\n');
+}
+
+/**
+ * Slugs whose palette is dark. Used for the CSS `color-scheme` declaration, and
+ * exposed so the CMS can warn that a custom dark theme does not pick up
+ * Tailwind's `dark:` utilities.
+ *
+ * NOTE — why there is no "also apply the .dark class" mapping here: next-themes
+ * applies its value with a single `classList.add(value)`, and DOMTokenList.add
+ * throws InvalidCharacterError on a string containing a space, so a `"vibrant
+ * dark"` mapping crashes the switcher. Tailwind's dark variant is compiled to
+ * `.dark`, and the set of dark themes is only known at runtime, so it cannot be
+ * widened at build time either. Wiring `dark:` to a data attribute would need a
+ * pre-hydration script mirroring next-themes' own; deliberately out of scope.
+ * A custom dark theme therefore recolours every token but does not activate
+ * `dark:` utilities — same as the shipped `.vibrant` theme has always behaved.
+ */
+export function darkSchemeSlugs(themes: SiteTheme[]): string[] {
+  return themes
+    .filter((theme) => theme.is_active && isValidThemeSlug(theme.slug) && theme.color_scheme === 'dark')
+    .map((theme) => theme.slug);
+}
+
+/** Slugs offered to next-themes, in display order. */
+export function activeThemeSlugs(themes: SiteTheme[]): string[] {
+  return themes
+    .filter((theme) => theme.is_active && isValidThemeSlug(theme.slug))
+    .sort((a, b) => a.sort_order - b.sort_order)
+    .map((theme) => theme.slug);
+}
+
+export function defaultThemeSlug(themes: SiteTheme[]): string {
+  const active = themes.filter((theme) => theme.is_active && isValidThemeSlug(theme.slug));
+  return (active.find((theme) => theme.is_default) ?? active[0])?.slug ?? 'light';
+}

package/templates/nextblock-template/lib/themes/tokenColor.ts

@@ -0,0 +1,31 @@
+import { parseCssColor, rgbaToHex, rgbaToHsla, type Rgba } from '@nextblock-cms/utils';
+
+/**
+ * Bridge between how theme colours are STORED and how the colour picker speaks.
+ *
+ * Stored: a bare HSL triplet (`"222 47% 11%"`), because the Tailwind config wraps
+ * it as `hsl(var(--token))` and appends alpha as `hsl(var(--primary) / 0.5)` —
+ * that composition only works with a bare triplet.
+ * Picker: any CSS colour string, normally a hex.
+ */
+
+export function tokenValueToCss(triplet: string): string {
+  return `hsl(${triplet.trim()})`;
+}
+
+/** Triplet -> hex, for seeding the colour picker. Returns null if unparseable. */
+export function tokenValueToHex(triplet: string): string | null {
+  const rgba = parseCssColor(tokenValueToCss(triplet));
+  return rgba ? rgbaToHex(rgba) : null;
+}
+
+/**
+ * Any CSS colour -> the stored triplet. Alpha is dropped: these tokens are
+ * composed with an alpha at use time, so baking one in would double-apply it.
+ */
+export function cssColorToTokenValue(color: string): string | null {
+  const rgba: Rgba | null = parseCssColor(color);
+  if (!rgba) return null;
+  const { h, s, l } = rgbaToHsla(rgba);
+  return `${h} ${s}% ${l}%`;
+}

package/templates/nextblock-template/lib/themes/tokens.ts

@@ -0,0 +1,143 @@
+/**
+ * The design tokens a theme can set.
+ *
+ * These mirror the CSS custom properties consumed by libs/ui/tailwind.config.js.
+ * Anything not listed here is rejected when a theme is saved, so a stored theme
+ * can never introduce an unknown custom property (or a CSS injection) into the
+ * stylesheet the root layout renders.
+ */
+
+export type ThemeTokenKind = 'color' | 'length';
+
+export interface ThemeTokenDef {
+  /** Custom property name without the leading `--`. */
+  key: string;
+  label: string;
+  kind: ThemeTokenKind;
+  /** Token whose value is a sensible backdrop for contrast-checking this one. */
+  pairedWith?: string;
+  hint?: string;
+}
+
+export interface ThemeTokenGroup {
+  id: string;
+  label: string;
+  description: string;
+  tokens: ThemeTokenDef[];
+}
+
+export const THEME_TOKEN_GROUPS: ThemeTokenGroup[] = [
+  {
+    id: 'surfaces',
+    label: 'Surfaces',
+    description: 'Page and container backgrounds, and the text that sits on them.',
+    tokens: [
+      { key: 'background', label: 'Page background', kind: 'color' },
+      { key: 'foreground', label: 'Body text', kind: 'color', pairedWith: 'background' },
+      { key: 'card', label: 'Card background', kind: 'color' },
+      { key: 'card-foreground', label: 'Card text', kind: 'color', pairedWith: 'card' },
+      { key: 'popover', label: 'Popover background', kind: 'color' },
+      { key: 'popover-foreground', label: 'Popover text', kind: 'color', pairedWith: 'popover' },
+    ],
+  },
+  {
+    id: 'brand',
+    label: 'Brand',
+    description: 'Primary actions and supporting brand tints.',
+    tokens: [
+      { key: 'primary', label: 'Primary', kind: 'color' },
+      { key: 'primary-foreground', label: 'On primary', kind: 'color', pairedWith: 'primary' },
+      { key: 'secondary', label: 'Secondary', kind: 'color' },
+      { key: 'secondary-foreground', label: 'On secondary', kind: 'color', pairedWith: 'secondary' },
+      { key: 'accent', label: 'Accent', kind: 'color' },
+      { key: 'accent-foreground', label: 'On accent', kind: 'color', pairedWith: 'accent' },
+    ],
+  },
+  {
+    id: 'states',
+    label: 'States',
+    description: 'Feedback colours and de-emphasised content.',
+    tokens: [
+      { key: 'muted', label: 'Muted surface', kind: 'color' },
+      { key: 'muted-foreground', label: 'Muted text', kind: 'color', pairedWith: 'background' },
+      { key: 'destructive', label: 'Destructive', kind: 'color' },
+      { key: 'destructive-foreground', label: 'On destructive', kind: 'color', pairedWith: 'destructive' },
+      { key: 'warning', label: 'Warning', kind: 'color' },
+      { key: 'warning-foreground', label: 'On warning', kind: 'color', pairedWith: 'warning' },
+    ],
+  },
+  {
+    id: 'controls',
+    label: 'Controls',
+    description: 'Borders, form inputs and focus rings.',
+    tokens: [
+      { key: 'border', label: 'Border', kind: 'color' },
+      { key: 'input', label: 'Input border', kind: 'color' },
+      { key: 'ring', label: 'Focus ring', kind: 'color' },
+    ],
+  },
+  {
+    id: 'charts',
+    label: 'Charts',
+    description: 'Categorical series colours for data visualisations.',
+    tokens: [
+      { key: 'chart-1', label: 'Series 1', kind: 'color' },
+      { key: 'chart-2', label: 'Series 2', kind: 'color' },
+      { key: 'chart-3', label: 'Series 3', kind: 'color' },
+      { key: 'chart-4', label: 'Series 4', kind: 'color' },
+      { key: 'chart-5', label: 'Series 5', kind: 'color' },
+    ],
+  },
+  {
+    id: 'shape',
+    label: 'Shape',
+    description: 'Global geometry.',
+    tokens: [
+      {
+        key: 'radius',
+        label: 'Corner radius',
+        kind: 'length',
+        hint: 'A CSS length, e.g. 0.75rem. Use 0px for square corners.',
+      },
+    ],
+  },
+];
+
+export const THEME_TOKENS: ThemeTokenDef[] = THEME_TOKEN_GROUPS.flatMap((group) => group.tokens);
+
+export const THEME_TOKEN_KEYS: string[] = THEME_TOKENS.map((token) => token.key);
+
+const TOKEN_BY_KEY = new Map(THEME_TOKENS.map((token) => [token.key, token]));
+
+export function getThemeToken(key: string): ThemeTokenDef | undefined {
+  return TOKEN_BY_KEY.get(key);
+}
+
+export function isThemeTokenKey(key: string): boolean {
+  return TOKEN_BY_KEY.has(key);
+}
+
+/**
+ * Colour tokens are stored as bare HSL triplets (`"222 47% 11%"`) because the
+ * Tailwind config wraps them in `hsl(var(--token))` and relies on being able to
+ * append an alpha, as in `hsl(var(--primary) / 0.5)`.
+ */
+export const HSL_TRIPLET_PATTERN = /^-?\d{1,3}(?:\.\d+)?(?:deg)?[\s,]+\d{1,3}(?:\.\d+)?%[\s,]+\d{1,3}(?:\.\d+)?%$/;
+
+export const LENGTH_PATTERN = /^(?:0|-?\d{1,4}(?:\.\d+)?(?:px|rem|em|%|vh|vw))$/;
+
+/**
+ * Reject anything that could terminate the declaration and start a new rule.
+ * Values are interpolated into a <style> tag, so this is a security boundary,
+ * not a nicety.
+ */
+const UNSAFE_VALUE_CHARS = /[;{}<>@\\()]/;
+
+export function isValidTokenValue(key: string, value: string): boolean {
+  const token = getThemeToken(key);
+  if (!token) return false;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > 64) return false;
+  if (UNSAFE_VALUE_CHARS.test(trimmed)) return false;
+  return token.kind === 'color' ? HSL_TRIPLET_PATTERN.test(trimmed) : LENGTH_PATTERN.test(trimmed);
+}