kerfjs 5.0.0-beta.52 → 5.0.0-beta.53

package/CHANGELOG.md

@@ -6,6 +6,335 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- `@kerfjs/ui` elevation shadows follow the color scheme, with or without the
+  optional `@kerfjs/ui/webawesome.css` theme. Kerf's theme layer set
+  `--wa-shadow-s` / `-m` / `-l` to fixed light-mode shadows (14%, 11%, and 9%
+  black), which all but vanished against the dark page, and the
+  `--kui-shadow-s` / `--kui-shadow-l` foundation fallbacks copied those fixed
+  values. The theme now pairs each light alpha with a stronger dark one (50%,
+  40%, 32%) through `light-dark()`, and the foundation fallbacks mirror them, so
+  selected segments and app tabs, compact overlay panels, and Web Awesome
+  surfaces that read `--wa-shadow-*` keep their elevation in dark mode. Light mode is unchanged. The browser parity test
+  now compares every `--kui-shadow-*` token with and without the theme in both
+  schemes.
+- `@kerfjs/ui` text on loud tone fills clears WCAG AA in both color schemes,
+  with or without the optional `@kerfjs/ui/webawesome.css` theme. White
+  `on-loud` text reached about 2.2:1 on the success fill, 3.5:1 on the light
+  brand fill (`#0088ff`), and 3.6:1 on the danger fill (`#ff383c`) in both
+  schemes. Kerf's theme layer and the foundation fallbacks now pair each
+  fill with a foreground chosen to keep the tone's look: success keeps its
+  bright green with dark text (`#1d1d1f`, 7.6:1), as warning already did; light
+  brand and danger keep white text on a slightly deeper fill of the same hue
+  (`#0075db`, 4.6:1; `#eb0005`, 4.6:1); dark danger keeps its fill with dark
+  text (`#111113`, 5.3:1), as dark brand already did. Web Awesome accent
+  buttons, badges, and checked controls pick this up, and accent `wa-badge`s now
+  use their variant's `on-loud` foreground by default instead of a fixed dark
+  color (`--kui-wa-badge-accent-foreground` still overrides it). The browser
+  contrast test asserts every tone's `on-loud` over `fill-loud` pair, including
+  pop and neutral, in both schemes with and without the theme.
+- `@kerfjs/ui` brand, success, and warning text clears WCAG AA on the lowered
+  page background in light mode, with or without the optional
+  `@kerfjs/ui/webawesome.css` theme. Their light `on-quiet` values (`#1e6ef4`,
+  `#008932`, `#a16a00`) passed on the white surface but reached only about
+  4.1:1 on `#f2f2f7`. Kerf's theme layer and the foundation fallbacks now use
+  the same hues a step darker: `#0c62f3` (4.64:1), `#007f2e` (4.62:1), and
+  `#966200` (4.65:1) on the page, about 5.2:1 on white. Links, selected tabs,
+  segmented and toolbar selections, and token-search accents that read
+  `brand-on-quiet` darken with it. Dark mode is unchanged. The browser contrast
+  test no longer skips light text over the page background.
+- `@kerfjs/ui` surfaces, links, and focus rings match the optional
+  `@kerfjs/ui/webawesome.css` theme without it. Three foundation fallbacks
+  pointed at a different token than the theme: `--kui-color-surface-raised`
+  fell back to the surface color (the theme's dark raised surface is
+  `#2c2c2e`), `--kui-color-text-link` fell back to the brand fill (`#0088ff`,
+  about 3.5:1 on white) instead of the brand on-quiet text color, and the focus
+  ring used the brand fill instead of the theme's focus color (`#007aff`). Each
+  now falls back to the theme's value. The browser parity test now covers every
+  `--kui-color-*` token the foundation declares, plus the focus ring, instead of
+  only the tone tokens.
+- The `@kerfjs/ui` UX catalog's `StateBanner` route adds a placeholder with a
+  badge for every tone, next to the existing badge-less placeholder, so visual
+  review and captures show the solid badge's loading skeleton on each tone's
+  fill. A browser test checks that each tone's badged placeholder is present.
+- `@kerfjs/ui` toned text stays readable in dark mode without the optional
+  `@kerfjs/ui/webawesome.css` theme. The foundation's fallbacks for the
+  success, warning, and danger `on-quiet` and `on-normal` tokens were single
+  light-mode colors, so dark danger `Text` rendered dark red on a dark surface
+  (under 3:1). Every tone token now falls back to the same light and dark
+  pair the theme assigns, including `brand-on-loud` (dark text on the pale dark
+  brand fill instead of white) and `neutral-border-quiet`. Light-mode colors
+  are unchanged. A browser test bundles the package with and without the theme
+  and asserts that every tone token resolves identically in both color schemes
+  and that toned text clears WCAG AA in dark mode.
+- `@kerfjs/ui` danger text and badges are readable in dark mode, and every
+  tone's `StateBanner` detail and quiet or outline `Badge` text now clears
+  WCAG AA. The danger tone was the only one without an on-fill foreground: its
+  solid badge fill and `StateBanner` text reused `danger-on-quiet`, a mid red
+  in dark mode (banner detail 4.0:1, badge placeholder skeleton 2.25:1). A new
+  `--kui-color-danger-on-fill` token (also accepted by `uiColor()`) matches the
+  other tones' pale dark values, lifting the dark danger banner text to 8.2:1.
+  The banner detail no longer dims to 78% opacity, which left the light info,
+  success, warning, and danger details at 3.4 to 4.3:1; it reads as secondary
+  through its smaller type, and the neutral detail uses the quiet text color.
+  Quiet and outline badges use their tone's on-fill text, lifting light brand,
+  success, and warning from about 4.1:1 to at least 5:1.
+
+- A `@kerfjs/ui` placeholder skeleton inside a solid `Badge`, such as the
+  badge of a `StateBanner` placeholder, is now clearly visible. The generic
+  skeleton tint, 12% of the text color, almost disappeared on the badge's
+  saturated fill in every tone. A solid badge now tints its skeleton from its
+  own foreground color, which contrasts with the fill in every tone in light
+  and dark mode. Quiet and outline badges keep the generic tint, which already
+  reads on their pale fills. Geometry is unchanged.
+- The `@kerfjs/ui` SVG design templates render badges as filled pills: the
+  `StateBanner` badge and the `ListHeader` and `List` count pills used to show
+  as plain text, because the template build loaded only a hand-written list of
+  stylesheets that omitted `badge.css`. The build now loads each component's
+  full stylesheet set from its generated browser entry, the same set a
+  consumer's browser import loads, so a nested component's CSS can no longer be
+  missed. The `ListHeader` and `List` templates also pick up the label inset
+  from `text.css`, so a header label now lines up with the list items below it,
+  as it does in the live component.
+- A `@kerfjs/ui` `StateBanner` placeholder's badge sits at the live badge's
+  height on every platform. With a skeleton instead of text, the badge took a
+  baseline from the skeleton's bottom edge and sat about a pixel higher, by an
+  amount that depended on the platform's font metrics.
+- A `@kerfjs/ui` `StateBanner` with a long, wrapping title keeps its badge
+  one item gap after the title's last word, and its detail uses the full copy
+  width. The wide flex layout shrank the title and detail together, which left
+  a large gap before the badge and truncated the detail early. The title,
+  badge, and detail now flow as inline text: the detail stays beside the title
+  while it fits whole, and otherwise moves to its own line, truncating only at
+  the full width. A wrapped title's lines stay evenly spaced.
+- A `@kerfjs/ui` `ListHeader` disclosure toggle disabled with `actionDisabled`
+  is dimmed by the component itself, at the same tone as a disabled action
+  button, and shows the `not-allowed` cursor. It used to rely on Web Awesome's
+  native `button:disabled` dimming, so without `webawesome.css` it looked
+  enabled. Disabled toggles and action buttons also no longer show hover
+  feedback without `webawesome.css`.
+- A `@kerfjs/ui` `ListActionRow` placeholder keeps its `busy` spinner. The
+  whole status line used to collapse into one skeleton, dropping the spinner
+  the component draws from a known prop. Now only the `status` text becomes a
+  skeleton, matching `ListItem`.
+- **A tooltip or popover already showing stays visible when a modal opens.**
+  Lifting a surface above an open modal `<dialog>` was decided only when the
+  surface opened, so a tooltip or popover already on screen when a modal
+  dialog opened was left inert beneath it. Whenever `kerfjs/overlay` opens a
+  modal `<dialog>` (a `native: true` modal, or one it lifted), it now moves
+  every open tooltip and popover into the top layer above the new dialog. One
+  that is already a `[popover]` is re-shown so it stacks on top. The existing
+  `kerfjs/dev` warnings still report an engine without the Popover API, and a
+  surface with controls the modal keeps inert. A modal `<dialog>` the app
+  opens itself, outside kerf, is not observed.
+- Moved `mount()`'s list-binding lifecycle (turning list markers into
+  bindings, first-render row-contract validation, orphan pruning) into its own
+  internal module, so `mount.ts` holds only the render orchestration. No
+  behavior or public API change.
+- A narrow (576px and below) `@kerfjs/ui` `StateBanner` keeps its badge
+  sized to its content, one item gap after the title and on the title's
+  baseline, as in the wide layout. The narrow grid stretched the badge across
+  the free column into a wide pill that sat less than 1px from the title.
+- Hovering a `@kerfjs/ui` `ListActionRow` placeholder with
+  `trailingActionVisibility="interaction"` no longer reveals its disabled
+  trailing button. A placeholder is inert, so it keeps the live row's resting
+  state, with the trailing action hidden until an interaction it cannot take.
+- A `@kerfjs/ui` `ListItem` placeholder keeps its `busy` spinner. The whole
+  trailing slot used to collapse into one skeleton, dropping the spinner the
+  component draws from a known prop and shifting the label's width. Now only
+  the values in that slot become skeletons: `status` text in its status line
+  and author-supplied `trailing` content (always a value, since the component
+  cannot tell a chevron from a count) each get their own.
+- `@kerfjs/ui` placeholders keep the live disabled tone of a control the
+  author disabled. A disabled `ListItem` or `ListActionRow`, a
+  `trailingActionDisabled` button, a disabled `SegmentedControl` choice, or a
+  `ListHeader` with `actionDisabled` rendered at full opacity as a
+  placeholder, because the placeholder reset could not tell its own
+  `disabled` attribute from the author's. Those controls now carry a
+  component-owned `data-kui-disabled="true"` marker whenever their disabled
+  prop is set; the disabled tone keys on it and the placeholder reset skips
+  it. The marker is reserved: the extension-attribute props cannot set it.
+- `@kerfjs/ui` adds a browser test that renders every placeholder-capable
+  component live and as a placeholder from identical props and diffs each
+  element's geometry and computed chrome, so any future drift outside a value
+  slot fails. It caught one more: a `ListActionRow` placeholder's `status`
+  line was 3.5px shorter than the live line; the status line now always
+  keeps a full line height.
+- `@kerfjs/ui`'s `Select` placeholder hint now matches the live hint: 14px
+  text at a 1.6 line height, 7px below the box. It was 12px / 1.4 with a 4px
+  gap, so a placeholder with a `hint` was 8.6px shorter than the loaded
+  control and the content below it jumped when loading finished.
+- `@kerfjs/ui`'s `StateBanner` placeholder adds a detail skeleton only when
+  `detail` is set, matching the live banner. Previously every placeholder
+  showed a detail line, so a banner without one changed shape when loading
+  finished. Pass the banner's real `title` and `detail` with `placeholder`;
+  an empty `detail` now means no detail line.
+- `@kerfjs/ui`'s `AppTab` placeholder pill is no longer dimmed to 50% with a
+  `not-allowed` cursor when `webawesome.css` is loaded; it keeps the live
+  tab's tone, and only its name is a skeleton.
+- `@kerfjs/ui`'s `ListHeader` placeholder no longer dims its action button
+  (48%) or, in `toggle` mode, the whole title and label (Web Awesome's native
+  50%), and its inert action and toggle give no hover feedback. A live
+  `actionDisabled` header still dims its action.
+- `@kerfjs/ui`'s `SegmentedControl` placeholder now keeps its choices. The
+  choices are known; only the selection is unknown, so a placeholder renders
+  every choice's live label or icon at its live size, selects none, and stays
+  inert. Previously every segment became a 4em text skeleton (widening icon
+  segments from 40px to 60px) and was dimmed to 45%.
+- `@kerfjs/ui`'s `ListItem` and `ListActionRow` placeholders now match the
+  live row. They are no longer dimmed (the rows' own `:disabled` tone and
+  hover highlight skip placeholders), and a row with a `description` (or a
+  `ListActionRow` `status`) keeps that line as a second, smaller skeleton, so
+  the row keeps its live height instead of collapsing to one line. The
+  `ListActionRow` icon placeholder is an 18px block centered in its icon slot,
+  like `ListItem`'s.
+- `@kerfjs/ui` placeholders no longer look disabled. A component's
+  `placeholder` keeps its controls `disabled` (inert and out of the keyboard
+  order), but `skeleton.css` now neutralizes generic disabled chrome under
+  `[data-placeholder="true"]`: full opacity and the default cursor instead of
+  Web Awesome's native `button:disabled` dimming to 50% with a `not-allowed`
+  cursor. A component's own opacity (a control hidden until interaction) still
+  applies.
+- `toElement('<image href="…" />')` now returns an SVG `<image>`. The HTML
+  parser rewrites an orphan `<image>` to an HTML `<img>` before kerf sees the
+  tag, so it previously came back as an XHTML `img` that no `<svg>` would
+  render. kerf now recognizes a leading `<image` tag in the raw input
+  (case-insensitive, after leading whitespace) and parses it through the SVG
+  wrapper. A genuine `<img>` is unchanged.
+- `delegateActions()` (`kerfjs/actions`) dispatches only the table's own
+  entries. It used to look the action up with a plain property read, so a
+  `data-action` naming an inherited `Object.prototype` member resolved:
+  `"__proto__"` or `"hasOwnProperty"` threw a `TypeError` from the listener,
+  and `"toString"` or `"constructor"` silently ran the inherited function.
+  Those values are now ignored like any other action absent from the table.
+  An own entry with such a name (`{ toString: … }`) still dispatches.
+- `toElement()` now puts orphan camelCase SVG fragments in the SVG namespace.
+  `toElement('<linearGradient>…</linearGradient>')`, and likewise `clipPath`,
+  `radialGradient`, and `foreignObject`, previously returned an XHTML
+  `LINEARGRADIENT` element that no `<svg>` would render, because the lookup
+  compared the HTML parser's lowercased tag against camelCase names. The
+  fragment is now wrapped in `<svg>` and XML-parsed like `<path>` or `<g>`,
+  and the returned element keeps its camelCase `localName`.
+- **A tooltip or popover no longer outlives its anchor.** When the anchor left
+  the document, most commonly because the modal containing it closed, the
+  `tooltip()` or `popover()` stayed on screen: a removed element fires no
+  `pointerleave` or `blur`. Both now watch their anchor with the same removal
+  tracking as `kerfjs/attach`. The tooltip hides, and the popover closes
+  without calling `onDismiss`, as soon as the anchor leaves the document.
+  Moving the anchor within the document keeps them open. A tooltip show still
+  pending when its anchor is removed never appears.
+- **Overlays opened over a modal `<dialog>` are visible and usable.** A browser
+  makes everything outside an open modal dialog inert and paints a plain
+  element beneath it, so a `tooltip()`, `popover()`, or `confirm()` opened
+  from inside a `native: true` dialog without `native` itself was invisible and
+  could not be used. While a modal `<dialog>` is open, `kerfjs/overlay` now
+  hosts such a surface in the top layer anyway: a tooltip or popover becomes a
+  `[popover]`, and a nested modal becomes its own `<dialog>`. The browser's
+  default `[popover]` / `<dialog>` styles then apply, as they do with `native:
+true`. Browsers keep a popover outside the modal dialog inert even in the top
+  layer, so a lifted popover with buttons is visible but not clickable. A new
+  always-on `kerfjs/dev` warning reports that case, and an engine without the
+  needed API.
+- **A tooltip shown inside a modal no longer disables the modal.** `kerfjs/overlay`
+  used to treat the most recently opened overlay as the only one that could
+  react to input, so a `tooltip()` (which handles no input) inside an open
+  modal left Escape doing nothing and let Tab leave the dialog. Every overlay,
+  native or fallback, now joins one open-order stack, and each Escape, backdrop
+  click, outside click, or trapped Tab goes to the topmost surface that handles
+  it. A modal still blocks everything beneath it, and a surface that handles
+  nothing never intercepts. A popover that dismisses on Escape gets it before
+  the modal beneath. One click that is both outside a popover and on a modal's
+  backdrop now closes only the popover. A native `<dialog>` is arbitrated with
+  the fallback surfaces: one Escape closes one surface, and a fallback modal
+  beneath an open dialog no longer takes the dialog's Tab. Closing a lower
+  overlay first leaves focus in the overlay that holds it. An overlay opened
+  from inside it then restores focus to the closed overlay's opener, not a
+  detached node.
+- `kerfjs` now exports the `EachOptions<T>` type (`{ cacheKey?, key? }`), the
+  options-object form of `each()`'s third argument, so a helper that builds or
+  forwards those options can import the shape instead of restating it:
+  `import { type EachOptions } from "kerfjs"`. Type-only; no runtime or bundle
+  change.
+- Documentation: the companion-utility reference now matches the code. The
+  router's `match()` / `activeClass()` compare a literal path prefix, so
+  `match('/users/:id')` is never true. Link interception still applies to
+  `target="_self"`, the no-match `outlet()` is `null` with `params` `{}`,
+  components receive `(params, route)`, and hash mode keeps `route.hash` at
+  `''`. Invalid `bindList` configuration throws only `RangeError`. `popover()`
+  defaults `className` to `'kerf-popover'`, and the toast region is a reused
+  `.kerf-toasts` element when one exists. A `resource()` `cacheKey` applies
+  only to `run(input, fetcher)`, and throttle's `flush()` leaves the cooldown
+  running. `delegate()` / `delegateCapture()` throw on an invalid selector at
+  registration. The reference also now lists the `kerfjs/jsx-dev-runtime`
+  alias, the `DEV_HOOKS` export of `kerfjs/dev`, and `Signal#peek()`.
+- Documentation: `morph(liveRoot, template)` is now described as it behaves.
+  It reconciles only the root's children and never touches the root's own
+  attributes, so `template` describes the content inside the root (an
+  `Element` template contributes its child nodes). The examples no longer
+  nest a duplicate `<article>` inside the live one. An `each()` list parent is
+  not a children-only short-circuit: the diff still walks it and skips only
+  the owned rows. The user-agent-owned `open` exception covers custom elements
+  as well as `<details>` / `<dialog>`, and a content-only row change inside an
+  `each()` list keeps its DOM node (and focus) unless the row's top-level tag
+  changes or the same render also inserts, removes, or moves rows.
+- Every opt-in `kerfjs/dev` warning now ends with a silence hint that leads
+  with the browser-reachable switch, for example "Silence it with
+  enableWarnings({ narrowSet: false }) from kerfjs/dev, or set
+  KERF_DEV_WARN_NARROW_SET=0 (or unset it) under Node." Previously the
+  messages named only the environment variable, which a browser cannot reach.
+  The docs now teach `enableWarnings()` wherever they showed an env-only
+  switch, and name all three creation-time boundaries: `signal()`
+  (`untrackedSignals`), `effect()` (`delegateInEffect`), and `mount()`
+  (`rebuiltListeners`) decide once when created, so anything created before
+  the install or the opt-in stays uncovered.
+- The `kerfjs/dev` rebuilt-listeners warning (`rebuiltListeners` /
+  `KERF_DEV_WARN_REBUILT_LISTENERS`) now dedups once per `mount()`, as
+  documented. Previously the first warning silenced every other mount for
+  the life of the process, so a second mount with the same bug stayed quiet.
+- `kerfjs/router`: a second router on the same document no longer diverges
+  from the URL after a link click. The first router's interceptor navigates
+  with `pushState`, which fires no `popstate`, so the second router ignored
+  the already-handled click and kept the old route. An already-handled click
+  now re-syncs the route from the URL; when nothing navigated, it is a no-op.
+  One router per document remains the supported shape: a second router does
+  not follow another router's programmatic `navigate()` (no `popstate` fires
+  and routers do not broadcast to each other) until the next `popstate` or
+  link click. This is now documented and pinned by a test.
+- `kerfjs/scope`: a disposed `Scope` handle no longer leaks registrations.
+  Previously `add` / `mount` / `effect` / `delegate` on a handle after its
+  `dispose()` (or from a disposer while `dispose()` ran) pushed into a list
+  nothing would ever run, leaving the effect subscribed or the listener
+  attached. Such a registration now tears down at once: `add(fn)` calls `fn`
+  immediately, and the wrappers create and immediately dispose.
+- `bindList` measured-height virtualization no longer applies a stale
+  scroll-anchor correction. A `setHeight()` report for a row above the viewport
+  is now resolved when the animation frame runs: if the source removed the key,
+  moved it below the fold, or the user scrolled the row into view first,
+  `scrollTop` is left alone, and several reports for one key in a frame net
+  out. Fixed-height windows also clamp to the source length, so a list that
+  shrinks while scrolled deep no longer pads far past its content.
+- `create-kerf-component` accepts an explicit `boundaries.rootClass: null` as
+  an author decision, as its schema always allowed. A wrapper whose root
+  element belongs to another catalog (a `rendersAs` wrapper) no longer has to
+  invent a class to satisfy the generator. An absent `rootClass` still fails
+  as undecided.
+- `@kerfjs/ui`'s `Select` placeholder now matches the live control. The label
+  uses the field-label style (uppercase, extra-small, quiet, inset to line up
+  with the value), and the chevron is the same glyph at the same size.
+  Previously the placeholder drew a larger, regular-weight label at a
+  different inset and a different, smaller chevron. Only the value is a
+  skeleton; the chrome no longer changes when loading finishes.
+- **Wrapper components can declare the cataloged root they render.** A
+  `kerf.components.json` component may set `composition.rendersAs`, for
+  example `["@kerfjs/ui:toolbar-control-group"]`: a list of the roots it
+  renders, any one of them, or nothing. `kerf-component-catalog` copies it
+  into the generated v2 entry and fails unless every key resolves to a
+  cataloged entry. `eslint-plugin-kerfjs`'s `ui-composition` rule, and so
+  `kerf-ui-doctor`, now loads the application and third-party catalogs a
+  `.kerf-ui-profile.json` declares. It resolves their components by package
+  subpath or source file and checks a wrapper as each declared root: a zone
+  must accept every root, each root's parent contract applies where the
+  wrapper is placed, and a wrapper counts as zero or one child. Undeclared
+  wrappers keep reporting `KUI-L202`.
 - `@kerfjs/ui`'s `AppTab` adds `pending` for a known tab that is still
   opening. It keeps the name visible in the quiet text color and uses it as
   the tab's accessible name, so a trailing spinner's label is not folded in.

package/README.md

@@ -209,12 +209,13 @@ The class lives in its own subpath so apps that don't need it shed ~1 KB. Reads
 ```ts
 import { morph, raw } from "kerfjs";
 
-morph(liveCard, freshlyBuiltCardEl); // Element template
-morph(liveCard, '<article class="card">…</article>'); // raw HTML string
+// `template` describes liveCard's CHILDREN; liveCard's own attributes are untouched
+morph(liveCard, freshlyBuiltCardEl); // Element template: its child nodes are used
+morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>'); // raw HTML string
 morph(liveCard, raw(htmlFromServer)); // SafeHtml
 ```
 
-Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the `<details>` / `<dialog>` user-agent-owned `open` rule all carry over. Use it for SSR-fragment hydration, page-refresh diffs, third-party widget remounts. See [`docs/4-render.md`](./docs/4-render.md) §4.4.3.
+Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the user-agent-owned `open` rule (`<details>`, `<dialog>`, custom elements) all carry over. Only the live root's children are reconciled — the root's own attributes are never touched. Use it for SSR-fragment hydration, page-refresh diffs, third-party widget remounts. See [`docs/4-render.md`](./docs/4-render.md) §4.4.3.
 
 ### No build step at all: the `html` tagged template
 

package/ai/cursorrules

@@ -1,4 +1,4 @@
-<!-- kerf-skill-version: 1.21.0 -->
+<!-- kerf-skill-version: 1.21.1 -->
 
 # kerf.cursorrules — rules for building apps with kerf
 
@@ -17,7 +17,7 @@ You are writing a UI in kerf — a ~12 KB reactive framework (~13 KB with `array
 - Install with `npm install kerfjs`.
 - `tsconfig.json`: `"jsx": "react-jsx"`, `"jsxImportSource": "kerfjs"`.
 - Vite / esbuild need no extra config.
-- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it FIRST if relying on the untracked-signal warning — `signal()` picks its constructor at creation time.
+- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it (and any `enableWarnings()` call) FIRST if relying on the untracked-signal, delegate-in-effect, or rebuilt-listeners warnings — `signal()`, `effect()`, and `mount()` decide those at creation time, so anything created earlier stays uncovered.
   - **Switch individual warnings on with `enableWarnings()`**, which is the only switch that works in a browser (no `process` object there, and a bundler `define` cannot reach the read): `const dev = await import('kerfjs/dev'); dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });`. The `KERF_DEV_WARN_*` env vars do the same for Node/SSR/CI; an explicit call wins either way.
   - **A component package must NEVER import `kerfjs/dev`.** The hooks are process-global, so installing them is the consuming app's decision — a library that does it forces the diagnostics (and the chunk) on every consumer. Put the import in your demo page or test harness instead.
 - Recommended: also install `eslint-plugin-kerfjs` (`npm install --save-dev eslint-plugin-kerfjs`) and add `kerfjs.configs.recommended` to the project's eslint config. It enforces five of the hard rules below (no inline JSX event handlers, require `data-key` in `each()`, capture `delegate()` disposers, no nested `mount()`, prefer module JSX augmentation) at edit time so violations surface as IDE squiggles before any code runs.
@@ -128,7 +128,7 @@ if (import.meta.env.DEV) await import("kerfjs/dev");
 5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
 6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX.
 7. **No `<MyComponent />` semantics with hooks.** Components are plain functions returning JSX. State lives in module-scope signals or stores, never in component closures.
-8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`KERF_DEV_WARN_STALE_BINDING=1` detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` flags re-renders that could have been bindings.
+8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node) detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) flags re-renders that could have been bindings.
 9. **Store actions receive `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.
 10. **Use `data-action` attributes, not inline `onClick`.** Inline handlers are NOT supported by the JSX → string runtime; delegate from the root instead.
 11. **`arraySignal` is opt-in for long keyed lists** where most updates are pointwise (single-row edits, append-to-end). For short lists / filter+sort pipelines, plain `signal` + `each(items.value, ...)` is simpler and equally fast.
@@ -207,7 +207,8 @@ const cart = defineStore({
 });
 
 // One-shot reconcile against existing DOM (no signals)
-morph(liveCard, '<article class="card">…</article>');
+// the template describes liveCard's CHILDREN; liveCard's own attributes are untouched
+morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>');
 
 // No build step (CDN / importmap): the html tagged template instead of JSX.
 // Same runtime semantics as JSX; write real HTML attribute names; a hole must
@@ -260,7 +261,7 @@ mount(listEl, () => (
 - ` html` ``: partial attribute values are not supported → in `kerfjs/html` templates a hole must be the COMPLETE attribute value. Replace `class="a ${b}"` with a pre-built string (`` class="${`a ${b}`}" ``) or, for a bound attribute, `class="${computed(() => `a ${b.value}`)}"`.
 - An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns in dev) → lists without a key are identified by position among the render's `each()` calls, so adding/removing one above shifts this list's identity and kerf rebuilds it. Give the lists stable keys: `each(items, render, { key: 'results' })`; keying just the conditional list is usually enough.
 - Keyed `each()` list suddenly renders zero rows — only its `<!--kf-list:N-->` marker — with no errors, and it never recovers (kerfjs ≤ 2.0.1) → a conditionally-rendered sibling BEFORE the list (possibly higher in the tree, e.g. an error banner) was removed that render; older kerfjs rebuilt the shifted list container from the template, permanently detaching the list's internal binding. Upgrade kerfjs (fixed after 2.0.1 — the morph now moves the shifted container up in place, keeping node identity). On older versions, keep the structure before the list stable: wrap the conditional in an always-present container (`<div class="banners">{cond ? <div/> : ''}</div>`).
-- A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1`.
+- A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `enableWarnings({ staleIndex: true })` (or `KERF_DEV_WARN_STALE_INDEX=1` under Node).
 
 ## Server / SSR
 

package/ai/manifest.json

@@ -1,13 +1,13 @@
 {
-  "kerfjsVersion": "5.0.0-beta.52",
+  "kerfjsVersion": "5.0.0-beta.53",
   "files": [
     {
       "name": "skill",
       "source": "kerf.claude-skill.md",
       "bundle": "ai/skill.md",
       "dest": ".claude/skills/kerf-app/SKILL.md",
-      "version": "1.23.0",
-      "sha256": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007",
+      "version": "1.23.1",
+      "sha256": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c",
       "history": {
         "1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
         "1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
@@ -37,7 +37,8 @@
         "1.20.0": "aa88ccdbf969624bbc6cefadba76ada1f090fae436597a7bab564e24c467287f",
         "1.21.0": "265b747eeb9c3d445c60d66a1109eec42705075b7cd154d107bd79d543c1e7e5",
         "1.22.0": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70",
-        "1.23.0": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007"
+        "1.23.0": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007",
+        "1.23.1": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c"
       }
     },
     {
@@ -45,8 +46,8 @@
       "source": "kerf.cursorrules",
       "bundle": "ai/cursorrules",
       "dest": ".cursorrules",
-      "version": "1.21.0",
-      "sha256": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f",
+      "version": "1.21.1",
+      "sha256": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
       "history": {
         "1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
         "1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
@@ -74,7 +75,8 @@
         "1.18.0": "de3eea1bc181da629694d19a0817d252a868e4704437fbdd9e923856b8a0890a",
         "1.19.0": "c5b91e449f6feccaa36a04cb7f8550d3e414eb2795ea6c5dccdf6071206b3261",
         "1.20.0": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03",
-        "1.21.0": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f"
+        "1.21.0": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f",
+        "1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee"
       }
     }
   ]

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-app
 description: Build UIs in the kerf reactive framework and its @kerfjs/ui component package (https://github.com/brianwestphal/kerf). Use this skill whenever the user is writing or modifying code that imports `kerfjs` or `@kerfjs/ui`, asks to add a feature to a kerf app, or asks "how do I do X in kerf?". Use it proactively the moment you spot a kerf import in the file you're editing.
-kerf-skill-version: 1.23.0
+kerf-skill-version: 1.23.1
 ---
 
 # Building apps with kerf
@@ -17,7 +17,7 @@ kerf is a ~12 KB reactive UI framework (~13 KB with `arraySignal`): signals + DO
 - Install: `npm install kerfjs`
 - `tsconfig.json`: `"jsx": "react-jsx"`, `"jsxImportSource": "kerfjs"`
 - Vite / esbuild need no extra config.
-- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it FIRST if relying on the untracked-signal warning — `signal()` picks its constructor at creation time.
+- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it (and any `enableWarnings()` call) FIRST if relying on the untracked-signal, delegate-in-effect, or rebuilt-listeners warnings — `signal()`, `effect()`, and `mount()` decide those at creation time, so anything created earlier stays uncovered.
   - **Switch individual warnings on with `enableWarnings()`**, which is the only switch that works in a browser (no `process` object there, and a bundler `define` cannot reach the read): `const dev = await import('kerfjs/dev'); dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });`. The `KERF_DEV_WARN_*` env vars do the same for Node/SSR/CI; an explicit call wins either way.
   - **A component package must NEVER import `kerfjs/dev`.** The hooks are process-global, so installing them is the consuming app's decision — a library that does it forces the diagnostics (and the chunk) on every consumer. Put the import in your demo page or test harness instead.
 - Recommended companion: `npm install --save-dev eslint-plugin-kerfjs` and add `kerfjs.configs.recommended` to the project's eslint config. Enforces five of the hard rules below (no inline JSX event handlers, require `data-key` in `each()`, capture `delegate()` disposers, no nested `mount()`, prefer module JSX augmentation) at edit time — useful as a self-correction signal when authoring kerf code.
@@ -137,7 +137,7 @@ if (import.meta.env.DEV) await import("kerfjs/dev");
 5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
 6. **One `mount()` per root.** Don't nest `mount()` calls. Compose with plain functions returning JSX.
 7. **Components are plain functions.** `<MyComponent props />` works — the JSX runtime calls `MyComponent(props)` and uses the returned JSX — but there's no hook system, no lifecycle, and no per-instance state. State lives in module-scope signals or stores, never in component closures.
-8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` does NOT re-render. One caveat on bound holes: bind a STABLE signal/computed instance per hole (`class={computed(() => …)}` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (detectable via `KERF_DEV_WARN_STALE_BINDING=1`). The idiom's endpoint: a render that reads NO `.value` runs exactly once — a fully bound mount never re-renders. To find `.value` holes worth migrating, `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` flags re-renders whose only differences were text/attribute values.
+8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` does NOT re-render. One caveat on bound holes: bind a STABLE signal/computed instance per hole (`class={computed(() => …)}` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (detectable via `enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node)). The idiom's endpoint: a render that reads NO `.value` runs exactly once — a fully bound mount never re-renders. To find `.value` holes worth migrating, `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) flags re-renders whose only differences were text/attribute values.
 9. **Store actions take `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.
 10. **Use `data-action` attributes, not inline `onClick`.** Inline handlers are NOT supported by the JSX → string runtime; delegate from the root.
 11. **`arraySignal` is opt-in for long keyed lists** where most updates are pointwise. For short lists / filter+sort pipelines, plain `signal` + `each(items.value, ...)` is simpler and equally fast.
@@ -219,7 +219,8 @@ const cart = defineStore({
 // access: cart.state.value.items, cart.actions.add('x'), cart.reset()
 
 // Pattern 4: one-shot reconcile (no signals, no effect)
-morph(liveCard, '<article class="card">…</article>');
+// the template describes liveCard's CHILDREN; liveCard's own attributes are untouched
+morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>');
 
 // Pattern 5: fine-grained binding (opt-in) — pass the signal/computed ITSELF
 // into a hole so a change updates ONLY that node (no render re-run, no
@@ -276,7 +277,7 @@ mount(
 | ` html` ``: partial attribute values are not supported                                                                                                             | In `kerfjs/html` templates a hole must be the COMPLETE attribute value                                                                                                                                                                                                                                                                                                                  | Build the full string first (``class="${`a ${b}`}"``), or bind `class="${computed(() => `a ${b.value}`)}"` for a reactive one                                                                                                                                                                                                                                 |
 | An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns about this in dev)      | Lists without a key are identified by their position among the render's `each()` calls, so adding/removing one above shifts this list's identity and kerf rebuilds it                                                                                                                                                                                                                   | Give the lists stable keys: `each(items, render, { key: 'results' })`. Keying just the conditional list is usually enough                                                                                                                                                                                                                                     |
 | Keyed `each()` list suddenly renders zero rows — only its `<!--kf-list:N-->` marker — with no errors, and it never recovers (kerfjs ≤ 2.0.1)                       | A conditionally-rendered sibling BEFORE the list (possibly higher in the tree, e.g. an error banner) was removed that render; older kerfjs rebuilt the shifted list container from the template, permanently detaching the list's internal binding                                                                                                                                      | Upgrade kerfjs (fixed after 2.0.1 — the morph now moves the shifted container up in place, keeping node identity). On older versions, keep the structure before the list stable: wrap the conditional in an always-present container (`<div class="banners">{cond ? <div/> : ''}</div>`)                                                                      |
-| A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right  | The render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps the HTML it rendered at its old index                                                                                                                                                                     | Fold the index into the memo key so displaced rows re-render: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1`                                                                                                                                                                      |
+| A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right  | The render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps the HTML it rendered at its old index                                                                                                                                                                     | Fold the index into the memo key so displaced rows re-render: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `enableWarnings({ staleIndex: true })` (or `KERF_DEV_WARN_STALE_INDEX=1` under Node)                                                                                                               |
 
 ## Workflow guidance
 

package/dist/actions.js

@@ -1,5 +1,5 @@
 import { attr } from './chunk-MK42GLPV.js';
-import { delegate } from './chunk-E5R5GNKE.js';
+import { delegate } from './chunk-X6OQ2HTR.js';
 
 
 // src/actions.ts
@@ -14,8 +14,8 @@ function delegateActions(root, eventType, table, options) {
     eventType,
     `[${attrName}]`,
     (event, el) => {
-      const handler = table[el.getAttribute(attrName)];
-      if (handler !== void 0) handler(event, el);
+      const value = el.getAttribute(attrName);
+      if (Object.hasOwn(table, value)) table[value](event, el);
     },
     options
   );

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAmCA,IAAM,mBAAA,GAAsB,aAAA;AAkBrB,SAAS,OAAyB,KAAA,EAAsC;AAC7E,EAAA,OAAO,IAAA,CAAK,qBAAqB,KAAK,CAAA;AACxC;AAwBO,SAAS,eAAA,CACd,IAAA,EACA,SAAA,EACA,KAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,QAAA,GAAW,SAAS,IAAA,IAAQ,mBAAA;AAClC,EAAA,OAAO,QAAA;AAAA,IACL,IAAA;AAAA,IACA,SAAA;AAAA,IACA,IAAI,QAAQ,CAAA,CAAA,CAAA;AAAA,IACZ,CAAC,OAAO,EAAA,KAAO;AAEb,MAAA,MAAM,OAAA,GAAU,KAAA,CAAM,EAAA,CAAG,YAAA,CAAa,QAAQ,CAAW,CAAA;AACzD,MAAA,IAAI,OAAA,KAAY,MAAA,EAAW,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA;AAAA,IAC9C,CAAA;AAAA,IACA;AAAA,GACF;AACF","file":"actions.js","sourcesContent":["/**\n * `kerfjs/actions` — the delegated action-table helper.\n *\n * The most-reinvented idiom across real kerf apps: one table of `data-action`\n * attribute specs used as the single source of truth for BOTH the JSX attribute\n * and the delegate selector, plus a hand-rolled `switch (dataset.action)`\n * dispatcher. This subpath blesses it as two thin helpers over the existing\n * `attr()` + `delegate()` — it does NOT replace them.\n *\n *   import { action, delegateActions } from 'kerfjs/actions';\n *\n *   const A = {\n *     select: action('select-file'),\n *     remove: action('remove-file'),\n *   };\n *\n *   // JSX — spread the attr (rename-safe; no hardcoded attribute name):\n *   //   <button {...A.select.attrs} data-id={id}>…</button>\n *\n *   // Wire the whole table with ONE delegated listener; returns a disposer:\n *   const dispose = delegateActions(root, 'click', {\n *     [A.select.value]: (_e, el) => selectFile(el.getAttribute('data-id')),\n *     [A.remove.value]: (_e, el) => removeFile(el.getAttribute('data-id')),\n *   });\n *\n * Contract: `delegateActions` returns a `() => void` disposer and holds no\n * per-instance state — the same shape as `delegate()`, which it builds on (so\n * it inherits the single-listener dispatch and the capture auto-promotion for\n * well-known non-bubbling event types). One event type per call, mirroring\n * `delegate()`; collect the disposers for a root that needs several.\n */\nimport { attr, type AttrSpec } from './attr.js';\nimport { delegate, type DelegateOptions } from './delegate.js';\n\n/** The attribute an action table keys on by default. */\nconst DEFAULT_ACTION_ATTR = 'data-action';\n\n/**\n * A handler in a {@link delegateActions} table. Receives the DOM event and the\n * matched element (walk-up `closest()` match by default) — the same shape as a\n * `delegate()` handler.\n */\nexport type ActionHandler<E extends Element = Element> = (\n  event: Event,\n  el: E,\n) => void;\n\n/**\n * `action(value)` — an {@link AttrSpec} on `data-action`. A thin specialization\n * of `attr('data-action', value)`: spread its `.attrs` in JSX and use its\n * `.value` as the handler-table key, so the action name lives in exactly one\n * place and can't drift between the markup and the dispatcher.\n */\nexport function action<V extends string>(value: V): AttrSpec<'data-action', V> {\n  return attr(DEFAULT_ACTION_ATTR, value);\n}\n\n/** Options for {@link delegateActions}. Extends {@link DelegateOptions}. */\nexport interface DelegateActionsOptions extends DelegateOptions {\n  /**\n   * The attribute the table keys on. Default `'data-action'`. Override it only\n   * if you also author the specs with `attr(yourName, …)` instead of `action()`.\n   */\n  attr?: string;\n}\n\n/**\n * Wire a whole table of action handlers with ONE delegated listener.\n *\n * On `eventType`, the nearest element carrying the action attribute (walk-up\n * `closest()` by default; pass `{ match: 'direct' }` for an exact-element match)\n * is looked up in `table` by its attribute value, and the matching handler\n * runs. An element whose action is absent from the table is ignored — the same\n * behavior as a `switch (dataset.action)` with no matching `case`.\n *\n * Returns a `() => void` disposer. One event type per call (the smallest\n * surface, mirroring `delegate()`); collect the disposers when a root needs\n * several event types.\n */\nexport function delegateActions<E extends Element = Element>(\n  root: HTMLElement,\n  eventType: string,\n  table: Readonly<Record<string, ActionHandler<E>>>,\n  options?: DelegateActionsOptions,\n): () => void {\n  const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;\n  return delegate<E>(\n    root,\n    eventType,\n    `[${attrName}]`,\n    (event, el) => {\n      // `el` matched `[${attrName}]`, so the attribute is always present.\n      const handler = table[el.getAttribute(attrName) as string];\n      if (handler !== undefined) handler(event, el);\n    },\n    options,\n  );\n}\n"]}
+{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAmCA,IAAM,mBAAA,GAAsB,aAAA;AAkBrB,SAAS,OAAyB,KAAA,EAAsC;AAC7E,EAAA,OAAO,IAAA,CAAK,qBAAqB,KAAK,CAAA;AACxC;AAwBO,SAAS,eAAA,CACd,IAAA,EACA,SAAA,EACA,KAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,QAAA,GAAW,SAAS,IAAA,IAAQ,mBAAA;AAClC,EAAA,OAAO,QAAA;AAAA,IACL,IAAA;AAAA,IACA,SAAA;AAAA,IACA,IAAI,QAAQ,CAAA,CAAA,CAAA;AAAA,IACZ,CAAC,OAAO,EAAA,KAAO;AAEb,MAAA,MAAM,KAAA,GAAQ,EAAA,CAAG,YAAA,CAAa,QAAQ,CAAA;AAKtC,MAAA,IAAI,MAAA,CAAO,OAAO,KAAA,EAAO,KAAK,GAAG,KAAA,CAAM,KAAK,CAAA,CAAE,KAAA,EAAO,EAAE,CAAA;AAAA,IACzD,CAAA;AAAA,IACA;AAAA,GACF;AACF","file":"actions.js","sourcesContent":["/**\n * `kerfjs/actions` — the delegated action-table helper.\n *\n * The most-reinvented idiom across real kerf apps: one table of `data-action`\n * attribute specs used as the single source of truth for BOTH the JSX attribute\n * and the delegate selector, plus a hand-rolled `switch (dataset.action)`\n * dispatcher. This subpath blesses it as two thin helpers over the existing\n * `attr()` + `delegate()` — it does NOT replace them.\n *\n *   import { action, delegateActions } from 'kerfjs/actions';\n *\n *   const A = {\n *     select: action('select-file'),\n *     remove: action('remove-file'),\n *   };\n *\n *   // JSX — spread the attr (rename-safe; no hardcoded attribute name):\n *   //   <button {...A.select.attrs} data-id={id}>…</button>\n *\n *   // Wire the whole table with ONE delegated listener; returns a disposer:\n *   const dispose = delegateActions(root, 'click', {\n *     [A.select.value]: (_e, el) => selectFile(el.getAttribute('data-id')),\n *     [A.remove.value]: (_e, el) => removeFile(el.getAttribute('data-id')),\n *   });\n *\n * Contract: `delegateActions` returns a `() => void` disposer and holds no\n * per-instance state — the same shape as `delegate()`, which it builds on (so\n * it inherits the single-listener dispatch and the capture auto-promotion for\n * well-known non-bubbling event types). One event type per call, mirroring\n * `delegate()`; collect the disposers for a root that needs several.\n */\nimport { attr, type AttrSpec } from './attr.js';\nimport { delegate, type DelegateOptions } from './delegate.js';\n\n/** The attribute an action table keys on by default. */\nconst DEFAULT_ACTION_ATTR = 'data-action';\n\n/**\n * A handler in a {@link delegateActions} table. Receives the DOM event and the\n * matched element (walk-up `closest()` match by default) — the same shape as a\n * `delegate()` handler.\n */\nexport type ActionHandler<E extends Element = Element> = (\n  event: Event,\n  el: E,\n) => void;\n\n/**\n * `action(value)` — an {@link AttrSpec} on `data-action`. A thin specialization\n * of `attr('data-action', value)`: spread its `.attrs` in JSX and use its\n * `.value` as the handler-table key, so the action name lives in exactly one\n * place and can't drift between the markup and the dispatcher.\n */\nexport function action<V extends string>(value: V): AttrSpec<'data-action', V> {\n  return attr(DEFAULT_ACTION_ATTR, value);\n}\n\n/** Options for {@link delegateActions}. Extends {@link DelegateOptions}. */\nexport interface DelegateActionsOptions extends DelegateOptions {\n  /**\n   * The attribute the table keys on. Default `'data-action'`. Override it only\n   * if you also author the specs with `attr(yourName, …)` instead of `action()`.\n   */\n  attr?: string;\n}\n\n/**\n * Wire a whole table of action handlers with ONE delegated listener.\n *\n * On `eventType`, the nearest element carrying the action attribute (walk-up\n * `closest()` by default; pass `{ match: 'direct' }` for an exact-element match)\n * is looked up in `table` by its attribute value, and the matching handler\n * runs. An element whose action is absent from the table is ignored — the same\n * behavior as a `switch (dataset.action)` with no matching `case`.\n *\n * Returns a `() => void` disposer. One event type per call (the smallest\n * surface, mirroring `delegate()`); collect the disposers when a root needs\n * several event types.\n */\nexport function delegateActions<E extends Element = Element>(\n  root: HTMLElement,\n  eventType: string,\n  table: Readonly<Record<string, ActionHandler<E>>>,\n  options?: DelegateActionsOptions,\n): () => void {\n  const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;\n  return delegate<E>(\n    root,\n    eventType,\n    `[${attrName}]`,\n    (event, el) => {\n      // `el` matched `[${attrName}]`, so the attribute is always present.\n      const value = el.getAttribute(attrName) as string;\n      // Own entries only: the table is an ordinary object, so a bare\n      // `table[value]` would resolve Object.prototype names (`__proto__`,\n      // `constructor`, `toString`, `hasOwnProperty`, …) and dispatch or throw\n      // on markup that names no action in the table.\n      if (Object.hasOwn(table, value)) table[value](event, el);\n    },\n    options,\n  );\n}\n"]}

package/dist/array-signal.js

@@ -1,4 +1,4 @@
-export { ARRAY_SIGNAL_BRAND, ArraySignal, arraySignal } from './chunk-ELXVRKY2.js';
+export { ARRAY_SIGNAL_BRAND, ArraySignal, arraySignal } from './chunk-H7WTRM6F.js';
 
 
 

package/dist/async.js

@@ -1,4 +1,4 @@
-import { signal } from './chunk-Y2FOYPBV.js';
+import { signal } from './chunk-IHMDBBUJ.js';
 
 
 // src/async.ts