kerfjs 3.0.0-beta.1 → 4.0.0

package/dist/jsx-runtime.d.ts

@@ -33,6 +33,124 @@ import { B as Binding } from './bindings-CYwoJpQb.js';
  * undefined / `SafeHtml`. Event-handler props (`onClick` etc.) are
  * deliberately omitted: kerf renders to strings, so inline handlers do
  * nothing. Use `delegate()` / `delegateCapture()` instead.
+ *
+ * ---
+ *
+ * ## Provenance — where these types come from
+ *
+ * Attribute names, value sets, and per-element membership are taken from the
+ * **WHATWG HTML Living Standard** (and **SVG 2** for the SVG interfaces), with
+ * MDN used only as a readable index into them. They are NOT derived from
+ * `@types/react`, `lib.dom.d.ts`, or any other framework's table — those model
+ * a *property* surface (`HTMLElement.draggable: boolean`), and kerf emits
+ * *content attributes* into an HTML string, which is a different contract in
+ * exactly the places that bite (see the enumerated-attribute rule below).
+ *
+ * Coverage is deliberately focused rather than exhaustive: the ~100 most-used
+ * elements and their commonly-authored attributes. A missing attribute is a
+ * gap to fill, not a statement that it's invalid — extend via declaration
+ * merging (above) until it lands here.
+ *
+ * ## The rule that governs every value type
+ *
+ * `boolean` in an attribute type means **HTML boolean attribute** — one whose
+ * *presence* is the whole signal. `foo={true}` renders ` foo` and `foo={false}`
+ * renders nothing, so only attributes with those exact semantics may accept a
+ * boolean.
+ *
+ * HTML's **enumerated** attributes look boolean but are not: they take the
+ * literal *strings* `"true"` / `"false"`, and their missing-value default is a
+ * third state. Typing one as `boolean` produces markup that silently means the
+ * opposite of what was written:
+ *
+ *   - `draggable={true}` → `<div draggable>` → empty value is invalid for
+ *     `draggable`, so the element falls to the **auto** state — which for a
+ *     `<div>` means **not draggable**. The attribute that was supposed to turn
+ *     dragging on turns nothing on.
+ *   - `draggable={false}` → attribute omitted → **auto** again, and auto for
+ *     `<img>` / `<a href>` 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<unknown>`, 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
+ * `<input type="file">` 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.
+ *   - **`<meta property>`** is Open Graph vocabulary, not an attribute in the
+ *     HTML standard. Typed anyway because it is universal in real documents —
+ *     every social-preview `<head>` carries `og:*` meta tags.
+ *
+ * Attributes that are *not* typed because they do nothing when rendered as
+ * markup: `value` / `defaultValue` on `<select>` and `<textarea>` (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.
  */
 
 /**
@@ -44,6 +162,45 @@ import { B as Binding } from './bindings-CYwoJpQb.js';
 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.
@@ -68,26 +225,48 @@ interface KerfBaseAttrs extends DataAriaAttrs {
     title?: AttrLike;
     lang?: AttrLike;
     dir?: AttrLike<'ltr' | 'rtl' | 'auto'>;
-    hidden?: AttrLike<boolean>;
-    draggable?: AttrLike<boolean>;
-    contentEditable?: AttrLike<boolean | 'true' | 'false' | 'inherit' | 'plaintext-only'>;
     /**
-     * Lowercase HTML form accepted alongside `contentEditable` (same shape as
-     * `class` / `tabindex` / `autofocus` / `spellcheck`). The HTML spec defines
-     * `contenteditable` as a string-valued enumerated attribute; an HTML-savvy
-     * developer typing the lowercase form will reach for `contenteditable="false"`.
+     * 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.
      */
-    contenteditable?: AttrLike<boolean | 'true' | 'false' | 'inherit' | 'plaintext-only'>;
+    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'>;
-    spellCheck?: AttrLike<boolean>;
     /**
-     * KF-183 — lowercase HTML form accepted alongside `spellCheck`. Widened
-     * to also accept the literal string values `'true'` / `'false'` because
-     * the HTML spec defines `spellcheck` as a string-valued enumerated
-     * attribute, and an HTML-savvy developer typing the lowercase form
-     * will naturally reach for `spellcheck="false"`.
+     * 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?: AttrLike<boolean | 'true' | 'false'>;
+    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
@@ -102,14 +281,63 @@ interface KerfBaseAttrs extends DataAriaAttrs {
     autoCapitalize?: AttrLike<'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'>;
     autoFocus?: AttrLike<boolean>;
     /**
-     * KF-191 — lowercase HTML form accepted alongside `autoFocus`. Widened
-     * to also accept `'true'` / `'false'` strings (same rationale as KF-183
-     * for `spellcheck` — HTML boolean-attribute parsing allows the string
-     * forms, and the canonical HTML attribute name lets developers reach
-     * for either spelling).
+     * 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 | 'true' | 'false'>;
+    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. */
@@ -123,7 +351,14 @@ interface HTMLAnchorAttrs extends KerfBaseAttrs {
     href?: AttrLike;
     target?: AttrLike<'_self' | '_blank' | '_parent' | '_top'>;
     rel?: AttrLike;
-    download?: 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;
@@ -136,6 +371,10 @@ interface HTMLAreaAttrs extends KerfBaseAttrs {
     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;
@@ -144,12 +383,14 @@ interface HTMLImgAttrs extends KerfBaseAttrs {
     height?: AttrLike<number | string>;
     srcSet?: AttrLike;
     sizes?: AttrLike;
-    loading?: AttrLike<'eager' | 'lazy'>;
+    loading?: LoadingBehavior;
     decoding?: AttrLike<'sync' | 'async' | 'auto'>;
     crossOrigin?: AttrLike<'anonymous' | 'use-credentials' | ''>;
     referrerPolicy?: AttrLike;
     useMap?: AttrLike;
-    fetchPriority?: AttrLike<'high' | 'low' | 'auto'>;
+    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'>;
@@ -175,7 +416,7 @@ interface HTMLInputAttrs extends KerfBaseAttrs {
     autocomplete?: AttrLike;
     form?: AttrLike;
     formAction?: AttrLike;
-    formMethod?: AttrLike<'get' | 'post' | 'dialog'>;
+    formMethod?: FormMethod;
     formTarget?: AttrLike;
     formEncType?: AttrLike;
     formNoValidate?: AttrLike<boolean>;
@@ -186,6 +427,15 @@ interface HTMLInputAttrs extends KerfBaseAttrs {
     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'>;
@@ -198,14 +448,39 @@ interface HTMLButtonAttrs extends KerfBaseAttrs {
     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?: AttrLike<'get' | 'post' | 'dialog'>;
+    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`. */
@@ -228,10 +503,14 @@ 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;
-    value?: AttrLike;
-    defaultValue?: AttrLike;
     multiple?: AttrLike<boolean>;
     required?: AttrLike<boolean>;
     disabled?: AttrLike<boolean>;
@@ -241,10 +520,13 @@ interface HTMLSelectAttrs extends KerfBaseAttrs {
     /** 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}</textarea>` — which is what kerf's morph reconciles.
+ */
 interface HTMLTextareaAttrs extends KerfBaseAttrs {
     name?: AttrLike;
-    value?: AttrLike;
-    defaultValue?: AttrLike;
     placeholder?: AttrLike;
     rows?: AttrLike<number>;
     cols?: AttrLike<number>;
@@ -254,13 +536,17 @@ interface HTMLTextareaAttrs extends KerfBaseAttrs {
     maxLength?: AttrLike<number>;
     minLength?: AttrLike<number>;
     wrap?: AttrLike<'hard' | 'soft' | 'off'>;
+    /** Submits the field's text direction alongside its value, under this name. */
+    dirName?: AttrLike;
     autoComplete?: AttrLike;
     /** KF-183 — lowercase HTML form accepted alongside `autoComplete`. */
     autocomplete?: AttrLike;
     form?: AttrLike;
 }
 interface HTMLTableAttrs extends KerfBaseAttrs {
+    /** @deprecated Obsolete presentational attribute — use CSS `padding` on the cells. Typed so legacy markup still compiles. */
     cellPadding?: AttrLike<number | string>;
+    /** @deprecated Obsolete presentational attribute — use CSS `border-spacing`. Typed so legacy markup still compiles. */
     cellSpacing?: AttrLike<number | string>;
 }
 interface HTMLTableCellAttrs extends KerfBaseAttrs {
@@ -278,6 +564,13 @@ interface HTMLMetaAttrs extends KerfBaseAttrs {
     content?: AttrLike;
     charSet?: AttrLike;
     httpEquiv?: AttrLike;
+    media?: AttrLike;
+    /**
+     * Open Graph (`og:title` etc.) — NOT in the HTML standard, typed because it
+     * is universal in real documents. See the deviations list in this file's
+     * header.
+     */
+    property?: AttrLike;
 }
 interface HTMLLinkAttrs extends KerfBaseAttrs {
     href?: AttrLike;
@@ -290,7 +583,13 @@ interface HTMLLinkAttrs extends KerfBaseAttrs {
     crossOrigin?: AttrLike;
     integrity?: AttrLike;
     referrerPolicy?: AttrLike;
-    fetchPriority?: AttrLike<'high' | 'low' | 'auto'>;
+    fetchPriority?: FetchPriority;
+    /** A genuine HTML boolean attribute on `<link>`: the stylesheet is not applied (and for a stylesheet link, not fetched) until it's removed. */
+    disabled?: AttrLike<boolean>;
+    /** For `rel="preload" as="image"`: the srcset the preload should match. */
+    imageSrcSet?: AttrLike;
+    imageSizes?: AttrLike;
+    blocking?: BlockingToken;
 }
 interface HTMLScriptAttrs extends KerfBaseAttrs {
     src?: AttrLike;
@@ -301,12 +600,14 @@ interface HTMLScriptAttrs extends KerfBaseAttrs {
     integrity?: AttrLike;
     crossOrigin?: AttrLike;
     referrerPolicy?: AttrLike;
-    nonce?: AttrLike;
+    blocking?: BlockingToken;
+    fetchPriority?: FetchPriority;
 }
+/** No `scoped`: the proposal was removed from the HTML standard and never shipped in any engine. */
 interface HTMLStyleAttrs extends KerfBaseAttrs {
     type?: AttrLike;
     media?: AttrLike;
-    scoped?: AttrLike<boolean>;
+    blocking?: BlockingToken;
 }
 interface HTMLIframeAttrs extends KerfBaseAttrs {
     src?: AttrLike;
@@ -317,7 +618,7 @@ interface HTMLIframeAttrs extends KerfBaseAttrs {
     allowFullScreen?: AttrLike<boolean>;
     width?: AttrLike<number | string>;
     height?: AttrLike<number | string>;
-    loading?: AttrLike<'eager' | 'lazy'>;
+    loading?: LoadingBehavior;
     referrerPolicy?: AttrLike;
 }
 interface HTMLMediaAttrs extends KerfBaseAttrs {
@@ -341,6 +642,9 @@ interface HTMLSourceAttrs extends KerfBaseAttrs {
     srcSet?: AttrLike;
     sizes?: AttrLike;
     media?: AttrLike;
+    /** Valid when the parent is `<picture>`: intrinsic dimensions for the candidate image, so layout is stable before selection. */
+    width?: AttrLike<number | string>;
+    height?: AttrLike<number | string>;
 }
 interface HTMLTrackAttrs extends KerfBaseAttrs {
     src?: AttrLike;

package/dist/jsx-runtime.js

@@ -1,4 +1,4 @@
-export { Fragment, SafeHtml, assertEmittableAttrName as _assertEmittableAttrName, _renderAttrVerbatim, _toSegment, granularListSafeHtml, isSafeHtml, jsx, jsx as jsxDEV, jsx as jsxs, listSafeHtml, raw } from './chunk-JVVU2RQO.js';
+export { Fragment, SafeHtml, assertEmittableAttrName as _assertEmittableAttrName, _renderAttrVerbatim, _toSegment, granularListSafeHtml, isSafeHtml, jsx, jsx as jsxDEV, jsx as jsxs, listSafeHtml, raw } from './chunk-JXAR5J54.js';
 import './chunk-GY4XV2UV.js';
 import './chunk-3APBEVHF.js';
 import './chunk-VVDJLWMP.js';

package/llms.txt

@@ -1,6 +1,6 @@
 # kerf
 
-> A tiny (~11 KB minified + gzipped including its one runtime dependency `@preact/signals-core`; ~12 KB with `arraySignal`) reactive UI framework — fine-grained signals + DOM morphing + JSX. No virtual DOM, no compiler. Apply the smallest possible cut to update your DOM.
+> A tiny (~12 KB minified + gzipped including its one runtime dependency `@preact/signals-core`; ~13 KB with `arraySignal`) reactive UI framework — fine-grained signals + DOM morphing + JSX. No virtual DOM, no compiler. Apply the smallest possible cut to update your DOM.
 
 kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "list"/"mixed" segments where `each(...)` was used) and reconciles it against the live tree with a custom segment-aware morph. Static surrounds go through a general-purpose tree-morph; list contents go through a keyed reconciler that operates directly on live children — partial-update on huge lists is O(changes), not O(rows). Reactivity is provided by [@preact/signals-core](https://github.com/preactjs/signals). It pairs well with server-rendered HTML, embedded widgets, and any UI where preserving focus / selection across re-renders matters. Public API is one import: `signal`, `computed`, `effect`, `batch`, `defineStore`, `resetAllStores`, `mount`, `morph`, `each`, `attr`, `delegate`, `delegateCapture`, `toElement`, `SafeHtml`, `isSafeHtml`, `raw`, `Fragment`. (Two more subpaths: `kerfjs/testing` exposes `clearStoreRegistry` for unit-test isolation; `kerfjs/jsx-runtime` exposes the typed JSX building blocks for declaration-merging custom-element types.) An optional subpath at `kerfjs/array-signal` adds `arraySignal()` — a granular keyed-list signal whose patch events let `each()` reconcile in O(patches) instead of O(N). An optional subpath at `kerfjs/dev` installs the development diagnostics — kerf does NOT infer dev mode, so you import it behind your own build's dev flag (`if (import.meta.env.DEV) await import('kerfjs/dev');`); omitting it is production and sheds ~4.7 KB min+gzip. Another optional subpath at `kerfjs/html` adds the `html` tagged template — JSX-identical runtime semantics with no JSX transform, so CDN/importmap projects can author kerf UIs with literally no build step.
 
@@ -30,11 +30,12 @@ kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "
 - [API reference](https://github.com/brianwestphal/kerf/blob/main/docs/8-api-reference.md): every export, every option.
 - [Live demo](https://github.com/brianwestphal/kerf/blob/main/docs/9-live-demo.md): the GitHub Pages deploy of `examples/reactivity-demo`.
 - [Migrating](https://github.com/brianwestphal/kerf/blob/main/docs/10-migrating.md): the `/kerf/migrating/` comparison hub — coming-from-React/Alpine/Lit/vanjs pages with side-by-side todo-list translations.
-- [Dev-mode warnings](https://github.com/brianwestphal/kerf/blob/main/docs/11-dev-warnings.md): the opt-in `KERF_DEV_WARN_*` env-gated dev-warn family (rebuilt listeners, untracked signals, narrow store sets, delegate-in-effect, each-in-morph-skip, duplicate keys, value-only re-renders, stale bindings), how the diagnostics are installed via the `kerfjs/dev` subpath rather than inferred from the environment, and the rules each new warning must follow.
+- [Dev-mode warnings](https://github.com/brianwestphal/kerf/blob/main/docs/11-dev-warnings.md): the opt-in `KERF_DEV_WARN_*` env-gated dev-warn family (rebuilt listeners, untracked signals, narrow store sets, delegate-in-effect, each-in-morph-skip, duplicate keys, value-only re-renders, stale bindings, list rebinds, stale row indices, parser repairs) plus the `KERF_DEV_INVARIANTS` structural checks, how the diagnostics are installed via the `kerfjs/dev` subpath rather than inferred from the environment, and the rules each new warning must follow.
 - [AI-assistant configs](https://github.com/brianwestphal/kerf/blob/main/docs/12-ai-assistant-configs.md): how the drop-in Claude Code skill + Cursor rules ship inside the `kerfjs` npm package at `ai/skill.md` / `ai/cursorrules` / `ai/manifest.json`, the version + marker contract for customization preservation, and the `kerfjs/ai-assistant-configs` ESLint rule that surfaces drift on every lint pass.
 - [Component packages](https://github.com/brianwestphal/kerf/blob/main/docs/13-component-packages.md): building and publishing reusable kerf components as npm packages — the no-instance component model, per-instance state via factories, event/cleanup patterns, and `kerfjs`-as-peer-dependency packaging modeled on `eslint-plugin-kerfjs`. Scaffold one with `npm create kerf-component@latest <dir>` (the `create-kerf-component` initializer).
 - [Feature coverage](https://github.com/brianwestphal/kerf/blob/main/docs/14-feature-coverage.md): the per-behavior coverage axis orthogonal to line coverage — an index mapping each behavior (especially list-reconciler *state transitions*) to its guarding test, enforced by `npm run check:features`.
 - [No-build example](https://github.com/brianwestphal/kerf/blob/main/docs/15-no-build-example.md): the served-as-source `live-poll` example app — plain JS + importmap + the `html` tagged template, zero tooling — and the vendor-copy contract that ships it.
+- [List identity](https://github.com/brianwestphal/kerf/blob/main/docs/16-list-identity.md): why an `each()` list's call-order identity is not stable, what the source guard fixes and what it doesn't, the five constraints any scheme must survive, and the explicit-key recommendation now shipped as `each(items, render, { key })`.
 
 ## Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kerfjs",
-  "version": "3.0.0-beta.1",
+  "version": "4.0.0",
   "description": "Tiny reactive UI framework — fine-grained signals + DOM morphing + JSX. Apply the smallest possible cut to update your DOM.",
   "type": "module",
   "sideEffects": [
@@ -91,7 +91,7 @@
     "bench:serve": "bash bench/site.sh",
     "lint": "eslint src tests",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
-    "check": "npm run lint && npm run typecheck && node scripts/check-doc-test-inventory.mjs && node scripts/check-doc-api-coverage.mjs && node scripts/check-doc-site-tickets.mjs && node scripts/check-feature-coverage.mjs && node scripts/check-ai-bundle.mjs && npm test && npm run build && node scripts/check-bundle-size.mjs && node scripts/check-doc-api-signatures.mjs && vitest run --config vitest.config.dist.ts && vitest run --config vitest.config.dist-full.ts && node node_modules/typescript7/bin/tsc -p tests/dist/jsx-typing/tsconfig.json && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json && node scripts/check-docs-examples.mjs",
+    "check": "npm run lint && npm run typecheck && node scripts/check-doc-test-inventory.mjs && node scripts/check-doc-api-coverage.mjs && node scripts/check-doc-site-tickets.mjs && node scripts/check-dev-warn-docs.mjs && node scripts/check-skill-freshness.mjs && node scripts/check-design-rule-5.mjs && node scripts/check-feature-coverage.mjs && node scripts/check-ai-bundle.mjs && npm test && npm run build && node scripts/check-bundle-size.mjs && node scripts/check-doc-api-signatures.mjs && vitest run --config vitest.config.dist.ts && vitest run --config vitest.config.dist-full.ts && node node_modules/typescript7/bin/tsc -p tests/dist/jsx-typing/tsconfig.json && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json && node scripts/check-docs-examples.mjs",
     "check:docs:examples": "node scripts/check-docs-examples.mjs",
     "check:full": "npm run check && playwright test",
     "check:docs:test-inventory": "node scripts/check-doc-test-inventory.mjs",
@@ -113,7 +113,10 @@
     "site:dev": "cd site && npm install && npm run dev",
     "site:dev:hmr": "cd site && npm install && npm run dev:hmr",
     "site:build": "cd site && npm install && npm run build",
-    "check:bundle-size": "npm run build && node scripts/check-bundle-size.mjs"
+    "check:bundle-size": "npm run build && node scripts/check-bundle-size.mjs",
+    "check:skills": "node scripts/check-skill-freshness.mjs",
+    "check:design-rule-5": "node scripts/check-design-rule-5.mjs",
+    "check:docs:dev-warns": "node scripts/check-dev-warn-docs.mjs"
   },
   "dependencies": {
     "@preact/signals-core": "^1.14.1"
@@ -137,5 +140,16 @@
     "typescript": "^6.0.3",
     "typescript7": "npm:typescript@^7.0.2",
     "vitest": "^3.0.0"
+  },
+  "gitgist": {
+    "exclude": [
+      "site/public/demos/*.svg",
+      "site/src/content/docs/docs/*",
+      "site/src/content/docs/api.md",
+      "ai/*",
+      "site/public/llms.txt",
+      "bench/results.json",
+      "bench/results.md"
+    ]
   }
 }