basalt-ui 1.22.0 → 1.23.0

package/src/cli/waiver-audit.test.ts

@@ -104,11 +104,15 @@ describe('check-theme --audit-allows — theme-allow annotations', () => {
   })
 
   it('names the scope it audited, so "0 dead" is never read as "0 dead anywhere"', () => {
-    // The audit reads exactly what check-theme reads. A waiver in a file outside `basalt.roots` is
-    // invisible to it — not because it is fine, but because nothing scanned it.
+    // The audit reads exactly what check-theme reads, and that is WIDER than `basalt.roots` — two
+    // consumers reported a live `public/site.webmanifest` waiver under a scope line claiming
+    // files outside roots are not audited. The line has to name every class the scan reaches, or
+    // it is a second false statement in the sentence that exists to prevent one.
     fixture("export const c = '#ff0000' // theme-allow raw-hex — brand literal\n")
     const { log } = audit()
-    expect(log).toContain('Scope: the 1 file(s) check-theme scans under basalt.roots (src)')
+    expect(log).toContain('Scope: the 1 file(s) check-theme scans — everything under basalt.roots')
+    expect(log).toContain('sibling index.html and public/ tree')
+    expect(log).toContain('basalt.include')
   })
 
   it('marks an unaccountable waiver while still reporting what it covers', () => {

package/src/guard/check-source.test.ts

@@ -2738,59 +2738,134 @@ describe('inline-spacing — the style-object test', () => {
   })
 })
 
-// ── theme-allow comment shapes ───────────────────────────────────────────────────────────────────
+// ── theme-allow shape grid ───────────────────────────────────────────────────────────────────────
 
 /**
- * The prefix contract, pinned per comment shape.
+ * The whole shape space of an annotation, pinned cell by cell.
  *
- * Three holes have been found in this rule in three rounds — two false positives and one false
- * NEGATIVE (a docblock documenting a file's waivers disarmed the file). So every shape a consumer
- * actually writes gets a fixture, and the oxlint plugin's copy is pinned identically in
- * `configs/oxlint-plugin.test.ts`: the two halves of one contract must agree on what an annotation
- * IS, and may differ only on which rules each can judge.
+ * FIVE holes have been found in this one contract in four rounds — two false positives, one false
+ * negative, and twice the guard and the oxlint plugin disagreeing about what an annotation IS. Each
+ * was found by a consumer writing a shape nobody had thought to test, and round 6's answer (a
+ * thirteen-shape list of "every shape a consumer actually writes") missed the next three anyway,
+ * because a list of observed shapes cannot cover the ones not yet observed.
+ *
+ * So this is a GRID over the four things that actually vary, not a list of anecdotes:
+ *
+ * | axis | values |
+ * |-|-|
+ * | comment style | `//` · `/* *\/` · `/** *\/` · `{/* *\/}` · `{/** *\/}` · `<!-- -->` · JSON member |
+ * | token position | opener line · gutter line · trailing after code |
+ * | where the closer falls | the token's line · its own line · N lines below · n/a |
+ * | what follows | code · blank then code · comment then code · code on the closer's line |
+ *
+ * `configs/oxlint-plugin.test.ts` pins the same grid, under the same row names, for the subset the
+ * plugin can judge (TS/JSX — it never sees CSS, HTML or JSON). The two halves must agree on every
+ * shared cell; add a row to one and it goes in the other in the same commit.
+ *
+ * The unsupported cells are asserted too. "Unsupported" and "silently broken" read identically to a
+ * consumer, and the whole point of the grid is to make them different things.
  */
-describe('theme-allow comment shapes', () => {
-  const REASON = 'deliberate legacy value'
-  const waives = (relPath: string, src: string): boolean =>
-    checkSource(src, relPath, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex').length === 0
+/** Wraps JSX children in a component, so a `{/* … *\/}` child is legal source. */
+const jsxShape = (body: string): string =>
+  `export const C = () => (\n  <div>\n${body}\n  </div>\n)\n`
+
+/** Does the file waive its `raw-hex`? — the one question every grid row asks. */
+const shapeWaives = (relPath: string, src: string): boolean =>
+  checkSource(src, relPath, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex').length === 0
 
+describe('theme-allow shape grid', () => {
+  const REASON = 'deliberate legacy value'
+  const A = `theme-allow raw-hex — ${REASON}`
+  const AF = `theme-allow-file raw-hex — ${REASON}`
+  /** The statement the guard reports `raw-hex` on. */
+  const T = `const a = '#f00'`
+  /** The JSX child the guard reports `raw-hex` on. */
+  const JT = `<span style={{ color: '#f00' }} />`
+  const J = jsxShape
+  const waives = shapeWaives
+
+  // ── SUPPORTED — every cell of the grid that waives ────────────────────────
   it.each([
-    ['own line //', PATH, `// theme-allow raw-hex — ${REASON}\nconst a = '#f00'\n`],
+    // `//` — no closer to place.
+    ['// own line', PATH, `// ${A}\n${T}\n`],
+    ['// indented', PATH, `function f() {\n  // ${A}\n  ${T}\n}\n`],
+    ['// no space after the marker', PATH, `//${A}\n${T}\n`],
+    ['// trailing', PATH, `${T} // ${A}\n`],
+    ['// reason wrapped onto a second // comment', PATH, `// ${A},\n// continued here\n${T}\n`],
+    // `/* */` and `/** */` at statement level, closer in each of its three places.
+    ['/* */ own line', PATH, `/* ${A} */\n${T}\n`],
+    ['/* */ trailing', PATH, `${T} /* ${A} */\n`],
+    ['/** */ own line (docblock opener)', PATH, `/** ${A} */\n${T}\n`],
+    ['/* opener + token, closer on its own line', PATH, `/* ${A}\n*/\n${T}\n`],
+    ['/* gutter token, closer on the token line', PATH, `/*\n ${A} */\n${T}\n`],
+    ['/* gutter token, closer on its own line', PATH, `/*\n ${A}\n*/\n${T}\n`],
+    ['/** star gutter, closer on the token line', PATH, `/**\n * ${A} */\n${T}\n`],
+    ['/** star gutter, closer on its own line', PATH, `/**\n * ${A}\n */\n${T}\n`],
+    // Prose between the token and the closer — any amount of it.
+    ['/** token then 1 prose line', PATH, `/**\n * ${A}\n * more\n */\n${T}\n`],
+    ['/** token then 12 prose lines', PATH, `/**\n * ${A}\n${' * p\n'.repeat(12)} */\n${T}\n`],
     [
-      'indented //',
+      '/** prose first, token on a later gutter line',
       PATH,
-      `function f() {\n  // theme-allow raw-hex — ${REASON}\n  const a = '#f00'\n}\n`,
+      `/**\n * some prose\n * ${A}\n */\n${T}\n`,
     ],
-    ['trailing //', PATH, `const a = '#f00' // theme-allow raw-hex — ${REASON}\n`],
-    ['trailing block', PATH, `const a = '#f00' /* theme-allow raw-hex — ${REASON} */\n`],
+    // JSX expression containers — the family every disagreement so far has come from.
+    ['{/* */} own line', PATH, J(`    {/* ${A} */}\n    ${JT}`)],
+    ['{/* */} trailing on the target line', PATH, J(`    ${JT} {/* ${A} */}`)],
+    ['{/* opener + token, closer on its own line', PATH, J(`    {/* ${A}\n    */}\n    ${JT}`)],
+    ['{/* gutter token, closer on the token line', PATH, J(`    {/*\n      ${A} */}\n    ${JT}`)],
     [
-      'JSX expression comment',
+      '{/* gutter token, closer on its own line',
       PATH,
-      `export const C = () => (\n  <div>\n    {/* theme-allow raw-hex — ${REASON} */}\n    <span style={{ color: '#f00' }} />\n  </div>\n)\n`,
+      J(`    {/*\n      ${A}\n    */}\n    ${JT}`),
     ],
+    ['{/** star gutter, closer on the token line', PATH, J(`    {/**\n     * ${A} */}\n    ${JT}`)],
     [
-      'JSX expression comment, token on its own wrapped line',
+      '{/** star gutter, closer on its own line',
       PATH,
-      `export const C = () => (\n  <div>\n    {/*\n      theme-allow raw-hex — ${REASON} */}\n    <span style={{ color: '#f00' }} />\n  </div>\n)\n`,
+      J(`    {/**\n     * ${A}\n     */}\n    ${JT}`),
     ],
-    ['block gutter *', PATH, `/**\n * theme-allow raw-hex — ${REASON}\n */\nconst a = '#f00'\n`],
-    ['docblock opener /**', PATH, `/** theme-allow raw-hex — ${REASON} */\nconst a = '#f00'\n`],
-    ['css trailing', 'src/a.css', `a { color: #f00; /* theme-allow raw-hex — ${REASON} */ }\n`],
     [
-      'css reflowed onto continuation lines',
-      'src/a.css',
-      `a {\n  color: var(\n    --x,\n    #f00\n  ); /* theme-allow raw-hex — ${REASON} */\n}\n`,
+      '{/** token then 6 prose lines',
+      PATH,
+      J(`    {/**\n     * ${A}\n${'     * p\n'.repeat(6)}     */}\n    ${JT}`),
     ],
+    ['{/* target on the closer line', PATH, J(`    {/*\n      ${A}\n    */}${JT}`)],
+    ['{/* closer alone, tab indented', PATH, J(`\t{/*\n\t  ${A}\n\t*/}\n\t${JT}`)],
     [
-      'html comment',
-      'index.html',
-      `<!-- theme-allow raw-hex — ${REASON} -->\n<b style="color: #f00"></b>\n`,
+      '{/* closer alone, space between */ and }',
+      PATH,
+      J(`    {/*\n      ${A}\n    */ }\n    ${JT}`),
     ],
     [
-      'html trailing comment',
-      'index.html',
-      `<b style="color: #f00"></b> <!-- theme-allow raw-hex — ${REASON} -->\n`,
+      '{/* closer alone, two annotations in one block',
+      PATH,
+      J(`    {/*\n      ${A}\n      theme-allow raw-color-fn — ${REASON}\n    */}\n    ${JT}`),
+    ],
+    // A further comment between the annotation and the code is walked through; a blank line is not.
+    ['/** */ then an unrelated // note', PATH, `/** ${A} */\n// an unrelated note\n${T}\n`],
+    [
+      '{/* */} then an unrelated {/* */}',
+      PATH,
+      J(`    {/* ${A} */}\n    {/* unrelated */}\n    ${JT}`),
+    ],
+    // The file-declaration form, which is position-independent — pinned in two placements anyway,
+    // because "position-independent" is a claim the parser has to keep making.
+    [
+      'theme-allow-file, {/* closer on its own line',
+      PATH,
+      J(`    {/*\n      ${AF}\n    */}\n    ${JT}`),
+    ],
+    ['theme-allow-file, /** star gutter', PATH, `/**\n * ${AF}\n */\n${T}\n`],
+    // Dialects the plugin never sees — CSS continuation lines, HTML, and the JSON member form.
+    ['css trailing', 'src/a.css', `a { color: #f00; /* ${A} */ }\n`],
+    [
+      'css reflowed onto continuation lines',
+      'src/a.css',
+      `a {\n  color: var(\n    --x,\n    #f00\n  ); /* ${A} */\n}\n`,
     ],
+    ['html comment own line', 'index.html', `<!-- ${A} -->\n<b style="color: #f00"></b>\n`],
+    ['html trailing comment', 'index.html', `<b style="color: #f00"></b> <!-- ${A} -->\n`],
     [
       'JSON member form',
       'public/site.webmanifest',
@@ -2800,25 +2875,46 @@ describe('theme-allow comment shapes', () => {
     expect(waives(relPath as string, src as string)).toBe(true)
   })
 
-  // The false negative the prefix rule closed: a sentence that MENTIONS the token is not one.
+  // ── UNSUPPORTED — asserted, so a hole can never pass for a design decision ──
   it.each([
+    // A blank line is the separation people use for "this comment is not about the next statement".
+    ['blank line after a // annotation', PATH, `// ${A}\n\n${T}\n`],
+    ['blank line after a {/* */} annotation', PATH, J(`    {/* ${A} */}\n\n    ${JT}`)],
     [
-      'mid-sentence in a line comment',
-      `// we normally write a theme-allow raw-hex here\nconst a = '#f00'\n`,
+      'blank line after a {/* closer on its own line',
+      PATH,
+      J(`    {/*\n      ${A}\n    */}\n\n    ${JT}`),
+    ],
+    // Prose that MENTIONS the token is not an annotation — the one false NEGATIVE in the set, and
+    // the reason the token has to START its comment.
+    ['mid-sentence in a line comment', PATH, `// we normally write a ${A} here\n${T}\n`],
+    [
+      'mid-sentence in a docblock gutter',
+      PATH,
+      `/**\n * Each value is escaped with a ${A} annotation.\n */\n${T}\n`,
     ],
     [
-      'mid-sentence in a docblock',
-      `/**\n * Each value below is escaped with a theme-allow raw-hex annotation.\n */\nconst a = '#f00'\n`,
+      'mid-sentence in a JSX expression comment',
+      PATH,
+      J(`    {/* the shape here is a ${A} comment */}\n    ${JT}`),
+    ],
+    ['inside a string literal', PATH, `const doc = 'theme-allow raw-hex'\n${T}\n`],
+    // An annotation reaches the first line below its comment — not an arbitrary line further down.
+    // A multi-line opening tag therefore needs the annotation beside the attribute, not above the
+    // tag. Both halves agree, and both report rather than silently waiving the wrong node.
+    [
+      'above a multi-line opening tag',
+      PATH,
+      J(`    {/* ${A} */}\n    <span\n      style={{ color: '#f00' }}\n    />`),
     ],
-    ['inside a string literal', `const doc = 'theme-allow raw-hex'\nconst a = '#f00'\n`],
-  ])('%s does NOT waive', (_name, src) => {
-    expect(waives(PATH, src as string)).toBe(false)
+  ])('%s does NOT waive', (_name, relPath, src) => {
+    expect(waives(relPath as string, src as string)).toBe(false)
   })
 
   // The narrowness of the `*/}` exception: a `}` that is REAL code keeps its trailing
   // classification, so the annotation does not reach the statement below it.
   it('a trailing annotation on a real closing brace stays on its own line', () => {
-    const src = `function f() {\n  const a = 1\n} // theme-allow raw-hex — ${REASON}\nconst b = '#0f0'\n`
+    const src = `function f() {\n  const a = 1\n} // ${A}\nconst b = '#0f0'\n`
     expect(
       checkSource(src, PATH, DEFAULT_GUARD_CONFIG)
         .filter((f) => f.kind === 'raw-hex')
@@ -2829,7 +2925,7 @@ describe('theme-allow comment shapes', () => {
   // A trailing annotation is scoped to its OWN line — otherwise `const a = '#f00' // theme-allow`
   // would silently waive the statement below it too.
   it('a trailing annotation does not reach the line below', () => {
-    const src = `const a = '#f00' // theme-allow raw-hex — ${REASON}\nconst b = '#0f0'\n`
+    const src = `const a = '#f00' // ${A}\nconst b = '#0f0'\n`
     expect(
       checkSource(src, PATH, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex'),
     ).toHaveLength(1)

package/src/guard/index.ts

@@ -400,7 +400,7 @@ const RAW_CHART_LEGEND_ARRAY = /<ChartLegend\b[^>]*?\bitems\s*=\s*\{\s*\[/g
 // alternative so their `>` never terminates the tag early. A bare `>` comparison inside a prop
 // expression still ends the match (accepted limitation of the bounded scan).
 const CHART_ENTRY_POINT_TAG =
-  /<(?:MultiLine|Bars|Donut|DualPanel|Heatmap|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g
+  /<(?:MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g
 const HAS_ARIA_LABEL_PROP = /\bariaLabel\s*=/
 
 // Raw lowercase form-control element — line-scoped, same shape as RAW_VISX_AXIS. `\b` after the
@@ -771,8 +771,45 @@ function parseAllowAnnotation(rest: string, scope: AllowScope): AllowAnnotation
 /** How far back a trailing CSS annotation reaches for the declaration it terminates. */
 const MAX_CSS_CONTINUATION_LINES = 8
 
-/** How far a comment-only annotation reaches forward through the rest of its own comment block. */
-const MAX_COMMENT_BLOCK_LINES = 8
+/**
+ * The 0-based line the annotation's OWN comment closes on.
+ *
+ * A comment-only annotation waives the first line below its comment that is not itself comment, so
+ * the walk needs to know how far the annotation's own comment reaches. It used to substitute a
+ * budget — walk forward at most eight lines — which was wrong in two ways nothing could see:
+ *
+ * 1. **A comment block longer than the budget.** A docblock with ~12 lines of reason between the
+ *    token and its `*\/` ran the walk out before it reached the code, while the oxlint plugin
+ *    (which reads the comment NODE, so length is free) waived it. Nothing about the shape said so;
+ *    the annotation just stopped working past a line count nobody could count.
+ * 2. **A blank line inside the block.** Outside a comment a blank line SEPARATES — it is how people
+ *    say "this comment is not about the next statement" — but a blank gutter line in the middle of
+ *    a docblock is just prose, and ending the walk there dropped the waiver.
+ *
+ * Knowing where the comment ends settles both: inside it, keep going; past it, the ordinary
+ * comment-run rules apply (see the walk in {@link collectAllowAnnotations}, and
+ * {@link isCommentOnly} for the third hole this pass closed).
+ *
+ * An unterminated block comment reports its own line — the conservative answer for a file that does
+ * not parse anyway, and it keeps the walk from running to EOF.
+ */
+function commentBlockEnd(
+  lines: readonly string[],
+  index: number,
+  tokenAt: number,
+  syntax: GuardSyntax,
+): number {
+  const line = lines[index] ?? ''
+  // A line comment closes at its own end of line. CSS has no `//`, so the test is TS-only: there,
+  // a `//`-looking sequence is text and the conservative same-line answer is the right one anyway.
+  if (syntax === 'ts' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
+  const closer = syntax === 'markup' ? '-->' : '*/'
+  if (line.slice(tokenAt).includes(closer)) return index
+  for (let ahead = index + 1; ahead < lines.length; ahead++) {
+    if ((lines[ahead] ?? '').includes(closer)) return ahead
+  }
+  return index
+}
 
 /**
  * A comment opener sitting immediately before the annotation token.
@@ -805,6 +842,22 @@ const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/
  */
 const JSX_COMMENT_CLOSE = /\*\/\s*\}\s*$/
 
+/**
+ * Is this line NOTHING but comment? — one definition, used both to classify the annotation's own
+ * line (own-line vs trailing) and to walk the lines under it.
+ *
+ * The two used to be written out separately, and the walk's copy was the one missing the
+ * {@link JSX_COMMENT_CLOSE} clause: a `*\/}` alone on its line read as the code `}`, so the walk
+ * stopped ON the closer and the annotation waived a brace. Two consumers isolated that
+ * independently — `{/* … *\/}` and `{/** … *\/}` — each with a probe pair differing by one newline,
+ * while the oxlint plugin (whose test is comment-node-based and never sees the brace) waived both.
+ * A shared predicate is what stops the two placements from drifting apart again.
+ */
+function isCommentOnly(raw: string, stripped: string): boolean {
+  const code = stripped.trim()
+  return code === '' || COMMENT_ONLY_LINE.test(raw) || (code === '}' && JSX_COMMENT_CLOSE.test(raw))
+}
+
 /**
  * Everything allowed between the comment opener (or the start of the line) and the annotation
  * token, for the token to count as an ANNOTATION rather than prose that mentions one.
@@ -933,7 +986,12 @@ function collectAllowAnnotations(
   }
 
   /** Place one parsed annotation: file declarations reach everywhere, line ones the 3 placements. */
-  const record = (index: number, annotation: AllowAnnotation, trailing: boolean): void => {
+  const record = (
+    index: number,
+    annotation: AllowAnnotation,
+    trailing: boolean,
+    tokenAt: number,
+  ): void => {
     declared.push({ line: index + 1, annotation })
     if (annotation.scope === 'file') {
       fileScoped.push(annotation)
@@ -941,16 +999,20 @@ function collectAllowAnnotations(
     }
     add(index, annotation)
     if (!trailing) {
-      // The first line below that is not itself comment. A docblock's `*/` (or the rest of a
-      // wrapped reason) sits between the annotation and the code it is about, so `index + 1` alone
-      // meant the natural multi-line shape silently waived nothing — argo hit it three times in one
-      // upgrade, each looking like a correct annotation. A BLANK line still ends the block: that is
-      // the separation people use to mean "this comment is not about the next statement".
-      for (let ahead = 1; ahead <= MAX_COMMENT_BLOCK_LINES; ahead++) {
-        const raw = lines[index + ahead] ?? ''
-        add(index + ahead, annotation)
-        if (raw.trim() !== '' && (codeLines[index + ahead] ?? '').trim() !== '') break
+      // The first CODE line below the comment. A docblock's `*/` (or the rest of a wrapped reason)
+      // sits between the annotation and the code it is about, so `index + 1` alone meant the
+      // natural multi-line shape silently waived nothing — argo hit it three times in one upgrade,
+      // each looking like a correct annotation. A BLANK line outside the comment still ends the
+      // block: that is the separation people use to mean "this comment is not about the next
+      // statement". Inside it, a blank gutter line is just prose.
+      const closesAt = commentBlockEnd(lines, index, tokenAt, syntax)
+      for (let ahead = 1; index + ahead < lines.length; ahead++) {
+        const at = index + ahead
+        add(at, annotation)
+        if (at <= closesAt) continue
+        const raw = lines[at] ?? ''
         if (raw.trim() === '') break
+        if (!isCommentOnly(raw, codeLines[at] ?? '')) break
       }
       return
     }
@@ -968,14 +1030,17 @@ function collectAllowAnnotations(
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i] ?? ''
     const stripped = codeLines[i] ?? ''
-    const code = stripped.trim()
-    const isCommentOnlyLine =
-      code === '' || COMMENT_ONLY_LINE.test(line) || (code === '}' && JSX_COMMENT_CLOSE.test(line))
+    const isCommentOnlyLine = isCommentOnly(line, stripped)
 
     // The JSON member form. Markup-only: in TS/CSS that string would be code, not an annotation.
     if (syntax === 'markup') {
       for (const m of line.matchAll(jsonKey)) {
-        record(i, parseAllowAnnotation(m[2] ?? '', m[1] === undefined ? 'line' : 'file'), false)
+        record(
+          i,
+          parseAllowAnnotation(m[2] ?? '', m[1] === undefined ? 'line' : 'file'),
+          false,
+          m.index,
+        )
       }
     }
 
@@ -993,6 +1058,7 @@ function collectAllowAnnotations(
         i,
         parseAllowAnnotation(rest, m[1] === undefined ? 'line' : 'file'),
         !isCommentOnlyLine,
+        at,
       )
     }
   }

package/src/vite.test.ts

@@ -234,6 +234,85 @@ describe('basaltAppPlugin — base handling', () => {
     const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
     expect(manifest.icons[0].src).toBe('/brand/web-app-manifest-192x192.png')
   })
+
+  // ── the consumer-named array form ─────────────────────────────────────────
+  //
+  // `{ dir }` can move basalt's six filenames but not rename one, so an app whose only icon is
+  // `favicon.svg` could pick between a manifest naming two PNGs it does not ship and a manifest
+  // with no icons at all. Both are wrong for an installable app, and the second is why rb still
+  // kept a hand-written manifest one release after `icons: false` was fixed.
+
+  // rb's REAL icon set, copied from apps/web/public/manifest.webmanifest — the manifest this
+  // option exists to let the plugin generate.
+  const RB_ICONS = [
+    { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+  ] as const
+
+  test("generates rb's hand-written manifest icons member verbatim", () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: RB_ICONS })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons).toEqual([
+      { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+    ])
+    expect(JSON.stringify(manifest)).not.toContain('.png')
+    expect(manifest.name).toBe('rb')
+    expect(manifest.display).toBe('standalone')
+  })
+
+  test('a named icon reaches the head only when it asks for a rel', () => {
+    const iconLinks = (icons: NonNullable<BasaltAppOptions['icons']>): HtmlTagDescriptor[] => {
+      const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons })
+      resolveConfig(plugin, '/')
+      return transformHtml(plugin, HTML_NO_VIEWPORT).filter(
+        (tag) => tag.tag === 'link' && String(tag.attrs?.['rel']).includes('icon'),
+      )
+    }
+
+    // rb's index.html already links favicon.svg — the manifest gets fixed, the head is left alone.
+    expect(iconLinks(RB_ICONS)).toHaveLength(0)
+
+    const withRel = iconLinks([{ src: 'favicon.svg', type: 'image/svg+xml', rel: 'icon' }])
+    expect(withRel).toHaveLength(1)
+    expect(withRel[0]?.attrs).toEqual({
+      rel: 'icon',
+      type: 'image/svg+xml',
+      href: '/favicon.svg',
+    })
+  })
+
+  test('a named icon src is base-prefixed, with or without its leading slash', () => {
+    const plugin = getPlugin({
+      name: 'rb',
+      themeColor: THEME_COLOR,
+      icons: [
+        { src: 'favicon.svg', sizes: 'any' },
+        { src: '/icon-512.png', sizes: '512x512' },
+      ],
+    })
+    const middleware = getDevMiddleware(plugin, '/myapp/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/myapp/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons.map((icon: { src: string }) => icon.src)).toEqual([
+      '/myapp/favicon.svg',
+      '/myapp/icon-512.png',
+    ])
+  })
+
+  test('an empty array reads as icons: false — no member, not an empty one', () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: [] })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toBeUndefined()
+  })
+
+  test('the array form omits keys the consumer did not write', () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: [{ src: '/a.svg' }] })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toEqual([{ src: '/a.svg' }])
+  })
 })
 
 describe('basaltAppPlugin — the anti-FOUC boot rule (V1)', () => {