@bitmagic/cli 0.1.83-dev.1 → 0.1.83-dev.3

package/dist/{theme/theme-validate.js → vendor/hud-theme/validate-strict.js}

@@ -1,77 +1,37 @@
 /**
  * The strict write-time HUD theme validator.
  *
- * STRICTER than the engine's load-time validator on purpose, and that asymmetry
- * is the design: at WRITE time a bad per-element leaf is an error the agent can
- * fix in the same turn, while at LOAD time the engine must keep rendering
- * already-published themes, so it warns and drops the leaf instead. Everything
- * this validator accepts, the engine accepts; the reverse is not required.
+ * STRICTER than the engine's load-time validator (`validateAndResolveTheme`) on
+ * purpose, and that asymmetry is the design: at WRITE time a bad per-element leaf
+ * is an error the agent can fix in the same turn, while at LOAD time the engine
+ * must keep rendering already-published themes, so it warns and drops the leaf
+ * instead. Everything this validator accepts, the engine accepts; the reverse is
+ * not required. This package's tests hold that rule over a fixture corpus.
  *
- * This replaced `lightValidateTheme`, which skipped glow keys, every numeric
- * range, the whole `elements` block, decoration slot suitability and decoration
- * size/position/repeat — six ways a theme could pass the write tool and then
- * silently render as the DEFAULT look at engine load, which reads as "theming
- * is broken" rather than "the value was wrong". Parity with the engine is
- * enforced by scripts/check-hud-catalog.ts, which runs both validators over a
- * fixture corpus under tsx and compares verdicts.
- *
- * Validation rules mirror game/src/engine/hud/validateTheme.ts; vocabulary
- * comes from the drift-checked catalog next door.
+ * Both modes read the same vocabulary and ranges from the engine's ThemeTokens.ts
+ * and the same catalogues (fonts, decorations), and share the engine's
+ * `suggestClosest`, so they cannot disagree about what a key, a range or a
+ * "Closest match" is — only about how loudly to fail.
  */
-import { HUD_DECORATIONS, HUD_DECORATION_SLOTS, HUD_ELEMENT_CLASSES, HUD_FONTS, HUD_GLOW_KEYS, HUD_ICON_KEYS, } from './hud-theme-catalog.js';
-const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
-// Mirrors the engine's TILE_SIZE: "<n>px|% <n>px|%", decimals allowed.
-const TILE_SIZE = /^\d{1,4}(?:\.\d{1,2})?(?:px|%) \d{1,4}(?:\.\d{1,2})?(?:px|%)$/;
-const POSITION_VALUES = [
-    'top', 'top-right', 'right', 'bottom-right', 'bottom', 'bottom-left', 'left', 'top-left', 'center',
-];
-const REPEAT_VALUES = ['no-repeat', 'repeat', 'repeat-x', 'repeat-y'];
-const BORDER_REPEAT_VALUES = ['stretch', 'repeat', 'round', 'space'];
-const COLOR_KEYS = [
-    'primary', 'danger', 'warning', 'success', 'background', 'surface', 'text', 'textMuted', 'outline',
-];
-const REQUIRED_COLOR_KEYS = ['primary', 'danger', 'background', 'surface', 'text'];
-// Levenshtein, matching the engine: suggest only when the distance is small
-// relative to the input. A wild guess gets the full candidate list from the
-// error message, never false confidence in one arbitrary name.
-function editDistance(a, b) {
-    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-    for (let i = 1; i <= a.length; i++) {
-        const cur = [i];
-        for (let j = 1; j <= b.length; j++) {
-            const deletion = (prev[j] ?? 0) + 1;
-            const insertion = (cur[j - 1] ?? 0) + 1;
-            const substitution = (prev[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
-            cur[j] = Math.min(deletion, insertion, substitution);
-        }
-        prev = cur;
-    }
-    return prev[b.length] ?? 0;
-}
-export function suggestClosest(value, candidates) {
-    const v = value.toLowerCase();
-    let best;
-    let bestScore = Infinity;
-    for (const c of candidates) {
-        const score = editDistance(v, c.toLowerCase());
-        if (score < bestScore) {
-            bestScore = score;
-            best = c;
-        }
-    }
-    const maxDistance = Math.max(2, Math.ceil(v.length / 3));
-    return bestScore <= maxDistance ? best : undefined;
-}
+import { BACKGROUND_POSITIONS, BACKGROUND_REPEATS, BACKGROUND_SIZE_KEYWORDS, BACKGROUND_TILE_SIZE, BORDER_IMAGE_REPEATS, DECORATION_SLOT_KINDS, FONT_BODY_WEIGHTS, FONT_HEADING_WEIGHTS, GLOW_KEYS, HUD_ELEMENT_CLASSES, IMAGE_RENDERINGS, LABEL_CASES, MAX_INLINE_SVG_LENGTH, REQUIRED_THEME_COLOR_KEYS, THEME_COLOR_KEYS, THEME_ICON_KEYS, THEME_NUMBER_RANGES, isHexColor, } from './engine/hud/ThemeTokens.js';
+import { HUD_FONTS } from './engine/hud/fonts.js';
+import { HUD_DECORATIONS } from './engine/hud/decorations.js';
+import { suggestClosest } from './engine/hud/validateTheme.js';
+export { suggestClosest };
 function isObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
-function checkNumber(ctx, path, value, min, max) {
+function includes(list, value) {
+    return list.includes(value);
+}
+function checkNumber(ctx, path, value, token) {
+    const [min, max] = THEME_NUMBER_RANGES[token];
     if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
         ctx.errors.push({ path, message: `${JSON.stringify(value)} is not a number in [${min}, ${max}]` });
     }
 }
 function checkHexAt(ctx, path, value) {
-    if (typeof value !== 'string' || !HEX_COLOR.test(value)) {
+    if (!isHexColor(value)) {
         ctx.errors.push({
             path,
             message: `${JSON.stringify(value)} is not a 6-digit hex color`,
@@ -89,6 +49,14 @@ function checkKeyed(ctx, path, value, allowed) {
         ...(close ? { suggestion: `Closest match: "${close}"` } : {}),
     });
 }
+function unknownKey(ctx, path, message, value, known) {
+    const close = suggestClosest(value, known);
+    ctx.errors.push({
+        path,
+        message,
+        suggestion: close ? `Closest match: "${close}". Known: ${known.join(', ')}` : `Known: ${known.join(', ')}`,
+    });
+}
 function checkFontBlock(ctx, path, raw, required) {
     if (raw === undefined) {
         if (required)
@@ -119,15 +87,11 @@ function checkFontBlock(ctx, path, raw, required) {
         // corrected object is what gets written, and the warning explains the
         // swap so the agent can mention it to the user.
         //
-        // Only a VALID case value is eligible: the auto-correct used to run
-        // first and mutate any string (including "lower"/"uppercase") to
-        // suitsCase[0], so the enum check below then saw the corrected value and
-        // the kit passed with a warning where the engine hard-rejects the whole
-        // theme — kit-ok/engine-reject, the exact parity direction the gate
-        // exists to forbid.
+        // Only a VALID case value is eligible: correcting any string (including
+        // "lower"/"uppercase") would let the enum check below see the corrected
+        // value and pass a theme the engine hard-rejects.
         const entry = HUD_FONTS[raw.key];
-        if ((raw.case === 'upper' || raw.case === 'normal')
-            && !entry.suitsCase.includes(raw.case)) {
+        if (includes(LABEL_CASES, raw.case) && !includes(entry.suitsCase, raw.case)) {
             const originalCase = raw.case;
             const correctedCase = entry.suitsCase[0];
             raw.case = correctedCase;
@@ -138,21 +102,21 @@ function checkFontBlock(ctx, path, raw, required) {
             });
         }
     }
-    if (raw.case !== undefined && raw.case !== 'upper' && raw.case !== 'normal') {
+    if (raw.case !== undefined && !includes(LABEL_CASES, raw.case)) {
         ctx.errors.push({ path: `${path}.case`, message: `${JSON.stringify(raw.case)} is not "upper" or "normal"` });
     }
-    if (raw.weightBody !== undefined && ![300, 400, 500, 700].includes(raw.weightBody)) {
-        ctx.errors.push({ path: `${path}.weightBody`, message: `${JSON.stringify(raw.weightBody)} is not one of 300, 400, 500, 700` });
+    if (raw.weightBody !== undefined && !includes(FONT_BODY_WEIGHTS, raw.weightBody)) {
+        ctx.errors.push({ path: `${path}.weightBody`, message: `${JSON.stringify(raw.weightBody)} is not one of ${FONT_BODY_WEIGHTS.join(', ')}` });
     }
-    if (raw.weightHeading !== undefined && ![400, 500, 700, 900].includes(raw.weightHeading)) {
-        ctx.errors.push({ path: `${path}.weightHeading`, message: `${JSON.stringify(raw.weightHeading)} is not one of 400, 500, 700, 900` });
+    if (raw.weightHeading !== undefined && !includes(FONT_HEADING_WEIGHTS, raw.weightHeading)) {
+        ctx.errors.push({ path: `${path}.weightHeading`, message: `${JSON.stringify(raw.weightHeading)} is not one of ${FONT_HEADING_WEIGHTS.join(', ')}` });
     }
     if (raw.trackingLabel !== undefined)
-        checkNumber(ctx, `${path}.trackingLabel`, raw.trackingLabel, 0, 4);
+        checkNumber(ctx, `${path}.trackingLabel`, raw.trackingLabel, 'trackingLabel');
     if (raw.outlineWidth !== undefined)
-        checkNumber(ctx, `${path}.outlineWidth`, raw.outlineWidth, 0, 3);
+        checkNumber(ctx, `${path}.outlineWidth`, raw.outlineWidth, 'outlineWidth');
     if (raw.sizeScale !== undefined)
-        checkNumber(ctx, `${path}.sizeScale`, raw.sizeScale, 0.85, 1.3);
+        checkNumber(ctx, `${path}.sizeScale`, raw.sizeScale, 'sizeScale');
 }
 function checkColorsBlock(ctx, path, raw, required) {
     if (raw === undefined) {
@@ -165,20 +129,15 @@ function checkColorsBlock(ctx, path, raw, required) {
         return;
     }
     if (required) {
-        for (const key of REQUIRED_COLOR_KEYS) {
+        for (const key of REQUIRED_THEME_COLOR_KEYS) {
             if (raw[key] === undefined) {
                 ctx.errors.push({ path: `${path}.${key}`, message: `colors.${key} is required (hex string)` });
             }
         }
     }
     for (const key of Object.keys(raw)) {
-        if (!COLOR_KEYS.includes(key)) {
-            const close = suggestClosest(key, COLOR_KEYS);
-            ctx.errors.push({
-                path: `${path}.${key}`,
-                message: `unknown color token "${key}"`,
-                suggestion: close ? `Closest match: "${close}". Known: ${COLOR_KEYS.join(', ')}` : `Known: ${COLOR_KEYS.join(', ')}`,
-            });
+        if (!includes(THEME_COLOR_KEYS, key)) {
+            unknownKey(ctx, `${path}.${key}`, `unknown color token "${key}"`, key, THEME_COLOR_KEYS);
             continue;
         }
         checkHexAt(ctx, `${path}.${key}`, raw[key]);
@@ -191,21 +150,15 @@ function checkShapeBlock(ctx, path, raw) {
         ctx.errors.push({ path, message: 'shape must be an object' });
         return;
     }
-    if (raw.radiusPill !== undefined)
-        checkNumber(ctx, `${path}.radiusPill`, raw.radiusPill, 0, 500);
-    if (raw.radiusCard !== undefined)
-        checkNumber(ctx, `${path}.radiusCard`, raw.radiusCard, 0, 32);
-    if (raw.borderWidth !== undefined)
-        checkNumber(ctx, `${path}.borderWidth`, raw.borderWidth, 0, 6);
-    if (raw.bevel !== undefined)
-        checkNumber(ctx, `${path}.bevel`, raw.bevel, 0, 1);
-    if (raw.gloss !== undefined)
-        checkNumber(ctx, `${path}.gloss`, raw.gloss, 0, 1);
+    for (const token of ['radiusPill', 'radiusCard', 'borderWidth', 'bevel', 'gloss']) {
+        if (raw[token] !== undefined)
+            checkNumber(ctx, `${path}.${token}`, raw[token], token);
+    }
     if (raw.glow !== undefined)
-        checkKeyed(ctx, `${path}.glow`, raw.glow, HUD_GLOW_KEYS);
+        checkKeyed(ctx, `${path}.glow`, raw.glow, GLOW_KEYS);
     if (raw.glowColor !== undefined)
         checkHexAt(ctx, `${path}.glowColor`, raw.glowColor);
-    if (raw.imageRendering !== undefined && raw.imageRendering !== 'auto' && raw.imageRendering !== 'pixelated') {
+    if (raw.imageRendering !== undefined && !includes(IMAGE_RENDERINGS, raw.imageRendering)) {
         ctx.errors.push({ path: `${path}.imageRendering`, message: `${JSON.stringify(raw.imageRendering)} is not "auto" or "pixelated"` });
     }
 }
@@ -226,7 +179,7 @@ function checkDecorationValue(ctx, path, slotName, value) {
         // Suitability is a WARNING, matching the engine: an unsuited pairing
         // renders, it just usually looks wrong.
         const entry = HUD_DECORATIONS[value];
-        if (!entry.suitsSlots.includes(slotName)) {
+        if (!includes(entry.suitsSlots, slotName)) {
             ctx.warnings.push({
                 path,
                 message: `decoration "${value}" isn't designed for slot "${slotName}" (suits: ${entry.suitsSlots.join(', ')})`,
@@ -239,18 +192,18 @@ function checkDecorationValue(ctx, path, slotName, value) {
             ctx.errors.push({ path: `${path}.svg`, message: 'inline decoration must have an svg string' });
             return;
         }
-        if (value.svg.length > 16384) {
+        if (value.svg.length > MAX_INLINE_SVG_LENGTH) {
             ctx.errors.push({ path: `${path}.svg`, message: 'inline SVG exceeds 16kb limit' });
         }
         if (slotName === 'borderImage') {
             if (value.borderSlice !== undefined)
-                checkNumber(ctx, `${path}.borderSlice`, value.borderSlice, 0, 200);
+                checkNumber(ctx, `${path}.borderSlice`, value.borderSlice, 'borderSlice');
             if (value.repeat !== undefined)
-                checkKeyed(ctx, `${path}.repeat`, value.repeat, BORDER_REPEAT_VALUES);
+                checkKeyed(ctx, `${path}.repeat`, value.repeat, BORDER_IMAGE_REPEATS);
         }
         else {
-            if (value.size !== undefined && value.size !== 'cover' && value.size !== 'contain' && value.size !== 'auto'
-                && !(typeof value.size === 'string' && TILE_SIZE.test(value.size))) {
+            if (value.size !== undefined && !includes(BACKGROUND_SIZE_KEYWORDS, value.size)
+                && !(typeof value.size === 'string' && BACKGROUND_TILE_SIZE.test(value.size))) {
                 ctx.errors.push({
                     path: `${path}.size`,
                     message: `${JSON.stringify(value.size)} is not "cover", "contain", "auto", or an explicit tile size`,
@@ -258,14 +211,20 @@ function checkDecorationValue(ctx, path, slotName, value) {
                 });
             }
             if (value.position !== undefined)
-                checkKeyed(ctx, `${path}.position`, value.position, POSITION_VALUES);
+                checkKeyed(ctx, `${path}.position`, value.position, BACKGROUND_POSITIONS);
             if (value.repeat !== undefined)
-                checkKeyed(ctx, `${path}.repeat`, value.repeat, REPEAT_VALUES);
+                checkKeyed(ctx, `${path}.repeat`, value.repeat, BACKGROUND_REPEATS);
         }
         return;
     }
     ctx.errors.push({ path, message: 'expected curated decoration key string or inline SVG object' });
 }
+function checkElementClassKey(ctx, path, elementClass) {
+    if (includes(HUD_ELEMENT_CLASSES, elementClass))
+        return true;
+    unknownKey(ctx, `${path}.${elementClass}`, `unknown HUD element class "${elementClass}"`, elementClass, HUD_ELEMENT_CLASSES);
+    return false;
+}
 function checkDecorationsBlock(ctx, path, raw) {
     if (raw === undefined || raw === null)
         return;
@@ -274,30 +233,14 @@ function checkDecorationsBlock(ctx, path, raw) {
         return;
     }
     for (const elementClass of Object.keys(raw)) {
-        if (!HUD_ELEMENT_CLASSES.includes(elementClass)) {
-            const close = suggestClosest(elementClass, HUD_ELEMENT_CLASSES);
-            ctx.errors.push({
-                path: `${path}.${elementClass}`,
-                message: `unknown HUD element class "${elementClass}"`,
-                suggestion: close
-                    ? `Closest match: "${close}". Known: ${HUD_ELEMENT_CLASSES.join(', ')}`
-                    : `Known: ${HUD_ELEMENT_CLASSES.join(', ')}`,
-            });
+        if (!checkElementClassKey(ctx, path, elementClass))
             continue;
-        }
         const slots = raw[elementClass];
         if (!isObject(slots))
             continue;
         for (const slotName of Object.keys(slots)) {
-            if (!HUD_DECORATION_SLOTS.includes(slotName)) {
-                const close = suggestClosest(slotName, HUD_DECORATION_SLOTS);
-                ctx.errors.push({
-                    path: `${path}.${elementClass}.${slotName}`,
-                    message: `unknown slot "${slotName}"`,
-                    suggestion: close
-                        ? `Closest match: "${close}". Known: ${HUD_DECORATION_SLOTS.join(', ')}`
-                        : `Known: ${HUD_DECORATION_SLOTS.join(', ')}`,
-                });
+            if (!includes(DECORATION_SLOT_KINDS, slotName)) {
+                unknownKey(ctx, `${path}.${elementClass}.${slotName}`, `unknown slot "${slotName}"`, slotName, DECORATION_SLOT_KINDS);
                 continue;
             }
             checkDecorationValue(ctx, `${path}.${elementClass}.${slotName}`, slotName, slots[slotName]);
@@ -312,17 +255,8 @@ function checkElementsBlock(ctx, path, raw) {
         return;
     }
     for (const elementClass of Object.keys(raw)) {
-        if (!HUD_ELEMENT_CLASSES.includes(elementClass)) {
-            const close = suggestClosest(elementClass, HUD_ELEMENT_CLASSES);
-            ctx.errors.push({
-                path: `${path}.${elementClass}`,
-                message: `unknown HUD element class "${elementClass}"`,
-                suggestion: close
-                    ? `Closest match: "${close}". Known: ${HUD_ELEMENT_CLASSES.join(', ')}`
-                    : `Known: ${HUD_ELEMENT_CLASSES.join(', ')}`,
-            });
+        if (!checkElementClassKey(ctx, path, elementClass))
             continue;
-        }
         const override = raw[elementClass];
         if (!isObject(override)) {
             ctx.errors.push({ path: `${path}.${elementClass}`, message: 'expected a partial theme object' });
@@ -339,6 +273,34 @@ function checkElementsBlock(ctx, path, raw) {
         checkDecorationsBlock(ctx, `${path}.${elementClass}.decorations`, override.decorations);
     }
 }
+function checkIconsBlock(ctx, raw) {
+    if (raw === undefined || raw === null)
+        return;
+    if (!isObject(raw)) {
+        ctx.errors.push({ path: 'icons', message: `icons must be an object keyed by slot name (${THEME_ICON_KEYS.join(', ')})` });
+        return;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!includes(THEME_ICON_KEYS, key)) {
+            ctx.errors.push({
+                path: `icons.${key}`,
+                message: `unknown icon slot "${key}"`,
+                suggestion: `Known: ${THEME_ICON_KEYS.join(', ')}`,
+            });
+            continue;
+        }
+        const value = raw[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value !== 'string') {
+            ctx.errors.push({ path: `icons.${key}`, message: 'icon SVG must be a string' });
+            continue;
+        }
+        if (value.length > MAX_INLINE_SVG_LENGTH) {
+            ctx.errors.push({ path: `icons.${key}`, message: 'icon SVG exceeds 16kb limit' });
+        }
+    }
+}
 /**
  * Whether an issue would make the ENGINE reject the whole theme, or only drop a
  * leaf while the theme keeps rendering.
@@ -358,6 +320,11 @@ export function isEngineFatalIssue(issue) {
         return false;
     return true;
 }
+/**
+ * Validate a whole inline theme at write time. Mutates `theme` in one place: a
+ * font case the font is not designed for is auto-corrected (with a warning), and
+ * the corrected object is what the caller writes.
+ */
 export function validateThemeStrict(theme) {
     const ctx = { errors: [], warnings: [] };
     if (!isObject(theme)) {
@@ -372,35 +339,6 @@ export function validateThemeStrict(theme) {
     checkShapeBlock(ctx, 'shape', theme.shape);
     checkDecorationsBlock(ctx, 'decorations', theme.decorations);
     checkElementsBlock(ctx, 'elements', theme.elements);
-    // icons
-    const icons = theme.icons;
-    if (icons !== undefined && icons !== null) {
-        if (!isObject(icons)) {
-            ctx.errors.push({ path: 'icons', message: 'icons must be an object keyed by slot name (heart, mouse, arrow)' });
-        }
-        else {
-            for (const key of Object.keys(icons)) {
-                if (!HUD_ICON_KEYS.includes(key)) {
-                    ctx.errors.push({
-                        path: `icons.${key}`,
-                        message: `unknown icon slot "${key}"`,
-                        suggestion: `Known: ${HUD_ICON_KEYS.join(', ')}`,
-                    });
-                    continue;
-                }
-                const value = icons[key];
-                if (value === undefined || value === null)
-                    continue;
-                if (typeof value !== 'string') {
-                    ctx.errors.push({ path: `icons.${key}`, message: 'icon SVG must be a string' });
-                    continue;
-                }
-                if (value.length > 16384) {
-                    ctx.errors.push({ path: `icons.${key}`, message: 'icon SVG exceeds 16kb limit' });
-                }
-            }
-        }
-    }
+    checkIconsBlock(ctx, theme.icons);
     return { ok: ctx.errors.length === 0, errors: ctx.errors, warnings: ctx.warnings };
 }
-//# sourceMappingURL=theme-validate.js.map

package/dist/verify/browser.d.ts

@@ -102,3 +102,14 @@ export declare class VerifyBrowserSession {
     close(): Promise<void>;
     check(options: HeadlessCheckOptions): Promise<VerifyObservations>;
 }
+/**
+ * One check on a page that already exists: arm the probes, `navigate` (a `goto` for verify, a
+ * `reload` for a packaged desktop app that loaded its own page before anything could attach),
+ * start the game the way a player does, settle, and observe. Split from
+ * {@link VerifyBrowserSession.check} so `bitmagic steam build` can hold the real Electron app to
+ * the same verdict a browser tab gets.
+ */
+export declare function observeGamePage(page: Page, options: HeadlessCheckOptions, viewport: {
+    width: number;
+    height: number;
+}, navigate: (page: Page) => Promise<unknown>): Promise<VerifyObservations>;