Feature: Template preview harness

[jhweir]

feat: a preview host, and fixtures that outlive it

Branch: feat/template-preview-harness → dev · 15 commits · phases 0–3 landed for the two templates with reference screenshots

Summary

The six showcase templates are shaped like the platforms they reference but don't yet look like
them, and closing that gap is visual work: proportion, density, palette, type scale. Doing it by
hand means a screenshot-and-describe round trip per adjustment, which caps out at four or five
iterations per template before it stops being worth anyone's afternoon.

This closes the loop instead. A fourth host runs the real WE application over the in-memory
backend — no executor, no agent, no neighbourhood — and Playwright drives it headlessly against
the installed Chrome, so a render can be produced, looked at, adjusted and re-rendered without a
human in the middle. The target is a screenshot the author picked; the output is a template and a
theme that match it.

The second half is the part that outlives the exercise. Rendering a template needs data in it —
an empty Discord clone screenshots as an empty state and says nothing about density — and the
fixtures that supply it are useful in at least two more places: seeding a personal space with
sample content so an author can build a template against something, and generating the marketplace
preview images that Template.screenshots and Theme.screenshots have had a relation for and
nothing to fill with. So the fixture format is designed for three consumers from the start, and
only one of them is built here.

Why a host and not a harness

The first sketch of this was a small harness with stubbed stores. That was wrong, and worth
recording because it is the obvious wrong answer: stubbed stores drift from the real ones, so
every screenshot would be of a fiction, and templates would get matched against behaviour the
application does not have. A fidelity tool built on approximations of the thing it measures is
worse than no tool.

The right seam already exists, one layer lower. Stores in this codebase are already
backend-agnostic — they consume ports:

• apps/we-web/src/index.tsx is twenty-five lines:
  <PlatformProvider seed platform backend><App/></PlatformProvider>.
• BackendConnector.ports() returns a BackendPorts bundle
  (backendPorts.ts) — agentSession,
  lifecycle, schemas, profiles, ephemeral, dataBindings, with interop, runtime and
  transcription optional and feature-detected.
• createInMemoryBackendPorts already implements every required member
  (lifecycle.ts:277).
• executorFreeBoot.test.tsx already runs
  the real session, dataset, profile and space stores over that bundle, and backendPorts.ts
  notes that its own surface was derived from what that suite had to mock — "the boot suite doubles
  as the conformance test".

So no new abstraction over stores is needed, and none should be invented. The preview host is a
BackendConnector returning in-memory ports, plus a headless PlatformAdapter, plus its own seed.

It follows that this shows the whole application, not a template in isolation. The shell is
itself templates — Sidebar, Settings, Profile, BootScreen, TemplateEditor, ModuleRail,
the marketplace and spaces surfaces all live in @we/template-shell
and are painted by the same renderer over the same stores. <App/> in the preview host is WE,
with a different connector behind it.

What ships

apps/we-preview (new app) — a fourth host beside we-web/we-electron/we-tauri. Entry mirrors
we-web's; the differences are backend (in-memory ports rather than ad4mConnector), platform
(a headless adapter), and its own we-preview.seed.json selecting the showcase templates with
modules off. A separate app directory rather than a flag on we-web because apps are deployments
here — that is what the seed file expresses — and because it keeps @we/backend-inmemory and the
fixture sets out of the production web bundle, which a runtime flag would drag in unless fought.

@we/backend-inmemory — seedable peer profiles. The one concrete gap found while planning.
createInMemoryProfileDirectory holds a private Map and publish() writes only the self
profile, so get(someOtherDid) returns a blank record and there is no way to seed one
(lifecycle.ts:223). Every template being
matched is a multi-author surface — a feed of identical blank avatars is not a feed — so this is
load-bearing, not cosmetic. Fix is small and has precedent: an optional seed argument surfaced
through InMemoryBackendPortsOptions, in the same spirit as lifecycle.seedShared. Presence needs
the equivalent, for the same reason: presenceStore.onlineHere over a one-agent bus shows only you,
and the Discord template puts that roster in its channel header.

packages/templates/fixtures (new package) — declarative sample content per template,
expressed in model terms (CollectionBlock with kind, children, authors, timestamps) and
applied through the same Model.create calls on either backend. That portability is not
speculative: @we/models classes are compiled from one manifest into row-backed classes by
entities.ts and into triple-backed ones by the
AD4M adapter, and the difference is invisible to a caller. Fake agents (DID, name, avatar) and fake
presence are part of the format rather than bolted on.

The shoot script — Playwright with channel: 'chrome' against the already-installed
/usr/bin/google-chrome, so no browser download. Takes template, theme, route and viewport; writes
a PNG. Two analysis helpers run in-page on a canvas rather than as dependencies, because the box has
no ImageMagick and no sharp and the browser is already an image library: sample a target
screenshot's palette to real hex values, and composite target-beside-render into one image (which is
materially easier to judge than two files).

Before Phase 0 — the audit slice this branch depends on

This branch measures visual fidelity, so it needs a design system that renders
correctly before it can measure anything. Otherwise every screenshot is of a bug,
and the gap list this is meant to produce is just the audit's, rediscovered
slowly and by eye. From PR_AUDIT_2026-08-12_FOLLOWUP.md:

Required — this branch measures against these

1. Fix the 12 dead theme selectors (audit P2-3, ~½ day including the guard).

2-themes targets we-toggle (the element is we-switch), we-tab-item (it is
we-tab), we-menu-group-item (we-menu-group), we-modal::part(modal) and
::part(header) (neither part exists), we-input::part(input-wrapper) (that part
is on select), and we-button[circle] (the prop is square). Retro and
cyberpunk are substantially broken today and it is invisible because CSS fails
silently.

Write the guard first: 3-primitives already emits custom-elements.json, so a
test asserting that every we-* tag and every ::part() used in
2-themes/src/**/*.css actually resolves catches all twelve and stops it
recurring. Two of the five themes cannot be matched against anything until this
lands.

2. Role tokens, phases 0–1 (audit P4-1, ~1.5 days).

Phase 0 — add the roles that are missing and blocking: overlay/scrim (six
different hardcoded black opacities across modals, drawers and gates),
shadowColor (nine primitives hardcode rgba(0,0,0,…), which is invisible on a
dark surface — the reason dark themes need elevation-by-lightness), focus,
{danger,success,warning}Surface, surfaceHover/surfaceActive.

Phase 1 — migrate the nine overlay/floating primitives onto them.

Start with the two lines that pay immediately: modal.ts:9 and drawer.ts:11 →
surfaceRaised. In dark mode today every modal and popover paints darker than
the page it floats over, with a black shadow invisible against near-black. The
--we-role-* vocabulary shipped in #114 with zero consumers, so the dark preset's
override is currently dead code.

Without this, the fidelity work keeps hitting the theme ceiling this PR already
predicts under "Fidelity target" — and logs gaps that are already written down.

Cheap while you are in there — protective of this branch specifically

3. pnpm validate:schemas into CI (audit P3-2, one line). This branch edits
six templates and adds a fixture package; tsc cannot see an unknown component
type, a misspelled prop, a $routes outlet with no routes array, or an orphan
$local. The validator can, and already exists.

4. ShellRouteStore missing params/setParam (audit P2-4, ~5 lines). A live
regression from #114: shell overlays have no query-param support. This host boots
the real shell and renders its overlays, so it is inside the blast radius.

5. A typecheck script for the new app (audit P3-1). apps/we-preview should
ship with one rather than joining the 38 packages that lack it — especially since
we-web, the app it mirrors, is one of two that cannot currently be typechecked
at all (its Vite path aliases are absent from its tsconfig). The full workspace
rollout is ~1 day with 28 packages already clean; at minimum do not add a 39th.

Deliberately not prerequisites

The trust boundary (audit P0), the device-lifecycle cluster (P1), and the
raw-theme-CSS decision (P0-4). None of them changes what a template looks like.
P0-4 does constrain a later theming step — demand-driven scoped-theme injection
— but that is not on this branch's path.

---

Phases

Phase 0 — prove the risky part. (After the prerequisites above.) Boot app-shell over in-memory ports in a real browser, render
one showcase template with hardcoded rows, screenshot it. Everything else is downstream. Built as
the real host rather than a throwaway spike, since the spike is ninety percent of the host anyway.

Phase 1 — fixture format, and a set per template. Includes the profile/presence seeding above.

Phase 2 — the shoot script and the two analysis helpers.

Phase 3 — the matching work, against author-supplied screenshots.

Phase 4 — deliberately out of scope here. In-app "fill this space with sample content", using
the same fixtures against a real perspective. Blocked on an open question (below), and there is no
reason for it to hold up phases 1–3.

What the host found

Everything below was found by looking at one rendered frame, which is the argument for the host in
a sentence. All are fixed on this branch except the last two, which are recorded rather than
repaired.

• scope was declared unsupported by the in-memory adapter, and rowsFor dropped it into
  ...rest. The shared engine has always executed drill-downs; only the lowering could not express
  one. A scoped query therefore answered a different question — every message in the space rather
  than one channel's.
• Untyped relations were omitted from the engine's relation map. CollectionBlock.children is
  untyped by design, so containment did not work at all, and addChildren never wrote the link
  either. Registering them fixed scope; a second pass fixed include, where relatedRows read
  data.tables[''] — an untyped relation means of any type, not no targets.
• A shared space was invisible to the template resolver, which matches on
  Space.url === dataset.sharedId and falls back to uuid only for a personal one. A space setting
  uuid alone renders under the default template while looking entirely correct.
• No URL can express "this space, that route". buildRoutes mounts template routes at the
  router root, so the Discord template owns /channel/:channelId; navigateToSpace builds
  /space/<id>/<view>, which only the default template's own /space/:spaceId route satisfies. No
  showcase template can be deep-linked. Recorded, not fixed — PreviewBootstrap states both
  halves instead (select dataset, then navigate).
• Editor state does not survive non-ASCII. createBlocks encodes UTF-8; decodeEditorState
  reads it back with a bare atob. Any post containing an accent or an em-dash renders mojibake in
  the running app. Recorded as a test, not fixed — it bit this branch's own Kanban fixture.

Two more are visible in the shots and belong to the matching work rather than here: the channel
rail lists every channel twice (once flat, once under its category), and Kanban column headers all
count 0.

The matching, and what it cost the system to do it

Two references (Discord, X), measured rather than eyeballed, and matched. What the exercise was
for was the list below: every item is something the template or theme system could not express,
found by trying to say it.

Fixed here, because both templates needed them

• A template could not name a role. The vocabulary existed and the primitives read it, but an
  author had to write var(--we-role-surface-sunken) by hand, so templates used scale positions
  instead. That cannot express a relationship that inverts: our rail was neutral-100 over a
  neutral-50 page, which is lighter-on-darker in dark mode where every real client's rails are
  darker in both. bg="surface-sunken" now resolves.
• $each gave a row no view of its neighbours, so grouping was unreachable — collapsing
  consecutive messages from one person, which is most of a chat log's density. $index and $prev
  now come with every row.
• Two surfaces ignored the theme entirely. #root and TemplateLayout's content area
  hardcoded neutral-50; the second is the element carrying data-we-theme, so a space theme was
  restyling everything except its own backing.

Found and worked around, worth fixing properly

• The lightness ramp is uniform and real palettes are not. With one subtractor, the gap from
  page to rail always equals the gap from page to raised surface; the reference's gaps are 3.5 and
  6. The channels theme pins three surfaces as roles to get an uneven ramp. Roles are the right
  escape hatch, but a theme wanting its own rhythm between surfaces has to leave the parametric
  system to get it.
• "Containers with no parent" is not a query. channelRail showed every channel twice once a
  category existed, because the ungrouped list has no scope and returns all of them. The correct
  query needs a filter on the absence of an incoming relation — relationFilters, declared false
  by both adapters. Worked around by showing the flat list only while no category exists, which
  leaves a loose channel in a categorised space invisible.
• There is no group-hover. Reaction controls for every defined type on every row roughly doubled
  a one-line message's height, so only signals somebody gave are shown now — and a first reaction
  can no longer be given from the feed. The usual answer is revealing controls on row hover;
  hoverProps styles an element on its own :hover and there is no way to say "when my ancestor is
  hovered".
• Grouping cannot break on time. Real clients end a group after a few minutes' silence. That
  needs date arithmetic the schema language does not have, so grouping is author-only and
  over-groups a conversation that paused.

Deliberate differences, not gaps

Discord's server rail and member list, and X's trends column, are chrome WE's shell provides in a
different shape or not at all. The templates match the parts that are theirs. A band of shell
sidebar also stays on the agent's theme rather than the space's, so a full-window screenshot has a
strip of chrome in a different palette — correct for the app, visible in a photograph.

Open questions

Authorship in a real perspective. In the preview host, fake DIDs can be minted and their
profiles seeded. In a real AD4M perspective the author is the signing agent, so fixture content is
authored by whoever ran it and every row shows one face — which is exactly what the templates being
matched are least able to survive. Either the in-app version accepts single-author sample data and
says so, or it needs a display-layer concession. Unresolved, and the reason Phase 4 is sequenced
last rather than folded into Phase 1.

TemplateStore and ThemeStore over in-memory ports are unproven. Resolved. Both run: the
dark theme applies, the shell surfaces paint, and the template switcher resolves bundled templates.

Fidelity target. Proceeding on idiomatic lookalike: build from DS props and theme tokens, and
where a styles escape hatch is tempting, log a gap in the theme vocabulary instead. Themes here
are parametric — a hue, a saturation, and a (lightness − subtractor) × multiplier ramp
(presets.ts) — so a real platform's palette,
which is not a linear ramp off one hue, will not be reachable in full. The roles override exists
because that ceiling was already hit once. Expect the gap list to be the more valuable artifact.

Known limits of the preview host

Worth writing down so they are not rediscovered as bugs:

• Backend-specific settings surfaces render degraded. createInMemoryBackendPorts omits the
  optional runtime port, and the headless platform will omit AccountHost, so RuntimeSettings,
  LanguageSettings, HostSettings and AccountSettings show their capability-gated empty states.
  Irrelevant to template matching; relevant if the host is ever used for shell design work.
• Join and publish are simulated against inmemory:// URIs. Useful rather than limiting — those
  flows become screenshottable.
• Module weight. @we/app-shell hard-depends on module-call/globe/graph/notes plus three.js and
  gsap. The seed drops them from the deployment but not from the dependency graph.

Follow-ups this makes cheap

• In-app capture. A button in the running app that writes the current view to
  Template.screenshots / Theme.screenshots — a relation that exists today and is populated only
  by manual file upload in publishToMarketplace
  (TemplateStore.tsx:1121),
  which is to say never.
• Visual regression. Once matched, the shoot script wrapped in Vitest browser mode (the repo is
  already on Vitest 4 throughout) turns these into toHaveScreenshot tests, so restyling one theme
  cannot silently break another template. Deliberately not adopted now: a test runner is ceremony
  during an iteration loop.
• A we-preview others can use. The stated ambition — point an AI at a screenshot or a Figma
  export and get a WE template — is this host plus a fixture set. Worth keeping in view while naming
  things, not worth building for yet.

Non-goals

• No live network access. Reference material is author-supplied screenshots; nothing browses.
• No new abstraction over stores. The port contract is the seam, and it already exists.
• No pixel-diff scoring against target screenshots — different content and text make it noise.
  Pixel diffing earns its place later, for self-regression only.

Test plan

• Prerequisites: theme-selector guard green and thirteen dead rules fixed (the audit counted
  twelve; dark had a fourteenth instance of the same ::part(modal) bug); roles phase 0–1
  landed — modals and drawers read surface-raised, no hardcoded black remains in the
  primitives outside the vendored leaflet sheet; validate:schemas in CI; ShellRouteStore
  fixed with five tests.
• Phase 0: preview host boots in headless Chrome with no executor; the shell paints.
• pnpm typecheck — clean, including the new app, which unlike we-web can actually be
  typechecked.
• pnpm lint and pnpm lint:css — clean.
• pnpm validate:schemas — 27 schemas, no issues.
• pnpm test — whole workspace green. New: 5 ShellRouteStore, 6 in-memory seeding + scope,
  2 engine untyped-relation, 9 fixture, 2 theme-selector, 2 role-token.
• Each of the six templates renders populated (not an empty state) at 1440px:
  pnpm --filter @we/app-preview shoot.
• Phase 3: channels and timeline themes, and both templates matched against the references.
• Manual, and the one that matters: James confirms the real app renders what the preview
  host showed, for at least one template. The host is worth nothing if that does not hold, and
  no automated check on this branch can establish it.

Running it

pnpm --filter @we/app-preview dev                    # http://localhost:3100
pnpm --filter @we/app-preview build && pnpm --filter @we/app-preview serve   # :4173

pnpm --filter @we/app-preview shoot                                    # all six
pnpm --filter @we/app-preview shoot -- --fixture discord --width 1280
pnpm --filter @we/app-preview shoot -- --fixture discord --clip 'we-scroll-area'
pnpm --filter @we/app-preview shoot -- --fixture discord --target ~/ref/discord.png

--target samples both palettes to hex and writes a side-by-side composite. There is deliberately
no similarity score — see the script's header for why one would measure the wrong thing here.

[netlify]

✅ Deploy Preview for coasys-we ready!

Name	Link
🔨 Latest commit	684104d
🔍 Latest deploy log	https://app.netlify.com/projects/coasys-we/deploys/6a7ced36a3eb220007d2f277
😎 Deploy Preview	https://deploy-preview-116--coasys-we.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.