@ambitresearch/genie 1.3.1

package/dist/validate/full-scan.d.ts

@@ -0,0 +1,87 @@
+import type { Renderer } from "./render.js";
+/**
+ * The read slice of `KitStore` this facet needs — `listFiles` to enumerate the
+ * kit tree and `readFile` to pull each preview's bytes. Declared narrowly (not
+ * the whole `KitStore`) so a unit test injects a two-method in-memory stub,
+ * mirroring `refine.ts`'s `RefineKitStore`. A real `KitStore` (LocalFs / git
+ * host) is structurally assignable, so `server.ts` passes its shared store
+ * unchanged (the extra `readFile` fields — `encoding`, `mimeType` — are simply
+ * ignored here).
+ */
+export interface FullScanKitStore {
+    listFiles(kitId: string): Promise<Array<{
+        path: string;
+    }>>;
+    readFile(kitId: string, path: string): Promise<{
+        content: string;
+    }>;
+}
+/** AC6 — the shape `validate`'s full-scan facet returns. */
+export interface FullScanResult {
+    /** Paths whose first line fails the M3-01 `@genie` marker regex (AC3). */
+    markerMissing: string[];
+    /** Paths whose rendered content height is below `meta.json`'s
+     * `renderCheck.minHeight` (default 80px) (AC4). */
+    thin: string[];
+    /** Paths whose render perceptually hashes the same as another path's (AC5). */
+    variantsIdentical: string[];
+    /** Total `.html` files inspected — i.e. successfully read (AC6). */
+    total: number;
+    /** `markerMissing.length + thin.length + variantsIdentical.length` (AC6). */
+    bad: number;
+}
+/** Injected dependencies for {@link fullScan}. */
+export interface FullScanDeps {
+    /** Read port over the kit (AC3 enumerate + read). Required. */
+    kitStore: FullScanKitStore;
+    /**
+     * The one headless renderer reused across the scan (AC4/AC5), or `null` to
+     * run marker-only (graceful degradation — see the module doc). The caller
+     * owns this instance's lifecycle (create once per scan, `close()` after).
+     */
+    renderer: Renderer | null;
+    /** pHash tolerance override (bits) — defaults to `phash.ts`'s calibrated
+     * `DEFAULT_TOLERANCE_BITS`. Exposed for tuning/tests. */
+    toleranceBits?: number;
+    /** Hue-veto color tolerance override (L1 over mean ink RGB, DRO-717) —
+     * defaults to `phash.ts`'s calibrated `DEFAULT_COLOR_TOLERANCE_L1`. Exposed
+     * for tuning/tests; the veto only ever REMOVES a blockhash pairing, so raising
+     * this loosens the hue check back toward blockhash-only behavior. */
+    colorToleranceL1?: number;
+}
+/** The `validate` verb's input (AC2). `planId` is accepted per the verb's
+ * declared `validate({ kitId, planId? })` signature (a scan MAY run mid-write-
+ * sequence) but is not otherwise consumed by this facet — no AC ties scan
+ * behavior to it, and the full-kit scan reads the committed readable surface. */
+export interface FullScanInput {
+    kitId: string;
+    planId?: string;
+}
+/**
+ * Run genie's full validator suite (AC3–AC6) against every readable `.html`
+ * file in `input.kitId`.
+ *
+ * Two passes:
+ *   1. **Read + marker (AC3).** List the kit, keep `.html` paths (sorted), read
+ *      each. A path that `listFiles` advertised but `readFile` can't return
+ *      (a race with a concurrent delete, a permission error) is SKIPPED
+ *      entirely — not counted toward `total`, not reported as `markerMissing`
+ *      (asserting a registration-contract violation on bytes you can't read
+ *      would be a false positive). Every successfully-read file counts toward
+ *      `total`; those whose first line fails the `@genie` regex land in
+ *      `markerMissing`.
+ *   2. **Render → thin + variants (AC4/AC5).** When a renderer is present,
+ *      render EVERY readable file (including marker-missing ones — a card can be
+ *      both unregistered AND thin, and each finding is reported independently),
+ *      measure content height against the per-component `minHeight`, and
+ *      perceptual-hash the screenshot for cross-file duplicate clustering. A
+ *      single file that fails to render is tolerated (skipped from thin/variants)
+ *      rather than aborting the whole scan.
+ *
+ * `bad` is the literal `markerMissing.length + thin.length +
+ * variantsIdentical.length` the spec defines — the arrays MAY overlap (a
+ * marker-missing thin card counts in both), matching the M1-12 counter facet's
+ * `bad` field this shares a persistence path with.
+ */
+export declare function fullScan(deps: FullScanDeps, input: FullScanInput): Promise<FullScanResult>;
+//# sourceMappingURL=full-scan.d.ts.map

package/dist/validate/full-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-scan.d.ts","sourceRoot":"","sources":["../../src/validate/full-scan.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;uDACmD;IACnD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B;6DACyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;yEAGqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;iFAGiF;AACjF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA2LD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAqFhG"}

package/dist/validate/full-scan.js

@@ -0,0 +1,299 @@
+/**
+ * `validate`'s full-scan facet (M3-04 / DRO-260): the heavyweight walk that
+ * runs the `@genie` marker check (M3-01), the "thin render" check, and the
+ * "variants identical" perceptual-hash check across a kit's every `.html`
+ * file and returns structured findings (D-A: this is one facet of the single
+ * `validate` verb; the counter-persistence facet is M1-12 / `validate.ts`).
+ *
+ * Orchestration only — the individual checks are pure/DI'd modules this file
+ * composes:
+ *   - `validate/marker.ts` (M3-01, already shipped)          → `markerMissing`
+ *   - `validate/render.ts`'s injectable {@link Renderer}      → `thin` + the
+ *     screenshots `variantsIdentical` hashes
+ *   - `validate/phash.ts` (this issue)                        → `variantsIdentical`
+ *
+ * ── Dependency injection: caller owns the seams (and the browser lifecycle) ───
+ * `fullScan` takes a {@link FullScanDeps} bag — a `FullScanKitStore` (the read
+ * slice of `KitStore`) and a `Renderer | null` — exactly as `refine.ts` takes
+ * a `RefineKitStore`/`RegionCropper`. The CALLER (the `validate` MCP tool, or a
+ * test) creates the one headless-Chromium `Renderer` reused across the whole
+ * scan (AC7's < 5 s / 50-component budget) and is responsible for `close()`-ing
+ * it afterward; `fullScan` never closes a renderer it did not create. Unit
+ * tests inject an in-memory store + a stub renderer, so the suite runs fully
+ * offline with no Playwright/Chromium.
+ *
+ * ── Graceful degradation (renderer === null) ─────────────────────────────────
+ * AC4 (thin) and AC5 (variantsIdentical) need a real render; Playwright is an
+ * OPTIONAL peer dependency (see `render.ts`). When the injected renderer is
+ * `null` (Playwright/Chromium unavailable — a stripped install, a CI runner
+ * missing the browser or its OS libs), the scan still returns `markerMissing`
+ * (pure regex) and `total`, with `thin`/`variantsIdentical` empty — rather than
+ * failing the whole `validate` call over an environment gap. Same posture as
+ * `refine.ts`'s AC7 region crop degrading to no image.
+ *
+ * ── Read-only: never perturbs card bytes (RFC G-5) ───────────────────────────
+ * Every check reads bytes the store already holds and renders them in a
+ * throwaway page; nothing here writes to the kit. `validate` is a read-side
+ * verb, so the G-5 "cards byte-identical across vehicles" guarantee is
+ * structurally impossible to violate from this module.
+ */
+import { validateMarker, extractViewport } from "./marker.js";
+import { computePHash, computeColorSignature, findDuplicateClusters, } from "./phash.js";
+/** Default "thin" gate (AC4) when a component's `meta.json` doesn't specify
+ * `renderCheck.minHeight`. */
+const DEFAULT_MIN_HEIGHT = 80;
+/** Render viewport used for both the thin-height measurement and the
+ * perceptual-hash screenshot when a component names NEITHER an `@genie`
+ * marker `viewport="WxH"` token NOR a `meta.json` `viewport` override — the
+ * last-resort fallback, same default `refine.ts`'s `deriveRenderViewport`
+ * falls back to, so a kit that specifies no size anywhere still gets a
+ * consistent, reasonably-sized render across every tool that renders it.
+ *
+ * ── DRO-711 QA finding: this is now the THIRD-choice source, not the second ──
+ * Real-Chromium QA (DRO-711, post-merge hardening of DRO-260/PR #152) found
+ * that `conjure.ts` — genie's only real component-authoring path — never
+ * synthesizes a `meta.json` itself; the LLM system prompt only *encourages*
+ * one ("You may also add … a `meta.json`") and the output JSON Schema does
+ * NOT require it (`files` needs just one `<Name>.html` match). So in
+ * practice, on any kit whose model output omitted `meta.json` — the common
+ * case, not an edge case — the OLD code (which read `meta.json` only, never
+ * the marker) silently rendered every card at this generic 400×300 canvas
+ * regardless of the component's real declared size. Two confirmed effects:
+ *   - **Genuine thin false positives on responsive/percentage-sized content.**
+ *     A card whose body uses `width: 100%` (or similar) wraps its text
+ *     differently — and so measures a genuinely different `contentHeight` —
+ *     depending on which viewport it's rendered at. A 240×120-declared card
+ *     measured 120px tall at its OWN size but only 72px (under the 80px
+ *     `DEFAULT_MIN_HEIGHT`) forced into the old hardcoded 400×300 canvas —
+ *     a real, viewport-CAUSED thin misclassification, confirmed on real
+ *     Chromium renders.
+ *   - **AC5 pHash dilution.** The screenshot fed to `computePHash` is the
+ *     WHOLE canvas, so an oversized, mostly-blank canvas shrinks a small
+ *     component's contribution to the block-grid signal. A legitimately-
+ *     distinct outline-vs-filled button variant hashed only 4 bits apart (AT
+ *     `DEFAULT_TOLERANCE_BITS`, not above it — a false "identical" pairing)
+ *     at 400×300, vs. 12 bits apart when rendered at the marker's own
+ *     declared 320×96.
+ *   (NOT claimed: that this fix changes the thin verdict for every small,
+ *   FIXED-size element, e.g. a single-line button with hardcoded padding —
+ *   that box measures the same height regardless of the surrounding canvas,
+ *   confirmed on real renders. Whether `DEFAULT_MIN_HEIGHT` itself is well
+ *   calibrated for small-but-legitimate fixed-size components is a SEPARATE,
+ *   still-open question a DRO-711 follow-up issue tracks — this fix only
+ *   corrects which viewport reaches the renderer, not the 80px threshold.)
+ *
+ * The fix: `extractViewport` (already shipped by M3-01's `validate/marker.ts`,
+ * but — until this fix — used only by this module's own tests; production
+ * code never called it) reads the marker line's OWN `viewport="WxH"` token —
+ * present on every well-formed `@genie` card, because the system prompt asks
+ * the model for one. That becomes the primary viewport source here; a
+ * `meta.json` `viewport` (when the model DID emit one) still wins as an
+ * explicit override, since `meta.json` is the intentionally-mutable "override
+ * the marker" surface (RFC §7.3) — this is NOT the same precedence
+ * `manifest/compiler.ts`'s `compileManifest` uses for its own `viewport`
+ * field, which reads the marker token exclusively and never lets a sibling
+ * `meta.json` supersede it (`meta.json` there only supplies `subtitle`/`tags`);
+ * two different modules answering two different questions ("what do we
+ * render at" vs. "what do we list the card's declared size as") are free to
+ * resolve viewport precedence differently, and do. `refine.ts`'s
+ * `deriveRenderViewport` is a third, independent precedent: it reads
+ * `meta.json` only and has no marker fallback at all. `DEFAULT_VIEWPORT` here
+ * is the last resort for the rare marker with no viewport attribute at all. */
+const DEFAULT_VIEWPORT = { width: 400, height: 300 };
+/**
+ * Resolve a component's `{ minHeight, viewport }` for the render pass.
+ *
+ * Precedence (DRO-711 fix — see {@link DEFAULT_VIEWPORT}'s doc for the real-
+ * render QA evidence behind this order):
+ *   1. `meta.json`'s `viewport` / `renderCheck.minHeight`, when present and
+ *      well-formed — an explicit per-component override always wins.
+ *   2. The `@genie` marker's own `viewport="WxH"` token (`markerFirstLine`,
+ *      via `extractViewport`) — present on every well-formed card in
+ *      practice (the system prompt asks the model for one), so this is the
+ *      REALISTIC default, not the generic fallback. Used for viewport only;
+ *      the marker convention has no `minHeight` attribute, so `minHeight`
+ *      still falls through to step 3 unless `meta.json` set it.
+ *   3. `DEFAULT_VIEWPORT` / `DEFAULT_MIN_HEIGHT` — the last-resort constants,
+ *      now reached only when NEITHER a marker viewport NOR a meta.json
+ *      viewport is available (a marker with no `viewport` attribute at all).
+ *
+ * Each field defaults INDEPENDENTLY at every step — a broken `minHeight`
+ * doesn't discard a good `viewport` and vice-versa.
+ */
+function parseComponentMeta(raw, markerFirstLine) {
+    const markerViewport = extractViewport(markerFirstLine);
+    const result = {
+        minHeight: DEFAULT_MIN_HEIGHT,
+        viewport: markerViewport ? { ...markerViewport } : { ...DEFAULT_VIEWPORT },
+    };
+    if (raw === undefined)
+        return result;
+    try {
+        const parsed = JSON.parse(raw);
+        const minHeight = parsed.renderCheck?.minHeight;
+        if (typeof minHeight === "number" && Number.isFinite(minHeight) && minHeight >= 0) {
+            result.minHeight = minHeight;
+        }
+        const w = parsed.viewport?.width;
+        const h = parsed.viewport?.height;
+        if (typeof w === "number" &&
+            typeof h === "number" &&
+            Number.isFinite(w) &&
+            Number.isFinite(h) &&
+            w > 0 &&
+            h > 0) {
+            result.viewport = { width: w, height: h };
+        }
+    }
+    catch {
+        // Malformed meta.json — keep whatever step 1/2 already resolved.
+    }
+    return result;
+}
+/** Derive a `.html` file's sibling `meta.json` kit-relative path — same
+ * directory, fixed basename (the `components/<group>/<Name>/meta.json`
+ * convention every M3-adjacent module assumes, e.g. `manifest/compiler.ts`'s
+ * sibling-read). A root-level `.html` (no `/`) maps to a root `meta.json`. */
+function siblingMetaPath(htmlPath) {
+    const lastSlash = htmlPath.lastIndexOf("/");
+    const dir = lastSlash === -1 ? "" : htmlPath.slice(0, lastSlash + 1);
+    return `${dir}meta.json`;
+}
+/** Read `path` from the kit, tolerating absence (or any other read failure) as
+ * `undefined` — every caller here treats the file as optional/best-effort. */
+async function readOptional(store, kitId, path) {
+    try {
+        const file = await store.readFile(kitId, path);
+        return file.content;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Simple bounded-concurrency map — renders are I/O + CPU bound in a real
+ * browser process, so unbounded `Promise.all` over a large kit would spin up
+ * far more concurrent pages than helps; a small worker pool keeps AC7's < 5 s
+ * / 50-component budget without serializing every render either. */
+async function mapWithConcurrency(items, concurrency, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    }
+    const workerCount = Math.max(1, Math.min(concurrency, items.length));
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}
+/** Render concurrency for the thin/pHash pass (see {@link mapWithConcurrency}'s doc). */
+const RENDER_CONCURRENCY = 6;
+/** Stable lexicographic sort (ASCII) for deterministic finding arrays. */
+function byPath(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Run genie's full validator suite (AC3–AC6) against every readable `.html`
+ * file in `input.kitId`.
+ *
+ * Two passes:
+ *   1. **Read + marker (AC3).** List the kit, keep `.html` paths (sorted), read
+ *      each. A path that `listFiles` advertised but `readFile` can't return
+ *      (a race with a concurrent delete, a permission error) is SKIPPED
+ *      entirely — not counted toward `total`, not reported as `markerMissing`
+ *      (asserting a registration-contract violation on bytes you can't read
+ *      would be a false positive). Every successfully-read file counts toward
+ *      `total`; those whose first line fails the `@genie` regex land in
+ *      `markerMissing`.
+ *   2. **Render → thin + variants (AC4/AC5).** When a renderer is present,
+ *      render EVERY readable file (including marker-missing ones — a card can be
+ *      both unregistered AND thin, and each finding is reported independently),
+ *      measure content height against the per-component `minHeight`, and
+ *      perceptual-hash the screenshot for cross-file duplicate clustering. A
+ *      single file that fails to render is tolerated (skipped from thin/variants)
+ *      rather than aborting the whole scan.
+ *
+ * `bad` is the literal `markerMissing.length + thin.length +
+ * variantsIdentical.length` the spec defines — the arrays MAY overlap (a
+ * marker-missing thin card counts in both), matching the M1-12 counter facet's
+ * `bad` field this shares a persistence path with.
+ */
+export async function fullScan(deps, input) {
+    const { kitStore, renderer } = deps;
+    const { kitId } = input;
+    // ── Pass 1: enumerate + read + marker check (AC3) ───────────────────────────
+    const entries = await kitStore.listFiles(kitId);
+    const htmlPaths = entries
+        .map((e) => e.path)
+        .filter((p) => p.endsWith(".html"))
+        .sort(byPath);
+    const markerMissing = [];
+    /** Successfully-read previews carried into the render pass. */
+    const readable = [];
+    for (const path of htmlPaths) {
+        const content = await readOptional(kitStore, kitId, path);
+        if (content === undefined)
+            continue; // unreadable → not inspected, not counted
+        readable.push({ path, content });
+        if (!validateMarker(path, content).ok)
+            markerMissing.push(path);
+    }
+    // htmlPaths was sorted, so markerMissing is already ascending — keep the sort
+    // explicit so the guarantee survives any future reordering of pass 1.
+    markerMissing.sort(byPath);
+    const total = readable.length;
+    // ── Pass 2: render → thin (AC4) + variantsIdentical (AC5) ───────────────────
+    const thin = [];
+    let variantsIdentical = [];
+    if (renderer) {
+        const rendered = await mapWithConcurrency(readable, RENDER_CONCURRENCY, async ({ path, content }) => {
+            const metaRaw = await readOptional(kitStore, kitId, siblingMetaPath(path));
+            // DRO-711 fix: pass the preview's own first line so parseComponentMeta
+            // can prefer its marker `viewport="WxH"` token over the generic
+            // DEFAULT_VIEWPORT when meta.json is absent/silent on viewport (see
+            // parseComponentMeta's doc for why this is the common case, not an
+            // edge case). `content.split("\n", 1)[0]` mirrors validateMarker's own
+            // first-line extraction above.
+            const firstLine = content.split("\n", 1)[0] ?? "";
+            const meta = parseComponentMeta(metaRaw, firstLine);
+            try {
+                const card = await renderer.render(content, meta.viewport);
+                return { path, minHeight: meta.minHeight, card };
+            }
+            catch {
+                // A single file that fails to render (malformed markup crashing the
+                // page, a screenshot timeout) must not abort the scan — drop its
+                // AC4/AC5 contribution. It still got its AC3 marker check + total above.
+                return null;
+            }
+        });
+        for (const r of rendered) {
+            if (r && r.card.contentHeight < r.minHeight)
+                thin.push(r.path);
+        }
+        thin.sort(byPath);
+        const hashedEntries = [];
+        for (const r of rendered) {
+            if (r) {
+                // DRO-717: carry a hue signature alongside the (hue-blind) blockhash so
+                // findDuplicateClusters can veto a same-layout / different-fill pair
+                // (e.g. a primary/danger/success button set) that the blockhash alone
+                // would falsely cluster. computeColorSignature returns undefined for a
+                // blank/near-white render, in which case the veto abstains for that entry.
+                hashedEntries.push({
+                    path: r.path,
+                    hash: computePHash(r.card.image),
+                    color: computeColorSignature(r.card.image),
+                });
+            }
+        }
+        variantsIdentical = findDuplicateClusters(hashedEntries, deps.toleranceBits, deps.colorToleranceL1);
+    }
+    const bad = markerMissing.length + thin.length + variantsIdentical.length;
+    return { markerMissing, thin, variantsIdentical, total, bad };
+}
+//# sourceMappingURL=full-scan.js.map

package/dist/validate/full-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-scan.js","sourceRoot":"","sources":["../../src/validate/full-scan.ts"],"names":[],"mappings":"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"}

package/dist/validate/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public re-export barrel for genie's `@genie` marker validator (M3-01 / AC6).
+ *
+ * Mirrors the existing `store/index.ts` / `plans/index.ts` barrel pattern:
+ * downstream consumers (the M3-02 watcher, the M3-03 manifest compiler, the
+ * M3-04 `validate` full-scan facet, and any future consumer outside this
+ * directory) import from `../validate/index.js` rather than reaching into
+ * `./marker.js` directly, so the module's internal file layout can change
+ * without breaking callers.
+ */
+export { MARKER_REGEX, validateMarker, extractViewport, type MarkerValidationResult, type MarkerViewport, } from "./marker.js";
+export { fullScan, type FullScanDeps, type FullScanInput, type FullScanResult, type FullScanKitStore, } from "./full-scan.js";
+export { createDefaultRenderer, type Renderer, type RenderedCard } from "./render.js";
+export { computePHash, computeColorSignature, colorDistanceL1, hammingDistance, findDuplicateClusters, DEFAULT_TOLERANCE_BITS, DEFAULT_COLOR_TOLERANCE_L1, type RGBAImage, type HashedEntry, type ColorSignature, } from "./phash.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/validate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EACL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC"}

package/dist/validate/index.js

@@ -0,0 +1,18 @@
+/**
+ * Public re-export barrel for genie's `@genie` marker validator (M3-01 / AC6).
+ *
+ * Mirrors the existing `store/index.ts` / `plans/index.ts` barrel pattern:
+ * downstream consumers (the M3-02 watcher, the M3-03 manifest compiler, the
+ * M3-04 `validate` full-scan facet, and any future consumer outside this
+ * directory) import from `../validate/index.js` rather than reaching into
+ * `./marker.js` directly, so the module's internal file layout can change
+ * without breaking callers.
+ */
+export { MARKER_REGEX, validateMarker, extractViewport, } from "./marker.js";
+// M3-04 (DRO-260) — the full-scan facet's orchestrator + its render/pHash
+// helpers, surfaced here so `tools/validate.ts` (and any future consumer)
+// composes them through the barrel rather than reaching into the files.
+export { fullScan, } from "./full-scan.js";
+export { createDefaultRenderer } from "./render.js";
+export { computePHash, computeColorSignature, colorDistanceL1, hammingDistance, findDuplicateClusters, DEFAULT_TOLERANCE_BITS, DEFAULT_COLOR_TOLERANCE_L1, } from "./phash.js";
+//# sourceMappingURL=index.js.map

package/dist/validate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,GAGhB,MAAM,aAAa,CAAC;AAErB,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,OAAO,EACL,QAAQ,GAKT,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoC,MAAM,aAAa,CAAC;AACtF,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,GAI3B,MAAM,YAAY,CAAC"}

package/dist/validate/marker.d.ts

@@ -0,0 +1,89 @@
+/**
+ * M3-01 (DRO-257) — genie's own first-line `@genie` marker validator.
+ *
+ * This is genie's **registration contract** for a component preview file:
+ * every `<Name>.html` / `preview.html`
+ * must open with a comment matching {@link MARKER_REGEX}, e.g.
+ *
+ *   <!-- @genie group="actions" viewport="400x200" -->
+ *
+ * A missing or malformed first line fails the build with `MARKER_MISSING`
+ * (AC4). The regex intentionally permits arbitrary additional attributes
+ * after `group` — `viewport`, `name`, `subtitle`, … — so {@link
+ * validateMarker} accepts any of them without needing to enumerate the full
+ * attribute set; {@link extractViewport} is the one attribute the manifest
+ * compiler (M3-03) and `list_components` (M1-15) need decomposed into
+ * `{ width, height }` integers (AC5), so it gets its own narrow helper
+ * rather than a general attribute parser.
+ *
+ * This module is pure and offline — no filesystem, no network — so both
+ * `KitStore` adapters (local FS, git host) and the future watcher (M3-02) /
+ * manifest compiler (M3-03) / `validate` full-scan facet (M3-04) can call it
+ * against whatever bytes they already have in hand.
+ *
+ * `MARKER_REGEX` is genie's **native** marker — do not substitute Anthropic's
+ * `@dsCard` shape here (CLAUDE.md hard rule 1 / AGENTS.md hard rule 1); that
+ * regex lives only in a future opt-in interop adapter.
+ */
+/**
+ * AC2 — the canonical `@genie` first-line marker regex. This is the single source of truth for the
+ * pattern: `../llm/validate.ts`'s `MARKER_REGEX_M2_07` re-exports this
+ * constant (it previously carried its own temporary duplicate literal,
+ * shipped ahead of this issue landing) rather than redefining it.
+ *
+ * Deliberately permissive after `group="…"`: `[^>]*` allows any further
+ * attributes (`viewport`, `name`, `subtitle`, …) in any order, so adding a
+ * new optional attribute to the marker convention never requires touching
+ * this regex.
+ */
+export declare const MARKER_REGEX: RegExp;
+/** Discriminated-union result of {@link validateMarker} (AC4). */
+export type MarkerValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: "MARKER_MISSING";
+    path: string;
+};
+/**
+ * AC1/AC4 — validate that `content`'s first line carries genie's `@genie`
+ * marker. `path` is carried through into the failure result (not used for
+ * validation itself) so a caller batching many files can report exactly
+ * which one failed, matching the `[MARKER_MISSING] <relpath>` build-failure
+ * shape the `ERR_MARKER_MISSING` contract describes.
+ *
+ * Uses `content.split("\n", 1)[0]` per the spec's implementation note — the
+ * `limit` argument means `split` stops after producing one element, so this
+ * never allocates an array for the rest of the file. A trailing `\r` (CRLF
+ * line endings) stays attached to that first element; `MARKER_REGEX` has no
+ * trailing anchor, so a `\r` after the marker's `-->` does not affect the
+ * match (verified by the CRLF fixture in `marker.test.ts`).
+ */
+export declare function validateMarker(path: string, content: string): MarkerValidationResult;
+/** Integer `{ width, height }` pair extracted from a marker's `viewport` attribute (AC5). */
+export interface MarkerViewport {
+    width: number;
+    height: number;
+}
+/**
+ * AC5 — optional attribute parse: extract `viewport="WxH"` from a marker
+ * line into a structured `{ width, height }` (both integers). Returns
+ * `undefined` when the line has no `viewport` attribute, or its value isn't
+ * the strict `<digits>x<digits>` shape (e.g. a named token like `"desktop"`
+ * — `list_components`/the manifest compiler keep that case as an opaque
+ * string rather than a decomposed size).
+ *
+ * Deliberately independent of {@link validateMarker}: a caller can ask "does
+ * this line have a parseable viewport" without first requiring the whole
+ * marker to be well-formed, and the manifest compiler (M3-03) needs this
+ * extraction on its own, already-validated lines.
+ *
+ * The `(?:^|\s)` lookbehind-by-alternation requires `viewport` to start a
+ * fresh attribute (preceded by whitespace, or the very start of the string)
+ * rather than merely `\b`-bordering the previous character — `\b` alone
+ * would also fire mid-token on a hyphen (e.g. a hypothetical `data-viewport`
+ * attribute), which is not part of genie's marker convention and must not be
+ * mistaken for it.
+ */
+export declare function extractViewport(firstLine: string): MarkerViewport | undefined;
+//# sourceMappingURL=marker.d.ts.map

package/dist/validate/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/validate/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAA2C,CAAC;AAErE,kEAAkE;AAClE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAMpF;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAI7E"}

package/dist/validate/marker.js

@@ -0,0 +1,87 @@
+/**
+ * M3-01 (DRO-257) — genie's own first-line `@genie` marker validator.
+ *
+ * This is genie's **registration contract** for a component preview file:
+ * every `<Name>.html` / `preview.html`
+ * must open with a comment matching {@link MARKER_REGEX}, e.g.
+ *
+ *   <!-- @genie group="actions" viewport="400x200" -->
+ *
+ * A missing or malformed first line fails the build with `MARKER_MISSING`
+ * (AC4). The regex intentionally permits arbitrary additional attributes
+ * after `group` — `viewport`, `name`, `subtitle`, … — so {@link
+ * validateMarker} accepts any of them without needing to enumerate the full
+ * attribute set; {@link extractViewport} is the one attribute the manifest
+ * compiler (M3-03) and `list_components` (M1-15) need decomposed into
+ * `{ width, height }` integers (AC5), so it gets its own narrow helper
+ * rather than a general attribute parser.
+ *
+ * This module is pure and offline — no filesystem, no network — so both
+ * `KitStore` adapters (local FS, git host) and the future watcher (M3-02) /
+ * manifest compiler (M3-03) / `validate` full-scan facet (M3-04) can call it
+ * against whatever bytes they already have in hand.
+ *
+ * `MARKER_REGEX` is genie's **native** marker — do not substitute Anthropic's
+ * `@dsCard` shape here (CLAUDE.md hard rule 1 / AGENTS.md hard rule 1); that
+ * regex lives only in a future opt-in interop adapter.
+ */
+/**
+ * AC2 — the canonical `@genie` first-line marker regex. This is the single source of truth for the
+ * pattern: `../llm/validate.ts`'s `MARKER_REGEX_M2_07` re-exports this
+ * constant (it previously carried its own temporary duplicate literal,
+ * shipped ahead of this issue landing) rather than redefining it.
+ *
+ * Deliberately permissive after `group="…"`: `[^>]*` allows any further
+ * attributes (`viewport`, `name`, `subtitle`, …) in any order, so adding a
+ * new optional attribute to the marker convention never requires touching
+ * this regex.
+ */
+export const MARKER_REGEX = /^<!--\s*@genie\s+group="[^"]*"[^>]*-->/;
+/**
+ * AC1/AC4 — validate that `content`'s first line carries genie's `@genie`
+ * marker. `path` is carried through into the failure result (not used for
+ * validation itself) so a caller batching many files can report exactly
+ * which one failed, matching the `[MARKER_MISSING] <relpath>` build-failure
+ * shape the `ERR_MARKER_MISSING` contract describes.
+ *
+ * Uses `content.split("\n", 1)[0]` per the spec's implementation note — the
+ * `limit` argument means `split` stops after producing one element, so this
+ * never allocates an array for the rest of the file. A trailing `\r` (CRLF
+ * line endings) stays attached to that first element; `MARKER_REGEX` has no
+ * trailing anchor, so a `\r` after the marker's `-->` does not affect the
+ * match (verified by the CRLF fixture in `marker.test.ts`).
+ */
+export function validateMarker(path, content) {
+    const firstLine = content.split("\n", 1)[0] ?? "";
+    if (MARKER_REGEX.test(firstLine)) {
+        return { ok: true };
+    }
+    return { ok: false, code: "MARKER_MISSING", path };
+}
+/**
+ * AC5 — optional attribute parse: extract `viewport="WxH"` from a marker
+ * line into a structured `{ width, height }` (both integers). Returns
+ * `undefined` when the line has no `viewport` attribute, or its value isn't
+ * the strict `<digits>x<digits>` shape (e.g. a named token like `"desktop"`
+ * — `list_components`/the manifest compiler keep that case as an opaque
+ * string rather than a decomposed size).
+ *
+ * Deliberately independent of {@link validateMarker}: a caller can ask "does
+ * this line have a parseable viewport" without first requiring the whole
+ * marker to be well-formed, and the manifest compiler (M3-03) needs this
+ * extraction on its own, already-validated lines.
+ *
+ * The `(?:^|\s)` lookbehind-by-alternation requires `viewport` to start a
+ * fresh attribute (preceded by whitespace, or the very start of the string)
+ * rather than merely `\b`-bordering the previous character — `\b` alone
+ * would also fire mid-token on a hyphen (e.g. a hypothetical `data-viewport`
+ * attribute), which is not part of genie's marker convention and must not be
+ * mistaken for it.
+ */
+export function extractViewport(firstLine) {
+    const match = /(?:^|\s)viewport="(\d+)x(\d+)"/.exec(firstLine);
+    if (!match)
+        return undefined;
+    return { width: Number(match[1]), height: Number(match[2]) };
+}
+//# sourceMappingURL=marker.js.map

package/dist/validate/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.js","sourceRoot":"","sources":["../../src/validate/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,wCAAwC,CAAC;AAOrE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,OAAe;IAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;AACrD,CAAC;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,KAAK,GAAG,gCAAgC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC"}