@cmpose/core 0.3.0 → 0.5.0

package/src/backendOption.js

@@ -3,17 +3,11 @@ const fs = require('fs-extra');
 const path = require('path');
 const { removeSwiftPackage, parseObjects, isa } = require('./xcodePackages');
 const { PRIVACY_MANIFEST } = require('./privacyManifest');
+const { removeMarkedBlocks, applySwapMarkers } = require('./markerBlocks');
 
 // featuresConfig.backend: the template marks everything the backend adds (MAINTAINING.md → Backend markers).
 // Off strips it, on keeps it and drops only the markers. Runs on the template package, before the rename.
 
-const MARKERS = {
-    slash: { open: '// cmpose:backend', close: '// /cmpose:backend' },
-    hash: { open: '# cmpose:backend', close: '# /cmpose:backend' },
-    html: { open: '<!-- cmpose:backend -->', close: '<!-- /cmpose:backend -->' }
-};
-const SWAP = '// cmpose:backend-off: ';
-
 const KIND_BY_EXTENSION = {
     '.kt': 'slash', '.kts': 'slash', '.swift': 'slash', '.xcconfig': 'slash',
     '.toml': 'hash', '.gitignore': 'hash', '.properties': 'hash',
@@ -75,63 +69,6 @@ const BACKEND_PIN_IDENTITIES = new Set([
     'gtm-session-fetcher', 'gtmappauth', 'interop-ios-for-google-sdks', 'leveldb', 'nanopb', 'promises', 'swift-protobuf'
 ]);
 
-// Off: drops each marked block with its marker lines; on: drops only the marker lines. Either way a blank
-// line on both sides of a dropped run becomes one (blank runs elsewhere stay).
-function removeMarkedBlocks(content, kind, keep) {
-    const { open, close } = MARKERS[kind];
-    const out = [];
-    const joins = [];
-    let inside = false;
-    let dropped = false;
-    for (const line of content.split('\n')) {
-        const t = line.trim();
-        if (t === open) {
-            if (inside) throw new Error(`nested ${open}`);
-            inside = true;
-            dropped = true;
-            continue;
-        }
-        if (t === close) {
-            if (!inside) throw new Error(`stray ${close}`);
-            inside = false;
-            dropped = true;
-            continue;
-        }
-        if (inside && !keep) continue;
-        if (dropped) joins.push(out.length);
-        dropped = false;
-        out.push(line);
-    }
-    if (inside) throw new Error('unclosed cmpose:backend block');
-    if (dropped) joins.push(out.length);
-    return collapseBlankRuns(out, joins).join('\n');
-}
-
-// At each join (the index of the first line after a dropped run), blank lines that follow a blank line go
-function collapseBlankRuns(lines, joins) {
-    const drop = new Set();
-    for (const join of joins) {
-        if (join === 0 || lines[join - 1] !== '') continue;
-        for (let i = join; i < lines.length && lines[i] === ''; i++) drop.add(i);
-    }
-    return lines.filter((_, i) => !drop.has(i));
-}
-
-// Off: the line after a swap marker becomes the marker's text at that line's indentation; on: the marker goes
-function applySwapMarkers(content, keep) {
-    const lines = content.split('\n');
-    const out = [];
-    for (let i = 0; i < lines.length; i++) {
-        const t = lines[i].trim();
-        if (!t.startsWith(SWAP)) { out.push(lines[i]); continue; }
-        const next = lines[i + 1];
-        if (next === undefined) throw new Error('cmpose:backend-off marker on the last line');
-        if (keep) { out.push(next); } else { out.push(next.match(/^\s*/)[0] + t.slice(SWAP.length)); }
-        i++;
-    }
-    return out.join('\n');
-}
-
 // Off: the Firebase and GoogleSignIn packages, the build phase copying GoogleService-Info.plist, the
 // membership exceptions of the entitlements and GoogleService-Info.plist, and the entitlements and
 // Info.plist preprocessing (LOCAL_SERVER) build settings. Text edits only.

package/src/game/applyTheme.js

@@ -0,0 +1,129 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { setScalar, setList } = require('./unityYaml');
+const { readMetaGuid } = require('./guid');
+const { hexToRgb, derivePalette } = require('./themeColors');
+
+// cmpose game: writes a style family (themes.js) into the project as ThemeFamilies.Apply does in the editor: the light
+// palette, the dark one while the uiTheme flag's folder is there, and the style asset (fonts, shapes, motion, post,
+// world colours). Values are written the way Unity serializes them, so applying the template's own family changes nothing.
+const LIGHT_PATH = 'Assets/_Project/Core/Presentation/Resources/Theme/Light.asset';
+const DARK_PATH = 'Assets/_Project/Core/Theme/Resources/Theme/Dark.asset';
+const STYLE_PATH = 'Assets/_Project/Core/Presentation/Resources/Theme/Style.asset';
+const ASSET_DOC = { classId: 114, fileId: 11400000 };
+
+// ThemeStyle's enums (SurfaceStyle, MotionProfile, BackgroundStyle): Unity stores the index
+const ENUMS = {
+    surface: ['Flat', 'Soft', 'Raised'],
+    motion: ['Calm', 'Snappy', 'Bouncy'],
+    background: ['Solid', 'Gradient', 'Pattern']
+};
+
+// A float as Unity writes it: the shortest text that reads back as the same 32-bit float
+function unityFloat(x) {
+    const f = Math.fround(x);
+    for (let p = 1; p <= 9; p++) {
+        const s = f.toPrecision(p);
+        if (Math.fround(Number(s)) === f) return String(Number(s));
+    }
+    return String(f);
+}
+
+function unityColor(hex) {
+    const { r, g, b, a } = hexToRgb(hex);
+    return `{r: ${unityFloat(r / 255)}, g: ${unityFloat(g / 255)}, b: ${unityFloat(b / 255)}, a: ${unityFloat(a / 255)}}`;
+}
+
+// Palette's serialized field of a ThemeRole: Background → background, OnPrimary → onPrimary
+const fieldOf = (role) => role.charAt(0).toLowerCase() + role.slice(1);
+
+// themes.json names assets by project path; only paths inside Assets are followed
+function assetPath(projectDir, rel, what) {
+    if (typeof rel !== 'string' || !rel.startsWith('Assets/') || path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+        throw new Error(`theme: ${what} must be a path inside Assets`);
+    }
+    return path.join(projectDir, rel);
+}
+
+async function assetRef(projectDir, rel, what) {
+    const file = assetPath(projectDir, rel, what);
+    if (!(await fs.pathExists(file)) || !(await fs.pathExists(`${file}.meta`))) throw new Error(`theme: ${what} ${rel} is missing`);
+    return `{fileID: 11400000, guid: ${readMetaGuid(await fs.readFile(`${file}.meta`, 'utf8'))}, type: 2}`;
+}
+
+function enumIndex(name, value) {
+    const i = ENUMS[name].indexOf(value);
+    if (i < 0) throw new Error(`theme: style.${name} must be one of ${ENUMS[name].join(', ')}`);
+    return i;
+}
+
+function writePalette(text, roles) {
+    let out = text;
+    for (const [role, hex] of Object.entries(roles)) out = setScalar(out, fieldOf(role), unityColor(hex), { doc: ASSET_DOC });
+    return out;
+}
+
+async function readAsset(projectDir, rel) {
+    const file = path.join(projectDir, rel);
+    if (!(await fs.pathExists(file))) throw new Error(`theme: ${rel} is missing`);
+    return fs.readFile(file, 'utf8');
+}
+
+/** Writes themeValue (validateTheme().value: family, fontPair, primary?, accent?) of themes (readThemes) into
+ * projectDir. uiTheme: whether the flag is on (its Dark.asset is written, never created). Every asset is read and every
+ * reference resolved before anything is written. Returns the warnings of colours that fell back and the theme as
+ * applied (primary/accent only where they were kept). */
+async function applyTheme(projectDir, themeValue, themes, { uiTheme = false } = {}) {
+    const family = themes.families.find((f) => f.id === themeValue.family);
+    if (!family) throw new Error('theme: unknown family');
+    const pair = family.fontPairs.find((p) => p.id === themeValue.fontPair);
+    if (!pair) throw new Error('theme: unknown font pair');
+    const style = family.style;
+
+    const requested = { primary: themeValue.primary, accent: themeValue.accent };
+    const light = derivePalette(family, requested, 'light');
+    const dark = uiTheme ? derivePalette(family, requested, 'dark') : null;
+
+    const display = await assetRef(projectDir, pair.display, 'display font');
+    const body = await assetRef(projectDir, pair.body, 'body font');
+    const post = await assetRef(projectDir, style.post, 'post profile');
+    const worldColors = Array.isArray(style.worldColors) ? style.worldColors : [];
+    if (worldColors.length < 3 || worldColors.length > 4) throw new Error('theme: style.worldColors needs 3 or 4 colours');
+    const numbers = {};
+    for (const [key, min, max] of [['cornerRadius', 0, 48], ['shadowStrength', 0, 1]]) {
+        const v = style[key];
+        if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max) throw new Error(`theme: style.${key} must be from ${min} to ${max}`);
+        numbers[key] = unityFloat(v);
+    }
+    const enums = Object.fromEntries(Object.keys(ENUMS).map((k) => [k, enumIndex(k, style[k])]));
+
+    const lightText = writePalette(await readAsset(projectDir, LIGHT_PATH), light.roles);
+    const darkText = dark ? writePalette(await readAsset(projectDir, DARK_PATH), dark.roles) : null;
+    let styleText = await readAsset(projectDir, STYLE_PATH);
+    const scalars = [
+        ['familyId', family.id], ['displayFont', display], ['bodyFont', body],
+        ['cornerRadius', numbers.cornerRadius], ['surface', enums.surface], ['shadowStrength', numbers.shadowStrength],
+        ['motion', enums.motion], ['post', post], ['background', enums.background]
+    ];
+    for (const [key, v] of scalars) styleText = setScalar(styleText, key, v, { doc: ASSET_DOC });
+    styleText = setList(styleText, 'worldColors', worldColors.map(unityColor), { doc: ASSET_DOC });
+
+    await fs.writeFile(path.join(projectDir, LIGHT_PATH), lightText);
+    if (darkText !== null) await fs.writeFile(path.join(projectDir, DARK_PATH), darkText);
+    await fs.writeFile(path.join(projectDir, STYLE_PATH), styleText);
+
+    const warnings = [...light.warnings, ...(dark ? dark.warnings : [])];
+    const fellBack = (role) => warnings.some((w) => w.startsWith(`theme: ${role} `));
+    return {
+        warnings,
+        theme: {
+            family: family.id,
+            ...(themeValue.primary && !fellBack('Primary') ? { primary: themeValue.primary } : {}),
+            ...(themeValue.accent && !fellBack('Accent') ? { accent: themeValue.accent } : {}),
+            fontPair: pair.id
+        }
+    };
+}
+
+module.exports = { LIGHT_PATH, DARK_PATH, STYLE_PATH, unityFloat, unityColor, applyTheme };

package/src/game/contract.js

@@ -1,6 +1,7 @@
 'use strict';
 const { hashContract } = require('../contract');
 const limits = require('../limits');
+const { THEME_FIELDS } = require('./themes');
 
 // The Unity game generator's contract: what the game_* tools accept. Published facts feed contractVersion.
 const GAME_SCHEMA = Object.freeze({
@@ -26,7 +27,9 @@ const GAME_SCHEMA = Object.freeze({
         'button', 'lifetime', 'object', 'preserve', 'resources', 'serializable', 'transform',
         'about', 'ads', 'boot', 'common', 'guide', 'inspector', 'leaderboards', 'menu', 'network', 'pause',
         'purchases', 'runner2d', 'settings', 'theme', 'track3d', 'update'],
-    reservedPackagePrefix: 'com.kturker'
+    reservedPackagePrefix: 'com.kturker',
+    // The theme request's fields; the families themselves come from the template (game_describe themes)
+    theme: { fields: THEME_FIELDS.slice(), colorFormat: '#RRGGBB' }
 });
 
 function gameContractFacts() {

package/src/game/describe.js

@@ -2,8 +2,18 @@
 const pins = require('../pins');
 const { GAME_SCHEMA, gameContractFacts, gameContractVersion } = require('./contract');
 
-/** What the Unity game generator offers: engine, pinned template, defaults and the contract facts */
-function describeGame() {
+// What a planner needs to pick a family: palettes, style and font paths stay in the template
+function summarizeThemes(themes) {
+    const families = themes && Array.isArray(themes.families) ? themes.families : [];
+    return {
+        default: families.length ? themes.default : null,
+        families: families.map((f) => ({ id: f.id, title: f.title, suits: f.suits, fontPairs: f.fontPairs.map((p) => p.id) }))
+    };
+}
+
+/** What the Unity game generator offers: engine, pinned template, defaults, the template's theme families
+ * (readThemes of the pinned template; none when not given) and the contract facts */
+function describeGame({ themes = null } = {}) {
     return {
         engine: GAME_SCHEMA.engine,
         unityVersion: GAME_SCHEMA.unityVersion,
@@ -17,8 +27,10 @@ function describeGame() {
             minSdk: GAME_SCHEMA.limits.minSdkMin,
             iosVersion: GAME_SCHEMA.limits.iosVersionMin
         },
+        // Outside `contract`: the families belong to the template, contractVersion hashes the contract only
+        themes: summarizeThemes(themes),
         contract: gameContractFacts()
     };
 }
 
-module.exports = { describeGame };
+module.exports = { describeGame, summarizeThemes };

package/src/game/generate.js

@@ -12,6 +12,8 @@ const { writeGameIds } = require('./ids');
 const { applyGameReadme } = require('./readme');
 const { buildGameRecord, writeGameRecord } = require('./record');
 const { verifyGameProject } = require('./verifier');
+const { readThemes, validateTheme } = require('./themes');
+const { applyTheme } = require('./applyTheme');
 
 // The template cache's own records and Unity's local state never reach the project; nor does the template's
 // LICENSE (the generated project is the user's, to license as they choose), nor an older template's GameCI
@@ -42,6 +44,11 @@ async function generateGame(value, { projectDir, template = null, coreVersion, g
         commit: await readMarker(COMMIT_FILE_NAME)
     };
 
+    // The family and font pair are checked against the template's themes.json before anything changes
+    const themes = await readThemes(projectDir);
+    const theme = validateTheme(value.theme, themes);
+    if (!theme.ok) throw new Error(theme.error);
+
     // 1. leftovers
     for (const leftover of LEFTOVERS) await fs.remove(path.join(projectDir, leftover));
     log.info('✅ Cleanup completed');
@@ -63,13 +70,20 @@ async function generateGame(value, { projectDir, template = null, coreVersion, g
     await applyGameReadme(projectDir, value);
     log.info(`✅ Renamed to ${value.companyName}.${value.projectName} (${value.packageName})`);
 
-    // 7. a broken project is never returned
+    // 7. the style family (the template's default when none was asked; nothing for a template without families)
+    let applied = { warnings: [], theme: null };
+    if (theme.value) {
+        applied = await applyTheme(projectDir, theme.value, themes, { uiTheme: value.flags.includes('uiTheme') });
+        log.info(`✅ Applied theme ${applied.theme.family} (${applied.theme.fontPair})`);
+    }
+
+    // 8. a broken project is never returned
     const problems = await verifyGameProject(projectDir);
     if (problems.length) throw new Error('generated project failed verification:\n- ' + problems.join('\n- '));
 
-    // 8. the template's package guid allowlist goes; the record stays
+    // 9. the template's package guid allowlist goes; the record stays
     await fs.remove(path.join(projectDir, PACKAGE_GUIDS));
-    const record = buildGameRecord({ template: source, coreVersion, generatorVersion, value, now });
+    const record = buildGameRecord({ template: source, coreVersion, generatorVersion, value, theme: applied.theme, now });
     await writeGameRecord(projectDir, record);
 
     return {
@@ -78,7 +92,8 @@ async function generateGame(value, { projectDir, template = null, coreVersion, g
         flags: value.flags.slice(),
         features: value.features.slice(),
         ids: record.ids,
-        warnings: gameWarnings(value)
+        theme: applied.theme,
+        warnings: [...applied.warnings, ...gameWarnings(value)]
     };
 }
 

package/src/game/index.js

@@ -9,6 +9,9 @@ const { writeGameIds } = require('./ids');
 const { applyGameReadme } = require('./readme');
 const { buildGameRecord, writeGameRecord } = require('./record');
 const { verifyGameProject } = require('./verifier');
+const { readThemes, validateTheme, ThemesFileError } = require('./themes');
+const { applyTheme } = require('./applyTheme');
+const { derivePalette } = require('./themeColors');
 
 module.exports = {
     validateGame,
@@ -24,6 +27,11 @@ module.exports = {
     buildGameRecord,
     writeGameRecord,
     verifyGameProject,
+    readThemes,
+    ThemesFileError,
+    validateTheme,
+    applyTheme,
+    derivePalette,
     flags: require('./flags'),
     guid: require('./guid'),
     guidIntegrity: require('./guidIntegrity'),

package/src/game/record.js

@@ -20,8 +20,9 @@ function idStatuses(flags, ids) {
 const strings = (list) => (Array.isArray(list) ? list.filter((x) => typeof x === 'string') : []);
 
 /** The .cmpose/generation.json content of a generated Unity game (no personal data, no ID values);
- * generatorVersion names the caller (e.g. mcp@0.2.0), null when not given */
-function buildGameRecord({ template, coreVersion, generatorVersion = null, value, now = new Date() }) {
+ * generatorVersion names the caller (e.g. mcp@0.2.0), null when not given; theme the style family as applied
+ * (applyTheme), null for a template without families */
+function buildGameRecord({ template, coreVersion, generatorVersion = null, value, theme = null, now = new Date() }) {
     const flags = strings(value.flags);
     return {
         generator: '@cmpose/core',
@@ -36,6 +37,7 @@ function buildGameRecord({ template, coreVersion, generatorVersion = null, value
         minSdk: value.minSdk,
         iosVersion: value.iosVersion,
         ids: idStatuses(flags, value.ids),
+        theme: theme ? { ...theme } : null,
         template: { repo: template.repo, ref: template.ref, commit: template.commit },
         generatedAt: now.toISOString()
     };

package/src/game/themeColors.js

@@ -0,0 +1,173 @@
+'use strict';
+
+// cmpose game: a family's palette with the requested Primary/Accent. The colours keep the requested hue and saturation;
+// only the lightness moves, until every contrast floor the template's own tests ask for holds (ThemeFamilyTests'
+// AssertReads, Contrast.AssertBoxes and AssertAccentAndStatus). A colour that cannot reach them stays the family's.
+
+// Contrast floors of Contrast (Assets/_Project/Tests/EditMode/ThemeTests.cs)
+const BODY_TEXT = 4.5;
+const NON_TEXT = 3;
+const SMALL_TEXT = 3;
+const BOX_ON_PANEL = 1.25;
+const SELECTED_ON_ROW = 1.1;
+// The floors that differ by palette: Primary text on the rows, Control on Surface
+const MODE_FLOORS = {
+    light: { accentOnRow: 3, controlOnSurface: 1.4 },
+    dark: { accentOnRow: 2.3, controlOnSurface: 3 }
+};
+// A requested hue stays visible: never shifted to black or white
+const MIN_LIGHTNESS = 0.1;
+const MAX_LIGHTNESS = 0.9;
+const STEP = 0.01;
+
+function hexToRgb(hex) {
+    const m = /^#([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})?$/.exec(hex);
+    if (!m) throw new Error(`'${hex}' is not a #RRGGBB colour`);
+    return { r: parseInt(m[1], 16), g: parseInt(m[2], 16), b: parseInt(m[3], 16), a: m[4] === undefined ? 255 : parseInt(m[4], 16) };
+}
+
+const byte = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0').toUpperCase();
+const rgbToHex = ({ r, g, b }) => `#${byte(r)}${byte(g)}${byte(b)}`;
+
+// WCAG 2 relative luminance, as Contrast.Luminance computes it
+function luminance(hex) {
+    const { r, g, b } = hexToRgb(hex);
+    const channel = (c) => {
+        const v = c / 255;
+        return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+function contrast(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+function hexToHsl(hex) {
+    const { r, g, b } = hexToRgb(hex);
+    const [R, G, B] = [r / 255, g / 255, b / 255];
+    const max = Math.max(R, G, B);
+    const min = Math.min(R, G, B);
+    const l = (max + min) / 2;
+    if (max === min) return { h: 0, s: 0, l };
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    if (max === R) h = (G - B) / d + (G < B ? 6 : 0);
+    else if (max === G) h = (B - R) / d + 2;
+    else h = (R - G) / d + 4;
+    return { h: h / 6, s, l };
+}
+
+function hslToHex({ h, s, l }) {
+    if (s === 0) return rgbToHex({ r: l * 255, g: l * 255, b: l * 255 });
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const hue = (t) => {
+        if (t < 0) t += 1;
+        if (t > 1) t -= 1;
+        if (t < 1 / 6) return p + (q - p) * 6 * t;
+        if (t < 1 / 2) return q;
+        if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    };
+    return rgbToHex({ r: hue(h + 1 / 3) * 255, g: hue(h) * 255, b: hue(h - 1 / 3) * 255 });
+}
+
+// Every floor a palette must meet: [a, b, floor] contrast pairs, then the colours that must differ
+function contrastPairs(mode) {
+    const { accentOnRow, controlOnSurface } = MODE_FLOORS[mode];
+    return [
+        ['Text', 'Background', BODY_TEXT],
+        ['Text', 'Surface', BODY_TEXT],
+        ['TextMuted', 'Surface', BODY_TEXT],
+        ['OnPrimary', 'Primary', BODY_TEXT],
+        ['OnAccent', 'Accent', BODY_TEXT],
+        ['Danger', 'Surface', NON_TEXT],
+        ['Success', 'Surface', NON_TEXT],
+        ['Primary', 'Surface', NON_TEXT],
+        ['Primary', 'Control', NON_TEXT],
+        ['Control', 'Surface', controlOnSurface],
+        ['Track', 'Surface', BOX_ON_PANEL],
+        ['SurfaceVariant', 'Surface', BOX_ON_PANEL],
+        ['SurfaceVariant', 'Background', BOX_ON_PANEL],
+        ['SurfaceVariant', 'Track', SELECTED_ON_ROW],
+        ['TextMuted', 'Track', SMALL_TEXT],
+        ['TextMuted', 'SurfaceVariant', SMALL_TEXT],
+        ['Primary', 'Track', accentOnRow],
+        ['Primary', 'SurfaceVariant', accentOnRow],
+        ['Primary', 'Track', NON_TEXT]
+    ];
+}
+const DISTINCT = [['Accent', 'Primary'], ['Success', 'Danger']];
+
+const sameColour = (a, b) => a.toUpperCase() === b.toUpperCase();
+
+/** The floors roles (role → #RRGGBB) misses in mode ('light' | 'dark'), as 'A on B' / 'A is B'; only the pairs
+ * that involve one of `only` when given */
+function paletteProblems(roles, mode, only = null) {
+    if (!MODE_FLOORS[mode]) throw new Error(`unknown palette mode '${mode}'`);
+    const concerns = (a, b) => !only || only.includes(a) || only.includes(b);
+    const problems = [];
+    for (const [a, b, floor] of contrastPairs(mode)) {
+        if (concerns(a, b) && contrast(roles[a], roles[b]) < floor) problems.push(`${a} on ${b}`);
+    }
+    for (const [a, b] of DISTINCT) if (concerns(a, b) && sameColour(roles[a], roles[b])) problems.push(`${a} is ${b}`);
+    return problems;
+}
+
+// Lightness values from the requested one outwards, inside the visible range
+function lightnessSteps(from) {
+    const start = Math.min(MAX_LIGHTNESS, Math.max(MIN_LIGHTNESS, from));
+    const steps = [start];
+    for (let d = STEP; d <= 1; d += STEP) {
+        if (start - d >= MIN_LIGHTNESS - 1e-9) steps.push(start - d);
+        if (start + d <= MAX_LIGHTNESS + 1e-9) steps.push(start + d);
+    }
+    return steps;
+}
+
+const unique = (list) => list.filter((c, i) => list.findIndex((x) => sameColour(x, c)) === i);
+
+// The requested colour itself when it passes, else its hue at the nearest lightness that does; the text on it is the
+// family's On colour, its Text or its Surface (whichever reads); Control moves only when nothing else works
+function shiftRole(roles, mode, role, requested) {
+    const on = `On${role}`;
+    const changes = role === 'Primary' ? [role, on, 'Control'] : [role, on];
+    const ons = unique([roles[on], roles.Text, roles.Surface]);
+    const hsl = hexToHsl(requested);
+    const candidates = unique([requested.toUpperCase(), ...lightnessSteps(hsl.l).map((l) => hslToHex({ ...hsl, l }))]);
+    const controls = [roles.Control];
+    if (role === 'Primary') {
+        const c = hexToHsl(roles.Control);
+        controls.push(...unique(lightnessSteps(c.l).map((l) => hslToHex({ ...c, l }))).filter((x) => !sameColour(x, roles.Control)));
+    }
+    for (const control of controls) {
+        for (const colour of candidates) {
+            for (const text of ons) {
+                const next = { ...roles, [role]: colour, [on]: text, ...(role === 'Primary' ? { Control: control } : {}) };
+                if (!paletteProblems(next, mode, changes).length) return next;
+            }
+        }
+    }
+    return null;
+}
+
+/** family's palette for mode ('light' | 'dark') with the requested primary/accent (#RRGGBB) shifted to pass every
+ * contrast floor. roles: role → #RRGGBB(AA); warnings: one line per colour that fell back to the family's */
+function derivePalette(family, { primary, accent } = {}, mode = 'light') {
+    if (!family || !family[mode]) throw new Error(`family has no ${mode} palette`);
+    let roles = { ...family[mode] };
+    const warnings = [];
+    for (const [role, requested] of [['Primary', primary], ['Accent', accent]]) {
+        if (!requested) continue;
+        const next = shiftRole(roles, mode, role, requested);
+        if (next) roles = next;
+        else warnings.push(`theme: ${role} fell back to the family default in the ${mode} palette`);
+    }
+    return { roles, warnings };
+}
+
+module.exports = { MODE_FLOORS, hexToRgb, rgbToHex, luminance, contrast, hexToHsl, hslToHex, paletteProblems, derivePalette };

package/src/game/themes.js

@@ -0,0 +1,112 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+
+// The template owns its style families (palettes, style, font pairs); older pins have no such file
+const THEMES_PATH = path.join('.cmpose', 'themes.json');
+const THEME_FIELDS = ['family', 'primary', 'accent', 'fontPair'];
+const HEX_RE = /^#[0-9A-Fa-f]{6}$/;
+// Palette entries: #RRGGBB or #RRGGBBAA (Scrim carries alpha)
+const PALETTE_HEX_RE = /^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/;
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isText = (v) => typeof v === 'string' && v.length > 0;
+
+// A template's themes.json that is there but cannot be used
+class ThemesFileError extends Error { }
+
+function broken(why) {
+    return new ThemesFileError(`${THEMES_PATH.split(path.sep).join('/')} is not valid: ${why}`);
+}
+
+function checkPalette(id, name, palette) {
+    if (!isObject(palette)) throw broken(`family "${id}" has no ${name} palette`);
+    for (const [key, value] of Object.entries(palette)) {
+        if (typeof value !== 'string' || !PALETTE_HEX_RE.test(value)) throw broken(`family "${id}" ${name}.${key} is not a #RRGGBB colour`);
+    }
+}
+
+function checkFamily(f) {
+    if (!isObject(f) || !isText(f.id)) throw broken('a family has no id');
+    checkPalette(f.id, 'light', f.light);
+    checkPalette(f.id, 'dark', f.dark);
+    if (!isObject(f.style)) throw broken(`family "${f.id}" has no style`);
+    if (!Array.isArray(f.fontPairs) || !f.fontPairs.length) throw broken(`family "${f.id}" has no font pairs`);
+    for (const p of f.fontPairs) {
+        if (!isObject(p) || !isText(p.id) || !isText(p.display) || !isText(p.body)) throw broken(`family "${f.id}" has a font pair without id, display or body`);
+    }
+    return {
+        id: f.id, title: f.title, suits: f.suits,
+        light: { ...f.light }, dark: { ...f.dark }, style: { ...f.style },
+        fontPairs: f.fontPairs.map((p) => ({ id: p.id, display: p.display, body: p.body }))
+    };
+}
+
+/** The template's style families from .cmpose/themes.json; no families when the file is missing.
+ * A file that is there but broken throws: the generator must not guess a theme. */
+async function readThemes(templateDir) {
+    const file = path.join(templateDir, THEMES_PATH);
+    if (!(await fs.pathExists(file))) return { version: null, default: null, families: [] };
+    let data;
+    try {
+        data = JSON.parse(await fs.readFile(file, 'utf8'));
+    } catch {
+        throw broken('not JSON');
+    }
+    if (!isObject(data) || !Array.isArray(data.families)) throw broken('no families list');
+    const families = data.families.map(checkFamily);
+    const ids = families.map((f) => f.id);
+    if (new Set(ids).size !== ids.length) throw broken('duplicate family ids');
+    if (!ids.includes(data.default)) throw broken(`default "${data.default}" is not a family`);
+    return { version: data.version, default: data.default, families };
+}
+
+/** theme's shape alone (validateGame has no template): an object of known string fields, colours as #RRGGBB.
+ * value keeps the given fields, colours uppercased. */
+function checkThemeShape(theme) {
+    if (!isObject(theme)) return { error: 'theme must be an object' };
+    const extra = Object.keys(theme).filter((k) => !THEME_FIELDS.includes(k));
+    if (extra.length) return { error: `theme has unknown fields: ${extra.join(', ')} (known: ${THEME_FIELDS.join(', ')})` };
+    const value = {};
+    for (const k of THEME_FIELDS) {
+        if (!Object.hasOwn(theme, k)) continue;
+        const v = theme[k];
+        if (typeof v !== 'string') return { error: `theme.${k} must be a string` };
+        if ((k === 'primary' || k === 'accent') && !HEX_RE.test(v)) return { error: `theme.${k} must look like #RRGGBB` };
+        value[k] = k === 'primary' || k === 'accent' ? v.toUpperCase() : v;
+    }
+    return { value };
+}
+
+// Errors list the valid ids but never echo the request's value back
+/** A theme request against the template's families (readThemes). value: { family, primary?, accent?, fontPair },
+ * the default family and each family's first font pair filling gaps; null when the template has no families and
+ * none was asked for. */
+function validateTheme(theme, themes) {
+    const families = themes && Array.isArray(themes.families) ? themes.families : [];
+    const asked = theme !== undefined && theme !== null;
+    if (!families.length) {
+        return asked ? { ok: false, error: 'theme cannot be used: this template has no theme families' } : { ok: true, value: null };
+    }
+    const shape = asked ? checkThemeShape(theme) : { value: {} };
+    if (shape.error) return { ok: false, error: shape.error };
+    const t = shape.value;
+    const ids = families.map((f) => f.id);
+    const familyId = t.family === undefined ? themes.default : t.family;
+    const family = families.find((f) => f.id === familyId);
+    if (!family) return { ok: false, error: `theme.family must be one of this template's families: ${ids.join(', ')}` };
+    const pairs = family.fontPairs.map((p) => p.id);
+    const fontPair = t.fontPair === undefined ? pairs[0] : t.fontPair;
+    if (!pairs.includes(fontPair)) return { ok: false, error: `theme.fontPair must be one of ${family.id}'s font pairs: ${pairs.join(', ')}` };
+    return {
+        ok: true,
+        value: {
+            family: family.id,
+            ...(t.primary ? { primary: t.primary } : {}),
+            ...(t.accent ? { accent: t.accent } : {}),
+            fontPair
+        }
+    };
+}
+
+module.exports = { THEMES_PATH, THEME_FIELDS, ThemesFileError, readThemes, validateTheme, checkThemeShape };