docs: Sitesmith design spec (was untracked) with the amended per-send call cap for page-by-page site builds

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
shadowdaoandClaude Opus 5.5 committed 2026-11-01 17:31:16 -08:00
1 parent 04c0b0a08a
commit 69568e5979
1 file changed
+184
@@ -0,0 +1,184 @@
# Sitesmith upgrade: sites that look custom-made
Status: APPROVED TO BUILD by Josh (2026-11-01: "Continue to build all the
features and deploy when they pass checks"). Ship order: test VM .148 first,
then fleet, only when tests and browser checks pass. Design calls below that are
not Josh's words are marked MY CALL.
## Why
Sites built with Sitesmith (the AI assistant in the builder) look "really
basic" (Josh, about olsdigital.com and tabletopmisfits.online). Josh wants sites
made elegantly so that nobody can tell a site builder was used. Findings from
reading the code (2026-11-01): the system prompt (`libs/sitesmith-prompts.php`)
has no design guidance at all; its one example hardcodes an indigo gradient and
emoji icons; the catalog it knows is about 25 components while the editor has
about 50 section designs in 11 families and 16 templates; the model never sees
pixels (it picks uploaded images by filename and EXIF text); output is one
blocking JSON call (up to ~120 s with the retry) with no timeout handling in the
browser, and a `send` NetworkError on whp01 was never resolved.
## Goals
1. **Use the user's uploaded images.** Sitesmith can see each uploaded asset
(not just its filename), knows its size, and places it with a good caption/alt
text, using relative `assets/<file>` URLs. A free stock-photo provider will be
added later; design the image source so that provider can plug in (the Pexels
stock tool already exists in the editor and is not used by Sitesmith).
2. **Look good by default.** Give Sitesmith a real design brief and the full
component and section-family vocabulary, site design tokens (`var(--wsb-*)`),
typography scale, spacing rhythm, varied layouts, real icons (Font Awesome 7.3.1
is shipped) instead of emoji, and image treatments. Remove the example that
anchors every site to the same indigo gradient.
3. **Sites the user likes (reference sites).** Users can list example websites
they like and which parts they like. Sitesmith uses these as guidance.
4. **Mockups.** A user can upload a mockup image and Sitesmith builds toward it.
5. **See its own work.** Sitesmith can review a render of what it built,
critique it, and fix it (self-review loop).
6. **Reliable transport.** Replace the single blocking request with start-then-poll
(or equivalent), with browser-side timeouts and clear errors; find and fix the
cause of the whp01 `send` NetworkError (candidates: proxy/WAF/PHP timeout on a
~120 s request).
7. **Accessibility.** Sitesmith's color choices pass WCAG contrast, using the
same checker as the color-system project (`contrastRatio`).
## Non-goals
- No new stock-photo provider yet (design the hook, do not choose a vendor).
- No fetching of arbitrary websites by the panel host in this project (see
"Deferred" below).
- No change to the builder's visual design or to existing sites' saved content.
## Anti-goals
- Output that is still generic with more words around it.
- Any way for a user to make the panel host fetch internal addresses (SSRF).
- Costs that run away: keep the existing per-user and per-server rate and dollar
limits (6/min, $2/user/day, $50/server/day) and count image tokens in them.
- Regressing existing Sitesmith behavior (patch/replace/ask modes, schema
validation, sanitising HtmlBlock output, prompt-injection guard).
## Decided by Josh
- Use the user's uploaded images; stock photos later.
- Users can give example websites and the parts they like about each.
- Sitesmith should be able to look at screenshots/images and review them, and
build from an uploaded mockup.
- Sites should be elegant and not look like a site builder.
## My calls (override me if wrong)
- **Vision input:** pass image content blocks (resized thumbnails, e.g. long edge
1024 px, JPEG/WebP, capped count and bytes) to the model; the configured
advanced-tier profile must be vision-capable (verify it; report if not).
- **Transport:** job + poll (store job state in the DB or a temp file keyed by
user and site; frontend polls with backoff; server keeps working after the
browser disconnects). SSE is acceptable if it survives the proxy chain; the
builder decides after measuring.
- **Reference sites, v1 (no server-side fetching):** a "Sites I like" list per
site/project: URL (kept as a label), free-text "what I like", and optional
screenshots the user uploads themselves. Sitesmith sees the text and images.
It never makes the server fetch the URL in v1.
- **Self-review loop:** the editor renders the page client-side (Preview HTML in
an iframe) and captures an image for the model (html-to-image / canvas, or
Playwright-free approach); one critique-and-fix round by default, capped.
Must fit in the cost limits.
- **Image captions:** generate once per asset with the vision model, cache with
the asset (sidecar or DB), reuse.
- **Design brief:** a maintained prompt section plus a small catalog generated
from the editor's real component/section-family definitions so they cannot
drift (fix the duplicate keys in `sitesmith_component_catalog`).
## Deferred (needs a decision from Josh, does not block the above)
- **Screenshots of live reference websites.** The panel hosts have no headless
browser, and fetching user-supplied URLs is an SSRF risk. Likely design: one
hardened screenshot service on one host (egress-restricted, DNS pinned, public
IPs only, size/time caps) that panels call; needs an infrastructure decision
(which host, which container). Until then users upload screenshots themselves.
## Anchors in the code (verified by reading 2026-11-01; may drift)
- `web-files/libs/Sitesmith.php` (send flow, limits, assets listing),
`libs/sitesmith-prompts.php`, `libs/sitesmith-schema.php`,
`libs/litellm_client.php` (request builders), `libs/whp_ai_config.php`,
`api/sitesmith.php`
- `craft/src/panels/sitesmith/SitesmithModal.tsx`, `hooks/useSitesmith.ts`,
`utils/canvas-summary.ts`, `utils/apply-ai-response.ts`
- `craft/src/sections/families/`, `templates/definitions.ts`, `constants/palettes.ts`
- Existing stock tool: `api/site-builder.php` (`stock_search`, `stock_import`),
`ui/StockPhotoTab.tsx`
- Contrast helper: `utils/publish-checks.ts` (`contrastRatio`)
## Success looks like
- Asking Sitesmith for a home page for a small business produces a page with real
hierarchy, varied sections, proper icons, the user's own images placed sensibly,
passing contrast, and a published result that a person would not call "basic".
- Uploading a mockup image yields a page recognisably built from it.
- A long generation never produces a NetworkError; the user sees progress or a
clear, specific error.
- Quality is measured, not assumed: a small fixed set of prompts (including the
OLS Digital and Tabletop Misfits businesses) is run before and after, with
screenshots compared, and the results are reported honestly.
## Settled calls (builder-check answers, 2026-11-01; MY CALLS, flag if wrong)
1. **Vision support.** Verify the configured advanced-tier profile accepts image
blocks in both request builders (Anthropic-style and OpenAI-style in
`litellm_client.php`). If a host's profile is not vision-capable, add a
separate `sitesmith_vision` feature slot in `whp_ai_features()`; if none is
configured, hide/disable the image features (mockup, reference screenshots,
image captions, self-review) with a clear message and keep text-only
generation working. Never fail the whole send because vision is missing.
2. **Cost.** Count usage from the provider's reported tokens after each call
(image tokens included) and gate with a conservative pre-call estimate. One
user "send" = one unit of the 6/min rate limit; internal calls (caption,
critique, fix) do not consume extra rate units but DO count against the
per-user and per-server dollar limits. Hard cap per send: 3 model calls
(generate, critique, fix). Stay inside the existing $2/user/day and $50/server/day.
**Amended 2026-11-01 (round 3, MY CALL):** a whole-site build is planned first
and then built one page per model call, so its cap is 3 + P calls where P is the
number of pages built, P <= 4 (at most 7 calls: caption, plan, one retry shared by
the whole send, one call per page). Why: one answer for a 3-page site + header and
footer ran past 16000 and then 24000 output tokens (RESPONSE_TOO_LONG, $0.41 for
nothing, live eval of 2026.11.7); per-page calls each fit the normal cap. Bounds:
every call still passes the per-call dollar reservation (a refusal mid-build
returns the pages built so far), a 480 s wall-clock budget for the pages, more than
4 planned pages -> the first 4 and a note, progress through the job poll phase
(page:K/N). WHP docs/sitesmith-backend.md "Whole-site builds" has the details.
3. **Self-review.** Client-side capture, run as a separate follow-up job started
by the browser after it applies the result (no job-pausing). On by default
while the editor is open, with a visible toggle; one round max by default.
If capture or the review call fails, skip it and show a small non-blocking
note. Prefer rendering the page's published-style HTML in a same-origin
iframe; verify that web fonts, Font Awesome and assets-proxy images actually
appear in the capture (measure), otherwise say the loop is unreliable and ship
it off by default.
4. **Assets.** GD and Imagick are installed on panel hosts (verify in setup.sh).
Thumbnail server-side (long edge 1024, JPEG/WebP). SVG: skip for vision
(pass dimensions + filename). GIF: first frame. HEIC/other: skip. Cap count
and total bytes per request. Caption cache: a DB table keyed by
(site_id, filename, content hash), via an idempotent migration (see the
whp-add-migration skill); it is not part of site export.
5. **Jobs.** A second send while one is running for the same user+site is rejected
with a clear message. Jobs expire after 24 h; cleanup runs opportunistically on
the next send. "ask" mode works as a job result. The result is persisted to
history on the server even if nobody polls (browser closed).
6. **Mockups and reference screenshots** are stored separately from site assets
(`.site-builder/sitesmith-refs/`), never listed in the asset library, never
publishable. "Sites I like" (URL label, "what I like", optional screenshot ids)
lives in a DB table per site; excluded from site export; backed up with the
site directory.
7. **Quality measurement.** Run a fixed set of prompts through the real provider
on the test VM only (small cost), with business details taken from the OLS
Digital and Tabletop Misfits site text (stored state copies in the scratchpad
state dirs). Non-deterministic, so it reports and screenshots, and does not
gate the deploy on a score. The deploy gates on tests: schema validity, patch/
replace/ask regressions, rate/cost limits, and browser checks.
8. **Accessibility.** Both: design-brief guidance, and a client-side check before
applying a response that auto-repairs failing text/background pairs to the
nearest passing token or black/white without another model round. No PHP port.
9. **Catalog.** Generated at build time from the editor's definitions
(`craft/scripts/`), committed as a generated file under the panel's libs, with a
test that regenerates and compares so drift fails CI/tests.