# Beauty Design Compiler
Implementation snapshot: July 27, 2026
## V2 corrective implementation status
This document retains the V1 architecture and evidence below as historical context. The current
corrective implementation is the Beauty Design Compiler V2 aesthetic-convergence pipeline:
```text
SiteSpec
+ persistent design identity
+ content/media profile
+ exactly one versioned art-direction capsule
-> deterministic candidate tournament
-> hard policy, lineage, accessibility, and content gates
-> production-equivalent browser rendering
-> quality, capsule-adherence, and distinctness evaluation
-> selected immutable manifest
```
The V2 evidence set contains 16 art-direction capsules, 128 accepted fictional-fixture pages,
512 exact-viewport browser screenshots, 52 directly inspected evidence records, and 256 axe-core
runs. All accepted pages use packaged self-hosted fonts and resolved production-equivalent fixture
assets; the V1 font and asset-resolver limitations described later in this document have therefore
been closed for this evidence set. The final release summary, perceptual-similarity report, and
hosted smoke evidence remain the authoritative source for whether the complete V2 gate passed.
The renderer-style migration is committed for all 128 accepted pages. The post-migration evidence
is bound to that migration report and the exact migrated HTML: 512/512 Chrome screenshots and
runtime records completed with both intended font faces loaded, zero failed resource requests,
zero broken links, zero console or page errors, and zero horizontal overflow. The required
four-viewport direct-inspection set passed 52/52, and 256/256 mobile/desktop axe-core runs passed
the finalizer. The optional Responses screenshot critic produced no accepted result: the path was
unavailable under the configured account controls, and seven staged calls were discarded
atomically. No human-participant or Responses-critic result is claimed.
The public artifact is a sanitized, non-indexed QA exhibit. It is not a customer site, a human
preference study, a production customer deployment, or permission to relax `DRY_RUN`, the global
kill switch, feature freezes, billing controls, outreach controls, DNS controls, or deployment
gates.
This document describes the implemented deterministic beauty-template system in the current
repository and the local evidence collected for it. The compiler, durable design-identity
repository, private-preview integration, static renderer, protected Generator Lab, fixture-media
pipeline, and QA matrix are present and tested. The browser evidence is local preproduction
evidence; it is not evidence that a customer site has been deployed.
All businesses, people, reviews, addresses, images, and design concepts under
`fixtures/beauty-design-compiler.ts` and
`docs/templates/beauty-design-compiler/concepts/` are fictional internal references. They are not
customers, prospects, testimonials, portfolio evidence, or representations of real businesses.
Generated and procedural assets are decorative only and must never be treated as evidence.
## 1. Outcome and invariants
The implemented core follows this contract:
```text
approved business facts
-> non-claim presentation signals
-> persistent design seed + generator version
-> constrained recipe and axis resolution
-> validated BeautyDesignManifest
-> immutable manifest hash and SiteSpec presentation reference
-> static renderer candidate
-> information coverage and QA
-> separately authorized activation
```
The non-negotiable invariants are:
- SiteSpec remains the source of truth for every customer-facing fact.
- The compiler chooses presentation; it does not author business claims.
- A 256-bit design seed is created once and persisted before compilation.
- Rendering uses no runtime randomness.
- The same supported generator version, seed, candidate nonce, presentation intent, and content
profile produce the same manifest.
- Normal content updates reuse the accepted presentation reference.
- A design cannot change merely because hours, prices, services, or contact details changed.
- Explicit design overrides are high-level registry choices, never arbitrary CSS.
- A manifest is accepted only after schema and compatibility validation.
- Exact and first-viewport collisions are rejected within a bounded search.
- Generated imagery is always marked `role: "decorative"` and
`documentaryEvidence: false`.
- No lead discovery, crawling, outreach, billing, DNS, hosting, deployment, or production gate is
controlled by this compiler.
## 2. Current implementation status
| Area | Current state | Evidence and release interpretation |
| ------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Contracts | Implemented | Strict Zod schemas are exported from `packages/contracts/src/beauty-design.ts`. |
| Seed and PRNG | Implemented and tested | Web Crypto supplies a persistent 256-bit seed; xoshiro256\*\* supplies deterministic selection. |
| Grammar and recipes | Implemented and tested | Sixteen recipes, four variants, and curated axis registries use shared semantic components. |
| Compatibility | Implemented and tested | Inspectable rule traces reject incoherent or content-ineligible combinations. |
| Fingerprints and collision search | Implemented and validated over 1,000 seeds | All 1,000 full and first-viewport fingerprints were unique; the bounded search did not exhaust. |
| SiteSpec adapter and presentation pin | Implemented and tested | Approved signals feed the compiler; immutable manifest identity and SHA-256 are pinned to SiteSpec. |
| Durable persistence | Migration and D1 repository implemented and tested | Migration 0045 and the D1 repository passed isolated migration, guard, lifecycle, and collision tests. |
| Private-preview integration | Implemented and tested | The queue compiles and accepts the manifest before dispatching renderer-specific QA and private retrieval. |
| Decorative asset subsystem | Implemented and tested | Exact prompts, hashing, validation, fixture cache, provider gates, procedural fallback, and manifest adaptation are connected. |
| Static renderer | Implemented, migrated, and browser-tested | All 128 accepted fixture pages were migrated through the committed renderer path; 512 fresh Chrome captures and metrics, 256 axe runs, and 52 direct inspections passed. |
| Fictional fixtures | Implemented with local-only media guards | Fixtures cover representative and edge content shapes and cannot be admitted as customer evidence. |
| Design concepts | Implemented and compared with browser renders | Concept-to-Chrome comparison sheets and a fidelity ledger record the match and intentional deviations. |
| Beauty Generator Lab | Implemented at protected operator route `/design-lab` | It supports fixture controls, manifest and prompt inspection, seed comparison, grids, and development JSON export. |
| Production activation | Not performed, by explicit scope boundary | No customer site, outreach, billing, DNS, deployment, provider login, production gate, or paid image-generation setting changed. |
## 3. Repository architecture
### 3.1 Contracts
`packages/contracts/src/beauty-design.ts` owns:
- `BeautyPresentationSpec`
- `BeautyPresentationReference`
- `BeautyDesignIdentity`
- `BeautyContentSignals`
- `BeautyContentProfile`
- `BeautyAssetBrief`
- `BeautyDesignManifest`
- `BeautyFingerprintVector`
- `BeautyDesignCohortEntry`
- `BeautyCompatibilityTraceEntry`
- `BeautyRecipeDefinition`
- compiler result and trace schemas
`packages/contracts/src/site-platform.ts` adds an optional
`BeautyPresentationReference` to `SiteSpec` and a corresponding
`presentationIdentity` to `FrozenSiteContract`. This is backward-compatible for non-beauty and
older SiteSpecs because both fields are optional.
The reference pins:
- high-level presentation specification;
- design identity ID;
- design manifest ID;
- accepted candidate nonce;
- design fingerprint;
- canonical manifest SHA-256.
It intentionally does not place arbitrary CSS or the entire resolved token graph in SiteSpec.
### 3.2 Compiler core
`packages/commercial/src/beauty-design/` contains:
- `versions.ts`: generator, grammar, and fingerprint version constants and bounded defaults;
- `seed.ts`: seed creation and nonce-separated candidate-seed derivation;
- `prng.ts`: deterministic xoshiro256** selection;
- `content-profile.ts`: category and content-shape classification;
- `registries.ts`: recipes, typography, palettes, spacing, geometry, motifs, and motion;
- `compatibility.ts`: content and override constraints with structured trace output;
- `fingerprint.ts`: canonical hashing, weighted similarity, and nearest-candidate lookup;
- `compiler.ts`: deterministic manifest compilation and bounded uniqueness search;
- `site-spec.ts`: approved-fact signal extraction and SiteSpec presentation pinning;
- `generator-lab.ts`: fictional-fixture compilation, comparison, and bounded grid helpers;
- `assets/`: decorative brief normalization, prompting, hashing, validation, caching, provider
boundaries, manifest adaptation, and procedural fallback;
- `render/`: static component rendering, media validation, booking fallback, information coverage,
and CSS token resolution.
`packages/commercial/src/index.ts` and the package export
`@site-rescue/commercial/beauty-design` expose the current subsystem.
Durable and workflow integration lives in:
- `migrations/0045_beauty_design_compiler.sql`;
- `workers/api/src/beauty-design-repository.ts`;
- `workers/api/src/public-preview-pipeline.ts`;
- `workers/api/src/public-preview-pipeline-repository.ts`;
- `workers/api/src/public-job-consumer.ts`;
- `workers/api/src/index.ts`.
The protected operator surface is lazy-loaded from
`apps/operator-dashboard/src/pages/BeautyGeneratorLabPage.tsx` at `/design-lab`.
### 3.3 SiteSpec fields consumed
The SiteSpec adapter examines these approved `BusinessProfile` fact paths to derive layout signals:
- `displayName`
- `primaryCategory`
- `secondaryCategories`
- `services`
- `photos`
- `staff`
- `testimonials`
- `locations`
- `serviceAreas`
- `offers`
- `certifications`
- `accessibilityDetails`
- `parkingDetails`
- `faqs`
- `externalBookingUrls`
- `phoneNumbers`
- `publicEmail`
- `brandColors`
Only facts that are publishable, actively confirmed, non-conflicted, not rejected, not stale, and
rights-valid where required are counted. These counts and categories influence layout eligibility
only. The renderer reads the actual names, descriptions, prices, durations, policies, addresses,
hours, links, people, and proof from the sealed SiteSpec.
The current adapter does not manufacture an SMS number and leaves logo-legibility analysis as
`unknown` unless supplied by a future approved asset-analysis step.
## 4. Design identity lifecycle
### 4.1 Initial compile
The implemented authoritative sequence is:
1. Generate a 32-byte value with `crypto.getRandomValues`.
2. Store it as 64 lowercase hexadecimal characters before compiling.
3. Store the supported generator version with the identity.
4. Derive a candidate seed from the persistent seed and candidate nonce with SHA-256.
5. Initialize xoshiro256** from the derived candidate seed.
6. Compile a schema-valid candidate from eligible registry options.
7. Hash its high-impact design vector and first-viewport vector.
8. Compare it with the supplied cohort.
9. Increment the nonce and retry when the candidate is exact, has an identical first viewport, or
exceeds the configured similarity threshold.
10. Persist the accepted identity, nonce, trace, reservations, manifest, and manifest hash.
11. Resolve decorative assets idempotently.
12. Render and run QA.
13. Activate only through the existing approval and production gates.
The compiler itself is deliberately pure with respect to persistence. The D1 repository persists
the seed before compilation, assembles the privacy-safe cohort, records collision retries, verifies
the immutable manifest hash, reserves fingerprints, and applies optimistic authorization and
locking guards.
### 4.2 Candidate derivation
Candidate seeds are derived from:
```text
SHA-256("beauty-design-candidate-v1\n" + designSeed + "\n" + candidateNonce)
```
The original seed remains the design identity. The derived candidate seed is an internal selection
input and is not used as a substitute identity.
### 4.3 Stability under content updates
`createNextSiteSpecVersion` preserves the presentation reference for ordinary content versions and
rejects a changed reference unless the caller explicitly authorizes a template-upgrade preview.
The existing unit tests cover an hours change preserving the design and a silent presentation
reroll being refused.
The system does not call `compileBeautyDesign` for a routine phone, hours, price, link, or copy
update. A new review, gallery asset, or team member may enrich an existing section only through
deterministic behavior permitted by the pinned manifest and frozen component contract. If that
cannot be expressed without changing the manifest, it requires a controlled presentation version.
Tests confirm that phone, hours, and service updates preserve the identity and manifest.
### 4.4 Explicit regeneration
Regeneration is never an incidental rebuild. The database migration models it as:
- a new identity with purpose `REGENERATION`;
- an append-only record binding prior identity and manifest to the new identity;
- an explicit reason and requesting principal;
- optimistic concurrency against the active site design;
- no regeneration while the design is locked;
- a separately authorized activation.
`D1BeautyDesignRepository.beginRegeneration` executes this lifecycle with an explicit reason,
requesting principal, expected optimistic version, and design-lock check. Activation remains
separate from compilation and must still pass the repository's existing approval and production
gates.
## 5. Versioning and safe migration
Current versions are:
- generator: `beauty-design-generator-v1`;
- grammar: `beauty-design-grammar-v1`;
- fingerprint: `beauty-design-fingerprint-v1`;
- static renderer: `beauty-static-renderer-v1`;
- atmospheric prompt: `beauty-atmospheric-prompt-v1`.
The compiler rejects an unsupported generator version rather than silently interpreting an older
identity with new rules. The manifest records generator and grammar versions. SiteSpec records a
renderer version and canonical manifest hash. Asset requests record generator, prompt, design
fingerprint, and request-hash versions.
A safe generator migration must:
1. Leave the old identity, manifest, assets, SiteSpec version, and rendered release intact.
2. Create a new controlled-migration or regeneration identity.
3. Compile against the explicitly selected new generator.
4. reserve fingerprints and persist a new immutable manifest;
5. render a preview without changing the active release;
6. run factual, functional, accessibility, performance, security, and visual QA;
7. obtain the required approval;
8. activate atomically with rollback to the prior release;
9. create a new frozen presentation reference when applicable.
No background task may rewrite an accepted manifest simply because a new registry or generator is
available. A newly discovered compatibility defect should block new publication and trigger a
controlled preview, not silently restyle an approved site.
## 6. Design grammar
### 6.1 Principal variants
- `atelier`: warm fashion-editorial composition for hair, color, and boutique studios;
- `ritual`: quiet mineral and tactile composition for spa, skincare, massage, and wellness;
- `studio`: graphic, crisp, one-accent composition for nails, brows, lashes, and expressive brands;
- `precision`: aligned, controlled, lower-radius composition for barbering, grooming, and precise
appointment services.
An explicit compatible variant wins. Otherwise, category supplies deterministic weights. The
weights favor the expected variant without making the category itself a visual claim.
### 6.2 Master recipes
The registry contains exactly sixteen shared semantic recipes.
| Variant | Recipe | Defining behavior |
| --------- | --------------------------- | --------------------------------------------------------------- |
| Atelier | `atelier-split-portrait` | Portrait or approved hero-fallback split; editorial alternation |
| Atelier | `atelier-gallery-spread` | Requires at least six gallery and three suitable images |
| Atelier | `atelier-type-canvas` | No-image-safe, typography and atmosphere led |
| Atelier | `atelier-framed-panorama` | Landscape or approved hero-fallback framing |
| Ritual | `ritual-quiet-column` | Sparse-safe, quiet progressive rhythm |
| Ritual | `ritual-asymmetric-mineral` | Restrained asymmetry with mineral atmosphere |
| Ritual | `ritual-full-bleed-pause` | Crop-safe image or approved hero fallback required |
| Ritual | `ritual-soft-diptych` | Requires two suitable real visual assets |
| Studio | `studio-lacquer-grid` | Sparse-safe graphic grid with a restrained accent |
| Studio | `studio-offset-pop` | Requires a viable real image or approved hero fallback |
| Studio | `studio-monochrome-punch` | Type-led graphic or framed composition |
| Studio | `studio-gallery-index` | Requires at least six gallery and three suitable images |
| Precision | `precision-axis` | Sparse-safe aligned technical rhythm |
| Precision | `precision-dark-frame` | Requires viable media and excludes dark-only logo assets |
| Precision | `precision-typographic-cut` | Sparse-safe type and index composition |
| Precision | `precision-toolline` | Sparse-safe procedural linework and indexed services |
Recipes configure one semantic component system. They are not copied customer-specific page
components.
### 6.3 Controlled axes
The manifest resolves:
- variant and master recipe;
- header;
- hero;
- page rhythm;
- service preview;
- gallery;
- differentiators;
- team;
- complete service menu;
- proof;
- new-client guide;
- visit;
- final action;
- footer;
- typography pairing, scales, weights, tracking, and line height;
- semantic palette and contrast;
- spacing profile and fluid values;
- geometry, border, and media framing;
- primary motif and bounded intensity;
- motion profile;
- decorative asset family;
- negative-space orientation.
High-level SiteSpec presentation preferences may request variant, recipe, intensity, spacing,
temperature, contrast, geometry, hero, typography, or accent hue. Every request remains subject to
registry and compatibility checks.
### 6.4 Curated libraries
The current registries provide:
- eight hero architectures;
- six page rhythms;
- twelve two-family typography pairings;
- sixteen semantic palettes;
- four spacing profiles;
- four geometry profiles;
- eleven restrained motifs;
- four motion profiles;
- five service-preview layouts;
- seven gallery states and layouts;
- team, proof, visit, final-action, header, and footer families.
The typography manifest records one curated display/body pairing and its declared weights. The V2
QA renderer packages and preloads the selected self-hosted display and body faces while retaining
robust fallback stacks. Post-migration Chrome evidence recorded both intended faces available and
`document.fonts.status === "loaded"` in all 512 viewport measurements, with zero measured
font-driven layout shift. Production packaging must preserve the recorded font files, license
records, preload policy, and hashes.
Palettes are exact curated values, not random hex colors. A supplied brand color is retained as
`rawBrandColor`; it does not overwrite the accessible semantic palette. A preferred accent hue
weights the nearest approved palettes instead of inventing a color.
Spacing and geometry resolve to exact semantic tokens. SiteSpec does not accept raw arbitrary
spacing or per-component CSS.
## 7. Compatibility resolver
Compatibility decisions are emitted as structured trace entries containing rule ID, axis, option,
disposition, and reason. Important rules include:
- an explicit recipe must exist and belong to the explicit variant;
- media prerequisites exclude gallery, portrait, panorama, and diptych recipes that cannot be
supported;
- only `decorative-and-hero-fallback` may satisfy a missing hero-visual requirement;
- a long business name removes condensed wordmark pairings;
- zero gallery images forces `gallery: omitted`;
- one gallery image forces a focused-single composition;
- two to five images limit the gallery to measured arrangements;
- six or more images enable richer gallery layouts;
- zero team members force omission;
- one team member forces a founder feature;
- two to four use a spacious team grid;
- five or more use a compact directory;
- zero verified reviews force proof omission;
- one or two verified reviews use a featured quotation;
- three or more enable a restrained proof grid;
- service-area, single-location, and multiple-location businesses receive distinct visit layouts;
- a single service favors focused editorial layouts;
- twenty or more services favor indexed or split menus;
- visually rich authentic media reduces expressive motif candidates;
- `precision-dark-frame` is excluded when an approved logo is only usable on a light surface;
- an explicit hero, typography, or spacing preference is rejected when unknown or incompatible.
Critical constraints are code and data, not prompt instructions. A model cannot bypass them.
## 8. Manifest contract
`BeautyDesignManifest` is strict, serializable, versioned, and deterministic. It contains:
- identity: template family, generator version, grammar version, seed, and candidate nonce;
- art direction: variant, recipe, intensity, and generated-asset policy;
- semantic composition selections;
- exact typography, color, spacing, geometry, motif, and motion values;
- zero to four normalized decorative asset briefs;
- uniqueness vector, design hash, first-viewport hash, cohort metadata, nearest score, threshold,
and bounded-exhaustion state.
The compiler returns the manifest with a separate trace:
- attempted nonces;
- compatibility decisions;
- rejected candidate fingerprints;
- whether bounded search was exhausted.
The trace is for audit and development inspection. It must not expose another customer’s content.
## 9. Uniqueness and collision prevention
### 9.1 Fingerprint vector
The full fingerprint encodes:
- variant;
- recipe;
- header;
- hero;
- page rhythm;
- typography;
- palette;
- spacing;
- geometry;
- media frame;
- motif;
- service, gallery, team, proof, visit, and closing layouts;
- footer;
- motion;
- decorative asset family;
- negative-space orientation.
It intentionally excludes raw seed and candidate nonce. Adding either would make uniqueness
measurement meaningless.
### 9.2 Weights
Structural choices carry more weight than decorative ones:
| Axis | Weight |
| ---------------------------------------- | -----: |
| Master recipe | 18 |
| Hero | 18 |
| Page rhythm | 14 |
| Typography pairing | 13 |
| Variant | 10 |
| Palette, service layout, gallery layout | 8 each |
| Header, media frame, motif, final action | 7 each |
| Decorative asset family | 6 |
| Spacing, geometry, team, proof, visit | 5 each |
| Footer, negative space | 4 each |
| Motion | 3 |
A palette change alone therefore cannot make two otherwise identical sites meaningfully unique.
### 9.3 First viewport
The first-viewport hash uses variant, recipe, header, hero, page rhythm, typography, palette, media
frame, motif, and negative space. An identical first-viewport hash is rejected even when a
below-fold axis differs.
### 9.4 Search policy
Defaults are:
- similarity threshold: `0.92`;
- candidate attempts: `48`;
- hard maximum accepted by the compiler: `128`.
The compiler compares supplied cohort entries, selects the lowest-similarity candidate as the
bounded fallback, and marks `acceptedAfterExhaustion: true` if no candidate clears all gates.
Callers must surface that state for inspection; it is not a silent success.
Production cohort assembly should use the strongest applicable privacy-safe set:
- active beauty designs globally;
- recent category designs;
- local category and market designs;
- current preview or sales batch.
Only fingerprints and vectors are required. Customer names, addresses, copy, and images must not
be included in uniqueness diagnostics.
## 10. Content-to-section behavior
The canonical semantic sequence remains:
1. header;
2. hero;
3. priority services;
4. work or results;
5. differentiators;
6. team or founder;
7. complete service menu;
8. verified proof;
9. new-client guide;
10. visit and contact;
11. final action;
12. footer.
Recipes may vary rhythm and narrow middle-section relationships, but the compiler does not perform
arbitrary page-order shuffling.
Content rules include:
- real portrait, landscape, and gallery counts gate corresponding hero architectures;
- no credible media uses a type-led or approved decorative atmosphere, never a fake person;
- one to six services can use individual emphasis;
- larger inventories use priority selection plus grouped or indexed complete menus;
- missing price, duration, consultation, or preparation data is omitted rather than invented;
- one person becomes a founder feature;
- verified-review count controls proof eligibility;
- service-area businesses never receive a fake storefront composition;
- multiple locations receive a location selector;
- booking actions resolve from actual links and contact data.
The booking resolver chooses the first safe option in this order:
1. HTTPS booking URL;
2. telephone;
3. SMS;
4. validated email.
It never emits a dead primary action. An outbound link is not treated as a completed booking.
## 11. Information parity
The renderer includes `BeautyCoverageTracker`. It collects non-empty SiteSpec bindings
and collection items, then records whether each source was:
- rendered;
- rendered through a fallback;
- intentionally omitted with a rule;
- invalid.
The report records SiteSpec path, component, section, and reason. Any approved source not claimed
by a renderer component becomes invalid.
Current critical paths, when present, include:
- display name;
- primary category;
- services;
- prices;
- hours;
- booking URLs;
- phone numbers;
- locations;
- service areas;
- accessibility details.
Static rendering fails closed when a critical value lacks rendered or fallback-rendered coverage.
This prevents a recipe from silently dropping valid critical information.
All 64 generated QA records completed information coverage with zero invalid entries. Browser
inspection also checked that every page had a live primary action, one H1, no empty conditional
section, no broken image, and no horizontal overflow. The renderer treats testimonial content as
proof only when the entry carries explicit `verified: true`; unverified strings are intentionally
omitted rather than presented as customer evidence.
## 12. Decorative asset policy
### 12.1 Evidence boundary
The following must always use authentic, rights-cleared business assets:
- staff;
- customers;
- results;
- before-and-after relationships;
- real interiors and storefronts;
- actual equipment and products;
- credentials, licenses, awards, and press;
- testimonials and reviews.
Generated or procedural content may provide only non-documentary atmosphere, material studies,
abstract reflection, texture, dividers, footer atmosphere, or social backgrounds. It must not
contain meaningful text.
Every accepted generated asset carries provenance equivalent to:
```json
{
"aiGenerated": true,
"role": "decorative",
"documentaryEvidence": false
}
```
The renderer independently rejects AI-generated media that is assigned an evidentiary role, lacks
approved decorative provenance, or belongs to another design fingerprint.
### 12.2 Manifest integration
`assets/manifest-adapter.ts` deterministically translates a manifest `BeautyAssetBrief` into the
normalized asset request without changing category or factual subject matter. Focused tests cover
brief creation, prompt determinism, hashing, cache reuse, validation, and provider/fallback gates.
Live provider spending remains disabled by the existing DRY_RUN and explicit-call controls.
### 12.3 Prompt compiler
The versioned prompt builder composes modules in this fixed order:
1. production role;
2. category-specific visual concept;
3. variant art direction;
4. palette and tonal contrast;
5. materials;
6. lighting;
7. composition;
8. negative-space and text-side requirement;
9. focal and orientation treatment;
10. detail and crop requirement;
11. explicit non-documentary purpose;
12. global and brief-specific exclusions.
The registered category families are:
- hair silk/fiber;
- hair mirror/light;
- unbranded hair tool still life;
- nail lacquer material;
- nail color objects;
- brow/lash line and curve;
- spa mineral and water;
- spa plaster and shadow;
- massage/wellness contour;
- barber metal and line;
- general reflection and material.
The global prompt foundation identifies the output as atmospheric art rather than business
evidence. The exclusion module prohibits people, faces, hands, skin, fake locations, fake results,
medical procedures, text, logos, labels, branded packaging, certificates, awards, and common
stock-photo clichés. Named artists and design studios are not used.
The exact source of truth is
`packages/commercial/src/beauty-design/assets/prompts.ts`; documentation paraphrases must not fork
that versioned prompt.
### 12.4 Idempotent request hash and cache
The asset request hash covers canonicalized:
- normalized brief;
- exact prompt;
- prompt version;
- generator version;
- design fingerprint;
- intended role.
Matching approved output is reused. Changing any of those inputs yields a different request hash.
The D1 repository persists immutable asset metadata and provenance. Local QA uses deterministic
fixture files. A production storage-key-to-public-URL/R2 resolver for provider-stored bytes remains
to be connected; the private-preview renderer therefore uses the polished procedural or
typography-led fallback when no browser-safe source is available.
### 12.5 Validation
Asset candidates remain inert until validation approves them. Validation checks:
- non-empty and bounded bytes;
- allowed MIME and matching file signature;
- SVG active-content safety;
- decodability;
- minimum dimensions by role;
- orientation range;
- focal-point bounds;
- negative-space side and luminance;
- intended text-side contrast;
- request-hash, version, provider, and fingerprint provenance;
- analysis flags for text, faces, hands, identifiable people, logos, medical imagery, and
off-category content.
The renderer accepts validated responsive sources and emits `<picture>`, explicit dimensions,
`srcset`, `sizes`, lazy loading, focal-point cropping, and high fetch priority for an eager hero.
The six local fixture atmospheres are fixed WebP files used only behind fixture provenance guards.
A production provider-backed derivative and public-URL resolver remains part of the R2 integration
described above.
### 12.6 Fallback order
Customer orchestration should prefer credible supplied authentic media before requesting decorative
generation. For an approved decorative request, the implemented resolver uses:
1. matching approved cache entry;
2. deterministic fixture in `DRY_RUN`;
3. live provider only when not in `DRY_RUN` and `allowProviderCall === true`;
4. deterministic procedural SVG;
5. typography-led composition.
Supplying a provider object does not grant spending authority. Failure never produces a public
placeholder box or a broken page.
## 13. Procedural visual system
The procedural subsystem derives SVG output from the request hash, not runtime randomness. It
supports:
- comb-line rhythm;
- fine grid;
- folded-paper edge;
- hairline rules;
- halo ring;
- index marks;
- lacquer slice;
- mineral contour;
- mirror arc;
- crop notch;
- paper grain;
- reflective band;
- soft noise.
Motifs are category constrained, use safe palette values, contain no business claims, and carry
decorative provenance. SVG validation rejects scripts, event handlers, remote/data sources,
iframes, and `foreignObject`.
## 14. Static rendering
The static renderer:
- accepts only sealed, hash-valid `beauty_personal_care` SiteSpecs;
- requires the pinned renderer version;
- validates the strict design manifest;
- validates assets and cross-design provenance;
- builds all customer-facing content from SiteSpec bindings;
- emits static HTML and inline deterministic CSS;
- emits exact structured data only for supported beauty/local-business schema types;
- supports forced preview `noindex, nofollow, noarchive`;
- hashes each file and the complete render;
- emits CSP, framing, referrer, MIME-sniffing, and robots headers;
- fails when information coverage is incomplete.
The semantic component source includes header, hero, priority services, gallery,
differentiators, founder/team, complete menu, proof, new-client guide, visit, final action, footer,
and a mobile booking tray.
The renderer was exercised across 64 complete pages. Twenty-four representative pages were
inspected in Chrome at top, middle, and bottom at 1440×1000; all 16 recipes were inspected at
390×844; and representative pages were checked at 768×1024 and 1920×1080. The evidence is under
the ignored `artifacts/beauty-design-compiler/` QA directory, with the durable review summary in
`docs/templates/beauty-design-compiler-fidelity-ledger.md`.
## 15. Persistence model
`migrations/0045_beauty_design_compiler.sql` models:
- `beauty_design_sites`: active identity/manifest pointers, design lock, and optimistic version;
- `beauty_design_identities`: persisted initial or regeneration seeds and accepted fingerprints;
- `beauty_design_candidate_attempts`: append-only bounded retry evidence;
- `beauty_design_fingerprint_reservations`: isolated global/category/market/batch reservations;
- `beauty_design_manifests`: immutable manifest JSON and SHA-256;
- `beauty_design_assets`: immutable prompt, brief, storage, validation, and provenance metadata;
- `beauty_design_manifest_assets`: immutable manifest-to-asset bindings;
- `beauty_design_regeneration_audit`: explicit prior/new identity chain and reason;
- `beauty_design_lock_events`: audited optimistic lock transitions;
- `beauty_design_activations`: initial, explicit regeneration, or controlled migration activation.
Triggers reject replacement, mutation, deletion, missing authority, stale optimistic versions,
unreserved fingerprints, and activation while locked.
`D1BeautyDesignRepository` implements seed-first identity creation, cohort reads, bounded collision
retry recording, manifest and asset acceptance, design locks, and explicit regeneration. The full
isolated D1 migration/seed integration test and the beauty repository tests pass. Migration 0045
has not been applied to a live environment.
Preview SiteVersion activation and beauty-manifest acceptance currently use two D1 transactions
because the database trigger requires the source SiteVersion to exist first. A crash between them
cannot publish an unbound design: subsequent rendering fails closed and routes the intake to human
review. A future schema change could combine the operations, but the present failure mode is safe.
## 16. Fixtures and concept references
The local fixture module includes representative Atelier, Ritual, Studio, and Precision cases plus
long-name, one-service, 20-plus-service, no-image, one-image, multiple-location,
missing-price/duration, and generated-asset-failure shapes.
All fixture domains use reserved test-style values and all people/reviews are explicitly fictional.
They must be blocked from production ingestion and customer output.
Reference art-direction images live under:
`docs/templates/beauty-design-compiler/concepts/`
They cover representative rich/sparse Atelier, Ritual, Studio, Precision, mobile, typography-led,
gallery-rich, and section-specific directions. They are internal references only. Direct
reference-to-Chrome comparison is recorded in the fidelity ledger.
## 17. Beauty Generator Lab
The protected Generator Lab is implemented at the operator route `/design-lab`. It provides:
- fictional fixture selection;
- seed entry and explicitly authorized regeneration;
- automatic or explicit variant/recipe selection;
- content, image, services, team, review, and location richness toggles;
- generated-asset success/failure toggles;
- manifest, trace, fingerprint, nearest score, and resolved token inspection;
- information-coverage inspection;
- exact asset briefs, prompts, request hashes, and fallback state;
- side-by-side seed comparison;
- bounded seed grids;
- screenshot capture and development manifest export.
The route is inside the existing authenticated operator shell and uses fictional fixtures. A real
operator session is required to verify the deployed route; the standalone static QA pages do not
bypass that authorization boundary.
## 18. Accessibility, performance, SEO, and analytics
Source-level renderer safeguards include semantic static markup, a skip link, focus tokens, reduced
motion, validated contrast, explicit media dimensions, responsive-source support, safe links,
structured data allowlisting, and a mobile booking tray.
Post-migration Chrome QA covers all 128 accepted pages at 390×844, 768×1024, 1440×1000, and
1920×1080. All 512 runtime records had no console or page error, failed request, broken link,
horizontal overflow, or font-load failure; the primary action remained visible and at least
44×44 CSS pixels, reduced motion was verified, and `noindex` remained present. The direct
inspection plan passed 52/52 records across all four viewports. Axe-core completed 256 mobile and
desktop runs with zero violations; its 70 automated `incomplete` contrast findings (221 nodes)
were independently resolved from computed browser styles and all met the applicable contrast
threshold.
Controlled local Chrome timing covers 16 capsule representatives at mobile and desktop, for 32
runs. It recorded zero runtime, resource, font, and layout-shift failures. This evidence is a
bounded local regression check, not Lighthouse, field Core Web Vitals, a production network, a
real-user dataset, or a customer deployment. Hosted smoke remains a separate deployment-time
gate, and no public URL or hosted result is claimed here.
The manifest exposes template family, variant, recipe, fingerprint, and generator version. The
static markup exposes bounded `data-action` values for the existing analytics layer. No new event
sender was introduced, and no outreach, payment, or sensitive appointment analytics were changed.
## 19. QA and validation
### 19.1 Confirmed compiler validation
The focused unit suite covers:
- seed format and nonce derivation;
- xoshiro reproducibility and bounds;
- exact recipe registry;
- manifest determinism;
- explicit compatible overrides;
- incompatible override rejection;
- sparse-content behavior;
- structural similarity weighting;
- bounded collision exhaustion;
- 1,000-seed generation.
The standalone validator is:
```powershell
pnpm exec tsx tools/validate-beauty-generator.ts
```
It uses only four fictional aggregate content profiles, reads no customer data, writes no files,
and emits one bounded JSON object without raw seeds or fingerprints.
The July 27, 2026 validation run produced:
- 1,000 requested and 1,000 valid manifests;
- zero invalid manifests;
- 1,000 unique full fingerprints;
- 1,000 unique first-viewport fingerprints;
- zero exact or first-viewport duplicates;
- zero bounded-search exhaustion;
- eight successful deterministic replay checks;
- all 16 recipes;
- all eight hero architectures;
- all twelve typography pairings;
- all six page rhythms;
- all sixteen palettes;
- mean 1.079 candidate attempts;
- maximum three attempts;
- maximum accepted nearest-similarity score `0.916168`, below the `0.92` threshold.
The command exits nonzero if any required distribution is absent, any manifest is invalid, a full
or first-viewport duplicate is accepted, a replay differs, or the bounded search exhausts.
### 19.2 Integrated V2 QA evidence
- Renderer migration: `COMMITTED`, 128/128 accepted pages, zero failures, constrained presentation
reconciliation, and unchanged business-body and stable design-identity hashes.
- Chrome capture: 512 screenshots and 512 runtime records over four exact viewports, with zero
runtime, resource, font, link, or overflow failures.
- Direct inspection: 52/52 required records passed all six named checks over mobile, tablet,
desktop, and wide captures.
- Accessibility: 256 axe-core runs completed with zero violations; all 221 nodes reported under
automated `incomplete` contrast checks were independently resolved as passing.
- Controlled performance: 32 local Chrome timing runs completed without runtime, resource, font,
or layout-shift failures. This is not Lighthouse or field Core Web Vitals evidence.
- Perceptual similarity: the bounded calibrated report passed with zero exact or near-duplicate
accepted pairs under its documented thresholds and limitations.
- Responses critic: no result was accepted. Configured account controls prevented the path from
running; seven staged calls were discarded atomically.
- Fidelity: concept comparison and the material findings are in
`docs/templates/beauty-design-compiler-fidelity-ledger.md`.
The local V2 evidence lives under
`artifacts/beauty-design-compiler-v2/qa-site/`. It is fixture-only, non-indexed, and not a customer
production release. The browser finalizer, perceptual summary, controlled-performance summary, and
recorded test summary remain separate evidence sources; none should be replaced by prose claims.
## 20. Security, privacy, and cost controls
- Crawled or client-supplied strings remain untrusted data.
- The compiler receives no credentials and performs no network calls.
- Seeds use Web Crypto, not `Math.random`.
- Prompt generation occurs outside the public browser.
- Live asset-provider calls require explicit non-DRY_RUN authority.
- Provider failures do not expose provider details in public output.
- Asset prompts and diagnostics must not contain customer secrets.
- Fingerprint cohorts contain design vectors, not private customer content.
- Generated media cannot cross design fingerprints.
- The static renderer denies unsupported SiteSpecs, schemas, assets, links, and missing critical
coverage.
- No part of this system authorizes outreach, billing, DNS, hosting, deployment, or production
publication.
## 21. Release checklist
Before calling the Beauty Design Compiler production-ready:
1. Apply migration 0045 through the controlled live migration process; it has passed isolated D1
tests only.
2. Connect provider asset storage keys to the approved R2/public-URL and responsive-derivative
resolver.
3. Keep live image spending disabled until provider credentials, budgets, retries, and emergency
stops pass their own launch review.
4. Preserve the tested self-hosted font binaries, license records, preload policy, hashes, and
fallback behavior in the hosted artifact.
5. Run Lighthouse and real-device/network Core Web Vitals checks against the actual hosted
candidate.
6. Verify `/design-lab` using a real authorized operator session in the deployed environment.
7. Decide whether to keep the safe two-transaction SiteVersion/manifest acceptance boundary or
migrate it to one schema-supported transaction.
8. Verify final approval creates the expected frozen presentation reference.
9. Verify rollback restores the prior SiteSpec, manifest, assets, and release pointer in the target
hosting environment.
The deterministic compiler, persistence, private-preview integration, local rendering, and QA
matrix are implemented and validated. Production hosting and activation remain deliberately
outside this work. No lead, crawling, outreach, billing, Stripe, DNS, domain, deployment, or
production-gate behavior changed.