@usequeek/theme-check 0.1.0

package/dist/run.d.ts

@@ -0,0 +1,25 @@
+import type { CheckEnv, Finding, Rule, ThemeContext } from './types.js';
+/** Every rule that runs on a developer's machine, in the order they report. */
+export declare const RULES: Rule[];
+/**
+ * Checks that only Queek can run, when a theme is submitted: they need Queek's
+ * other themes, a server render, or Queek's storage. Listed so a clean local
+ * run never reads as "nothing else can fail".
+ */
+export declare const AT_SUBMISSION: ReadonlyArray<{
+    id: string;
+    summary: string;
+}>;
+export interface CheckOptions {
+    /** Override how findings name files and where they link (see CheckEnv). */
+    env?: Partial<CheckEnv>;
+    /** Run only these rule ids. */
+    only?: string[];
+}
+export interface CheckResult {
+    context: ThemeContext;
+    findings: Finding[];
+}
+/** 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>;
+export declare const rejects: (findings: Finding[]) => Finding[];

package/dist/run.js

@@ -0,0 +1,42 @@
+import { loadContext } from './context.js';
+import { ANALYSIS_RULES } from './rules/analysis.js';
+import { STATIC_RULES } from './rules/static.js';
+/** Every rule that runs on a developer's machine, in the order they report. */
+export const RULES = [...STATIC_RULES, ...ANALYSIS_RULES];
+/**
+ * Checks that only Queek can run, when a theme is submitted: they need Queek's
+ * other themes, a server render, or Queek's storage. Listed so a clean local
+ * run never reads as "nothing else can fail".
+ */
+export const AT_SUBMISSION = [
+    { id: 'theme/divergence', summary: 'the design is its own, not a copy of an existing Queek theme' },
+    { id: 'theme/renders', summary: 'every declared variant renders visible content with sample data' },
+    { id: 'theme/price-range-signal', summary: 'a product priced as a range shows "From", not its floor as the price' },
+    { id: 'theme/demo-art-hosting', summary: 'demo images are moved onto Queek’s CDN (done for you)' },
+    { id: 'theme/template-screenshot', summary: 'template screenshots are uploaded (done for you)' },
+];
+/** 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 rules = RULES.filter((rule) => !options.only || options.only.includes(rule.id));
+    const findings = [];
+    for (const rule of rules) {
+        try {
+            findings.push(...(await rule.run(context)));
+        }
+        catch (error) {
+            // A rule that throws is itself a failure signal — a theme whose module
+            // graph will not load cannot be published, and silently skipping the
+            // rule would report that theme as clean.
+            findings.push({
+                rule: rule.id,
+                severity: 'reject',
+                theme: context.slug,
+                found: `the check could not run: ${error.message}`,
+                fix: 'Usually a theme module that fails to load. Run `npx tsc --noEmit` and fix the error first.',
+            });
+        }
+    }
+    return { context, findings };
+}
+export const rejects = (findings) => findings.filter((finding) => finding.severity === 'reject');

package/dist/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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.
+ */
+/**
+ * The parts of a theme's manifest (and of @usequeek/theme-kit's ThemeManifest)
+ * the rules read. Structural, so this package does not compile the kit's
+ * source — the kit ships TypeScript, not declarations.
+ */
+export interface ThemeManifest {
+    slug?: string;
+    variants?: Record<string, unknown[]>;
+    tokens?: DesignTokens;
+    [key: string]: unknown;
+}
+/** The design-token dimensions the design-tokens rule requires (the kit's DesignTokens). */
+export interface DesignTokens {
+    color?: Record<string, unknown>;
+    type?: {
+        heading_font?: string;
+        body_font?: string;
+        scale_ratio?: number;
+        [key: string]: unknown;
+    };
+    space?: {
+        density?: string;
+        [key: string]: unknown;
+    };
+    shape?: {
+        radius?: string;
+        [key: string]: unknown;
+    };
+    elevation?: string;
+    motion?: string;
+    [key: string]: unknown;
+}
+/** `reject` blocks publication. `warn` is advice a theme can ship with. */
+export type Severity = 'reject' | 'warn';
+export interface Finding {
+    /** Stable id — an agent keys its fix loop on this, so never rename casually. */
+    rule: string;
+    severity: Severity;
+    theme: string;
+    /** `path/in/theme.tsx:line` where known. */
+    where?: string;
+    /** What is actually there. */
+    found: string;
+    /** What to do about it, concretely enough to act on without reading docs. */
+    fix: string;
+    /** True when `--fix` can resolve it without a human decision. */
+    fixable?: boolean;
+    docs?: string;
+}
+/** One demo store on disk: `demo.json` (id `default`) or `demos/<id>.json`. */
+export interface DemoStore {
+    id: string;
+    /** Relative to the theme directory. */
+    file: string;
+    /** Null when the file is missing or not valid JSON. */
+    data: Record<string, unknown> | null;
+}
+/** A `demos[]` entry in theme.config.ts. */
+export interface DeclaredDemo {
+    id: string;
+    label: string;
+    /** Business slugs (the vendor's service_slug/service_type vocabulary). */
+    for: string[];
+    /** What an AI reads to choose this template for a merchant (≤ 300 chars). */
+    description?: string;
+}
+/**
+ * Where the rules are running, so every finding names things the reader can
+ * act on. A developer's repo and Queek's submission pipeline see the same
+ * theme through different paths and commands; the rules are the same.
+ */
+export interface CheckEnv {
+    /** How a file of the theme is written in a finding, e.g. `theme/` — always ends with `/`. */
+    root: string;
+    /** The contract, as a URL (findings link `<docs>#<section>`). */
+    docs: string;
+    /** Where the business vocabulary is, as the reader would find it. */
+    vocabulary: string;
+    /** The command that scaffolds a complete theme. */
+    scaffold: string;
+    /** Where a template previews, by template id (`default` is the primary). */
+    preview: (templateId: string) => string;
+    /**
+     * True when Queek is checking a submission. Two checks only mean anything
+     * then: demo art on Queek's CDN, and screenshots uploaded — both done by the
+     * submission pipeline itself, never by the developer.
+     */
+    submission: boolean;
+}
+export interface ThemeContext {
+    env: CheckEnv;
+    slug: string;
+    dir: string;
+    /** `active: false` in theme.config.ts — retired, exempt from publish gates. */
+    retired: boolean;
+    /** The primary store — `demos[0].data`. Kept for rules that only ever read it. */
+    demo: Record<string, unknown> | null;
+    /** Every store on disk, the primary first. */
+    demos: DemoStore[];
+    /** `demos` from theme.config.ts; null when the config could not be loaded. */
+    declaredDemos: DeclaredDemo[] | null;
+    /** `default_demo.description` from theme.config.ts — the primary template's description. */
+    defaultDescription: string | null;
+    /** `default_demo.for` from theme.config.ts, unvalidated — the primary template's business. */
+    defaultFor: unknown;
+    manifest: ThemeManifest | null;
+    /** Declares page-block variants, so the page-based structure applies. */
+    pageBased: boolean;
+    file: (relative: string) => string;
+    exists: (relative: string) => boolean;
+    read: (relative: string) => string | null;
+}
+export interface Rule {
+    id: string;
+    /** One line, shown by `--list`. */
+    summary: string;
+    /** Render rules import theme modules and are slow — `--static` skips them. */
+    kind: 'static' | 'render';
+    run: (context: ThemeContext) => Finding[] | Promise<Finding[]>;
+}
+export declare function finding(context: ThemeContext, rule: string, severity: Severity, parts: Omit<Finding, 'rule' | 'severity' | 'theme'>): Finding;

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * 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

@@ -0,0 +1,6 @@
+export declare const SERVICE_SLUGS: readonly string[];
+export declare const CATALOGUE: 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. */
+export declare function businessRoot(key: string): string;

package/dist/utils/business-vocabulary.js

@@ -0,0 +1,18 @@
+/**
+ * The business vocabulary a template's `for` speaks (business-vocabulary.json):
+ * 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.
+ */
+import vocabulary from './business-vocabulary.json' with { type: 'json' };
+export const SERVICE_SLUGS = vocabulary.services;
+export const CATALOGUE = vocabulary.catalogue;
+const ROOT_OF = new Map(Object.entries(CATALOGUE).flatMap(([root, branches]) => [[root, root], ...branches.map((branch) => [branch, root])]));
+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. */
+export function businessRoot(key) {
+    return ROOT_OF.get(key) ?? key;
+}

package/dist/utils/business-vocabulary.json

@@ -0,0 +1,20 @@
+{
+  "$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.",
+  "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"
+  ],
+  "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"]
+  }
+}

package/dist/utils/theme-demo-images.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Image references inside a theme's `demo.json`.
+ *
+ * Three consumers must never disagree about what counts as an image: the
+ * rehost command (what to upload and rewrite), `/api/theme-registry` (what to
+ * publish as `variant_images`, and what to refuse to serve), and the CI
+ * assertion that keeps foreign art out of the tree. They all read from here.
+ *
+ * Collection walks VALUES, not field names — 26 references in
+ * `themes/default/demo.json` are bare elements of `products[].media.gallery`
+ * with no field name at all. But a value walk alone over-collects: `url`
+ * carries section art (342 of them) AND social links
+ * (`https://instagram.com/theglowedit`), so every value is classified rather
+ * than assumed to be an image.
+ */
+/** The prefix rehosted theme art lives under, inside an owned host. */
+export declare const THEME_ASSET_PREFIX = "theme-assets/";
+export type RefKind = 'image' | 'link' | 'unknown';
+export interface DemoRef {
+    value: string;
+    kind: RefKind;
+}
+/**
+ * `null` for anything that is not a reference at all — prose, ids, markdown.
+ * `unknown` is deliberate and load-bearing: a URL on a host we have not
+ * classified is reported rather than silently treated as copy, so a new CDN
+ * cannot slip past the rehost command unnoticed.
+ */
+export declare function classifyRef(value: unknown): RefKind | null;
+/** Every classified reference in `node`, in document order, duplicates kept. */
+export declare function collectRefs(node: unknown): DemoRef[];
+/** Image references in document order. Duplicates kept — order is the contract. */
+export declare function collectImageRefs(node: unknown): string[];
+/** URLs on hosts we cannot classify. The rehost command warns on these. */
+export declare function collectUnknownRefs(node: unknown): string[];
+/** True for an image already served from a Queek host under `theme-assets/`. */
+export declare function isOwnedImageRef(ref: string): boolean;
+/**
+ * Image references that must not ship: a foreign host, or a local file that
+ * exists only in a contributor's checkout.
+ */
+export declare function foreignImageRefs(node: unknown): string[];

package/dist/utils/theme-demo-images.js

@@ -0,0 +1,138 @@
+/**
+ * Image references inside a theme's `demo.json`.
+ *
+ * Three consumers must never disagree about what counts as an image: the
+ * rehost command (what to upload and rewrite), `/api/theme-registry` (what to
+ * publish as `variant_images`, and what to refuse to serve), and the CI
+ * assertion that keeps foreign art out of the tree. They all read from here.
+ *
+ * Collection walks VALUES, not field names — 26 references in
+ * `themes/default/demo.json` are bare elements of `products[].media.gallery`
+ * with no field name at all. But a value walk alone over-collects: `url`
+ * carries section art (342 of them) AND social links
+ * (`https://instagram.com/theglowedit`), so every value is classified rather
+ * than assumed to be an image.
+ */
+/** Hosts Queek serves its own media from. `R2_URL` extends this when set. */
+const OWNED_IMAGE_HOSTS = new Set(['media.usequeek.com']);
+/** The prefix rehosted theme art lives under, inside an owned host. */
+export const THEME_ASSET_PREFIX = 'theme-assets/';
+const IMAGE_EXTENSION = /\.(?:jpe?g|png|webp|avif|gif)$/i;
+/** Image CDNs that serve extensionless URLs (Unsplash: `/photo-1441986…?w=`). */
+const IMAGE_HOSTS = new Set([
+    'images.unsplash.com',
+    'plus.unsplash.com',
+    'source.unsplash.com',
+    'res.cloudinary.com',
+    'cdn.shopify.com',
+    'images.pexels.com',
+]);
+/** Hosts a demo links TO. Never fetched, never rewritten, never gated. */
+const LINK_HOSTS = new Set([
+    'instagram.com', 'www.instagram.com',
+    'x.com', 'www.x.com', 'twitter.com', 'www.twitter.com',
+    'facebook.com', 'www.facebook.com',
+    'tiktok.com', 'www.tiktok.com',
+    'pinterest.com', 'www.pinterest.com',
+    'linkedin.com', 'www.linkedin.com',
+    'threads.net', 'www.threads.net',
+    'snapchat.com', 't.me',
+    'wa.me', 'api.whatsapp.com',
+    'youtube.com', 'www.youtube.com', 'youtu.be',
+    'vimeo.com', 'player.vimeo.com',
+    'maps.google.com', 'maps.app.goo.gl', 'goo.gl',
+]);
+function ownedHosts() {
+    const hosts = new Set(OWNED_IMAGE_HOSTS);
+    const configured = process.env.R2_URL;
+    if (configured) {
+        try {
+            hosts.add(new URL(configured).hostname.toLowerCase());
+        }
+        catch {
+            // A malformed R2_URL is the rehost command's problem, not the gate's.
+        }
+    }
+    return hosts;
+}
+/**
+ * `null` for anything that is not a reference at all — prose, ids, markdown.
+ * `unknown` is deliberate and load-bearing: a URL on a host we have not
+ * classified is reported rather than silently treated as copy, so a new CDN
+ * cannot slip past the rehost command unnoticed.
+ */
+export function classifyRef(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    if (/^https?:\/\//i.test(trimmed)) {
+        let url;
+        try {
+            url = new URL(trimmed);
+        }
+        catch {
+            return null;
+        }
+        const host = url.hostname.toLowerCase();
+        if (LINK_HOSTS.has(host))
+            return 'link';
+        if (IMAGE_HOSTS.has(host) || IMAGE_EXTENSION.test(url.pathname))
+            return 'image';
+        return 'unknown';
+    }
+    // A local file a theme builder dropped in the folder. Requires an extension,
+    // so prose containing a slash is never mistaken for a path.
+    if (/^\.{0,2}\//.test(trimmed) || /^[\w.-]+\//.test(trimmed)) {
+        return IMAGE_EXTENSION.test(trimmed.split(/[?#]/)[0]) ? 'image' : null;
+    }
+    return null;
+}
+/** Every classified reference in `node`, in document order, duplicates kept. */
+export function collectRefs(node) {
+    const found = [];
+    const walk = (value) => {
+        if (typeof value === 'string') {
+            const kind = classifyRef(value);
+            if (kind)
+                found.push({ value: value.trim(), kind });
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach(walk);
+            return;
+        }
+        if (value && typeof value === 'object') {
+            Object.values(value).forEach(walk);
+        }
+    };
+    walk(node);
+    return found;
+}
+/** Image references in document order. Duplicates kept — order is the contract. */
+export function collectImageRefs(node) {
+    return collectRefs(node).filter((ref) => ref.kind === 'image').map((ref) => ref.value);
+}
+/** URLs on hosts we cannot classify. The rehost command warns on these. */
+export function collectUnknownRefs(node) {
+    return [...new Set(collectRefs(node).filter((ref) => ref.kind === 'unknown').map((ref) => ref.value))];
+}
+/** True for an image already served from a Queek host under `theme-assets/`. */
+export function isOwnedImageRef(ref) {
+    try {
+        const url = new URL(ref);
+        return ownedHosts().has(url.hostname.toLowerCase())
+            && url.pathname.replace(/^\//, '').startsWith(THEME_ASSET_PREFIX);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Image references that must not ship: a foreign host, or a local file that
+ * exists only in a contributor's checkout.
+ */
+export function foreignImageRefs(node) {
+    return [...new Set(collectImageRefs(node).filter((ref) => !isOwnedImageRef(ref)))];
+}

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

@@ -0,0 +1,28 @@
+export declare const DEMO_SEPARATOR = "~";
+/** The id `demo.json` goes by. Reserved — never a file under `demos/`. */
+export declare const PRIMARY_DEMO_ID = "default";
+/** Same shape as a theme slug: it lands in a URL and a filename. */
+export declare const DEMO_ID_FORMAT: RegExp;
+export interface PreviewTheme {
+    slug: string;
+    demoId: string;
+}
+/**
+ * `roast` → the primary; `roast~foods` → the `foods` store. Null for anything
+ * else, including `roast~default` — one canonical URL per store.
+ */
+export declare function parsePreviewTheme(param: string): PreviewTheme | null;
+/** The theme segment for a store: `roast`, or `roast~foods`. */
+export declare function previewThemeParam(slug: string, demoId: string): string;
+export interface DemoFile {
+    id: string;
+    /** Absolute path. */
+    path: string;
+}
+export declare function demoFilePath(themeDir: string, demoId: string): string;
+/**
+ * Every demo store on disk: the primary first, then `demos/*.json` by name.
+ * Files whose name is not a valid id are listed too — the identity rule is
+ * what rejects them, and it can only do that if it sees them.
+ */
+export declare function demoFilesOf(themeDir: string): DemoFile[];

package/dist/utils/theme-demos.js

@@ -0,0 +1,66 @@
+/**
+ * A theme's demo stores.
+ *
+ * `demo.json` is the primary — what the thumbnail, the section-library capture
+ * and the registry's top-level compositions come from. `demos/<id>.json` are
+ * alternatives (the same store shape, different business): roast previewed as
+ * a restaurant instead of a coffee house. Each is declared in `theme.config.ts`
+ * (`demos: [{ id, label, for }]`) so the registry can publish it and the
+ * backend can offer a food vendor the food demo.
+ *
+ * The preview URL carries the demo in the theme segment — `roast~foods` —
+ * because that is the one place every route, link and the proxy already
+ * agree on. `~` is URL-unreserved and cannot appear in a slug, so the split
+ * is unambiguous. Four consumers must never disagree about this: the preview
+ * routes, theme-check, the registry generator and the rehost command. They
+ * all read from here.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const DEMO_SEPARATOR = '~';
+/** The id `demo.json` goes by. Reserved — never a file under `demos/`. */
+export const PRIMARY_DEMO_ID = 'default';
+/** Same shape as a theme slug: it lands in a URL and a filename. */
+export const DEMO_ID_FORMAT = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * `roast` → the primary; `roast~foods` → the `foods` store. Null for anything
+ * else, including `roast~default` — one canonical URL per store.
+ */
+export function parsePreviewTheme(param) {
+    const parts = param.split(DEMO_SEPARATOR);
+    if (parts.length > 2)
+        return null;
+    const [slug, demoId = PRIMARY_DEMO_ID] = parts;
+    if (!DEMO_ID_FORMAT.test(slug) || !DEMO_ID_FORMAT.test(demoId))
+        return null;
+    if (parts.length === 2 && demoId === PRIMARY_DEMO_ID)
+        return null;
+    return { slug, demoId };
+}
+/** The theme segment for a store: `roast`, or `roast~foods`. */
+export function previewThemeParam(slug, demoId) {
+    return demoId === PRIMARY_DEMO_ID ? slug : `${slug}${DEMO_SEPARATOR}${demoId}`;
+}
+export function demoFilePath(themeDir, demoId) {
+    return demoId === PRIMARY_DEMO_ID ? join(themeDir, 'demo.json') : join(themeDir, 'demos', `${demoId}.json`);
+}
+/**
+ * Every demo store on disk: the primary first, then `demos/*.json` by name.
+ * Files whose name is not a valid id are listed too — the identity rule is
+ * what rejects them, and it can only do that if it sees them.
+ */
+export function demoFilesOf(themeDir) {
+    const files = [];
+    const primary = demoFilePath(themeDir, PRIMARY_DEMO_ID);
+    if (existsSync(primary))
+        files.push({ id: PRIMARY_DEMO_ID, path: primary });
+    const dir = join(themeDir, 'demos');
+    if (!existsSync(dir))
+        return files;
+    for (const entry of readdirSync(dir).sort()) {
+        if (!entry.endsWith('.json'))
+            continue;
+        files.push({ id: entry.slice(0, -'.json'.length), path: join(dir, entry) });
+    }
+    return files;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Theme templates — the registry contract the backend builds from
+ * (queek_backend `.agent/TASKS/frontend/storefront-theme-templates-contract.md`).
+ *
+ * A template is a demo store: `demo.json` (id `default`) or `demos/<id>.json`.
+ * The backend builds a vendor's store from ONE template's layout, keeps its
+ * declared variants, applies its chrome, dials and per-section `style`, and
+ * fills every content slot with the vendor's own material. Everything here is
+ * the shared reading of that contract — the registry generator, the registry
+ * API route, the rehost script, theme-check and the tests all call it, so the
+ * five of them cannot disagree about what a template publishes.
+ */
+/** Longest `description` a template may carry — written for a model choosing on a merchant's behalf. */
+export declare const TEMPLATE_DESCRIPTION_MAX = 300;
+/** How `themes/_bare`'s description starts — a new theme must replace it before it publishes. */
+export declare const TEMPLATE_DESCRIPTION_PLACEHOLDER = "Replace before publishing.";
+/** Where rehosted theme imagery is served — the host the backend passes through untouched. */
+export declare const THEME_ASSET_BASE = "https://media.usequeek.com/theme-assets";
+/** Per-theme record of the screenshots the rehost script has uploaded. */
+export declare const SCREENSHOT_LOCK = "screenshots.json";
+/**
+ * The screenshot file a template is judged by, relative to the theme dir:
+ * `theme.jpg` (or `theme.png`) for the primary, `demos/<id>.jpg` for the rest.
+ * `exists` decides between jpg and png for the primary, so callers pass their
+ * own file check (fs, or theme-check's context).
+ */
+export declare function screenshotFile(demoId: string, exists: (relative: string) => boolean): string;
+/**
+ * Content-addressed, like the section art: `theme-assets/{theme}/{sha256[..16]}.{ext}`.
+ * A re-captured screenshot gets a new URL, so no cache anywhere keeps showing
+ * the old picture — and the URL is known from the bytes alone, offline.
+ */
+export declare function screenshotKey(theme: string, bytes: Uint8Array, file: string): string;
+export declare function screenshotUrl(theme: string, bytes: Uint8Array, file: string): string;
+export interface TokenReach {
+    /** The theme's CSS reads the kit's colour vars (`--brand-bg`, `--brand-accent`, …). */
+    colors: boolean;
+    /** The theme's CSS reads the kit's face vars (`--font-heading` / `--font-body`). */
+    fonts: boolean;
+}
+/**
+ * Which token groups a theme actually renders from. A theme that hard-codes
+ * its palette (roast, glow, carat) publishes tokens without `color`, so the
+ * backend never promises a merchant a colour change the theme will ignore.
+ * Comments are stripped first — glow mentions `--brand-text` only in one.
+ */
+export declare function tokenReach(css: string): TokenReach;
+/**
+ * A template's tokens as the backend should apply them: the dials always
+ * (sizes, weights, spacing, radius, motion, image treatment), the palette and
+ * the faces only when the theme reads them. Undefined when nothing is left.
+ */
+export declare function templateTokens(tokens: unknown, reach: TokenReach): Record<string, unknown> | undefined;
+/**
+ * The header (or footer) variant a template names, when the theme implements
+ * one of that scope. A theme with no variants of the scope (the single-page
+ * default theme) publishes null; a name the theme does not implement also
+ * publishes null here and is a theme-check rejection, never a silent fallback.
+ */
+export declare function templateChrome(demo: unknown, scope: 'header' | 'footer', implemented: string[]): string | null;
+/**
+ * Whether a declared field is presentational — how the section looks, not
+ * what it says: a structured `enum` / `boolean` / `color` field, or a string
+ * descriptor that is an `a|b|c` enum or a `bool`. Copy, images, ids and links
+ * never qualify; neither do the query fields.
+ */
+export declare function isPresentationalField(name: string, spec: unknown): boolean;
+/** The presentational field names a variant declares. */
+export declare function presentationalFields(fields: Record<string, unknown> | undefined): string[];
+/** `{type: {variantId: fields}}` from a manifest's (or registry entry's) `variants`. */
+export declare function declaredFieldsByVariant(variants: unknown): Record<string, Record<string, Record<string, unknown>>>;
+/**
+ * A section's `style`: the presentational fields its variant declares, with
+ * the values the template set. Only primitives — never copy, images, ids or
+ * links, which the vendor's content fills. Undefined when there are none.
+ */
+export declare function sectionStyle(section: {
+    type?: unknown;
+    variant?: unknown;
+    data?: unknown;
+}, declared: Record<string, Record<string, Record<string, unknown>>>): Record<string, string | number | boolean> | undefined;
+type Copy = Record<string, unknown>;
+/**
+ * A section's `copy`: the words the template set in the fields its variant
+ * declares as text — headings, body, markdown, button labels, and the text
+ * keys of its list entries (steps, slides, FAQ items). Never images, links,
+ * ids, prices or product and collection references. The backend builds a
+ * section with no vendor facts behind it (a how-to, a statement) from this,
+ * and qee rewrites it for the vendor. Undefined when there are none.
+ */
+export declare function sectionCopy(section: {
+    type?: unknown;
+    variant?: unknown;
+    data?: unknown;
+}, declared: Record<string, Record<string, Record<string, unknown>>>): Copy | undefined;
+export {};