epic 2.6: the viewer chrome reads its brand from config

[kuyazee]

Three items from epic 2.6, plus one commit closing every finding the review gauntlet confirmed.
Viewer-facing chrome now reads its brand from config instead of carrying the product name and the
accent color in the shell files.

Items

• T2.6.8 - a branding block on the config endpoint (commit 0360ecc)
• T2.6.2 - the shells read branding from config (commit b9967bb)
• T2.6.9 - branding on every viewer-facing surface (commit 257d6b8)
• Review findings from all three lenses, fourteen of them (commit 2ca4a76)

Tests: 118 to 152, no failures. Smoke: 203 to 212 ok-lines, exit 0.

The rule this whole change is built around

Default output is byte-identical to main. Empty string is the neutral value for all five fields
and means "keep the built-in look", which makes the default identical by construction rather than by
care. An existing self-host upgrading sees no visual change at all.

That was verified by serving every shell from this branch and from a git archive checkout of main
with the same BASE_URL, then running cmp:

byte-identical: frame (6306 bytes)
byte-identical: password (5284 bytes)
byte-identical: not-found (2962 bytes)
byte-identical: md (3912 bytes)
byte-identical: jsx (1758 bytes)

The QA lens pointed out that nothing in CI would have caught a regression of this. The old tests
asserted each slot VALUE equalled the literal the shell used to carry, which guards the values and
not the rendered page: move {{LOGO}} to its own line or add a blank line around {{BRAND_STYLE}}
and every test and every smoke line still passed. So test/fixtures/shells-default/ now holds the
five main renders and test/shells-default.test.js fills each current shell with the all-empty slot
table and asserts equality. It was proven to bite by appending one newline to shells/md.html, which
turned that case red.

T2.6.8 - a branding block on the config endpoint

branding: {productName, logoUrl, faviconUrl, accentColor, footerText} on GET/PUT /api/config,
mirroring the existing frame block: same validation shape, same persistence, same precedence
(stored, then env, then empty). New module lib/branding.js keeps parsing and normalizing separate
from the store, so the per-tenant override layer the item describes can merge on top later without
touching a shell. That override half stays out of this repo, as the item says.

PUT /api/config is requireAuth('full'). Checked against live scoped keys: unauthenticated 401,
read 403, publish 403, full 200, bootstrap 200.

Every field is length-capped and validated, and a refused field rolls the whole PUT back rather than
half-applying. normalizeBranding re-validates on read, so a hand-edited config.json cannot smuggle
an unvalidated value into a shell.

T2.6.2 and T2.6.9 - the shells read it

Wired: shells/frame.html, shells/password.html, shells/not-found.html, shells/md.html,
shells/jsx.html, and the share-link tags in lib/social.js. The badge and watermark overlay shell
in T2.6.2's list does not exist yet, since T2.6.1 is unbuilt.

The T2.6.9 grep is clean. No brand accent hex and no viewer-facing product name is left in shells/.
Every hex still in there is the neutral surface palette. The remaining artifact hits are internal
identifiers only: the artifactTheme localStorage key, the #__artifact_error id, and
data-filename="artifact.tsx".

The md render cache keys on branding as well as md config, so a rebrand shows on the next view rather
than serving a stale render.

One behaviour worth knowing. A jsx artifact is built once, at publish time, so a config change
does not rebrand an already-published one; its frame rebrands either way, and republishing rebrands
the body. An html artifact has no shell at all, so it never carries branding beyond its frame.
Documented in docs/api.md and asserted in both directions in smoke.

Review findings

Three lenses ran: adversarial, security, and QA plus UX. Fourteen findings were confirmed with
measured numbers against a live server. All fourteen are fixed in 2ca4a76. Three more were filed
rather than built, listed at the end.

The security lens found no injection path. It set the worst values that pass validation and read
the served bytes across all six sinks: <title>, an attribute value, a URL attribute, a meta
content=, inside <script> (the jsx error label, which goes through JSON.stringify), and inside
<style>. Each is escaped correctly for its own context, not merely escaped. lib/shells.js does one
pass with a function replacement, which kills both slot-stealing and the $& and $` and $'
substitution patterns; all three render verbatim. Prototype pollution attempts returned 200 with no
pollution.

Contrast, three findings, all measured. These were the substance of the review.

One accentColor was filling both the light and the dark slot, but the shipped shells carried a
light/dark pair per surface precisely because one hue cannot serve both grounds. #1d4ed8 gave md
light links 6.70:1 and dark links 2.90:1; #ffe600 gave dark 15.36:1 and light 1.27:1. The *_DARK
slots now derive color-mix(in srgb, <accent> 70%, white) when an accent is set and keep the literal
when it is not. #1d4ed8 dark links go 2.90 to 5.45:1, the 404 dark accent 2.78 to 5.21:1.

The unlock button hardcoded its label at #0b0d0f, so an ordinary brand blue gave 2.90:1 against a
4.5:1 requirement, and a corporate navy gave 1.31:1, an invisible word on a dark rectangle. A BTN_FG
slot now picks #0b0d0f or #ffffff by the accent's relative luminance: #1d4ed8 goes to 6.70:1 and
#16264a to 14.89:1. Separately BTN_BG and BTN_HOVER both returned the accent, so hover lost its
background change entirely; hover now derives its own value.

The accent allowlist was shape-only, so rgb(--), rgb(,,,,), hsl(+) and rgba(1,2) all returned
200 and then failed silently in the browser: one invalid layer voids the whole declaration, so the
unlock button fell back to UA grey and the page lost its dot grid. Color functions are parsed now
rather than pattern-matched, in both the comma and the space-slash form. Alpha below 1 is refused with
a message saying why, which also closes rgba(0,0,0,0) and #0000 computing every link and code rule
to fully transparent, and color-mix multiplying an accent's own alpha so an hsla(...,0.3) glow
rendered at 0.024 opacity and simply was not there.

Layout, two findings. No logo had a max-width, so at 390px a 1200x60 wordmark rendered 400px
wide, pushed scrollWidth to 579, and put the Copy link and Hide buttons off screen; with a product
name too, the artifact title collapsed to 0px. A 600x60 wordmark is 10:1, which is where the frame
starts breaking, so this is an ordinary input. All three logo rules are capped now, and at 390px the
same logo renders 120px with scrollWidth back to 390 and the title unclipped. The frame bar also
showed logo and wordmark side by side with no hierarchy while refusing to shrink, so the viewer's
document lost its name to keep the operator's; the name renders only when there is no logo, and drops
below 560px.

A CSS selector regression. main > p:last-child styled the 404 description, and {{FOOTER}}
appends its paragraph after it, so setting a footer silently restyled the body copy: 14px to 16px,
muted rgb(89,99,110) to full-foreground rgb(31,35,40), margin 0 to 16px 0, rewrapping two
lines into three. The fix goes in BRAND_STYLE rather than on the paragraph, because adding a class
to the shell would change the untouched page's bytes.

Brand assets are same-origin or inline now. The validator accepted any absolute http(s) URL and
lib/branding.js even commented "so a CDN works", but FRAME_CSP carries img-src 'self' data: on
all three chrome pages, so the browser refused the image: a broken-image box on the frame and the
gate, and on the 404 no mark at all, since the built-in anvil is swapped out for the <img>. It was
also inconsistent, because ?raw=1 runs under img-src * and a remote favicon did load there,
leaking viewer IP and UA to the logo host on that one surface.

T2.6.10 already settles the policy: brand assets live in the same storage backend artifacts use, with
no remote hotlinking, because a hotlinked logo means mixed content and a third-party request from
every viewer page. So parseBrandUrl takes a single-slash path or a base64 data: URI, and refuses
absolute URLs with a message naming the reason. data:image/svg+xml gets its own refusal: an SVG
served from our origin is the stored-XSS case T2.2.3 and T2.6.10 both call out, and this branch has no
sanitizer. The cap on those two fields went 2048 to 8192 so a small inline image fits. The docs now say
where a self-host actually puts the file, since .env.example had been suggesting /brand/logo.svg
and there is no static file route on this server, so that 404s on a stock install.

A product name is not a count noun. productName was substituting the noun for a published item,
so a white-label host served <h1>Dropkiln unavailable</h1> on a dead link, which reads as "the
service is down" rather than "this link is wrong", plus "Protected Dropkiln", "This Dropkiln is
password protected." and "Copy link to this Dropkiln." docs/api.md blessed it explicitly. The noun is
the literal artifact again, everywhere, and productName reaches only the four places a brand
belongs: the frame chip, og:site_name, the footer, and the jsx error label. Removing it from the
h1 also dissolved a separate finding, where a 40-character unbroken name overflowed the 404 card by
180px.

The smoke block could not pass on a branded host, and wiped its branding. It asserted the target
renders Artifact unavailable and --link: #c73d1d, both false on exactly the instances this feature
exists for, then PUT all five fields to empty unconditionally. Since fail() exits, any failure in
between left the target branded "Smokebrand" with a blue accent. It now reads the stored branding
first, skips the built-in-look assertions when the host is already branded, and restores what was
there, following the md.width save-and-restore precedent. Proven both ways: on an unbranded host,
212 ok-lines, exit 0; on a host pre-branded Acme Docs with a purple accent and a footer, 211
ok-lines, exit 0, and the config came out exactly as it went in.

Also fixed. The footer was centered on the gate and left-aligned on the 404 while both cards align
everything else left, now left on both. The accentColor error message omitted #rgba while the code
accepted it. docs/api.md grouped html with jsx on build-time staleness, but html carries no branding
at all, so the sentence implied stale branding where there is none. Two coverage gaps closed: the real
upgrade path (a config.json with no branding key, which is the case that decides "zero visual
change after upgrading", and the nearest existing test covered the opposite case), and the BRAND_*
env path, which .env.example documents and nothing pinned.

Filed, not built. Three items appended to the backlog rather than folded in here:

• The 410 and the plain-text 404 responses stay unbranded and still say "artifact" on a white-labelled
  host. Pre-existing on main, but T2.6.9 says every viewer-facing surface, so the gap is named.
  Turning a plain-text response into an HTML page is a behaviour change that needs its own item.
• Branding is API-only. The dashboard settings panel writes back frame and md and has no branding
  inputs, the CLI has none, and there is no MCP config tool, so an operator opens Settings, sees every
  other global knob, and has to go find curl for this one. Both done-when clauses are satisfied by a
  PUT, so this is a gap rather than a missed requirement, but it is the gap that decides whether
  anyone uses the feature.
• The dashboard itself is unbranded.

Left alone deliberately. A light-theme accent can still read poorly against the light ground:
#ffe600 is 1.27:1. The derivation is scoped to the dark slots on purpose, because the light slot is
the operator's literal accent and darkening it means overriding the color they picked in the theme
they picked it for. Same reasoning for an accent near luminance 0.19, where neither black nor white
label clears 4.5:1 and the helper picks the better of the two at about 4.4:1. Both want a product
decision, not a contrast helper.

Verification

• npm test: 152 pass, 0 fail. Was 118 on main.
• Smoke on an unbranded host: exit 0, 212 ok-lines. On a pre-branded host: exit 0, 211 ok-lines, with
  the stored branding restored unchanged.
• Byte-identity: all five shells cmp-equal against main, and now guarded by a fixture test.
• git diff origin/main..HEAD -U0 | grep "^+" | grep "—\|–" returns nothing.

https://claude.ai/code/session_01JPiFnXvsTMjDJUdRZNwTea