@cmpose/core 0.4.0 → 0.5.0

package/README.md

@@ -2,4 +2,4 @@
 
 The cmpose generator library: it turns the pinned Compose Multiplatform template into a new project (validation, package and name rewrites, optional features and modules). See the README at the root of the cmpose repository for usage and development.
 
-It also generates Unity mobile games from the pinned game template: `game.validateGame`, `game.generateGame` and `game.describeGame`.
+It also generates Unity mobile games from the pinned game template: `game.validateGame`, `game.generateGame` and `game.describeGame` (`describeGame({ themes: await game.readThemes(templateDir) })` adds the template's theme families).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmpose/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "cmpose project generator core (Compose Multiplatform)",
   "license": "MIT",
   "repository": {

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 };

package/src/game/validate.js

@@ -2,6 +2,7 @@
 const PV = require('../ProjectValidator');
 const limits = require('../limits');
 const { GAME_SCHEMA: S } = require('./contract');
+const { checkThemeShape } = require('./themes');
 
 const CSHARP_KEYWORDS = ('abstract as base bool break byte case catch char checked class const continue decimal default delegate do double else enum event explicit extern false finally fixed float for foreach goto if implicit in int interface internal is lock long namespace new null object operator out override params private protected public readonly ref return sbyte sealed short sizeof stackalloc static string struct switch this throw true try typeof uint ulong unchecked unsafe ushort using virtual void volatile while').split(' ');
 const KOTLIN_KEYWORDS = PV.KOTLIN_HARD_KEYWORDS;
@@ -179,9 +180,17 @@ function validateGame(input) {
         ids = r.value;
     }
 
+    // The family and font pair are checked against the template's themes.json later (validateTheme)
+    let theme = null;
+    if (input.theme !== undefined) {
+        const r = checkThemeShape(input.theme);
+        if (r.error) return fail(r.error);
+        theme = r.value;
+    }
+
     return {
         ok: true,
-        value: { projectName, appName, packageName, companyName, templateType, render, flags, features, minSdk, iosVersion, ids }
+        value: { projectName, appName, packageName, companyName, templateType, render, flags, features, minSdk, iosVersion, ids, theme }
     };
 }
 

package/src/pins.js

@@ -3,7 +3,7 @@
 module.exports = Object.freeze({
     cmp: Object.freeze({ repo: 'whinstudio/cmpose-template', ref: 'template-2026.10.17' }),
     // The release step replaces the placeholder with the game template's tag
-    game: Object.freeze({ repo: 'whinstudio/cmpose-game-template', ref: 'game-template-2026.10.15.2' }),
+    game: Object.freeze({ repo: 'whinstudio/cmpose-game-template', ref: 'game-template-2026.10.17' }),
     // The release step replaces the placeholder with the backend template's tag
     backend: Object.freeze({ repo: 'whinstudio/cmpose-backend-template', ref: 'backend-template-2026.10.17' })
 });