@statorjs/stator 1.0.0

package/src/server/session-runtime.ts

@@ -0,0 +1,242 @@
+import { createActor, type EffectInvocation, type Snapshot } from '../engine/index.ts'
+import type { AnyMachineDef } from './define-machine.ts'
+import { type DispatchContext, recordTouch, withDispatchContext } from './dispatch-context.ts'
+import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
+import { buildDispatchEvent, MAX_CASCADE_DEPTH, type MachineStore } from './machine-store.ts'
+import { serverReadsResolver } from './reads-helpers.ts'
+
+/**
+ * Per-request scope for session-lifecycle machine actors. Created at the
+ * top of an HTTP handler, populated by `loadGraph` (which pulls only the
+ * machines this request needs from the Store and hydrates transient
+ * actors), and disposed at the bottom of the handler.
+ *
+ * Subscription wiring uses cross-actor listeners installed via
+ * `actor.on(...)`. Because the actors are transient, the wiring is rebuilt
+ * per request — never reused across requests.
+ *
+ * Same shape will host SSE connection lifetime in V1: the connection's
+ * runtime simply lives longer (one runtime per open connection, not one
+ * per request), and `processEvent` is invoked when an out-of-band state
+ * change touches a machine the connection's route reads.
+ */
+export class SessionRuntime {
+  private actors = new Map<string, InstanceHandle>()
+  private wired = false
+  /** Synchronous emit→subscribe cascade depth + trail for THIS runtime. A
+   *  subscription cycle would otherwise recurse to a bare stack overflow;
+   *  the cap converts it into an error that names the loop. */
+  private cascadeDepth = 0
+  private cascadeTrail: string[] = []
+  /** Effects surfaced during processEvent, queued until the entry point has
+   *  persisted and released the session lock (see server/effects.ts). */
+  private pendingEffects: EffectInvocation[] = []
+
+  constructor(
+    readonly sessionId: string,
+    readonly store: MachineStore,
+  ) {}
+
+  /**
+   * Ensure the given machines (and everything reachable via their `reads:`
+   * and `subscribes:` declarations + machines that subscribe back to them)
+   * are loaded into this runtime. Idempotent: calling twice with overlapping
+   * inputs costs only the de-duped delta.
+   */
+  async loadGraph(seeds: ReadonlyArray<AnyMachineDef>): Promise<void> {
+    const queue = [...seeds]
+    while (queue.length > 0) {
+      const def = queue.shift()!
+      if (def.lifecycle !== 'session') continue
+      if (this.actors.has(def.name)) continue
+      await this.loadOne(def)
+      queue.push(...def.reads)
+      for (const sub of def.subscribes) queue.push(sub.from)
+      for (const sub of this.store.subscribersOf(def.name)) {
+        const targetDef = this.store.getDef(sub.targetName)
+        if (targetDef) queue.push(targetDef)
+      }
+    }
+  }
+
+  private async loadOne(def: AnyMachineDef): Promise<void> {
+    const persisted = await this.store.persistence.get(this.sessionId, def.name)
+    const actor = createActor(def, {
+      snapshot: persisted !== null ? (persisted as Snapshot<object>) : undefined,
+      resolveHelpers: serverReadsResolver(def),
+      // Server plane: never run effects inline — queue them for the entry
+      // point to schedule after persist + lock release.
+      onEffect: (invocation) => this.pendingEffects.push(invocation),
+    }).start()
+    this.actors.set(
+      def.name,
+      createInstanceProxy(def, actor, (name) => this.proxyFor(name)),
+    )
+  }
+
+  /**
+   * Replace a session actor with a fresh hydration from the Store. Used by
+   * fan-out before recomputing a long-lived SSE connection's diffs: the
+   * mutation happened in ANOTHER runtime (a POST or an effect completion)
+   * and only exists in persistence — this runtime's in-memory actor is
+   * frozen at whatever the connection last saw. Subscription listeners are
+   * NOT rewired onto the new actor; connection runtimes are read-only diff
+   * targets and never dispatch.
+   */
+  async rehydrate(name: string): Promise<void> {
+    const def = this.store.getDef(name)
+    if (def?.lifecycle !== 'session' || !this.actors.has(name)) return
+    const persisted = await this.store.persistence.get(this.sessionId, def.name)
+    const actor = createActor(def, {
+      snapshot: persisted !== null ? (persisted as Snapshot<object>) : undefined,
+      resolveHelpers: serverReadsResolver(def),
+      onEffect: (invocation) => this.pendingEffects.push(invocation),
+    }).start()
+    this.actors.get(name)?.actor.stop()
+    this.actors.set(
+      name,
+      createInstanceProxy(def, actor, (n) => this.proxyFor(n)),
+    )
+  }
+
+  /** Lifecycle of a machine by name, for fan-out applicability decisions. */
+  lifecycleOf(name: string): 'session' | 'app' | undefined {
+    return this.store.getDef(name)?.lifecycle
+  }
+
+  /** Hand queued effect invocations to the scheduler, clearing the queue. */
+  drainPendingEffects(): EffectInvocation[] {
+    const drained = this.pendingEffects
+    this.pendingEffects = []
+    return drained
+  }
+
+  /**
+   * Install actor.on listeners for every subscription whose source is a
+   * session-machine loaded in this runtime. The target may be:
+   *   - another session-machine in this runtime (session→session)
+   *   - an app-machine in the long-lived appInstances (session→app)
+   * App→session is blocked at validation; app→app is wired at app boot.
+   *
+   * Cross-lifecycle (session→app) subscriptions inject `sourceSessionId`
+   * into the dispatched event so the app receiver can correlate which
+   * session emitted it.
+   *
+   * Must be called before any event is sent. Idempotent.
+   */
+  wireSubscriptions(): void {
+    if (this.wired) return
+    this.wired = true
+
+    for (const [sourceName, sourceHandle] of this.actors) {
+      for (const sub of this.store.subscribersOf(sourceName)) {
+        const targetDef = this.store.getDef(sub.targetName)
+        if (!targetDef) continue
+        const targetHandle =
+          targetDef.lifecycle === 'app'
+            ? this.store.appInstance(sub.targetName)
+            : this.actors.get(sub.targetName)
+        if (!targetHandle) continue
+
+        const crossLifecycle = sourceHandle.def.lifecycle !== targetDef.lifecycle
+        const sid = this.sessionId
+        const targetName = sub.targetName
+
+        sourceHandle.actor.on(sub.event as never, (emitted) => {
+          this.cascadeDepth += 1
+          this.cascadeTrail.push(`${sourceName} —${sub.event}→ ${targetName}`)
+          try {
+            if (this.cascadeDepth > MAX_CASCADE_DEPTH) {
+              throw new Error(
+                `stator: emit cascade exceeded ${MAX_CASCADE_DEPTH} hops — ` +
+                  `subscription cycle? Last hops:\n  ${this.cascadeTrail.slice(-6).join('\n  ')}`,
+              )
+            }
+            const before = targetHandle.actor.getCommitCount()
+            targetHandle.actor.send(
+              buildDispatchEvent(emitted, sub.dispatch, crossLifecycle ? sid : undefined) as never,
+            )
+            if (targetHandle.actor.getCommitCount() !== before) recordTouch(targetName)
+          } finally {
+            this.cascadeDepth -= 1
+            this.cascadeTrail.pop()
+          }
+        })
+      }
+    }
+  }
+
+  /** Resolve a proxy for a machine — session-scoped from this runtime,
+   *  app-scoped from the long-lived app instance map. */
+  proxyFor(name: string): unknown {
+    const local = this.actors.get(name)
+    if (local) return local.proxy
+    const app = this.store.appInstance(name)
+    return app?.proxy
+  }
+
+  handleFor(name: string): InstanceHandle | undefined {
+    return this.actors.get(name) ?? this.store.appInstance(name)
+  }
+
+  /**
+   * Send an event to a loaded machine. Returns the set of machine names
+   * whose actors received any event during the dispatch (the origin plus
+   * any subscriber targets that fired via cross-machine listeners).
+   *
+   * Throws if the origin machine isn't loaded — call `loadGraph` first.
+   */
+  processEvent(machineName: string, event: { type: string; [k: string]: unknown }): Set<string> {
+    const handle = this.actors.get(machineName)
+    if (!handle) {
+      throw new Error(
+        `stator: machine "${machineName}" is not loaded into this runtime — ` +
+          `call loadGraph(...) with the relevant defs first.`,
+      )
+    }
+    if (!this.wired) this.wireSubscriptions()
+    const ctx: DispatchContext = {
+      runtime: this,
+      touched: new Set<string>([machineName]),
+    }
+    const before = handle.actor.getCommitCount()
+    withDispatchContext(ctx, () => {
+      handle.actor.send(event as never)
+    })
+    // A guard-dropped / unhandled event committed nothing: it must not count
+    // as touched (no persist, no fan-out, and `committed: false` on the wire).
+    if (handle.actor.getCommitCount() === before) ctx.touched.delete(machineName)
+    return ctx.touched
+  }
+
+  /** Write the current persisted snapshot for each touched machine back to
+   *  its store: session machines to the session Store, app machines (touched
+   *  via session→app subscriptions) to the AppStore when they opted in. */
+  async persistTouched(touched: ReadonlySet<string>): Promise<void> {
+    const ttlSeconds = this.store.sessionTtlSeconds
+    for (const name of touched) {
+      const handle = this.actors.get(name)
+      if (!handle) {
+        // Not a session machine in this runtime — an app machine reached via
+        // subscription. Safe no-op unless it opted into persistence.
+        await this.store.persistAppMachine(name)
+        continue
+      }
+      const snapshot = handle.actor.getPersistedSnapshot()
+      // Every set refreshes the session's whole expiry — the user is
+      // active, so all of their machines stay alive together.
+      await this.store.persistence.set(this.sessionId, name, snapshot, {
+        ttlSeconds,
+      })
+    }
+  }
+
+  /** Stop every transient actor. After dispose, the runtime must not be
+   *  used. Safe to call multiple times. */
+  dispose(): void {
+    for (const handle of this.actors.values()) {
+      handle.actor.stop()
+    }
+    this.actors.clear()
+  }
+}

package/src/server/session.ts

@@ -0,0 +1,29 @@
+import { randomUUID } from 'node:crypto'
+import type { Context } from 'hono'
+import { getCookie, setCookie } from 'hono/cookie'
+
+export const SESSION_COOKIE = 'stator_sid'
+
+/** Secure cookie flag — set when running behind HTTPS. Enabled by
+ *  NODE_ENV=production; can be overridden via STATOR_SECURE_COOKIE. */
+function shouldUseSecureCookie(): boolean {
+  if (process.env.STATOR_SECURE_COOKIE === '1') return true
+  if (process.env.STATOR_SECURE_COOKIE === '0') return false
+  return process.env.NODE_ENV === 'production'
+}
+
+export function getOrCreateSessionId(c: Context): {
+  sessionId: string
+  isNew: boolean
+} {
+  const existing = getCookie(c, SESSION_COOKIE)
+  if (existing) return { sessionId: existing, isNew: false }
+  const sessionId = randomUUID()
+  setCookie(c, SESSION_COOKIE, sessionId, {
+    httpOnly: true,
+    sameSite: 'Lax',
+    path: '/',
+    secure: shouldUseSecureCookie(),
+  })
+  return { sessionId, isNew: true }
+}

package/src/server/sse.ts

@@ -0,0 +1,175 @@
+import type { Patch } from '../wire/index.ts'
+import { scopedLogger } from './logger.ts'
+import { recompute } from './recompute.ts'
+import type { RenderState } from './render-context.ts'
+import type { RouteDefinition, RouteRequest } from './routing.ts'
+import type { SessionRuntime } from './session-runtime.ts'
+
+const sseLog = scopedLogger('sse')
+
+/**
+ * One open SSE connection. Lifetime equals the underlying TCP connection.
+ * The runtime stays alive for the connection's duration — this is the one
+ * place per-session state outlives a single request, because the
+ * connection *is* a single (very long) request.
+ *
+ * `renderState` carries the slot bindings + `lastValue` baseline that
+ * recompute will diff against when fan-out fires. Each push updates
+ * `lastValue` for the bindings touched by the push, so subsequent pushes
+ * only emit deltas.
+ */
+export interface Connection {
+  id: string
+  sessionId: string
+  /** The browser page-load identity (client-generated). Lets fan-out
+   *  recognize a dispatch's OWN connection: its baseline is advanced but
+   *  nothing is sent — the POST response already delivered those patches. */
+  clientId?: string
+  routeKey: string
+  route: RouteDefinition
+  /** URL-derived state for this specific connection. Stored at connection
+   *  open and reused by every fan-out recompute. Parameterized routes
+   *  carry the resolved path params here (`/p/:id` connection knows its
+   *  specific id). */
+  request: RouteRequest
+  runtime: SessionRuntime
+  renderState: RenderState
+  send: (data: string) => Promise<void>
+  closed: boolean
+}
+
+const connections = new Map<string, Connection>()
+let nextId = 0
+
+export function registerConnection(init: Omit<Connection, 'id' | 'closed'>): Connection {
+  const id = `sse${nextId++}`
+  const conn: Connection = { ...init, id, closed: false }
+  connections.set(id, conn)
+  sseLog.info(
+    { id, sid: conn.sessionId, route: conn.routeKey, total: connections.size },
+    'connection opened',
+  )
+  return conn
+}
+
+export function unregisterConnection(id: string): void {
+  const conn = connections.get(id)
+  if (!conn) return
+  conn.closed = true
+  conn.runtime.dispose()
+  connections.delete(id)
+  sseLog.info(
+    { id, sid: conn.sessionId, route: conn.routeKey, total: connections.size },
+    'connection closed',
+  )
+}
+
+export function activeConnectionCount(): number {
+  return connections.size
+}
+
+/**
+ * After a state-changing dispatch settles, iterate every open connection
+ * whose route's `reads:` intersects `touched`, recompute against that
+ * connection's slot map, and push any resulting patches over its event
+ * stream. Recompute mutates the connection's `renderState.lastValue`s so
+ * the next push is correctly diffed.
+ *
+ * Connections from any session receive pushes — that's the point: an
+ * admin tab on session C sees updates triggered by session A's POSTs.
+ */
+export async function fanOut(
+  touched: ReadonlySet<string>,
+  source?: { sessionId?: string; originClientId?: string },
+): Promise<void> {
+  if (touched.size === 0 || connections.size === 0) return
+
+  let pushedCount = 0
+  let skippedNoIntersect = 0
+  let skippedNoPatches = 0
+  let skippedOriginator = 0
+  let failed = 0
+
+  // Expand through the reverse-reads graph once per fan-out: machines whose
+  // SELECTORS derive from a touched machine must re-diff even though their
+  // own state didn't move. (Every connection shares the one MachineStore.)
+  const first = connections.values().next().value
+  const { all: expandedTouched, derived } = first
+    ? first.runtime.store.expandTouchedForRecompute(touched)
+    : { all: new Set(touched), derived: new Set<string>() }
+
+  for (const conn of connections.values()) {
+    if (conn.closed) continue
+
+    // Applicability per machine, judged against the connection's actual
+    // bindings (byMachine covers transitive reads, not just declared seeds):
+    //   - app machines: every connection (the shared instance IS the state).
+    //   - DIRECTLY-touched session machines: only the touching session's own
+    //     connections — and the connection's long-lived runtime must
+    //     REHYDRATE them from the Store first, because the mutation happened
+    //     in another runtime and this one's actor is frozen at connect time.
+    //   - DERIVED session machines (expansion only): every connection that
+    //     binds them, any session, no rehydration — their own state didn't
+    //     change; their selectors' dependencies did.
+    const applicable: string[] = []
+    for (const name of expandedTouched) {
+      if (!conn.renderState.byMachine.has(name)) continue
+      if (conn.runtime.lifecycleOf(name) === 'session' && !derived.has(name)) {
+        if (source?.sessionId === undefined || source.sessionId !== conn.sessionId) continue
+        await conn.runtime.rehydrate(name)
+      }
+      applicable.push(name)
+    }
+    if (applicable.length === 0) {
+      skippedNoIntersect++
+      continue
+    }
+
+    const patches: Patch[] = []
+    for (const name of applicable) {
+      patches.push(...recompute(conn.renderState, name, conn.runtime))
+    }
+    if (patches.length === 0) {
+      skippedNoPatches++
+      continue
+    }
+
+    // The dispatching page's own connection: the POST response already
+    // delivered this diff. The recompute above advanced the baseline (so the
+    // NEXT push diffs correctly); sending would double-apply — and keyed
+    // insert/remove/move ops are not idempotent.
+    if (
+      source?.originClientId !== undefined &&
+      conn.clientId !== undefined &&
+      conn.clientId === source.originClientId
+    ) {
+      skippedOriginator++
+      continue
+    }
+
+    try {
+      await conn.send(JSON.stringify({ patches }))
+      pushedCount++
+    } catch (err) {
+      // Bumped from debug to warn — silent push failures were why "30-50%
+      // delivery" was invisible in production logs.
+      failed++
+      sseLog.warn({ id: conn.id, sid: conn.sessionId, err: String(err) }, 'sse push failed')
+    }
+  }
+
+  // Log every fan-out at info so the user can see touched-machines flow and
+  // correlate against client-side inspector entries.
+  sseLog.info(
+    {
+      touched: [...touched],
+      total: connections.size,
+      pushed: pushedCount,
+      skippedNoIntersect,
+      skippedNoPatches,
+      skippedOriginator,
+      failed,
+    },
+    'fan-out',
+  )
+}

package/src/server/store.ts

@@ -0,0 +1,95 @@
+/**
+ * Persistence boundary for session-scoped machine state. Stored values are
+ * XState v5 *persisted snapshots* — serializable blobs containing the state
+ * name plus context, recoverable via `createActor(machine, { snapshot })`.
+ *
+ * The framework treats stored values as opaque JSON. App-lifecycle machine
+ * state is held in process (not persisted by this layer).
+ *
+ * ## TTL semantics — per-session, not per-entry
+ *
+ * `ttlSeconds` on `set` refreshes the **whole session's** expiry, not just
+ * the entry being written. If CartMachine is stored at T+0 and CheckoutMachine
+ * is stored at T+6h (both with ttlSeconds=86400), both expire at T+30h, not
+ * T+24h and T+30h respectively. Adapters MUST honor this — the session is
+ * the TTL unit, machines within a session are not independent.
+ *
+ * Rationale: a user actively interacting with one machine (checkout) is also
+ * an active session for their other machines (cart) by definition. Splitting
+ * TTL per-machine would drop carts under users mid-checkout. Sessions
+ * expire as a whole when fully idle.
+ */
+export interface Store {
+  get(sessionId: string, machineName: string): Promise<unknown | null>
+  set(
+    sessionId: string,
+    machineName: string,
+    snapshot: unknown,
+    opts?: { ttlSeconds?: number },
+  ): Promise<void>
+  has(sessionId: string, machineName: string): Promise<boolean>
+  deleteSession(sessionId: string): Promise<void>
+}
+
+/**
+ * In-memory implementation. Lazy-expiry: nothing is swept proactively, but
+ * any read of an expired session returns null and drops the session's data.
+ * Per-session expiry is tracked separately from the data map.
+ */
+export class InMemoryStore implements Store {
+  private data = new Map<string, Map<string, unknown>>()
+  private expiryAt = new Map<string, number>() // sessionId → epoch ms
+
+  private isExpired(sid: string): boolean {
+    const at = this.expiryAt.get(sid)
+    return at !== undefined && at <= Date.now()
+  }
+
+  private dropSession(sid: string): void {
+    this.data.delete(sid)
+    this.expiryAt.delete(sid)
+  }
+
+  async get(sid: string, name: string): Promise<unknown | null> {
+    if (this.isExpired(sid)) {
+      this.dropSession(sid)
+      return null
+    }
+    return this.data.get(sid)?.get(name) ?? null
+  }
+
+  async set(
+    sid: string,
+    name: string,
+    snapshot: unknown,
+    opts?: { ttlSeconds?: number },
+  ): Promise<void> {
+    // Drop any stale data before writing — set() against an expired session
+    // is effectively a fresh session.
+    if (this.isExpired(sid)) this.dropSession(sid)
+
+    let session = this.data.get(sid)
+    if (!session) {
+      session = new Map()
+      this.data.set(sid, session)
+    }
+    session.set(name, snapshot)
+
+    if (opts?.ttlSeconds) {
+      // Refresh the whole session's expiry, not just this entry's.
+      this.expiryAt.set(sid, Date.now() + opts.ttlSeconds * 1000)
+    }
+  }
+
+  async has(sid: string, name: string): Promise<boolean> {
+    if (this.isExpired(sid)) {
+      this.dropSession(sid)
+      return false
+    }
+    return this.data.get(sid)?.has(name) ?? false
+  }
+
+  async deleteSession(sid: string): Promise<void> {
+    this.dropSession(sid)
+  }
+}

package/src/stator-modules.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ambient type for `.stator` single-file components. A `.stator` module's
+ * default export is its render function — it takes the component's props and
+ * returns an HtmlFragment. Consumers reference this via the package's types.
+ */
+declare module '*.stator' {
+  import type { HtmlFragment } from '@statorjs/stator/template'
+
+  // biome-ignore lint/suspicious/noExplicitAny: the wildcard fallback must admit every component's props — `Record<string, unknown>` would reject interfaces without index signatures
+  const component: (props?: any) => HtmlFragment
+  export default component
+}

package/src/template/client-shell.ts

@@ -0,0 +1,65 @@
+import { allocElementId, getCurrentRenderState, registerBinding } from '../server/render-context.ts'
+import { escapeAttribute } from './parser.ts'
+import { isReadResult, type ReadResult } from './read.ts'
+
+/**
+ * Server-side: render a client component's declared attributes onto its
+ * custom-element root. A client component's server module calls this to map
+ * camelCase props → kebab DOM attributes (`unitPrice` → `unit-price`), per the
+ * `static attrs` coercer kinds. Booleans are presence flags; other scalars are
+ * stringified + escaped. `null`/`undefined`/`false`-boolean → omitted.
+ *
+ * A prop may be a `read(...)`: the attribute becomes a LIVE binding — the
+ * server patches it like any attr binding, and the island (which observes
+ * its declared attrs) receives `${key}Changed(next)`. This is the sanctioned
+ * channel for live server state flowing INTO an island.
+ *
+ * Returns a leading-spaced attribute string (or '') to splice into the open tag.
+ */
+export function clientShellAttrs(
+  props: Record<string, unknown>,
+  decl: Record<string, 'number' | 'string' | 'boolean'>,
+): string {
+  let out = ''
+  let elementId: string | null = null
+  for (const key in decl) {
+    const v = props[key]
+    if (v == null) continue
+    const name = key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+
+    if (isReadResult(v)) {
+      const state = getCurrentRenderState()
+      if (!state) {
+        throw new Error(
+          `stator: read() passed as island prop "${key}" outside a render — ` +
+            `live island attrs only make sense inside a route render.`,
+        )
+      }
+      if (!elementId) {
+        elementId = allocElementId(state)
+        out += ` data-stator-id="${elementId}"`
+      }
+      const r = v as ReadResult
+      registerBinding(state, {
+        slotId: r.slotId,
+        machineName: r.machineName,
+        selector: r.selector,
+        lastValue: r.value,
+        kind: 'attr',
+        attrName: name,
+        parentId: elementId,
+      })
+      // Same value semantics as template attr bindings (boolean-aware).
+      if (r.value === false || r.value === null || r.value === undefined) continue
+      out += r.value === true ? ` ${name}` : ` ${name}="${escapeAttribute(String(r.value))}"`
+      continue
+    }
+
+    if (decl[key] === 'boolean') {
+      if (v) out += ` ${name}`
+    } else {
+      out += ` ${name}="${escapeAttribute(String(v))}"`
+    }
+  }
+  return out
+}