diff --git a/docs/superpowers/specs/2026-11-01-sitesmith-upgrade-design.md b/docs/superpowers/specs/2026-11-01-sitesmith-upgrade-design.md new file mode 100644 index 0000000..cc271e5 --- /dev/null +++ b/docs/superpowers/specs/2026-11-01-sitesmith-upgrade-design.md @@ -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/` 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.