@statorjs/stator 1.8.0 → 2.0.0

package/src/engine/actor.ts

@@ -18,9 +18,9 @@ export interface Actor<C, E extends EventObject> {
    *  the element's connect). No-op after start. */
   seed(partial: Partial<C>): void
   getSnapshot(): Snapshot<C>
-  /** Monotonic count of HANDLED events (a matching transition fired or an
-   *  `@set` applied). Guard-dropped and unhandled events don't count — this
-   *  is how the server distinguishes "committed" from "silently dropped". */
+  /** Monotonic count of HANDLED events (a matching transition fired).
+   *  Guard-dropped and unhandled events don't count — this is how the server
+   *  distinguishes "committed" from "silently dropped". */
   getCommitCount(): number
   subscribe(listener: (snapshot: Snapshot<C>) => void): { unsubscribe(): void }
   /** Listen for a declared emit. Returns a remover. Used by cross-machine
@@ -63,12 +63,6 @@ export interface CreateActorOptions<C> {
    *  effect locally on a microtask and sends its completion event to itself —
    *  the client-plane (and unit-test) behavior. */
   onEffect?: (invocation: EffectInvocation) => void
-  /** Honor framework-internal events (currently `@set`, which powers two-way
-   *  `bind:value`). Enabled ONLY for client-island actors, whose `@set` events
-   *  originate from their own compiled bind code. Server actors leave this off:
-   *  they take events straight from the untrusted wire (`/__events`), where a
-   *  `@set` would be an arbitrary-context-write that bypasses every guard. */
-  internalEvents?: boolean
   /** Host hook: a state was ENTERED (fresh start or a value-changing transition —
    *  never hydration). The server uses it to arm `after` timers from the state's
    *  config; `ctx` is the current context (for context-dependent delays). */
@@ -224,19 +218,6 @@ export function createActor<C extends object, E extends EventObject, S extends s
     },
 
     send(event: E) {
-      // Framework-internal `@set`: assign one context key. Powers two-way
-      // `bind:value` (DOM → state) on client islands without a per-field
-      // transition. Honored ONLY when the host opted in (`internalEvents`) —
-      // server actors never do, so a wire-delivered `@set` falls through to
-      // ordinary (unhandled) resolution and mutates nothing. Without this gate
-      // `@set` is a guard-bypassing arbitrary-context write over `/__events`.
-      if (opts.internalEvents && (event as { type: string }).type === '@set') {
-        const e = event as unknown as { key: string; value: unknown }
-        context = { ...context, [e.key]: e.value }
-        commits += 1
-        notify()
-        return
-      }
       // Resolve the current leaf state (depth-1 today: value[0]).
       const stateKey = value[value.length - 1]!
       const node = def.states[stateKey]

package/src/engine/index.ts

@@ -31,6 +31,7 @@ export type {
   ReadsMap,
   SelectorMap,
   Snapshot,
+  StateNameOf,
   StateNode,
   SubscribeEntry,
   Transition,

package/src/engine/types.ts

@@ -288,6 +288,13 @@ export type ReadsMap<TReads extends readonly AnyMachineDef[]> = {
 export type EventOf<D extends AnyMachineDef> =
   D extends MachineDef<any, infer E, any, any, any> ? E : never
 
+/** The state-name union a machine declares (the keys of its `states`). Threads
+ *  the literal names into `instance.state` so a template comparison
+ *  (`read(m, s => s.state === 'ready')`) autocompletes and a typo is a compile
+ *  error, instead of `state: string` swallowing it. */
+export type StateNameOf<D extends AnyMachineDef> =
+  D extends MachineDef<any, any, infer S, any, any> ? S : string
+
 export function isStatorMachine(v: unknown): v is AnyMachineDef {
   return (
     typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isStatorMachine === true

package/src/server/http.ts

@@ -324,12 +324,12 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       return c.json({ error: 'invalid event payload', detail: String(e) }, 400)
     }
 
-    // Reserved `@`-prefixed events (e.g. the engine's built-in `@set`) are
-    // framework-internal and only ever originate in-browser for client-island
-    // binds. They must never reach a server machine from the wire, where `@set`
-    // would be a guard-bypassing arbitrary-context write. Server actors also
-    // ignore them (createActor without `internalEvents`); this is the clean
-    // 400 at the boundary rather than a silent no-op.
+    // The `@` event-name prefix is RESERVED for the framework. Nothing uses
+    // it today (2.0 removed the engine's `@set`), and keeping the wire fence
+    // means any future internal event is unreachable from untrusted input by
+    // construction — a clean 400 at the boundary rather than a silent no-op.
+    // History: `@set` (two-way bind:'s desugaring) was once wire-reachable —
+    // a guard-bypassing arbitrary-context write, fixed as a security patch.
     if (body.event.type.startsWith('@')) {
       return c.json({ error: `event type "${body.event.type}" is reserved` }, 400)
     }

package/src/server/index.ts

@@ -1,3 +1,13 @@
+/**
+ * `/server` carries two tiers (see the docs' stability policy): the STABLE
+ * app surface (createApp, defineMachine, defineApiRoute, the stores, logger,
+ * dispatchToApp, rotateSession) and the TOOLCHAIN plumbing the compiler/Vite
+ * module graph needs importable (recompute, renderRoute, buildHonoApp,
+ * SessionRuntime, render-context internals, …). The Toolchain tier is not
+ * covered by semver and is RESERVED to move to a dedicated subpath
+ * (`@statorjs/stator/server/runtime`) in a 2.x minor — import it expecting
+ * that move.
+ */
 export type {
   ElementTarget,
   Patch,

package/src/server/recompute.ts

@@ -1,7 +1,7 @@
 import { renderBranchBody } from '../template/conditional.ts'
 import { coerceKeys, renderKeyedItem, renderListBody } from '../template/each.ts'
+import { attrValue, sanitizeAttr, textValue } from '../wire/attr-value.ts'
 import type { Patch } from '../wire/index.ts'
-import { isUrlAttribute, safeAttrUrl } from '../wire/safe-url.ts'
 import {
   type ItemBinding,
   keyedScopePrefix,
@@ -34,7 +34,7 @@ function diffItemBindings(
     ib.lastValue = nv
     if (ib.kind === 'text') {
       pending.push({
-        patch: { target: { kind: 'slot', id: ib.slotId }, op: 'text', value: stringify(nv) },
+        patch: { target: { kind: 'slot', id: ib.slotId }, op: 'text', value: textValue(nv) },
         sourceSlot: ib.slotId,
       })
     } else {
@@ -43,7 +43,7 @@ function diffItemBindings(
           target: { kind: 'element', id: ib.parentId },
           op: 'attr',
           name: ib.attrName,
-          value: sanitizeAttrWire(ib.attrName, attrWireValue(nv)),
+          value: sanitizeAttr(ib.attrName, attrValue(nv)),
         },
         sourceSlot: ib.parentId,
       })
@@ -104,7 +104,7 @@ function recomputeInner(state: RenderState, machineName: string, runtime: Sessio
           patch: {
             target: { kind: 'slot', id: slotId },
             op: 'text',
-            value: stringify(newValue),
+            value: textValue(newValue),
           },
           sourceSlot: slotId,
         })
@@ -117,7 +117,7 @@ function recomputeInner(state: RenderState, machineName: string, runtime: Sessio
             target: { kind: 'element', id: binding.parentId },
             op: 'attr',
             name: binding.attrName,
-            value: sanitizeAttrWire(binding.attrName, attrWireValue(newValue)),
+            value: sanitizeAttr(binding.attrName, attrValue(newValue)),
           },
           sourceSlot: slotId,
         })
@@ -297,12 +297,6 @@ function arrayShallowEqual(a: readonly unknown[], b: readonly unknown[]): boolea
   return true
 }
 
-function stringify(v: unknown): string {
-  if (v == null) return ''
-  if (typeof v === 'string') return v
-  return String(v)
-}
-
 /** Baseline invalidation marker — never equal to any real value or key. */
 const NEVER_SYNCED = Symbol('stator.never-synced')
 
@@ -368,17 +362,3 @@ export function initialSyncPatches(state: RenderState, runtime: SessionRuntime):
 /** Attr-binding wire semantics, mirroring the render side: false/null/
  *  undefined → null (attribute removed), true → '' (present, empty),
  *  anything else stringified. */
-function attrWireValue(v: unknown): string | null {
-  if (v === false || v === null || v === undefined) return null
-  if (v === true) return ''
-  return stringify(v)
-}
-
-/** Mirror of html.ts `sanitizeAttrValue` for the live-update path: strip a
- *  javascript:/vbscript: value from a url-bearing attribute patch so a binding
- *  that was safe at first render can't turn dangerous via a diff. Null
- *  (attribute-absent) passes through. */
-function sanitizeAttrWire(attrName: string, value: string | null): string | null {
-  if (value === null) return null
-  return isUrlAttribute(attrName) ? safeAttrUrl(value) : value
-}

package/src/template/directives/on.ts

@@ -3,9 +3,13 @@ import { type DirectiveInvocation, defineDirective, invoke } from './core.ts'
 
 type Handler = () => EventDescriptor | undefined
 
-const onDirective = defineDirective<Handler>({
+const onDirective = defineDirective<Handler | null | undefined>({
   name: 'on',
   apply({ modifier, arg, addAttribute }) {
+    // A forwarded/optional handler may be absent — `on:click={onClick}` where the
+    // caller passed no handler (Stator.forwarded returns undefined). Emit no
+    // binding rather than crash on `arg()`.
+    if (arg == null) return
     const result = arg()
     if (!isEventDescriptor(result)) {
       throw new Error(
@@ -17,6 +21,9 @@ const onDirective = defineDirective<Handler>({
   },
 })
 
-export function on(modifier: string, handler: Handler): DirectiveInvocation<Handler> {
+export function on(
+  modifier: string,
+  handler: Handler | null | undefined,
+): DirectiveInvocation<Handler | null | undefined> {
   return invoke(onDirective, modifier, handler)
 }

package/src/template/directives/spread.ts

@@ -0,0 +1,88 @@
+import { registerBinding, requireCurrentRenderState } from '../../server/render-context.ts'
+import { isUrlAttribute, safeAttrUrl } from '../../wire/safe-url.ts'
+import { isItemReadResult } from '../each.ts'
+import { isReadResult } from '../read.ts'
+import { type DirectiveInvocation, defineDirective, invoke, isDirectiveInvocation } from './core.ts'
+
+/**
+ * `{...spread}` on an element — forward a bag of attributes onto it. This is what
+ * makes the `HTMLAttributes<Tag>` component pattern practical: a `<Button>` can
+ * `<button {...rest} />` instead of hand-forwarding every native attribute.
+ *
+ * A spread value may be a literal OR a live machine `read(...)` — each read
+ * registers the same attribute binding the normal `attr={read(...)}` path does,
+ * so it patches on machine events (there is no separate reactive-spread wire).
+ * Two value kinds are rejected LOUDLY rather than silently mishandled:
+ *   - `read(item, …)` (an item binding) — it's owned by its each() row and can't
+ *     ride through a spread; bind it directly on the element. Mirrors the
+ *     class:list / style:list item-read rule (deferred util, see spread.test).
+ *   - a directive invocation (a `classList()` / `on()` result) — a directive owns
+ *     a whole attribute and isn't a plain value.
+ *
+ * Boolean/url semantics match the literal attr path (see html.ts handleRead):
+ * false / null / undefined ⇒ the attribute is ABSENT, true ⇒ present-and-empty,
+ * anything else stringifies; url-bearing names (href/src/…) get the scheme guard.
+ */
+export type SpreadAttrs = Record<string, unknown>
+
+const spreadDirective = defineDirective<SpreadAttrs>({
+  name: 'spread',
+  apply({ elementId, arg, addAttribute }) {
+    if (arg == null) return
+    const state = requireCurrentRenderState()
+    for (const [name, value] of Object.entries(arg)) {
+      if (isItemReadResult(value)) {
+        throw new Error(
+          `stator: read(item, …) can't be forwarded through {...spread} (attribute "${name}") — ` +
+            `an item read is owned by its each() row. Bind it directly on the element ` +
+            `(<el ${name}={read(item, …)} />). Only machine reads and static values can be spread.`,
+        )
+      }
+      if (isDirectiveInvocation(value)) {
+        throw new Error(
+          `stator: a directive (class:list / style:list / on:) can't be a {...spread} value ` +
+            `(attribute "${name}") — a directive owns a whole attribute. Apply it on the element directly.`,
+        )
+      }
+      if (isReadResult(value)) {
+        // A live machine read: register the same attr binding the normal
+        // `attr={read(...)}` path registers, keyed to this element + name, so a
+        // machine event patches it. No new wire — same shape recompute expects.
+        registerBinding(state, {
+          slotId: value.slotId,
+          machineName: value.machineName,
+          selector: value.selector,
+          lastValue: value.value,
+          kind: 'attr',
+          attrName: name,
+          parentId: elementId,
+        })
+        emitAttribute(name, value.value, addAttribute)
+        continue
+      }
+      emitAttribute(name, value, addAttribute)
+    }
+  },
+})
+
+/** Emit one attribute with the shared boolean/url semantics. false/null/undefined
+ *  ⇒ absent (no `addAttribute` call at all); true ⇒ present-and-empty; otherwise
+ *  stringified, url-guarded on url-bearing names. `addAttribute` HTML-escapes. */
+function emitAttribute(
+  name: string,
+  value: unknown,
+  addAttribute: (name: string, value: string) => void,
+): void {
+  if (value === false || value === null || value === undefined) return
+  if (value === true) {
+    addAttribute(name, '')
+    return
+  }
+  const str = typeof value === 'string' ? value : String(value)
+  addAttribute(name, isUrlAttribute(name) ? safeAttrUrl(str) : str)
+}
+
+/** Wrap an attribute bag as the directive the compiler emits for `{...spread}`. */
+export function spreadAttrs(attrs: SpreadAttrs): DirectiveInvocation<SpreadAttrs> {
+  return invoke(spreadDirective, '', attrs)
+}

package/src/template/html-attributes.ts

@@ -0,0 +1,210 @@
+/**
+ * Type-only HTML attribute surface for authoring components that extend a native
+ * element — the Astro/Svelte `HTMLAttributes<'button'>` pattern. So a component
+ * can be `Stator.props<HTMLAttributes<'button'> & { variant: 'primary' }>()` and
+ * get every native button attribute typed + validated, plus its own props.
+ *
+ * Hand-authored and intentionally LEAN: a useful subset, not the whole DOM. It
+ * mirrors `svelte/elements`' shape — a shared base (global attrs + ARIA + the
+ * Stator directives) plus a per-element attribute map, combined by tag. Grow the
+ * per-element map on demand; there is no compiler machinery behind this.
+ *
+ * STATOR REACTIVITY: a template attribute value can be a literal OR a live
+ * `read(...)` binding (`ReadResult<T>`), so every non-directive attribute value
+ * is `Reactive<T>`. This is the adaptation that makes typed intrinsics coexist
+ * with Stator templates — the load-bearing difference from Astro/Svelte, where
+ * attributes are plain values.
+ */
+
+import type { ReadResult } from './read.ts'
+
+/** A template attribute value: a literal, or a live `read(...)` binding. */
+export type Reactive<T> = T | ReadResult<T>
+
+/** Wrap every property value in `Reactive` (bindings allowed on any attribute).
+ *  Homomorphic, so it preserves the `data-*`/`aria-*` index signatures. */
+type Reactivize<A> = { [K in keyof A]: Reactive<A[K]> }
+
+/** Stator template directives — colon-namespaced, valid on any element and on any
+ *  component that forwards them. Not reactivized: their values are handlers/specs,
+ *  not bindings. Values are `unknown` for now — a later pass gives `on:`/`bind:`/
+ *  `ref:` their Stator-specific types. */
+export interface StatorDirectiveAttributes {
+  'class:list'?: unknown
+  'style:list'?: unknown
+  [key: `on:${string}`]: unknown
+  [key: `ref:${string}`]: unknown
+}
+
+/** ARIA — `role` plus the open-ended `aria-*` family. */
+export interface AriaAttributes {
+  role?: string
+  [key: `aria-${string}`]: unknown
+}
+
+/** Global attributes present on every HTML element (a lean subset). Numeric
+ *  attributes accept `string` too, since templates write them as strings. */
+export interface GlobalHTMLAttributes {
+  class?: string
+  id?: string
+  style?: string
+  title?: string
+  hidden?: boolean
+  tabindex?: number | string
+  lang?: string
+  dir?: 'ltr' | 'rtl' | 'auto'
+  draggable?: boolean | 'true' | 'false'
+  popover?: boolean | string
+  /** Stator named-slot target — `child="header"` fills `<children name="header"/>`. */
+  child?: string
+  [key: `data-${string}`]: unknown
+}
+
+/** Per-element extra attributes. Extend as components need them. */
+export interface ElementSpecificAttributes {
+  a: { href?: string; target?: string; rel?: string; download?: string | boolean }
+  button: {
+    type?: 'submit' | 'reset' | 'button'
+    disabled?: boolean
+    name?: string
+    value?: string
+    form?: string
+    autofocus?: boolean
+    popovertarget?: string
+    popovertargetaction?: 'show' | 'hide' | 'toggle'
+  }
+  input: {
+    type?: string
+    name?: string
+    value?: string | number
+    placeholder?: string
+    disabled?: boolean
+    required?: boolean
+    readonly?: boolean
+    checked?: boolean
+    min?: string | number
+    max?: string | number
+    step?: string | number
+    minlength?: number | string
+    maxlength?: number | string
+    pattern?: string
+    autocomplete?: string
+    inputmode?: string
+    autofocus?: boolean
+  }
+  label: { for?: string }
+  form: {
+    action?: string
+    method?: 'get' | 'post' | 'GET' | 'POST' | 'dialog'
+    novalidate?: boolean
+  }
+  select: {
+    name?: string
+    disabled?: boolean
+    required?: boolean
+    multiple?: boolean
+    value?: string | number
+  }
+  option: { value?: string | number; selected?: boolean; disabled?: boolean }
+  textarea: {
+    name?: string
+    placeholder?: string
+    rows?: number | string
+    cols?: number | string
+    disabled?: boolean
+    required?: boolean
+    readonly?: boolean
+    minlength?: number | string
+    maxlength?: number | string
+  }
+  img: {
+    src?: string
+    alt?: string
+    width?: number | string
+    height?: number | string
+    loading?: 'eager' | 'lazy'
+  }
+}
+
+/**
+ * The attribute type for a native element `Tag`. Intersect it in a component's
+ * props to forward native attributes:
+ *
+ *   const { variant, ...rest } =
+ *     Stator.props<HTMLAttributes<'button'> & { variant: 'primary' | 'danger' }>()
+ *
+ * `Tag` defaults to the shared base (global + ARIA + directives) for elements not
+ * in the per-element map. HTML attribute values are `Reactive` (literal or live
+ * binding); directives keep their own value types.
+ */
+export type HTMLAttributes<Tag extends string = string> = Reactivize<
+  GlobalHTMLAttributes &
+    AriaAttributes &
+    (Tag extends keyof ElementSpecificAttributes
+      ? ElementSpecificAttributes[Tag]
+      : Record<never, never>)
+> &
+  StatorDirectiveAttributes
+
+/**
+ * The per-element intrinsic map wired into `JSX.IntrinsicElements`, so a typo on
+ * a plain `<button typ=>` is a real error. Common HTML tags are typed;
+ * the `[tag: string]: any` fallback keeps custom elements (client-island tags
+ * like `<live-sky>`) and everything not listed (SVG, rare tags) permissive — the
+ * escape valve that stops the typing from flooding real templates. Every explicit
+ * entry is assignable to `any`, so the index signature is satisfied.
+ */
+export interface StatorIntrinsicElements {
+  a: HTMLAttributes<'a'>
+  button: HTMLAttributes<'button'>
+  input: HTMLAttributes<'input'>
+  select: HTMLAttributes<'select'>
+  option: HTMLAttributes<'option'>
+  textarea: HTMLAttributes<'textarea'>
+  label: HTMLAttributes<'label'>
+  form: HTMLAttributes<'form'>
+  img: HTMLAttributes<'img'>
+  div: HTMLAttributes<'div'>
+  span: HTMLAttributes<'span'>
+  p: HTMLAttributes<'p'>
+  h1: HTMLAttributes<'h1'>
+  h2: HTMLAttributes<'h2'>
+  h3: HTMLAttributes<'h3'>
+  h4: HTMLAttributes<'h4'>
+  h5: HTMLAttributes<'h5'>
+  h6: HTMLAttributes<'h6'>
+  ul: HTMLAttributes<'ul'>
+  ol: HTMLAttributes<'ol'>
+  li: HTMLAttributes<'li'>
+  nav: HTMLAttributes<'nav'>
+  header: HTMLAttributes<'header'>
+  footer: HTMLAttributes<'footer'>
+  section: HTMLAttributes<'section'>
+  main: HTMLAttributes<'main'>
+  article: HTMLAttributes<'article'>
+  aside: HTMLAttributes<'aside'>
+  strong: HTMLAttributes<'strong'>
+  em: HTMLAttributes<'em'>
+  small: HTMLAttributes<'small'>
+  code: HTMLAttributes<'code'>
+  pre: HTMLAttributes<'pre'>
+  time: HTMLAttributes<'time'>
+  cite: HTMLAttributes<'cite'>
+  hr: HTMLAttributes<'hr'>
+  br: HTMLAttributes<'br'>
+  figure: HTMLAttributes<'figure'>
+  figcaption: HTMLAttributes<'figcaption'>
+  details: HTMLAttributes<'details'>
+  summary: HTMLAttributes<'summary'>
+  dialog: HTMLAttributes<'dialog'>
+  table: HTMLAttributes<'table'>
+  thead: HTMLAttributes<'thead'>
+  tbody: HTMLAttributes<'tbody'>
+  tr: HTMLAttributes<'tr'>
+  td: HTMLAttributes<'td'>
+  th: HTMLAttributes<'th'>
+  fieldset: HTMLAttributes<'fieldset'>
+  legend: HTMLAttributes<'legend'>
+  // biome-ignore lint/suspicious/noExplicitAny: escape valve — custom-element islands, SVG, and unlisted tags stay fully permissive; every explicit entry above is assignable to this index signature.
+  [tag: string]: any
+}

package/src/template/html.ts

@@ -4,7 +4,7 @@ import {
   registerBinding,
   requireCurrentRenderState,
 } from '../server/render-context.ts'
-import { isUrlAttribute, safeAttrUrl } from '../wire/safe-url.ts'
+import { attrValue, sanitizeAttr, textValue } from '../wire/attr-value.ts'
 import { escapeAttribute, escapeText, HtmlBuilder, type ValuePosition } from './parser.ts'
 import { createHtmlFragment, type HtmlFragment, isHtmlFragment } from './types.ts'
 
@@ -46,14 +46,6 @@ export function html(strings: TemplateStringsArray, ...values: unknown[]): HtmlF
   return createHtmlFragment(builder.toString())
 }
 
-/** URL-scheme guard for attribute interpolation: on url-bearing attributes
- *  (href/src/…), strip a javascript:/vbscript: value; other attributes pass
- *  through unchanged. Mirrored on the live-update path (server/recompute.ts) so
- *  a value that's safe at first render can't turn dangerous via a patch. */
-function sanitizeAttrValue(attrName: string, value: string): string {
-  return isUrlAttribute(attrName) ? safeAttrUrl(value) : value
-}
-
 function processValue(builder: HtmlBuilder, state: RenderState, value: unknown): void {
   const pos = builder.positionForValue()
   if (pos.kind === 'invalid') {
@@ -123,11 +115,14 @@ function processValue(builder: HtmlBuilder, state: RenderState, value: unknown):
   }
 
   if (pos.kind === 'text') {
-    builder.pushRaw(escapeText(stringifyValue(value)))
+    builder.pushRaw(escapeText(textValue(value)))
     return
   }
   if (pos.kind === 'attr-value') {
-    builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(value))))
+    // The shared attr contract (wire/attr-value.ts): null → attribute ABSENT.
+    const av = attrValue(value)
+    if (av === null) builder.omitCurrentAttribute()
+    else builder.pushRaw(escapeAttribute(sanitizeAttr(pos.attrName, av)))
     return
   }
   throw new Error(`stator: cannot interpolate a plain value at ${pos.kind} position`)
@@ -162,7 +157,7 @@ function handleRead(
       lastValue: r.value,
       kind: 'text',
     })
-    builder.pushRaw(`<span data-slot="${r.slotId}">${escapeText(stringifyValue(r.value))}</span>`)
+    builder.pushRaw(`<span data-slot="${r.slotId}">${escapeText(textValue(r.value))}</span>`)
     return
   }
   if (pos.kind === 'attr-value') {
@@ -183,14 +178,12 @@ function handleRead(
       attrName: pos.attrName,
       parentId: pos.elementId,
     })
-    // Boolean semantics: false/null/undefined mean the attribute is ABSENT
-    // (`disabled={read(...)}` must be able to un-disable), true means
-    // present-and-empty. Everything else stringifies as before. The patch
-    // side mirrors this: see recompute's attrWireValue.
-    if (r.value === false || r.value === null || r.value === undefined) {
-      builder.omitCurrentAttribute()
-    } else if (r.value !== true) {
-      builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(r.value))))
+    // The shared attr contract (wire/attr-value.ts) — the same function the
+    // patch side (recompute) normalizes with, so render and diff can't drift.
+    {
+      const av = attrValue(r.value)
+      if (av === null) builder.omitCurrentAttribute()
+      else builder.pushRaw(escapeAttribute(sanitizeAttr(pos.attrName, av)))
     }
     return
   }
@@ -216,7 +209,7 @@ function handleItemRead(
   if (pos.kind === 'text') {
     const slotId = allocSlotId(state)
     row.push({ kind: 'text', slotId, selector: r.selector, lastValue: r.value })
-    builder.pushRaw(`<span data-slot="${slotId}">${escapeText(stringifyValue(r.value))}</span>`)
+    builder.pushRaw(`<span data-slot="${slotId}">${escapeText(textValue(r.value))}</span>`)
     return
   }
   if (pos.kind === 'attr-value') {
@@ -233,21 +226,13 @@ function handleItemRead(
       selector: r.selector,
       lastValue: r.value,
     })
-    // Same boolean semantics as a machine attr read (see handleRead).
-    if (r.value === false || r.value === null || r.value === undefined) {
-      builder.omitCurrentAttribute()
-    } else if (r.value !== true) {
-      builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(r.value))))
+    // Same shared attr contract as every other attr writer.
+    {
+      const av = attrValue(r.value)
+      if (av === null) builder.omitCurrentAttribute()
+      else builder.pushRaw(escapeAttribute(sanitizeAttr(pos.attrName, av)))
     }
     return
   }
   throw new Error(`stator: read(item, …) cannot be interpolated at ${pos.kind} position`)
 }
-
-function stringifyValue(v: unknown): string {
-  if (v == null) return ''
-  if (typeof v === 'string') return v
-  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
-  if (Array.isArray(v)) return v.map(stringifyValue).join('')
-  return String(v)
-}

package/src/template/index.ts

@@ -8,23 +8,29 @@ export {
 } from './conditional.ts'
 export type { DeferArms, DeferResult } from './defer.ts'
 export { defer, isDeferResult } from './defer.ts'
-export type {
-  Directive,
-  DirectiveContext,
-  DirectiveDefinition,
-  DirectiveInvocation,
-} from './directives/core.ts'
-export {
-  defineDirective,
-  invoke,
-  isDirectiveInvocation,
-} from './directives/core.ts'
+// The custom-directive surface (defineDirective/invoke) was removed from the
+// public barrel in 2.0: it was documented but unusable from `.stator` files
+// (the compiler owns the closed directive namespace), and a future custom-
+// directive system would be global configuration, not per-template calls.
+// The runtime pieces live on in ./directives/core.ts as internals.
+export { isDirectiveInvocation } from './directives/core.ts'
 export type { ClassListSpec, StyleListSpec } from './directives/list-attr.ts'
 export { classList, styleList } from './directives/list-attr.ts'
 export { on } from './directives/on.ts'
+export type { SpreadAttrs } from './directives/spread.ts'
+export { spreadAttrs } from './directives/spread.ts'
 export type { EachResult } from './each.ts'
 export { each, isEachResult, itemBind, renderListBody } from './each.ts'
 export { html, raw } from './html.ts'
+export type {
+  AriaAttributes,
+  ElementSpecificAttributes,
+  GlobalHTMLAttributes,
+  HTMLAttributes,
+  Reactive,
+  StatorDirectiveAttributes,
+  StatorIntrinsicElements,
+} from './html-attributes.ts'
 export type { ReadResult } from './read.ts'
 export { isReadResult, read } from './read.ts'
 export type { HtmlFragment, InstanceOf } from './types.ts'