feat(i18n,theming): a form wrote English over every field, and a dark select opened white on white

Two visitor-facing defects and the guards that would have caught them.

FORM LABELS. Every label came from a wire name through humanize(), so a Spanish page
rendered `Birth date` over a translated city box, and no catalogue keyed on English source
text could reach it: that text is itself computed here, so there is no constant to key on.
The API now publishes the map at /languages/field-labels, keyed by wire name with enums as
{field}.{value}. It is pulled at BUILD time by scripts/sync-field-labels.ts, which
`bun run generate` calls right after it refreshes the spec, because they are one fact from
one source.

Build time, not run time, and the first answer was the other way round. A runtime fetch was
argued as decoupling language from the release chain, but this form already consumes
version-pinned schema slices baked at build, so there was no decoupling to protect, and on an
embed it would paint English and then re-render translated a moment later. The labels ride
the locales/{lang}.js payload a translated page already downloads: no extra request, English
still ships nothing, works with no network at render time.

humanize() stays as the FALLBACK, which is what makes partial locales shippable: an
untranslated language, a key a translator declined to guess, a blocked request and a page
with no payload are one code path, not four.

DARK MODE. `color-scheme` was never declared anywhere in the library, so the browser painted
every native control light. A <select> looked right closed and opened a light popup whose
<option> rows inherited our near-white --roxy-fg: white on white. Same omission dimmed the
date and time pickers, the number spinner, the autofill highlight and the scrollbar. Declared
once per theme trigger beside the tokens, because a per-control fix cannot reach the popup at
all: the OS renders it outside the DOM.

DATES. formatDateGrain passed a bare date straight to new Date(), which the platform reads as
UTC midnight and Intl renders in the VIEWER's zone, so everyone west of Greenwich read the
previous day. Normalisation moved into resolveDisplayDate and three inline copies went with
it.

GUARDS. THEMING.md is now asserted against tokens.css (every token documented, none invented,
every printed hex correct) and caught three real defects: --roxy-ring and --roxy-accent-ink
were documented as hardcoded hex when both DERIVE from the accent, so the doc told a themer
to override what already follows their brand. The layout e2e now asserts document-level
scroll, and the untranslated-literal ratchet holds every file not in its budget at zero, so a
new component cannot start out leaking.

RELEASE. scripts/purge-cdn.ts purges both jsDelivr aliases and then POLLS x-jsd-version until
every asset serves the published version, as a separate verify-cdn job so a CDN hiccup cannot
strand the packages on npm with no tag or release. Publishing is not shipping: 0.27.2 and
0.27.3 sat half-live for twelve hours with npm correct and nothing erroring.

Author: ph33nx

.github/workflows/release.yml

@@ -250,3 +250,32 @@ jobs:
     steps:
       - id: deployment
         uses: actions/deploy-pages@v5
+
+  # Publishing to npm is NOT shipping. `@latest` resolves per FILE, so a release can go
+  # half-live and stay that way silently: on 2026-08-12, twelve hours after 0.27.2 and
+  # 0.27.3 published, the CDN still served `roxy-ui.js` at 0.27.1 while the locale
+  # catalogues had already moved, so every hosted embed ran a bundle older than the strings
+  # it was loading and rendered untranslated in all seven languages. npm looked correct
+  # throughout and nothing errored. It was a hand-typed runbook step, and it was missed on
+  # two consecutive releases, so it is automated.
+  #
+  # It is a SEPARATE JOB, and deliberately not a step at the end of `release`. The purge can
+  # only run after `npm publish`, but a CDN hiccup must never strand the release: as a step
+  # it would fail before "Commit, tag, push", leaving the packages published with no git
+  # tag, no GitHub Release and no Pages deploy, which is strictly worse than the stale CDN
+  # it exists to prevent. Behind `needs: release` every one of those has already happened,
+  # so a failure here means exactly one thing, says so loudly, and is fixed by re-running
+  # this job alone. The script is idempotent.
+  verify-cdn:
+    needs: release
+    if: needs.release.outputs.version != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+      # No `bun install` and no build. The script talks to the CDN over plain fetch and
+      # derives its asset list from the built manifest plus the theme filenames, both of
+      # which are produced by the release job. It reads them from the checkout, so the
+      # locale and theme lists are whatever that version actually shipped.
+      - name: Purge jsDelivr and verify the edge actually flipped
+        run: bun run purge:cdn ${{ needs.release.outputs.version }}

AGENTS.md

@@ -215,51 +215,6 @@ Several components select a view, mode, or chart layout in addition to `data`. T
 
 The full set: `RoxyNatalChart` `houseSystem`, `RoxyHoroscopeCard` `period`, `RoxyMoonPhase` `mode`, `RoxyCompatibilityCard` `mode`, `RoxyVedicKundli` and `RoxyDivisionalChart` `chartStyle`, `RoxyPanchangTable` `detail`, `RoxyDashaTimeline` `period`, `RoxyDoshaCard` `type`, `RoxyNumerologyCard` `type`, `RoxyTarotSpread` `spread`, `RoxyBiorhythmChart` `mode`, `RoxyHexagram` `mode`. Outside React and Vue, set the same value as a kebab-case attribute or a JS property on the element (for example `chart-style="south"` or `el.chartStyle = 'south'`).
 
-### 6d. Chart without the written report
-
-Every component takes `hide-readings` (`hideReadings` in React and Vue). It renders the chart and the data and leaves the interpretation out of the page: wheels, maps, tables, grids, legends, badges and every number stay, the interpretive prose goes. Off by default, so a component that does not set it is unchanged.
-
-The line is drawn on the CONTENT, never on the block, so a block that reads like analysis still stays when it is made of measurements. `<roxy-natal-chart>` and `<roxy-aspects-table>` both render the `patterns` payload and both make the same cut: the figure name, element, modality, tightness and planet chips are geometry and survive, the paragraph under them is the reading and goes. To remove such a block entirely, use `hide-sections` below.
-
-```html
-<roxy-natal-chart hide-readings></roxy-natal-chart>
-```
-
-```tsx
-<RoxyNatalChart data={chart} hideReadings />
-```
-
-Reach for it when the page supplies its own words, which is the usual case for a practitioner site that writes its own commentary under the chart. The prose is left out of the markup rather than hidden with CSS, so the page never ships text it is not showing.
-
-**Which components act on it.** Every component that renders a written interpretation, so there is no tag you have to test to find out. A pure chart or table has no interpretation to take away, so the attribute is a no-op on those by definition.
-
-One component is a documented no-op despite being mostly prose:
-
-| Component | Behaviour |
-|---|---|
-| `<roxy-dream-card>` | Ignores `hide-readings`. The dream symbol response is the symbol, its dictionary letter and the interpretation, so removing the interpretation would leave a heading over nothing. Style it with `::part(card)` or leave the card out of the page instead. |
-
-What survives, by family: charts keep the drawing, legend, glyphs, degrees and tab strip; tables keep every row and every calculated column (kaksha bindus, koota scores, significance bars, orbs, strengths); cards keep the header, badges, meters and fact grids, so a dosha keeps its verdict, phase and severity, a crystal keeps its Mohs hardness and attribute grid, and a horoscope keeps its energy meter, Moon placement, active transits and key dates; every Vedic response keeps its sidereal frame caption. What goes: interpretation paragraphs, reading accordions, keyword chips attached to a reading, remedies, action steps and strengths lists, and any section whose only content was one of those, heading included.
-
-### 6e. Removing a whole block
-
-Every component also takes `hide-sections` (`hideSections` in React and Vue): a comma-separated list of `part` names, and each one named is taken off that component.
-
-```html
-<roxy-natal-chart hide-sections="patterns"></roxy-natal-chart>
-<roxy-natal-chart hide-sections="patterns, legend"></roxy-natal-chart>
-```
-
-```tsx
-<RoxyNatalChart data={chart} hideSections="patterns" />
-```
-
-**It is per element, which is the difference from a stylesheet.** A `::part()` rule in your CSS reaches every matching component on the site at once; this reaches the one you put it on, so the same chart can keep its patterns on one page and drop them on another with no CSS at all.
-
-**Use `hide-readings` when the words must not ship, and `hide-sections` when a block should not show.** They are different tools rather than two spellings of one. `hide-readings` drops interpretive prose out of the markup entirely, so the page never ships text it is not displaying. `hide-sections` hides the block with CSS and leaves it in the DOM, because a block is a rendering concern and its content may be measurements you have no reason to strip.
-
-Any name a component publishes works, and the names are in `components-catalog.json` under `parts`. A name the component does not carry hides nothing and is not an error, so one list can be applied across a page of mixed components. Names are case-insensitive and spaces around the commas are ignored.
-
 ### 6c. Vue and Nuxt
 
 `@roxyapi/ui-vue` exposes the same components with the same prop names. Bind `data` and the config props normally; the package sets them as DOM properties for you, so an object payload never gets stringified into an attribute. Listen to widget events with the usual `@` syntax.
@@ -607,20 +562,37 @@ Per-element scope is supported:
 
 Every visible aspect of the chart is driven by `--roxy-*` CSS custom properties on `:host`. Override any token on `:root`, on `:host`, or per element. Do not write Tailwind utility classes inside the components; the Shadow DOM boundary stops them at the door.
 
-## Restyling a block from outside the component
+## Choosing what a component renders
 
-Tokens cover colour, spacing and type. When you need to reach a specific block, every chart and reading component names its structural pieces with `part`, so a stylesheet on the page can target them. The names are identical in every component, so one rule covers the library.
+Three tools, one vocabulary. Every structural block carries a `part` name; `::part()` targets it from a stylesheet, `hide-sections` drops it on one element, and `hide-readings` removes interpretive prose from the markup entirely.
 
-```css
-roxy-natal-chart::part(readings) {
-	display: none;
-}
-roxy-natal-chart::part(card) {
-	border: 0;
-	box-shadow: none;
-}
+**Pick by what you need:**
+
+| Need | Use |
+|---|---|
+| Restyle a block | `::part(name)` in your CSS |
+| Hide a block everywhere on the site | `::part(name) { display: none }` |
+| Hide a block on ONE element, keep it on another | `hide-sections="name"` |
+| Keep the chart, drop the written interpretation | `hide-readings` |
+
+`hide-readings` and `hide-sections` are different tools, not two spellings of one. `hide-readings` leaves the prose out of the markup, so the page never ships text it is not displaying. `hide-sections` hides the block whatever it holds, because a block may be measurements you have no reason to strip.
+
+```html
+<roxy-natal-chart hide-readings></roxy-natal-chart>
+<roxy-natal-chart hide-sections="patterns, legend"></roxy-natal-chart>
+```
+
+```tsx
+<RoxyNatalChart data={chart} hideReadings />
+<RoxyNatalChart data={chart} hideSections="patterns" />
 ```
 
+Both are off by default. `hide-sections` takes a comma-separated list, is case-insensitive, ignores spaces around commas, and a name the component does not carry hides nothing and is not an error, so one list can be applied across a page of mixed components.
+
+**The line `hide-readings` draws is on the CONTENT, never on the block**, so a block that reads like analysis stays when it is made of measurements. `<roxy-natal-chart>` and `<roxy-aspects-table>` both render the `patterns` payload and both make the same cut: figure name, element, modality, tightness and planet chips are geometry and survive; the paragraph under them is the reading and goes. To remove the block itself, that is what `hide-sections` is for. What survives elsewhere: charts keep the drawing, legend, glyphs, degrees and tab strip; tables keep every calculated column (kaksha bindus, koota scores, orbs, strengths); cards keep header, badges, meters and fact grids; every Vedic response keeps its sidereal frame caption. One documented no-op: `<roxy-dream-card>` ignores `hide-readings`, because the response IS the interpretation and removing it would leave a heading over nothing.
+
+### The part vocabulary
+
 | part | What it names |
 |---|---|
 | `card` | The component's own card or wrapper root |
@@ -635,9 +607,7 @@ roxy-natal-chart::part(card) {
 | `reading` | One disclosure card inside it |
 | `form`, `loading`, `error`, `edit-bar`, `attribution` | The built-in states, on every component |
 
-The table is the shared vocabulary, not the whole list. **`components-catalog.json` carries a `parts` array for every component, so you can read the exact names a component answers to instead of guessing or inspecting the DOM.** A name means the same block wherever it appears, which is what makes one rule enough: `::part(aspects)` reaches the aspect grid on a natal chart, the aspect list on an aspects table and the transit aspects on a transits table alike.
-
-Two notes. Parts reach exactly one shadow root deep, and a component that draws another one re-exports its parts, so `roxy-relocation-wheel::part(readings)` reaches the wheel it nests. And to remove a reading rather than hide it, use `hide-readings` (above): a `display: none` rule still ships the words in the page.
+That table is the shared vocabulary, not the whole list. **`components-catalog.json` carries a `parts` array for every component, so read the exact names a component answers to instead of guessing or inspecting the DOM.** A name means the same block wherever it appears, which is what makes one rule enough: `::part(aspects)` reaches the aspect grid on a natal chart, the aspect list on an aspects table and the transit aspects on a transits table alike. Parts reach exactly one shadow root deep, and a component that draws another re-exports its parts, so `roxy-relocation-wheel::part(readings)` reaches the wheel it nests.
 
 ## Rules every agent must follow
 
@@ -651,7 +621,7 @@ Two notes. Parts reach exactly one shadow root deep, and a component that draws
 
 ## Domain ordering
 
-When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain.
+When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, forecast, human design, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain. The `domain` field in `components-catalog.json` carries the same names, so sort by this list rather than by whatever order you discovered components in.
 
 ## What not to ship
 
@@ -666,9 +636,8 @@ When listing domains in user-visible copy, use the canonical order: Western astr
 
 ## Where to look next
 
-- Component source: `packages/ui/src/components/`
-- Sample data for every component: `apps/docs/sample-data.js`
-- Token reference: `packages/ui/THEMING.md`
-- Live preview: `bun run preview` then open `http://localhost:3001`
+- **Machine-readable catalog, and the one to reach for first**: <https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/components-catalog.json>. Every component with its `tag`, `pascal` name, `domain`, what it renders, the `endpoints` it consumes, its `parts`, and copy-paste `snippets`. Fetch and query it instead of scraping the tables in this file.
+- Token reference: `THEMING.md`, beside this file in the package
 - Endpoint reference: <https://roxyapi.com/api-reference>
-- Machine-readable component catalog (every component, its domain, what it renders, and the endpoint(s) it consumes): <https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/components-catalog.json>. Fetch it to discover or map components programmatically instead of scraping this table.
+- Integration guide: <https://roxyapi.com/docs/ui>
+- Live preview of every component: <https://roxyapi.github.io/ui/>

README.md

@@ -736,7 +736,11 @@ roxy-natal-chart::part(card) {
 }
 ```
 
-The parts: `card`, `header`, `chart`, `legend`, `details`, `table`, `tablist`, `tab`, `panel`, `section`, `readings`, `reading`, plus `form`, `loading`, `error` and `attribution` on the built-in states. A `section` also carries its own name, which is what `::part(patterns)` above targets, so any single block can be dropped or restyled on its own.
+The parts: `card`, `header`, `chart`, `legend`, `details`, `table`, `tablist`, `tab`, `panel`, `section`, `readings`, `reading`, plus `form`, `loading`, `error`, `edit-bar` and `attribution` on the built-in states. A `section` also carries its own name, which is what `::part(patterns)` above targets, so any single block can be dropped or restyled on its own.
+
+That list is the shared vocabulary, not the whole set. **[`components-catalog.json`](https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/components-catalog.json) carries a `parts` array for every component**, so you can read the exact names a component answers to instead of guessing or inspecting the DOM. A name means the same block wherever it appears, which is what makes one rule enough: `::part(aspects)` reaches the aspect grid on a natal chart, the aspect list on an aspects table and the transit aspects on a transits table alike.
+
+One nesting rule worth knowing: parts reach exactly one shadow root deep, and a component that draws another one re-exports its parts, so `roxy-relocation-wheel::part(readings)` reaches the wheel nested inside it.
 
 ### Chart without the written report
 
@@ -752,7 +756,7 @@ For the same outcome in markup rather than CSS, set `hide-readings`. The compone
 
 It is off by default, so nothing changes until you ask for it. Wheels, maps, tables, grids, legends, badges and every number stay; the interpretive prose is what goes.
 
-That line is drawn on the content, not on the block, so a block made of measurements stays even when it reads like analysis. The clearest case is the natal chart patterns block: a T-Square or a Stellium is a geometric fact about where the bodies sit, so the figure, its element and modality, its tightness and its planets all survive, and only the paragraph under them goes. To drop the block itself, hide its part: `roxy-natal-chart::part(patterns) { display: none }`.
+That line is drawn on the content, not on the block, so a block made of measurements stays even when it reads like analysis. The clearest case is the natal chart patterns block: a T-Square or a Stellium is a geometric fact about where the bodies sit, so the figure, its element and modality, its tightness and its planets all survive, and only the paragraph under them goes. To drop the block itself, use `hide-sections` below.
 
 #### Which components it applies to
 
@@ -773,6 +777,25 @@ What each family keeps when you set it:
 
 What goes: interpretation paragraphs, the reading accordions, keyword chips attached to a reading, remedies and action steps and strengths lists (sentences laid out as bullets), and any section whose only content was one of those, heading included.
 
+### Remove a whole block
+
+Every component also takes `hide-sections` (`hideSections` in React and Vue): a comma-separated list of `part` names, and each one named is taken off that component.
+
+```html
+<roxy-natal-chart hide-sections="patterns"></roxy-natal-chart>
+<roxy-natal-chart hide-sections="patterns, legend"></roxy-natal-chart>
+```
+
+```tsx
+<RoxyNatalChart data={chart} hideSections="patterns" />
+```
+
+The names are the same `part` names listed above, so anything you can target with `::part()` you can also drop with an attribute. The rule is generated from the name rather than from a list of components that opted in, so it works on every component, and a name no block carries hides nothing rather than erroring.
+
+**Use `hide-readings` when the words must not ship, and `hide-sections` when a block should not show.** They are different tools rather than two spellings of one. `hide-readings` drops interpretive prose out of the markup entirely, so the page never ships text it is not displaying. `hide-sections` hides the block and leaves it in the DOM, because a block is a rendering concern and its content may be measurements you have no reason to strip.
+
+**Reach for `::part()` instead when one rule should cover a whole site**, and for `hide-sections` when two components on the same page have to differ, which a stylesheet cannot express.
+
 ## Languages
 
 A component reads the page language and renders its own labels in it. Set `lang` on the element, on any ancestor of it, or on `<html>`, and add the catalogue for that language.

package.json

@@ -18,10 +18,12 @@
 		"build:registry": "bun run scripts/build-registry.ts",
 		"build:widgets": "bun run scripts/build-widgets.ts",
 		"build:schemas": "bun run scripts/build-schemas.ts",
+		"purge:cdn": "bun run scripts/purge-cdn.ts",
 		"size:check": "bun run scripts/check-sizes.ts",
 		"docs:sync": "bun run scripts/sync-docs.ts",
 		"version:sync": "bun run scripts/sync-version.ts",
 		"tokens:sync": "bun run scripts/sync-tokens.ts",
+		"labels:sync": "bun run scripts/sync-field-labels.ts",
 		"themes:sync": "bun run scripts/sync-themes.ts",
 		"manifest:sync": "bun run scripts/sync-manifest.ts",
 		"bindings:sync": "bun run scripts/sync-bindings.ts",