` → empty value is invalid for * `draggable`, so the element falls to the **auto** state — which for a * `

` means **not draggable**. The attribute that was supposed to turn * dragging on turns nothing on. * - `draggable={false}` → attribute omitted → **auto** again, and auto for * `` / `` is *draggable*. The disable never happens either. * - `spellCheck={false}` / `contentEditable={false}` → omitted → the * **inherit** default, not the false state. (Their `true` direction happens * to work: the empty string is a spec keyword for the true state on those * two, unlike `draggable`.) * * So these are typed as string literal unions and reject `boolean` outright. * Six attributes have this shape; they do NOT all share one type, because the * keywords differ — `EnumeratedBool` (`"true"`/`"false"`) covers `draggable`, * `spellcheck` and `writingsuggestions`, `ContentEditableValue` adds * `plaintext-only`, and `translate` (`"yes"`/`"no"`) and `autocorrect` * (`"on"`/`"off"`) spell their keywords differently again. Grep `EnumeratedBool` * for the largest group. The fix is at the type * level rather than in the runtime on purpose: translating `{true}` → * `="true"` would require the renderer to carry a list of every enumerated * attribute in HTML, and any attribute *missing* from that list would silently * regress to precisely this bug. A per-attribute type keeps the knowledge where * the spec knowledge already lives and costs nothing at runtime. The tradeoff * is a compile error on `draggable={true}` — which is the point. * * One residual hole this cannot close: a signal-valued attribute * (`draggable={sig}`) is `ReadonlySignal`, so a boolean inside it is * invisible to the type system. Put the string in the signal: `signal('true')`. * * A third shape sits between the two and accepts `boolean | string` * legitimately: **presence-or-value** attributes, where the presence carries * the meaning and a value refines it. `download` is the clearest case — bare, * it means "download this and let the server name the file"; with a value, the * value is the filename; absent, it's ordinary navigation. `capture` on * `` is the same shape (bare = the default capture device, * `user`/`environment` pick one). * * The test that separates this shape from the enumerated one: ask what * `{true}` and `{false}` each render, then what those markups MEAN. Here all * three states are real and distinct, so both forms are typed. For `draggable` * they collapse onto the same `auto` state, which is why `boolean` is rejected * there. * * ## Deliberate deviations from the spec * * Each of these is a knowing departure, kept because removing it would cost * more than it buys: * * - **Lowercase aliases** (`class`, `for`, `tabindex`, `autofocus`, * `spellcheck`, `contenteditable`, `autocomplete`) sit alongside the * camelCase forms. Both spellings are accepted because the migration docs * tell incoming developers to write the real HTML name. * - **`contentEditable="inherit"`** is accepted but is *not* a spec keyword. * It lands on the inherit state only via the invalid-value default. Kept * for React parity; omitting the attribute is the spec-correct way to * inherit. * - **`tabindex` / `autofocus` / `capture`** accept a widened value set * (string ints, plain `boolean`) matching what the parser actually honors. * - **`cellPadding` / `cellSpacing`** are obsolete presentational attributes, * marked `@deprecated` rather than removed so legacy markup still compiles. * - **`xlink:*`** attributes are deprecated in SVG 2 but still typed — real * documents and icon sprites still carry them. * - **`data-morph-skip` / `-skip-children` / `-preserve`** are kerf's own * `data-*` attributes, valid HTML by the `data-*` rule. * - **``** is Open Graph vocabulary, not an attribute in the * HTML standard. Typed anyway because it is universal in real documents — * every social-preview `` carries `og:*` meta tags. * * Attributes that are *not* typed because they do nothing when rendered as * markup: `value` / `defaultValue` on `

` (neither
 * element has a `value` content attribute — a select's selection comes from
 * `<option selected>`, a textarea's value is its child text), any `on*`
 * handler prop (rejected at runtime — use `delegate()`), and the declarative
 * shadow DOM attributes on `<template>` (`shadowrootmode` and its
 * `shadowrootdelegatesfocus` / `shadowrootclonable` companions): the fragment
 * parsing behind `innerHTML` — kerf's entire client render path — never
 * instantiates declarative shadow roots (only the document parser and
 * `setHTMLUnsafe` do), so through `mount()` the template would sit inert in
 * the DOM instead of becoming a shadow root. Declaration-merge them if you
 * emit full-document SSR strings, where the document parser does honor them.
 *
 * Attributes outside the Living Standard stay out even when browsers ship
 * them: `<video disablepictureinpicture / disableremoteplayback>` live in
 * separate W3C specs and only appear in video-player code, `<iframe
 * credentialless>` is engine-specific (in the standard only as a COEP value,
 * not an iframe attribute), and `<iframe allowpaymentrequest>` was removed
 * from the standard outright. Declaration merging is the path for all of
 * them.
 */

/**
 * Every kerf attribute value resolves to one of these. A `ReadonlySignal`
 * (covariant — accepts both `signal()` and `computed()` of any T) is a
 * KF-294 fine-grained attribute binding: handed a signal, the runtime updates
 * that attribute directly on change instead of re-running the render.
 */
type AttrValue = string | number | boolean | null | undefined | SafeHtml | ReadonlySignal<unknown>;
/** A typed-narrowing helper: `AttrLike<'a'|'b'>` accepts the literals plus the runtime fall-throughs. */
type AttrLike<T = string> = T | SafeHtml | null | undefined | ReadonlySignal<unknown>;
/**
 * An HTML **enumerated** attribute whose keywords are the literal strings
 * `"true"` / `"false"` — NOT a boolean attribute.
 *
 * This is the shape that has to be got right more than any other in this file,
 * because getting it wrong is silent: omitting the attribute selects a third
 * state (inherit, or auto), so `boolean` would render markup meaning something
 * other than what was written. `draggable`, `spellcheck`, `contenteditable`,
 * `translate`, `autocorrect`, and `writingsuggestions` are all this shape, and
 * each was typed as a boolean at some point before being corrected.
 *
 * Naming it makes the classification greppable — `EnumeratedBool` answers
 * "which attributes are in this family?" in one command, which is a question
 * the docs repeatedly got wrong while it was six separate inline unions.
 *
 * The per-attribute JSDoc stays at the attribute: this alias says *what shape
 * it is*, the attribute says *what omitting it means for that attribute*.
 */
type EnumeratedBool = AttrLike<'true' | 'false'>;
/**
 * `contenteditable`'s value set — the enumerated-bool keywords plus
 * `plaintext-only`, and `inherit`, which is NOT a spec keyword (it reaches the
 * inherit state only via the invalid-value default; kept for React parity).
 */
type ContentEditableValue = AttrLike<'true' | 'false' | 'inherit' | 'plaintext-only'>;
/** Resource-loading priority hint: `<img>` / `<link>` / `<script>`. */
type FetchPriority = AttrLike<'high' | 'low' | 'auto'>;
/**
 * The `blocking` token list. `render` is the only token the standard defines
 * today — a union rather than a plain string so a typo fails to compile, and a
 * one-line edit when the set grows.
 */
type BlockingToken = AttrLike<'render'>;
/** Lazy-loading behavior: `<img>` / `<iframe>`. */
type LoadingBehavior = AttrLike<'eager' | 'lazy'>;
/** Form submission method, on `<form method>` and the `form*` overrides. */
type FormMethod = AttrLike<'get' | 'post' | 'dialog'>;
/** What a popover invoker does to its target: `<button>` / `<input>`. */
type PopoverTargetAction = AttrLike<'toggle' | 'show' | 'hide'>;
/**
 * `data-*` and `aria-*` index signatures. Applied via `KerfBaseAttrs` so
 * every typed element accepts them without per-element enumeration.
 */
interface DataAriaAttrs {
    [k: `data-${string}`]: AttrValue;
    [k: `aria-${string}`]: AttrValue;
}
/** Attributes valid on essentially every HTML element. */
interface KerfBaseAttrs extends DataAriaAttrs {
    id?: AttrLike;
    className?: AttrLike;
    /**
     * KF-191 — lowercase HTML form accepted alongside `className`. The
     * migration doc (`docs/10-migrating.md` / the published React-migration
     * page) tells incoming developers to write `class` because that's the
     * canonical HTML attribute name; the type system now accepts either
     * spelling so `<div class="...">` per the docs compiles cleanly.
     */
    class?: AttrLike;
    style?: AttrLike;
    title?: AttrLike;
    lang?: AttrLike;
    dir?: AttrLike<'ltr' | 'rtl' | 'auto'>;
    /**
     * A genuine HTML boolean attribute, so `hidden={true}` → ` hidden` is
     * correct. `'until-found'` is the one non-boolean keyword: the element is
     * hidden but still findable by find-in-page and fragment navigation, which
     * reveals it.
     */
    hidden?: AttrLike<boolean | 'until-found'>;
    /**
     * Enumerated, NOT boolean — write `draggable="true"` / `draggable="false"`.
     * `boolean` is rejected because both directions would render the wrong
     * state: `{true}` emits an empty value (invalid → the **auto** state, which
     * for most elements means *not* draggable) and `{false}` omits the attribute
     * (auto again — and auto for `<img>` / `<a href>` is *draggable*). Omit the
     * attribute to mean auto. See the enumerated-attribute rule in this file's
     * header.
     */
    draggable?: EnumeratedBool;
    /**
     * Enumerated, NOT boolean — write `contentEditable="true"` / `="false"`.
     * `contentEditable={false}` would omit the attribute, which means *inherit*,
     * not false — so a child of an editable region would stay editable.
     *
     * `'inherit'` is not a spec keyword; it reaches the inherit state only
     * through the invalid-value default. Accepted for React parity, but omitting
     * the attribute is the spec-correct way to inherit.
     */
    contentEditable?: ContentEditableValue;
    /**
     * KF-191 — lowercase HTML form accepted alongside `contentEditable` (same
     * shape as `class` / `tabindex` / `autofocus` / `spellcheck`), with the same
     * enumerated value set.
     */
    contenteditable?: ContentEditableValue;
    inputMode?: AttrLike<'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search'>;
    /**
     * Enumerated, NOT boolean — write `spellCheck="false"` to turn spellchecking
     * off. `spellCheck={false}` would omit the attribute, which means *inherit
     * the default*, not off; the disable would silently never happen.
     */
    spellCheck?: EnumeratedBool;
    /** KF-183 — lowercase HTML form accepted alongside `spellCheck`. */
    spellcheck?: EnumeratedBool;
    tabIndex?: AttrLike<number>;
    /**
     * KF-191 — lowercase HTML form accepted alongside `tabIndex`. Widened to
     * also accept strings because the HTML spec defines `tabindex` as a
     * string-valued integer attribute, and an HTML-savvy developer typing
     * the lowercase form will naturally reach for `tabindex="0"`.
     */
    tabindex?: AttrLike<number | string>;
    role?: AttrLike;
    slot?: AttrLike;
    is?: AttrLike;
    autoCapitalize?: AttrLike<'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'>;
    autoFocus?: AttrLike<boolean>;
    /**
     * KF-191 — lowercase HTML form accepted alongside `autoFocus`.
     *
     * A real boolean attribute, so only `boolean` is accepted. The string forms
     * are deliberately NOT allowed: `autofocus="false"` is *present*, and a
     * present boolean attribute is true regardless of its value — the spelling
     * that reads like "off" turns autofocus **on**. Use `{false}` or omit it.
     */
    autofocus?: AttrLike<boolean>;
    accessKey?: AttrLike;
    /**
     * A genuine HTML boolean attribute (the subtree becomes non-interactive and
     * invisible to assistive tech), so `inert={true}` → ` inert` is correct.
     */
    inert?: AttrLike<boolean>;
    /**
     * Enumerated: `auto` / `hint` / `manual` — but the boolean forms are ALSO
     * accepted, because both land on spec states, unlike `draggable`:
     * `popover={true}` renders the bare attribute, whose empty value is a spec
     * keyword for the **auto** state (`<div popover>` is the canonical
     * spelling), and `popover={false}` omits it — the not-a-popover state.
     */
    popover?: AttrLike<'auto' | 'hint' | 'manual' | boolean>;
    /** CSP nonce. A global attribute — most useful on `<script>` / `<style>` / `<link>`. */
    nonce?: AttrLike;
    /** Shadow-DOM part name(s) this element exposes for `::part()` styling. */
    part?: AttrLike;
    /** All-lowercase in HTML (`exportparts`) — there is no camelCase form to alias. */
    exportparts?: AttrLike;
    enterKeyHint?: AttrLike<'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'>;
    /**
     * Enumerated, NOT boolean — write `translate="yes"` / `translate="no"`.
     * `translate={false}` would omit the attribute, which means *inherit*, not
     * "no" — the opt-out would silently never happen. (The keywords are
     * `yes` / `no`, not `true` / `false`.) See the enumerated-attribute rule in
     * this file's header.
     */
    translate?: AttrLike<'yes' | 'no'>;
    /**
     * Enumerated, NOT boolean — write `autocorrect="on"` / `autocorrect="off"`.
     * `autocorrect={false}` would omit the attribute, which means *inherit the
     * default* (on, for most editable elements), not off.
     */
    autocorrect?: AttrLike<'on' | 'off'>;
    /**
     * Enumerated, NOT boolean — write `writingsuggestions="false"` to turn the
     * browser's writing suggestions off. `writingsuggestions={false}` would omit
     * the attribute, which means *inherit the default* (on, ultimately), not
     * off — the same trap as `spellcheck`. Keywords are `true` / `false`.
     * All-lowercase in HTML — there is no camelCase form to alias.
     */
    writingsuggestions?: EnumeratedBool;
    /** A genuine HTML boolean attribute: presence declares the item. */
    itemScope?: AttrLike<boolean>;
    itemProp?: AttrLike;
    itemType?: AttrLike;
    itemId?: AttrLike;
    itemRef?: AttrLike;
    /** `data-morph-skip` opts a subtree out of kerf's morph. Any value (incl. `true`) is treated as set. */
    'data-morph-skip'?: AttrValue;
    /** `data-morph-skip-children` (KF-152) — morph the element's attributes but leave its children verbatim. For client-hydrated slots whose loading/state classes still need to flow through. Any value (incl. `true`) is treated as set. */
    'data-morph-skip-children'?: AttrValue;
    /** `data-morph-preserve` (KF-151) — an unmatched live element with this attribute is skipped by kerf's morph trailing-removal pass instead of removed. For imperatively-injected nodes (autoplay videos, tour overlays, analytics pixels) whose lifetime the consumer manages outside kerf. Does NOT block a keyed-match move; this is strictly an end-of-list-discard opt-out. Any value (incl. `true`) is treated as set. */
    'data-morph-preserve'?: AttrValue;
    children?: unknown;
}
/** Element-specific attribute interfaces. Each extends `KerfBaseAttrs`. */
interface HTMLAnchorAttrs extends KerfBaseAttrs {
    href?: AttrLike;
    target?: AttrLike<'_self' | '_blank' | '_parent' | '_top'>;
    rel?: AttrLike;
    /**
     * Presence-or-value (see the third shape in this file's header):
     * `download={true}` renders the bare attribute — download the resource and
     * let the server's `Content-Disposition` / the URL decide the filename —
     * while a string overrides the filename. `download={false}` omits it, which
     * is ordinary navigation. All three are real states, so both forms are typed.
     */
    download?: AttrLike<boolean | string>;
    hrefLang?: AttrLike;
    ping?: AttrLike;
    referrerPolicy?: AttrLike;
    type?: AttrLike;
}
interface HTMLAreaAttrs extends KerfBaseAttrs {
    alt?: AttrLike;
    coords?: AttrLike;
    shape?: AttrLike<'rect' | 'circle' | 'poly' | 'default'>;
    href?: AttrLike;
    target?: AttrLike;
    rel?: AttrLike;
    /** Presence-or-value, same as `<a download>` — see that attribute's note. */
    download?: AttrLike<boolean | string>;
    ping?: AttrLike;
    referrerPolicy?: AttrLike;
}
interface HTMLImgAttrs extends KerfBaseAttrs {
    src?: AttrLike;
    alt?: AttrLike;
    width?: AttrLike<number | string>;
    height?: AttrLike<number | string>;
    srcSet?: AttrLike;
    sizes?: AttrLike;
    loading?: LoadingBehavior;
    decoding?: AttrLike<'sync' | 'async' | 'auto'>;
    crossOrigin?: AttrLike<'anonymous' | 'use-credentials' | ''>;
    referrerPolicy?: AttrLike;
    useMap?: AttrLike;
    fetchPriority?: FetchPriority;
    /** A genuine HTML boolean attribute: inside `<a href>`, clicks send the click coordinates to the server. */
    isMap?: AttrLike<boolean>;
}
interface HTMLInputAttrs extends KerfBaseAttrs {
    type?: AttrLike<'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'datetime-local' | 'time' | 'month' | 'week' | 'color' | 'checkbox' | 'radio' | 'file' | 'hidden' | 'submit' | 'reset' | 'button' | 'image' | 'range'>;
    name?: AttrLike;
    value?: AttrLike;
    defaultValue?: AttrLike;
    placeholder?: AttrLike;
    required?: AttrLike<boolean>;
    disabled?: AttrLike<boolean>;
    readOnly?: AttrLike<boolean>;
    checked?: AttrLike<boolean>;
    defaultChecked?: AttrLike<boolean>;
    multiple?: AttrLike<boolean>;
    pattern?: AttrLike;
    min?: AttrLike<number | string>;
    max?: AttrLike<number | string>;
    step?: AttrLike<number | string>;
    minLength?: AttrLike<number>;
    maxLength?: AttrLike<number>;
    size?: AttrLike<number>;
    autoComplete?: AttrLike;
    /** KF-183 — lowercase HTML form accepted alongside `autoComplete`. */
    autocomplete?: AttrLike;
    form?: AttrLike;
    formAction?: AttrLike;
    formMethod?: FormMethod;
    formTarget?: AttrLike;
    formEncType?: AttrLike;
    formNoValidate?: AttrLike<boolean>;
    list?: AttrLike;
    src?: AttrLike;
    alt?: AttrLike;
    width?: AttrLike<number | string>;
    height?: AttrLike<number | string>;
    accept?: AttrLike;
    capture?: AttrLike<boolean | 'user' | 'environment'>;
    /** Submits the field's text direction alongside its value, under this name. */
    dirName?: AttrLike;
    /**
     * Popover invokers apply to button-state `<input>`s (`type="button"` /
     * `"submit"` / `"reset"` / `"image"`) exactly as they do to `<button>` —
     * the standard lists both elements.
     */
    popoverTarget?: AttrLike;
    popoverTargetAction?: PopoverTargetAction;
}
interface HTMLButtonAttrs extends KerfBaseAttrs {
    type?: AttrLike<'button' | 'submit' | 'reset'>;
    name?: AttrLike;
    value?: AttrLike;
    disabled?: AttrLike<boolean>;
    form?: AttrLike;
    formAction?: AttrLike;
    formMethod?: AttrLike;
    formTarget?: AttrLike;
    formEncType?: AttrLike;
    formNoValidate?: AttrLike<boolean>;
    popoverTarget?: AttrLike;
    popoverTargetAction?: PopoverTargetAction;
    /**
     * Invoker Commands: a spec keyword — `show-modal` / `close` / `request-close`
     * for a `<dialog>` target, `toggle-popover` / `show-popover` / `hide-popover`
     * for a popover target — or a custom command, which the spec requires to
     * start with `--`.
     *
     * **This union is a snapshot of a moving target.** The keyword set is still
     * being extended (menu elements and `interestfor` are open in the HTML
     * standard's invoker pipeline; `show-picker`, media, and fullscreen commands
     * are staged behind them), so a keyword can ship in browsers before it is
     * listed here. When that happens the compile error is kerf being out of
     * date, not your markup being wrong — please file an issue so the union can
     * be updated.
     *
     * Two ways through in the meantime, in preference order: use the custom
     * `--*` form if the behavior is yours to define, or assert the value
     * (`command={'show-picker' as never}`) at the one call site. The custom-command
     * arm below is part of the design, not a workaround.
     */
    command?: AttrLike<'show-modal' | 'close' | 'request-close' | 'toggle-popover' | 'show-popover' | 'hide-popover' | `--${string}`>;
    commandFor?: AttrLike;
}
interface HTMLFormAttrs extends KerfBaseAttrs {
    action?: AttrLike;
    method?: FormMethod;
    encType?: AttrLike;
    target?: AttrLike;
    name?: AttrLike;
    noValidate?: AttrLike<boolean>;
    /** Link types for the form's submission navigation — `noopener` / `noreferrer` / `opener`, the pairing `target` warrants. */
    rel?: AttrLike;
    acceptCharset?: AttrLike;
    autoComplete?: AttrLike;
    /** KF-183 — lowercase HTML form accepted alongside `autoComplete`. */
    autocomplete?: AttrLike;
}
interface HTMLLabelAttrs extends KerfBaseAttrs {
    htmlFor?: AttrLike;
    /** KF-191 — lowercase HTML form accepted alongside `htmlFor`. */
    for?: AttrLike;
    form?: AttrLike;
}
interface HTMLOptionAttrs extends KerfBaseAttrs {
    value?: AttrLike;
    selected?: AttrLike<boolean>;
    defaultSelected?: AttrLike<boolean>;
    disabled?: AttrLike<boolean>;
    label?: AttrLike;
}
interface HTMLOptgroupAttrs extends KerfBaseAttrs {
    label?: AttrLike;
    disabled?: AttrLike<boolean>;
}
/**
 * No `value` / `defaultValue`: `<select>` has no `value` content attribute, so
 * rendering one is inert markup. The selection is expressed on the options —
 * `<option value="b" selected>` — which is also the form kerf's morph keeps in
 * sync with the live `selected` property after the user has picked.
 */
interface HTMLSelectAttrs extends KerfBaseAttrs {
    name?: AttrLike;
    multiple?: AttrLike<boolean>;
    required?: AttrLike<boolean>;
    disabled?: AttrLike<boolean>;
    size?: AttrLike<number>;
    form?: AttrLike;
    autoComplete?: AttrLike;
    /** KF-183 — lowercase HTML form accepted alongside `autoComplete`. */
    autocomplete?: AttrLike;
}
/**
 * No `value` / `defaultValue`: a `<textarea>`'s value is its child text, and
 * there is no `value` content attribute to render. Write the text as a child —
 * `<textarea>{draft}