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:
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.
|
||||
Reference in new issue
Block a user