@ethlete/core 5.0.0-next.7 → 5.0.0-next.71

package/generators/tailwind-4-surface-theme/generator.js

@@ -0,0 +1,379 @@
+import { formatFiles, logger, visitNotIgnoredFiles } from '@nx/devkit';
+import { Project, SyntaxKind } from 'ts-morph';
+import { cssThemeName, surfaceThemeCss } from '../../design/theme-css.js';
+export default async function generate(tree, schema) {
+    logger.log('\n🔄 Starting Tailwind 4 surface theme generator...\n');
+    const themesPath = schema.themesPath || 'src/surface-themes.ts';
+    const outputPath = schema.outputPath || 'src/styles/generated-tailwind-surface-themes.css';
+    const prefix = schema.prefix || 'et';
+    // The runtime prefix drives the theme-swap CSS variables (--<runtimePrefix>-surface-*)
+    // and selectors (.<runtimePrefix>-surface--<name>). It defaults to `prefix` so existing
+    // consumers who only ever passed one prefix see no change in output.
+    const runtimePrefix = schema.runtimePrefix || prefix;
+    if (!tree.exists(themesPath)) {
+        logger.error(`❌ Surface themes file not found at: ${themesPath}`);
+        logger.log(`\nPlease specify the correct path using --themesPath option.`);
+        logger.log(`Example: nx g @ethlete/core:tailwind-4-surface-theme --themesPath=src/app/surface-themes.ts\n`);
+        return;
+    }
+    logger.log(`📁 Reading surface themes from: ${themesPath}`);
+    const themesContent = tree.read(themesPath, 'utf-8');
+    if (!themesContent) {
+        logger.error('❌ Failed to read surface themes file');
+        return;
+    }
+    let themes;
+    try {
+        themes = extractSurfaceThemesFromContent(themesContent, themesPath);
+        logger.log(`✅ Found ${themes.length} surface theme(s)`);
+    }
+    catch (error) {
+        logger.error('❌ Failed to parse surface themes file');
+        logger.error(`   ${error instanceof Error ? error.message : String(error)}`);
+        logger.log('\nThe surface themes file must export themes as:');
+        logger.log('  export const SURFACE_THEMES = [...] satisfies SurfaceTheme[];\n');
+        return;
+    }
+    // Apply the generation-time default overrides, if any. The shared theme definitions may
+    // mark defaults via isDefault, but in a monorepo each app picks its own defaults at its
+    // generation invocation - the options win over the definitions (per surface type).
+    try {
+        if (schema.defaultLightTheme) {
+            const name = applyDefaultSurfaceThemeOverride(themes, schema.defaultLightTheme, 'light');
+            logger.log(`🎯 Default light surface theme set at generation time: ${name}`);
+        }
+        if (schema.defaultDarkTheme) {
+            const name = applyDefaultSurfaceThemeOverride(themes, schema.defaultDarkTheme, 'dark');
+            logger.log(`🎯 Default dark surface theme set at generation time: ${name}`);
+        }
+    }
+    catch (error) {
+        logger.error('❌ Invalid default theme option');
+        logger.error(`   ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    try {
+        validateSurfaceThemeConfiguration(themes);
+    }
+    catch (error) {
+        logger.error('❌ Surface theme configuration error');
+        logger.error(`   ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    logger.log('\n🎨 Generating Tailwind surface theme CSS...');
+    const css = generateSurfaceThemeCss(themes, prefix, runtimePrefix, schema);
+    const typesOutputPath = schema.typesOutputPath ?? outputPath.replace(/\.css$/, '.d.ts');
+    if (typesOutputPath === outputPath) {
+        throw new Error('A custom outputPath must end in .css or be paired with a distinct typesOutputPath.');
+    }
+    tree.write(outputPath, css);
+    logger.log(`✅ Generated Tailwind surface themes at: ${outputPath}`);
+    // Generate the `EthleteSurfaceThemeNameRegistry` augmentation, so `etProvideSurface` (and
+    // anything else that accepts a `RegisteredSurfaceThemeName`) is checked/autocompleted
+    // against this app's actual surface theme names, instead of a plain `string`.
+    const typesDts = generateSurfaceThemeNameTypes(themes, schema);
+    tree.write(typesOutputPath, typesDts);
+    logger.log(`✅ Generated surface theme name types at: ${typesOutputPath}`);
+    const mainStylesFiles = findMainStylesFile(tree);
+    if (mainStylesFiles.length > 0) {
+        logger.log('\n📝 Found potential main styles files:');
+        mainStylesFiles.forEach((file) => logger.log(`   - ${file}`));
+        logger.log('\n⚠️  Please manually import the generated themes:');
+        logger.log(`   @import './${outputPath.replace('src/styles/', '')}';`);
+    }
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    logger.log('\n✅ Generation completed successfully!\n');
+}
+//#endregion
+//#region Parsing
+function extractSurfaceThemesFromContent(content, filePath) {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: {
+            target: 99,
+            module: 99,
+        },
+    });
+    const sourceFile = project.createSourceFile(filePath, content);
+    const themes = [];
+    const exportedDeclarations = sourceFile.getVariableDeclarations().filter((decl) => {
+        const statement = decl.getVariableStatement();
+        return statement?.isExported();
+    });
+    const themesArray = exportedDeclarations.find((decl) => {
+        const name = decl.getName();
+        return name === 'SURFACE_THEMES' || name === 'surfaceThemes';
+    });
+    if (!themesArray) {
+        throw new Error('Could not find SURFACE_THEMES or surfaceThemes export');
+    }
+    let initializer = themesArray.getInitializer();
+    if (!initializer) {
+        throw new Error('SURFACE_THEMES export has no initializer');
+    }
+    // Handle 'satisfies X'/'as const' wrappers, in either order: [array] satisfies Type[],
+    // [array] as const, or both combined.
+    while (initializer.isKind(SyntaxKind.SatisfiesExpression) || initializer.isKind(SyntaxKind.AsExpression)) {
+        initializer = initializer.getExpression();
+    }
+    if (!initializer.isKind(SyntaxKind.ArrayLiteralExpression)) {
+        throw new Error('SURFACE_THEMES export must be an array literal');
+    }
+    const elements = initializer.getElements();
+    for (const element of elements) {
+        let themeObj;
+        let name = '<inline>';
+        if (element.isKind(SyntaxKind.Identifier)) {
+            name = element.getText();
+            const themeDecl = exportedDeclarations.find((decl) => decl.getName() === name);
+            if (!themeDecl) {
+                logger.warn(`⚠️  Could not find declaration for surface theme: ${name}`);
+                continue;
+            }
+            themeObj = themeDecl.getInitializer();
+            if (!themeObj) {
+                logger.warn(`⚠️  Surface theme ${name} has no initializer`);
+                continue;
+            }
+        }
+        else {
+            themeObj = element;
+        }
+        while (themeObj.isKind(SyntaxKind.AsExpression) || themeObj.isKind(SyntaxKind.SatisfiesExpression)) {
+            themeObj = themeObj.getExpression();
+        }
+        if (!themeObj.isKind(SyntaxKind.ObjectLiteralExpression)) {
+            logger.warn(`⚠️  Surface theme ${name} is not an object literal`);
+            continue;
+        }
+        try {
+            const theme = parseSurfaceThemeObject(themeObj, sourceFile);
+            themes.push(theme);
+        }
+        catch (error) {
+            logger.warn(`⚠️  Failed to parse surface theme ${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (themes.length === 0) {
+        throw new Error('No valid surface themes found in SURFACE_THEMES array');
+    }
+    return themes;
+}
+const COLOR_PROPS = ['background', 'color', 'colorMuted', 'colorSubtle', 'border'];
+const isColorProp = (name) => COLOR_PROPS.some((p) => p === name);
+const INTERACTION_KEYS = ['default', 'hover', 'focus', 'active', 'disabled'];
+const isInteractionKey = (name) => INTERACTION_KEYS.some((key) => key === name);
+const SWATCH_KEYS = ['color', 'onColor', 'inkColor'];
+const isSwatchKey = (name) => SWATCH_KEYS.some((key) => key === name);
+const resolveObjectLiteral = (expression, sourceFile) => {
+    let resolved = expression;
+    while (resolved.isKind(SyntaxKind.AsExpression) || resolved.isKind(SyntaxKind.SatisfiesExpression)) {
+        resolved = resolved.getExpression();
+    }
+    if (resolved.isKind(SyntaxKind.Identifier)) {
+        const declaration = sourceFile
+            .getVariableDeclarations()
+            .find((candidate) => candidate.getName() === resolved.getText());
+        const initializer = declaration?.getInitializer();
+        return initializer ? resolveObjectLiteral(initializer, sourceFile) : null;
+    }
+    return resolved.isKind(SyntaxKind.ObjectLiteralExpression) ? resolved : null;
+};
+function parseInteractionColorMap(obj) {
+    const map = {};
+    for (const prop of obj.getProperties()) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const name = prop.getName();
+        const initializer = prop.getInitializer();
+        if (initializer?.isKind(SyntaxKind.StringLiteral) && isInteractionKey(name)) {
+            map[name] = initializer.getLiteralValue();
+        }
+    }
+    return map;
+}
+function parseInteractionColor(obj, themeName, sourceFile) {
+    const swatch = {};
+    for (const prop of obj.getProperties()) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const name = prop.getName();
+        const initializer = prop.getInitializer();
+        if (isInteractionKey(name)) {
+            throw new Error(`Surface theme "${themeName}" uses the old flat \`interactionColor\` shape. It now takes a swatch: ` +
+                `{ color: { default, hover, focus, active, disabled }, onColor?, inkColor? }. ` +
+                `Run \`nx g @ethlete/core:migrate-surface-interaction-swatch\` to convert your themes.`);
+        }
+        if (!initializer || !isSwatchKey(name))
+            continue;
+        const mapObject = resolveObjectLiteral(initializer, sourceFile);
+        if (!mapObject) {
+            throw new Error(`Surface theme "${themeName}" has an interactionColor.${name} value that cannot be resolved.`);
+        }
+        const map = parseInteractionColorMap(mapObject);
+        if (name === 'color') {
+            if (!map.default || !map.hover || !map.focus || !map.active || !map.disabled) {
+                throw new Error(`Surface theme "${themeName}" must define default, hover, focus, active and disabled interaction colors.`);
+            }
+            swatch.color = map;
+            continue;
+        }
+        if (map.default) {
+            swatch[name] = map;
+        }
+    }
+    if (!swatch.color) {
+        throw new Error(`Surface theme "${themeName}" interactionColor must define a color swatch.`);
+    }
+    return swatch;
+}
+function parseSurfaceThemeObject(obj, sourceFile) {
+    const properties = obj.getProperties();
+    const theme = {};
+    let interactionColorObj = null;
+    for (const prop of properties) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment)) {
+            continue;
+        }
+        const propName = prop.getName();
+        const initializer = prop.getInitializer();
+        if (!initializer) {
+            continue;
+        }
+        if (propName === 'isDefault') {
+            if (initializer.isKind(SyntaxKind.TrueKeyword)) {
+                theme.isDefault = true;
+            }
+            continue;
+        }
+        if (propName === 'interactionColor') {
+            interactionColorObj = resolveObjectLiteral(initializer, sourceFile);
+            if (!interactionColorObj) {
+                throw new Error('Surface theme interactionColor must be an inline or same-file object literal.');
+            }
+            continue;
+        }
+        if (propName === 'elevation') {
+            if (initializer.isKind(SyntaxKind.NumericLiteral)) {
+                theme.elevation = Number(initializer.getLiteralValue());
+            }
+            continue;
+        }
+        if (propName === 'type' && initializer.isKind(SyntaxKind.StringLiteral)) {
+            theme.type = initializer.getLiteralValue();
+            continue;
+        }
+        if (!initializer.isKind(SyntaxKind.StringLiteral)) {
+            continue;
+        }
+        if (propName === 'name') {
+            theme.name = initializer.getLiteralValue();
+        }
+        else if (isColorProp(propName)) {
+            theme[propName] = initializer.getLiteralValue();
+        }
+    }
+    if (!theme.name ||
+        !theme.type ||
+        theme.elevation === undefined ||
+        !theme.background ||
+        !theme.color ||
+        !theme.colorMuted ||
+        !theme.colorSubtle ||
+        !theme.border) {
+        throw new Error('SurfaceTheme must have name, type, elevation, background, color, colorMuted, colorSubtle, and border properties');
+    }
+    if (interactionColorObj) {
+        theme.interactionColor = parseInteractionColor(interactionColorObj, theme.name, sourceFile);
+    }
+    return theme;
+}
+// Makes the named theme the sole default of its surface type, overriding any isDefault
+// flags on themes of that type. Matches the theme's name or its CSS-safe form. Themes of
+// the other type keep their flags. Returns the resolved name.
+function applyDefaultSurfaceThemeOverride(themes, defaultTheme, type) {
+    const wanted = cssThemeName(defaultTheme);
+    const matches = themes.filter((t) => t.name === defaultTheme || cssThemeName(t.name) === wanted);
+    const target = matches.find((t) => t.type === type);
+    if (!target) {
+        const [firstMatch] = matches;
+        if (firstMatch) {
+            throw new Error(`Theme "${defaultTheme}" has type '${firstMatch.type}', but was passed as the default '${type}' theme`);
+        }
+        const available = themes.filter((t) => t.type === type).map((t) => t.name);
+        throw new Error(`No surface theme named "${defaultTheme}" found. Available '${type}' themes: ${available.join(', ')}`);
+    }
+    for (const theme of themes) {
+        if (theme.type === type) {
+            theme.isDefault = theme === target;
+        }
+    }
+    return target.name;
+}
+function validateSurfaceThemeConfiguration(themes) {
+    const defaultThemes = themes.filter((t) => t.isDefault);
+    if (defaultThemes.length === 0) {
+        throw new Error('No default surface theme found. Each type (light/dark) must have exactly one theme with isDefault: true');
+    }
+    const types = new Set(themes.map((t) => t.type));
+    for (const type of types) {
+        const defaultsForType = defaultThemes.filter((t) => t.type === type);
+        if (defaultsForType.length === 0) {
+            throw new Error(`No default surface theme found for type '${type}'. Add isDefault: true to one '${type}' theme`);
+        }
+        if (defaultsForType.length > 1) {
+            throw new Error(`Multiple default surface themes found for type '${type}': ${defaultsForType.map((t) => t.name).join(', ')}. Only one theme per type can have isDefault: true`);
+        }
+    }
+}
+//#endregion
+//#region CSS Generation
+function generateSurfaceThemeNameTypes(themes, schema) {
+    const themesPath = schema.themesPath || 'src/surface-themes.ts';
+    const outputPath = schema.outputPath || 'src/styles/generated-tailwind-surface-themes.css';
+    const typesOutputPath = schema.typesOutputPath || outputPath.replace(/\.css$/, '.d.ts');
+    const names = themes.map((theme) => `'${theme.name}'`).join(' | ');
+    return `/*
+ * Auto-generated by @ethlete/core:tailwind-4-surface-theme
+ * DO NOT EDIT THIS FILE MANUALLY
+ *
+ * Regenerate by running:
+ * nx g @ethlete/core:tailwind-4-surface-theme --themesPath=${themesPath}${schema.outputPath ? ` --outputPath=${outputPath}` : ''}${schema.typesOutputPath ? ` --typesOutputPath=${typesOutputPath}` : ''}${schema.prefix && schema.prefix !== 'et' ? ` --prefix=${schema.prefix}` : ''}${schema.defaultLightTheme ? ` --defaultLightTheme=${schema.defaultLightTheme}` : ''}${schema.defaultDarkTheme ? ` --defaultDarkTheme=${schema.defaultDarkTheme}` : ''}
+ */
+
+declare module '@ethlete/core' {
+  interface EthleteSurfaceThemeNameRegistry {
+    name: ${names};
+  }
+}
+
+export {};
+`;
+}
+function generateSurfaceThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
+    const themesPath = schema.themesPath || 'src/surface-themes.ts';
+    const outputPath = schema.outputPath || 'src/styles/generated-tailwind-surface-themes.css';
+    const header = `/*
+ * Auto-generated Tailwind 4 surface theme colors from @ethlete/core
+ * DO NOT EDIT THIS FILE MANUALLY
+ *
+ * Generated from your surface theme definitions
+ * This file can be regenerated by running:
+ * nx g @ethlete/core:tailwind-4-surface-theme --themesPath=${themesPath}${schema.outputPath ? ` --outputPath=${outputPath}` : ''}${schema.prefix && schema.prefix !== 'et' ? ` --prefix=${schema.prefix}` : ''}${schema.runtimePrefix && schema.runtimePrefix !== schema.prefix ? ` --runtimePrefix=${schema.runtimePrefix}` : ''}${schema.defaultLightTheme ? ` --defaultLightTheme=${schema.defaultLightTheme}` : ''}${schema.defaultDarkTheme ? ` --defaultDarkTheme=${schema.defaultDarkTheme}` : ''}
+ */
+
+`;
+    return `${header}${surfaceThemeCss(themes, { prefix: utilityPrefix, runtimePrefix })}`;
+}
+function findMainStylesFile(tree) {
+    const potentialFiles = [];
+    visitNotIgnoredFiles(tree, '', (path) => {
+        if (path.match(/styles\.(css|scss)$/) && !path.includes('node_modules') && !path.includes('dist')) {
+            potentialFiles.push(path);
+        }
+    });
+    return potentialFiles;
+}
+//#endregion

package/generators/tailwind-4-surface-theme/schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "tailwind-4-surface-theme",
+  "title": "Tailwind 4 Surface Theming Generator",
+  "description": "Generates Tailwind 4 compatible CSS from your Ethlete surface theme definitions",
+  "type": "object",
+  "properties": {
+    "themesPath": {
+      "type": "string",
+      "description": "Path to your surface themes file (relative to workspace root)",
+      "default": "src/surface-themes.ts",
+      "x-prompt": "Where is your surface themes file located?"
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Where to output the generated Tailwind surface themes CSS",
+      "default": "src/styles/generated-tailwind-surface-themes.css",
+      "x-prompt": "Where should the generated CSS be saved?"
+    },
+    "typesOutputPath": {
+      "type": "string",
+      "description": "Where to output the generated `EthleteSurfaceThemeNameRegistry` augmentation (a .d.ts that narrows `etProvideSurface` and other surface-theme-name APIs to your actual surface theme names). Defaults to `outputPath` with its extension swapped to `.d.ts`."
+    },
+    "prefix": {
+      "type": "string",
+      "description": "Prefix for Tailwind utility surface variable names (e.g., 'et' creates --color-et-surface-*, usable as bg-et-surface)",
+      "default": "et"
+    },
+    "runtimePrefix": {
+      "type": "string",
+      "description": "Prefix for the runtime theme-swap mechanism: the CSS custom properties (--<runtimePrefix>-surface-*) and selectors (.<runtimePrefix>-surface--<name>) that ProvideSurfaceDirective (etProvideSurface) toggles between. Defaults to the same value as 'prefix'. Set this separately when your Tailwind utility prefix needs to differ from your runtime theme-switching prefix."
+    },
+    "defaultLightTheme": {
+      "type": "string",
+      "description": "Name of the 'light' surface theme to use as the default, overriding any isDefault flags on light themes in the definitions. Use this when multiple apps share one surface theme definition set (e.g. in a monorepo) but each app needs a different default."
+    },
+    "defaultDarkTheme": {
+      "type": "string",
+      "description": "Name of the 'dark' surface theme to use as the default, overriding any isDefault flags on dark themes in the definitions. Use this when multiple apps share one surface theme definition set (e.g. in a monorepo) but each app needs a different default."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after generation",
+      "default": false
+    }
+  },
+  "required": []
+}

package/migrations/legacy-color-themes.md

@@ -0,0 +1,38 @@
+# Move the runtime color theming to Tailwind 4
+
+`provideColorThemes()` injects the color theme CSS at runtime and pairs with a Tailwind 3 config built from
+`createTailwindColorThemes()`. It is deprecated: `@ethlete/components` expects
+`provideColorThemesWithTailwind4()`, the CSS the Tailwind 4 generators emit, and a set of surface themes.
+
+The theme data carries over unchanged. A codemod does the mechanical part; the rest is setup that depends
+on the app.
+
+## What to change
+
+1. Run the codemod:
+
+   ```bash
+   nx g @ethlete/core:migrate-legacy-color-themes
+   ```
+
+   It rewrites every `provideColorThemes(X)` imported from `@ethlete/core` into
+   `provideColorThemesWithTailwind4(X)`, fixes the import, and writes
+   `legacy-color-themes-migration-tasks.md` at the workspace root. Pass `--projects` or `--include` to
+   migrate one app at a time.
+
+2. Work through `legacy-color-themes-migration-tasks.md`. It lists, per call site, the
+   `tailwind-4-color-theme` generator run that replaces the runtime styles, every Tailwind 3 helper left
+   in a config, and - when no app provides any yet - the surface themes to build.
+
+3. Move the Tailwind 3 config to Tailwind 4, run both generators, and import the generated `.css` in each
+   app's global stylesheet. Keep the prefix the Tailwind 3 config used, so the utility names stay.
+
+4. Derive the first surface themes from the app's existing page background, text, muted text and border
+   colors. Ask the user before inventing colors the app does not have.
+
+5. Search the app's own CSS for `--et-color-alt-`. Those variables are not emitted any more; move the
+   region into its own `etProvideColor` scope and read `--et-color-primary` there.
+
+6. Build the app and compare a page against the old one: the colors must match.
+
+The guide is at <https://ethlete-sdk-docs.web.app/core/theming#migrating-from-runtime-theming>.

package/migrations/seo-directive-removed.md

@@ -0,0 +1,81 @@
+# Replace `SeoDirective` with the `apply*Binding` functions
+
+`SeoDirective` and its `SeoConfig` types were removed in `@ethlete/core` v5. The directive wrote to
+`document` directly, so it never worked under server rendering, and it held one config object per
+component, so a child route could only override a parent by re-declaring the whole config.
+
+No codemod can do this rewrite: an Observable value becomes a signal, and one config key becomes one
+function call. Both are decisions about the call site.
+
+## What to change
+
+1. Find every component that injects `SeoDirective` or `SEO_DIRECTIVE_TOKEN`, or lists the directive in
+   `hostDirectives` or `imports`.
+2. Remove the directive from the component.
+3. Replace the `updateConfig({ … })` call with one `apply*Binding` call per key it set.
+4. Turn an Observable value into a signal: `toSignal()` at the edge of the component, or a
+   `computed()` over a signal that is already there.
+5. Import each `apply*Binding` function from `@ethlete/core`.
+
+## The replacement for each key
+
+| `SeoConfig` key              | Replacement                                                   |
+| ---------------------------- | ------------------------------------------------------------- |
+| `title`                      | `applyHeadTitleBinding`                                       |
+| `description`                | `applyDescriptionBinding`                                     |
+| `keywords`                   | `applyKeywordsBinding`                                        |
+| `robots`                     | `applyRobotsBinding` (takes a directive object, not a string) |
+| `icon`                       | `applyLinkBinding({ rel: 'icon', href })`                     |
+| `themeColor` / `colorScheme` | `applyMetaBinding({ name: 'theme-color' \| 'color-scheme' })` |
+| `canonical`                  | `applyCanonicalBinding`                                       |
+| `alternate`                  | `applyAlternateBinding` / `applyAlternateLanguagesBindings`   |
+| `og`                         | `applyOpenGraphBindings`                                      |
+| `twitter`                    | `applyTwitterCardBindings`                                    |
+| `facebook`                   | `applyOpenGraphBindings` (Facebook reads Open Graph)          |
+| any other key                | `applyMetaBinding({ name, content })`                         |
+
+## Example
+
+```ts
+// before
+@Component({ hostDirectives: [SeoDirective] })
+export class ArticleComponent {
+  private seo = inject(SeoDirective);
+
+  constructor() {
+    this.seo.updateConfig({
+      title: this.article$.pipe(map((a) => a.title)),
+      description: 'A brief description',
+      canonical: 'https://example.com/article',
+      og: { image: 'https://example.com/image.jpg' },
+    });
+  }
+}
+
+// after
+@Component({})
+export class ArticleComponent {
+  private article = toSignal(this.article$);
+
+  constructor() {
+    applyHeadTitleBinding(computed(() => this.article()?.title ?? ''));
+    applyDescriptionBinding('A brief description');
+    applyCanonicalBinding('https://example.com/article');
+    applyOpenGraphBindings({ images: ['https://example.com/image.jpg'] });
+  }
+}
+```
+
+## Two things to watch
+
+- A child component no longer re-declares its parent's config to override one key. Title parts
+  compose through the title store, and duplicate meta and link tags are deduplicated by selector.
+  Delete a re-declaration instead of porting it.
+- `robots` took a string and now takes a directive object, for example `{ index: true, follow: true }`.
+
+## When you are done
+
+Nothing may import `SeoDirective` or `SeoConfig` any more. Run the type check and the lint task of
+every project you changed.
+
+The full guide, with every binding and its options, is at <https://ethlete-sdk-docs.web.app/core/seo>.

package/migrations/surface-theme-regenerate.md

@@ -0,0 +1,20 @@
+# Regenerate the surface theme after the swatch change
+
+`SurfaceTheme['interactionColor']` is a swatch now: `{ color, onColor, inkColor }` instead of a single
+colour. `nx g @ethlete/core:migrate-surface-interaction-swatch` rewrites the theme definitions, but the
+generated stylesheet still holds the CSS variables of the old shape.
+
+Regenerate it with the same command that created it, in each app that has a surface theme:
+
+```bash
+nx g @ethlete/core:tailwind-4-surface-theme
+```
+
+The generator asks for the same answers as the first time. It overwrites the generated stylesheet, so
+check the diff: a hand-written override inside the generated file is lost.
+
+`onColor` and `inkColor` carry the two foreground colours an interaction surface needs. The codemod
+fills them from the old single colour, which keeps the rendering identical but is rarely the design
+intent. Read the swatch through with the designer once, then correct the values.
+
+The theming guide is at <https://ethlete-sdk-docs.web.app/core/theming>.

package/migrations.json

@@ -0,0 +1,59 @@
+{
+  "migrations": [
+    {
+      "name": "to-v5",
+      "version": "5.0.0-beta.11",
+      "kind": "auto",
+      "level": "required",
+      "description": "Rewrite the v4 core API into its v5 shape.",
+      "generator": "@ethlete/core:migrate-to-v5"
+    },
+    {
+      "name": "provider-shape",
+      "version": "5.0.0-next.37",
+      "kind": "auto",
+      "level": "required",
+      "description": "Rewrite destructured provider tuples into the tree-shakeable definition shape.",
+      "generator": "@ethlete/core:migrate-provider-shape",
+      "docs": "/core/providers"
+    },
+    {
+      "name": "seo-directive-removed",
+      "version": "5.0.0-next.41",
+      "kind": "assisted",
+      "level": "required",
+      "description": "SeoDirective and SeoConfig are gone. Every call site moves to the apply*Binding function for its key.",
+      "instructions": "./migrations/seo-directive-removed.md",
+      "docs": "/core/seo"
+    },
+    {
+      "name": "surface-interaction-swatch",
+      "version": "5.0.0-next.46",
+      "kind": "auto",
+      "level": "required",
+      "description": "Rewrite surface theme interactionColor maps into the { color, onColor, inkColor } swatch shape.",
+      "generator": "@ethlete/core:migrate-surface-interaction-swatch",
+      "requires": ["ts-morph"],
+      "docs": "/core/theming"
+    },
+    {
+      "name": "surface-theme-regenerate",
+      "version": "5.0.0-next.46",
+      "kind": "manual",
+      "level": "required",
+      "description": "Regenerate the surface theme stylesheet, so the new swatch reaches the CSS variables.",
+      "instructions": "./migrations/surface-theme-regenerate.md",
+      "docs": "/core/theming"
+    },
+    {
+      "name": "legacy-color-themes",
+      "version": "5.0.0-next.62",
+      "kind": "assisted",
+      "level": "recommended",
+      "description": "Move the runtime color theming to Tailwind 4: provideColorThemes becomes provideColorThemesWithTailwind4, and the generated CSS and surface themes replace the runtime styles.",
+      "scan": "@ethlete/core:migrate-legacy-color-themes",
+      "instructions": "./migrations/legacy-color-themes.md",
+      "docs": "/core/theming#migrating-from-runtime-theming"
+    }
+  ]
+}