@usequeek/theme-check 0.4.0 → 0.5.0

package/dist/format.js

@@ -16,6 +16,7 @@ export function formatJson(result) {
     return JSON.stringify({
         theme: result.context.slug,
         summary: summarize(result.findings),
+        vocabulary: result.vocabulary,
         findings: result.findings.map((finding) => ({
             rule: finding.rule,
             level: levelOf(finding),

package/dist/index.d.ts

@@ -3,14 +3,15 @@
  * against, as a library. The `queek-theme check` command of
  * @usequeek/theme-cli is its command-line front end.
  */
-export { checkTheme, rejects, RULES, AT_SUBMISSION, type CheckOptions, type CheckResult } from './run.js';
+export { checkTheme, rejects, RULES, AT_SUBMISSION, type CheckOptions, type CheckResult, type CheckVocabulary } from './run.js';
+export { resolveVocabulary, vocabularyCacheDir, readCachedVocabulary, bundledVocabulary, bundledVersion, parseEndpointPayload, parseVocabularyData, VOCABULARY_URL, VOCABULARY_CACHE_TTL_MS, type BusinessVocabularyData, type ResolveVocabularyOptions, type ResolvedVocabulary, type VocabularySource, } from './vocabulary.js';
 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, SUBCATEGORIES, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
+export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, SUBCATEGORIES, ROOT_SERVICE, BUNDLED_VERSION, bundledVocabularyView, vocabularyViewOf, isBusinessKey, businessRoot, type VocabularyView } 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, templateDesignsRule, TEMPLATE_DESIGNS_MAX, 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, compositionVariantsRule, 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

@@ -4,9 +4,10 @@
  * @usequeek/theme-cli is its command-line front end.
  */
 export { checkTheme, rejects, RULES, AT_SUBMISSION } from './run.js';
+export { resolveVocabulary, vocabularyCacheDir, readCachedVocabulary, bundledVocabulary, bundledVersion, parseEndpointPayload, parseVocabularyData, VOCABULARY_URL, VOCABULARY_CACHE_TTL_MS, } from './vocabulary.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, SUBCATEGORIES, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
+export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, SUBCATEGORIES, ROOT_SERVICE, BUNDLED_VERSION, bundledVocabularyView, vocabularyViewOf, 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
@@ -16,5 +17,5 @@ export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, de
 // 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, templateDesignsRule, TEMPLATE_DESIGNS_MAX, 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, compositionVariantsRule, 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

@@ -32,6 +32,17 @@ export declare const selectionMetadataRule: Rule;
 export declare const demoCompletenessRule: Rule;
 export declare const subscribeScopeRule: Rule;
 export declare const demoBlockTypesRule: Rule;
+/**
+ * A composition's variants are ones the theme implements (backend BE19: every
+ * beaurify store's blog named gallery/grid, which beaurify does not implement,
+ * and the backend refused three templates over it). "Implemented" is the
+ * registry's `implemented_variants`: the manifest's declared variants per
+ * scope — theme/variant-parity enforces they match the theme's
+ * `variantImplementations` map 1:1, so the manifest list is the implemented
+ * set. A separate id from theme/demo-block-types: that rule owns type names
+ * against core's list, this one variant ids against the theme's own.
+ */
+export declare const compositionVariantsRule: Rule;
 export declare const identityRule: Rule;
 export declare const productMetafieldsRule: Rule;
 export declare const poweredByRule: Rule;

package/dist/rules/static.js

@@ -5,7 +5,7 @@ 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';
+import { bundledVocabularyView } from '../utils/business-vocabulary.js';
 import { themeSourceFiles } from '../context.js';
 import { finding } from '../types.js';
 /** A theme file as a finding names it: relative to the theme, with `/` on every OS (Windows gave `styles\type.css`). */
@@ -550,6 +550,58 @@ export const demoBlockTypesRule = {
         return findings;
     },
 };
+/**
+ * A composition's variants are ones the theme implements (backend BE19: every
+ * beaurify store's blog named gallery/grid, which beaurify does not implement,
+ * and the backend refused three templates over it). "Implemented" is the
+ * registry's `implemented_variants`: the manifest's declared variants per
+ * scope — theme/variant-parity enforces they match the theme's
+ * `variantImplementations` map 1:1, so the manifest list is the implemented
+ * set. A separate id from theme/demo-block-types: that rule owns type names
+ * against core's list, this one variant ids against the theme's own.
+ */
+export const compositionVariantsRule = {
+    id: 'theme/composition-variants',
+    summary: 'Every section names a variant its theme implements',
+    kind: 'static',
+    run(context) {
+        if (context.retired || !context.manifest)
+            return [];
+        const declared = context.manifest.variants ?? {};
+        const implemented = new Map();
+        for (const [scope, list] of Object.entries(declared)) {
+            if (Array.isArray(list))
+                implemented.set(scope, list.map((variant) => String(variant?.id)));
+        }
+        const findings = [];
+        for (const store of context.demos) {
+            if (!store.data)
+                continue;
+            const pages = store.data.pages ?? {};
+            const list = Array.isArray(pages)
+                ? pages
+                : Object.entries(pages).map(([slug, page]) => ({ slug, ...page }));
+            for (const page of list) {
+                (page?.content ?? []).forEach((section, index) => {
+                    const type = section?.type;
+                    const variant = section?.variant;
+                    if (typeof type !== 'string' || typeof variant !== 'string' || variant === '')
+                        return;
+                    const ids = implemented.get(type);
+                    if (!ids || ids.includes(variant))
+                        return;
+                    findings.push(finding(context, 'theme/composition-variants', 'reject', {
+                        where: `${context.env.root}${store.file} → pages.${page.slug ?? '?'}[${index}]`,
+                        found: `${type}/${variant}`,
+                        fix: `${type}/${variant} is not a ${type} variant ${context.slug} implements (one of: ${ids.join(', ') || 'none'}). A store built from this page carries the section verbatim; a variant the theme cannot render comes out blank.`,
+                        docs: `${context.env.docs}#manifest`,
+                    }));
+                });
+            }
+        }
+        return findings;
+    },
+};
 export const identityRule = {
     id: 'theme/identity',
     summary: 'manifest, config, demo and directory all agree on the slug',
@@ -860,6 +912,10 @@ export const templateBusinessRule = {
     run(context) {
         if (context.retired || context.declaredDemos === null)
             return [];
+        // The resolved vocabulary on the context (checkTheme puts it there:
+        // bundled unless a live, cached or pinned copy was passed), never the
+        // module-level bundled import — hand-built contexts fall back to bundled.
+        const vocabulary = context.vocabulary ?? bundledVocabularyView;
         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.
@@ -882,13 +938,13 @@ export const templateBusinessRule = {
                 }));
                 continue;
             }
-            const unknown = keys.filter((key) => typeof key !== 'string' || !isBusinessKey(key));
+            const unknown = keys.filter((key) => typeof key !== 'string' || !vocabulary.isBusinessKey(key));
             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 named = keys.filter((key) => vocabulary.services.includes(key));
+                if (named.length > 0 && !vocabulary.services.includes(keys[0])) {
                     const general = [...named, ...keys.filter((key) => !named.includes(key))];
                     findings.push(finding(context, 'theme/template-business', 'reject', {
                         where,
@@ -897,12 +953,24 @@ export const templateBusinessRule = {
                         docs: `${context.env.docs}#templates`,
                     }));
                 }
+                // R2.9: `shop` is for a general store only. A template dressed as a
+                // specific business that names only `shop` matches every general store
+                // and no one in particular — advisory (warn), never a reject, so the
+                // starter and existing general themes keep passing.
+                if (keys.length === 1 && keys[0] === 'shop') {
+                    findings.push(finding(context, 'theme/template-business', 'warn', {
+                        where,
+                        found: `template "${id}" is for only "shop"`,
+                        fix: 'Name the specific business this template serves in `for` (its business category first) — "shop" is for a general store only.',
+                        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): 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.`,
+                fix: `Use service slugs or catalogue keys from ${context.env.vocabulary} (${vocabulary.businessKeys.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`,
             }));
         }
@@ -1135,6 +1203,20 @@ export const templateCopyRule = {
         const findings = [];
         for (const store of context.demos) {
             const name = store.data?.profile?.name;
+            // The header announcement is copied onto real stores like section copy,
+            // whether the bar is enabled or not — so it reads by the same rules.
+            const announcement = store.data?.config?.header?.announcement?.text;
+            if (typeof announcement === 'string' && announcement !== '') {
+                const why = copyViolations(announcement, typeof name === 'string' ? name : null);
+                if (why.length > 0) {
+                    findings.push(finding(context, 'theme/template-copy', 'reject', {
+                        where: `${context.env.root}${store.file} → config.header.announcement.text`,
+                        found: `text: ${why.join('; ')} — "${announcement.length > 80 ? `${announcement.slice(0, 77)}…` : announcement}"`,
+                        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`,
+                    }));
+                }
+            }
             for (const [pageKey, page] of Object.entries(pagesOf(store))) {
                 (page?.content ?? []).forEach((section, index) => {
                     if (typeof section?.type !== 'string')
@@ -1361,7 +1443,7 @@ export const placeholderContentRule = {
         return findings;
     },
 };
-export const STATIC_RULES = [moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule,
+export const STATIC_RULES = [moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, compositionVariantsRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule,
     templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule,
     templateBusinessRule, templateVersionsRule, templateDesignsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule,
 ];

package/dist/run.d.ts

@@ -1,4 +1,5 @@
 import type { CheckEnv, Finding, Rule, ThemeContext } from './types.js';
+import type { BusinessVocabularyData, VocabularySource } from './vocabulary.js';
 /** Every rule that runs on a developer's machine, in the order they report. */
 export declare const RULES: Rule[];
 /**
@@ -10,15 +11,27 @@ export declare const AT_SUBMISSION: ReadonlyArray<{
     id: string;
     summary: string;
 }>;
+/** The vocabulary a check runs against: resolved data plus where it came from (for `check --json`). */
+export interface CheckVocabulary {
+    data: BusinessVocabularyData;
+    /** Where the data came from. Defaults to bundled for bundled data, else file. */
+    source?: VocabularySource;
+}
 export interface CheckOptions {
     /** Override how findings name files and where they link (see CheckEnv). */
     env?: Partial<CheckEnv>;
     /** Run only these rule ids. */
     only?: string[];
+    /** The vocabulary the rules read from the context. Default: the bundled snapshot, so existing callers keep working. */
+    vocabulary?: CheckVocabulary;
 }
 export interface CheckResult {
     context: ThemeContext;
     findings: Finding[];
+    vocabulary: {
+        source: VocabularySource;
+        version: string;
+    };
 }
 /** Every finding for the theme in `themeDir`. No `reject` finding means it will pass these checks on submission. */
 export declare function checkTheme(themeDir: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/run.js

@@ -1,6 +1,7 @@
 import { loadContext } from './context.js';
 import { ANALYSIS_RULES } from './rules/analysis.js';
 import { STATIC_RULES } from './rules/static.js';
+import { bundledVocabularyView, vocabularyViewOf } from './utils/business-vocabulary.js';
 /** Every rule that runs on a developer's machine, in the order they report. */
 export const RULES = [...STATIC_RULES, ...ANALYSIS_RULES];
 /**
@@ -18,6 +19,11 @@ export const AT_SUBMISSION = [
 /** Every finding for the theme in `themeDir`. No `reject` finding means it will pass these checks on submission. */
 export async function checkTheme(themeDir, options = {}) {
     const context = await loadContext(themeDir, options.env);
+    const view = options.vocabulary
+        ? vocabularyViewOf(options.vocabulary.data)
+        : bundledVocabularyView;
+    const source = options.vocabulary?.source ?? (options.vocabulary ? 'file' : 'bundled');
+    context.vocabulary = view;
     const rules = RULES.filter((rule) => !options.only || options.only.includes(rule.id));
     const findings = [];
     for (const rule of rules) {
@@ -37,6 +43,6 @@ export async function checkTheme(themeDir, options = {}) {
             });
         }
     }
-    return { context, findings };
+    return { context, findings, vocabulary: { source, version: view.version } };
 }
 export const rejects = (findings) => findings.filter((finding) => finding.severity === 'reject');

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { VocabularyView } from './utils/business-vocabulary.js';
 /**
  * One definition of "is this theme valid", shared by three consumers: the
  * author's `yarn theme:check`, this repo's CI, and (later) the pull/publish
@@ -108,6 +109,8 @@ export interface CheckEnv {
 }
 export interface ThemeContext {
     env: CheckEnv;
+    /** The vocabulary the rules check `for` against. Set by checkTheme (bundled unless a vocabulary is passed); hand-built contexts fall back to bundled. */
+    vocabulary?: VocabularyView;
     slug: string;
     dir: string;
     /** `active: false` in theme.config.ts — retired, exempt from publish gates. */

package/dist/types.js

@@ -1,12 +1,3 @@
-/**
- * One definition of "is this theme valid", shared by three consumers: the
- * author's `yarn theme:check`, this repo's CI, and (later) the pull/publish
- * command. The moment validity has two implementations they drift, and an
- * author gets a green locally and a rejection here.
- *
- * Rules therefore live in this library and the tests assert over it — not the
- * other way round, which is where five of these gates started.
- */
 export function finding(context, rule, severity, parts) {
     return { rule, severity, theme: context.slug, ...parts };
 }

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

@@ -1,7 +1,28 @@
+import type { BusinessVocabularyData } from '../vocabulary.js';
+/** One vocabulary copy as the rules read it: sets plus the helpers. */
+export interface VocabularyView {
+    version: string;
+    services: readonly string[];
+    catalogue: Readonly<Record<string, readonly string[]>>;
+    subcategories: Readonly<Record<string, readonly string[]>>;
+    rootService: Readonly<Record<string, string>>;
+    labels: Readonly<Record<string, string>>;
+    businessKeys: ReadonlySet<string>;
+    isBusinessKey: (key: string) => boolean;
+    businessRoot: (key: string) => string;
+}
+/** Any vocabulary copy (resolved, bundled, pinned) as the rules read it. */
+export declare function vocabularyViewOf(data: BusinessVocabularyData): VocabularyView;
+/** The bundled snapshot as the rules read it: what `checkTheme` uses unless a vocabulary is passed. */
+export declare const bundledVocabularyView: VocabularyView;
 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[]>>;
+/** A catalogue root's business category where they differ (`phones-tablets` → `phones-accessories`). */
+export declare const ROOT_SERVICE: Readonly<Record<string, string>>;
+/** The bundled snapshot's version (the synced S1 snapshot). */
+export declare const BUNDLED_VERSION: string;
 export declare const BUSINESS_KEYS: ReadonlySet<string>;
 export declare function isBusinessKey(key: string): boolean;
 /** A catalogue key's root (`wigs-extensions-hair-accessories` → `beauty-personal-care`, `jewelry` → `fashion`); any other key is its own. */

package/dist/utils/business-vocabulary.js

@@ -3,22 +3,66 @@
  * the service slugs a vendor registers as, plus the marketplace catalogue's
  * roots and branches — what tells a wig seller from a makeup seller when both
  * register as beauty. Agreed with the backend; theme-check rejects any other key.
+ *
+ * The module-level sets describe the bundled snapshot (what offline callers
+ * and the storefront's offline tests check against). A resolved vocabulary —
+ * live, cache or file, via `resolveVocabulary()` — travels as a
+ * VocabularyView: `vocabularyViewOf(data)`, carried on the ThemeContext so
+ * rules never read the module-level import.
  */
 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);
+function rootsOf(data) {
+    const roots = new Map();
+    for (const [root, branches] of Object.entries(data.catalogue)) {
+        roots.set(root, root);
+        for (const branch of branches)
+            roots.set(branch, root);
+    }
+    for (const [branch, children] of Object.entries(data.subcategories)) {
+        for (const child of children)
+            roots.set(child, roots.get(branch) ?? branch);
+    }
+    return roots;
+}
+/** Any vocabulary copy (resolved, bundled, pinned) as the rules read it. */
+export function vocabularyViewOf(data) {
+    const roots = rootsOf(data);
+    const services = [...data.services];
+    const businessKeys = new Set([...services, ...roots.keys()]);
+    return {
+        version: data.version ?? 'unknown',
+        services,
+        catalogue: data.catalogue,
+        subcategories: data.subcategories,
+        rootService: data.root_service ?? {},
+        labels: data.labels ?? {},
+        businessKeys,
+        isBusinessKey: (key) => businessKeys.has(key),
+        businessRoot: (key) => roots.get(key) ?? key,
+    };
 }
-export const BUSINESS_KEYS = new Set([...SERVICE_SLUGS, ...ROOT_OF.keys()]);
+const BUNDLED = vocabularyViewOf({
+    version: vocabulary.version,
+    services: vocabulary.services,
+    catalogue: vocabulary.catalogue,
+    subcategories: vocabulary.subcategories,
+    root_service: vocabulary.root_service,
+});
+/** The bundled snapshot as the rules read it: what `checkTheme` uses unless a vocabulary is passed. */
+export const bundledVocabularyView = BUNDLED;
+export const SERVICE_SLUGS = BUNDLED.services;
+export const CATALOGUE = BUNDLED.catalogue;
+/** A branch's own children, a third level (`bags-accessories` → `jewelry`). */
+export const SUBCATEGORIES = BUNDLED.subcategories;
+/** A catalogue root's business category where they differ (`phones-tablets` → `phones-accessories`). */
+export const ROOT_SERVICE = BUNDLED.rootService;
+/** The bundled snapshot's version (the synced S1 snapshot). */
+export const BUNDLED_VERSION = BUNDLED.version;
+export const BUSINESS_KEYS = BUNDLED.businessKeys;
 export function isBusinessKey(key) {
-    return BUSINESS_KEYS.has(key);
+    return BUNDLED.isBusinessKey(key);
 }
 /** 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;
+    return BUNDLED.businessRoot(key);
 }

package/dist/utils/business-vocabulary.json

@@ -1,24 +1,429 @@
 {
-  "$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.",
+  "$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 (storefront-theme-templates-contract.md, R2.1; jewelry R2.5; production snapshot R2.9); change it only together with the backend.",
+  "version": "d1f9c8eefc91ed3b2c834345458c62343f465ce6",
   "services": [
-    "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", "laundry", "gas-refill", "home-cleaning",
-    "car-wash"
+    "baby-kids",
+    "beauty-cosmetics",
+    "electronics",
+    "fashion",
+    "foods",
+    "gas-refill",
+    "groceries",
+    "health-wellness-store",
+    "home-living",
+    "laundry",
+    "office-school",
+    "pharmacy",
+    "phones-accessories",
+    "shop",
+    "shop-groceries",
+    "supermarket"
   ],
   "catalogue": {
-    "fashion": ["womens-fashion", "mens-fashion", "kids-fashion", "shoes", "bags-accessories", "modest-occasion-wear"],
-    "beauty-personal-care": ["makeup", "skincare", "hair-care-styling", "fragrance", "wigs-extensions-hair-accessories", "personal-care", "beauty-tools-devices"],
-    "electronics": ["computers-laptops", "tv-home-entertainment", "gaming-consoles", "cameras-drones", "smart-home-security", "power-solar"],
-    "phones-tablets": ["smartphones", "tablets-e-readers", "smartwatches-wearables", "chargers-power-banks", "earbuds-headsets", "cases-screen-protection", "phone-repair-replacement"],
-    "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"],
-    "supermarket": ["beverages"]
+    "baby-kids": [
+      "baby-clothing",
+      "baby-gear",
+      "diapering-potty",
+      "feeding-nursing",
+      "kids-clothing",
+      "nursery-safety",
+      "school-essentials",
+      "toys-games"
+    ],
+    "beauty-personal-care": [
+      "beauty-tools-devices",
+      "fragrance",
+      "hair-care-styling",
+      "makeup",
+      "personal-care",
+      "skincare",
+      "wigs-extensions-hair-accessories"
+    ],
+    "electronics": [
+      "cameras-drones",
+      "computers-laptops",
+      "gaming-consoles",
+      "power-solar",
+      "smart-home-security",
+      "tv-home-entertainment"
+    ],
+    "fashion": [
+      "bags-accessories",
+      "kids-fashion",
+      "mens-fashion",
+      "modest-occasion-wear",
+      "shoes",
+      "womens-fashion"
+    ],
+    "health-wellness": [
+      "fitness-recovery",
+      "health-devices",
+      "healthy-living",
+      "medical-supplies",
+      "personal-care-hygiene",
+      "sexual-wellness",
+      "vitamins-supplements"
+    ],
+    "home-living": [
+      "bedding-bath",
+      "furniture",
+      "home-decor",
+      "kitchen-dining",
+      "lighting-electrical",
+      "storage-organization"
+    ],
+    "office-school": [
+      "bags-lunch-gear",
+      "office-furniture",
+      "office-supplies",
+      "printers-accessories",
+      "school-supplies",
+      "stationery-writing",
+      "tech-for-school-office"
+    ],
+    "phones-tablets": [
+      "cases-screen-protection",
+      "chargers-power-banks",
+      "earbuds-headsets",
+      "phone-repair-replacement",
+      "smartphones",
+      "smartwatches-wearables",
+      "tablets-e-readers"
+    ]
   },
   "subcategories": {
-    "bags-accessories": ["jewelry"]
+    "baby-clothing": [
+      "newborn-clothing",
+      "sets",
+      "sleepsuits",
+      "socks-caps"
+    ],
+    "baby-gear": [
+      "car-seats",
+      "carriers",
+      "strollers",
+      "walkers"
+    ],
+    "bags-accessories": [
+      "backpacks",
+      "handbags",
+      "jewelry",
+      "wallets",
+      "watches"
+    ],
+    "bags-lunch-gear": [
+      "backpacks",
+      "lunch-bags",
+      "pencil-cases",
+      "water-bottles"
+    ],
+    "beauty-tools-devices": [
+      "beauty-blenders",
+      "makeup-brushes",
+      "nail-tools",
+      "skincare-devices"
+    ],
+    "bedding-bath": [
+      "bathroom-accessories",
+      "bedsheets",
+      "pillows-duvets",
+      "towels"
+    ],
+    "cameras-drones": [
+      "cameras",
+      "drones",
+      "lenses",
+      "photography-accessories"
+    ],
+    "cases-screen-protection": [
+      "phone-cases",
+      "screen-protectors",
+      "tablet-covers"
+    ],
+    "chargers-power-banks": [
+      "cables",
+      "car-chargers",
+      "power-banks",
+      "wall-chargers",
+      "wireless-chargers"
+    ],
+    "computers-laptops": [
+      "desktop-pcs",
+      "keyboards-mice",
+      "laptops",
+      "monitors",
+      "storage-devices"
+    ],
+    "diapering-potty": [
+      "changing-accessories",
+      "diapers",
+      "potty-training",
+      "wipes"
+    ],
+    "earbuds-headsets": [
+      "bluetooth-earbuds",
+      "headphones",
+      "phone-headsets",
+      "speakers"
+    ],
+    "feeding-nursing": [
+      "bibs",
+      "bottles",
+      "breast-pumps",
+      "feeding-accessories"
+    ],
+    "fitness-recovery": [
+      "exercise-equipment",
+      "massage-recovery",
+      "support-braces",
+      "yoga-pilates"
+    ],
+    "fragrance": [
+      "body-mists",
+      "gift-sets",
+      "perfumes"
+    ],
+    "furniture": [
+      "beds-mattresses",
+      "chairs-stools",
+      "sofas",
+      "tables-desks",
+      "wardrobes-storage"
+    ],
+    "gaming-consoles": [
+      "consoles",
+      "gaming-accessories",
+      "gaming-chairs"
+    ],
+    "hair-care-styling": [
+      "hair-tools",
+      "hair-treatments",
+      "shampoo-conditioner",
+      "styling-products"
+    ],
+    "health-devices": [
+      "nebulizers",
+      "oximeters",
+      "posture-wellness-devices",
+      "weighing-scales"
+    ],
+    "healthy-living": [
+      "digestive-health",
+      "healthy-snacks",
+      "herbal-products",
+      "sleep-support"
+    ],
+    "home-decor": [
+      "decorative-accessories",
+      "mirrors",
+      "rugs-curtains",
+      "wall-art"
+    ],
+    "kids-clothing": [
+      "boys-clothing",
+      "girls-clothing",
+      "school-wear"
+    ],
+    "kids-fashion": [
+      "baby-clothing",
+      "boys-clothing",
+      "girls-clothing",
+      "school-wear"
+    ],
+    "kitchen-dining": [
+      "cookware",
+      "dinnerware",
+      "kitchen-storage",
+      "small-kitchen-appliances"
+    ],
+    "lighting-electrical": [
+      "ceiling-lights",
+      "electrical-fittings",
+      "lamps",
+      "outdoor-lighting"
+    ],
+    "makeup": [
+      "eye-makeup",
+      "face-makeup",
+      "lip-makeup",
+      "makeup-sets"
+    ],
+    "medical-supplies": [
+      "blood-pressure-monitors",
+      "first-aid",
+      "glucose-monitors",
+      "thermometers"
+    ],
+    "mens-fashion": [
+      "native-wear",
+      "shirts",
+      "t-shirts-polos",
+      "trousers-jeans",
+      "underwear-sleepwear"
+    ],
+    "modest-occasion-wear": [
+      "aso-ebi",
+      "bridal-occasion",
+      "kaftans-abayas",
+      "suits-blazers"
+    ],
+    "nursery-safety": [
+      "baby-monitors",
+      "cots-cribs",
+      "nursery-bedding",
+      "safety-gates"
+    ],
+    "office-furniture": [
+      "desks",
+      "office-chairs",
+      "shelves",
+      "whiteboards"
+    ],
+    "office-supplies": [
+      "desk-accessories",
+      "filing-organization",
+      "laminating-binding",
+      "paper-products"
+    ],
+    "personal-care": [
+      "bath-body",
+      "feminine-care",
+      "grooming",
+      "oral-care"
+    ],
+    "personal-care-hygiene": [
+      "bath-body",
+      "deodorants",
+      "feminine-care",
+      "oral-care"
+    ],
+    "phone-repair-replacement": [
+      "phone-batteries",
+      "repair-tools",
+      "replacement-screens"
+    ],
+    "power-solar": [
+      "batteries-ups",
+      "extension-surge-protectors",
+      "inverters",
+      "solar-panels"
+    ],
+    "printers-accessories": [
+      "ink-toner",
+      "printer-accessories",
+      "printers",
+      "printing-paper"
+    ],
+    "school-essentials": [
+      "lunch-boxes",
+      "school-bags",
+      "stationery",
+      "water-bottles"
+    ],
+    "school-supplies": [
+      "classroom-supplies",
+      "exam-essentials",
+      "exercise-books",
+      "geometry-sets"
+    ],
+    "sexual-wellness": [
+      "condoms",
+      "intimate-care",
+      "lubricants",
+      "performance-support"
+    ],
+    "shoes": [
+      "kids-shoes",
+      "men-shoes",
+      "slides-sandals",
+      "women-shoes"
+    ],
+    "skincare": [
+      "cleansers",
+      "face-masks",
+      "moisturizers",
+      "serums",
+      "sunscreens"
+    ],
+    "smart-home-security": [
+      "cctv-security",
+      "networking",
+      "smart-home-devices"
+    ],
+    "smartphones": [
+      "android-phones",
+      "iphones",
+      "refurbished-phones"
+    ],
+    "smartwatches-wearables": [
+      "fitness-bands",
+      "gps-wearables",
+      "smartwatches"
+    ],
+    "stationery-writing": [
+      "art-supplies",
+      "markers-highlighters",
+      "notebooks",
+      "pens-pencils"
+    ],
+    "storage-organization": [
+      "closet-organizers",
+      "laundry-storage",
+      "shelving",
+      "utility-storage"
+    ],
+    "tablets-e-readers": [
+      "e-readers",
+      "kids-tablets",
+      "tablets"
+    ],
+    "tech-for-school-office": [
+      "calculators",
+      "computer-accessories",
+      "laptops",
+      "projectors"
+    ],
+    "toys-games": [
+      "board-games",
+      "dolls-action-figures",
+      "learning-toys",
+      "outdoor-toys"
+    ],
+    "tv-home-entertainment": [
+      "home-audio",
+      "projectors",
+      "streaming-devices",
+      "televisions",
+      "tv-accessories"
+    ],
+    "vitamins-supplements": [
+      "immunity-support",
+      "multivitamins",
+      "sports-nutrition",
+      "weight-management"
+    ],
+    "wigs-extensions-hair-accessories": [
+      "extensions",
+      "hair-accessories",
+      "human-hair-wigs",
+      "synthetic-wigs",
+      "wigs"
+    ],
+    "womens-fashion": [
+      "dresses",
+      "lingerie-sleepwear",
+      "skirts-shorts",
+      "tops-tees"
+    ]
+  },
+  "root_service": {
+    "baby-kids": "baby-kids",
+    "beauty-personal-care": "beauty-cosmetics",
+    "electronics": "electronics",
+    "fashion": "fashion",
+    "health-wellness": "health-wellness-store",
+    "home-living": "home-living",
+    "office-school": "office-school",
+    "phones-tablets": "phones-accessories"
   }
 }

package/dist/utils/template-copy.js

@@ -93,10 +93,19 @@ const NAIRA_AMOUNT = [
     /(?<![\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". */
+/**
+ * A discount or a coupon code: "Save 20% with code RAINS20", "Up to 25% off".
+ * "Half-price" and a bare "sale" are offers too ("the clearance sale is on",
+ * "shop the sale", "sale ends Sunday") — but only as their own word, so
+ * "wholesale" and "salesperson" are not, and never the trade phrase "for sale
+ * by the kilo". "Discount" and "coupon" alone name an offer no store can keep.
+ */
 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,
+    /\bhalf[\s-]price\b/i,
+    /\b(?<!for )sale\b(?! by the kilo)/i,
+    /\b(?:coupon|discount)s?\b/i,
 ];
 /**
  * Opening hours: "Open daily", "11am–10pm", "Doors open 11am", "from 6 AM",
@@ -109,18 +118,23 @@ const HOURS = new RegExp([
     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`,
+    // a weekday at a clock time is the store's schedule: "New drop every Friday, 7pm"
+    String.raw `\b(?:mon|tues|wednes|thurs|fri|satur|sun)days?\b,?\s+(?:at\s+)?${TIME}`,
 ].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 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*|measur\w*|tailor\w*|alter(?:s|ed|ing|ations?)?)`;
+const WINDOW = String.raw `(?:(?:within|in|under)\s+(?:about\s+)?(?:\d+|an?|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|fourteen|fifteen|twenty)[\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(?:free|complimentary)\s+(?:\w+\s+)?(?:delivery|shipping|returns?|pick[- ]?up|collection|alterations?|installation|install|resizing|exchanges?|samples?|styling|gifts?|consultations?|fittings?|refills?)\b/i,
+    // a service promised without end, or a reply promised fast
+    /\b(?:returns?|exchanges?|refunds?|delivery|shipping)\b[^.!?\n|]{0,20}\balways\b/i,
+    /\b(?:answer\w*|repl(?:y|ies|ied)|respond\w*)\s+(?:fast|quickly|promptly|right away)\b|\b(?:fast|quick|prompt)\s+(?:repl(?:y|ies)|answers?|responses?)\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". */

package/dist/vocabulary.d.ts

@@ -0,0 +1,70 @@
+/** Where the live vocabulary is fetched from. */
+export declare const VOCABULARY_URL = "https://api.usequeek.com/api/v1/client/theme-vocabulary";
+/** A cached copy younger than this is used without a network request (the endpoint sends `Cache-Control: public, max-age=3600`). */
+export declare const VOCABULARY_CACHE_TTL_MS = 3600000;
+export type VocabularySource = 'live' | 'cache' | 'bundled' | 'file';
+/** The vocabulary itself: the endpoint's `data`, the bundled JSON, or a pinned file. */
+export interface BusinessVocabularyData {
+    version?: string;
+    services: string[];
+    catalogue: Record<string, string[]>;
+    subcategories: Record<string, string[]>;
+    root_service?: Record<string, string>;
+    labels?: Record<string, string>;
+}
+export interface ResolveVocabularyOptions {
+    /** `live` (default) refreshes through the cache; `offline` uses the bundled snapshot, no network. */
+    mode?: 'live' | 'offline';
+    /** A pinned vocabulary file: wins over everything, and is validated. */
+    file?: string;
+    /** Ignore a fresh cache, but still revalidate with `If-None-Match`. Queek's submission step uses it. */
+    force?: boolean;
+    /** Fetch timeout in ms. A timeout falls back like any network error. */
+    timeoutMs?: number;
+    /** Injectable fetch, for tests. Defaults to the global fetch at call time. */
+    fetch?: typeof fetch;
+    /** Injectable cache dir, for tests. Defaults to vocabularyCacheDir(). */
+    cacheDir?: string;
+    /** Injectable clock, for tests. Defaults to Date.now(). */
+    now?: number;
+}
+export interface ResolvedVocabulary {
+    vocabulary: BusinessVocabularyData;
+    source: VocabularySource;
+    version: string;
+    /** One line explaining a fallback (cache/bundled used because live failed). Absent on a clean resolve. */
+    notice?: string;
+}
+/**
+ * The vocabulary's shape, strictly: non-empty service slugs, catalogue roots
+ * to branch lists, branches to children. `version` is required when it must
+ * identify the copy (endpoint payloads, the cache); a pinned file may omit it.
+ */
+export declare function parseVocabularyData(value: unknown, options: {
+    requireVersion: boolean;
+}): BusinessVocabularyData;
+/** The endpoint's `{ status, data }` envelope, unwrapped and strictly validated. */
+export declare function parseEndpointPayload(value: unknown): BusinessVocabularyData;
+/** The bundled snapshot, as data. Its version comes from the synced file. */
+export declare function bundledVocabulary(): BusinessVocabularyData;
+/** The bundled snapshot's version (the synced S1 snapshot). */
+export declare function bundledVersion(): string;
+export declare function vocabularyCacheDir(options?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}): string;
+/** The cached copy, synchronously, for prompts that must ask before any fetch returns. Null when absent or invalid. */
+export declare function readCachedVocabulary(cacheDir?: string): BusinessVocabularyData | null;
+/**
+ * Resolve the vocabulary regulators and prompts check against.
+ *
+ * - `file` wins, and is validated (an unreadable or invalid file throws).
+ * - `offline` uses the bundled snapshot, with no network and no cache read.
+ * - `live` uses a fresh cache as-is, else a conditional GET with
+ *   `If-None-Match: "<cached version>"`: 304 keeps the cache, 200 validates,
+ *   caches atomically, and uses the fresh copy.
+ * - A network error, timeout, unexpected status or bad payload falls back to
+ *   the cache, else the bundled snapshot, with a one-line `notice`.
+ * - `force` skips the fresh-cache shortcut but still sends `If-None-Match`.
+ */
+export declare function resolveVocabulary(options?: ResolveVocabularyOptions): Promise<ResolvedVocabulary>;

package/dist/vocabulary.js

@@ -0,0 +1,249 @@
+/**
+ * The live business vocabulary: one resolver, one cache, shared by
+ * theme-check, theme-cli and create-theme.
+ *
+ * Production serves `{ status, data }` at VOCABULARY_URL, where `data` holds
+ * the vocabulary (`version`, `services`, `catalogue`, `subcategories`,
+ * `root_service`, `labels`). The cache lives under vocabularyCacheDir() and
+ * holds the last good `data` with its version. Reads never throw for `live`
+ * (they fall back to the cache, then the bundled snapshot, with a one-line
+ * notice); only an explicitly pinned `file` that cannot be read or validated
+ * throws.
+ *
+ * Production weakens the ETag to `W/"<v>-br"` (backend 216e0df3 pending), so
+ * the conditional GET is built from the stored version, never the raw header:
+ * `If-None-Match: "<version>"` (quoted, no `W/`, no suffix).
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import bundled from './utils/business-vocabulary.json' with { type: 'json' };
+/** Where the live vocabulary is fetched from. */
+export const VOCABULARY_URL = 'https://api.usequeek.com/api/v1/client/theme-vocabulary';
+/** A cached copy younger than this is used without a network request (the endpoint sends `Cache-Control: public, max-age=3600`). */
+export const VOCABULARY_CACHE_TTL_MS = 3_600_000;
+/** The file in the cache dir holding the last good vocabulary. */
+const CACHE_FILE = 'vocabulary.json';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+const isStringArrayMap = (value) => isRecord(value) && Object.values(value).every(isStringArray);
+const isStringMap = (value) => isRecord(value) && Object.values(value).every((item) => typeof item === 'string');
+/**
+ * The vocabulary's shape, strictly: non-empty service slugs, catalogue roots
+ * to branch lists, branches to children. `version` is required when it must
+ * identify the copy (endpoint payloads, the cache); a pinned file may omit it.
+ */
+export function parseVocabularyData(value, options) {
+    if (!isRecord(value))
+        throw new Error('the vocabulary is not an object');
+    const { version, services, catalogue, subcategories, root_service: rootService, labels } = value;
+    if (options.requireVersion && (typeof version !== 'string' || version.length === 0)) {
+        throw new Error('the vocabulary has no version');
+    }
+    if (version !== undefined && typeof version !== 'string')
+        throw new Error('the vocabulary version is not a string');
+    if (!isStringArray(services) || services.length === 0 || services.some((slug) => slug.length === 0)) {
+        throw new Error('the vocabulary has no services list');
+    }
+    if (!isStringArrayMap(catalogue))
+        throw new Error('the vocabulary has no catalogue map');
+    if (!isStringArrayMap(subcategories))
+        throw new Error('the vocabulary has no subcategories map');
+    if (rootService !== undefined && !isStringMap(rootService))
+        throw new Error('the vocabulary root_service is not a map');
+    if (labels !== undefined && !isStringMap(labels))
+        throw new Error('the vocabulary labels are not a map');
+    return { version, services, catalogue, subcategories, root_service: rootService, labels };
+}
+/** The endpoint's `{ status, data }` envelope, unwrapped and strictly validated. */
+export function parseEndpointPayload(value) {
+    if (!isRecord(value) || !isRecord(value.data))
+        throw new Error('the vocabulary endpoint did not return { status, data }');
+    return parseVocabularyData(value.data, { requireVersion: true });
+}
+/** The bundled snapshot, as data. Its version comes from the synced file. */
+export function bundledVocabulary() {
+    return parseVocabularyData(bundled, { requireVersion: true });
+}
+/** The bundled snapshot's version (the synced S1 snapshot). */
+export function bundledVersion() {
+    return bundled.version;
+}
+export function vocabularyCacheDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    if (platform === 'win32') {
+        const base = env.LOCALAPPDATA;
+        if (typeof base === 'string' && base.length > 0)
+            return join(base, 'usequeek');
+    }
+    if (platform === 'darwin')
+        return join(homedir(), 'Library', 'Caches', 'usequeek');
+    const xdg = env.XDG_CACHE_HOME;
+    if (typeof xdg === 'string' && xdg.length > 0)
+        return join(xdg, 'usequeek');
+    return join(homedir(), '.cache', 'usequeek');
+}
+function readCache(dir) {
+    let raw;
+    try {
+        raw = readFileSync(join(dir, CACHE_FILE), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // The envelope this resolver writes; a raw vocabulary (hand-placed) is
+        // accepted too, but counts as stale so it is revalidated.
+        if (isRecord(parsed) && typeof parsed.fetchedAt === 'number' && parsed.vocabulary !== undefined) {
+            const vocabulary = parseVocabularyData(parsed.vocabulary, { requireVersion: true });
+            if (typeof parsed.version !== 'string' || parsed.version !== vocabulary.version)
+                return null;
+            return { version: vocabulary.version, fetchedAt: parsed.fetchedAt, vocabulary };
+        }
+        const vocabulary = parseVocabularyData(parsed, { requireVersion: true });
+        return { version: vocabulary.version, fetchedAt: 0, vocabulary };
+    }
+    catch {
+        return null;
+    }
+}
+/** The cached copy, synchronously, for prompts that must ask before any fetch returns. Null when absent or invalid. */
+export function readCachedVocabulary(cacheDir) {
+    try {
+        return readCache(cacheDir ?? vocabularyCacheDir())?.vocabulary ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the cache atomically (temp file + rename), so a crash never leaves half a vocabulary. */
+function writeCache(dir, vocabulary, now) {
+    mkdirSync(dir, { recursive: true });
+    const entry = { version: vocabulary.version, fetchedAt: now, vocabulary };
+    const staging = join(dir, `.${CACHE_FILE}.${process.pid}.tmp`);
+    writeFileSync(staging, `${JSON.stringify(entry, null, 2)}\n`);
+    renameSync(staging, join(dir, CACHE_FILE));
+}
+/** Fetch with a timeout that also aborts the request (an injected fake that ignores the signal still loses the race). */
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        const result = await Promise.race([
+            fetchImpl(url, { ...init, signal: controller.signal }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+        return result;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const cacheNotice = (version, reason) => `theme vocabulary: using the cached copy (version ${version}) — live refresh failed (${reason}).`;
+const bundledNotice = (reason) => `theme vocabulary: using the bundled copy (version ${bundledVersion()}) — ${reason}.`;
+/**
+ * Resolve the vocabulary regulators and prompts check against.
+ *
+ * - `file` wins, and is validated (an unreadable or invalid file throws).
+ * - `offline` uses the bundled snapshot, with no network and no cache read.
+ * - `live` uses a fresh cache as-is, else a conditional GET with
+ *   `If-None-Match: "<cached version>"`: 304 keeps the cache, 200 validates,
+ *   caches atomically, and uses the fresh copy.
+ * - A network error, timeout, unexpected status or bad payload falls back to
+ *   the cache, else the bundled snapshot, with a one-line `notice`.
+ * - `force` skips the fresh-cache shortcut but still sends `If-None-Match`.
+ */
+export async function resolveVocabulary(options = {}) {
+    const { mode = 'live', file, force = false, timeoutMs = 4000, now = Date.now() } = options;
+    if (file !== undefined) {
+        let raw;
+        try {
+            raw = readFileSync(resolve(file), 'utf8');
+        }
+        catch (error) {
+            throw new Error(`cannot read --vocabulary ${file} (${error.message})`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`--vocabulary ${file} is not valid JSON`);
+        }
+        const vocabulary = isRecord(parsed) && parsed.data !== undefined
+            ? parseEndpointPayload(parsed)
+            : parseVocabularyData(parsed, { requireVersion: false });
+        return { vocabulary, source: 'file', version: vocabulary.version ?? 'unknown' };
+    }
+    if (mode === 'offline') {
+        const vocabulary = bundledVocabulary();
+        return { vocabulary, source: 'bundled', version: vocabulary.version };
+    }
+    const dir = options.cacheDir ?? vocabularyCacheDir();
+    const cached = readCache(dir);
+    if (cached && !force && now - cached.fetchedAt < VOCABULARY_CACHE_TTL_MS) {
+        return { vocabulary: cached.vocabulary, source: 'cache', version: cached.version };
+    }
+    const fetchImpl = (options.fetch ?? globalThis.fetch);
+    const headers = { Accept: 'application/json' };
+    if (cached)
+        headers['If-None-Match'] = `"${cached.version}"`;
+    const fallback = (reason) => {
+        if (cached)
+            return { vocabulary: cached.vocabulary, source: 'cache', version: cached.version, notice: cacheNotice(cached.version, reason) };
+        const vocabulary = bundledVocabulary();
+        return { vocabulary, source: 'bundled', version: vocabulary.version, notice: bundledNotice(reason) };
+    };
+    let response;
+    try {
+        response = await fetchWithTimeout(fetchImpl, VOCABULARY_URL, { headers }, timeoutMs);
+    }
+    catch (error) {
+        return fallback(error instanceof Error ? error.message : String(error));
+    }
+    if (response.status === 304) {
+        if (!cached) {
+            // No copy to keep: a 304 with nothing cached is a server surprise, not a vocabulary.
+            const vocabulary = bundledVocabulary();
+            return { vocabulary, source: 'bundled', version: vocabulary.version, notice: bundledNotice('the server sent 304 with nothing cached') };
+        }
+        try {
+            writeCache(dir, cached.vocabulary, now);
+        }
+        catch {
+            // The copy in hand is what matters; a timestamp refresh that fails is not a failure.
+        }
+        return { vocabulary: cached.vocabulary, source: 'cache', version: cached.version };
+    }
+    if (response.status !== 200) {
+        return fallback(`the server sent ${response.status}`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        return fallback('the response was not JSON');
+    }
+    let vocabulary;
+    try {
+        vocabulary = parseEndpointPayload(payload);
+    }
+    catch (error) {
+        return fallback(`the payload was invalid (${error.message})`);
+    }
+    try {
+        writeCache(dir, vocabulary, now);
+    }
+    catch (error) {
+        return { vocabulary, source: 'live', version: vocabulary.version, notice: `theme vocabulary: fetched live (version ${vocabulary.version}) but the cache could not be written (${error.message}).` };
+    }
+    return { vocabulary, source: 'live', version: vocabulary.version };
+}

package/package.json

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