eidotter 0.40.2 → 0.41.1

package/migrations/0.41.0.md

@@ -0,0 +1,883 @@
+# Upgrading to eidotter 0.41.0
+
+This guide is for developers and AI agents working in an app that consumes the
+`eidotter` npm package. It assumes you have not seen the eidotter repository.
+Everything here was checked against the 0.41.0 source and the published
+`dist/` output. Linear ids (DMNC-xxxx) are references only; you do not need
+access to them.
+
+You are reading this from `node_modules/eidotter/migrations/0.41.0.md`, or from
+the repository's `migrations/` folder. If you are upgrading across several
+minors, read [`README.md`](./README.md) in this folder first.
+
+> **Install 0.41.1 or later.** 0.41.0 was published before the release review fixes. It lacks the eidotter token utilities that section 2 promises, its reset still cancels Tailwind v4 utilities, and `Stat` loses its colours. 0.41.1 fixes all of this with no API change, and everything in this guide applies to it.
+
+## Who must act
+
+Every consumer. 0.41.0 is a 0.x **minor**, so it carries visible changes, and a
+caret range on 0.40 does not pick it up.
+
+In three lines:
+
+1. Body text has a 16px floor (Tailwind preset `text-xs`/`text-sm` are now
+   1rem), `eidotter/styles` stops leaking its CSS reset (fonts, link colours)
+   and its unused utilities into your app, and `text-secondary` is now a
+   visible tone, not near-black.
+2. `Header` shows the logo lockup by default with uppercase nav, and Modal,
+   Lightbox, CmdPalette, Card, DosFigure, Alert, Notification, Logo and Mark
+   look different. Some overlay CSS classes are gone.
+3. New shared pieces replace hand-rolled code: `IconButton`, `DosDialog`,
+   `DosWindow`, a `Header` `end` slot, the `amber-paper` theme and the
+   `eidotter/favicon.svg` asset.
+
+No public prop was removed or renamed. A diff of every published `.d.ts` in
+`dist/components` between 0.40.2 and 0.41.0 shows only additions. What can
+break is CSS: your overrides, your reliance on leaked global styles, and
+utility classes you used without having Tailwind yourself.
+
+### Which sections apply to your stack
+
+| Your stack | Read especially |
+|---|---|
+| Tailwind 3 or 4 with `eidotter/tailwind.preset` | 1 (16px floor), 3, 5, 6, 7 |
+| Tailwind 4 without the preset | 1 (component sizes only), 3, 5, 6, 7 |
+| No Tailwind (plain CSS, Astro, Vite React) | 2 (utilities removed), 4 (reset no longer leaks), 3, 5, 6, 7 |
+| Next.js App Router (server components) | all of the above plus "RSC deep imports" |
+
+## How to bump
+
+0.x caret ranges stop at the next minor: `^0.40.2` means `>=0.40.2 <0.41.0`.
+Older ranges such as `^0.38.0`, `^0.37.0` or `^0.33.0` are the same: none of
+them reach 0.41.0. Change the range explicitly:
+
+```bash
+npm install eidotter@^0.41.1
+# check what actually resolved
+npm ls eidotter
+```
+
+Install from the npm registry. Do not point the dependency at a local checkout
+(`file:../eidotter`): `npm ci` passes, but CI, Docker and Vercel builds fail
+with "Module not found".
+
+Before you bump, save a copy of the old bundle. You need it for the class diff
+in section 2:
+
+```bash
+cp node_modules/eidotter/dist/eidotter.css /tmp/eidotter-old.css
+```
+
+If you are coming from older than 0.40, also read
+"Jumping from older versions" at the end.
+
+---
+
+## Breaking and visible changes
+
+Each item is: what changed, how to find it in your code, what to do, how to
+verify. Patterns use `rg` (ripgrep). If you only have grep, `grep -rnE` with the
+same pattern works. Adjust the search roots (`src app components pages`) to
+your repo.
+
+### 1. 16px body-size floor; preset `text-xs` / `text-sm` are 1rem (DMNC-1579)
+
+**What changed.** The Tailwind preset (`eidotter/tailwind.preset`) now maps
+Tailwind's `text-xs` and `text-sm` to `1rem` with a `1.25rem` line height. A
+new token `--typography-font-size-text-base` (1rem) and utility
+`text-dos-text-base` exist. Inside eidotter, `Breadcrumb` (was 12px with 0.35em
+tracking, now 16px with 0.1em), `Footer` (was 14px), `Input` label, description
+and error text (were 12px) and the `Header` brand link render at 16px.
+`Progress` sizes `sm`/`md`/`lg` render 16/20/22px.
+
+The preset alias only affects apps that load the preset. The bundle
+(`dist/eidotter.css`) no longer ships any stock `.text-xs` … `.text-9xl` rule,
+so it no longer overrides your own Tailwind sizes (0.40 shipped an unlayered
+`.text-xs{font-size:1rem}` that did).
+
+**Find it.**
+
+```bash
+# Tailwind classes that will now render at 16px (preset users)
+rg -n '\btext-(xs|sm)\b' src app components pages
+# overrides you added to bump eidotter components up to body size
+rg -n -A4 '\.eidotter-(breadcrumb|footer|input|header__branding)' --glob '*.{css,scss}'
+rg -n 'text-base' src app components | rg -i 'breadcrumb|footer|input|header'
+```
+
+**What to do.**
+
+- Preset users: expect `text-xs`/`text-sm` text to grow to 16px. The floor is
+  deliberate (the DOS VGA cell is 9×16). Where a label now overflows on mobile,
+  shorten the label; do not widen its container.
+- Delete per-element `font-size` / `text-base` overrides you added to
+  Breadcrumb, Footer, Input or the Header brand. They are now redundant.
+- Prefer `text-dos-text-base` over `text-base` for body-size text in new code.
+
+```tsx
+// before (0.40): forcing eidotter's small Breadcrumb up to body size
+<div className="[&_.eidotter-breadcrumb]:text-base"><Breadcrumb items={crumbs} /></div>
+// after (0.41): the component is already 16px
+<Breadcrumb items={crumbs} />
+```
+
+**Verify.** In the browser,
+`getComputedStyle(document.querySelector('.eidotter-breadcrumb')).fontSize`
+is `"16px"`. Check that no label wraps or overflows at 390px width.
+
+### 2. Utilities removed from `dist/eidotter.css` (consumers without their own Tailwind)
+
+**What changed.** The bundle used to contain every stock Tailwind utility
+that appeared anywhere in eidotter's docs and stories. It now contains only the
+stock utilities used by shipped component source. Apps that used those generic
+classes in their own markup without running Tailwind themselves lose them. Apps
+that run their own Tailwind are not affected, because their build generates the
+classes.
+
+eidotter's own token utilities stay available without Tailwind:
+`text-dos-*`, `bg-dos-*`, `border-dos-*`, `shadow-dos-*`, `font-dos-*`
+(including the `font-dos-bold` / `-semibold` / `-regular` aliases), `bg-cga-*`
+and `text-cga-*`.
+
+Examples of generic utilities that are gone:
+
+- Layout and spacing: `mt-4`, `p-3`, `space-y-2`, `grid-cols-1`,
+  `grid-cols-2`, `md:grid-cols-2`, `md:grid-cols-4`, `lg:grid-cols-3`,
+  `col-span-2`, `max-w-3xl`, `max-w-5xl`, `min-h-screen`, `flex-grow`,
+  `flex-shrink`, `float-left`, `float-right`, `contents`, `isolate`,
+  `inline-grid`, `print:hidden`.
+- Borders and radius: `border-t`, `border-r`, `border-l`, `border-x`,
+  `border-y`, `border-transparent`, `divide-x`, `divide-y`, `rounded`,
+  `rounded-t`, `rounded-b`, `rounded-l`, `rounded-r`.
+- Typography: the stock sizes `text-xs`, `text-sm`, `text-base`, `text-lg`,
+  `text-xl`, plus `italic`, `capitalize`, `lowercase`, `antialiased`,
+  `text-wrap`.
+
+That list is not exhaustive. Compute the exact diff for your installed versions.
+
+**Find it.** After the bump, compare the saved old bundle with the new one and
+search your code for each removed class:
+
+```bash
+node -e '
+const fs = require("fs");
+const classes = (f) => new Set([...fs.readFileSync(f, "utf8")
+  .matchAll(/\.(-?[A-Za-z_](?:\\.|[A-Za-z0-9_-])*)/g)].map((m) => m[1].replace(/\\/g, "")));
+const before = classes("/tmp/eidotter-old.css");
+const after = classes("node_modules/eidotter/dist/eidotter.css");
+console.log([...before].filter((c) => !after.has(c)).sort().join("\n"));
+' > /tmp/eidotter-removed-classes.txt
+wc -l /tmp/eidotter-removed-classes.txt
+rg -n -w -F -f /tmp/eidotter-removed-classes.txt src app components pages \
+  --glob '*.{tsx,jsx,ts,js,astro,html,mdx,vue,svelte}'
+```
+
+Review the hits by hand. A `-w` match on a short word such as `contents` or
+`rounded` can be a false positive in prose. Ignore any eidotter token utility
+(`*-dos-*`, `*-cga-*`) the diff lists; those remain supported.
+
+**What to do.** For each real hit, pick one:
+
+- Replace the utility with a semantic class or a plain CSS rule in your own
+  stylesheet using eidotter tokens:
+
+  ```css
+  /* before: <p class="grid grid-cols-2 mt-4"> relied on eidotter's bundle */
+  /* after: your own CSS */
+  .intro { display: grid; grid-template-columns: 1fr 1fr; margin-top: var(--spacing-4); } /* 16px */
+  ```
+
+  All token names are in `node_modules/eidotter/src/styles/tokens.css`.
+- For display or body typography in raw HTML, the `.dos-*` classes from
+  `import 'eidotter/utilities'` (`.dos-body`, `.dos-caption`, `.dos-h1` …
+  `.dos-h5`, `.dos-label`, `.dos-code`) are another option.
+- Or add Tailwind to the app and load `eidotter/tailwind.preset`, which
+  generates any of these classes on demand.
+
+**Verify.** Rerun the `rg` command: no hits left that you did not deliberately
+keep. Visually check the pages that had hits.
+
+### 3. `text-secondary` changed meaning; use `text-on-accent` / `text-on-brand` / `text-on-light` (DMNC-1494)
+
+**What changed.** `--color-semantic-text-secondary` (Tailwind
+`text-dos-text-secondary`) used to resolve to the darkest CGA value: the same
+near-black as the page background. That made it correct only for dark text on
+an amber or light fill, and invisible everywhere else. It now resolves to a
+visible, de-emphasised tone (the `light-gray` primitive on dark themes; warm
+tan `#b87c1a` under amber-mono; near-black under the light theme). Three new
+tokens name text-on-fill explicitly:
+
+| Token | Tailwind | Use for |
+|---|---|---|
+| `--color-semantic-text-on-accent` | `text-dos-text-on-accent` | text/icons on a `background-accent` fill (eidotter uses it for the Button primary label, Badge accent, Tag filled, Tabs pills, FilterBar active, Switch thumb, Accordion header, Terminal title bar). This is the old `text-secondary` value. |
+| `--color-semantic-text-on-brand` | `text-dos-text-on-brand` | text/icons on a brand-amber fill (`background-brand`; eidotter uses it for InlineLink hover/active and the IconButton hover glyph) |
+| `--color-semantic-text-on-light` | `text-dos-text-on-light` | an unfilled element sitting on a light surface; near-black in every theme (eidotter uses it for `Nav` `modern` links) |
+
+`text-on-accent` and `text-on-brand` are identical under amber-mono. They
+differ in `cga-amber`, where the accent fill is blue and on-accent text is
+light. So pick by the fill underneath, not by the colour you see today.
+
+**Find it.**
+
+```bash
+rg -n 'text-dos-text-secondary|color-semantic-text-secondary|border-dos-text-secondary' \
+  src app components pages styles --glob '!node_modules'
+```
+
+**What to do.** Look at what each hit sits on.
+
+- Dark text on an accent fill (`bg-dos-bg-accent`): switch to `text-on-accent`.
+  On a brand fill (`bg-dos-bg-brand`): `text-on-brand`. Unfilled text on a
+  light surface: `text-on-light`.
+
+  ```tsx
+  // before
+  <span className="bg-dos-bg-accent text-dos-text-secondary">NEW</span>
+  // after
+  <span className="bg-dos-bg-accent text-dos-text-on-accent">NEW</span>
+  ```
+
+  ```css
+  /* before */ .chip--active { color: var(--color-semantic-text-secondary); }
+  /* after  */ .chip--active { color: var(--color-semantic-text-on-accent); }
+  ```
+
+- De-emphasised text on a dark background: leave it. It is now visible, as you
+  intended.
+
+**Verify.** Every former hit renders legibly in the default theme and in any
+theme you offer (`light`, `amber-paper`). Check colours with
+`getComputedStyle(el).color`; screenshots taken under WSL/Playwright can shift
+amber hues.
+
+### 4. `eidotter/styles` no longer leaks its CSS reset (fonts, link colours) (DMNC-1434)
+
+**What changed.** Up to 0.40, `import 'eidotter/styles'` carried Tailwind's
+preflight unlayered. Two parts of it overrode your app's styles whatever their
+specificity: `a { color: inherit; text-decoration: inherit }` turned every link
+the surrounding text colour, and `html, :host { font-family: … }` plus
+Tailwind's default `--font-sans` / `--font-mono` / `--default-font-family` /
+`--default-mono-font-family` variables set a system sans-serif and beat a
+Tailwind v4 `@theme` font. 0.41.0 strips those. eidotter components style their
+own fonts and anchors and render unchanged.
+
+Who sees a difference: apps **without a preflight of their own** (no Tailwind)
+that set no font on `html`/`body`. Bare text now shows the browser default font
+(usually a serif), and plain `<a>` outside eidotter components shows the browser
+link colour (blue/purple, underlined). Apps with their own Tailwind keep their
+own preflight, which already resets links; for them the change only removes
+the interference.
+
+**Find it.**
+
+```bash
+# do you set a font and link styles yourself?
+rg -n 'font-family' --glob '*.{css,scss,astro}' src app styles
+rg -n '(^|[\s,}])a\s*(,|\{|:)' --glob '*.{css,scss}' src app styles
+```
+
+Then open the app with the new version and look for serif body text or blue
+links.
+
+**What to do.** Set what you relied on in your own global stylesheet:
+
+```css
+/* global.css — loaded after eidotter/styles */
+html {
+  background: var(--color-semantic-background-primary);
+  color: var(--color-semantic-text-primary);
+  font-family: var(--typography-font-family-body); /* JetBrains Mono Nerd Font */
+  /* or var(--typography-font-family-primary) for Perfect DOS VGA 437 everywhere */
+}
+a { color: var(--color-semantic-text-accent); }
+```
+
+If you want the old "links look like the text around them" behaviour, add
+`a { color: inherit; text-decoration: inherit; }` yourself. With Tailwind v4,
+put such rules in `@layer base { … }` so your utilities still win.
+
+**Verify.** `getComputedStyle(document.body).fontFamily` names your intended
+font. A bare link outside eidotter components is not `rgb(0, 0, 238)` (the
+browser default blue), unless you want it to be.
+
+### 5. `Header`: lockup brand by default, quieter retro styling, uppercase nav, `end` slot (DMNC-1584)
+
+**What changed.**
+
+- **Default brand is the lockup.** When you pass `brandName` and no `children`,
+  the header now renders the eiDotter Logo (28px, glow) next to the name in
+  uppercase, wide-tracked DOS text. The new prop
+  `brand?: 'lockup' | 'mark' | 'text'` (default `'lockup'`) selects it.
+  `brand="text"` restores the 0.40 plain-text brand. Headers that pass their
+  own `children` as branding render unchanged.
+- **Retro styling.** The strong amber glow becomes a soft glow under a 1px
+  dim-amber line. The brand link and the context-row return pill use brand
+  amber (`text-brand`) and lift to `text-brand-bright` on hover. Retro `Nav`
+  desktop and mobile-panel links and the MENU trigger use the same pair, and
+  their labels render uppercase (CSS `text-transform`, so your label strings
+  are unchanged). The `modern` variant is unchanged.
+- **New `end` slot.** `end?: ReactNode` renders once: after the desktop nav on
+  wide screens, between the brand and the MENU trigger below 768px. Without it
+  the DOM is unchanged.
+- **New `skipLinkTarget`.** `skipLinkTarget="#main"` renders a visually hidden
+  "Skip to content" link as the header's first child, shown on keyboard focus.
+  Off by default.
+
+**Find it.**
+
+```bash
+rg -n -A8 '<Header\b' src app components pages      # brandName without children?
+rg -n 'eidotter-header|eidotter-nav' --glob '*.{css,scss}' src app styles
+rg -n 'position:\s*absolute' --glob '*.{css,scss}' src app styles | rg -i 'header|toggle|theme'
+```
+
+**What to do.**
+
+```tsx
+// before (0.40): plain-text brand, theme toggle positioned by hand over the header
+<div className="relative">
+  <Header brandName="MY SITE" items={nav} activeHref={pathname} />
+  <ThemeToggle className="absolute right-16 top-3" />
+</div>
+
+// after (0.41): keep the lockup (or brand="text" for the old look), toggle in `end`
+<Header
+  brandName="MY SITE"
+  items={nav}
+  activeHref={pathname}
+  end={<ThemeToggle />}
+  skipLinkTarget="#main"
+/>
+<main id="main">…</main>
+```
+
+- Decide per site: lockup (default), `brand="mark"` (see "Adopt"), or
+  `brand="text"`.
+- Delete CSS that recoloured the retro header/nav to brand amber or forced
+  uppercase on nav links. That is now the default.
+- Delete CSS that targeted the old strong glow on `.eidotter-header--retro`.
+- Keep `end` content compact: on mobile it clips before the brand name does.
+- The `end` slot is `overflow: hidden` at every width. A dropdown, menu or
+  tooltip opened from it must render in a portal (React Aria popovers such as
+  `Select` already do); an in-flow popover is clipped.
+
+**Verify.** At 390px the brand, the `end` content and the MENU trigger fit on
+one line. At 1280px it reads brand, nav, then `end`. Tabbing from the address
+bar focuses the skip link first, if you set one.
+
+### 6. Overlays rebuilt on `DosDialog`; removed classes (DMNC-1592)
+
+**What changed.** `Modal`, `Lightbox` and `CmdPalette` now render inside the
+shared `DosDialog` shell: brand-coloured border with amber glow, square
+corners, a blurred scrim, and a dark title strip (yellow title, `▸` marker,
+uppercase, dim-amber rule). They enter and exit with a shared pop (scale 0.8
+to 1, 150ms). Their z-index is `--z-index-modal` (1040). Modal was 50 and
+Lightbox 60, so opening a Lightbox over an open Modal is no longer supported.
+Props are unchanged except for additions (Modal gained `size` and
+`isDismissable`).
+
+Specific visible changes: Modal's yellow frame becomes the brand border and its
+header becomes the strip; long Modal titles wrap. Lightbox gains a strip whose
+title is the `[ n / N ]` counter, spans the viewport minus 32px, and its prev and
+next arrows are pixel chevron `IconButton`s. CmdPalette's `▸ JUMP TO` head loses
+its amber fill and becomes the dark strip; at phone width the box is capped at
+viewport minus 32px.
+
+**Removed classes.** CSS that targets these no longer matches anything:
+
+| Component | Removed | Target instead |
+|---|---|---|
+| Modal | `eidotter-modal-overlay`, `eidotter-modal-overlay--entering`, `eidotter-modal-overlay--exiting`, `eidotter-modal`, `eidotter-modal--entering`, `eidotter-modal--exiting`, `eidotter-modal__header`, `eidotter-modal__title` | `eidotter-dialog__overlay`, `eidotter-dialog`, `eidotter-dialog__container`, `eidotter-dialog__head`, `eidotter-dialog__title` |
+| Lightbox | `eidotter-lightbox-overlay`, `eidotter-lightbox-overlay--entering`, `eidotter-lightbox-overlay--exiting`, `eidotter-lightbox`, `eidotter-lightbox--entering`, `eidotter-lightbox--exiting` | the `eidotter-dialog*` classes above |
+| CmdPalette | `eidotter-cmdpal-overlay`, `eidotter-cmdpal-overlay--entering`, `eidotter-cmdpal-overlay--exiting`, `eidotter-cmdpal`, `eidotter-cmdpal--entering`, `eidotter-cmdpal--exiting`, `eidotter-cmdpal__head` | the `eidotter-dialog*` classes; the head is `eidotter-dialog__head` |
+| Card | `eidotter-card__header`, `eidotter-card__footer` | `eidotter-window__strip`, `eidotter-window__footer` |
+| DosFigure | `eidotter-dos-figure__title` | `eidotter-window__strip`, `eidotter-window__title` |
+| Mark | `eidotter-mark__blob`, `eidotter-mark__blob--morph` | the root `eidotter-mark` (the drawing is now an SVG) |
+
+Still present: `eidotter-modal__container`, `__body`, `__footer`, `__close`;
+`eidotter-lightbox__container`, `__counter`, `__close`, `__figure`, `__image`,
+`__caption`, `__nav`; `eidotter-cmdpal__container`, `__input`, `__results`,
+`__item*`, `__empty`, `__footer`, `__blink`, plus the new
+`eidotter-cmdpal__text--bright` / `--muted`. The close and navigation classes
+(`eidotter-modal__close`, `eidotter-lightbox__close`, `eidotter-lightbox__nav`,
+`eidotter-nav__close`, `eidotter-alert__close`, `eidotter-notification__close`,
+`eidotter-tag__close`) stay on the buttons as hooks, but their old visual
+styles are gone: the buttons are now `IconButton`s (class
+`eidotter-icon-button`).
+
+The `eidotter-dialog*` classes are shared by every DosDialog. To restyle one
+kind of overlay only, scope your rule by the component's container class,
+which sits on the same element as `eidotter-dialog__container`:
+`.eidotter-modal__container`, `.eidotter-lightbox__container` or
+`.eidotter-cmdpal__container`. Modal and CmdPalette also merge your
+`className` onto that element.
+
+**Find it.**
+
+```bash
+rg -n 'eidotter-(modal-overlay|modal--|modal__header|modal__title|lightbox-overlay|lightbox--|cmdpal-overlay|cmdpal--|cmdpal__head|card__header|card__footer|dos-figure__title|mark__blob)' \
+  src app components pages styles
+rg -n '\.eidotter-(modal|lightbox|cmdpal)\b' --glob '*.{css,scss}' src app styles
+rg -n 'eidotter-(modal|lightbox|alert|notification|tag|nav)__close|eidotter-lightbox__nav' \
+  --glob '*.{css,scss}' src app styles
+rg -n 'z-index' --glob '*.{css,scss}' src app styles | rg -i 'modal|lightbox|overlay|cmdpal'
+```
+
+**What to do.**
+
+- Delete overrides that restyled the old frame, header, scrim or enter/exit
+  animation. The new chrome is the house style; first see whether you still
+  need anything.
+- Retarget what you still need, using the table above.
+- Delete restyles of the close and prev/next buttons. The shared IconButton
+  already has hover, focus and disabled states.
+- If your own fixed or sticky UI must sit above or below dialogs, compare it
+  against 1040, not 50 or 60.
+
+```css
+/* before (0.40) */
+.eidotter-modal__header { background: var(--color-semantic-background-secondary); }
+.eidotter-modal-overlay { backdrop-filter: blur(4px); }
+/* after (0.41): usually delete both; if you must keep a tweak, retarget it */
+.eidotter-modal__container .eidotter-dialog__head { /* … */ }
+```
+
+**Verify.** Open each Modal, Lightbox and CmdPalette in your app. Escape and a
+backdrop click close them, focus returns to the trigger, and nothing of yours
+paints over the dialog. A Modal with a long title wraps instead of clipping.
+
+### 7. Other visible restyles
+
+Each of these is CSS only, with no prop change. Search for overrides and
+delete or retarget them.
+
+- **Card** is built on `DosWindow`. The header becomes the dark strip (yellow
+  xs uppercase title, `▸` marker, dim-amber rule), and the footer becomes the
+  window footer. `elevated` is now the brand border plus `--shadow-drop`
+  instead of a near-black border with a 4px offset shadow. Find:
+  `rg -n 'eidotter-card' --glob '*.{css,scss}'`.
+- **DosFigure** is built on `DosWindow`. The amber title bar with dark text
+  becomes the dark strip. Find: `rg -n 'eidotter-dos-figure' --glob '*.{css,scss}'`.
+- **Alert and Notification** are square (no 4px radius) and their close is an
+  outlined 36×36 IconButton. Find:
+  `rg -n 'eidotter-(alert|notification)' --glob '*.{css,scss}'`.
+- **Tag remove** is a bare IconButton with the pixel X instead of `[x]`. The
+  accessible name is still `Remove <label>`. Tests that query the text `[x]`
+  must query the button by role and name instead:
+
+  ```ts
+  // before
+  screen.getByText('[x]');
+  // after
+  screen.getByRole('button', { name: 'Remove react' });
+  ```
+
+  Find: `rg -n "\[x\]" --glob '*.{test,spec}.{ts,tsx,js,jsx}'`.
+- **Lightbox prev/next** are chevron IconButtons instead of `◀ ▶` text. Find
+  tests that query those glyphs: `rg -n '◀|▶' --glob '*.{test,spec}.*'`.
+- **Logo and Mark** share one SVG drawing (DMNC-1586). Logo's flat yolk becomes
+  a lit yolk with highlights, and its glow drops from 6px to 5px. Mark renders
+  that SVG instead of a CSS blob. The `morph` prop now drives a slow breath
+  (scale to 1.045, 4.3s) and is off under reduced motion. Mark gains `glow`
+  (default `true`). `size`, `label`, `arms`, the ref and the root class
+  `eidotter-mark` are unchanged. Find:
+  `rg -n 'eidotter-(logo|mark)' --glob '*.{css,scss}'` and any copied favicon
+  (`rg --files | rg -i 'favicon|icon\.svg'`). Re-copy the favicon (see
+  "Adopt").
+- **Motion.** Select's popover pops instead of dropping 4px. TimelineContainer
+  zoom views and the master-detail pane fade instead of rising. Several
+  components share keyframes now (`eidotter-pop-in/out`,
+  `eidotter-fade-in/out`, `eidotter-breathe`). If your CSS overrode eidotter's
+  internal keyframe names (`modal-crt-enter`, `cmdpal-enter`, `tag-enter`,
+  `badge-enter`, `alert-enter`, `notification-enter`, `select-pop-in`,
+  `eidotter-mark-morph`, `eidotter-card-enter`, `eidotter-inline-expand-fade`,
+  `eidotter-timeline-node-enter`, `eidotter-skeleton-breathe`,
+  `eidotter-health-breathe`, …), those names no longer exist. Find:
+  `rg -n 'modal-crt|cmdpal-|badge-enter|tag-enter|tag-exit|alert-enter|notification-enter|select-pop|backdrop-open|timeline-fade-in|master-detail-fade|blink-loading|eidotter-(mark-morph|card-enter|inline-expand-fade|timeline-node-enter|skeleton-breathe|health-breathe)' --glob '*.{css,scss}'`.
+- **Progress** sizes are distinct again: `sm`/`md`/`lg` render 16/20/22px (were
+  16/16/18px).
+
+### 8. Focus rings (DMNC-1436)
+
+**What changed.** Keyboard focus is now a visible amber ring. `Button`'s ring
+was cancelled under Tailwind v4 and shows again. `Input`, `Select` and the
+Accordion header (`Section`) draw a 2px amber outline at 2px offset on
+`:focus-visible`. Their focus border used to be invisible under amber-mono.
+The Accordion header's flush box-shadow ring is replaced by that outline. The
+CmdPalette input gets the same 2px outline. Under amber-mono the focus colour
+(`--color-semantic-border-focus`) is now amber `#FFB000` (was amber-bright).
+
+**Find it.** Look for focus styles you added to fill the gap; they may now
+double up:
+
+```bash
+rg -n -B2 -A4 'focus' --glob '*.{css,scss}' src app styles | rg 'eidotter-'
+rg -n 'focus-visible:(outline|ring)' src app components | rg '<(Button|Input|Select|Section)\b'
+```
+
+**What to do.** Delete your own focus outlines and rings on eidotter Button,
+Input, Select and Accordion. Keep focus styles on your own elements.
+
+**Verify.** Tab through a page: each eidotter control shows exactly one amber
+ring.
+
+### 9. Renamed variants
+
+None at runtime. 0.41.0 corrects variant keys in the component registry
+metadata used by eidotter's own tooling (DMNC-1459). No component prop or
+variant value changed; Badge, Tag, Alert and Button props are as in 0.40.
+
+---
+
+## Adopt the new pieces
+
+Replace hand-rolled patterns with these. They are optional, but they are the
+point of the release: one shared chrome instead of a slightly different copy
+in every site.
+
+All imports below use the barrel (`'eidotter'`), which is right for client
+code. For Next.js server components, see "RSC deep imports" at the end of this
+section.
+
+### IconButton: every close, prev/next, remove icon control
+
+An icon-only React Aria button: a 1px outlined square with an `Icon` glyph,
+amber fill on hover, a 2px brand outline on focus, half opacity when disabled.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `icon` | `IconName` | required | e.g. `'Close'`, `'Chevron Left'`, `'Chevron Right'`, `'Add'`, `'Check'` |
+| `label` | `string` | required | becomes the `aria-label` |
+| `size` | `'md' \| 'window'` | `'md'` | md is 36×36 with a 20px glyph; window is 28×28 with a 16px glyph for dense chrome |
+| `variant` | `'outline' \| 'bare'` | `'outline'` | bare has no resting outline |
+| `isDisabled`, `onPress`, `excludeFromTabOrder`, `className` | | | `onPress` receives a React Aria `PressEvent` |
+
+Available icon names: `Info`, `Warning`, `Error`, `Done`, `Check`, `Close`,
+`Chevron Up`, `Chevron Down`, `Chevron Left`, `Chevron Right`, `App`,
+`Cancel` (a minus glyph, for minimize), `Fullscreen`, `Add`.
+
+```bash
+rg -n '(aria-label=.(close|dismiss|previous|next|remove)|>\s*(×|✕|x|\[x\]|◀|▶|‹|›)\s*<)' -i src app components
+```
+
+```tsx
+// before: a hand-rolled close button
+<button className="close-btn" aria-label="Close" onClick={onClose}>×</button>
+// after
+import { IconButton } from 'eidotter';
+<IconButton icon="Close" label="Close" onPress={onClose} />
+<IconButton icon="Chevron Left" label="Previous image" onPress={prev} isDisabled={index === 0} />
+```
+
+IconButton is a client component (it carries `'use client'` in the deep-import
+build).
+
+### DosDialog: custom modal and overlay shells
+
+Use `Modal` for an ordinary titled dialog (`isOpen`, `onOpenChange` /
+`onClose`, `title`, `footer`, `size`, `isDismissable`). Use `DosDialog` when
+you are building your own overlay shell, such as a settings sheet, a
+search-results overlay, or a confirm dialog with custom chrome. React Aria
+provides the focus trap, scroll lock, Escape and backdrop dismissal.
+
+Props: `open` (required), `onOpenChange`, `placement` (`'center'` default |
+`'top'`), `size` (`'sm'` 24rem, `'md'` 30rem default, `'lg'` 40rem, `'full'`),
+`head` (`{ title, end?, marker?, decorative? }` or any ReactNode), `footer`,
+`isDismissable` (default `true`), `aria-label` / `aria-labelledby`,
+`className`. A non-decorative `head.title` renders as the `<h2>` and names the
+dialog. Otherwise pass `aria-label`; in development an unnamed open dialog logs
+a warning.
+
+```bash
+rg -n 'createPortal|role="dialog"|aria-modal|fixed inset-0' src app components
+```
+
+```tsx
+import { useState } from 'react';
+import { DosDialog, IconButton, Button } from 'eidotter';
+
+function SettingsDialog() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onPress={() => setOpen(true)}>Settings</Button>
+      <DosDialog
+        open={open}
+        onOpenChange={setOpen}
+        size="sm"
+        head={{
+          title: 'SETTINGS',
+          end: <IconButton icon="Close" label="Close settings" onPress={() => setOpen(false)} />,
+        }}
+        footer={<Button onPress={() => setOpen(false)}>Done</Button>}
+      >
+        {/* your content */}
+      </DosDialog>
+    </>
+  );
+}
+```
+
+DosDialog does not add a close button for you; pass one in `head.end` as
+above. DosDialog is a client component.
+
+### DosWindow: in-page window chrome
+
+The same title strip as DosDialog on a brand border with `--shadow-drop`, but
+in page flow, with no glow and no backdrop. Card and DosFigure are built on it.
+Use it for panels you currently frame by hand with a border and a title bar.
+
+Props: `title`, `marker` (default `true`, the `▸`), `active` (default `true`;
+inactive dims the title), `controls` (IconButtons for the strip's end),
+`footer`, `className`, plus any `<div>` attribute. With neither `title` nor
+`controls` there is no strip. The strip title is a `<span>`, not a heading;
+pass your own heading element as `title` if the window belongs in the document
+outline.
+
+```tsx
+import { DosWindow, IconButton } from 'eidotter';
+
+<DosWindow
+  title="SYSTEM.LOG"
+  controls={<IconButton icon="Close" label="Hide log" onPress={hideLog} />}
+  footer="3 entries"
+>
+  <ul>…</ul>
+</DosWindow>
+```
+
+DosWindow is server-safe: no hooks, no `'use client'`. In a Next.js server
+component you can render it directly from `eidotter/components/DosWindow`. Put
+any `controls` with `onPress` handlers in a client component, because a server
+component cannot pass functions.
+
+### CmdPalette: mount once, in the root layout
+
+Mount one `<CmdPalette>` per site in the root layout, so ⌘K / Ctrl+K works on
+every page. The default `hotkey` is `'mod+k'`; pass `hotkey={false}` to open it
+yourself. `items` should list only that site's public routes. The palette
+requests close on Escape, backdrop click and item selection through
+`onOpenChange`.
+
+```tsx
+// components/SiteCmdPalette.tsx (Next.js App Router)
+'use client';
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { CmdPalette, type CmdPaletteItem } from 'eidotter';
+
+const routes = [
+  { path: '/', label: 'HOME' },
+  { path: '/about', label: 'ABOUT' },
+];
+
+export function SiteCmdPalette() {
+  const [open, setOpen] = useState(false);
+  const router = useRouter();
+  const items: CmdPaletteItem[] = routes.map((r) => ({
+    id: r.path,
+    label: r.label,
+    onSelect: () => router.push(r.path),
+  }));
+  return <CmdPalette open={open} onOpenChange={setOpen} items={items} />;
+}
+```
+
+```tsx
+// app/layout.tsx
+import { SiteCmdPalette } from '@/components/SiteCmdPalette';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <SiteCmdPalette />
+      </body>
+    </html>
+  );
+}
+```
+
+- Astro: put the same component (with `onSelect: () => { window.location.href = r.path; }`)
+  in the base layout as `<SiteCmdPalette client:load />`.
+- Vite with react-router: render it once next to `<Routes>` and navigate with
+  `useNavigate()`.
+- Show a ⌘K hint (in the site `Footer` or the Header `end` slot) only where
+  the palette is mounted. Not in `footerHint`, which renders only inside the
+  open palette.
+
+### `eidotter/favicon.svg`
+
+The logomark favicon ships in the package (regenerated in 0.41.0 from the new
+Logo drawing). It is an SVG only. Copy it into your app at build time instead of
+committing a copy that goes stale:
+
+```json
+// package.json (any framework); for Next.js App Router change the target to app/icon.svg
+{
+  "scripts": {
+    "copy-favicon": "node -e \"require('fs').copyFileSync(require.resolve('eidotter/favicon.svg'), 'public/favicon.svg')\"",
+    "predev": "npm run copy-favicon",
+    "prebuild": "npm run copy-favicon"
+  }
+}
+```
+
+- **Next.js App Router:** copy to `app/icon.svg`. Next generates the
+  `<link rel="icon">` itself. Remove any old `app/favicon.ico` or `app/icon.*`
+  you no longer want.
+- **Vite:** copy to `public/favicon.svg`, then in `index.html`:
+  `<link rel="icon" type="image/svg+xml" href="/favicon.svg" />`.
+- **Astro:** copy to `public/favicon.svg`, then in the base layout `<head>`:
+  `<link rel="icon" type="image/svg+xml" href="/favicon.svg" />`.
+
+Add the copied path to `.gitignore` if you generate it on every build.
+
+### `amber-paper` theme and a theme toggle
+
+A third theme next to the dark default and `light`: reverse video, with an
+amber ground and near-black ink. Functional colour stays monochrome and there
+is no phosphor glow. Themes are opt-in CSS plus an attribute (or class) on an
+ancestor, usually `<html>`:
+
+```ts
+import 'eidotter/styles';
+import 'eidotter/themes/light.css';
+import 'eidotter/themes/amber-paper.css';
+```
+
+```html
+<html data-theme="amber-paper">   <!-- or class="theme-amber-paper" -->
+```
+
+No attribute means the dark default. `data-theme="light"` is the light theme
+(`eidotter/themes/light.css`). `data-theme="amber-mono"` is already in
+`eidotter/styles`. The house convention is the amber/dark default, with other
+themes offered through a toggle. A minimal toggle for the Header `end` slot:
+
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { Button } from 'eidotter';
+
+const THEMES = ['default', 'light', 'amber-paper'] as const;
+type Theme = (typeof THEMES)[number];
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useState<Theme>('default');
+  useEffect(() => {
+    try {
+      const saved = localStorage.getItem('theme') as Theme | null;
+      if (saved && THEMES.includes(saved)) setTheme(saved);
+    } catch {}
+  }, []);
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === 'default') delete root.dataset.theme;
+    else root.dataset.theme = theme;
+    try { localStorage.setItem('theme', theme); } catch {}
+  }, [theme]);
+  const next = THEMES[(THEMES.indexOf(theme) + 1) % THEMES.length];
+  return (
+    <Button variant="secondary" size="sm" onPress={() => setTheme(next)}>
+      THEME: {theme.toUpperCase()}
+    </Button>
+  );
+}
+```
+
+On server-rendered sites, set the attribute before first paint so a saved
+theme does not flash. A tiny inline script in `<head>` does it:
+`<script>try{var t=localStorage.getItem('theme');if(t&&t!=='default')document.documentElement.dataset.theme=t}catch(e){}</script>`.
+In React, put `suppressHydrationWarning` on `<html>`.
+
+Check your own CSS under amber-paper. Anything hard-coded to "dark background,
+light text" breaks there; paint with `var(--color-semantic-*)` roles.
+
+### Mark in the header
+
+`<Header brand="mark" brandName="MY SITE" … />` shows the breathing Mark
+(28px) instead of the static Logo. Use one or the other across a site.
+Standalone: `import { Mark } from 'eidotter'`; `<Mark size={48} />`. Pass
+`label=""` when it is decorative, and `morph={false}` for a still mark.
+
+### RSC deep imports (Next.js server components)
+
+The `eidotter` barrel is client-only. Importing it from a server component
+fails. In server components, deep-import per component:
+
+```tsx
+import { DosWindow } from 'eidotter/components/DosWindow';   // server-safe
+import { Header } from 'eidotter/components/Header';         // server-safe (its interactive bits are client leaves)
+import { IconButton } from 'eidotter/components/IconButton'; // client reference
+import { DosDialog } from 'eidotter/components/DosDialog';   // client reference
+import { Logo, Mark } from 'eidotter/components/Brand';
+```
+
+Interactive components resolve as client references, so they render, but you
+cannot pass them function props such as `onPress` from a server component;
+wrap those in your own `'use client'` component. CSS still comes from one
+`import 'eidotter/styles'` in the root layout.
+
+---
+
+## Upgrade checklist
+
+Work top to bottom. Each step points at the section above that explains it.
+
+- [ ] Read every guide in `node_modules/eidotter/migrations/` between your old
+      version and 0.41.0, oldest first (see `README.md` in that folder).
+- [ ] `cp node_modules/eidotter/dist/eidotter.css /tmp/eidotter-old.css` (before the bump).
+- [ ] `npm install eidotter@^0.41.0`, then `npm ls eidotter` shows 0.41.x. Commit the lockfile.
+- [ ] No-Tailwind apps: run the class diff from section 2 and fix every real hit.
+- [ ] No-preflight apps: set `html` font, colours and `a` colour yourself (section 4).
+- [ ] Preset apps: review `text-xs` / `text-sm` hits; delete redundant 16px overrides (section 1).
+- [ ] Replace `text-secondary` used on amber or light fills with `text-on-accent` (section 3).
+- [ ] Header: choose `brand` (`lockup` default, `mark`, or `text`), move hand-placed header controls into `end`, consider `skipLinkTarget` (section 5).
+- [ ] Delete or retarget CSS on removed classes (Modal, Lightbox, CmdPalette, Card, DosFigure, Mark) and on the old close and nav buttons (section 6).
+- [ ] Delete overrides fighting the new Card, DosFigure, Alert, Notification, Logo and Mark looks, and references to retired keyframe names (section 7).
+- [ ] Delete your own focus rings on eidotter Button, Input, Select and Accordion (section 8).
+- [ ] Update tests that query `[x]`, `◀`, `▶`, the old classes or the old plain-text brand.
+- [ ] Optional adoption: IconButton for icon controls, DosDialog / DosWindow for hand-rolled shells, one CmdPalette in the root layout, the favicon copy script, an amber-paper option in the theme toggle.
+- [ ] Next.js: server components import from `eidotter/components/<Name>`, not the barrel.
+- [ ] Run the app's lint, typecheck, tests and production build.
+- [ ] Visual check at **390px** and **1280px** wide, on every page template: header (brand, nav, `end`, MENU), body text size and font, link colours, cards and figures, every dialog (open, Escape, backdrop click, focus return), alerts and notifications, keyboard focus rings, and every theme you offer. Verify colours with `getComputedStyle` rather than screenshots.
+- [ ] Open the PR with before/after screenshots at both widths. **A human must
+      sign off on the visuals before merge.** Tests passing is not sufficient
+      for this release.
+
+---
+
+## Jumping from older versions
+
+If your range was below `^0.40`, these also land when you bump. Each one is
+additive or automatic unless noted. Details are in the eidotter
+[CHANGELOG](https://github.com/CinimoDY/eiDotter/blob/main/CHANGELOG.md). It is
+not shipped in the npm package; read it on GitHub.
+
+- **0.38.0:** `article` entry kind for `TimelineContainer` (thumbnail strip and
+  summary when collapsed; gallery, body and read-more when expanded). Additive.
+- **0.38.0:** `RetroEffects` `boot` no longer flashes content before the
+  turn-on; the cover now ships in the server HTML.
+- **0.38.1:** fonts are no longer inlined into `dist/eidotter.css` (5.7MB down
+  to about 150KB). Your bundler must resolve the packaged font `url()`s; this
+  works out of the box in Vite, Astro and Next.js.
+- **0.39.0:** connector-system navigation: `Header` `context` row, `Mark`,
+  `Connector`, `TimelineFeed`, `TimelinePage`. Additive.
+- **0.39.0:** nav link hrefs (`Breadcrumb`, `Nav`, `Footer`, `Header brandHref`)
+  are sanitised; `javascript:` and similar render as plain text. `isSafeHref`
+  is exported.
+- **0.40.0:** health and metabolism family: `Gauge`, `Meter`/`MeterGroup`,
+  `RangeBar`, `SeriesBars`, `DecayStrip`, `VitalsStrip`, plus `Stat`
+  `unit`/`note`/`target`. Additive, with no medical defaults.
+- **0.40.0:** `InlineExpand` expands inline (marker-pen highlight, trailing
+  `[-]`). This is a visible redesign; recheck pages that use it.
+- **0.40.1:** every prompt cursor (CommandPrompt, ChatInput, streaming
+  ChatMessage, Terminal) is the DOS underscore `_`, not a `█` block. Visible.
+- **0.40.2:** `eidotter/favicon.svg` export (see "Adopt").
+
+- **0.38.0 entry:** two-tier typography. Display text stays Perfect DOS VGA
+  437 and body text (`.dos-body`, `font-dos-body`) is JetBrains Mono Nerd Font.
+
+Coming from 0.37 or older: also read the CHANGELOG entries for 0.33–0.37,
+including the RSC deep imports `eidotter/components/<Name>` (0.37.1, DMNC-1130).