@statorjs/stator 1.8.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.8.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.8.0"
+    "@statorjs/stator": "2.0.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/bind.ts

@@ -33,6 +33,40 @@ export function bind(
   }
 }
 
+/**
+ * Text-slot binding for a client-machine `read()` in text position. The
+ * compiler renders an `<!--sN-->` comment where the expression sat; this finds
+ * every occurrence of the marker under `root` (a marker inside a `.map()`
+ * repeats per row), materializes one text node after each, and binds them all
+ * to the thunk through the normal `bind()` diff loop. Returns a disposer.
+ */
+export function bindSlot(
+  root: Node,
+  marker: string,
+  deps: ClientInstanceBase[],
+  compute: () => unknown,
+): () => void {
+  // Manual walk, not TreeWalker: happy-dom's walker prunes descent at
+  // non-matching nodes, so a SHOW_COMMENT filter never reaches nested comments
+  // — and the manual loop is as small as the workaround discussion.
+  const texts: Text[] = []
+  const stack: Node[] = [root]
+  while (stack.length > 0) {
+    const n = stack.pop() as Node
+    if (n.nodeType === 8 /* COMMENT_NODE */ && (n as Comment).data === marker) {
+      const t = document.createTextNode('')
+      n.parentNode?.insertBefore(t, n.nextSibling)
+      texts.push(t)
+    } else {
+      for (let c = n.firstChild; c; c = c.nextSibling) stack.push(c)
+    }
+  }
+  return bind(deps, compute, (v) => {
+    const s = v == null ? '' : String(v)
+    for (const t of texts) if (t.data !== s) t.data = s
+  })
+}
+
 /**
  * Imperative reactivity escape hatch: run `fn` now and again whenever any
  * dependency changes (no diffing — `fn` owns its own DOM writes). The lower-

package/src/client/client-id.ts

@@ -4,10 +4,25 @@
  * diff baseline WITHOUT re-sending patches the POST response already
  * delivered (text/attr dupes are invisible; keyed inserts are not).
  */
-export const clientId: string =
-  typeof crypto !== 'undefined' && 'randomUUID' in crypto
+function freshId(): string {
+  return typeof crypto !== 'undefined' && 'randomUUID' in crypto
     ? crypto.randomUUID()
     : `c${Math.random().toString(36).slice(2)}`
+}
+
+/** One identity per PAGE, not per bundle. The page runtime (a classic-script
+ *  bundle) and island modules (the Vite/asset graph) each carry their own copy
+ *  of this module — a plain module-scoped id would mint one per copy, the SSE
+ *  connection and an island's dispatch would disagree, and fan-out's
+ *  originator skip would never fire (double-applying keyed inserts on the
+ *  dispatching page). The window slot is the page-load singleton both copies
+ *  converge on. */
+export const clientId: string = (() => {
+  if (typeof window === 'undefined') return freshId()
+  const w = window as { __statorClientId?: string }
+  w.__statorClientId ??= freshId()
+  return w.__statorClientId
+})()
 
 /** Per-dispatch idempotency key: the server replays a duplicate POST's cached
  *  response instead of re-applying it, which is what makes retrying a lost

package/src/client/index.ts

@@ -4,11 +4,12 @@
  * island needs; these are also the symbols an author references directly.
  */
 
-export { bind, effect } from './bind.ts'
+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

@@ -22,9 +22,30 @@ import { defineMachine, type MachineDef } from '../engine/index.ts'
  * is just a label and need not be unique.
  */
 
-/** Client events are structurally loose — the terse form declares no union. */
+/** The loose client event shape — the fallback when a machine declares no
+ *  union and has no `on` map to derive one from. */
 export type ClientEvent = { type: string; [k: string]: unknown }
 
+/** Event-name union derived from an `on` map: the NAMES are typed (a `send`
+ *  typo is a compile error), payloads stay structurally open. The
+ *  zero-ceremony tier of client event typing. */
+export type DerivedEvents<O> = {
+  [K in keyof O & string]: { type: K } & Record<string, unknown>
+}[keyof O & string]
+
+/** The `on` map for a machine with a DECLARED event union: keys are the
+ *  declared event names, and each handler sees its event narrowed — no
+ *  annotations needed. Mirrors the server `defineMachine` experience. */
+export type TypedClientOnMap<C, E extends { type: string }> = {
+  [K in E['type']]?:
+    | ((ctx: C, ev: Extract<E, { type: K }>) => void)
+    | {
+        when?: (ctx: C, ev: Extract<E, { type: K }>) => boolean
+        do?: (ctx: C, ev: Extract<E, { type: K }>) => void
+        emit?: string | string[]
+      }
+}
+
 interface ClientTransitionObject<C> {
   when?: (ctx: C, ev: ClientEvent) => boolean
   do?: (ctx: C, ev: ClientEvent) => void
@@ -42,59 +63,53 @@ 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, no selectors.
+// 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 },
-): MachineDef<C, ClientEvent, 'active', Record<string, never>>
-// Data + behavior: handlers and selectors typed against the context.
+  context: C & { on?: never; select?: never; name?: never; events?: 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.
 export function machine<
   C extends Record<string, unknown>,
+  O extends Record<string, ClientTransition<C>>,
   S extends Record<string, (ctx: C) => unknown>,
 >(
-  context: C & { on?: never; select?: never; name?: never },
-  behavior: ClientBehavior<C> & { 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>>
+  context: C & { on?: never; select?: never; name?: never; events?: never },
+  behavior: { name?: string; events?: never; on: O; select?: S },
+): MachineDef<C, DerivedEvents<O>, 'active', S>
+// Declared union (`events: {} as E`) — mirrors defineMachine: full payload
+// typing on send, handlers narrowed per key, undeclared handler keys error.
+export function machine<
+  C extends Record<string, unknown>,
+  E extends { type: string },
+  S extends Record<string, (ctx: C) => unknown>,
+>(
+  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): 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, never, 'active', S>
 export function machine(
   first: Record<string, unknown>,
-  behavior?: ClientBehavior<never>,
+  // Loose impl signature: the overloads above are the contract. `events` is a
+  // type-only phantom (`{} as E`) — the runtime never reads it.
+  rawBehavior?: unknown,
 ): MachineDef {
-  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 behavior = rawBehavior as (ClientBehavior<never> & { events?: unknown }) | undefined
+  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

@@ -2,6 +2,7 @@ import {
   type AnyActor,
   type AnyMachineDef,
   createActor,
+  type EventOf,
   type MachineDef,
   type Snapshot,
 } from '../engine/index.ts'
@@ -17,17 +18,30 @@ const CLIENT_HELPERS = {
   ),
 } as never
 
+/** Event names sendable as a bare string: only members whose shape is
+ *  satisfied by `{ type }` alone — an event with a required payload must be
+ *  sent as an object. (For the loose ClientEvent this admits any string,
+ *  preserving the untyped tier's behavior.) */
+export type BareEventTypes<E extends { type: string }> = E extends { type: infer T extends string }
+  ? { type: T } extends E
+    ? T
+    : never
+  : never
+
 /**
  * The client-side reactive handle for a machine. Returned by `use()`, held as a
  * class field (`qty = use(Qty)`). Exposes:
  *   - each selector / context key as a live property (read through the actor's
  *     current snapshot on every access — the client mirror of the server
  *     instance proxy). This is what `bind:text={qty.count}` reads.
- *   - `send(event)` to drive transitions.
+ *   - `send(event)` to drive transitions, typed to the machine's event union
+ *     (declared `events:`, derived from `on` keys, or loose for data-only).
  *   - the underlying actor (non-enumerable) for the binding loop to subscribe.
  */
-export interface ClientInstanceBase {
-  send(event: { type: string; [k: string]: unknown } | string): void
+export interface ClientInstanceBase<
+  E extends { type: string } = { type: string; [k: string]: unknown },
+> {
+  send(event: E | BareEventTypes<E>): void
   /** @internal — the actor a binding subscribes to. */
   readonly __actor: AnyActor
 }
@@ -41,7 +55,8 @@ type ClientView<D> =
       }
     : unknown
 
-export type ClientInstance<D extends MachineDef = MachineDef> = ClientInstanceBase & ClientView<D>
+export type ClientInstance<D extends MachineDef = MachineDef> = ClientInstanceBase<EventOf<D>> &
+  ClientView<D>
 
 /** An actor plus an optional deferred seed thunk — evaluated at the element's
  *  connect (when attributes are available), not at construction. */
@@ -52,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[] {
@@ -85,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, 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. */
@@ -40,9 +40,22 @@ export function emitClientModule(input: EmitClientInput): string {
   const lines: string[] = []
   let i = 0
   for (const [marker, group] of byMarker) {
+    if (group[0]?.kind === 'slot') {
+      // Text slot: the runtime finds every `<!--sN-->` comment, materializes a
+      // text node per occurrence, and binds them all to the one thunk.
+      for (const d of group) {
+        const thunk = `() => (${rewriteMembers(d.expr, members)})`
+        const deps = `[${d.deps.map((dep) => `this.${dep}`).join(', ')}]`
+        lines.push(`    this.track(bindSlot(this, ${JSON.stringify(marker)}, ${deps}, ${thunk}))`)
+      }
+      continue
+    }
+    // Element wiring: every occurrence of the marker is wired — a marked
+    // element inside a `.map()` repeats per row.
     const node = `n${i++}`
-    lines.push(`    const ${node} = this.querySelector('[data-b="${marker}"]')`)
-    lines.push(`    if (${node}) {`)
+    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('    }')
   }
@@ -67,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 {
@@ -115,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/client-script.ts

@@ -216,9 +216,13 @@ function loc(file?: string): DiagnosticLocation | undefined {
  * emits the wiring from this.
  */
 export interface ClientDirective {
-  /** Unique node marker, e.g. `b0`. The element gets `data-b="b0"`. */
+  /** Node marker. Element wiring (`on`/`bind`): `b<N>`, rendered as
+   *  `data-b="b<N>"` and resolved via querySelectorAll (every occurrence is
+   *  wired — a marker inside a `.map()` repeats). Text slots (`slot`): `s<N>`,
+   *  rendered as an `<!--s<N>-->` comment the client materializes a text node
+   *  after. */
   marker: string
-  kind: 'on' | 'bind'
+  kind: 'on' | 'bind' | 'slot'
   /** on: the DOM event name (`click`). */
   event?: string
   /** bind: the target (`text` / `html` / `value` / `checked` / `disabled` / attr). */

package/src/compiler/compile.ts

@@ -48,7 +48,7 @@ export interface CompileResult {
 }
 
 const PRIMITIVES_IMPORT =
-  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList } from '@statorjs/stator/template'"
+  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList, spreadAttrs } from '@statorjs/stator/template'"
 
 export interface CompileOptions {
   /** Stable id for the component (file path). Used for the scope hash so the
@@ -186,7 +186,7 @@ function compileClient(
   const attrDecl = `{ ${[...cls.staticAttrs].map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')} }`
   const rootScope = ctx.scopeAttr ? ` data-s-${ctx.hash}` : ''
   const serverCode = [
-    "import { html, read, each, when, match, defer, on, classList, styleList, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
+    "import { html, read, each, when, match, defer, on, classList, styleList, spreadAttrs, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
     '',
     `export default function (props = {}) {`,
     `  const __inner = ${innerExpr}`,
@@ -373,6 +373,26 @@ function processFrontmatter(
         repls.push([n.getStart(sf), n.getEnd(), bound])
         return
       }
+      if (ts.isCallExpression(n) && isStatorCall(n, 'forwarded')) {
+        if (kind === 'route') {
+          throw new CompileError(
+            'stator: Stator.forwarded() is only available in a component — it reads a directive ' +
+              'forwarded from a parent (`<Child on:click={h}/>`), and a route has no parent.',
+            locInFm(n),
+          )
+        }
+        const arg = n.arguments[0]
+        if (!arg) {
+          throw new CompileError(
+            "stator: Stator.forwarded(name) takes a directive name, e.g. Stator.forwarded('on:click')",
+            locInFm(n),
+          )
+        }
+        // The parent packs component-level directives into a reserved `$directives`
+        // prop; this reads one back so the author can re-attach it where they like.
+        repls.push([n.getStart(sf), n.getEnd(), `props.$directives?.[${arg.getText(sf)}]`])
+        return
+      }
       if (ts.isPropertyAccessExpression(n) && isStatorMember(n, 'request')) {
         requireRoute('Stator.request', kind, locInFm(n))
         repls.push([n.getStart(sf), n.getEnd(), '__req'])

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) {
@@ -43,18 +69,14 @@ export function generateDts(
       // props an island's SERVER-rendered markup may consume (they never
       // cross the attr wire, so `static attrs` can't know about them).
       propsT = `{ ${fields} } & { [prop: string]: unknown }`
+    } else {
+      // No declared attrs, but the hydrate contract still holds: an island's
+      // server shell may consume any props its markup references. A closed
+      // `Record<string, never>` here would reject every use site.
+      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/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. */
@@ -92,7 +92,8 @@ function injectImports(globals: string[], modulePath: string, userCode: string):
 // `Stator.reads` binding unassignable to component props.
 const AMBIENT_TYPE_IMPORTS =
   "import type { AnyMachineDef as __SMachineDef } from '@statorjs/stator/machine';\n" +
-  "import type { InstanceOf as __SInstanceOf } from '@statorjs/stator/template';\n"
+  "import type { InstanceOf as __SInstanceOf } from '@statorjs/stator/template';\n" +
+  "import type { StatorIntrinsicElements as __SIntrinsics } from '@statorjs/stator/template';\n"
 
 /**
  * Per-file ambient scaffold prepended to every virtual TSX. `Stator` (the macro
@@ -108,12 +109,13 @@ const AMBIENT_TYPE_IMPORTS =
 const STATOR_AMBIENT = `declare const Stator: {
   props<P>(): P;
   reads<const T extends readonly __SMachineDef[]>(defs: T): { -readonly [K in keyof T]: __SInstanceOf<T[K]> };
+  forwarded(name: \`on:\${string}\`): (() => unknown) | undefined;
   request: any;
   response: { status: number; headers: Record<string, string>; cookies: any };
 };
 declare global {
   namespace JSX {
-    interface IntrinsicElements extends Record<string, any> {}
+    interface IntrinsicElements extends __SIntrinsics {}
   }
 }
 `
@@ -172,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 += '  '