@statorjs/stator 1.2.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.2.2",
+  "version": "1.4.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.2.2"
+    "@statorjs/stator": "1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/css.d.ts

@@ -0,0 +1,6 @@
+// `.css` files are imported as text (esbuild `.css: 'text'` loader in
+// `bundleInspector()`), so the default export is the stylesheet source string.
+declare module '*.css' {
+  const css: string
+  export default css
+}

package/src/client/inspector-flash.css

@@ -0,0 +1,50 @@
+/* Stator dev inspector — element-flash styles.
+ *
+ * These decorate APP elements (the patched nodes in the page), so they cannot
+ * live in the widget's shadow root — they're injected document-level as a
+ * constructable stylesheet in `@layer stator-inspector`, deliberately the
+ * lowest-priority author layer. An app's own styles are unlayered, and
+ * unlayered author styles beat every layer, so the app ALWAYS wins: the flash
+ * can never override the page it is inspecting.
+ *
+ * Bundled into the inspector asset as text by `bundleInspector()`'s esbuild
+ * `.css: 'text'` loader; there is no separate stylesheet request.
+ */
+@layer stator-inspector {
+  /* Highlight the changed element with an OUTLINE only — never animate its
+     background-color. A CSS animation's background-color overrides the element's
+     own background (even an .active state) for the animation's full duration, so
+     flashing background would MASK the very change it's meant to highlight: a
+     patch that lights up a toggle button's background wouldn't visibly settle
+     until the 1.2s flash cleared. Outline is painted outside the box and masks
+     nothing — and unlike background, no app is likely to animate it. */
+  .stator-flash {
+    outline-style: solid;
+    outline-offset: 3px;
+    animation: stator-flash 1200ms ease-out forwards;
+    border-radius: 2px;
+  }
+  @keyframes stator-flash {
+    0% {
+      outline-width: 3px;
+      outline-color: var(--flash-color, dodgerblue);
+    }
+    30% {
+      outline-width: 3px;
+      outline-color: var(--flash-color, dodgerblue);
+    }
+    100% {
+      outline-width: 0;
+      outline-color: transparent;
+    }
+  }
+  .stator-flash--text {
+    --flash-color: #3b82f6;
+  }
+  .stator-flash--attr {
+    --flash-color: #a855f7;
+  }
+  .stator-flash--html {
+    --flash-color: #14b8a6;
+  }
+}

package/src/client/inspector.css

@@ -0,0 +1,196 @@
+/* Stator dev inspector — widget (toolbar + drawer) styles.
+ *
+ * Attached by inspector.ts to the <stator-inspector> custom element's SHADOW
+ * ROOT via adoptedStyleSheets. Shadow isolation cuts both ways: the app's
+ * global element selectors (todomvc's bare `button` reset was the shipped
+ * case) can't restyle the widget, and the widget's styles provably can't
+ * touch the page. No `@layer` needed in here — nothing else competes inside
+ * the shadow tree. The element flash decorates APP nodes and therefore lives
+ * document-level instead — see inspector-flash.css.
+ *
+ * Bundled into the inspector asset as text by `bundleInspector()`'s esbuild
+ * `.css: 'text'` loader; there is no separate stylesheet request.
+ */
+:host {
+  display: block;
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  z-index: 2147483000;
+  pointer-events: none;
+}
+.stator-inspector-toggle,
+.stator-inspector-drawer {
+  pointer-events: auto;
+}
+.stator-inspector-drawer[hidden],
+.stator-inspector-toggle[hidden] {
+  display: none;
+}
+.stator-inspector-toggle {
+  position: fixed;
+  bottom: 1rem;
+  right: 1rem;
+  background: #1a1a1a;
+  color: #d0d0d0;
+  border: 1px solid #2a2a2a;
+  padding: 0.45rem 0.85rem;
+  border-radius: 999px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.82rem;
+  cursor: pointer;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.18);
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+.stator-inspector-toggle:hover {
+  background: #232323;
+  color: #f0f0f0;
+}
+.stator-inspector-drawer {
+  background: #141414;
+  color: #d0d0d0;
+  border-top: 1px solid #2a2a2a;
+  max-height: 240px;
+  display: flex;
+  flex-direction: column;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.78rem;
+  box-shadow: 0 -2px 12px rgba(0, 0, 0, 0.25);
+}
+.stator-inspector-header {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.5rem 0.9rem;
+  background: #1a1a1a;
+  border-bottom: 1px solid #262626;
+  flex-shrink: 0;
+}
+.stator-inspector-title {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: #f5f5f5;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+}
+.stator-inspector-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #6a9955;
+  box-shadow: 0 0 0 2px rgba(106, 153, 85, 0.18);
+}
+.stator-inspector-legend {
+  display: inline-flex;
+  gap: 0.75rem;
+  color: #888;
+}
+.stator-inspector-key--up {
+  color: #dcdcaa;
+}
+.stator-inspector-key--down {
+  color: #9cdcfe;
+}
+.stator-inspector-header button {
+  background: transparent;
+  border: 1px solid #333;
+  color: #aaa;
+  padding: 0.15rem 0.55rem;
+  font-family: inherit;
+  font-size: 0.75rem;
+  border-radius: 4px;
+  cursor: pointer;
+}
+.stator-inspector-header button:hover {
+  background: #232323;
+  color: #f0f0f0;
+}
+/* higher specificity than `.stator-inspector-header button` so it wins without !important */
+.stator-inspector-header button.stator-inspector-close {
+  margin-left: auto;
+  font-size: 1rem;
+  line-height: 1;
+  padding: 0.05rem 0.5rem;
+}
+.stator-inspector-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0;
+}
+.stator-inspector-empty {
+  margin: 0;
+  padding: 1rem 0.9rem;
+  color: #6a6a6a;
+  font-style: italic;
+}
+.stator-inspector-row {
+  border-bottom: 1px solid #1f1f1f;
+}
+.stator-inspector-row:last-child {
+  border-bottom: none;
+}
+.stator-inspector-summary {
+  display: grid;
+  grid-template-columns: 90px 16px 130px 1fr auto;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding: 0.35rem 0.9rem;
+  cursor: pointer;
+  user-select: none;
+}
+.stator-inspector-summary:hover {
+  background: #1c1c1c;
+}
+.stator-inspector-time {
+  color: #6a6a6a;
+  font-variant-numeric: tabular-nums;
+}
+.stator-inspector-arrow {
+  text-align: center;
+  font-weight: 700;
+}
+.stator-inspector-row--up .stator-inspector-arrow {
+  color: #dcdcaa;
+}
+.stator-inspector-row--down .stator-inspector-arrow {
+  color: #9cdcfe;
+}
+.stator-inspector-machine {
+  color: #c586c0;
+  font-weight: 500;
+}
+.stator-inspector-row--down .stator-inspector-machine {
+  color: #9cdcfe;
+}
+.stator-inspector-event-type {
+  color: #4ec9b0;
+  font-weight: 500;
+}
+.stator-inspector-params {
+  color: #888;
+  text-align: right;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+.stator-inspector-detail {
+  margin: 0;
+  padding: 0.5rem 0.9rem 0.75rem 2.5rem;
+  background: #0e0e0e;
+  color: #cfcfcf;
+  font-size: 0.74rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+  border-top: 1px dashed #2a2a2a;
+}
+
+@media (max-height: 600px) {
+  .stator-inspector-drawer {
+    max-height: 50vh;
+  }
+}

package/src/client/inspector.ts

@@ -8,72 +8,17 @@
  *
  * It depends on nothing but that event contract — the same surface any external
  * devtool would use. Self-contained: it injects its own styles.
+ *
+ * The widget is a `<stator-inspector>` custom element with a shadow root
+ * (the Astro-dev-toolbar / vite-error-overlay pattern): the inspected app's
+ * global element selectors can't restyle the toolbar, and the toolbar's styles
+ * provably can't touch the page. Only the element-flash styles live at
+ * document level (they decorate app nodes), in the lowest-priority
+ * `@layer stator-inspector` so the app always wins over them.
  */
 
-const STYLES = `
-.stator-inspector { position: fixed; bottom: 0; left: 0; right: 0; z-index: 2147483000; pointer-events: none; }
-.stator-inspector > * { pointer-events: auto; }
-.stator-inspector-drawer[hidden], .stator-inspector-toggle[hidden] { display: none; }
-.stator-inspector-toggle {
-  position: fixed; bottom: 1rem; right: 1rem; background: #1a1a1a; color: #d0d0d0;
-  border: 1px solid #2a2a2a; padding: 0.45rem 0.85rem; border-radius: 999px;
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.82rem;
-  cursor: pointer; box-shadow: 0 2px 8px rgba(0,0,0,0.18); display: inline-flex;
-  align-items: center; gap: 0.4rem;
-}
-.stator-inspector-toggle:hover { background: #232323; color: #f0f0f0; }
-.stator-inspector-drawer {
-  background: #141414; color: #d0d0d0; border-top: 1px solid #2a2a2a; max-height: 240px;
-  display: flex; flex-direction: column; font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-  font-size: 0.78rem; box-shadow: 0 -2px 12px rgba(0,0,0,0.25);
-}
-.stator-inspector-header {
-  display: flex; align-items: center; gap: 1rem; padding: 0.5rem 0.9rem;
-  background: #1a1a1a; border-bottom: 1px solid #262626; flex-shrink: 0;
-}
-.stator-inspector-title { display: inline-flex; align-items: center; gap: 0.5rem; color: #f5f5f5; font-weight: 600; letter-spacing: 0.02em; }
-.stator-inspector-dot { width: 8px; height: 8px; border-radius: 50%; background: #6a9955; box-shadow: 0 0 0 2px rgba(106,153,85,0.18); }
-.stator-inspector-legend { display: inline-flex; gap: 0.75rem; color: #888; }
-.stator-inspector-key--up { color: #dcdcaa; }
-.stator-inspector-key--down { color: #9cdcfe; }
-.stator-inspector-header button {
-  background: transparent; border: 1px solid #333; color: #aaa; padding: 0.15rem 0.55rem;
-  font-family: inherit; font-size: 0.75rem; border-radius: 4px; cursor: pointer;
-}
-.stator-inspector-header button:hover { background: #232323; color: #f0f0f0; }
-.stator-inspector-close { margin-left: auto; font-size: 1rem !important; line-height: 1; padding: 0.05rem 0.5rem !important; }
-.stator-inspector-body { flex: 1; overflow-y: auto; padding: 0; }
-.stator-inspector-empty { margin: 0; padding: 1rem 0.9rem; color: #6a6a6a; font-style: italic; }
-.stator-inspector-row { border-bottom: 1px solid #1f1f1f; }
-.stator-inspector-row:last-child { border-bottom: none; }
-.stator-inspector-summary {
-  display: grid; grid-template-columns: 90px 16px 130px 1fr auto; align-items: baseline;
-  gap: 0.75rem; padding: 0.35rem 0.9rem; cursor: pointer; user-select: none;
-}
-.stator-inspector-summary:hover { background: #1c1c1c; }
-.stator-inspector-time { color: #6a6a6a; font-variant-numeric: tabular-nums; }
-.stator-inspector-arrow { text-align: center; font-weight: 700; }
-.stator-inspector-row--up .stator-inspector-arrow { color: #dcdcaa; }
-.stator-inspector-row--down .stator-inspector-arrow { color: #9cdcfe; }
-.stator-inspector-machine { color: #c586c0; font-weight: 500; }
-.stator-inspector-row--down .stator-inspector-machine { color: #9cdcfe; }
-.stator-inspector-event-type { color: #4ec9b0; font-weight: 500; }
-.stator-inspector-params { color: #888; text-align: right; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-variant-numeric: tabular-nums; }
-.stator-inspector-detail {
-  margin: 0; padding: 0.5rem 0.9rem 0.75rem 2.5rem; background: #0e0e0e; color: #cfcfcf;
-  font-size: 0.74rem; white-space: pre-wrap; word-break: break-word; border-top: 1px dashed #2a2a2a;
-}
-.stator-flash { outline-style: solid; outline-offset: 3px; animation: stator-flash 1200ms ease-out forwards; border-radius: 2px; }
-@keyframes stator-flash {
-  0% { outline-width: 3px; outline-color: var(--flash-color, dodgerblue); background-color: var(--flash-bg, rgba(30,144,255,0.16)); }
-  30% { outline-width: 3px; outline-color: var(--flash-color, dodgerblue); background-color: var(--flash-bg, rgba(30,144,255,0.16)); }
-  100% { outline-width: 0; outline-color: transparent; background-color: transparent; }
-}
-.stator-flash--text { --flash-color: #3b82f6; --flash-bg: rgba(59,130,246,0.12); }
-.stator-flash--attr { --flash-color: #a855f7; --flash-bg: rgba(168,85,247,0.12); }
-.stator-flash--html { --flash-color: #14b8a6; --flash-bg: rgba(20,184,166,0.10); }
-@media (max-height: 600px) { .stator-inspector-drawer { max-height: 50vh; } }
-`
+import inspectorCss from './inspector.css'
+import flashCss from './inspector-flash.css'
 
 const STORAGE_KEY = 'stator:inspector:open'
 const MAX_ENTRIES = 40
@@ -113,13 +58,24 @@ function formatEventParams(event: Record<string, unknown>): string {
 }
 
 function mount(): void {
-  const style = document.createElement('style')
-  style.textContent = STYLES
-  document.head.appendChild(style)
-
-  const root = document.createElement('div')
-  root.className = 'stator-inspector'
-  root.innerHTML = `
+  // Flash styles decorate APP elements, so they can't live in the widget's
+  // shadow — they're document-level, in `@layer stator-inspector` (see
+  // inspector-flash.css) so the app's own (unlayered) styles always win.
+  const flashSheet = new CSSStyleSheet()
+  flashSheet.replaceSync(flashCss)
+  document.adoptedStyleSheets = [...document.adoptedStyleSheets, flashSheet]
+
+  // The widget itself: a custom element whose shadow root carries the markup
+  // and styles — isolated from the page's cascade in both directions.
+  if (!customElements.get('stator-inspector')) {
+    customElements.define('stator-inspector', class extends HTMLElement {})
+  }
+  const root = document.createElement('stator-inspector')
+  const shadow = root.attachShadow({ mode: 'open' })
+  const widgetSheet = new CSSStyleSheet()
+  widgetSheet.replaceSync(inspectorCss)
+  shadow.adoptedStyleSheets = [widgetSheet]
+  shadow.innerHTML = `
     <button class="stator-inspector-toggle" type="button" aria-label="Show stator inspector">
       <span aria-hidden="true">{ }</span> Inspect
     </button>
@@ -139,7 +95,7 @@ function mount(): void {
     </section>`
   document.body.appendChild(root)
 
-  const q = (sel: string) => root.querySelector(sel) as HTMLElement
+  const q = (sel: string) => shadow.querySelector(sel) as HTMLElement
   const drawer = q('.stator-inspector-drawer')
   const body = q('.stator-inspector-body')
   const toggle = q('.stator-inspector-toggle')
@@ -219,6 +175,9 @@ function mount(): void {
   window.addEventListener('stator:patch-applied', (e: Event) => {
     const { patch, element } = (e as CustomEvent).detail
     if (!element) return
+    // Only flash while the drawer is open — the flash is an inspection aid, not
+    // ambient page decoration; a closed inspector shouldn't touch the app.
+    if (drawer.hidden) return
     const opClass = `stator-flash--${patch.op}`
     ;(element as HTMLElement).classList.add('stator-flash', opClass)
     window.setTimeout(() => {

package/src/client/runtime.ts

@@ -69,12 +69,16 @@ function initLiveChannel(): void {
       return
     }
     if (data.patches) {
+      // SSE is server-pushed — no client round-trip to time — so report the
+      // apply duration (still the useful "how expensive was this update?").
+      const startedAt = performance.now()
+      applyPatches(data.patches)
       emit('stator:patches-received', {
         patches: data.patches,
         source: 'sse',
+        durationMs: Math.round(performance.now() - startedAt),
         timestamp: Date.now(),
       })
-      applyPatches(data.patches)
     }
     if (data.directives && data.directives.length > 0) {
       applyDirectives(data.directives)

package/src/compiler/compile.ts

@@ -48,7 +48,7 @@ export interface CompileResult {
 }
 
 const PRIMITIVES_IMPORT =
-  "import { html, read, each, when, match, on, classList, styleList } from '@statorjs/stator/template'"
+  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList } from '@statorjs/stator/template'"
 
 export interface CompileOptions {
   /** Stable id for the component (file path). Used for the scope hash so the
@@ -186,11 +186,11 @@ 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, on, classList, styleList, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
+    "import { html, read, each, when, match, defer, on, classList, styleList, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
     '',
     `export default function (props = {}) {`,
     `  const __inner = ${innerExpr}`,
-    `  const __attrs = clientShellAttrs(props, ${attrDecl})`,
+    `  const __attrs = clientShellAttrs(props, ${attrDecl}, ${JSON.stringify(root.rootAttrs)})`,
     `  return createHtmlFragment(\`<${root.tag}\${__attrs}${rootScope}>\` + __inner.html + \`</${root.tag}>\`)`,
     '}',
     '',
@@ -214,9 +214,36 @@ function compileClient(
   }
 }
 
-/** Parse a client template, returning the custom-element root tag and the inner
- *  source (its children). Enforces "root must be the custom element". */
-function extractClientRoot(template: string, file?: string): { tag: string; inner: string } {
+/** Static attributes authored on a client component's ROOT element — its own
+ *  base `class`, `hidden`, ARIA, `data-*`. These are carried across the
+ *  split-and-reassemble so a component can style/flag its own root; the use site
+ *  merges them under its props (FINDINGS #4). Namespaced directives (class:list,
+ *  on:) and expression-valued attrs are not static and are skipped here. */
+function staticRootAttrs(
+  attrs: ts.JsxAttributes,
+  sf: ts.SourceFile,
+): Record<string, string | boolean> {
+  const out: Record<string, string | boolean> = {}
+  for (const attr of attrs.properties) {
+    if (!ts.isJsxAttribute(attr) || ts.isJsxNamespacedName(attr.name)) continue
+    const name = attr.name.getText(sf)
+    const init = attr.initializer
+    if (init === undefined) {
+      out[name] = true // valueless boolean attribute
+    } else if (ts.isStringLiteral(init)) {
+      out[name] = init.text
+    }
+  }
+  return out
+}
+
+/** Parse a client template, returning the custom-element root tag, its inner
+ *  source (its children), and the root's own static attributes. Enforces "root
+ *  must be the custom element". */
+function extractClientRoot(
+  template: string,
+  file?: string,
+): { tag: string; inner: string; rootAttrs: Record<string, string | boolean> } {
   const wrapped = `const __t = (<>${template}</>);`
   const sf = ts.createSourceFile('t.tsx', wrapped, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
   let fragment: ts.JsxFragment | undefined
@@ -241,13 +268,13 @@ function extractClientRoot(template: string, file?: string): { tag: string; inne
   if (ts.isJsxSelfClosingElement(rootEl)) {
     const tag = rootEl.tagName.getText(sf)
     requireCustomRoot(tag, file)
-    return { tag, inner: '' }
+    return { tag, inner: '', rootAttrs: staticRootAttrs(rootEl.attributes, sf) }
   }
   const el = rootEl as ts.JsxElement
   const tag = el.openingElement.tagName.getText(sf)
   requireCustomRoot(tag, file)
   const inner = wrapped.slice(el.openingElement.getEnd(), el.closingElement.getStart())
-  return { tag, inner }
+  return { tag, inner, rootAttrs: staticRootAttrs(el.openingElement.attributes, sf) }
 }
 
 function requireCustomRoot(tag: string, file?: string): void {

package/src/compiler/virtual-code.ts

@@ -49,7 +49,7 @@ export interface VirtualCodeResult {
 // runtime hides a missing-import bug; a name in both collides with the
 // author's legitimate import (`raw` is NOT a runtime global — authors
 // import it — which is why it must not be in this list).
-const TEMPLATE_GLOBALS = ['read', 'each', 'when', 'match', 'on', 'classList', 'styleList']
+const TEMPLATE_GLOBALS = ['read', 'each', 'when', 'match', 'defer', 'on', 'classList', 'styleList']
 const CLIENT_GLOBALS = [
   'StatorElement',
   'use',

package/src/engine/actor.ts

@@ -63,6 +63,13 @@ export interface CreateActorOptions<C> {
    *  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). */
+  onStateEnter?: (stateKey: string, ctx: C) => void
+  /** Host hook: a state was LEFT (a value-changing transition). The server uses
+   *  it to cancel that state's `after` timers. */
+  onStateExit?: (stateKey: string) => void
 }
 
 /** Unique per-invocation effect id — usable as an idempotency key, so it must
@@ -96,6 +103,10 @@ export function createActor<C extends object, E extends EventObject, S extends s
   let context: C = opts.snapshot
     ? (structuredClone(opts.snapshot.context) as C)
     : (structuredClone(def.context) as C)
+  // Hydrated actors have already lived: their current state's entry effect fired
+  // when it was entered, so `start()` must NOT re-fire it. Fresh actors (no
+  // snapshot) enter their initial state for the first time.
+  const hydrated = opts.snapshot !== undefined
 
   const subscribers = new Set<(s: Snapshot<C>) => void>()
   const emitListeners = new Map<string, Set<(e: EmittedEvent) => void>>()
@@ -112,6 +123,39 @@ export function createActor<C extends object, E extends EventObject, S extends s
     for (const fn of subscribers) fn(snap)
   }
 
+  // Schedule a state's entry effect (if declared) — the same host-scheduled,
+  // commit-time-snapshot, at-most-once path as a transition effect, minus the
+  // event. Firing does NOT bump `commits` (an entry is not a committed
+  // transition); the server persists an entry-firing machine via the host's
+  // pending-effects queue instead (see server/session-runtime.ts).
+  const fireEntryEffect = (stateKey: string): void => {
+    const entry = def.states[stateKey]?.entry
+    if (!entry) return
+    const effectId = newEffectId()
+    const ctxSnapshot = structuredClone(context)
+    const invocation: EffectInvocation = {
+      machineName: def.name,
+      effectId,
+      run: () => Promise.resolve(entry(ctxSnapshot, { effectId })),
+    }
+    if (opts.onEffect) {
+      opts.onEffect(invocation)
+    } else {
+      void invocation
+        .run()
+        .then((completion) => {
+          if (completion) actor.send(completion as E)
+        })
+        .catch((err) => {
+          console.error(
+            `stator: entry effect ${effectId} of "${def.name}" threw — effects must catch ` +
+              `and return their failure event. Dropped.`,
+            err,
+          )
+        })
+    }
+  }
+
   const actor: Actor<C, E> = {
     seed(partial: Partial<C>) {
       if (!started) context = { ...context, ...partial }
@@ -120,6 +164,12 @@ export function createActor<C extends object, E extends EventObject, S extends s
       if (!started) {
         started = true
         notify() // let subscribe-before-start consumers sync initial state
+        // Fresh initial-state entry (a hydrated actor already fired its).
+        if (!hydrated) {
+          const initial = value[value.length - 1]!
+          fireEntryEffect(initial)
+          opts.onStateEnter?.(initial, context)
+        }
       }
       return actor
     },
@@ -228,6 +278,15 @@ export function createActor<C extends object, E extends EventObject, S extends s
         }
       }
 
+      // A value-changing transition leaves the old state and enters the new one:
+      // fire the new state's entry effect and let the host arm/cancel `after`
+      // timers (self-transitions and action-only transitions do neither).
+      if (config.to && config.to !== stateKey) {
+        opts.onStateExit?.(stateKey)
+        fireEntryEffect(config.to)
+        opts.onStateEnter?.(config.to, context)
+      }
+
       notify()
     },
 

package/src/engine/types.ts

@@ -83,6 +83,31 @@ export type Effect<C, E extends EventObject, EAll extends EventObject = EventObj
   meta: EffectMeta,
 ) => Promise<EAll | null>
 
+/**
+ * A state ENTRY effect: async I/O the host schedules when a state is *entered* —
+ * a fresh start at the initial state, or a transition that changes the state
+ * value; never on hydration. Same host-scheduled, off-lock, at-most-once
+ * pipeline as a transition `Effect`, minus the event argument (a state entry has
+ * no triggering event). Returns the completion event to dispatch (annotate the
+ * return with your machine's event union, exactly as for `Effect`), or null.
+ */
+export type EntryEffect<C, EAll extends EventObject = EventObject> = (
+  ctx: C,
+  meta: EffectMeta,
+) => Promise<EAll | null>
+
+/**
+ * A state timeout: after `delay` ms in the state, the host dispatches `send`.
+ * Armed on entry, cancelled on exit — host-scheduled, in-memory, non-durable in
+ * v1 (a restart drops armed timers). `delay` may depend on context. The trigger
+ * is a *described* value, not a bare-ms key, so it can grow (dynamic delays now;
+ * durable/cron schedules later) without a breaking change.
+ */
+export interface AfterEntry<C, EAll extends EventObject = EventObject> {
+  delay: number | ((ctx: C) => number)
+  send: EAll
+}
+
 /** A scheduled effect surfaced to the host: everything needed to run it and
  *  dispatch its completion. `run` closes over the commit-time snapshots. */
 export interface EffectInvocation {
@@ -132,6 +157,14 @@ export type OnMap<C, E extends EventObject, S extends string, R = Record<string,
 
 export interface StateNode<C, E extends EventObject, S extends string, R = Record<string, any>> {
   on?: OnMap<C, E, S, R>
+  /** Async I/O run on *entering* this state (a fresh start at the initial state,
+   *  or a value-changing transition — never on hydration), host-scheduled like a
+   *  transition effect. `EAll` is the machine's full event union. See
+   *  `EntryEffect`. */
+  entry?: EntryEffect<C, E>
+  /** State timeouts: each fires `send` after its `delay` ms in this state
+   *  (armed on entry, cancelled on exit). See `AfterEntry`. */
+  after?: AfterEntry<C, E>[]
 }
 
 /** Payload selector runs synchronously AFTER the transition's action, so it

package/src/server/api-route.ts

@@ -83,8 +83,14 @@ export async function runApiRoute(
         return c.text('Internal Server Error', 500)
       }
 
+      // Persist committed machines plus any fresh machine that fired its initial
+      // entry effect (not in `touched` — an entry commits no transition), so it
+      // isn't re-created and re-fired next request. Fan-out stays on `touched`.
+      const toPersist = new Set([...touched, ...runtime.entryFiredMachines()])
+      if (toPersist.size > 0) {
+        await runtime.persistTouched(toPersist)
+      }
       if (touched.size > 0) {
-        await runtime.persistTouched(touched)
         await fanOut(touched, { sessionId })
       }