@statorjs/stator 1.0.0 → 1.1.1

package/package.json

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

package/src/client/bind.ts

@@ -1,4 +1,4 @@
-import { actorOf, type ClientInstance } from './use.ts'
+import { actorOf, type ClientInstanceBase } from './use.ts'
 
 /**
  * The one client binding mechanism: subscribe to a set of client actors, and on
@@ -12,7 +12,7 @@ import { actorOf, type ClientInstance } from './use.ts'
  * Returns a disposer that unsubscribes.
  */
 export function bind(
-  deps: ClientInstance[],
+  deps: ClientInstanceBase[],
   compute: () => unknown,
   apply: (value: unknown) => void,
 ): () => void {
@@ -38,7 +38,7 @@ export function bind(
  * dependency changes (no diffing — `fn` owns its own DOM writes). The lower-
  * level primitive `{key}Changed` desugars to. Returns a disposer.
  */
-export function effect(deps: ClientInstance[], fn: () => void): () => void {
+export function effect(deps: ClientInstanceBase[], fn: () => void): () => void {
   fn()
   const unsubs = deps.map((d) => actorOf(d).subscribe(fn).unsubscribe)
   return () => {

package/src/client/index.ts

@@ -7,7 +7,7 @@
 export { bind, effect } from './bind.ts'
 export { dispatch } from './dispatch.ts'
 export { defineElement, StatorElement } from './element.ts'
-export type { MachineConfig } from './machine.ts'
+export type { ClientBehavior, LegacyMachineConfig } from './machine.ts'
 export { machine } from './machine.ts'
-export type { ClientInstance } from './use.ts'
+export type { ClientInstance, ClientInstanceBase } from './use.ts'
 export { use } from './use.ts'

package/src/client/machine.ts

@@ -1,39 +1,107 @@
-import { defineMachine, type EventObject, type MachineDef } from '../engine/index.ts'
+import { defineMachine, type MachineDef } from '../engine/index.ts'
 
 /**
- * Terse machine form for component-local client state. Desugars to a single-state
- * `defineMachine` — context is every top-level key except the reserved `on` /
- * `select` / `name`, transitions go under one implicit `active` state, and
- * `select` becomes selectors.
+ * Terse machine form for component-local client state.
  *
- *   machine({ count: 1, on: { INC: s => s.count++ }, select: { atMax: s => s.count >= 99 } })
+ *   const Qty = machine(
+ *     { count: 1 },                                  // context: just data
+ *     {
+ *       on: { INC: (s) => { s.count += 1 } },        // s is typed from context
+ *       select: { atMax: (s) => s.count >= 99 },     // exposed on the instance
+ *     },
+ *   )
  *
- * Client machines run only via `createActor` (never the Store), so the name is
- * just a label and need not be unique.
+ * Context and behavior are SEPARATE arguments so TypeScript can infer the
+ * context first and then contextually type every handler and selector
+ * against it — one bag can't be soundly inferred (the handlers' parameter
+ * types would depend on the same object they're part of; see the probe
+ * history in the 1.0 spec). Events are structurally loose (`ev.color` is
+ * `unknown`); the machine desugars to a single-state `defineMachine`.
+ *
+ * Client machines run only via `createActor` (never the Store), so the name
+ * is just a label and need not be unique.
  */
-export interface MachineConfig {
+
+/** Client events are structurally loose — the terse form declares no union. */
+export type ClientEvent = { type: string; [k: string]: unknown }
+
+interface ClientTransitionObject<C> {
+  when?: (ctx: C, ev: ClientEvent) => boolean
+  do?: (ctx: C, ev: ClientEvent) => void
+  emit?: string | string[]
+}
+type ClientTransition<C> = ((ctx: C, ev: ClientEvent) => void) | ClientTransitionObject<C>
+
+export interface ClientBehavior<C> {
   /** Optional label (defaults to "ClientMachine"). */
   name?: string
-  /** Transition map for the single implicit state. A bare function is an action;
-   *  an object is a full `{ to?, when?, do?, emit? }` transition. */
-  // biome-ignore lint/suspicious/noExplicitAny: the terse form is dynamically shaped — context/event types aren't statically threaded (it desugars through defineMachine)
-  on?: Record<string, any>
-  /** Derived values, exposed as selectors on the instance. */
-  // biome-ignore lint/suspicious/noExplicitAny: same — ctx is the inferred context of the desugared machine
+  /** Transition map for the single implicit state. A bare function is an
+   *  action; an object is a full `{ when?, do?, emit? }` transition. */
+  on?: Record<string, ClientTransition<C>>
+  /** Derived values, exposed as live properties on the `use()` instance. */
+  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>
-  /** Everything else is initial context. */
   [key: string]: unknown
 }
 
-export function machine(config: MachineConfig): MachineDef {
-  const { name, on = {}, select = {}, ...context } = config
+const RESERVED = new Set(['name', 'on', 'select'])
+
+// Data-only: no behavior, no selectors.
+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.
+export function machine<
+  C extends Record<string, unknown>,
+  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>>
+export function machine(
+  first: Record<string, unknown>,
+  behavior?: ClientBehavior<never>,
+): 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>
+  }
   return defineMachine({
     name: name ?? 'ClientMachine',
     lifecycle: 'session',
-    events: {} as EventObject,
-    context: context as object,
+    events: {} as ClientEvent,
+    context,
     initial: 'active',
-    states: { active: { on } },
-    selectors: select,
+    states: { active: { on: on as never } },
+    selectors: select as never,
   }) as MachineDef
 }

package/src/client/use.ts

@@ -26,12 +26,23 @@ const CLIENT_HELPERS = {
  *   - `send(event)` to drive transitions.
  *   - the underlying actor (non-enumerable) for the binding loop to subscribe.
  */
-export interface ClientInstance {
+export interface ClientInstanceBase {
   send(event: { type: string; [k: string]: unknown } | string): void
   /** @internal — the actor a binding subscribes to. */
   readonly __actor: AnyActor
 }
 
+/** Context keys + selector results as readonly live properties — the typed
+ *  mirror of what the runtime proxy exposes. */
+type ClientView<D> =
+  D extends MachineDef<infer C, infer _E, infer _S, infer Sel, infer _N>
+    ? { readonly [K in keyof C]: C[K] } & {
+        readonly [K in keyof Sel]: Sel[K] extends (...args: never[]) => infer R ? R : never
+      }
+    : unknown
+
+export type ClientInstance<D extends MachineDef = MachineDef> = ClientInstanceBase & ClientView<D>
+
 /** An actor plus an optional deferred seed thunk — evaluated at the element's
  *  connect (when attributes are available), not at construction. */
 export interface CollectedActor {
@@ -61,10 +72,12 @@ export function popCollector(): void {
  * connect — required when the seed reads `this.attrs`, since attributes aren't
  * available at construction (the custom-element upgrade-timing rule).
  */
-export function use(
-  def: MachineDef,
-  seed?: Record<string, unknown> | (() => Record<string, unknown>),
-): ClientInstance {
+export function use<D extends MachineDef>(
+  def: D,
+  seed?: Partial<D['__context']> | (() => Partial<D['__context']>),
+): ClientInstance<D> {
+  // The live properties are defined dynamically below; the mapped view type
+  // is the static mirror of that runtime work.
   const eager = typeof seed === 'object' ? seed : undefined
   const snapshot: Snapshot<object> | undefined = eager
     ? {
@@ -110,10 +123,10 @@ export function use(
     get: () => actor,
   })
 
-  return inst as unknown as ClientInstance
+  return inst as unknown as ClientInstance<D>
 }
 
 /** Extract the actor from a `use()` instance (for the binding loop). */
-export function actorOf(inst: ClientInstance): AnyActor {
+export function actorOf(inst: ClientInstanceBase): AnyActor {
   return inst.__actor
 }

package/src/compiler/virtual-code.ts

@@ -43,10 +43,46 @@ export interface VirtualCodeResult {
   styles: VirtualFile[]
 }
 
-const TEMPLATE_IMPORTS =
-  "import { read, each, when, match, on, classList, styleList, raw } from '@statorjs/stator/template';\n"
-const CLIENT_IMPORTS =
-  "import { StatorElement, use, machine, defineElement, bind, effect, dispatch } from '@statorjs/stator/client';\n"
+// Must mirror the RUNTIME's auto-injected globals exactly (compile.ts
+// PRIMITIVES_IMPORT / client-emit.ts): a name injected here but not at
+// 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 CLIENT_GLOBALS = [
+  'StatorElement',
+  'use',
+  'machine',
+  'defineElement',
+  'bind',
+  'effect',
+  'dispatch',
+]
+
+/** Local names the user's code already binds from `modulePath` imports —
+ *  the runtime strips such habit-imports; the virtual emit (which must keep
+ *  offsets faithful) instead injects only what the user DIDN'T import. */
+function userImportedLocals(code: string, modulePath: string): Set<string> {
+  const locals = new Set<string>()
+  const re = new RegExp(
+    `import\\s+(?:type\\s+)?\\{([^}]*)\\}\\s+from\\s+['"]${modulePath.replace(/\//g, '\\/')}['"]`,
+    'g',
+  )
+  for (const m of code.matchAll(re)) {
+    for (const spec of m[1]!.split(',')) {
+      const parts = spec.trim().split(/\s+as\s+/)
+      const local = (parts[1] ?? parts[0] ?? '').trim().replace(/^type\s+/, '')
+      if (local) locals.add(local)
+    }
+  }
+  return locals
+}
+
+function injectImports(globals: string[], modulePath: string, userCode: string): string {
+  const bound = userImportedLocals(userCode, modulePath)
+  const missing = globals.filter((g) => !bound.has(g))
+  return missing.length > 0 ? `import { ${missing.join(', ')} } from '${modulePath}';\n` : ''
+}
 // Aliased so they never collide with a component's own `InstanceOf` import.
 // NOTE: `InstanceOf` comes from /template, not /machine — the template flavor
 // includes `send`/`state`/`snapshot` (what a route-level binding actually is,
@@ -99,7 +135,11 @@ export function toVirtualCode(source: string): VirtualCodeResult {
  *  template expressions see the frontmatter's bindings. */
 function buildServerTsx(regions: ScannedRegions): VirtualFile {
   const mappings: VirtualMapping[] = []
-  let code = TEMPLATE_IMPORTS + AMBIENT_TYPE_IMPORTS + STATOR_AMBIENT
+  const userCode = (regions.frontmatter?.content ?? '') + regions.template.content
+  let code =
+    injectImports(TEMPLATE_GLOBALS, '@statorjs/stator/template', userCode) +
+    AMBIENT_TYPE_IMPORTS +
+    STATOR_AMBIENT
 
   if (regions.frontmatter?.content.trim()) {
     push(
@@ -145,7 +185,12 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
  *  resolution — `bind:text={theme.label}` → the class field — is a later phase.) */
 function buildClientTsx(regions: ScannedRegions): VirtualFile {
   const mappings: VirtualMapping[] = []
-  let code = TEMPLATE_IMPORTS + CLIENT_IMPORTS + AMBIENT_TYPE_IMPORTS + STATOR_AMBIENT
+  const userScript = regions.scripts.map((s) => s.content).join('\n')
+  let code =
+    injectImports(TEMPLATE_GLOBALS, '@statorjs/stator/template', userScript) +
+    injectImports(CLIENT_GLOBALS, '@statorjs/stator/client', userScript) +
+    AMBIENT_TYPE_IMPORTS +
+    STATOR_AMBIENT
 
   for (const script of regions.scripts) {
     push(mappings, script.contentOffset, code.length, script.content.length)

package/src/server/banner.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs'
+import { networkInterfaces } from 'node:os'
+import { logger } from './logger.ts'
+
+/**
+ * Human-facing startup/exit output for the DEV plane. Production keeps
+ * structured pino logs (ops parse those); the dev server prints for a
+ * person: clickable URLs, a one-line inventory, a graceful goodbye.
+ */
+
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined
+const c = {
+  bold: (s: string) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+  dim: (s: string) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  cyan: (s: string) => (useColor ? `\x1b[36m${s}\x1b[0m` : s),
+  copper: (s: string) => (useColor ? `\x1b[38;5;173m${s}\x1b[0m` : s),
+}
+
+let cachedVersion: string | undefined
+function statorVersion(): string {
+  if (!cachedVersion) {
+    try {
+      const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+      cachedVersion = String(pkg.version)
+    } catch {
+      cachedVersion = ''
+    }
+  }
+  return cachedVersion
+}
+
+function lanAddress(): string | undefined {
+  for (const nets of Object.values(networkInterfaces())) {
+    for (const net of nets ?? []) {
+      if (net.family === 'IPv4' && !net.internal) return net.address
+    }
+  }
+  return undefined
+}
+
+export function printDevBanner(info: {
+  port: number
+  /** The port originally asked for, when the server had to shift off it. */
+  requestedPort?: number
+  machines: number
+  routes: number
+  inspector?: boolean
+}): void {
+  const v = statorVersion()
+  const lan = lanAddress()
+  const shifted =
+    info.requestedPort !== undefined && info.requestedPort !== info.port
+      ? [`  ${c.dim(`port ${info.requestedPort} was busy — using ${info.port}`)}`]
+      : []
+  const lines = [
+    '',
+    `  ${c.copper(c.bold('stator'))}${v ? c.dim(` v${v}`) : ''}  ${c.dim('dev server')}`,
+    '',
+    `  ${c.dim('local')}    ${c.cyan(`http://localhost:${info.port}/`)}`,
+    ...(lan ? [`  ${c.dim('network')}  ${c.cyan(`http://${lan}:${info.port}/`)}`] : []),
+    '',
+    `  ${c.dim(
+      `${info.machines} machine${info.machines === 1 ? '' : 's'} · ${info.routes} route${
+        info.routes === 1 ? '' : 's'
+      }${info.inspector ? ' · inspector on' : ''} — Ctrl+C to stop`,
+    )}`,
+    ...shifted,
+    '',
+  ]
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+/**
+ * Exit a server process like a well-mannered CLI: first signal closes
+ * cleanly and exits 0 (Ctrl+C is a normal action, not a failure — without
+ * this, the process dies 130 and pnpm prints an ELIFECYCLE error banner);
+ * a second signal force-quits for anything that hangs in close().
+ */
+export function installGracefulShutdown(close: () => Promise<void> | void, quiet = false): void {
+  let closing = false
+  const handler = (signal: NodeJS.Signals) => {
+    if (closing) process.exit(130)
+    closing = true
+    if (!quiet) process.stdout.write(`\n${c.dim('  stopping…')}\n`)
+    void (async () => {
+      try {
+        await close()
+      } catch (err) {
+        logger.warn({ err: String(err) }, 'error during shutdown')
+      }
+      process.exit(0)
+    })()
+    void signal
+  }
+  process.on('SIGINT', handler)
+  process.on('SIGTERM', handler)
+}
+
+/** First free TCP port at or above `start` (bounded probe). The dev plane
+ *  auto-shifts off busy ports like every modern dev server; production
+ *  never calls this — a taken port there is a deploy error to surface. */
+export async function findFreePort(start: number, attempts = 10): Promise<number> {
+  const { createServer } = await import('node:net')
+  for (let port = start; port < start + attempts; port++) {
+    const free = await new Promise<boolean>((resolve) => {
+      const probe = createServer()
+      probe.once('error', () => resolve(false))
+      probe.once('listening', () => probe.close(() => resolve(true)))
+      probe.listen(port)
+    })
+    if (free) return port
+  }
+  throw new Error(`stator: no free port found in ${start}–${start + attempts - 1}`)
+}

package/src/server/create-app.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import { serve } from '@hono/node-server'
 import type { AppStore } from './app-store.ts'
+import { installGracefulShutdown } from './banner.ts'
 import { discoverMachines } from './discovery.ts'
 import { wireAppEffects } from './effects.ts'
 import { buildHonoApp } from './http.ts'
@@ -71,10 +72,25 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   return {
     listen(port: number): Promise<void> {
       return new Promise((resolveFn) => {
-        serve({ fetch: app.fetch, port }, () => {
+        const server = serve({ fetch: app.fetch, port }, () => {
           logger.info({ port, machines: defs.length, routes: routes.length }, 'listening')
           resolveFn()
         })
+        // Production is strict about its port (a collision is a deploy
+        // error) — but says so in one line, not a stack trace.
+        server.on('error', (err: NodeJS.ErrnoException) => {
+          if (err.code === 'EADDRINUSE') {
+            logger.error(
+              { port },
+              `port ${port} is already in use — is another instance running? (set PORT to change it)`,
+            )
+            process.exit(1)
+          }
+          throw err
+        })
+        // Ctrl+C / SIGTERM (deploy rollover) exits 0, not 130 — quiet in
+        // prod: the structured logs are the record.
+        installGracefulShutdown(() => new Promise<void>((done) => server.close(() => done())), true)
       })
     },
     fetch: (request: Request) => app.fetch(request),

package/src/server/dev.ts

@@ -7,6 +7,7 @@ import { createServer as createViteServer, type ViteDevServer } from 'vite'
 import { compile } from '../compiler/index.ts'
 import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
+import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { logger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -51,10 +52,14 @@ export interface DevApp {
 }
 
 export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
+  // stator apps side by side would fight over it (the loser's live reload
+  // silently dies). Probe a free one instead.
+  const hmrPort = await findFreePort(24678)
   const vite = await createViteServer({
     root: resolve(config.root),
     appType: 'custom',
-    server: { middlewareMode: true },
+    server: { middlewareMode: true, hmr: { port: hmrPort } },
     // machineStub keeps server machines out of browser module graphs: island
     // imports of a machine resolve to a `{ name }` stub (SSR loads are
     // untouched — `options.ssr` gates it).
@@ -194,20 +199,27 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       const server = createHttpServer((req, res) => {
         vite.middlewares(req, res, () => honoListener(req, res))
       })
-      return new Promise((resolveFn) => {
-        server.listen(port, () => {
-          logger.info(
-            {
-              port,
-              mode: 'dev',
-              machines: machineCount,
-              routes: routes.length,
-            },
-            'listening',
-          )
-          resolveFn()
-        })
+      installGracefulShutdown(async () => {
+        await vite.close()
+        await new Promise<void>((done) => server.close(() => done()))
       })
+      // Busy port? Shift up like every modern dev server (the requested
+      // port is someone's other project, not an error).
+      return findFreePort(port).then(
+        (freePort) =>
+          new Promise((resolveFn) => {
+            server.listen(freePort, () => {
+              printDevBanner({
+                port: freePort,
+                requestedPort: port,
+                machines: machineCount,
+                routes: routes.length,
+                inspector: true,
+              })
+              resolveFn()
+            })
+          }),
+      )
     },
     close: () => vite.close(),
   }