docs/FH-026-placeholder-mark.md

1# FH-026 placeholder mark
2
3`brand.json` owns the placeholder `mark`. The shared `markIconUrl()` in
4`packages/forkhorse-dashboard/src/mark.ts` draws that value as escaped SVG text in
5the viewer's emoji font. It also derives the SVG's accessible name from the brand.
6No platform emoji artwork or new image binary is distributed.
7
8| Surface | Wiring |
9| --- | --- |
10| OS sidebar account | Account `avatar` uses `markIconUrl(brand.mark)` |
11| OS sidebar app entry | `providesUi.icon` uses the Phosphor Horse regular SVG selected by `brand.json.railIcon` |
12| Admin and connection picker vendor | Vendor `logo` |
13| Agent fork resource | Supported resource `icon` |
14| Standalone dashboard, including its local fixture | Vite injects a favicon in the HTML head |
15| Gatekeeper sidebar, configurator and picker frames | Build injects the same favicon |
16| Core OAuth consent page | Core adds the favicon only to successful GET consent HTML |
17
18The rail icon is separate from the emoji mark. `brand.json.railIcon` selects
19`phosphor:horse`; the gatekeeper inlines the single regular-weight path from
20`@phosphor-icons/react` 2.1.10, with a 256-square viewBox and `currentColor` fill.
21The pinned OS (`8cbfb2b`) maps `description.providesUi.icon` to the app's icon in
22`workshop-backend/src/server.ts`, then renders it as a 14px CSS mask filled with
23the row's current text color in `workshop-frontend/src/components/AppShell/Sidebar.tsx`.
24The account avatar is separate. Light, dark, hover and active colors come from
25the OS row; the SVG has no fixed color. Phosphor's MIT notice is in `NOTICE`.
26
27The OS stores the account description at connection time. After deployment, the
28owner must reconnect once to refresh the cached app icon; changing this metadata
29alone does not establish live visibility. All other surfaces retain the emoji.
30
31The pinned OS consumes the image URLs through its existing identity components;
32the adjacent product/resource labels remain their accessible names. The emoji SVG also
33has an image role and the product name for use by a standalone viewer. No mark is
34added to project titles, status markers, tabs or buttons.
35
36The OAuth HTML transform preserves the response status, cookies and headers.
37Authorization, enrollment, redirects and other OAuth responses are unchanged.
38The dashboard's existing CSP permits data images. The helper encodes apostrophes
39in addition to URI encoding, so its URL is safe in either HTML quote style.
40
41## Validation and review boundary
42
43The dashboard test parses the SVG as XML and checks injection-shaped future mark
44values remain text, with no script, image or path elements. Native workerd tests
45assert the actual vendor, resource and sidebar metadata, the served dashboard
46favicon and the Access-authorized consent favicon while completing PKCE. The
47gatekeeper build verifier checks all three generated frame favicons.
48
49Final acceptance requires a fresh `--no-local` clone of the exact branch head,
50frozen installs at root and upstream, touched package tests and typechecks,
51`pnpm test`, `pnpm lint`, and isolated `pnpm check` with eight Worker dry-runs.
52D5 uses exclusively created, mode-0600, ignored synthetic configuration, an empty
53environment and HOME, loopback-only networking, and denied Keychain access.
54It refuses an existing owner configuration and removes only its own file.
55
56Browser captures must be labeled local fixtures. They establish local rendering,
57not deployment or live acceptance. Design capture review and independent
58code/safety review remain separate required gates; implementation checks alone
59do not satisfy either review.
60