basalt-ui 1.19.1 → 1.21.0

package/src/theme/density-relations.test.ts

@@ -266,17 +266,20 @@ describe("Fix 7 — the knob's resolution is honest at every notch", () => {
     expect(minRatio).toBeLessThan(0.7)
   })
 
-  test('frozen-vs-baseline ceiling: fewer than 25 of the ~108 values equal their level-0 value at any non-zero level', () => {
-    // Measured under the 0.1/±3 law: worst case is 22 (at level ±1) — down from 43 under the old
-    // 0.06/±5 law. The ceiling of 25 leaves margin while still catching a future step reduction
-    // that reintroduces that dead zone.
+  test('frozen-vs-baseline ceiling: fewer than 27 of the ~129 values equal their level-0 value at any non-zero level', () => {
+    // Measured under the 0.1/±3 law: worst case is 25 (at level −1) — down from 43 under the old
+    // 0.06/±5 law. It is 25 rather than 24 because `mobileNavTabInsetY` (base 2) joined the set:
+    // a base that small rounds back to itself at ±1 and ±2 under any multiplier this law can
+    // produce, exactly as `mobileNavTabGap` (base 3) already did. That is the rounding law, not a
+    // resolution regression — the ceiling of 27 keeps the same margin over the measured worst case
+    // while still catching a future step reduction that reintroduces the real dead zone.
     const baseline = flattenSpacing(0)
     const keys = Object.keys(baseline)
     for (const level of ALL_LEVELS) {
       if (level === 0) continue
       const values = flattenSpacing(level)
       const frozen = keys.filter((k) => values[k] === baseline[k]).length
-      expect(frozen).toBeLessThan(25)
+      expect(frozen).toBeLessThan(27)
     }
   })
 

package/src/theme/spacing.test.ts

@@ -357,6 +357,8 @@ const SPACE_STEP_SWEEP: ReadonlyArray<
   // `app-mobile-nav.tsx` hands `mobileNavMenuWidth` to `<Menu width={…}>`.
   ['mobileNavBarHeight', 56, null],
   ['mobileNavIconSize', 24, 'space-mobile-nav-icon-size'],
+  ['mobileNavTabInsetY', 2, 'space-mobile-nav-tab-inset-y'],
+  ['mobileNavTabInsetX', 12, 'space-mobile-nav-tab-inset-x'],
   ['mobileNavRowHeight', 44, 'space-mobile-nav-row-height'],
   ['mobileNavMenuWidth', 232, null],
   ['agentRailInsetX', 10, 'space-agent-rail-inset-x'],

package/src/theme-toggle/index.tsx

@@ -84,7 +84,7 @@ function SchemeGlyph({ dark, reduceMotion }: { dark: boolean; reduceMotion: bool
       {dark ? (
         <motion.span
           key="moon"
-          style={{ display: 'inline-flex' }} // theme-allow: framer-motion element — inline-flex glyph wrapper, not a Mantine node
+          style={{ display: 'inline-flex' }} // theme-allow inline-display — a framer-motion glyph wrapper, not a Mantine layout node
           initial={{ opacity: 0, scale: 0.6, rotate: 30 }}
           animate={{ opacity: 1, scale: 1, rotate: 0 }}
           exit={{ opacity: 0, scale: 0.6, rotate: -30 }}
@@ -95,7 +95,7 @@ function SchemeGlyph({ dark, reduceMotion }: { dark: boolean; reduceMotion: bool
       ) : (
         <motion.span
           key="sun"
-          style={{ display: 'inline-flex' }} // theme-allow: framer-motion element — inline-flex glyph wrapper, not a Mantine node
+          style={{ display: 'inline-flex' }} // theme-allow inline-display — a framer-motion glyph wrapper, not a Mantine layout node
           initial={{ opacity: 0, scale: 0.6, rotate: -30 }}
           animate={{ opacity: 1, scale: 1, rotate: 0 }}
           exit={{ opacity: 0, scale: 0.6, rotate: 30 }}

package/src/tokens/index.ts

@@ -89,8 +89,30 @@ export const alpha = (token: string, a: number): string =>
  * `theme/index.ts`), so the component surface scales with the user's browser font-size AND with
  * `--mantine-scale`. `md` is the body step; `lg` is pinned at exactly 16px because it doubles as
  * the iOS input floor (see the `styles.css` floor — Safari zooms the viewport on focus below 16px).
+ *
+ * ## Adding a rung
+ *
+ * The ladder is hand-tuned per ROLE, not generated — but it is not arbitrary either, and the
+ * constraint is what keeps a "just add the size I need" request from dissolving it. Every adjacent
+ * pair sits between **1.06× and 1.17×**, so a new rung must too:
+ *
+ *  • Below the range, two rungs are visually the same size and the ladder stops being a choice —
+ *    the guard would then report a size for which two tokens are equally "right".
+ *  • Above it, the jump reads as a different type system rather than the next step of this one.
+ *
+ * That test is what admitted `nano` (11/10 = 1.10) and `display` (30/26 = 1.154, the second-widest
+ * step, which is the shape a display tier is supposed to have), and what rejected a 20px rung
+ * between `xl` (18) and `h2` (21): 21/20 = 1.05 is below the floor, and `h2` is already 1px away
+ * from any 20px site. A size the ladder declines to grow a rung for is a size that should snap to
+ * its nearest step — not a `theme-allow`.
+ *
+ * A rung is also a ROLE, not just a number. `nano` and `display` are both deliberately named for
+ * where they belong (a label engraved inside a drawn object; a numeral read from across a room)
+ * rather than for a position, because the failure mode of a bare `xxs`/`xxl` is that it becomes the
+ * escape hatch for every size the ladder was meant to prevent.
  */
 const TEXT = {
+  nano: 10, // engraved/graphic label INSIDE a drawn object (a plate face, a dial, a chip) — never UI copy or prose
   micro: 11, // mono uppercase micro-label (table th, Menu.Label, sidebar/section headers, axis ticks)
   xs: 12.5, // delta badges, tooltip meta, dense chrome, StatCard labels
   sm: 13.5, // table/stat numerals, chart tooltip, legend
@@ -100,6 +122,7 @@ const TEXT = {
   h2: 21, // article-density Prose h2 (docs/CONTENT-SPEC.md §5)
   kpi: 24, // the StatCard hero numeral (density pass: 31 → 24, tighter/less shouty)
   h1: 26, // article-density Prose h1 (docs/CONTENT-SPEC.md §5)
+  display: 30, // a numeral read at arm's length (a keypad readout, a timer, a kiosk figure) — not a heading
 } as const
 
 export const VX = {
@@ -533,6 +556,8 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-app-header-mobile-actions-height', `${space.step.appHeaderMobileActionsHeight}px`),
     decl('space-mobile-nav-tab-gap', `${space.step.mobileNavTabGap}px`),
     decl('space-mobile-nav-icon-size', `${space.step.mobileNavIconSize}px`),
+    decl('space-mobile-nav-tab-inset-y', `${space.step.mobileNavTabInsetY}px`),
+    decl('space-mobile-nav-tab-inset-x', `${space.step.mobileNavTabInsetX}px`),
     decl('space-mobile-nav-row-height', `${space.step.mobileNavRowHeight}px`),
     decl('space-agent-rail-inset-x', `${space.step.agentRailInsetX}px`),
     decl('space-agent-part-gap-top', `${space.step.agentPartGapTop}px`),
@@ -758,13 +783,13 @@ export type BuildPaletteOpts = {
    */
   mediaFallback?: boolean
   /**
-   * How much of the SPACING set to emit. Default: `'all'` (every one of the 104 `--vx-space-*`
+   * How much of the SPACING set to emit. Default: `'all'` (every one of the 108 `--vx-space-*`
    * declarations the framework's own components read).
    *
    * `'core'` keeps the 9 generic anchors — the stack rhythm, the two control heights, the row
-   * insets — and drops the 95 named for a specific basalt component
+   * insets — and drops the 99 named for a specific basalt component
    * (`--vx-space-agent-transcript-inset`, `--vx-space-toc-sub-indent`, …), taking the emitted set
-   * from 197 variables to 102. Nothing outside basalt's own React components reads those, so a
+   * from 204 variables to 105. Nothing outside basalt's own React components reads those, so a
    * framework-free consumer is carrying them for nothing.
    *
    * This is a SPACING filter only: color, radius, shadow, type and status variables are identical

package/src/tokens/palette.ts

@@ -97,12 +97,12 @@ export const p = (fam: readonly string[], light = 2, dark = 3): ColorPair => ({
  */
 export const SHADOW = {
   card: {
-    light: '0 1px 2px rgba(28,25,23,0.05), 0 0 0 1px var(--vx-surface-hairline)',
-    dark: '0 1px 3px rgba(0,0,0,0.4), inset 0 0 0 1px color-mix(in srgb, #ffffff 4%, transparent)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.05), 0 0 0 1px var(--vx-surface-hairline)',
+    dark: '0 1px 3px rgba(0, 0, 0, 0.4), inset 0 0 0 1px color-mix(in srgb, #ffffff 4%, transparent)',
   },
   ctrl: {
-    light: '0 1px 2px rgba(28,25,23,0.12)',
-    dark: '0 1px 2px rgba(0,0,0,0.35)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.12)',
+    dark: '0 1px 2px rgba(0, 0, 0, 0.35)',
   },
   /**
    * Interactive-control depth — the ONE value every raised Button/ActionIcon/Input variant shares
@@ -132,16 +132,16 @@ export const SHADOW = {
    * ever needs more, raise the DROP. Do not reintroduce an edge; both shapes have been tried.
    */
   raised: {
-    light: '0 1px 2px rgba(28,25,23,0.10)',
-    dark: '0 1px 2px rgba(0,0,0,0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.1)',
+    dark: '0 1px 2px rgba(0, 0, 0, 0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)',
   },
   // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a REAL drop shadow, a
   // step above `card`, so detached surfaces read as lifted off the page (`docs/DESIGN-SPEC.md` §5).
   // Unlike `card`, no embedded ring: floating surfaces carry a real 1px `--vx-surface-border` so
   // Mantine's rotated-square arrow inherits a proper edge.
   overlay: {
-    light: '0 8px 24px rgba(28,25,23,0.10)',
-    dark: '0 8px 24px rgba(0,0,0,0.5)',
+    light: '0 8px 24px rgba(28, 25, 23, 0.1)',
+    dark: '0 8px 24px rgba(0, 0, 0, 0.5)',
   },
 } as const
 
@@ -613,8 +613,14 @@ const SPACE_STEP_BASE = {
    *  `env(safe-area-inset-bottom)` to it. JS-consumed (AppShell `footer.height`), no `--vx-*` var,
    *  same shape as `appShellHeaderHeight`. Floored at 48px in `deriveSpacing`. */
   mobileNavBarHeight: 56,
-  /** Slot icon box. */
+  /** Slot icon box. Also the MIN box of the icon slot itself, so the active pill keeps its shape
+   *  when a destination ships no icon (an icon-less consumer is a supported configuration). */
   mobileNavIconSize: 24,
+  /** Active-pill inset around the slot icon, vertical. Sub-scale on its own, but it is one half of
+   *  a pair with `mobileNavTabInsetX` — a step keeps the pill's shape tracking density. */
+  mobileNavTabInsetY: 2,
+  /** Active-pill inset around the slot icon, horizontal. */
+  mobileNavTabInsetX: 12,
   /** Menu/sheet row height. Floored at 44px in `deriveSpacing` (Apple HIG 44pt / WCAG 2.5.5 AAA). */
   mobileNavRowHeight: 44,
   /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
@@ -1059,22 +1065,22 @@ function buildPaletteDataUncached(config: DeriveConfig) {
   const NEUTRAL = {
     line: { light: BP.gray[0], dark: BP.gray[4] }, // primary line
     line2: { light: BP.gray[1], dark: BP.gray[2] }, // secondary line
-    axis: { light: inkRgba(inkLight, 0.6), dark: 'rgba(255,255,255,0.6)' },
-    axisStroke: { light: inkRgba(inkLight, 0.12), dark: 'rgba(255,255,255,0.12)' },
-    grid: { light: inkRgba(inkLight, 0.07), dark: 'rgba(255,255,255,0.06)' },
-    crosshair: { light: inkRgba(inkLight, 0.32), dark: 'rgba(255,255,255,0.42)' },
+    axis: { light: inkRgba(inkLight, 0.6), dark: 'rgba(255, 255, 255, 0.6)' },
+    axisStroke: { light: inkRgba(inkLight, 0.12), dark: 'rgba(255, 255, 255, 0.12)' },
+    grid: { light: inkRgba(inkLight, 0.07), dark: 'rgba(255, 255, 255, 0.06)' },
+    crosshair: { light: inkRgba(inkLight, 0.32), dark: 'rgba(255, 255, 255, 0.42)' },
     dotStroke: { light: BP.white, dark: BP.darkGray[1] }, // matches chart-area bg
-    tooltipBg: { light: BP.white, dark: 'rgba(39,39,42,0.96)' },
-    tooltipText: { light: inkRgba(inkLight, 0.88), dark: 'rgba(255,255,255,0.88)' },
-    tooltipMuted: { light: inkRgba(inkLight, 0.5), dark: 'rgba(255,255,255,0.5)' },
+    tooltipBg: { light: BP.white, dark: 'rgba(39, 39, 42, 0.96)' },
+    tooltipText: { light: inkRgba(inkLight, 0.88), dark: 'rgba(255, 255, 255, 0.88)' },
+    tooltipMuted: { light: inkRgba(inkLight, 0.5), dark: 'rgba(255, 255, 255, 0.5)' },
     tooltipBorder: { light: `1px solid ${BP.lightGray[1]}`, dark: 'none' },
     tooltipShadow: {
       light: `0 2px 8px ${inkRgba(inkLight, 0.1)}`,
-      dark: '0 2px 8px rgba(0,0,0,0.35)',
+      dark: '0 2px 8px rgba(0, 0, 0, 0.35)',
     },
     // Chart legend text — same DERIVED-ink treatment as axis/grid/tooltip* above (light keys off
     // `inkLight`; dark stays flat white like every other neutral chart-chrome pair here).
-    legendText: { light: inkRgba(inkLight, 0.82), dark: 'rgba(255,255,255,0.92)' },
+    legendText: { light: inkRgba(inkLight, 0.82), dark: 'rgba(255, 255, 255, 0.92)' },
     // Base neutral for hairlines / muted / DIMMED text / overlays — apply opacity via alpha().
     // Binds to --mantine-color-dimmed, so it is THE dimmed-text lever. Equal to `INK.muted` (the
     // spec's "muted (secondary text)" row) — kept as its own pair for the pre-existing `--vx-neutral`

package/src/tokens/text-scale.test.ts

@@ -0,0 +1,51 @@
+/**
+ * The type ladder's own law — the thing that decides whether a requested size gets a rung.
+ *
+ * This exists because the ladder is hand-tuned rather than generated, which is exactly the shape
+ * that erodes: a consumer reports "no step for 20px", someone adds 20, and now 20 and 21 are the
+ * same size and the guard reports a violation with two equally-correct remedies. Pinning the ratio
+ * band makes the next request answerable with arithmetic instead of taste.
+ */
+import { describe, expect, it } from 'bun:test'
+import { VX } from './index'
+
+/** Every adjacent pair of the shipped ladder, ascending. */
+const STEPS = Object.values(VX.text)
+const RATIOS = STEPS.slice(1).map((size, index) => size / STEPS[index]!)
+
+/** The band documented on `TEXT` in `tokens/index.ts`. Widen it only with a reason written there. */
+const MIN_RATIO = 1.06
+const MAX_RATIO = 1.17
+
+describe('the type ladder', () => {
+  it('is strictly ascending, so `Object.values` order IS the ladder order', () => {
+    expect(STEPS).toEqual(STEPS.toSorted((a, b) => a - b))
+    expect(new Set(STEPS).size).toBe(STEPS.length)
+  })
+
+  it('keeps every adjacent step inside the 1.06–1.17 band', () => {
+    const offenders = RATIOS.map((ratio, index) => ({
+      pair: `${STEPS[index]} → ${STEPS[index + 1]}`,
+      ratio: Number(ratio.toFixed(3)),
+    })).filter(({ ratio }) => ratio < MIN_RATIO || ratio > MAX_RATIO)
+
+    expect(offenders).toEqual([])
+  })
+
+  it('spans the two ends consumers reported as unreachable', () => {
+    // A label engraved inside a drawn object, and a numeral read at arm's length. Both arrived from
+    // the same consumer round; both are roles the ladder genuinely had no step for.
+    expect(VX.text.nano).toBe(10)
+    expect(VX.text.display).toBe(30)
+  })
+
+  it('has no rung between xl and h2 — 21/20 = 1.05 is below the band', () => {
+    // The third site from that report. `h2` is the remedy, not a waiver: it is 1px away.
+    expect(STEPS.filter((size) => size > VX.text.xl && size < VX.text.h2)).toEqual([])
+    expect(VX.text.h2 / 20).toBeLessThan(MIN_RATIO)
+  })
+
+  it('pins the iOS input floor, which is a rung with an external constraint', () => {
+    expect(VX.text.lg).toBe(16)
+  })
+})

package/src/vite-color-mix.ts

@@ -28,8 +28,8 @@
  * what a color parser must never do.
  */
 const NAMED_COLORS: Record<string, string> = {
-  white: '#ffffff', // theme-allow — CSS keyword definition, not a design color
-  black: '#000000', // theme-allow — CSS keyword definition, not a design color
+  white: '#ffffff', // theme-allow raw-hex — the CSS keyword's definition, not a design color
+  black: '#000000', // theme-allow raw-hex — the CSS keyword's definition, not a design color
 }
 
 function normalizeHex(hex: string): string {

package/src/vite.test.ts

@@ -17,13 +17,20 @@ function resolveConfig(plugin: Plugin, base: string): void {
   configResolved({ base } as unknown as ResolvedConfig)
 }
 
+type HtmlTransformResult = { html: string; tags: HtmlTagDescriptor[] }
+
+/** Invokes the plugin's `transformIndexHtml` hook (object form, `order: 'pre'`). */
+function transform(plugin: Plugin, html: string): HtmlTransformResult {
+  const hook = plugin.transformIndexHtml as unknown as {
+    order: 'pre'
+    handler: (html: string) => HtmlTransformResult
+  }
+  return hook.handler(html)
+}
+
 /** Invokes the plugin's `transformIndexHtml` hook and returns the emitted tags. */
 function transformHtml(plugin: Plugin, html: string): HtmlTagDescriptor[] {
-  const transformIndexHtml = plugin.transformIndexHtml as unknown as (html: string) => {
-    html: string
-    tags: HtmlTagDescriptor[]
-  }
-  return transformIndexHtml(html).tags
+  return transform(plugin, html).tags
 }
 
 type FakeReq = { url: string }
@@ -63,6 +70,7 @@ describe('basaltAppPlugin — base handling', () => {
     const tags = transformHtml(plugin, HTML_NO_VIEWPORT)
 
     expect(tags).toEqual([
+      { tag: 'meta', attrs: { charset: 'UTF-8' } },
       {
         tag: 'meta',
         attrs: {
@@ -78,7 +86,11 @@ describe('basaltAppPlugin — base handling', () => {
         tag: 'meta',
         attrs: { name: 'theme-color', media: '(prefers-color-scheme: dark)', content: '#111111' },
       },
-      { tag: 'style', children: 'html{background-color:#111111;color-scheme:dark}' },
+      {
+        tag: 'style',
+        children:
+          'html:not([data-mantine-color-scheme]){background-color:#111111;color-scheme:dark}',
+      },
       { tag: 'link', attrs: { rel: 'shortcut icon', href: '/favicon.ico' } },
       { tag: 'link', attrs: { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' } },
       { tag: 'link', attrs: { rel: 'icon', sizes: '96x96', href: '/favicon-96x96.png' } },
@@ -190,3 +202,110 @@ describe('basaltAppPlugin — base handling', () => {
     )
   })
 })
+
+describe('basaltAppPlugin — the anti-FOUC boot rule (V1)', () => {
+  const bootStyleOf = (options: Partial<BasaltAppOptions>): string => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR, ...options })
+    resolveConfig(plugin, '/')
+    const style = transformHtml(plugin, HTML_NO_VIEWPORT).find((tag) => tag.tag === 'style')
+    return String(style?.children ?? '')
+  }
+
+  test('every mode scopes the rule so Mantine can take it back', () => {
+    // The whole defect: an UNLAYERED `html{color-scheme:dark}` outranks Mantine's own layered
+    // `:root{color-scheme:var(--mantine-color-scheme)}`, so light mode kept dark native controls
+    // forever. Scoping to the absence of the attribute Mantine writes is what expires it.
+    for (const colorScheme of ['dark', 'light', 'auto', false] as const) {
+      const css = bootStyleOf({ colorScheme })
+      expect(css).toContain('html:not([data-mantine-color-scheme])')
+      expect(css).not.toMatch(/(^|[};])html\{/)
+    }
+  })
+
+  test('default is dark — byte-identical to 1.20.0 apart from the scope', () => {
+    expect(bootStyleOf({})).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#111111;color-scheme:dark}',
+    )
+  })
+
+  test('light paints the light surface and declares color-scheme: light', () => {
+    expect(bootStyleOf({ colorScheme: 'light' })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#ffffff;color-scheme:light}',
+    )
+  })
+
+  test('auto declares `light dark` and follows prefers-color-scheme for the paint', () => {
+    expect(bootStyleOf({ colorScheme: 'auto' })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#ffffff;color-scheme:light dark}' +
+        '@media(prefers-color-scheme:dark){html:not([data-mantine-color-scheme])' +
+        '{background-color:#111111}}',
+    )
+  })
+
+  test('an explicit backgroundColor wins over the auto media pair', () => {
+    expect(bootStyleOf({ colorScheme: 'auto', backgroundColor: '#abcdef' })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#abcdef;color-scheme:light dark}',
+    )
+  })
+
+  test('colorScheme: false is the full opt-out — paint, no color-scheme at all', () => {
+    expect(bootStyleOf({ colorScheme: false })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#111111}',
+    )
+  })
+
+  test('the manifest theme_color follows the boot scheme', () => {
+    const read = (options: Partial<BasaltAppOptions>): Record<string, unknown> => {
+      const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR, ...options })
+      const body = runMiddleware(getDevMiddleware(plugin, '/'), '/site.webmanifest')
+      return JSON.parse(body ?? '{}') as Record<string, unknown>
+    }
+    expect(read({})['theme_color']).toBe('#111111')
+    expect(read({ colorScheme: 'auto' })['theme_color']).toBe('#111111')
+    expect(read({ colorScheme: 'light' })['theme_color']).toBe('#ffffff')
+    expect(read({ colorScheme: 'light' })['background_color']).toBe('#ffffff')
+  })
+})
+
+describe('basaltAppPlugin — the encoding declaration (V2)', () => {
+  const SHELL =
+    '<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n' +
+    '    <title>App</title>\n  </head>\n  <body></body>\n</html>'
+
+  test("the consumer's charset is hoisted out of the html and re-emitted first", () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    resolveConfig(plugin, '/')
+    const result = transform(plugin, SHELL)
+
+    expect(result.html).not.toContain('charset')
+    expect(result.tags[0]).toEqual({ tag: 'meta', attrs: { charset: 'utf-8' } })
+    // The hoist takes the whole line — no orphaned indentation left behind.
+    expect(result.html).toContain('<head>\n    <title>App</title>')
+  })
+
+  test('a shell that declares no encoding gets one', () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    resolveConfig(plugin, '/')
+    expect(transform(plugin, HTML_NO_VIEWPORT).tags[0]).toEqual({
+      tag: 'meta',
+      attrs: { charset: 'UTF-8' },
+    })
+  })
+
+  test('the legacy http-equiv form is left completely alone', () => {
+    const html =
+      '<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8">' +
+      '</head><body></body></html>'
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    resolveConfig(plugin, '/')
+    const result = transform(plugin, html)
+
+    expect(result.html).toBe(html)
+    expect(result.tags.some((tag) => tag.attrs?.['charset'] !== undefined)).toBe(false)
+  })
+
+  test("the hook runs `pre` so no other plugin's tags can land ahead of the charset", () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    expect((plugin.transformIndexHtml as { order?: string }).order).toBe('pre')
+  })
+})