@usequeek/theme-check 0.3.6 → 0.4.0

package/dist/context.js

@@ -68,6 +68,7 @@ export async function loadContext(themeDir, env = {}) {
         retired: config?.active === false,
         demo: demos.find((store) => store.id === 'default')?.data ?? null,
         demos,
+        themeConfig: config,
         declaredDemos: config === null ? null : Array.isArray(declared) ? declared : [],
         defaultDescription: typeof primary?.description === 'string' ? primary.description : null,
         defaultFor: primary?.for ?? null,

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export type { CheckEnv, Finding, Rule, Severity, ThemeContext, DemoStore, Declar
 export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, SUBCATEGORIES, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
 export { TEMPLATE_COPY_PLACES, copyViolations, isTestimonialSection, storeNameForms } from './utils/template-copy.js';
 export { PRIMARY_DEMO_ID, DEMO_ID_FORMAT, demoFilesOf } from './utils/theme-demos.js';
+export { designsOf, groupTemplates, mainTemplateKey, composeLabel, type DesignDeclaration, type ThemeDesignsConfig, type ThemeDesign, type ThemeTemplate, } from './utils/theme-designs.js';
 export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';
-export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, frameworkImport, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
+export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templateDesignsRule, TEMPLATE_DESIGNS_MAX, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, frameworkImport, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
 export { ANALYSIS_RULES, variantParityRule, fieldParityRule, designTokensRule } from './rules/analysis.js';

package/dist/index.js

@@ -9,9 +9,12 @@ export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fil
 export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, SUBCATEGORIES, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
 export { TEMPLATE_COPY_PLACES, copyViolations, isTestimonialSection, storeNameForms } from './utils/template-copy.js';
 export { PRIMARY_DEMO_ID, DEMO_ID_FORMAT, demoFilesOf } from './utils/theme-demos.js';
+// Theme → template → design (contract R2.8): the resolver the registry, the
+// preview and these rules share. Also published alone as `@usequeek/theme-check/designs`.
+export { designsOf, groupTemplates, mainTemplateKey, composeLabel, } from './utils/theme-designs.js';
 export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';
 // Per-kind rule arrays and the individual rule constants, for rule-level unit
 // tests that want to run one rule against a hand-built ThemeContext instead
 // of a whole theme directory through checkTheme().
-export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, frameworkImport, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
+export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templateDesignsRule, TEMPLATE_DESIGNS_MAX, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, frameworkImport, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
 export { ANALYSIS_RULES, variantParityRule, fieldParityRule, designTokensRule } from './rules/analysis.js';

package/dist/rules/static.d.ts

@@ -41,7 +41,16 @@ export declare const templateChromeRule: Rule;
 export declare const templateStyleRule: Rule;
 export declare const templateBusinessRule: Rule;
 export declare const templateVersionsRule: Rule;
-/** The designed pages every template ships (contract R2.3); versions `-2`… count. */
+/** A template has at most this many designs (contract R2.2). */
+export declare const TEMPLATE_DESIGNS_MAX = 3;
+/**
+ * Theme → template → design (contract R2.8). Designs are grouped by the
+ * `template` key each one declares, exactly as the registry and the preview
+ * group them (utils/theme-designs.ts). The resolver is lenient, so a config
+ * written before R2.8 still previews; this rule is where it is strict.
+ */
+export declare const templateDesignsRule: Rule;
+/** The designed pages every template ships (contract R2.3); page versions `-2`… count. */
 export declare const TEMPLATE_PAGES: readonly ["about", "sales", "landing"];
 export declare const templatePagesRule: Rule;
 export declare const templateCopyRule: Rule;

package/dist/rules/static.js

@@ -2,6 +2,7 @@ import { join, relative } from 'node:path';
 import { readdirSync, existsSync, readFileSync } from 'node:fs';
 import { foreignImageRefs } from '../utils/theme-demo-images.js';
 import { DEMO_ID_FORMAT, PRIMARY_DEMO_ID } from '../utils/theme-demos.js';
+import { designsOf, groupTemplates, mainTemplateKey } from '../utils/theme-designs.js';
 import { SCREENSHOT_LOCK, TEMPLATE_DESCRIPTION_MAX, TEMPLATE_DESCRIPTION_PLACEHOLDER, declaredFieldsByVariant, isPresentationalField, screenshotFile, screenshotUrl, sectionCopy } from '../utils/theme-templates.js';
 import { copyViolations, isTestimonialSection } from '../utils/template-copy.js';
 import { BUSINESS_KEYS, SERVICE_SLUGS, isBusinessKey } from '../utils/business-vocabulary.js';
@@ -66,6 +67,26 @@ function storesOf(context) {
         stores.unshift({ id: PRIMARY_DEMO_ID, file: 'demo.json', data: null });
     return stores;
 }
+/**
+ * theme.config.ts as the design resolver reads it (contract R2.8): its own
+ * fields, with `demos` as the context declares them. Never null, so a config
+ * that did not load resolves to demo.json alone.
+ */
+function designsConfig(context) {
+    const config = context.themeConfig !== null && typeof context.themeConfig === 'object' ? context.themeConfig : {};
+    return { ...config, demos: (context.declaredDemos ?? []) };
+}
+/** Every design, grouped by its explicit `template` exactly as the registry groups it, in declaration order. */
+function designsOfContext(context) {
+    return designsOf(designsConfig(context));
+}
+/** A design's declaration as written: `default_demo`, or its (first) `demos[]` entry. */
+function declarationOf(context, id) {
+    const config = designsConfig(context);
+    if (id === PRIMARY_DEMO_ID)
+        return config.default_demo ?? {};
+    return config.demos?.find((demo) => demo?.id === id) ?? {};
+}
 export const demoStoreRule = {
     id: 'theme/demo-store',
     summary: 'Every demo store is a believable store that identifies itself as this theme',
@@ -139,6 +160,9 @@ export const demoStoresRule = {
         };
         const declared = context.declaredDemos ?? [];
         const secondaries = context.demos.filter((store) => store.id !== PRIMARY_DEMO_ID);
+        // `label` and `for` are the template's, declared once on its design 1; a
+        // later design inherits them (theme/template-designs checks a repeat).
+        const firsts = new Set(designsOfContext(context).filter((design) => design.designIndex === 1).map((design) => design.id));
         for (const demo of declared) {
             const id = String(demo?.id ?? '');
             if (id === PRIMARY_DEMO_ID) {
@@ -152,6 +176,8 @@ export const demoStoresRule = {
             if (!secondaries.some((store) => store.id === id)) {
                 add(at, `demos[] declares "${id}" but there is no file ${context.env.root}demos/${id}.json`, 'Add the store, or drop the declaration. The registry advertises a preview URL for every declared store.');
             }
+            if (!firsts.has(id))
+                continue;
             if (typeof demo.label !== 'string' || demo.label.trim() === '') {
                 add(at, `demos[] "${id}" has no label`, 'Give it the name a merchant sees, e.g. "Restaurant & takeaway".');
             }
@@ -169,7 +195,7 @@ export const demoStoresRule = {
                 continue;
             }
             if (!declared.some((demo) => demo?.id === store.id)) {
-                add(`${context.env.root}${store.file}`, `demos/${store.id}.json is not declared in theme.config.ts`, `Add \`{ id: '${store.id}', label, for: [...] }\` to \`demos\` in theme.config.ts, or remove the file. An undeclared store is previewable but never offered to anyone.`);
+                add(`${context.env.root}${store.file}`, `demos/${store.id}.json is not declared in theme.config.ts`, `Add \`{ id: '${store.id}', template, label, for, description }\` to \`demos\` in theme.config.ts, or remove the file. An undeclared store is previewable but never offered to anyone.`);
             }
         }
         const seen = new Map();
@@ -835,9 +861,12 @@ export const templateBusinessRule = {
         if (context.retired || context.declaredDemos === null)
             return [];
         const config = `${context.env.root}theme.config.ts`;
+        // Each template once, by its design 1: `for` is the template's, and a later
+        // design that repeats it is theme/template-designs' to compare.
+        const firsts = new Set(designsOfContext(context).filter((design) => design.designIndex === 1).map((design) => design.id));
         const templates = [
             { id: PRIMARY_DEMO_ID, keys: context.defaultFor, where: `${config} → default_demo.for` },
-            ...context.declaredDemos.map((demo) => ({ id: demo.id, keys: demo.for, where: `${config} → demos[${demo.id}].for` })),
+            ...context.declaredDemos.filter((demo) => firsts.has(demo.id)).map((demo) => ({ id: demo.id, keys: demo.for, where: `${config} → demos[${demo.id}].for` })),
         ];
         const findings = [];
         for (const { id, keys, where } of templates) {
@@ -880,14 +909,20 @@ export const templateBusinessRule = {
         return findings;
     },
 };
-/** `food-2` → `food`; null for an id that is not a numbered version. */
-function versionBase(id) {
-    const match = /^(.+)-([2-9])$/.exec(id);
+/**
+ * A page slug's kind: `about-2` → `about`; null for a slug with no `-N`
+ * suffix. Only page slugs are numbered (R2.3). Designs are grouped by their
+ * explicit `template` (R2.8), never by an id's suffix.
+ */
+function pageBase(slug) {
+    const match = /^(.+)-([2-9])$/.exec(slug);
     return match ? match[1] : null;
 }
+// Keeps its id (`theme/template-versions` is API: tools and to-do lists name
+// it); the R2.8 grouping checks are theme/template-designs'.
 export const templateVersionsRule = {
     id: 'theme/template-versions',
-    summary: 'Every template has its own home design, and a version serves its original\'s business',
+    summary: 'Every design has its own home: no two list the same sections in the same order',
     kind: 'static',
     run(context) {
         if (context.retired)
@@ -896,7 +931,7 @@ export const templateVersionsRule = {
         const sequence = (store) => (pagesOf(store).home?.content ?? []).map((section) => `${section?.type}/${section?.variant ?? 'default'}`).join(' → ');
         const seen = new Map();
         // The single-page default theme draws one fixed layout whatever its home
-        // lists, so its templates differ by business, not composition.
+        // lists, so its designs differ by business, not composition.
         for (const store of context.pageBased ? context.demos : []) {
             const home = sequence(store);
             if (!home)
@@ -905,8 +940,8 @@ export const templateVersionsRule = {
             if (first) {
                 findings.push(finding(context, 'theme/template-versions', 'reject', {
                     where: `${context.env.root}${store.file} → pages.home`,
-                    found: `template "${store.id}" has the same home sections, in the same order, as "${first}"`,
-                    fix: 'A template must be its own design, not a recolour: change the order and the section variants (and the header, footer and palette where the theme allows). Vendors are spread across versions; two identical ones make that a coin toss between the same page.',
+                    found: `design "${store.id}" has the same home sections, in the same order, as "${first}"`,
+                    fix: 'Each design must be its own, not a recolour: change the order and the section variants (and the header, footer and palette where the theme allows). Vendors of one business are spread across its template\'s designs; two identical ones make that a coin toss between the same page.',
                     docs: `${context.env.docs}#templates`,
                 }));
             }
@@ -914,23 +949,109 @@ export const templateVersionsRule = {
                 seen.set(home, store.id);
             }
         }
-        const declared = context.declaredDemos ?? [];
-        const forOf = new Map(declared.map((demo) => [demo.id, JSON.stringify(demo.for ?? [])]));
-        for (const demo of declared) {
-            const base = versionBase(demo.id);
-            if (!base || !forOf.has(base) || forOf.get(base) === forOf.get(demo.id))
+        return findings;
+    },
+};
+/** A template has at most this many designs (contract R2.2). */
+export const TEMPLATE_DESIGNS_MAX = 3;
+/**
+ * Theme → template → design (contract R2.8). Designs are grouped by the
+ * `template` key each one declares, exactly as the registry and the preview
+ * group them (utils/theme-designs.ts). The resolver is lenient, so a config
+ * written before R2.8 still previews; this rule is where it is strict.
+ */
+export const templateDesignsRule = {
+    id: 'theme/template-designs',
+    summary: "Every design names its template; a template's designs share its label and business and are told apart by design_label",
+    kind: 'static',
+    run(context) {
+        if (context.retired || context.declaredDemos === null)
+            return [];
+        const findings = [];
+        const config = designsConfig(context);
+        const where = (id, field) => `${context.env.root}theme.config.ts → ${id === PRIMARY_DEMO_ID ? 'default_demo' : `demos[${id}]`}.${field}`;
+        const add = (at, found, fix) => {
+            findings.push(finding(context, 'theme/template-designs', 'reject', { where: at, found, fix, docs: `${context.env.docs}#templates` }));
+        };
+        const designs = designsOfContext(context);
+        // Every design names its template, by a key that can be one.
+        for (const { id } of designs) {
+            const key = declarationOf(context, id).template;
+            if (key === undefined || key === null || key === '') {
+                if (id === PRIMARY_DEMO_ID) {
+                    add(where(id, 'template'), 'the main template has no key (default_demo.template)', "Add `template` to `default_demo`: a lowercase slug naming its business (medley's main template is `beauty`). On a theme with two or more templates the main store moves to `/<slug>~<key>`, and `/<slug>` becomes the template gallery.");
+                }
+                else {
+                    add(where(id, 'template'), `design "${id}" names no template`, `Add \`template\` to it: \`template: '${id}'\` when it is the first design of its business, or the key of the template it is another design of. Designs are grouped by this key, never by an id's \`-2\`.`);
+                }
+            }
+            else if (typeof key !== 'string' || !DEMO_ID_FORMAT.test(key)) {
+                add(where(id, 'template'), `template key "${String(key)}" is not a slug`, 'Use lowercase letters, digits and single hyphens: the key is a URL segment (`/<slug>~<key>`). Never rename a key once shipped; old links redirect by it.');
+            }
+            else if (key === PRIMARY_DEMO_ID) {
+                add(where(id, 'template'), `template key "${key}" is reserved`, '"default" is demo.json\'s design id, never a template key. Name the business: `beauty`, `food`, `laundry`.');
+            }
+        }
+        // Template keys and design ids share one namespace: `/<slug>~<segment>` opens exactly one store.
+        const main = mainTemplateKey(config);
+        if (main !== null && designs.some((design) => design.id === main)) {
+            add(where(PRIMARY_DEMO_ID, 'template'), `the main template's key "${main}" is also a design id`, `\`/<slug>~${main}\` must open one store. Give the main template another key; design ids are never renamed once shipped, keys neither, so settle it before the theme ships.`);
+        }
+        for (const template of groupTemplates(designs)) {
+            const { key } = template;
+            if (key === null)
+                continue; // a main template with no key: reported above
+            const count = template.designs.length;
+            const [first, ...later] = template.designs;
+            if (first.id !== PRIMARY_DEMO_ID && !template.designs.some((design) => design.id === key)) {
+                add(where(first.id, 'template'), `template "${key}" has no design 1 (a design whose id is "${key}")`, `Design 1 of a template is the design whose id is its key, so \`/<slug>~${key}\` opens the template. Declare \`{ id: '${key}', template: '${key}', label, for, description }\` with demos/${key}.json, or give "${first.id}" its own id as its \`template\`.`);
+            }
+            if (count > TEMPLATE_DESIGNS_MAX) {
+                add(where(template.designs[TEMPLATE_DESIGNS_MAX].id, 'template'), `template "${key}" has ${count} designs; a template has at most ${TEMPLATE_DESIGNS_MAX}`, `Keep ${TEMPLATE_DESIGNS_MAX} designs of "${key}" (contract R2.2): drop the rest, or make one a template of another business.`);
+            }
+            // `label` and `for` are the template's, declared once on design 1. A later
+            // design may repeat them unchanged, or leave them out and inherit them.
+            for (const design of later) {
+                const declared = declarationOf(context, design.id);
+                const label = typeof declared.label === 'string' ? declared.label.trim() : '';
+                if (label !== '' && label !== template.label) {
+                    add(where(design.id, 'label'), `design "${design.id}" relabels its template ("${label}"); a design is named by design_label`, `\`label\` is the template's ("${template.label}"), declared once on "${first.id}". Drop \`label\` from "${design.id}" (it inherits it), and say what tells this design apart in \`design_label\`.`);
+                }
+                if (declared.for !== undefined && JSON.stringify(declared.for) !== JSON.stringify(template.for)) {
+                    add(where(design.id, 'for'), `design "${design.id}" is for ${JSON.stringify(declared.for)}, its template "${key}" for ${JSON.stringify(template.for)}`, `Every design of a template is for the same business: drop \`for\` from "${design.id}" (it inherits "${first.id}"'s), or make it exactly ${JSON.stringify(template.for)}. The backend spreads a business's vendors across its template's designs.`);
+                }
+            }
+            if (count > 1) {
+                const named = new Map();
+                for (const design of template.designs) {
+                    if (design.designLabel === null) {
+                        add(where(design.id, 'design_label'), `design "${design.id}" has no design_label (template "${key}" has ${count} designs)`, `Name what tells "${design.id}" from the template's other designs ("Dining room", "Neighbourhood buka"). The registry, the gallery and the Designs dropdown show it.`);
+                        continue;
+                    }
+                    const other = named.get(design.designLabel.toLowerCase());
+                    if (other) {
+                        add(where(design.id, 'design_label'), `designs "${other}" and "${design.id}" share the design_label "${design.designLabel}"`, 'Give each design of a template its own `design_label`: it is how a merchant tells them apart.');
+                    }
+                    else {
+                        named.set(design.designLabel.toLowerCase(), design.id);
+                    }
+                }
+            }
+        }
+        // A design_label is shown on every store built from the design (R2.6).
+        for (const design of designs) {
+            if (design.designLabel === null)
                 continue;
-            findings.push(finding(context, 'theme/template-versions', 'reject', {
-                where: `${context.env.root}theme.config.ts → demos[${demo.id}].for`,
-                found: `version "${demo.id}" is for ${forOf.get(demo.id)}, "${base}" for ${forOf.get(base)}`,
-                fix: `Give "${demo.id}" exactly the \`for\` of "${base}". Versions are the same business in different designs; the backend spreads matching vendors across them.`,
-                docs: `${context.env.docs}#templates`,
-            }));
+            const name = context.demos.find((store) => store.id === design.id)?.data?.profile?.name;
+            const why = copyViolations(design.designLabel, typeof name === 'string' ? name : null);
+            if (why.length === 0)
+                continue;
+            add(where(design.id, 'design_label'), `design "${design.id}" design_label: ${why.join('; ')}`, 'Write it true of any store in the business: no store name, place, naira amount, promise or date ("Neighbourhood buka", never "Lekki buka" or "Mama Tee\'s buka").');
         }
         return findings;
     },
 };
-/** The designed pages every template ships (contract R2.3); versions `-2`… count. */
+/** The designed pages every template ships (contract R2.3); page versions `-2`… count. */
 export const TEMPLATE_PAGES = ['about', 'sales', 'landing'];
 export const templatePagesRule = {
     id: 'theme/template-pages',
@@ -945,7 +1066,7 @@ export const templatePagesRule = {
             const pages = pagesOf(store);
             const where = `${context.env.root}${store.file} → pages`;
             for (const slug of TEMPLATE_PAGES) {
-                if (Object.keys(pages).some((key) => key === slug || versionBase(key) === slug))
+                if (Object.keys(pages).some((key) => key === slug || pageBase(key) === slug))
                     continue;
                 findings.push(finding(context, 'theme/template-pages', 'reject', {
                     where,
@@ -957,7 +1078,7 @@ export const templatePagesRule = {
                 }));
             }
             for (const [key, page] of Object.entries(pages)) {
-                const kind = TEMPLATE_PAGES.find((slug) => slug !== 'about' && (key === slug || versionBase(key) === slug));
+                const kind = TEMPLATE_PAGES.find((slug) => slug !== 'about' && (key === slug || pageBase(key) === slug));
                 if (!kind)
                     continue;
                 const content = page?.content ?? [];
@@ -1242,5 +1363,5 @@ export const placeholderContentRule = {
 };
 export const STATIC_RULES = [moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule,
     templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule,
-    templateBusinessRule, templateVersionsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule,
+    templateBusinessRule, templateVersionsRule, templateDesignsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule,
 ];

package/dist/types.d.ts

@@ -64,13 +64,23 @@ export interface DemoStore {
     /** Null when the file is missing or not valid JSON. */
     data: Record<string, unknown> | null;
 }
-/** A `demos[]` entry in theme.config.ts. */
+/**
+ * A `demos[]` entry in theme.config.ts: one design (contract R2.8). A theme is
+ * the look, a template is a business it is dressed as, and a design is one
+ * concrete store of a template — one demo file.
+ */
 export interface DeclaredDemo {
+    /** The design id: demos/<id>.json. Never renamed once shipped. */
     id: string;
-    label: string;
-    /** Business slugs (the vendor's service_slug/service_type vocabulary). */
-    for: string[];
-    /** What an AI reads to choose this template for a merchant (≤ 300 chars). */
+    /** The key of the template this design belongs to: `food`. Explicit on every design. */
+    template?: string;
+    /** The template's label, the business as a merchant sees it. Declared on the template's design 1; a later design inherits it. */
+    label?: string;
+    /** What tells this design from its template's others: `Neighbourhood buka`. Required when a template has 2+ designs. */
+    design_label?: string;
+    /** The template's business slugs (the vendor's service_slug/service_type vocabulary). Declared on design 1; a later design inherits them. */
+    for?: string[];
+    /** What an AI reads to choose this design for a merchant (≤ 300 chars). */
     description?: string;
 }
 /**
@@ -106,6 +116,12 @@ export interface ThemeContext {
     demo: Record<string, unknown> | null;
     /** Every store on disk, the primary first. */
     demos: DemoStore[];
+    /**
+     * theme.config.ts's default export, as loaded; null when it could not be
+     * loaded. The template and design rules read it through the design resolver
+     * (`designsOf`), so they group designs exactly as the registry does.
+     */
+    themeConfig: unknown;
     /** `demos` from theme.config.ts; null when the config could not be loaded. */
     declaredDemos: DeclaredDemo[] | null;
     /** `default_demo.description` from theme.config.ts — the primary template's description. */

package/dist/utils/business-vocabulary.json

@@ -4,7 +4,7 @@
     "foods", "local-meals", "shawarma-pizza-snacks", "suya", "boli", "fruits-fresh-natural",
     "meat-fish", "supermarket", "groceries", "shop-groceries", "local-market", "pharmacy",
     "health-wellness-store", "fashion", "beauty-cosmetics", "electronics", "phones-accessories",
-    "home-living", "baby-kids", "office-school", "shop", "shop-4-me", "laundry", "gas-refill", "home-cleaning",
+    "home-living", "baby-kids", "office-school", "shop", "laundry", "gas-refill", "home-cleaning",
     "car-wash"
   ],
   "catalogue": {

package/dist/utils/theme-designs.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Theme → template → design (queek_backend contract R2.8).
+ *
+ * A theme is the look. A template is a business the theme is dressed as
+ * (medley's Food), and a design is one concrete store of it, one demo file:
+ * `food` and `food-2` are the Food template's two designs. theme.config.ts
+ * declares every design. `default_demo` is the main template's first design
+ * (demo.json, id `default`); each `demos[]` entry is one more (demos/<id>.json).
+ *
+ *   default_demo: { template: 'beauty', label: 'Skincare & make-up', design_label: 'Photo collage', for: [...], description },
+ *   demos: [
+ *     { id: 'food', template: 'food', label: 'Restaurant & kitchen', design_label: 'Dining room', for: [...], description },
+ *     { id: 'food-2', template: 'food', design_label: 'Neighbourhood buka', description },
+ *   ],
+ *
+ * - `template` is the key designs are grouped by, explicit on every design
+ *   (never inferred from an id's `-2`): a slug, never `default`, never renamed
+ *   once shipped. Template keys and design ids share one namespace.
+ * - Design 1 of a template is the design whose id IS its key (`default` in the
+ *   main template), so `/medley~food` opens the Food template. The others
+ *   follow in `demos[]` order. The index is derived, never declared.
+ * - `label` (the business) and `for` belong to the template and are declared
+ *   on design 1. A later design may omit them; it inherits design 1's.
+ * - `design_label` names a design within its template ("Neighbourhood buka").
+ *
+ * Tolerant where theme-check is strict: a design without a valid `template` is
+ * a template of its own, keyed by its id, and a main design without one has no
+ * key (so no gallery). A config written before R2.8 previews and publishes as
+ * it did.
+ *
+ * One resolver for every consumer: the registry, the design index the proxy
+ * and the preview read, both copies of theme-check, and theme-cli. So it
+ * imports nothing. `yarn tools:sync-lists` copies this file byte for byte to
+ * theme-tools (packages/theme-check/src/utils/theme-designs.ts), and a copy
+ * that drifts fails `yarn tools:sync-lists --check`. Change it here, then sync.
+ */
+/** The id `demo.json` goes by: the main template's first design. Equal to theme-demos.ts's PRIMARY_DEMO_ID. */
+export declare const PRIMARY_DESIGN_ID = "default";
+/** Between the theme and the design in a preview segment: `medley~food-2`. Equal to DEMO_SEPARATOR. */
+export declare const DESIGN_SEPARATOR = "~";
+/** A design id or a template key: both land in a URL segment and a filename. Equal to DEMO_ID_FORMAT. */
+export declare const DESIGN_ID_FORMAT: RegExp;
+/** One design as theme.config.ts declares it (`default_demo`, or a `demos[]` entry with its `id`). */
+export interface DesignDeclaration {
+    /** The key of the template this design belongs to: `food`. */
+    template?: string;
+    /** The template's label, the business it is dressed as: `Restaurant & kitchen`. Declared on design 1. */
+    label?: string;
+    /** What tells this design from its template's others: `Neighbourhood buka`. */
+    design_label?: string;
+    /** The template's business, in lib/storefront/business-vocabulary.json. Declared on design 1. */
+    for?: string[];
+    /** What an AI reads to choose this design for a merchant (≤ 300 chars). */
+    description?: string;
+}
+/** The part of theme.config.ts this file reads. */
+export interface ThemeDesignsConfig {
+    /** The theme's name: the main template's label when `default_demo` declares none. */
+    name?: string;
+    default_demo?: DesignDeclaration;
+    demos?: Array<DesignDeclaration & {
+        id: string;
+    }>;
+}
+/** One design, resolved: what the registry publishes for it. */
+export interface ThemeDesign {
+    /** `default` for demo.json, else the name of its demos/<id>.json. Never renamed once shipped. */
+    id: string;
+    /** Its template's key. Null only for a main design that declares none (a config written before R2.8). */
+    template: string | null;
+    /** The template's label (design 1's `label`). */
+    templateLabel: string;
+    /** 1 for design 1 (the design whose id is the key; `default` in the main template), then `demos[]` order. */
+    designIndex: number;
+    designLabel: string | null;
+    /** For readers that know no templates: see composeLabel. */
+    label: string;
+    /** The template's business: design 1's `for`, the same on every design of it. */
+    for: string[];
+    description: string | null;
+}
+/** A template: its designs, design 1 first. */
+export interface ThemeTemplate {
+    key: string | null;
+    label: string;
+    for: string[];
+    designs: ThemeDesign[];
+}
+/** One theme in themes/design-index.json. */
+export interface DesignIndexEntry {
+    /** The main template's key: `/<slug>~<main>` is demo.json once the theme has a gallery. */
+    main: string | null;
+    /** The main template first, then in the order the config first names each. */
+    templates: DesignIndexTemplate[];
+}
+export interface DesignIndexTemplate {
+    key: string | null;
+    label: string;
+    /** Design 1 first. `label` is the design's `design_label` (its composed label when it declares none). */
+    designs: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+/** themes/design-index.json: every active theme, by slug. */
+export type DesignIndex = Record<string, DesignIndexEntry>;
+/**
+ * The label a reader that knows no templates shows (the registry's `label`):
+ * the template's label when it has one design; `template — design` on every
+ * design, design 1 included, when it has more, so two cards never read alike.
+ */
+export declare function composeLabel(templateLabel: string, designLabel: string | null, designs: number): string;
+/** Every design the config declares, resolved, in declaration order (demo.json first). */
+export declare function designsOf(config: ThemeDesignsConfig | null | undefined): ThemeDesign[];
+/** Designs grouped into templates: the main template (demo.json's) first, each template's design 1 first. */
+export declare function groupTemplates(designs: readonly ThemeDesign[]): ThemeTemplate[];
+/** The main template's key (`default_demo.template`), or null when it declares none. */
+export declare function mainTemplateKey(config: ThemeDesignsConfig | null | undefined): string | null;
+/** The theme's entry in themes/design-index.json. */
+export declare function designIndexEntry(config: ThemeDesignsConfig | null | undefined): DesignIndexEntry;
+/**
+ * Does `/<slug>` open the template gallery? Only for a theme with two or more
+ * templates and a main key to move the main store to (`/<slug>~<main>`). A
+ * single-template theme keeps `/<slug>` as its store.
+ */
+export declare function hasGallery(theme: {
+    main: string | null;
+    templates: readonly unknown[];
+}): boolean;
+/**
+ * The preview segment of a design: `medley~food-2`. demo.json's is the bare
+ * slug, unless the theme has a gallery there: then it is `<slug>~<main key>`.
+ */
+export declare function designParam(slug: string, id: string, main: string | null, gallery: boolean): string;
+/**
+ * The design a preview segment's `~<segment>` names, or null for none: the
+ * inverse of designParam. The main key is demo.json (`default`) on a gallery
+ * theme; any other design id is itself. `default` is never a segment (one URL
+ * per design), and a single-template theme's key is none either: its store
+ * stays at the bare slug.
+ */
+export declare function designOfSegment(theme: DesignIndexEntry, segment: string): string | null;

package/dist/utils/theme-designs.js

@@ -0,0 +1,183 @@
+/**
+ * Theme → template → design (queek_backend contract R2.8).
+ *
+ * A theme is the look. A template is a business the theme is dressed as
+ * (medley's Food), and a design is one concrete store of it, one demo file:
+ * `food` and `food-2` are the Food template's two designs. theme.config.ts
+ * declares every design. `default_demo` is the main template's first design
+ * (demo.json, id `default`); each `demos[]` entry is one more (demos/<id>.json).
+ *
+ *   default_demo: { template: 'beauty', label: 'Skincare & make-up', design_label: 'Photo collage', for: [...], description },
+ *   demos: [
+ *     { id: 'food', template: 'food', label: 'Restaurant & kitchen', design_label: 'Dining room', for: [...], description },
+ *     { id: 'food-2', template: 'food', design_label: 'Neighbourhood buka', description },
+ *   ],
+ *
+ * - `template` is the key designs are grouped by, explicit on every design
+ *   (never inferred from an id's `-2`): a slug, never `default`, never renamed
+ *   once shipped. Template keys and design ids share one namespace.
+ * - Design 1 of a template is the design whose id IS its key (`default` in the
+ *   main template), so `/medley~food` opens the Food template. The others
+ *   follow in `demos[]` order. The index is derived, never declared.
+ * - `label` (the business) and `for` belong to the template and are declared
+ *   on design 1. A later design may omit them; it inherits design 1's.
+ * - `design_label` names a design within its template ("Neighbourhood buka").
+ *
+ * Tolerant where theme-check is strict: a design without a valid `template` is
+ * a template of its own, keyed by its id, and a main design without one has no
+ * key (so no gallery). A config written before R2.8 previews and publishes as
+ * it did.
+ *
+ * One resolver for every consumer: the registry, the design index the proxy
+ * and the preview read, both copies of theme-check, and theme-cli. So it
+ * imports nothing. `yarn tools:sync-lists` copies this file byte for byte to
+ * theme-tools (packages/theme-check/src/utils/theme-designs.ts), and a copy
+ * that drifts fails `yarn tools:sync-lists --check`. Change it here, then sync.
+ */
+/** The id `demo.json` goes by: the main template's first design. Equal to theme-demos.ts's PRIMARY_DEMO_ID. */
+export const PRIMARY_DESIGN_ID = 'default';
+/** Between the theme and the design in a preview segment: `medley~food-2`. Equal to DEMO_SEPARATOR. */
+export const DESIGN_SEPARATOR = '~';
+/** A design id or a template key: both land in a URL segment and a filename. Equal to DEMO_ID_FORMAT. */
+export const DESIGN_ID_FORMAT = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : null);
+const businessKeys = (value) => {
+    if (!Array.isArray(value))
+        return null;
+    const keys = value.filter((key) => typeof key === 'string');
+    return keys.length > 0 ? keys : null;
+};
+/** A declared `template`, or null when it is missing or could not be a key. */
+function templateKey(value) {
+    return typeof value === 'string' && DESIGN_ID_FORMAT.test(value) && value !== PRIMARY_DESIGN_ID ? value : null;
+}
+function declaredDesigns(config) {
+    const main = config?.default_demo ?? {};
+    const designs = [{
+            id: PRIMARY_DESIGN_ID,
+            primary: true,
+            key: templateKey(main.template),
+            label: text(main.label),
+            designLabel: text(main.design_label),
+            for: businessKeys(main.for),
+            description: text(main.description),
+        }];
+    const seen = new Set([PRIMARY_DESIGN_ID]);
+    const demos = config?.demos;
+    for (const demo of Array.isArray(demos) ? demos : []) {
+        // A missing, reserved or repeated id is theme-check's to name; it is no design.
+        if (typeof demo?.id !== 'string' || seen.has(demo.id))
+            continue;
+        seen.add(demo.id);
+        designs.push({
+            id: demo.id,
+            primary: false,
+            key: templateKey(demo.template) ?? demo.id,
+            label: text(demo.label),
+            designLabel: text(demo.design_label),
+            for: businessKeys(demo.for),
+            description: text(demo.description),
+        });
+    }
+    return designs;
+}
+/**
+ * The label a reader that knows no templates shows (the registry's `label`):
+ * the template's label when it has one design; `template — design` on every
+ * design, design 1 included, when it has more, so two cards never read alike.
+ */
+export function composeLabel(templateLabel, designLabel, designs) {
+    return designs > 1 && designLabel ? `${templateLabel} — ${designLabel}` : templateLabel;
+}
+/** Every design the config declares, resolved, in declaration order (demo.json first). */
+export function designsOf(config) {
+    const declared = declaredDesigns(config);
+    const groups = new Map();
+    for (const design of declared)
+        groups.set(design.key, [...(groups.get(design.key) ?? []), design]);
+    const resolved = new Map();
+    for (const [key, members] of groups) {
+        const first = members.find((design) => design.primary) ?? members.find((design) => design.id === key) ?? members[0];
+        const ordered = [first, ...members.filter((design) => design !== first)];
+        const templateLabel = first.label
+            ?? (first.primary ? text(config?.name) : null)
+            ?? ordered.map((design) => design.label).find((label) => label !== null)
+            ?? key
+            ?? first.id;
+        const templateFor = first.for ?? ordered.map((design) => design.for).find((keys) => keys !== null) ?? [];
+        ordered.forEach((design, position) => {
+            resolved.set(design.id, {
+                id: design.id,
+                template: key,
+                templateLabel,
+                designIndex: position + 1,
+                designLabel: design.designLabel,
+                // A later design of a template that names no design_label keeps its own
+                // label rather than repeating the template's (theme-check rejects it).
+                label: ordered.length > 1 && !design.designLabel ? design.label ?? templateLabel : composeLabel(templateLabel, design.designLabel, ordered.length),
+                for: [...templateFor],
+                description: design.description,
+            });
+        });
+    }
+    return declared.map((design) => resolved.get(design.id));
+}
+/** Designs grouped into templates: the main template (demo.json's) first, each template's design 1 first. */
+export function groupTemplates(designs) {
+    const groups = new Map();
+    const main = designs.find((design) => design.id === PRIMARY_DESIGN_ID);
+    if (main)
+        groups.set(main.template, []);
+    for (const design of designs)
+        groups.set(design.template, [...(groups.get(design.template) ?? []), design]);
+    return [...groups].map(([key, members]) => {
+        const ordered = [...members].sort((a, b) => a.designIndex - b.designIndex);
+        return { key, label: ordered[0].templateLabel, for: [...ordered[0].for], designs: ordered };
+    });
+}
+/** The main template's key (`default_demo.template`), or null when it declares none. */
+export function mainTemplateKey(config) {
+    return templateKey(config?.default_demo?.template);
+}
+/** The theme's entry in themes/design-index.json. */
+export function designIndexEntry(config) {
+    return {
+        main: mainTemplateKey(config),
+        templates: groupTemplates(designsOf(config)).map((template) => ({
+            key: template.key,
+            label: template.label,
+            designs: template.designs.map((design) => ({ id: design.id, label: design.designLabel ?? design.label })),
+        })),
+    };
+}
+/**
+ * Does `/<slug>` open the template gallery? Only for a theme with two or more
+ * templates and a main key to move the main store to (`/<slug>~<main>`). A
+ * single-template theme keeps `/<slug>` as its store.
+ */
+export function hasGallery(theme) {
+    return theme.main !== null && theme.templates.length >= 2;
+}
+/**
+ * The preview segment of a design: `medley~food-2`. demo.json's is the bare
+ * slug, unless the theme has a gallery there: then it is `<slug>~<main key>`.
+ */
+export function designParam(slug, id, main, gallery) {
+    if (id !== PRIMARY_DESIGN_ID)
+        return `${slug}${DESIGN_SEPARATOR}${id}`;
+    return gallery && main !== null ? `${slug}${DESIGN_SEPARATOR}${main}` : slug;
+}
+/**
+ * The design a preview segment's `~<segment>` names, or null for none: the
+ * inverse of designParam. The main key is demo.json (`default`) on a gallery
+ * theme; any other design id is itself. `default` is never a segment (one URL
+ * per design), and a single-template theme's key is none either: its store
+ * stays at the bare slug.
+ */
+export function designOfSegment(theme, segment) {
+    if (hasGallery(theme) && segment === theme.main)
+        return PRIMARY_DESIGN_ID;
+    if (segment === PRIMARY_DESIGN_ID)
+        return null;
+    return theme.templates.some((template) => template.designs.some((design) => design.id === segment)) ? segment : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-check",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "The rules a Queek storefront theme is checked against, as a library.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./designs": {
+      "types": "./dist/utils/theme-designs.d.ts",
+      "default": "./dist/utils/theme-designs.js"
     }
   },
   "files": [