@estiva-app/ui 0.35.1 → 0.36.0

package/src/AttachmentCard.tsx

@@ -89,7 +89,7 @@ const formatBytes = (bytes: number) => {
 const typeLabelOf = (name: string) => extensionOf(name).toUpperCase() || 'FILE'
 
 const TILE_CLASSES = 'size-9 rounded-md bg-bg-active flex items-center justify-center shrink-0 text-text-secondary'
-// @estiva-escape: A6 (Katerina, 24 September: record only): a 12px medium name, the text style InputChip's label also uses, not a copy of a part
+// @estiva-escape(no-copied-look): A6 (Katerina, 24 September: record only): a 12px medium name, the text style InputChip's label also uses, not a copy of a part
 const NAME_CLASSES = 'text-caption font-medium text-text-primary truncate'
 const NOTE_CLASSES = 'text-small tracking-wide leading-tight truncate'
 
@@ -359,7 +359,7 @@ export function AttachmentCard({
     const failed = state === 'failed'
     const warning = state === 'warning'
     return (
-      // @estiva-escape: a failed or warning file's strong hairline is AttachmentCard's own state; Card's attention hairlines are the soft ones (UIG-9, Katerina 17 September)
+      // @estiva-escape(no-restyled-part): a failed or warning file's strong hairline is AttachmentCard's own state; Card's attention hairlines are the soft ones (UIG-9, Katerina 17 September)
       <Card
         fill="elevated"
         className={cn('group relative flex items-center gap-2 w-[200px] p-1.5 pr-3', failed ? 'border-error-default' : warning && 'border-warning-default', className)}
@@ -390,7 +390,7 @@ export function AttachmentCard({
         {/* On Base UI's Button, as InputChip's ✕ is (Katerina, 2026-09-14): IconButton is a 24px square
             that fills on hover, and this is Peek's 20px round badge on the card's corner. */}
         {onRemove && (
-          // @estiva-escape: N4 (Katerina, 24 September: record only): the small round button Lightbox's close also draws; a part if a third appears
+          // @estiva-escape(no-copied-look): N4 (Katerina, 24 September: record only): the small round button Lightbox's close also draws; a part if a third appears
           <BaseButton
             type="button"
             aria-label={`Remove ${name}`}
@@ -411,7 +411,7 @@ export function AttachmentCard({
 
   // Fades in with the card's hover or keyboard focus, and keeps its slot when hidden, so revealing it never shifts the row.
   const downloadControl = saving ? (
-    // @estiva-escape: Download shows when its card is pointed at or focused, AttachmentCard's own action; IconButton has no reveal on its card's hover (UIG-9, Katerina 17 September)
+    // @estiva-escape(no-restyled-part): Download shows when its card is pointed at or focused, AttachmentCard's own action; IconButton has no reveal on its card's hover (UIG-9, Katerina 17 September)
     <IconButton
       variant="muted"
       tooltip="Download"
@@ -430,7 +430,7 @@ export function AttachmentCard({
     return (
       // `role="status"`: a plain box may not carry a name (axe, aria-prohibited-attr), and a
       // status says what it is doing — loading — to a reader that cannot see the pulse.
-      // @estiva-escape: the loading pulse is AttachmentCard's own state; Card has no loading state (UIG-9, Katerina 17 September)
+      // @estiva-escape(no-restyled-part): the loading pulse is AttachmentCard's own state; Card has no loading state (UIG-9, Katerina 17 September)
       <Card role="status" fill="inset" aria-busy="true" aria-label={`Loading ${name}`} className={cn('w-[180px] h-28 animate-pulse', className)} {...props}>
         {null}
       </Card>
@@ -439,7 +439,7 @@ export function AttachmentCard({
 
   if (drawnState === 'unreadable') {
     return (
-      // @estiva-escape: a file that could not be read is faded as well as dashed, AttachmentCard's own state; Card has no faded state (UIG-9, Katerina 17 September)
+      // @estiva-escape(no-restyled-part): a file that could not be read is faded as well as dashed, AttachmentCard's own state; Card has no faded state (UIG-9, Katerina 17 September)
       <Card fill="inset" unreadable className={cn('flex items-center gap-2 w-[240px] p-1.5 opacity-70', className)} {...props}>
         <div className={TILE_CLASSES}>
           <TypeIcon name={name} />
@@ -494,7 +494,7 @@ export function AttachmentCard({
     </>
   )
   return (
-    // @estiva-escape: a file that cannot be opened is faded, AttachmentCard's own state; Card has no faded state (UIG-9, Katerina 17 September)
+    // @estiva-escape(no-restyled-part): a file that cannot be opened is faded, AttachmentCard's own state; Card has no faded state (UIG-9, Katerina 17 September)
     <Card fill="inset" hover={address ? 'hairline' : 'none'} className={cn('group flex items-center gap-2 w-[240px] p-1.5 pr-1', !address && 'opacity-70', className)} {...props}>
       {address ? (
         <Link href={address} external variant="plain" className="flex items-center gap-2 min-w-0 flex-1" onClick={(event) => event.stopPropagation()}>

package/src/Button.tsx

@@ -92,7 +92,7 @@ export function Button({
           size === 'default' && (hasLeadingIcon ? 'pl-2 pr-3' : 'px-2'),
           size === 'small' && (hasLeadingIcon ? 'pl-1.5 pr-2' : 'px-1.5'),
           !state.disabled && (variant === 'primary' || variant === 'resolve') && 'bg-accent-primary hover:bg-accent-hover text-text-inverse cursor-pointer signal:font-semibold',
-          // @estiva-escape: W2 (Katerina, 24 September: leave alone): an outlined button shares four words with Reaction's pill by coincidence
+          // @estiva-escape(no-copied-look): W2 (Katerina, 24 September: leave alone): an outlined button shares four words with Reaction's pill by coincidence
           !state.disabled && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-primary cursor-pointer',
           !state.disabled && variant === 'muted' && 'hover:bg-bg-hover text-text-primary cursor-pointer',
           !state.disabled && variant === 'destructive' && 'hover:bg-error-muted text-error-default cursor-pointer',

package/src/Card.tsx

@@ -127,14 +127,14 @@ export function Card({
   if (href !== undefined) {
     const { ref, ...anchorProps } = props as ComponentPropsWithRef<'a'>
     return (
-      // @estiva-escape: a card that leads somewhere is drawn on Link's anchor (UIG-27 ruling 1), so this frame is Card's own look, not Link restyled
+      // @estiva-escape(no-copied-look, no-restyled-part): a card that leads somewhere is drawn on Link's anchor (UIG-27 ruling 1), so this frame is Card's own look, not Link restyled
       <Link href={href} variant="plain" ref={ref} className={classes} {...anchorProps}>
         {children}
       </Link>
     )
   }
   return (
-    // @estiva-escape: N6 (Katerina, 24 September: leave alone): a card that cuts its content to its corners shares four words with the palette's window by coincidence
+    // @estiva-escape(no-copied-look): N6 (Katerina, 24 September: leave alone): a card that cuts its content to its corners shares four words with the palette's window by coincidence
     <div className={classes} {...props}>
       {children}
     </div>

package/src/ChipInput.mdx

@@ -32,6 +32,8 @@ leading slots.
 ```tsx
 import { ChipInput } from '@estiva-app/ui'
 
+const directory: { id: string; label: string; picture?: string }[] = people
+
 <ChipInput
   value={chosen}
   onChange={setChosen}

package/src/ChipInput.tsx

@@ -62,7 +62,7 @@ export function InputChip({ label, leading, onRemove, removeLabel, truncate, cla
   return (
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>
       {leading && <span className="flex shrink-0 items-center">{leading}</span>}
-      {/* @estiva-escape: A6 (Katerina, 24 September: record only): a 12px medium label, the text style AttachmentCard's name also uses, not a copy of a part */}
+      {/* @estiva-escape(no-copied-look): A6 (Katerina, 24 September: record only): a 12px medium label, the text style AttachmentCard's name also uses, not a copy of a part */}
       <span className={cn(CHIP_LABEL, truncate && 'min-w-0 truncate')}>{label}</span>
       {/* Base UI's `Button`, as every button in the package is (D6). Base UI
           has no chip of its own — its only chips are `Combobox.Chip` and

package/src/CommandPalette.tsx

@@ -123,7 +123,7 @@ export function CommandPalette({ open, onOpenChange, label, where, modKey = 'Ctr
       <Dialog.Portal>
         <Dialog.Backdrop className="fixed inset-0 z-40 bg-scrim" />
         <Dialog.Viewport className="fixed inset-0 z-50 flex items-start justify-center pt-[16vh]">
-          {/* @estiva-escape: A3 (Katerina, 24 September: leave CommandPalette alone): the palette's window keeps its own border */}
+          {/* @estiva-escape(no-copied-look): A3 (Katerina, 24 September: leave CommandPalette alone): the palette's window keeps its own border */}
           <Dialog.Popup
             ref={popupRef}
             aria-label={label}
@@ -374,7 +374,7 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
       <div className="flex h-12 shrink-0 items-center gap-3 border-b border-border-subtle px-5">
         <IconSearch size={16} stroke={1.5} className="shrink-0 text-text-secondary" />
         {chip && <LevelChip chip={chip} onBack={back} />}
-        {/* @estiva-escape: A5 (Katerina, 24 September: leave CommandPalette alone): the palette's search field keeps its own classes */}
+        {/* @estiva-escape(no-copied-look): A5 (Katerina, 24 September: leave CommandPalette alone): the palette's search field keeps its own classes */}
         <Autocomplete.Input
           ref={inputRef}
           data-command-palette-field=""
@@ -555,7 +555,7 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
 
   return (
     <div ref={frameRef} tabIndex={-1} onKeyDown={onKeyDown} onFocus={measure} onBlur={measure} onInput={measure} className="flex min-h-0 flex-col outline-none">
-      {/* @estiva-escape: the palette's own input bar, the twin of its search row; the level chip stands where the field was */}
+      {/* @estiva-escape(no-handmade-header): the palette's own input bar, the twin of its search row; the level chip stands where the field was */}
       <div className="flex h-12 shrink-0 items-center gap-3 border-b border-border-subtle px-5">
         {icon != null && <span className="flex shrink-0 items-center text-text-secondary">{icon}</span>}
         <LevelChip chip={chip} onBack={back} />

package/src/DialogShell.tsx

@@ -86,7 +86,7 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
 
         {/* Dialog */}
         <div className="fixed inset-0 z-50 flex items-center justify-center pointer-events-none">
-          {/* @estiva-escape: A3 (Katerina, 24 September: leave CommandPalette alone): a dialog's window and the palette's are left as they are */}
+          {/* @estiva-escape(no-copied-look): A3 (Katerina, 24 September: leave CommandPalette alone): a dialog's window and the palette's are left as they are */}
           <Parts.Popup
             ref={popupRef}
             /*

package/src/EmptyState.mdx

@@ -36,9 +36,10 @@ need a height from the caller (`className="h-full"`).
 
 ## When not
 
-- Data is still on its way → **Skeleton**; empty and loading are different
-  truths. When the shape of what arrives is unknown, an EmptyState that says so
-  — "Opening…" — is fine.
+- Data is still on its way → **Skeleton**: **SkeletonList**, or a shape of
+  your own from **SkeletonBar**; empty and loading are different truths.
+  When the shape of what arrives is unknown, an EmptyState that says so —
+  "Opening…" — is fine.
 - Something went wrong → say what failed, in words. An EmptyState can carry
   it, in its usual look — never red. An empty state that hides a failure
   misleads.

package/src/Lightbox.tsx

@@ -74,7 +74,7 @@ export function Lightbox({ src, alt, onClose, className }: LightboxProps) {
             onClick={(e) => e.stopPropagation()}
             className={cn('max-w-full max-h-full object-contain rounded-lg', className)}
           />
-          {/* @estiva-escape: N4 (Katerina, 24 September: record only): the small round button AttachmentCard's remove also draws; a part if a third appears */}
+          {/* @estiva-escape(no-copied-look): N4 (Katerina, 24 September: record only): the small round button AttachmentCard's remove also draws; a part if a third appears */}
           <Dialog.Close
             aria-label="Close"
             className="absolute top-4 right-4 size-8 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary"

package/src/NavItem.tsx

@@ -28,7 +28,7 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
 
 export function NavItem({ label, href, count, countLabel, active = false, icon, className, ...props }: NavItemProps) {
   return (
-    // @estiva-escape: N5 (Katerina, 24 September: record only): a row that fills on hover, as PersonTrigger's row also does
+    // @estiva-escape(no-copied-look): N5 (Katerina, 24 September: record only): a row that fills on hover, as PersonTrigger's row also does
     <a
       href={href}
       aria-current={active ? 'page' : undefined}

package/src/PersonTrigger.tsx

@@ -60,7 +60,7 @@ export function PersonTrigger({ name, picture, fallback, size, open = false, com
     )
   }
   return (
-    // @estiva-escape: N5 (Katerina, 24 September: record only): a row that fills on hover, as NavItem also does
+    // @estiva-escape(no-copied-look): N5 (Katerina, 24 September: record only): a row that fills on hover, as NavItem also does
     <BaseButton
       type="button"
       aria-haspopup="menu"

package/src/Reaction.tsx

@@ -63,7 +63,7 @@ export interface ReactionProps extends Omit<ButtonHTMLAttributes<HTMLButtonEleme
 
 export function Reaction({ emoji, count, pressed = false, className, ...props }: ReactionProps) {
   return (
-    // @estiva-escape: W1 (Katerina, 24 September: leave alone): a reaction pill shares four words with a field's box by coincidence
+    // @estiva-escape(no-copied-look): W1 (Katerina, 24 September: leave alone): a reaction pill shares four words with a field's box by coincidence
     <Toggle
       // Controlled: a reaction is yours when the data says so, not when the
       // pill was last pressed — a write can fail, and another client can

package/src/ScrollArea.mdx

@@ -27,6 +27,10 @@ the content is moving; nothing moves when it appears.
 - A box that never overflows. A ScrollArea around it changes nothing, and
   is one more element.
 - The page itself. The browser owns that bar.
+- A whole list column → **ListColumn**, which scrolls its rows itself.
+
+No alternative for the first two: a box that never overflows needs nothing
+around it, and the page's bar is the browser's.
 
 ## How
 

package/src/Select.tsx

@@ -74,7 +74,7 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
   // a native `disabled` button, which Tab skips and a tooltip cannot open on.
   const held = Boolean(disabledReason)
   const trigger = (
-      // @estiva-escape: N1 (Katerina, 24 September: record only): Select's box drops the hover while held, so it cannot take FIELD_SHELL_CLASSES as it is
+      // @estiva-escape(no-copied-look): N1 (Katerina, 24 September: record only): Select's box drops the hover while held, so it cannot take FIELD_SHELL_CLASSES as it is
       <BaseSelect.Trigger
         aria-label={ariaLabel}
         aria-required={aria['aria-required']}

package/src/TopBar.mdx

@@ -33,7 +33,7 @@ reachable.
 ## When not
 
 - Page-level headers inside the content → not this; this is the frame's
-  bar, once per app.
+  bar, once per app. The top of a column is **ContainerHeader**.
 - Anything the bar would need to know — who you are, what is searched —
   stays outside: pass composed slots.
 

package/src/eslint/escape.ts

@@ -4,15 +4,21 @@ import type { AST, Rule } from 'eslint'
  * The escape marker (UIG-3, seam S4 in docs/GATES.md §16): one written reason
  * why one element stays as it is.
  *
- * A line comment directly above the element,
+ * A line comment directly above the element, naming the rule it keeps off,
  *
- *     // @estiva-escape: <reason>
+ *     // @estiva-escape(no-raw-element): <reason>
  *
  * or, where the element is a JSX child, the JSX comment on the line above,
  *
- *     {/* @estiva-escape: <reason> *\/}
+ *     {/* @estiva-escape(no-raw-element): <reason> *\/}
  *
- * with at least ten characters of reason, spaces not counted.
+ * with at least ten characters of reason, spaces not counted. It escapes only
+ * the rules it names (Katerina's ruling B3, 25 September: one reason used to
+ * switch off every rule on the element, so a raw button that also wrote a
+ * dialog's role by hand passed under one reason). Two rules on one element are
+ * named together, `@estiva-escape(no-raw-element, no-rebuilt-behaviour)`, each
+ * on purpose. A marker that names no rule escapes nothing, and says which name
+ * to write.
  *
  * Not `eslint-disable`. A directive switches a rule off without saying it was
  * meant, and the count of escapes (`.gates-count.json`) could not see it. A
@@ -37,11 +43,29 @@ export const SETTINGS_KEY = 'estiva'
  * reports through the rule that called it.
  */
 export const ESCAPE_MESSAGES = {
-  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}: <why this stays>\`. An escape with no reason hides nothing.`,
-  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}: <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}({{rule}}): <why this stays>\`. An escape with no reason hides nothing.`,
+  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}({{rule}}): <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escapeWithoutRule: `Name the rule this escape keeps off: \`${ESCAPE_MARKER}({{rule}}): <reason>\`. An escape now keeps off only the rules it names.`,
   escaped: 'Escaped: {{reason}}',
 } as const
 
+/** A rule's name as a marker writes it: `no-raw-element` for `estiva/no-raw-element`. */
+export const shortRuleName = (id: string) => id.slice(id.lastIndexOf('/') + 1)
+
+/**
+ * What a marker says, read from a comment's text: the rules it names (none when
+ * it names none) and its reason. Null when the comment carries no marker.
+ */
+export function readMarker(text: string): { rules: string[]; reason: string } | null {
+  const at = text.indexOf(ESCAPE_MARKER)
+  if (at === -1) return null
+  const rest = text.slice(at + ESCAPE_MARKER.length)
+  const named = /^\s*\(([^)]*)\)/.exec(rest)
+  const rules = named ? named[1].split(/[\s,]+/).filter(Boolean).map(shortRuleName) : []
+  const reason = (named ? rest.slice(named[0].length) : rest).replace(/^\s*:/, '').trim()
+  return { rules, reason }
+}
+
 export interface EstivaSettings {
   /**
    * Report every sanctioned escape as a message with the id `escaped`, so a
@@ -85,24 +109,29 @@ export function isEscaped(context: Rule.RuleContext, node: Located): boolean {
     .find((c) => c.loc && c.range && c.loc.end.line === line - 1 && BETWEEN.test(sourceCode.text.slice(c.range[1], nodeStart)))
   if (!comment?.loc) return false
 
-  const at = comment.value.indexOf(ESCAPE_MARKER)
-  if (at === -1) return false
+  const marker = readMarker(comment.value)
+  if (!marker) return false
+  const rule = shortRuleName(context.id)
 
   const directive = DIRECTIVE.exec(comment.value)
   if (directive) {
     const rules = directiveRules(directive[1])
     // A directive for other rules (the token lint's notes) is not an escape of this one.
     if (rules.length > 0 && !rules.includes(context.id)) return false
-    context.report({ loc: comment.loc, messageId: 'escapeInDirective' })
+    context.report({ loc: comment.loc, messageId: 'escapeInDirective', data: { rule } })
+    return false
+  }
+
+  // Named, but not this rule: another rule on the element may be the one it keeps off.
+  if (marker.rules.length > 0 && !marker.rules.includes(rule)) return false
+  if (marker.rules.length === 0) {
+    context.report({ loc: comment.loc, messageId: 'escapeWithoutRule', data: { rule } })
     return false
   }
 
-  const reason = comment.value
-    .slice(at + ESCAPE_MARKER.length)
-    .replace(/^:/, '')
-    .trim()
+  const { reason } = marker
   if (reason.replace(/\s/g, '').length < MIN_REASON) {
-    context.report({ loc: comment.loc, messageId: 'escapeWithoutReason' })
+    context.report({ loc: comment.loc, messageId: 'escapeWithoutReason', data: { rule } })
     return false
   }
 

package/src/eslint/has-a-page-and-a-story.test.ts

@@ -17,7 +17,7 @@ const tester = new RuleTester({
 /** Real files of this package, so the rules are tested against what they read. */
 const src = (name: string) => fileURLToPath(new URL(`../${name}`, import.meta.url))
 const code = 'export function Probe() {\n  return null\n}\n'
-const escaped = '// @estiva-escape: a probe file that documents itself in its own page\nexport function Probe() {\n  return null\n}\n'
+const escaped = '// @estiva-escape(component-has-a-page, component-has-a-story): a probe file that documents itself in its own page\nexport function Probe() {\n  return null\n}\n'
 
 describe('the files these rules read', () => {
   it('Button has a page and a story beside it, and FieldLine and MenuItem have both without a component file', () => {

package/src/eslint/index.test.ts

@@ -145,14 +145,14 @@ describe('an app lint with configs.recommended', () => {
   })
 
   it('passes the same element under an escape', async () => {
-    const [result] = await lint(component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'))
+    const [result] = await lint(component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button type="button">x</button>'))
     expect(result.messages).toEqual([])
   })
 })
 
 describe('countGates', () => {
   it('counts an error, and an escape only when the lint reports escapes', async () => {
-    const code = component('    <div>\n      <button>x</button>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button>y</button>\n    </div>')
+    const code = component('    <div>\n      <button>x</button>\n      {/* @estiva-escape(no-raw-element): a preview drawn from its own palette */}\n      <button>y</button>\n    </div>')
     const none = { errors: 0, warnings: 0, escapes: 0 }
     expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 0 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none, 'estiva/no-copied-look': none })
     expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none, 'estiva/no-copied-look': none })

package/src/eslint/no-copied-look.test.ts

@@ -65,7 +65,7 @@ tester.run('no-copied-look', noCopiedLook, {
     {
       name: 'an escape with its reason',
       filename: app,
-      code: probe(`<>\n      {/* @estiva-escape: recorded in GATES.md, a label strip Katerina left as it is */}\n      <span className="${SECTION_LABEL}">x</span>\n    </>`),
+      code: probe(`<>\n      {/* @estiva-escape(no-copied-look): recorded in GATES.md, a label strip Katerina left as it is */}\n      <span className="${SECTION_LABEL}">x</span>\n    </>`),
     },
   ],
   invalid: [

package/src/eslint/no-hand-rolled-behaviour.test.ts

@@ -29,15 +29,15 @@ tester.run('no-hand-rolled-behaviour', noHandRolledBehaviour, {
     },
     {
       name: 'the import of a portal, kept with its reason',
-      code: "// @estiva-escape: the toast keeps its own portal until migration stage 6\nimport { createPortal } from 'react-dom'\nexport const Probe = () => null\n",
+      code: "// @estiva-escape(no-hand-rolled-behaviour): the toast keeps its own portal until migration stage 6\nimport { createPortal } from 'react-dom'\nexport const Probe = () => null\n",
     },
     {
       name: 'the call, kept with its reason',
-      code: 'export function probe(to: HTMLElement) {\n  // @estiva-escape: the toast keeps its own portal until migration stage 6\n  return createPortal(null, to)\n}\n',
+      code: 'export function probe(to: HTMLElement) {\n  // @estiva-escape(no-hand-rolled-behaviour): the toast keeps its own portal until migration stage 6\n  return createPortal(null, to)\n}\n',
     },
     {
       name: 'a global listener kept with its reason',
-      code: 'export function probe() {\n  // @estiva-escape: the frame measures the window, which no floating part owns\n  window.addEventListener("resize", () => {})\n}\n',
+      code: 'export function probe() {\n  // @estiva-escape(no-hand-rolled-behaviour): the frame measures the window, which no floating part owns\n  window.addEventListener("resize", () => {})\n}\n',
     },
   ],
   invalid: [

package/src/eslint/no-handmade-empty-state.test.ts

@@ -91,7 +91,7 @@ tester.run('no-handmade-empty-state', noHandmadeEmptyState, {
     { name: 'a box holding more than the line', code: jsx('<div>{rows.length === 0 ? <div className="px-3"><p>Nothing yet.</p><Button>Add one</Button></div> : rows.map((r) => <p key={r}>{r}</p>)}</div>') },
     {
       name: 'an escape with its reason',
-      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape: a printed report keeps its own empty line, set in the print style\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
+      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape(no-handmade-empty-state): a printed report keeps its own empty line, set in the print style\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
     },
 
     // the right scope
@@ -118,7 +118,7 @@ tester.run('no-handmade-empty-state', noHandmadeEmptyState, {
     },
     {
       name: 'an escape with no reason is not an escape',
-      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
+      code: jsx('<div>{rows.length === 0 ? (\n// @estiva-escape(no-handmade-empty-state)\n<p>Nothing to print.</p>\n) : rows.map((r) => <p key={r}>{r}</p>)}</div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, ...handmade],
     },
 

package/src/eslint/no-handmade-header.test.ts

@@ -33,7 +33,7 @@ tester.run('no-handmade-header', noHandmadeHeader, {
     { name: 'a column of rows', code: component('<div className="flex h-full flex-col">\n<div className="flex flex-col px-3"><span>{title}</span></div>\n<div />\n</div>') },
     {
       name: 'an escape with its reason',
-      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape: a print header that must not follow the theme */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
+      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape(no-handmade-header): a print header that must not follow the theme */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
     },
   ],
   invalid: [
@@ -82,7 +82,7 @@ tester.run('no-handmade-header', noHandmadeHeader, {
     },
     {
       name: 'an escape with no reason escapes nothing',
-      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape: */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
+      code: component('<div className="flex h-full flex-col">\n{/* @estiva-escape(no-handmade-header): */}\n<div className="flex items-center px-3 py-2"><span>{title}</span></div>\n<div />\n</div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'handmade' }],
     },
   ],

package/src/eslint/no-native-title.test.ts

@@ -40,7 +40,7 @@ tester.run('no-native-title', noNativeTitle, {
     { name: "the app's own component with a title of its own (Peek's NewTopicBanner)", filename: app, code: component('<NewTopicBanner title={name} />', "import { NewTopicBanner } from '@/components/Banner'\n") },
     { name: "a story's title is the Storybook's, an object key", code: "const meta = { title: 'Primitives/Tooltip', component: Tooltip }\nexport default meta\n" },
     { name: 'a prop of another name', code: component('<span aria-label={name} data-title={name}>{name}</span>') },
-    { name: 'an escape with its reason', code: component('<>\n{/* @estiva-escape: the print view has no pointer, and the address must survive a copy */}\n<span title={at}>{at}</span>\n</>') },
+    { name: 'an escape with its reason', code: component('<>\n{/* @estiva-escape(no-native-title): the print view has no pointer, and the address must survive a copy */}\n<span title={at}>{at}</span>\n</>') },
   ],
   invalid: [
     {
@@ -54,7 +54,7 @@ tester.run('no-native-title', noNativeTitle, {
     { name: "a part that hands it on to its element: the apps' status probe", code: component('<Button title="Delete">x</Button>', "import { Button } from '@estiva-app/ui'\n"), errors: native },
     { name: "through the app's re-export", filename: app, code: component('<IconButton title="Close" aria-label="Close">x</IconButton>', "import { IconButton } from '@/components/ui/IconButton'\n"), errors: native },
     { name: "through the app's wrapper that hands its props on", filename: app, code: component('<Button title="Delete">x</Button>', "import { Button } from '@/components/ui/Button'\n"), errors: native },
-    { name: 'an escape with no reason is not an escape', code: component('<>\n{/* @estiva-escape */}\n<span title={at}>{at}</span>\n</>'), errors: [{ messageId: 'escapeWithoutReason' }, ...native] },
+    { name: 'an escape with no reason is not an escape', code: component('<>\n{/* @estiva-escape(no-native-title) */}\n<span title={at}>{at}</span>\n</>'), errors: [{ messageId: 'escapeWithoutReason' }, ...native] },
   ],
 })
 

package/src/eslint/no-raw-element.test.ts

@@ -25,6 +25,10 @@ tester.run('no-raw-element', noRawElement, {
     { name: "the package's Button", code: component('<Button>Save</Button>') },
     { name: 'a member expression named button', code: component('<Foo.button>Save</Foo.button>') },
     { name: 'a name that starts with button', code: component('<buttonish />') },
+    // R5: a handler that only stops the click passes; a part may take one
+    { name: 'a wrapper that only stops the click', code: component('<div onClick={(e) => e.stopPropagation()} onPointerDown={(event) => { event.stopPropagation(); event.preventDefault() }}><Button>Save</Button></div>') },
+    { name: 'a press handler on a part', code: component('<Card onClick={open}>x</Card>') },
+    { name: 'a clickable element, escaped with its reason', code: component('    // @estiva-escape(no-raw-element): a surface that holds headings and lists, which a button cannot hold\n    <div onClick={edit}>x</div>') },
     {
       name: 'the elements that are not controls',
       code: component('    <section>\n      <h1>Title</h1>\n      <p>Text <strong>and</strong> <em>more</em></p>\n      <ul><li>One</li></ul>\n      <img src="x.png" alt="" />\n      <hr />\n      <kbd>Enter</kbd>\n      <svg><path d="M0 0" /></svg>\n      <time dateTime="2026-09-16">today</time>\n    </section>'),
@@ -37,31 +41,45 @@ tester.run('no-raw-element', noRawElement, {
     { name: 'controls written as false', code: component('<audio src="a.mp3" controls={false} />') },
     {
       name: 'a line comment escape directly above',
-      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'),
+      code: component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button type="button">x</button>'),
+    },
+    {
+      name: 'a marker naming two rules keeps off each of them, written with or without the plugin name',
+      code: component('    // @estiva-escape(no-rebuilt-behaviour, estiva/no-raw-element): a preview drawn from its own palette\n    <button type="button">x</button>'),
     },
     {
       name: 'a JSX comment escape on the line above a child',
-      code: component('    <div>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button type="button">x</button>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(no-raw-element): a preview drawn from its own palette */}\n      <button type="button">x</button>\n    </div>'),
     },
     {
       name: 'a JSX comment escape over several lines',
-      code: component('    <div>\n      {/*\n        @estiva-escape: a preview drawn from its own palette\n      */}\n      <button type="button">x</button>\n    </div>'),
+      code: component('    <div>\n      {/*\n        @estiva-escape(no-raw-element): a preview drawn from its own palette\n      */}\n      <button type="button">x</button>\n    </div>'),
     },
     {
       name: 'an escape above an opening tag that spans lines',
-      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button\n      type="button"\n      onClick={() => {}}\n    >\n      x\n    </button>'),
+      code: component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button\n      type="button"\n      onClick={() => {}}\n    >\n      x\n    </button>'),
     },
     {
       name: 'exactly ten characters of reason, spaces not counted',
-      code: component('    // @estiva-escape: ab cd ef gh ij\n    <button>x</button>'),
+      code: component('    // @estiva-escape(no-raw-element): ab cd ef gh ij\n    <button>x</button>'),
     },
     {
       name: 'an element with no part, escaped',
-      code: component('    // @estiva-escape: a map from another service, until the package has a frame\n    <iframe src="https://example.com" title="Map" />'),
+      code: component('    // @estiva-escape(no-raw-element): a map from another service, until the package has a frame\n    <iframe src="https://example.com" title="Map" />'),
     },
   ],
   invalid: [
     { name: 'a raw button', code: component('    <button type="button">x</button>'), errors: [{ messageId: 'raw', line: 3 }] },
+    {
+      name: 'a clickable div names Button and Card with href (R5)',
+      code: component('    <div onClick={open}>x</div>'),
+      errors: [{ message: 'A clickable <div onClick> is a button made by hand: it takes no focus and answers no key. Use `Button` from @estiva-app/ui; for a whole card that opens something, `Card` with `href`. A handler that only stops the click (`e.stopPropagation()`) is fine.' }],
+    },
+    {
+      name: 'a press that does more than stop the click, on any plain element',
+      code: component('    <li onMouseDown={(e) => { e.preventDefault(); onSearch() }}>\n      <span onPointerDown={handle} />\n    </li>'),
+      errors: [{ messageId: 'clickable', data: { element: '<li onMouseDown>' } }, { messageId: 'clickable', data: { element: '<span onPointerDown>' } }],
+    },
     {
       name: 'an opening tag that spans lines (what grep misses)',
       code: component('    <input\n      type="text"\n      value={x}\n    />'),
@@ -106,7 +124,7 @@ tester.run('no-raw-element', noRawElement, {
 
     {
       name: 'an escape with no reason is an error, and hides nothing',
-      code: component('    // @estiva-escape:\n    <button>x</button>'),
+      code: component('    // @estiva-escape(no-raw-element):\n    <button>x</button>'),
       errors: [
         { messageId: 'escapeWithoutReason', line: 3 },
         { messageId: 'raw', line: 4 },
@@ -114,22 +132,36 @@ tester.run('no-raw-element', noRawElement, {
     },
     {
       name: 'nine characters of reason is too short',
-      code: component('    <div>\n      {/* @estiva-escape: ab cd ef gh i */}\n      <button>x</button>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(no-raw-element): ab cd ef gh i */}\n      <button>x</button>\n    </div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
     },
     {
       name: 'a marker with no colon and no reason',
-      code: component('    // @estiva-escape\n    <button>x</button>'),
+      code: component('    // @estiva-escape(no-raw-element)\n    <button>x</button>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
     },
+    // B3 (Katerina, 25 September): a marker keeps off only the rules it names.
+    {
+      name: 'a marker that names no rule escapes nothing, and says which name to write',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      errors: [
+        { line: 3, message: 'Name the rule this escape keeps off: `@estiva-escape(no-raw-element): <reason>`. An escape now keeps off only the rules it names.' },
+        { messageId: 'raw', line: 4 },
+      ],
+    },
+    {
+      name: 'a marker that names another rule does not keep this one off',
+      code: component('    // @estiva-escape(no-rebuilt-behaviour): a preview drawn from its own palette\n    <button>x</button>'),
+      errors: [{ messageId: 'raw', line: 4 }],
+    },
     {
       name: 'an escape two lines above does not reach the element',
-      code: component('    // @estiva-escape: a preview drawn from its own palette\n\n    <button>x</button>'),
+      code: component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n\n    <button>x</button>'),
       errors: [{ messageId: 'raw', line: 5 }],
     },
     {
       name: 'an escape above a sibling does not reach the next element',
-      code: component('    <div>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <span />\n      <button>x</button>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(no-raw-element): a preview drawn from its own palette */}\n      <span />\n      <button>x</button>\n    </div>'),
       errors: [{ messageId: 'raw', line: 6 }],
     },
     {
@@ -139,23 +171,23 @@ tester.run('no-raw-element', noRawElement, {
     },
     {
       name: 'a marker inside a directive that switches every rule off is refused',
-      code: component('    // eslint-disable-next-line -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      code: component('    // eslint-disable-next-line -- @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button>x</button>'),
       // The directive silences the element's own report; the refusal sits on the directive's line.
       errors: [{ messageId: 'escapeInDirective', line: 3 }],
     },
     {
       name: 'a marker inside a directive that names this rule is refused',
-      code: component('    // eslint-disable-next-line rule-to-test/no-raw-element -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      code: component('    // eslint-disable-next-line rule-to-test/no-raw-element -- @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button>x</button>'),
       errors: [{ messageId: 'escapeInDirective', line: 3 }],
     },
     {
       name: "the token lint's note for another rule is not an escape of this one",
-      code: component('    // eslint-disable-next-line no-console -- @estiva-escape: its hand-written type waits for that\n    <button>x</button>'),
+      code: component('    // eslint-disable-next-line no-console -- @estiva-escape(no-raw-element): its hand-written type waits for that\n    <button>x</button>'),
       errors: [{ messageId: 'raw', line: 4 }],
     },
     {
       name: 'with reportEscapes on, a sanctioned escape is reported for the count',
-      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      code: component('    // @estiva-escape(no-raw-element): a preview drawn from its own palette\n    <button>x</button>'),
       settings: { estiva: { reportEscapes: true } },
       errors: [{ messageId: 'escaped', data: { reason: 'a preview drawn from its own palette' }, line: 3 }],
     },