{title}

\n \n Log out\n \n \n );\n const loginLink = loginHref\n ? (\n \n Log in\n \n )\n : null;\n\n return (\n \n \n \n \n {title}\n \n \n\n",[],[351,564],"0624324c-15a1-4656-b4f5-0e2e312f15c2","flow.svg","b35d6c26-7fb7-11f1-851e-1607ee4eb77e",241,["D",1784056238995],"\n",[],[351,572],["D",1784056238376],[420,421,422,423,424,425],[351],"a7d6b8dd-1925-4e52-8b1a-7519e5abc73e","issue-tracker-valtown.md","4e874dca-7be4-11f1-973a-1607ee4eb77e",199,["D",1783711960586],"# Issue tracker: val-issue-tracker (JSON API)\n\nUse the tracker's JSON API for agent and script operations; do not scrape HTML.\n\n**Tracker URL**: `` (for example `https://username-myval.web.val.run`)\n\n**Auth**: reads are public. Writes require\n`Authorization: Bearer `. Each write may include `actor`,\na Val Town handle; omitted actors default to `agent`. Actor provenance is stored\nonly in the append-only events log.\n\n## Response shapes\n\nEvery response is JSON. Successful responses are either a single object, an\narray, or a small acknowledgement object (`{\"deleted\": id}` /\n`{\"updated\": id}`); error responses always have the shape:\n\n```json\n{ \"error\": \"human-readable message\" }\n```\n\n### Label\n\n```ts\n{\n id: number;\n name: string;\n color: string; // six lowercase hex characters, no leading \"#\"\n created_at: number; // ms since epoch\n updated_at: number;\n}\n```\n\n### IssueReference\n\nThe compact shape used inside `blockers` and `blocks`.\n\n```ts\n{\n id: number;\n title: string;\n status: \"open\" | \"closed\";\n state_reason: \"completed\" | \"not_planned\" | \"duplicate\" | \"reopened\" | null;\n}\n```\n\n### Issue\n\n```ts\n{\n id: number;\n title: string;\n body: string; // markdown, verbatim (not trimmed)\n status: \"open\" | \"closed\";\n state_reason: \"completed\" | \"not_planned\" | \"duplicate\" | \"reopened\" | null;\n created_at: number;\n updated_at: number; // last activity: own edits, comments, or association changes\n creator: string | null; // Val Town handle, derived from the issue's creation event\n labels: Label[];\n assignees: string[]; // Val Town handles, no \"@\" prefix\n blockers: IssueReference[];\n blocks: IssueReference[];\n blocked: boolean; // true iff at least one blocker is still \"open\"\n}\n```\n\n`GET /api/issues/:id` returns an `Issue` plus a `comments` field\n(`comments: Comment[]`); no other endpoint includes `comments`.\n\n### Comment\n\n```ts\n{\n id: number;\n issue_id: number;\n body: string; // markdown, verbatim\n created_at: number;\n updated_at: number;\n author: string | null; // Val Town handle, derived from the comment's creation event\n}\n```\n\n### Event\n\n```ts\n{\n id: number;\n event_type:\n | \"issue.created\" | \"issue.updated\" | \"issue.deleted\"\n | \"comment.created\" | \"comment.updated\" | \"comment.deleted\"\n | \"label.created\" | \"label.updated\" | \"label.deleted\";\n entity_id: number; // the issue/comment/label id the event is about\n actor: string;\n data: unknown; // grammar below\n event_timestamp: number;\n}\n```\n\n`GET /api/issues/:id/events` returns `Event[]` in append order.\n\n## Event data grammar\n\nEvents are the source of truth for provenance and history; live tables hold only\ncurrent state.\n\n- **Boundary events (`*.created`, `*.deleted`) snapshot full state.** The `data`\n field is the entity's complete state at that moment — a hard-deleted row\n leaves a full tombstone:\n - `issue.created` / `issue.deleted` data:\n `{id, title, body, status, state_reason, created_at, updated_at}`\n - `comment.created` / `comment.deleted` data:\n `{id, issue_id, body, created_at, updated_at}` (no `author` — that is always\n derived from the surrounding event, never stored in the payload)\n - `label.created` / `label.deleted` data:\n `{id, name, color, created_at, updated_at}`\n- **`*.updated` events carry a single field delta:**\n `{update_target, from, to}`.\n - For `issue.updated`, `update_target` is one of `title`, `body`, `status`,\n `state_reason`, `label`, `assignee`, `blocks`, `blocked_by`. Associations\n (`label`, `assignee`, `blocks`, `blocked_by`) use **`null ↔ value`**\n (`from: null` = added, `to: null` = removed). A block edge writes exactly\n one event, on the acting issue (the one named in the endpoint path).\n - For `comment.updated`, `update_target` is `\"body\"`.\n - For `label.updated`, `update_target` is `\"name\"` or `\"color\"`.\n - One event per changed field: closing an issue with a new reason emits two\n `issue.updated` events (`status` and `state_reason`), sharing one actor and\n timestamp.\n\n## Status codes\n\n| Status | Meaning |\n| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `200` | Read succeeded, or a mutation applied and the endpoint returns the resulting state. |\n| `201` | An issue, comment, or label was created. |\n| `400` | The request is malformed: invalid `:id`, invalid `status` filter, invalid close `reason`, invalid label `color`, a missing required scalar field (`title`; `name`/`color`; comment `body`), or a collection field (`label_ids`, `add`, `remove`, `assignees`) that isn't shaped as required — see below. |\n| `401` | A write was attempted with a missing or incorrect bearer token. |\n| `403` | A write was attempted but `ISSUE_TRACKER_API_KEY` isn't configured, so writes are disabled entirely. |\n| `404` | The issue, comment, or label named by `:id` — or referenced by an ID inside `label_ids`/`add`/`remove` — does not exist. |\n| `409` | The write conflicts with an existing invariant: a blocking edge would create a cycle (including a self-edge), or a label `name` collides with an existing label. |\n\n## Strict collection validation\n\n`label_ids`, and the `add`/`remove` fields on the labels and blocks/blocked-by\nendpoints, are validated as a whole, not filtered element by element:\n\n- **Absent** — treated as an empty operation (no IDs added or removed).\n- **Present** — must be an array where every element is a positive integer\n (`Number.isInteger(x) && x > 0`). Any other shape (not an array, a\n non-integer, zero, a negative number, a string, etc.) rejects the entire\n request with `400`; nothing is applied.\n- Each ID that passes shape validation must still reference an existing label or\n issue, or the request fails with `404`.\n\n`assignees`, and the `add`/`remove` fields on the assignees endpoint, follow the\nsame absent-is-empty / present-is-all-or-nothing rule, but for handles:\n\n- **Present** — must be an array of non-empty strings after trimming and\n stripping a leading `@`. Any other shape rejects the request with `400`.\n- Handles are not entities (no lookup table), so there is no `404` for an\n unrecognized assignee — any well-shaped handle is accepted.\n\n## Endpoints\n\n| Method and path | Body / query | Success |\n| --------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `GET /api/issues` | `?status=open\\|closed&label=&assignee=&search=` | `200` `Issue[]`. `400` if `status` is present and not `open`/`closed`. |\n| `POST /api/issues` | `{title, body?, label_ids?: number[], assignees?: string[], actor?}` | `201` `Issue`. `400` missing `title` or malformed `label_ids`/`assignees`. `404` if a `label_ids` entry doesn't exist. |\n| `GET /api/issues/:id` | — | `200` `Issue & {comments: Comment[]}`. `400` invalid id. `404` missing issue. |\n| `PATCH /api/issues/:id` | `{title?, body?, actor?}` | `200` updated `Issue`. `400` invalid id. `404` missing issue. |\n| `DELETE /api/issues/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing issue. |\n| `POST /api/issues/:id/close` | `{reason?: \"completed\" \\| \"not_planned\" \\| \"duplicate\", comment?, actor?}` | `200` updated `Issue`; reason defaults to `completed`. `400` invalid id/reason. `404` missing issue. |\n| `POST /api/issues/:id/reopen` | `{actor?}` | `200` updated `Issue` with `state_reason: \"reopened\"`. `400` invalid id. `404` missing issue. |\n| `POST /api/issues/:id/labels` | `{add?: number[], remove?: number[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue or a missing label id. |\n| `POST /api/issues/:id/assignees` | `{add?: string[], remove?: string[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue. |\n| `POST /api/issues/:id/blocks` | `{add?: number[], remove?: number[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue or referenced issue id. `409` cycle or self-edge. |\n| `POST /api/issues/:id/blocked-by` | `{add?: number[], remove?: number[], actor?}` | Same as `/blocks`, opposite edge direction. |\n| `POST /api/issues/:id/comments` | `{body, actor?}` | `201` `Comment`. `400` invalid id or missing `body`. `404` missing issue. |\n| `PATCH /api/comments/:id` | `{body, actor?}` | `200` `{updated: id}`. `400` invalid id or missing `body`. `404` missing comment. |\n| `DELETE /api/comments/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing comment. |\n| `GET /api/issues/:id/events` | — | `200` `Event[]` in append order. `400` invalid id. `404` missing issue. |\n| `GET /api/labels` | — | `200` `Label[]`. |\n| `POST /api/labels` | `{name, color, actor?}` | `201` `Label` (`color` is hex, with or without `#`). `400` missing `name`/`color` or invalid `color`. `409` `name` already in use. |\n| `PATCH /api/labels/:id` | `{name?, color?, actor?}` | `200` updated `Label`. `400` invalid id or `color`. `404` missing label. `409` renaming to an in-use `name`. |\n| `DELETE /api/labels/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing label. |\n\nAll write routes additionally return `401` for a missing/incorrect bearer token,\nand `403` if `ISSUE_TRACKER_API_KEY` is unset — checked before any body or id\nvalidation.\n\n## Triage labels\n\nLabels are curated entities, not free-text arrays. Before applying workflow\nlabels such as `needs-triage`, create each one once with `POST /api/labels`,\nretain its ID, then send that ID to the issue-label endpoint. The product's\nfresh-install defaults are `bug`, `enhancement`, `documentation`, `question`,\nand `duplicate`.\n\n## curl examples\n\n```bash\nTRACKER=https://your-handle-your-val.web.val.run\nKEY=...\n\n# Discover label IDs\ncurl -s \"$TRACKER/api/labels\"\n\n# Create with curated labels and multiple assignees\ncurl -s -X POST \"$TRACKER/api/issues\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Fix flaky test\",\"body\":\"Observed in CI\",\"label_ids\":[1],\"assignees\":[\"alice\"],\"actor\":\"alice\"}'\n\n# Close as deliberately not planned\ncurl -s -X POST \"$TRACKER/api/issues/12/close\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"not_planned\",\"comment\":\"Superseded by #15.\",\"actor\":\"alice\"}'\n\n# Reopen\ncurl -s -X POST \"$TRACKER/api/issues/12/reopen\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"actor\":\"alice\"}'\n\n# Declare that #12 blocks #15\ncurl -s -X POST \"$TRACKER/api/issues/12/blocks\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"add\":[15],\"actor\":\"alice\"}'\n```\n",[],[358,583],"bab12ed8-89bb-4383-b479-55282f37780e","backlog.md","eea1bf8a-7bf2-11f1-975e-1607ee4eb77e",349,["D",1784091864833],"# Backlog — deferred wants\n\nThings wanted eventually, not now. Not commitments; parking lot.\n\n- **Clickable user handles.** Wherever a user handle is displayed (creator,\n comment author, assignee), render it as a link to that user's Val Town\n profile. Purely a rendering concern — the data model just stores the handle.\n (See [[User]] in CONTEXT.md.)\n- **Markdown rendering.** Issue bodies and comment bodies are stored as\n markdown; rendering them to HTML is a later concern.\n- **`DESIGN.md` component conformance.** The follow-on to\n `docs/issues/valtown-native-ui/spec.md`, which specced the foundation\n (palette, fonts, dual-scheme — landed) and defers the component-level Named\n Rules to here: The Machine Facts Rule (mono for issue numbers, handles,\n timestamps), The Hairline Rule and The No-Card Rule (one panel of hairline\n rows), The One Bold Rule and issue-row anatomy, The Badge Containment Rule,\n the status pill as a tinted pair, a visible focus ring on every interactive\n element, and hover along the `sky` ramp. Each needs visual judgment rather\n than measurement, which is why it wasn't in the foundation spec. Unblocked now\n that the foundation spec has landed — the tokens are in place.\n",[],[358,591],"3a3e928d-1e27-45cf-832b-40731eacf89d","spec.md","911c9a22-8004-11f1-821c-1607ee4eb77e","9102e5be-8004-11f1-8a46-1607ee4eb77e",331,["D",1784089252790],"# PRD: Val Town-native UI foundation\n\nStatus: ready-for-agent\n\n`DESIGN.md` is the normative target for this work; its YAML frontmatter carries\nthe tokens. `PRODUCT.md` carries the strategy. This spec covers the\n**foundation** of that migration — the layer whose correctness is decidable by\nmeasurement. Purely aesthetic conformance to the component-level Named Rules is\nexplicitly deferred (see Out of Scope).\n\nThis supersedes the \"Migrate the UI to `DESIGN.md`\" entry in `docs/backlog.md`.\nThat entry estimated the work as \"mostly `theme.ts` and `layout.tsx`\". That\nestimate is wrong, and the reason is the core of this spec: flipping the canvas\nbreaks colors that no token controls.\n\n## Problem Statement\n\nThe tracker wears a generic dark-SaaS costume — blue-charcoal surfaces\n(`#0f1115`), a bare system font stack, and a saturated blue accent. `PRODUCT.md`\nnames this exact combination as an anti-reference and as \"the specific thing\nthat makes this UI 'not look good'\". It is also a dark-only surface, so a\ntracker mounted in a light Val Town host renders as a dark island in a light\npage — which contradicts the \"it embeds politely\" principle directly. A guest\nthat ignores its host's color scheme is a rude guest.\n\nUnderneath the cosmetic problem sit measurable defects the maintainer cannot see\nbut does feel:\n\n- Four of the five seeded Labels are **illegible on a light canvas**. The Label\n chip paints the stored color as text on a transparent fill, which works\n against black and fails against white. `enhancement` (`a2eeef`) measures\n 1.31:1 on white; `duplicate` (`cfd3d7`) 1.51:1; `question` (`d876e3`) 2.76:1.\n Separately, `documentation` (`0075ca`) already fails **today** at 4.40:1 on\n the current dark canvas.\n- The open/closed **state icon** — the single most-scanned signal in the list —\n is hardcoded to a color that measures 1.74:1 on white. It disappears.\n- The Banner hardcodes dark-only tints, so on a light canvas it renders as a\n near-black island.\n- Every button and input has **no height mechanism at all**. The code says\n `min-h-10`, intending 40px, but the project's Twind build predates Tailwind's\n numeric `min-h-*` scale and emits no rule for it. Controls are sized by\n line-height alone (~20–24px), far under the 44px touch-target floor. The 40px\n everyone believes is there has never existed.\n\nThe last four are not migration risks. They are live defects, and three of them\nare invisible until the canvas flips.\n\n## Solution\n\nMigrate the tracker's visual foundation to the Val Town-native system already\ndocumented in `DESIGN.md`: an achromatic canvas (true white / true black),\nstructure carried by slate hairlines, the stock `sky` ramp as the only accent,\nIBM Plex Sans for interface text with iA Writer Mono for machine facts, and\n**dual-scheme rendering driven by `prefers-color-scheme`** so the tracker\nfollows whatever its host val is showing.\n\nThe migration is made cheap by one discovery: because every palette token feeds\na color slot and none appear in a `style` attribute, the palette module's\n**values** can change from hex literals to typed CSS variable references while\nevery one of its ~107 call sites stays byte-identical. The scheme switch then\nlives in one generated stylesheet block rather than in a `dark:` variant at\nevery call site.\n\nColors that no token controls — the Banner tints, the state icon, the status\npill, and user-authored Label colors — are brought under the token system or\nmade scheme-aware at render time. Label color is handled without touching stored\ndata: the stored hex remains the source of truth, and legibility is achieved by\nadapting lightness per scheme at render.\n\nEverything stays server-rendered and works with zero client-side JavaScript.\n\n## User Stories\n\n1. As a maintainer triaging in a light Val Town host, I want the tracker to\n render light, so that it does not sit in my page as a dark island.\n2. As a maintainer triaging in a dark Val Town host, I want the tracker to\n render dark, so that it continues to match its surroundings as it does today.\n3. As a maintainer whose host follows the OS scheme, I want the tracker to\n follow it too, so that I never configure the tracker's appearance separately.\n4. As a Val Town developer mounting the tracker, I want it to look like it\n belongs to the platform, so that it reads as native chrome rather than a\n third-party widget competing with my val.\n5. As a Val Town developer, I want the tracker to inherit the platform's own\n typographic identity, so that it does not announce itself as foreign.\n6. As a maintainer scanning the list, I want the interface set in IBM Plex Sans\n rather than a system stack, so that the UI reads as precise rather than\n generic.\n7. As a maintainer, I want the fonts to load without a flash of unstyled or\n invisible text, so that scanning is not interrupted on every navigation.\n8. As a maintainer on a slow or offline connection, I want the interface to stay\n fully legible if the webfonts never arrive, so that the tracker degrades to a\n sane fallback rather than breaking.\n9. As a maintainer scanning the list, I want the open/closed state icon to be\n clearly visible in both schemes, so that I can tell an Issue's Status at a\n glance — the thing the list exists for.\n10. As a maintainer scanning the list, I want every Label chip legible in both\n schemes, so that I can spot triage signal without opening an Issue.\n11. As a user who authored a Label color, I want my color to remain recognizably\n my color in both schemes, so that the chip still reads as the one I chose.\n12. As a user who authored a Label color, I want my stored color left untouched,\n so that switching schemes never silently rewrites my data.\n13. As a maintainer, I want the `documentation` Label to be legible on the dark\n canvas, so that a defect that exists today is fixed rather than carried\n forward.\n14. As a maintainer, I want a Label whose color is near-white to stay visible on\n a white canvas, so that no Label can be rendered invisible by its own color.\n15. As a maintainer, I want a Label whose color is near-black to stay visible on\n a black canvas, so that the same guarantee holds symmetrically.\n16. As a maintainer receiving a success or error Banner, I want it legible and\n correctly tinted in both schemes, so that feedback never renders as a dark\n block on a light page.\n17. As a maintainer, I want the Status pill legible in both schemes, so that\n lifecycle state never rides on an off-brand saturated fill.\n18. As a maintainer, I want state to be conveyed by icon or text as well as\n color, so that Status never rides on color alone.\n19. As a maintainer clicking a primary action, I want its label readable against\n its fill, so that the button is not the least legible element on the page.\n20. As a maintainer hovering a destructive action, I want its label readable\n against the hover fill, so that the most dangerous control is not the least\n legible.\n21. As a maintainer on a touch device, I want buttons and inputs large enough to\n tap reliably, so that I am not fighting 20px targets.\n22. As a maintainer, I want controls to have a real, working height mechanism,\n so that the intended control height is what actually renders.\n23. As a keyboard user, I want a visible focus ring on every interactive element\n in both schemes, so that the zero-JS form-driven flow stays navigable.\n24. As a keyboard user, I want the focus ring to be visible against both the\n white and black canvas, so that focus is never lost against its background.\n25. As a maintainer reading body and meta text, I want it comfortably readable\n in both schemes, so that scanning density does not cost legibility.\n26. As a developer changing a palette value, I want to change it in exactly one\n place, so that the palette stays a single source of truth.\n27. As a developer changing a fill color, I want the obligation to re-check its\n ink contrast to be visible at the point of change, so that I cannot\n introduce an unreadable pairing without noticing.\n28. As a developer, I want a test to fail if a color utility silently compiles\n to the wrong CSS property, so that the class of bug that made `min-h-10`\n dead cannot recur silently.\n29. As a developer, I want a test to fail if any palette pair drops below its\n contrast floor, so that contrast is enforced rather than audited.\n30. As a developer, I want a test to fail if a scheme leaves any variable\n undefined, so that one scheme cannot silently render with missing colors.\n31. As a developer, I want the migration to leave every call site untouched, so\n that the diff is reviewable and the risk is concentrated in one module.\n32. As an agent working the tracker through the JSON API, I want no API or\n schema change, so that this migration is invisible to me.\n33. As a maintainer, I want the existing routes, role model, storage, and API\n untouched, so that a visual migration cannot break behavior.\n34. As a maintainer, I want the tracker to remain fully functional with zero\n client-side JavaScript, so that the PRD-level zero-JS contract survives.\n\n## Implementation Decisions\n\n### The palette module becomes typed CSS variable references\n\nThe palette module keeps its current key names and gains a second export. Its\n`T` values change from hex literals to **typed** CSS variable references; a new\nexport carries the per-scheme hex tables that the layout shell renders into a\nstylesheet block and that the contrast test asserts over.\n\nBecause every call site interpolates `T.x` inside a Twind arbitrary-value\nbracket (`text-[${T.text}]`), and no token appears in a `style` attribute, all\ncall sites remain byte-identical. Verified against the real class strings: the\nsix prefixes tokens feed are `bg`, `border`, `focus:border`, `hover:bg`,\n`hover:text`, and `text` — all color slots.\n\n### The `color:` type hint is mandatory and non-obvious\n\nThis came out of a prototype and encodes the decision more precisely than prose\ncan. Twind infers the CSS property from the _shape_ of an arbitrary value. A\nbare `var()` is untyped, so it guesses wrong — **silently**, with no error:\n\n```\ntext-[var(--ink)] -> font-size: var(--ink) WRONG\nbg-[var(--canvas)] -> background-image: var(--canvas) WRONG\nborder-[var(--rule)] -> border-width: var(--rule) WRONG\n\ntext-[color:var(--ink)] -> color: var(--ink) correct\nbg-[color:var(--canvas)] -> background-color: var(--canvas) correct\nborder-[color:var(--rule)] -> border-color: var(--rule) correct\n```\n\nSo token values must embed the hint (`text: \"color:var(--ink)\"`), not just the\n`var()`. Confirmed to hold through `hover:` and `focus:` variants and the ring\ncolor. Anyone attempting this without the hint will conclude CSS variables are\nincompatible with Twind and fall back to doubling every call site with `dark:`\nvariants — which is the expensive, wrong path.\n\n### Dual-scheme lives in one generated stylesheet block\n\nThe layout shell renders a `

Diff · v358