@usequeek/theme-check 0.1.0 → 0.2.0

package/dist/context.js

@@ -71,6 +71,7 @@ export async function loadContext(themeDir, env = {}) {
         declaredDemos: config === null ? null : Array.isArray(declared) ? declared : [],
         defaultDescription: typeof primary?.description === 'string' ? primary.description : null,
         defaultFor: primary?.for ?? null,
+        themeDescription: typeof config?.description === 'string' ? config.description : null,
         manifest,
         pageBased: PAGE_BLOCK_SCOPES.some((scope) => (variants[scope] ?? []).length > 0),
         file,

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { checkTheme, rejects, RULES, AT_SUBMISSION, type CheckOptions, type Chec
 export { loadContext, localEnv, CONTRACT_URL } from './context.js';
 export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf, type Level, type Summary } from './format.js';
 export type { CheckEnv, Finding, Rule, Severity, ThemeContext, DemoStore, DeclaredDemo } from './types.js';
-export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
+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 { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';

package/dist/index.js

@@ -6,6 +6,7 @@
 export { checkTheme, rejects, RULES, AT_SUBMISSION } from './run.js';
 export { loadContext, localEnv, CONTRACT_URL } from './context.js';
 export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf } from './format.js';
-export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
+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 { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';

package/dist/rules/static.d.ts

@@ -38,4 +38,20 @@ export declare const templateVersionsRule: Rule;
 /** The designed pages every template ships (contract R2.3); versions `-2`… count. */
 export declare const TEMPLATE_PAGES: readonly ["about", "sales", "landing"];
 export declare const templatePagesRule: Rule;
+export declare const templateCopyRule: Rule;
+/**
+ * Where a vendor's own fact is shown with words of the theme's for when the
+ * vendor has none — `vendor.address ?? 'Lagos, Nigeria'`, `tagline || 'Quiet
+ * luxury…'`, `brandTagline ? … : <p>Refined wardrobe…</p>` (through a variable
+ * assigned from the fact). A store without one would show those words as its own.
+ */
+export declare function vendorFactFallbacks(source: string): Array<{
+    fact: string;
+    words: string;
+}>;
+export declare const vendorFactsRule: Rule;
+export declare const fontsSelfHostedRule: Rule;
+/** The starter's own demo photos, rehosted under themes/_bare — never a real theme's. */
+export declare const STARTER_PLACEHOLDER_IMAGES: readonly string[];
+export declare const placeholderContentRule: Rule;
 export declare const STATIC_RULES: Rule[];

package/dist/rules/static.js

@@ -2,8 +2,9 @@ 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 { SCREENSHOT_LOCK, TEMPLATE_DESCRIPTION_MAX, TEMPLATE_DESCRIPTION_PLACEHOLDER, isPresentationalField, screenshotFile, screenshotUrl } from '../utils/theme-templates.js';
-import { BUSINESS_KEYS, isBusinessKey } from '../utils/business-vocabulary.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';
 import { themeSourceFiles } from '../context.js';
 import { finding } from '../types.js';
 const REQUIRED_FILES = [
@@ -151,7 +152,7 @@ export const demoStoresRule = {
                 add(at, `demos[] "${id}" has no label`, 'Give it the name a merchant sees, e.g. "Restaurant & takeaway".');
             }
             if (!Array.isArray(demo.for) || demo.for.length === 0 || demo.for.some((v) => typeof v !== 'string' || v.trim() === '')) {
-                add(at, `demos[] "${id}" has no \`for\` business list`, `List the businesses this store is for, most specific first, from ${context.env.vocabulary} (service slugs like "foods", catalogue keys like "wigs-extensions-hair-accessories"). The backend offers it to matching vendors.`);
+                add(at, `demos[] "${id}" has no \`for\` business list`, `List the businesses this store is for — its business category first (or, for a niche, only catalogue keys) — from ${context.env.vocabulary} (service slugs like "foods", catalogue keys like "wigs-extensions-hair-accessories"). The backend offers it to matching vendors.`);
             }
         }
         for (const store of secondaries) {
@@ -831,12 +832,26 @@ export const templateBusinessRule = {
                 continue;
             }
             const unknown = keys.filter((key) => typeof key !== 'string' || !isBusinessKey(key));
-            if (unknown.length === 0)
+            if (unknown.length === 0) {
+                // R2.7: the backend matches the business category a merchant picked at setup
+                // first. A general template leads with its category; a niche one (hair, shoes,
+                // jewellery) names none, or it competes as a general template.
+                const named = keys.filter((key) => SERVICE_SLUGS.includes(key));
+                if (named.length > 0 && !SERVICE_SLUGS.includes(keys[0])) {
+                    const general = [...named, ...keys.filter((key) => !named.includes(key))];
+                    findings.push(finding(context, 'theme/template-business', 'reject', {
+                        where,
+                        found: `template "${id}" names the business category ${named.map((key) => JSON.stringify(key)).join(', ')} but leads with ${JSON.stringify(keys[0])}`,
+                        fix: `A template for a whole business leads with its category: ${JSON.stringify(general)}. A template for one kind of product (hair, shoes, jewellery, coffee) names only its catalogue keys — drop ${named.map((key) => JSON.stringify(key)).join(', ')}.`,
+                        docs: `${context.env.docs}#templates`,
+                    }));
+                }
                 continue;
+            }
             findings.push(finding(context, 'theme/template-business', 'reject', {
                 where,
                 found: `template "${id}" is for ${unknown.map((key) => JSON.stringify(key)).join(', ')}, not in the business vocabulary`,
-                fix: `Use service slugs or catalogue keys from ${context.env.vocabulary} (${BUSINESS_KEYS.size} keys), most specific first. The backend matches vendors on these keys only; any other key matches no one.`,
+                fix: `Use service slugs or catalogue keys from ${context.env.vocabulary} (${BUSINESS_KEYS.size} keys): a whole business leads with its category, a niche names only catalogue keys. The backend matches vendors on these keys only; any other key matches no one.`,
                 docs: `${context.env.docs}#templates`,
             }));
         }
@@ -955,7 +970,251 @@ export const templatePagesRule = {
         return findings;
     },
 };
-export const STATIC_RULES = [moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule,
+/* ── Round 2.6: copy a real store can publish unchanged ───────────────── */
+/** Every string in a section's copy, with where it sits (`items[2].text`). */
+function copyStrings(value, path = '') {
+    if (typeof value === 'string')
+        return [[path, value]];
+    if (Array.isArray(value))
+        return value.flatMap((entry, i) => copyStrings(entry, `${path}[${i}]`));
+    if (value && typeof value === 'object')
+        return Object.entries(value).flatMap(([key, entry]) => copyStrings(entry, path ? `${path}.${key}` : key));
+    return [];
+}
+export const templateCopyRule = {
+    id: 'theme/template-copy',
+    summary: 'Template copy is true of any store in its business: no store name, place, naira amount, promise or founding date',
+    kind: 'static',
+    run(context) {
+        if (context.retired || !context.manifest)
+            return [];
+        const declared = declaredFieldsByVariant(context.manifest.variants);
+        const findings = [];
+        for (const store of context.demos) {
+            const name = store.data?.profile?.name;
+            for (const [pageKey, page] of Object.entries(pagesOf(store))) {
+                (page?.content ?? []).forEach((section, index) => {
+                    if (typeof section?.type !== 'string')
+                        return;
+                    const variant = section.variant ?? 'default';
+                    if (isTestimonialSection(section.type, variant, declared[section.type]?.[variant]))
+                        return;
+                    const lines = copyStrings(sectionCopy(section, declared) ?? {}).flatMap(([path, text]) => {
+                        const why = copyViolations(text, typeof name === 'string' ? name : null);
+                        return why.length > 0 ? [`${path}: ${why.join('; ')} — "${text.length > 80 ? `${text.slice(0, 77)}…` : text}"`] : [];
+                    });
+                    if (lines.length === 0)
+                        return;
+                    findings.push(finding(context, 'theme/template-copy', 'reject', {
+                        where: `${context.env.root}${store.file} → pages.${pageKey}.content[${index}] (${section.type}.${variant})`,
+                        found: lines.join('\n'),
+                        fix: 'The setup wizard publishes this copy onto real stores unchanged. Write it for any store in the business: the store\'s name becomes a role ("our kitchen", "the studio"), a place becomes generic ("across the city") or goes, and prices, delivery windows, guarantees and founding dates go — they are the vendor’s to state. Testimonials and reviews are exempt.',
+                        docs: `${context.env.docs}#templates`,
+                    }));
+                });
+            }
+        }
+        return findings;
+    },
+};
+/* ── BE8: a vendor's facts never fall back to the theme author's words ── */
+const VENDOR_FACTS = ['tagline', 'address', 'phone', 'email', 'description'];
+/** `vendor.tagline`, `store?.address`, `profile.phone`… */
+const FACT_REF = new RegExp(`\\b(?:vendor|store|profile)\\??\\.(${VENDOR_FACTS.join('|')})\\b`, 'g');
+/**
+ * The rest of the expression that starts at `from`: up to the `}`, `)` or `]`
+ * that closes it, or a `;`/`,` at its own depth — across lines, skipping
+ * strings. So `{vendor.tagline ?? ''}…{label || 'Visit us'}` stops at the
+ * first `}` and never reads the second expression as the first's fallback.
+ */
+function expressionAfter(source, from) {
+    let depth = 0;
+    let quote = null;
+    const end = Math.min(source.length, from + 400);
+    for (let i = from; i < end; i++) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`')
+            quote = ch;
+        else if ('([{'.includes(ch))
+            depth++;
+        else if (')]}'.includes(ch)) {
+            if (depth === 0)
+                return source.slice(from, i);
+            depth--;
+        }
+        else if ((ch === ';' || ch === ',') && depth === 0)
+            return source.slice(from, i);
+    }
+    return source.slice(from, end);
+}
+const WORDS = String.raw `([^'"\x60\n]*[^'"\x60\s][^'"\x60\n]*)`;
+/** `?? 'words'`, `|| 'words'` */
+const OR_WORDS = new RegExp(String.raw `(?:\?\?|\|\|)\s*(['"\x60])${WORDS}\1`);
+/** A ternary's other branch: `: 'words'` or `: <p>Words` */
+const ELSE_WORDS = new RegExp(String.raw `:\s*(?:(['"\x60])${WORDS}\1|<[a-z][\w.-]*[^>]*>\s*([A-Za-z][^<{]{2,}))`);
+/** A ternary `?` — not `?.` or `??`. */
+const TERNARY = /(?:^|[^?.])\?(?![?.])/;
+/**
+ * Where a vendor's own fact is shown with words of the theme's for when the
+ * vendor has none — `vendor.address ?? 'Lagos, Nigeria'`, `tagline || 'Quiet
+ * luxury…'`, `brandTagline ? … : <p>Refined wardrobe…</p>` (through a variable
+ * assigned from the fact). A store without one would show those words as its own.
+ */
+export function vendorFactFallbacks(source) {
+    const code = stripComments(source);
+    const found = new Map();
+    const check = (fact, rest) => {
+        const or = OR_WORDS.exec(rest);
+        const other = TERNARY.test(rest) ? ELSE_WORDS.exec(rest) : null;
+        const hit = or ?? other;
+        if (!hit)
+            return;
+        // `… ?? vendor.name ?? 'Our story'` never shows: every vendor has a name (backend, BE9).
+        if (/\b(?:vendor|store|profile)\??\.name\b/.test(rest.slice(0, hit.index)))
+            return;
+        const words = (hit[2] ?? hit[3] ?? '').trim();
+        if (words)
+            found.set(`${fact}:${words}`, { fact, words });
+    };
+    for (const match of code.matchAll(FACT_REF))
+        check(match[1], expressionAfter(code, match.index + match[0].length));
+    // Facts held in a variable: `const t = stripMarkdown(vendor.tagline ?? '') || 'Quiet luxury';`
+    // (the declaration itself), then every later `t ?? …` / `t ? … : …`.
+    const locals = [];
+    for (const match of code.matchAll(/\b(?:const|let)\s+(\w+)\s*=\s*([^;\n]*)/g)) {
+        const fact = VENDOR_FACTS.find((name) => new RegExp(`\\b(?:vendor|store|profile)\\??\\.${name}\\b`).test(match[2]));
+        if (!fact)
+            continue;
+        check(fact, match[2].slice(match[2].search(new RegExp(`\\.${fact}\\b`)) + fact.length + 1));
+        locals.push({ name: match[1], fact });
+    }
+    // `const { tagline, address: where } = vendor;`
+    for (const match of code.matchAll(/\b(?:const|let)\s*\{([^}]*)\}\s*=\s*(?:vendor|store|profile)\b/g)) {
+        for (const part of match[1].split(',')) {
+            const [key, alias] = part.split(':').map((text) => text.trim().split(/\s*=/)[0]);
+            if (VENDOR_FACTS.includes(key))
+                locals.push({ name: alias || key, fact: key });
+        }
+    }
+    for (const { name, fact } of locals) {
+        for (const use of code.matchAll(new RegExp(`(?<![.\\w])${name}\\b(?!\\s*[=:](?!=))`, 'g')))
+            check(fact, expressionAfter(code, use.index + use[0].length));
+    }
+    return [...found.values()];
+}
+export const vendorFactsRule = {
+    id: 'theme/vendor-facts',
+    summary: "A vendor's tagline, address, phone, email or description never falls back to the theme's own words",
+    kind: 'static',
+    run(context) {
+        if (context.retired)
+            return [];
+        const findings = [];
+        for (const path of themeSourceFiles(context.dir)) {
+            for (const { fact, words } of vendorFactFallbacks(readFileSync(path, 'utf8'))) {
+                findings.push(finding(context, 'theme/vendor-facts', 'reject', {
+                    where: relative(context.dir, path),
+                    found: `vendor.${fact} falls back to "${words}"`,
+                    fix: `A store with no ${fact} would show these words as its own. Render nothing when it is empty (\`vendor.${fact} ?? ''\`, or leave the element out).`,
+                    docs: `${context.env.docs}#component-rules`,
+                }));
+            }
+        }
+        return findings;
+    },
+};
+/* ── Fonts ship as files in the theme (storefront 0d66ed0) ─────────────── */
+function themeCssFiles(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            return entry.name === 'node_modules' ? [] : themeCssFiles(full);
+        return entry.name.endsWith('.css') ? [full] : [];
+    });
+}
+export const fontsSelfHostedRule = {
+    id: 'theme/fonts-self-hosted',
+    summary: 'Theme fonts ship as files in the theme: next/font/google is rejected (it fails builds), a Google Fonts @import is flagged',
+    kind: 'static',
+    run(context) {
+        const findings = [];
+        const fix = `Put the font's .woff2 files in ${context.env.root}fonts/ and declare them in fonts/fonts.css with @font-face (font-display: swap), imported from layout.tsx — or use next/font/local, which reads a file in the repo. next/font/google downloads fonts DURING THE BUILD, and Google intermittently serves URLs Turbopack cannot parse, failing the build ("next/font/google queries have exactly one entry", vercel/next.js#99114).`;
+        for (const path of themeSourceFiles(context.dir)) {
+            const source = stripComments(readFileSync(path, 'utf8'));
+            if (/from\s+['"]next\/font\/google['"]/.test(source)) {
+                findings.push(finding(context, 'theme/fonts-self-hosted', 'reject', {
+                    where: relative(context.dir, path),
+                    found: 'imports next/font/google',
+                    fix,
+                    docs: `${context.env.docs}#fonts`,
+                }));
+            }
+        }
+        for (const path of themeCssFiles(context.dir)) {
+            const css = readFileSync(path, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+            if (/@import\s+(?:url\()?['"]?https?:\/\/fonts\.googleapis\.com/.test(css)) {
+                findings.push(finding(context, 'theme/fonts-self-hosted', 'warn', {
+                    where: relative(context.dir, path),
+                    found: 'loads a font with @import from fonts.googleapis.com',
+                    fix: `Either the bundler drops it (it only survives as the very first rule of the compiled stylesheet), so the font never loads, or it survives and every page load waits on an extra render-blocking request to Google before the text can paint. ${fix}`,
+                    docs: `${context.env.docs}#fonts`,
+                }));
+            }
+        }
+        return findings;
+    },
+};
+/** The starter's own demo photos, rehosted under themes/_bare — never a real theme's. */
+export const STARTER_PLACEHOLDER_IMAGES = [
+    'https://media.usequeek.com/theme-assets/_bare/0e21e31030533d79.jpg',
+    'https://media.usequeek.com/theme-assets/_bare/201b6247be904af4.jpg',
+    'https://media.usequeek.com/theme-assets/_bare/377756cea202d263.jpg',
+    'https://media.usequeek.com/theme-assets/_bare/57e4183c303aab31.jpg',
+    'https://media.usequeek.com/theme-assets/_bare/67913acc7ef19523.jpg',
+    'https://media.usequeek.com/theme-assets/_bare/cd48af92c911f8b6.jpg',
+];
+export const placeholderContentRule = {
+    id: 'theme/placeholder-content',
+    summary: "No demo store still carries the starter's placeholder products or photos, and the theme's description is its own",
+    kind: 'static',
+    run(context) {
+        if (context.retired)
+            return [];
+        const findings = [];
+        for (const store of context.demos) {
+            const products = (Array.isArray(store.data?.products) ? store.data.products : []);
+            const placeholders = products.filter((product) => typeof product.slug === 'string' && product.slug.startsWith('placeholder-')).length;
+            const text = JSON.stringify(store.data ?? {});
+            const photos = STARTER_PLACEHOLDER_IMAGES.filter((url) => text.includes(url)).length;
+            if (placeholders === 0 && photos === 0)
+                continue;
+            findings.push(finding(context, 'theme/placeholder-content', 'reject', {
+                where: `${context.env.root}${store.file}`,
+                found: [placeholders ? `${placeholders} placeholder product(s)` : '', photos ? `${photos} of the starter's photos` : ''].filter(Boolean).join(' and '),
+                fix: "Replace the starter's products and photos with your own for this business. Every theme's preview must look like itself; shared placeholder photos would make every theme's store look the same.",
+                docs: `${context.env.docs}#placeholder-content`,
+            }));
+        }
+        // The starter writes a placeholder theme description too; no template rule reads it.
+        if ((context.themeDescription?.trim() ?? '').startsWith(TEMPLATE_DESCRIPTION_PLACEHOLDER)) {
+            findings.push(finding(context, 'theme/placeholder-content', 'reject', {
+                where: `${context.env.root}theme.config.ts → description`,
+                found: "the theme's description is still the starter's placeholder",
+                fix: 'Write what this theme is, in one sentence. It is the first thing a merchant, and the AI choosing on their behalf, reads about it.',
+                docs: `${context.env.docs}#placeholder-content`,
+            }));
+        }
+        return findings;
+    },
+};
+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,
+    templateBusinessRule, templateVersionsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule,
 ];

package/dist/types.d.ts

@@ -112,6 +112,8 @@ export interface ThemeContext {
     defaultDescription: string | null;
     /** `default_demo.for` from theme.config.ts, unvalidated — the primary template's business. */
     defaultFor: unknown;
+    /** `description` from theme.config.ts — the theme's own, not a template's. */
+    themeDescription: string | null;
     manifest: ThemeManifest | null;
     /** Declares page-block variants, so the page-based structure applies. */
     pageBased: boolean;

package/dist/utils/business-vocabulary.d.ts

@@ -1,6 +1,8 @@
 export declare const SERVICE_SLUGS: readonly string[];
 export declare const CATALOGUE: Readonly<Record<string, readonly string[]>>;
+/** A branch's own children, a third level (`bags-accessories` → `jewelry`). */
+export declare const SUBCATEGORIES: Readonly<Record<string, readonly string[]>>;
 export declare const BUSINESS_KEYS: ReadonlySet<string>;
 export declare function isBusinessKey(key: string): boolean;
-/** A catalogue branch's root (`wigs-extensions-hair-accessories` → `beauty-personal-care`); any other key is its own. */
+/** A catalogue key's root (`wigs-extensions-hair-accessories` → `beauty-personal-care`, `jewelry` → `fashion`); any other key is its own. */
 export declare function businessRoot(key: string): string;

package/dist/utils/business-vocabulary.js

@@ -7,12 +7,18 @@
 import vocabulary from './business-vocabulary.json' with { type: 'json' };
 export const SERVICE_SLUGS = vocabulary.services;
 export const CATALOGUE = vocabulary.catalogue;
+/** A branch's own children, a third level (`bags-accessories` → `jewelry`). */
+export const SUBCATEGORIES = vocabulary.subcategories;
 const ROOT_OF = new Map(Object.entries(CATALOGUE).flatMap(([root, branches]) => [[root, root], ...branches.map((branch) => [branch, root])]));
+for (const [branch, children] of Object.entries(SUBCATEGORIES)) {
+    for (const child of children)
+        ROOT_OF.set(child, ROOT_OF.get(branch) ?? branch);
+}
 export const BUSINESS_KEYS = new Set([...SERVICE_SLUGS, ...ROOT_OF.keys()]);
 export function isBusinessKey(key) {
     return BUSINESS_KEYS.has(key);
 }
-/** A catalogue branch's root (`wigs-extensions-hair-accessories` → `beauty-personal-care`); any other key is its own. */
+/** A catalogue key's root (`wigs-extensions-hair-accessories` → `beauty-personal-care`, `jewelry` → `fashion`); any other key is its own. */
 export function businessRoot(key) {
     return ROOT_OF.get(key) ?? key;
 }

package/dist/utils/business-vocabulary.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "The only keys a template's `for` may use (theme.config.ts default_demo.for / demos[].for). `services` are the slugs a vendor registers as; `catalogue` is the marketplace product taxonomy, root -> branches, each key the Str::slug of the category name. The backend reads a vendor's business from what they actually sell and ranks a specific (branch) match above a broad one. Agreed with queek_backend 24/9/26 (storefront-theme-templates-contract.md, R2.1); change it only together with the backend.",
+  "$comment": "The only keys a template's `for` may use (theme.config.ts default_demo.for / demos[].for). `services` are the slugs a vendor registers as; `catalogue` is the marketplace product taxonomy, root -> branches, and `subcategories` a branch -> its own children; each key is the Str::slug of the category name. The backend reads a vendor's business from what they actually sell and ranks a specific (branch) match above a broad one. Agreed with queek_backend 24/9/26 (storefront-theme-templates-contract.md, R2.1; jewelry and beverages R2.5); change it only together with the backend.",
   "services": [
     "foods", "local-meals", "shawarma-pizza-snacks", "suya", "boli", "fruits-fresh-natural",
     "meat-fish", "supermarket", "groceries", "shop-groceries", "local-market", "pharmacy",
@@ -15,6 +15,10 @@
     "home-living": ["furniture", "home-decor", "kitchen-dining", "bedding-bath", "lighting-electrical", "storage-organization"],
     "baby-kids": ["baby-gear", "feeding-nursing", "diapering-potty", "baby-clothing", "kids-clothing", "toys-games", "school-essentials", "nursery-safety"],
     "health-wellness": ["vitamins-supplements", "personal-care-hygiene", "fitness-recovery", "sexual-wellness", "medical-supplies", "health-devices", "healthy-living"],
-    "office-school": ["stationery-writing", "office-supplies", "school-supplies", "bags-lunch-gear", "office-furniture", "printers-accessories", "tech-for-school-office"]
+    "office-school": ["stationery-writing", "office-supplies", "school-supplies", "bags-lunch-gear", "office-furniture", "printers-accessories", "tech-for-school-office"],
+    "supermarket": ["beverages"]
+  },
+  "subcategories": {
+    "bags-accessories": ["jewelry"]
   }
 }

package/dist/utils/template-copy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What a template's `copy` may not say (queek_backend contract R2.6).
+ *
+ * The merchant setup wizard publishes a template's homepage onto a real store
+ * without rewriting it, so its copy must be true of ANY store in that business:
+ * no demo store name ("…at Mama Tee's"), no place ("delivered across Lekki"),
+ * no naira amount ("free delivery over ₦5,000"), no offer or coupon code, no
+ * opening hours, no promise only the vendor can make (a delivery window, a
+ * return period, a guarantee), no founding date or store age, and no email or
+ * phone number. Testimonials and reviews are exempt; the backend never places
+ * their copy on a real store.
+ *
+ * Each pattern is shaped by what it must NOT catch as much as what it must: a
+ * review ran real demo lines through it (24/9/26) — "Cold brewed for 12–24
+ * hours" is process, "Delivered in 2 hours" is a promise; "London Dry gin" is a
+ * style, "Made in Lagos" is a place. tests/theme-templates.test.ts holds both lists.
+ */
+/**
+ * Places the demo copy named when it was measured (24/9/26), plus the rest of
+ * the country's big cities and Lagos and Abuja districts a new template is
+ * likely to reach for. Matched case-sensitively as whole words, so "the island"
+ * or "delta" in a sentence are not places. Left out on purpose: "Ankara" (in
+ * this copy it is the fabric) and cities that name product styles — London Dry
+ * gin, New York cheesecake, Dubai chocolate, Milan and Florence cuts.
+ */
+export declare const TEMPLATE_COPY_PLACES: readonly string[];
+/**
+ * The forms of a store's name that copy would use: the full name, without a
+ * leading "The", without the generic words it ends in ("Mama Tee's Buka" →
+ * "Mama Tee"), and each in capitals. A name that is nothing but generic words
+ * ("Fashion House") keeps only its full form — "Fashion" alone is the business.
+ */
+export declare function storeNameForms(name: string | null | undefined): string[];
+/** Why one copy string could not go live on another store unchanged; empty when it can. */
+export declare function copyViolations(text: string, storeName: string | null | undefined): string[];
+/**
+ * Testimonials and reviews, as the backend reads them (R2.6.3): a variant
+ * whose id or section type names them, or whose items declare quote, author or
+ * rating. Their copy is never placed on a real store, so the demo keeps it.
+ */
+export declare function isTestimonialSection(type: string, variant: string, fields: Record<string, unknown> | undefined): boolean;

package/dist/utils/template-copy.js

@@ -0,0 +1,190 @@
+/**
+ * What a template's `copy` may not say (queek_backend contract R2.6).
+ *
+ * The merchant setup wizard publishes a template's homepage onto a real store
+ * without rewriting it, so its copy must be true of ANY store in that business:
+ * no demo store name ("…at Mama Tee's"), no place ("delivered across Lekki"),
+ * no naira amount ("free delivery over ₦5,000"), no offer or coupon code, no
+ * opening hours, no promise only the vendor can make (a delivery window, a
+ * return period, a guarantee), no founding date or store age, and no email or
+ * phone number. Testimonials and reviews are exempt; the backend never places
+ * their copy on a real store.
+ *
+ * Each pattern is shaped by what it must NOT catch as much as what it must: a
+ * review ran real demo lines through it (24/9/26) — "Cold brewed for 12–24
+ * hours" is process, "Delivered in 2 hours" is a promise; "London Dry gin" is a
+ * style, "Made in Lagos" is a place. tests/theme-templates.test.ts holds both lists.
+ */
+/**
+ * Places the demo copy named when it was measured (24/9/26), plus the rest of
+ * the country's big cities and Lagos and Abuja districts a new template is
+ * likely to reach for. Matched case-sensitively as whole words, so "the island"
+ * or "delta" in a sentence are not places. Left out on purpose: "Ankara" (in
+ * this copy it is the fabric) and cities that name product styles — London Dry
+ * gin, New York cheesecake, Dubai chocolate, Milan and Florence cuts.
+ */
+export const TEMPLATE_COPY_PLACES = [
+    // Nigeria, its states and big cities
+    'Nigeria', 'Lagos', 'Abuja', 'Port Harcourt', 'Ibadan', 'Kano', 'Kaduna', 'Enugu', 'Benin City', 'Abeokuta',
+    'Owerri', 'Uyo', 'Calabar', 'Jos', 'Warri', 'Asaba', 'Onitsha', 'Aba', 'Ilorin', 'Akure', 'Osogbo', 'Ile-Ife',
+    'Sokoto', 'Maiduguri', 'Kwara', 'Ogun', 'Oyo', 'Anambra', 'Akwa Ibom', 'Cross River', 'Bayelsa', 'Ekiti', 'Ondo',
+    'Osun', 'Kogi', 'Benue', 'Katsina', 'Bauchi', 'Gombe', 'Borno', 'Adamawa', 'Taraba', 'Nasarawa', 'Zamfara',
+    'Kebbi', 'Jigawa', 'Ebonyi', 'Delta State', 'Rivers State', 'Plateau State', 'Niger State', 'Imo State', 'Edo State',
+    // Lagos
+    'Lekki', 'Ikoyi', 'Victoria Island', 'VI', 'Lagos Island', 'Banana Island', 'Eko Atlantic', 'Eko', 'Oniru', 'Ajah',
+    'Sangotedo', 'Yaba', 'Surulere', 'Ikeja', 'Computer Village', 'GRA', 'Maryland', 'Magodo', 'Gbagada', 'Ogudu',
+    'Ojodu', 'Ojota', 'Ketu', 'Agege', 'Isolo', 'Oshodi', 'Mushin', 'Ikorodu', 'Epe', 'Badagry', 'Festac', 'Apapa',
+    'Obalende', 'Ebute Metta', 'Ebute-Metta', 'Idumota', 'Balogun', 'Marina', 'Ilupeju', 'Opebi', 'Oregun',
+    'Allen Avenue', 'Admiralty Way', 'Awolowo Road', 'Odeku Street', 'Akoka', 'Bariga', 'Shomolu', 'Ogba', 'Omole',
+    'Ikota', 'Osapa', 'Chevron Drive',
+    // Abuja and Port Harcourt
+    'Wuse', 'Maitama', 'Garki', 'Asokoro', 'Gwarinpa', 'Jabi', 'Utako', 'Kubwa', 'Lugbe', 'Katampe', 'Guzape',
+    'Trans-Amadi', 'Rumuola',
+    // Abroad, as the demo stores claimed origins
+    'Accra', 'Nairobi', 'Johannesburg', 'Birmingham', 'Paris', 'Italy', 'France', 'Japan', 'China', 'Tokyo', 'Jaipur',
+    'Istanbul', 'Guangzhou',
+];
+/**
+ * Words a store name ends in that say what it is, not who: stripped to find
+ * the name a copy line would use ("Bloom Bakehouse" → "Bloom").
+ */
+const GENERIC_NAME_WORDS = new Set([
+    'co', 'co.', 'company', 'ltd', 'limited', 'enterprises', 'ventures', 'global', 'supply', 'house', 'kitchen',
+    'studio', 'studios', 'bakehouse', 'bakery', 'grillhouse', 'grill', 'buka', 'cafe', 'café', 'coffee', 'roasters',
+    'lagos', 'skin', 'skincare', 'cosmetics', 'beauty', 'hair', 'wigs', 'salon', 'fine', 'jewellery', 'jewelry',
+    'fashion', 'occasion', 'tailoring', 'couture', 'wear', 'shoes', 'sneakers', 'store', 'stores', 'shop', 'mart',
+    'boutique', 'collective', 'hub', 'foods', 'food', 'laundry', 'laundromat', 'pharmacy',
+]);
+/**
+ * The forms of a store's name that copy would use: the full name, without a
+ * leading "The", without the generic words it ends in ("Mama Tee's Buka" →
+ * "Mama Tee"), and each in capitals. A name that is nothing but generic words
+ * ("Fashion House") keeps only its full form — "Fashion" alone is the business.
+ */
+export function storeNameForms(name) {
+    const full = (name ?? '').trim();
+    if (!full)
+        return [];
+    const bare = full.replace(/^The\s+/, '');
+    const forms = new Set([full, bare]);
+    const words = bare.split(/\s+/);
+    while (words.length > 1 && GENERIC_NAME_WORDS.has(words[words.length - 1].toLowerCase()))
+        words.pop();
+    const core = words.join(' ').replace(/['’]s$/, '');
+    const allGeneric = words.every((word) => GENERIC_NAME_WORDS.has(word.toLowerCase().replace(/['’]s$/, '')));
+    if (core.length >= 3 && !allGeneric)
+        forms.add(core);
+    for (const form of [...forms])
+        forms.add(form.toUpperCase());
+    return [...forms];
+}
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** A whole word or phrase, case-sensitive: letters on either side make it part of another word. */
+const wordPattern = (phrase) => new RegExp(`(?<![\\p{L}\\p{N}])${escape(phrase)}(?![\\p{L}\\p{N}])`, 'u');
+/** "VI" is Victoria Island — unless it numbers something ("Collection VI"). */
+const ROMAN_CONTEXT = '(?<!(?:Collection|Volume|Vol\\.|Part|Chapter|Edition|Series|Season|Phase|No\\.|Act|Book) )';
+const PLACE_PATTERNS = TEMPLATE_COPY_PLACES.map((place) => [
+    place,
+    place === 'VI' ? new RegExp(`${ROMAN_CONTEXT}(?<![\\p{L}\\p{N}])VI(?![\\p{L}\\p{N}])`, 'u') : wordPattern(place),
+]);
+/** ₦5,000 · NGN 5000 · N5,000 · N5000 · 5,000 naira — any naira amount. */
+const NAIRA_AMOUNT = [
+    /₦\s?\d|\bNGN\s?\d/,
+    /(?<![\p{L}\p{N}])N\d{1,3}(,\d{3})+(?![\p{N}])|(?<![\p{L}\p{N}])N\d{3,}(?![\p{L}\p{N}])/u,
+    /\d[\d,.]*\s?k?\s?naira\b/i,
+];
+/** A discount or a coupon code: "Save 20% with code RAINS20", "Up to 25% off". */
+const OFFER = [
+    /\b(?:code|coupon|promo(?: code)?)\s*:?\s*[A-Z][A-Z0-9]{3,}\b/,
+    /\b\d{1,3}\s?%\s?(?:off|discount)\b|\bsave\s+(?:up to\s+)?\d{1,3}\s?%|\bup to\s+\d{1,3}\s?%/i,
+];
+/**
+ * Opening hours: "Open daily", "11am–10pm", "Doors open 11am", "from 6 AM",
+ * "till 11 PM", "08:00–19:00". A time on its own is not hours ("Glow before
+ * 8am", "trace your feet after 6pm").
+ */
+const TIME = String.raw `\d{1,2}(?::\d{2})?\s?(?:am|pm)\b`;
+const HOURS = new RegExp([
+    String.raw `\bopen\s+(?:daily|every\s+day|all\s+week|24\/7|early|late)\b`,
+    String.raw `\b\d{1,2}(?::\d{2})?\s?(?:am|pm)?\s?(?:–|-|to)\s?${TIME}`,
+    String.raw `\b(?:opens?|opening|doors|from|till|until|last\s+orders|closes?|closing)\s+(?:at\s+)?${TIME}`,
+    String.raw `\b(?:[01]?\d|2[0-3]):[0-5]\d\s?(?:–|-|to)\s?(?:[01]?\d|2[0-3]):[0-5]\d\b`,
+].join('|'), 'i');
+/**
+ * Commitments only the vendor can make. A time window is a promise only next
+ * to a service — delivered, ships, answered, fitted, returned — so a recipe's
+ * or a process's time ("marinated 24–48 hours", "ready in 3 minutes") is not.
+ */
+const SERVICE = String.raw `(?:deliver\w*|ship(?:s|ped|ping)?|dispatch\w*|arriv\w*|collect\w*|pick(?:ed|s)?[- ]?up|turnaround|answer\w*|repl(?:y|ies|ied)|respond\w*|install\w*|fit(?:ted|ting)?|resiz\w*|repair\w*|replace\w*|exchang\w*|return\w*|refund\w*)`;
+const WINDOW = String.raw `(?:(?:within|in|under)\s+(?:about\s+)?(?:\d+|an?|one|two|three|four)[\s-]?(?:min(?:ute)?s?|hours?|hrs?|days?|weeks?)|\d+\s*(?:–|-|to)\s*\d+[\s-]*(?:working\s+|business\s+)?(?:hours?|days?|weeks?)|(?:same|next)[- ](?:day|evening|morning))`;
+const PROMISE = [
+    new RegExp(String.raw `\b${SERVICE}\b[^.!?\n]{0,40}?${WINDOW}\b|${WINDOW}\b[^.!?\n]{0,40}?\b${SERVICE}\b`, 'i'),
+    /\b\d+[\s-](?:minute|min|hour|hr|day|week)s?\s+(?:delivery|dispatch|shipping|turnaround|returns?|exchanges?|refunds?|adjustments?|service)\b/i,
+    /\bfree\s+(?:\w+\s+)?(?:delivery|shipping|returns?|pick[- ]?up|collection|alterations?|installation|install|resizing|exchanges?)\b/i,
+    /\b(?:guarantee[ds]?|money[- ]back|warrant(?:y|ies)|no questions asked)\b/i,
+];
+/** The store's history, not the business's: "since 2014", "started in 2019", "six years, two stores". */
+const NUMBER = '(?:\\d+|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|fifteen|twenty)';
+const STORE_HISTORY = [
+    /\b(?:since|est\.?|established(?:\s+in)?)\s+(?:19|20)\d\d\b/i,
+    /\b(?:founded|started|opened|established|began)\b(?:\s+[\w’'-]+){0,6}?\s+in\s+(?:19|20)\d\d\b/i,
+    /\bin\s+(?:19|20)\d\d,?\s+(?:we|our|the\s+(?:shop|store|kitchen|studio|house|bakery))\b/i,
+    new RegExp(`\\b${NUMBER}\\s+years?(?:,|\\s+(?:on|later|ago|in\\s+business|of\\s+(?:experience|service|serving|trading)))`, 'i'),
+];
+/** The demo store's email or phone written into the words ("Email hello@zuri.ng", "wa.me/234…"). */
+const CONTACT = /[\w.+-]+@[\w-]+\.[a-z]{2,}|\+234[\s\d-]{6,}|\b0[789][01]\d(?:[\s-]?\d){7}\b|\bwa\.me\/\d+/i;
+const first = (patterns, text) => {
+    for (const pattern of patterns) {
+        const match = pattern.exec(text);
+        if (match)
+            return match[0];
+    }
+    return null;
+};
+/** Why one copy string could not go live on another store unchanged; empty when it can. */
+export function copyViolations(text, storeName) {
+    const found = [];
+    const name = storeNameForms(storeName).find((form) => wordPattern(form).test(text));
+    if (name)
+        found.push(`names the store ("${name}")`);
+    const places = PLACE_PATTERNS.filter(([, pattern]) => pattern.test(text)).map(([place]) => place);
+    if (places.length > 0)
+        found.push(`names ${places.length === 1 ? 'a place' : 'places'} (${places.join(', ')})`);
+    if (first(NAIRA_AMOUNT, text))
+        found.push('states a naira amount');
+    const offer = first(OFFER, text);
+    if (offer)
+        found.push(`states an offer ("${offer}")`);
+    const hours = HOURS.exec(text);
+    if (hours)
+        found.push(`states opening hours ("${hours[0]}")`);
+    const promise = first(PROMISE, text);
+    if (promise)
+        found.push(`makes a promise ("${promise}")`);
+    const history = first(STORE_HISTORY, text);
+    if (history)
+        found.push(`dates the store ("${history}")`);
+    const contact = CONTACT.exec(text);
+    if (contact)
+        found.push(`gives the store’s contact details ("${contact[0]}")`);
+    return found;
+}
+/** A section whose type or variant id is a testimonials/reviews one — whole words, so "preview" is not. */
+const TESTIMONIAL_NAME = /(?:^|[\s_-])(?:testimonials?|reviews?)(?:$|[\s_-])/i;
+/** Keys that make a list a set of customer quotes. */
+const TESTIMONIAL_KEYS = /\b(quote|author|rating)\b/;
+/**
+ * Testimonials and reviews, as the backend reads them (R2.6.3): a variant
+ * whose id or section type names them, or whose items declare quote, author or
+ * rating. Their copy is never placed on a real store, so the demo keeps it.
+ */
+export function isTestimonialSection(type, variant, fields) {
+    if (TESTIMONIAL_NAME.test(type) || TESTIMONIAL_NAME.test(variant))
+        return true;
+    return Object.values(fields ?? {}).some((spec) => {
+        if (typeof spec === 'string')
+            return TESTIMONIAL_KEYS.test(spec);
+        const of = spec && typeof spec === 'object' ? spec.of : undefined;
+        return !!of && typeof of === 'object' && Object.keys(of).some((key) => TESTIMONIAL_KEYS.test(key));
+    });
+}

package/dist/utils/theme-templates.js

@@ -163,8 +163,13 @@ const ENTRY_KEYS = /\[\{([^}\]]+)\}\]/;
  * hotspot coordinates, icons — belongs to the demo store, not the design.
  */
 const ENTRY_TEXT_KEYS = new Set(['title', 'subtitle', 'caption', 'text', 'heading', 'eyebrow', 'label', 'cta_label', 'question', 'answer', 'quote', 'author', 'name', 'role', 'body', 'description', 'content', 'kicker']);
-/** Links, references, prices, media, alt text (it describes one photo) and icon names are never copy, whatever their declared type. */
-const NOT_COPY = /(^|_)(url|link|href|slug|id|ids|price|amount|currency|video|image|icon|alt)$/;
+/**
+ * Links, references, prices, media, alt text (it describes one photo) and icon
+ * names are never copy, whatever their declared type. Nor are the demo store's
+ * own facts — its email, phone, address, opening hours and coupon code — or
+ * hotspot coordinates (`spots`): the vendor's profile supplies the facts.
+ */
+const NOT_COPY = /(^|_)(url|link|href|slug|id|ids|price|amount|currency|video|image|icon|alt|email|phone|whatsapp|address|hours|code|spots)$/;
 /** `[the balm](/products/balm)` → `the balm`: copy keeps a link's words, never where it pointed. */
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 function textOf(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-check",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The rules a Queek storefront theme is checked against, as a library.",
   "license": "MIT",
   "type": "module",