@statorjs/stator 1.9.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.9.0"
+    "@statorjs/stator": "2.0.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/index.ts

@@ -4,11 +4,12 @@
  * island needs; these are also the symbols an author references directly.
  */
 
+export { attrValue, setAttr } from '../wire/attr-value.ts'
 export { bind, bindSlot, effect } from './bind.ts'
 export type { DispatchResult } from './dispatch.ts'
 export { dispatch } from './dispatch.ts'
 export { defineElement, StatorElement } from './element.ts'
-export type { ClientBehavior, LegacyMachineConfig } from './machine.ts'
+export type { ClientBehavior } from './machine.ts'
 export { machine } from './machine.ts'
 export type { DispatchError } from './transport.ts'
 export type { ClientInstance, ClientInstanceBase } from './use.ts'

package/src/client/machine.ts

@@ -63,28 +63,12 @@ export interface ClientBehavior<C> {
   select?: Record<string, (ctx: C) => unknown>
 }
 
-/** @deprecated One-bag form: context keys mixed with `on`/`select`. Kept for
- *  compatibility, but handlers see `any` — TypeScript cannot infer a
- *  context from the same object the handlers live in. Prefer
- *  `machine(context, behavior)`. */
-export interface LegacyMachineConfig {
-  name?: string
-  // biome-ignore lint/suspicious/noExplicitAny: the one-bag form is untypeable by construction — that is exactly why the two-arg form exists
-  on?: Record<string, ((ctx: any, ev: ClientEvent) => void) | ClientTransitionObject<any>>
-  // biome-ignore lint/suspicious/noExplicitAny: same
-  select?: Record<string, (ctx: any) => unknown>
-  [key: string]: unknown
-}
-
-const RESERVED = new Set(['name', 'on', 'select'])
-
-// Data-only: no behavior. Events stay structurally LOOSE (ClientEvent) on
-// purpose: data-only machines are the `bind:value` / hand-written `@set`
-// carriers until 2.0 removes `@set` — tightening them now would break that
-// still-supported surface. Tighten to `never` when `@set` goes.
+// Data-only: no behavior, no events. With `@set` gone (2.0) a machine with
+// no `on` map accepts NOTHING — its state is set at construction (a seed)
+// and read for display; `send` is a type error by construction.
 export function machine<C extends Record<string, unknown>>(
   context: C & { on?: never; select?: never; name?: never; events?: never },
-): MachineDef<C, ClientEvent, 'active', Record<string, never>>
+): MachineDef<C, never, 'active', Record<string, never>>
 // Derived union — no `events:` declared: event NAMES come from the `on` keys
 // (typo-safe send), payloads stay open. Zero authoring change. Ordered BEFORE
 // the declared overload: `events?: never` keeps declared calls falling through.
@@ -106,19 +90,15 @@ export function machine<
   context: C & { on?: never; select?: never; name?: never; events?: never },
   behavior: { name?: string; events: E; on?: TypedClientOnMap<C, E>; select?: S },
 ): MachineDef<C, E, 'active', S>
-// Behavior without `on` (selectors only): loose, as data-only.
+// Behavior without `on` (selectors only): derived state, still nothing to
+// send — events are `never`, as data-only.
 export function machine<
   C extends Record<string, unknown>,
   S extends Record<string, (ctx: C) => unknown>,
 >(
   context: C & { on?: never; select?: never; name?: never; events?: never },
   behavior: { name?: string; events?: never; on?: never; select?: S },
-): MachineDef<C, ClientEvent, 'active', S>
-/** @deprecated see LegacyMachineConfig */
-export function machine(
-  config: LegacyMachineConfig,
-  // biome-ignore lint/suspicious/noExplicitAny: legacy view is deliberately loose
-): MachineDef<Record<string, any>, ClientEvent, 'active', Record<string, (ctx: any) => any>>
+): MachineDef<C, never, 'active', S>
 export function machine(
   first: Record<string, unknown>,
   // Loose impl signature: the overloads above are the contract. `events` is a
@@ -126,23 +106,10 @@ export function machine(
   rawBehavior?: unknown,
 ): MachineDef {
   const behavior = rawBehavior as (ClientBehavior<never> & { events?: unknown }) | undefined
-  let context: Record<string, unknown>
-  let name: string | undefined
-  let on: Record<string, unknown>
-  let select: Record<string, unknown>
-  if (behavior !== undefined || !Object.keys(first).some((k) => RESERVED.has(k))) {
-    context = first
-    name = behavior?.name
-    on = (behavior?.on ?? {}) as Record<string, unknown>
-    select = (behavior?.select ?? {}) as Record<string, unknown>
-  } else {
-    // Legacy one-bag: context is every non-reserved key.
-    const { name: n, on: o = {}, select: s = {}, ...rest } = first as LegacyMachineConfig
-    context = rest
-    name = n
-    on = o as Record<string, unknown>
-    select = s as Record<string, unknown>
-  }
+  const context = first
+  const name = behavior?.name
+  const on = (behavior?.on ?? {}) as Record<string, unknown>
+  const select = (behavior?.select ?? {}) as Record<string, unknown>
   return defineMachine({
     name: name ?? 'ClientMachine',
     lifecycle: 'session',

package/src/client/use.ts

@@ -67,7 +67,14 @@ export interface CollectedActor {
 
 /** Active collector: `use()` registers its actor here during element
  *  construction, so `StatorElement` can start/seed/stop them on connect/disconnect.
- *  A stack supports nested construction (rare, but correct). */
+ *  A stack supports nested construction (rare, but correct).
+ *
+ *  Dual-bundle note (the clientId lesson): module state is PER BUNDLE, and
+ *  the page runtime and island modules are separate bundles. This stack is
+ *  safe because it is construction-scoped and both its writer (`use()`) and
+ *  its reader (`StatorElement`) always come from the SAME bundle as the
+ *  island class using them. State that must be PAGE-scoped (one value across
+ *  all bundles) must live on `window` — see client-id.ts. */
 const collectors: CollectedActor[][] = []
 
 export function pushCollector(): CollectedActor[] {
@@ -100,10 +107,7 @@ export function use<D extends MachineDef>(
         context: { ...(def.context as object), ...eager },
       }
     : undefined
-  // Client islands honor framework-internal events (`@set` for two-way
-  // `bind:value`); the actor lives in the browser and only its own compiled
-  // bind code sends them. Server actors deliberately do NOT (see createActor).
-  const actor = createActor(def as AnyMachineDef, { snapshot, internalEvents: true })
+  const actor = createActor(def as AnyMachineDef, { snapshot })
 
   // Register with the element under construction so its lifecycle owns the actor.
   const bucket = collectors[collectors.length - 1]

package/src/compiler/client-emit.ts

@@ -1,6 +1,6 @@
 import ts from 'typescript'
+import { elementMarkerSelector } from '../wire/island-markers.ts'
 import type { ClientDirective, ClientElement } from './client-script.ts'
-import { CompileError } from './diagnostics.ts'
 
 /**
  * Phase 3b stage 5 — emit the client entry module for a client component: the
@@ -14,7 +14,7 @@ import { CompileError } from './diagnostics.ts'
  */
 
 const PRIMITIVES =
-  "import { StatorElement, defineElement, use, machine, bind, bindSlot, effect, dispatch } from '@statorjs/stator/client'"
+  "import { StatorElement, defineElement, use, machine, bind, bindSlot, effect, dispatch, attrValue, setAttr } from '@statorjs/stator/client'"
 
 export interface EmitClientInput {
   /** The author's `<script>` source. */
@@ -53,7 +53,9 @@ export function emitClientModule(input: EmitClientInput): string {
     // Element wiring: every occurrence of the marker is wired — a marked
     // element inside a `.map()` repeats per row.
     const node = `n${i++}`
-    lines.push(`    for (const ${node} of this.querySelectorAll('[data-b="${marker}"]')) {`)
+    lines.push(
+      `    for (const ${node} of this.querySelectorAll(${JSON.stringify(elementMarkerSelector(marker))})) {`,
+    )
     for (const d of group) lines.push(`      ${wireDirective(node, d, members)}`)
     lines.push('    }')
   }
@@ -78,42 +80,14 @@ function wireDirective(node: string, d: ClientDirective, members: Set<string>):
     const handler = emitHandler(d.expr, members)
     return `${node}.addEventListener(${JSON.stringify(d.event)}, ${handler})`
   }
-  // bind:
+  // kind 'bind': an attribute-position client read() — one-way display.
   const target = d.target ?? 'text'
   const thunk = `() => (${rewriteMembers(d.expr, members)})`
   const deps = `[${d.deps.map((dep) => `this.${dep}`).join(', ')}]`
-
-  // value / checked are TWO-WAY: state→DOM (below) PLUS a DOM→state listener
-  // that `@set`s the bound context key. The expression must be a settable
-  // `<actor>.<key>` path (a derived selector can't be assigned).
-  if (target === 'value' || target === 'checked') {
-    const path = parseTwoWayPath(d.expr)
-    if (!path) {
-      throw new CompileError(
-        `stator: bind:${target}={${d.expr}} must bind to a settable context path ` +
-          `like \`actor.key\` (a derived value can't be two-way bound).`,
-      )
-    }
-    const writer = emitWriter(node, target)
-    const read = target === 'checked' ? `${node}.checked` : `${node}.value`
-    const guard = target === 'value' ? `if (e.isComposing) return; ` : ''
-    const setter =
-      `${node}.addEventListener(${JSON.stringify(target === 'value' ? 'input' : 'change')}, (e) => { ` +
-      `${guard}this.${path.actor}.send({ type: '@set', key: ${JSON.stringify(path.key)}, value: ${read} }) })`
-    return `this.track(bind(${deps}, ${thunk}, ${writer}));\n      ${setter}`
-  }
-
   const writer = emitWriter(node, target)
   return `this.track(bind(${deps}, ${thunk}, ${writer}))`
 }
 
-/** Parse a two-way bind expression `actor.key` into its parts; null if it isn't
- *  a simple single-level member access (not assignable). */
-function parseTwoWayPath(expr: string): { actor: string; key: string } | null {
-  const m = expr.trim().match(/^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/)
-  return m ? { actor: m[1]!, key: m[2]! } : null
-}
-
 /** on: handler — a bare method reference becomes `(e) => this.m(e)`; any other
  *  expression is used directly (with member references rewritten). */
 function emitHandler(expr: string, members: Set<string>): string {
@@ -126,21 +100,13 @@ function emitHandler(expr: string, members: Set<string>): string {
 
 function emitWriter(node: string, target: string): string {
   switch (target) {
-    case 'text':
-      return `(v) => { ${node}.textContent = v == null ? '' : String(v) }`
-    case 'html':
-      return `(v) => { ${node}.innerHTML = v == null ? '' : String(v) }`
-    case 'value':
-      // Loop-break: only write when the DOM differs, so the echo from the user's
-      // own keystroke no-ops and the caret is preserved.
-      return `(v) => { const s = v == null ? '' : String(v); if (${node}.value !== s) ${node}.value = s }`
     case 'disabled':
     case 'hidden':
-    case 'checked':
+      // Boolean IDL properties write as properties, not attributes.
       return `(v) => { if (${node}.${target} !== !!v) ${node}.${target} = !!v }`
     default:
-      // arbitrary attribute
-      return `(v) => { if (v == null || v === false) ${node}.removeAttribute(${JSON.stringify(target)}); else ${node}.setAttribute(${JSON.stringify(target)}, v === true ? '' : String(v)) }`
+      // arbitrary attribute — the shared attr contract (wire/attr-value.ts)
+      return `(v) => setAttr(${node}, ${JSON.stringify(target)}, attrValue(v))`
   }
 }
 

package/src/compiler/dts.ts

@@ -21,7 +21,32 @@ export function generateDts(
   if ((opts.kind ?? 'component') === 'route') return null
 
   const { frontmatter, template, scripts } = splitStator(source)
-  const { hoisted, propsType } = extractFrontmatterTypes(frontmatter)
+  const { hoisted } = extractFrontmatterTypes(frontmatter)
+  const { propsT, needsReadResult } = statorPropsType(frontmatter, template, scripts)
+
+  const lines = ["import type { HtmlFragment } from '@statorjs/stator/template'"]
+  if (needsReadResult) {
+    lines.push("import type { ReadResult as __SReadResult } from '@statorjs/stator/template'")
+  }
+  if (hoisted) lines.push(hoisted)
+  lines.push('')
+  lines.push(`declare const _default: (props: ${propsT}) => HtmlFragment`)
+  lines.push('export default _default')
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * The component's props type — THE shared computation for the `.d.ts`
+ * generator (tsc) and the language-server virtual emit (editor), islands
+ * included, so the two can't disagree. `needsReadResult` means the type
+ * references `__SReadResult<T>`, which the caller must bring into scope.
+ */
+export function statorPropsType(
+  frontmatter: string,
+  template: string,
+  scripts: string[],
+): { propsT: string; needsReadResult: boolean } {
+  const { propsType } = extractFrontmatterTypes(frontmatter)
   let propsT = componentPropsType(propsType, template)
   let needsReadResult = false
 
@@ -29,9 +54,10 @@ export function generateDts(
   // `Stator.props`. Each attr accepts its coerced kind OR a live `read()`
   // binding — the compiler lowers read() island props to live attr bindings,
   // so the type surface must admit both.
-  if (!propsType && scripts.length > 0) {
+  const classes = scripts.length > 0 ? analyzeScriptClasses(scripts.join('\n')) : []
+  if (!propsType && classes.length > 0) {
     const attrs = new Map<string, string>()
-    for (const cls of analyzeScriptClasses(scripts.join('\n'))) {
+    for (const cls of classes) {
       for (const [key, kind] of cls.staticAttrs) attrs.set(key, kind)
     }
     if (attrs.size > 0) {
@@ -50,16 +76,7 @@ export function generateDts(
       propsT = '{ [prop: string]: unknown }'
     }
   }
-
-  const lines = ["import type { HtmlFragment } from '@statorjs/stator/template'"]
-  if (needsReadResult) {
-    lines.push("import type { ReadResult as __SReadResult } from '@statorjs/stator/template'")
-  }
-  if (hoisted) lines.push(hoisted)
-  lines.push('')
-  lines.push(`declare const _default: (props: ${propsT}) => HtmlFragment`)
-  lines.push('export default _default')
-  return `${lines.join('\n')}\n`
+  return { propsT, needsReadResult }
 }
 
 /**

package/src/compiler/lower.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { elementMarker, ISLAND_MARKER_ATTR, slotMarker } from '../wire/island-markers.ts'
 import { type ClientDirective, inferDeps } from './client-script.ts'
 import { CompileError, type DiagnosticLocation, locAt } from './diagnostics.ts'
 
@@ -90,10 +91,11 @@ export interface LowerOptions {
    *  validation is skipped for that component. Supplied by the Vite plugin /
    *  build, which can read sibling `.stator` files. */
   resolveRegions?: (componentName: string) => Set<string> | null
-  /** Client-component mode (Phase 3b). When set, `on:`/`bind:` directives are
-   *  *collected* (with a node marker injected) instead of emitted as server
-   *  directives — the generated client class wires them. `useFields` is the set
-   *  of `use()` actor names (for dep inference); `directives` is the out-list. */
+  /** Client-component mode. When set, `on:` directives and client-machine
+   *  `read()`s are *collected* (with node/slot markers injected) instead of
+   *  emitted as server directives — the generated client class wires them.
+   *  `useFields` is the set of `use()` actor names (for dep inference);
+   *  `directives` is the out-list. */
   client?: {
     useFields: Set<string>
     directives: ClientDirective[]
@@ -185,6 +187,17 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
     ts.isIdentifier(n.arguments[0]) &&
     opts.client.useFields.has(n.arguments[0].text)
 
+  /** `bind:` was removed in 2.0 — display folds into `read()`, input capture
+   *  is a typed commit event. One error, both compile modes. */
+  const bindRemoved = (name: string, at: DiagnosticLocation | undefined): CompileError =>
+    new CompileError(
+      `stator: bind:${name} was removed in 2.0. Display state with read() — ` +
+        `\`{read(m, (s) => s.value)}\` in text position, \`attr={read(m, …)}\` on an ` +
+        `attribute — and capture input at a commit boundary with a typed event ` +
+        `(ref:/FormData + send/dispatch). See the forms guide.`,
+      at,
+    )
+
   /** A client read as a plain expression: `(selector)(field)`. Client-emit's
    *  member rewriting turns `field` (and any use-field the selector closes
    *  over) into `this.field`. */
@@ -197,7 +210,7 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
   const allocSlotMarker = (): string => {
     const client = opts.client
     if (!client) throw new CompileError('stator: internal — slot marker outside client mode')
-    return `s${client.directives.filter((d) => d.kind === 'slot').length}`
+    return slotMarker(client.directives.filter((d) => d.kind === 'slot').length)
   }
 
   /** Shell expressions must not contain a client-machine read — the shell
@@ -534,15 +547,14 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
       const lowered = lowerAttribute(attr)
       if (lowered) out += ` ${lowered}`
     }
-    if (collected?.marker) out += ` data-b="${collected.marker}"`
+    if (collected?.marker) out += ` ${ISLAND_MARKER_ATTR}="${collected.marker}"`
     return out
   }
 
-  // Collect a client element's wiring — on:/bind: directives plus plain
-  // attributes whose value is a client-machine read — into
-  // `opts.client.directives` under a single node marker. Returns the marker
-  // (if any wiring was found) and the set of consumed attribute nodes the
-  // shell must not render.
+  // Collect a client element's wiring — on: directives plus plain attributes
+  // whose value is a client-machine read — into `opts.client.directives`
+  // under a single node marker. Returns the marker (if any wiring was found)
+  // and the set of consumed attribute nodes the shell must not render.
   const collectClientDirectives = (
     attrs: ts.JsxAttributes,
   ): { marker?: string; consumed: Set<ts.JsxAttribute> } => {
@@ -555,22 +567,13 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
       if (ts.isJsxNamespacedName(attr.name)) {
         const ns = attr.name.namespace.text
         const name = attr.name.name.text
-        if (ns !== 'on' && ns !== 'bind') continue
+        if (ns === 'bind') throw bindRemoved(name, loc(attr))
+        if (ns !== 'on') continue
         const expr = attrExpr(attr)
         if (!expr) {
-          throw new CompileError(`stator: ${ns}:${name} requires a value ({...})`, loc(attr))
-        }
-        if (ns === 'on') {
-          pending.push({ marker: '', kind: 'on', event: name, expr, deps: [] })
-        } else {
-          pending.push({
-            marker: '',
-            kind: 'bind',
-            target: name,
-            expr,
-            deps: inferDeps(expr, client.useFields),
-          })
+          throw new CompileError(`stator: on:${name} requires a handler ({...})`, loc(attr))
         }
+        pending.push({ marker: '', kind: 'on', event: name, expr, deps: [] })
         consumed.add(attr)
         continue
       }
@@ -602,7 +605,9 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
     if (pending.length === 0) return { consumed }
     // One marker per element (sequential over ELEMENT markers — slots have
     // their own `s<N>` namespace).
-    const marker = `b${new Set(client.directives.filter((d) => d.kind !== 'slot').map((d) => d.marker)).size}`
+    const marker = elementMarker(
+      new Set(client.directives.filter((d) => d.kind !== 'slot').map((d) => d.marker)).size,
+    )
     for (const d of pending) {
       d.marker = marker
       client.directives.push(d)
@@ -686,10 +691,8 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
         if (meta) meta.refs.add(name)
         return `data-ref=${JSON.stringify(name)}`
       }
-      throw new CompileError(
-        `stator: directive "${ns}:${name}" is not supported yet (Phase 3b)`,
-        loc(attr),
-      )
+      if (ns === 'bind') throw bindRemoved(name, loc(attr))
+      throw new CompileError(`stator: directive "${ns}:${name}" is not supported`, loc(attr))
     }
 
     const name = attr.name.getText(sf)
@@ -732,10 +735,11 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
       if (ts.isJsxNamespacedName(attr.name)) {
         const ns = attr.name.namespace.text
         const dirName = attr.name.name.text
+        if (ns === 'bind') throw bindRemoved(dirName, loc(attr))
         if (ns !== 'on') {
           throw new CompileError(
             `stator: forwarding "${ns}:${dirName}" to a component isn't supported yet — only ` +
-              `on:* event directives forward. Apply bind:/ref: on an element directly.`,
+              `on:* event directives forward. Apply ref: on an element directly.`,
             loc(attr),
           )
         }

package/src/compiler/virtual-code.ts

@@ -20,7 +20,7 @@
 
 import ts from 'typescript'
 import { analyzeScriptClasses } from './client-script.ts'
-import { componentPropsType, extractFrontmatterTypes } from './dts.ts'
+import { statorPropsType } from './dts.ts'
 import { type ScannedRegions, scanRegions } from './split.ts'
 
 /** A contiguous run mapping generated code back to source, 1:1 over its length. */
@@ -174,7 +174,14 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
   // is typed from `Stator.props<P>()` (same extraction as the .d.ts generator),
   // so `<Component bad={...}/>` in OTHER .stator files is checked in-editor.
   // Named prop types resolve because their type/interface decls hoisted above.
-  const propsT = componentPropsType(extractFrontmatterTypes(fm).propsType, regions.template.content)
+  const { propsT, needsReadResult } = statorPropsType(
+    fm,
+    regions.template.content,
+    regions.scripts.map((s) => s.content),
+  )
+  if (needsReadResult) {
+    code += "type __SReadResult<T> = import('@statorjs/stator/template').ReadResult<T>\n"
+  }
   code += `export default function (_props: ${propsT}) {\n`
   for (const seg of body) {
     code += '  '

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/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/html-attributes.ts

@@ -33,10 +33,7 @@ export interface StatorDirectiveAttributes {
   'class:list'?: unknown
   'style:list'?: unknown
   [key: `on:${string}`]: unknown
-  [key: `bind:${string}`]: unknown
   [key: `ref:${string}`]: unknown
-  [key: `class:${string}`]: unknown
-  [key: `style:${string}`]: unknown
 }
 
 /** ARIA — `role` plus the open-ended `aria-*` family. */

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,21 +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') {
-    // Same boolean semantics as the read-binding and item-read paths:
-    // false/null/undefined → attribute ABSENT (`checked={expr}` must be able
-    // to render unchecked; a static render must agree with what a live patch
-    // of the same attribute would do), true → present-and-empty. Previously
-    // this path stringified — `checked={false}` rendered `checked="false"`,
-    // a PRESENT (thus truthy) boolean attribute.
-    if (value === false || value === null || value === undefined) {
-      builder.omitCurrentAttribute()
-    } else if (value !== true) {
-      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`)
@@ -172,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') {
@@ -193,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
   }
@@ -226,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') {
@@ -243,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,17 +8,12 @@ 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'

package/src/wire/apply.ts

@@ -8,6 +8,7 @@
  * CustomEvent on `window` (the inspector's contract), regardless of which
  * path applied it.
  */
+import { setAttr } from './attr-value.ts'
 import type { Directive, Patch } from './index.ts'
 import {
   elementAt,
@@ -74,8 +75,7 @@ function applyPatch(
       return null
     }
     if (patch.op === 'text') element.textContent = patch.value
-    else if (patch.value === null) element.removeAttribute(patch.name)
-    else element.setAttribute(patch.name, patch.value)
+    else setAttr(element, patch.name, patch.value)
     return element
   }
 

package/src/wire/attr-value.ts

@@ -0,0 +1,55 @@
+import { isUrlAttribute, safeAttrUrl } from './safe-url.ts'
+
+/**
+ * THE attribute-value contract — one implementation for every tier that
+ * writes an attribute: static render (template/html.ts), the live diff
+ * (server/recompute.ts), the island writer codegen (compiler/client-emit.ts,
+ * via the client re-export), and the wire applier (wire/apply.ts).
+ *
+ * Boolean-absent semantics: `false`/`null`/`undefined` → `null`, meaning the
+ * attribute is ABSENT (`checked={expr}` must be able to render unchecked, and
+ * a static render must agree with what a live patch of the same attribute
+ * does). `true` → present-and-empty. Arrays join with no separator (matching
+ * text interpolation); everything else stringifies.
+ *
+ * History: this contract used to live in four drifting copies, and two of
+ * them disagreed in ways users hit — `checked={false}` rendered
+ * `checked="false"` on the static path, and array values patched as "a,b"
+ * but rendered as "ab". One implementation, so the seams can't disagree.
+ */
+export function attrValue(v: unknown): string | null {
+  if (v === false || v === null || v === undefined) return null
+  if (v === true) return ''
+  return stringifyAttr(v)
+}
+
+function stringifyAttr(v: unknown): string {
+  if (v == null) return ''
+  if (typeof v === 'string') return v
+  if (Array.isArray(v)) return v.map(stringifyAttr).join('')
+  return String(v)
+}
+
+/** The text-position value contract, shared by static render and text
+ *  patches: null/undefined → empty, arrays join with no separator (an
+ *  interpolated list of fragments/strings renders concatenated, not
+ *  comma-joined), everything else stringifies. */
+export function textValue(v: unknown): string {
+  return stringifyAttr(v)
+}
+
+/** Scheme guard for url-bearing attributes (href/src/…): strip a
+ *  javascript:/vbscript: value whether it arrives at first render or through
+ *  a later diff. `null` (attribute-absent) passes through. */
+export function sanitizeAttr(name: string, value: string): string
+export function sanitizeAttr(name: string, value: string | null): string | null
+export function sanitizeAttr(name: string, value: string | null): string | null {
+  if (value === null) return null
+  return isUrlAttribute(name) ? safeAttrUrl(value) : value
+}
+
+/** The DOM half of the contract: `null` removes, a string sets. */
+export function setAttr(el: Element, name: string, value: string | null): void {
+  if (value === null) el.removeAttribute(name)
+  else el.setAttribute(name, value)
+}

package/src/wire/island-markers.ts

@@ -0,0 +1,22 @@
+/**
+ * Island marker formats — the compiler↔island-runtime contract, in one place
+ * so codegen (compiler/lower.ts, compiler/client-emit.ts) and the runtime
+ * (client/bind.ts's bindSlot, the generated querySelector calls) can't drift.
+ *
+ * - ELEMENT markers: `data-b="b<N>"` on an element whose on:/bind:/read()
+ *   attribute wiring the island's setup() attaches. Every occurrence of a
+ *   marker is wired (a marked element inside a `.map()` repeats per row).
+ * - TEXT SLOT markers: an `<!--s<N>-->` comment where a client-machine
+ *   `read()` sat in text position; the runtime materializes one text node
+ *   after each occurrence. The comment's data IS the marker string.
+ */
+
+export const ISLAND_MARKER_ATTR = 'data-b'
+
+export const elementMarker = (i: number): string => `b${i}`
+
+export const slotMarker = (i: number): string => `s${i}`
+
+/** CSS selector for every occurrence of an element marker. */
+export const elementMarkerSelector = (marker: string): string =>
+  `[${ISLAND_MARKER_ATTR}="${marker}"]`