npm - @statorjs/stator - Versions diffs - 1.0.0 - Mend

@statorjs/stator 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/LICENSE +21 -0
package/README.md +104 -0
package/package.json +99 -0
package/src/build/build.ts +244 -0
package/src/build/head.ts +43 -0
package/src/build/index.ts +10 -0
package/src/build/sync.ts +65 -0
package/src/client/bind.ts +47 -0
package/src/client/client-id.ts +10 -0
package/src/client/dispatch.ts +62 -0
package/src/client/element.ts +156 -0
package/src/client/index.ts +13 -0
package/src/client/inspector.ts +237 -0
package/src/client/machine.ts +39 -0
package/src/client/runtime.ts +246 -0
package/src/client/use.ts +119 -0
package/src/compiler/client-emit.ts +180 -0
package/src/compiler/client-script.ts +256 -0
package/src/compiler/compile.ts +459 -0
package/src/compiler/diagnostics.ts +65 -0
package/src/compiler/dts.ts +87 -0
package/src/compiler/hash.ts +8 -0
package/src/compiler/index.ts +48 -0
package/src/compiler/lower.ts +0 -0
package/src/compiler/regions.ts +79 -0
package/src/compiler/split.ts +168 -0
package/src/compiler/styles.ts +200 -0
package/src/compiler/virtual-code.ts +184 -0
package/src/components/index.ts +2 -0
package/src/components/json-ld.ts +85 -0
package/src/engine/actor.ts +248 -0
package/src/engine/define-machine.ts +113 -0
package/src/engine/index.ts +37 -0
package/src/engine/types.ts +236 -0
package/src/server/api-route.ts +149 -0
package/src/server/app-dispatch.ts +52 -0
package/src/server/app-store.ts +35 -0
package/src/server/cached-store.ts +117 -0
package/src/server/create-app.ts +83 -0
package/src/server/define-machine.ts +10 -0
package/src/server/dev.ts +255 -0
package/src/server/discovery.ts +111 -0
package/src/server/dispatch-context.ts +39 -0
package/src/server/effects.ts +120 -0
package/src/server/http.ts +475 -0
package/src/server/index.ts +101 -0
package/src/server/instance-proxy.ts +95 -0
package/src/server/logger.ts +52 -0
package/src/server/machine-store.ts +355 -0
package/src/server/reads-helpers.ts +40 -0
package/src/server/recompute.ts +287 -0
package/src/server/redis-store.ts +116 -0
package/src/server/render-context.ts +228 -0
package/src/server/render.ts +111 -0
package/src/server/route-discovery.ts +226 -0
package/src/server/route-request.ts +36 -0
package/src/server/routing.ts +175 -0
package/src/server/session-lock.ts +33 -0
package/src/server/session-runtime.ts +242 -0
package/src/server/session.ts +29 -0
package/src/server/sse.ts +175 -0
package/src/server/store.ts +95 -0
package/src/stator-modules.d.ts +12 -0
package/src/template/client-shell.ts +65 -0
package/src/template/conditional.ts +166 -0
package/src/template/directives/core.ts +58 -0
package/src/template/directives/list-attr.ts +183 -0
package/src/template/directives/on.ts +22 -0
package/src/template/each.ts +295 -0
package/src/template/html.ts +180 -0
package/src/template/index.ts +29 -0
package/src/template/parser.ts +341 -0
package/src/template/read.ts +50 -0
package/src/template/types.ts +33 -0
package/src/vite/index.ts +6 -0
package/src/vite/plugin.ts +151 -0
package/src/vite/stub.ts +79 -0
package/src/wire/apply.ts +103 -0
package/src/wire/index.ts +67 -0

package/src/server/http.ts ADDED Viewed

@@ -0,0 +1,475 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, extname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+import { type Context, Hono } from 'hono'
+import { streamSSE } from 'hono/streaming'
+import { z } from 'zod'
+import { applyRenderedEffects, runApiRoute } from './api-route.ts'
+import { scheduleSessionEffects } from './effects.ts'
+import { scopedLogger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+import { initialSyncPatches, recompute } from './recompute.ts'
+import { renderRoute } from './render.ts'
+import type { DiscoveredRoute } from './route-discovery.ts'
+import { buildRouteRequest } from './route-request.ts'
+import type { RouteDefinition } from './routing.ts'
+import { getOrCreateSessionId } from './session.ts'
+import { withSessionLock } from './session-lock.ts'
+import { SessionRuntime } from './session-runtime.ts'
+import { fanOut, registerConnection, unregisterConnection } from './sse.ts'
+const httpLog = scopedLogger('http')
+export interface HttpConfig {
+  routes: DiscoveredRoute[]
+  store: MachineStore
+  staticDir?: string
+  /** Optional hook to inject extra `<head>` HTML for a GET route, keyed by the
+   *  route's file path. The dev server uses this to inline collected scoped CSS
+   *  (SSR head injection). Inserted at the `</head>` boundary. */
+  headExtras?: (filePath: string) => string | Promise<string>
+  /** Serve the dev inspector asset at `/@stator/inspector.js`. The dev server
+   *  sets this and injects the script tag; production leaves it off. */
+  inspector?: boolean
+}
+const eventSchema = z.object({
+  machine: z.string(),
+  event: z
+    .object({
+      type: z.string(),
+    })
+    .passthrough(),
+})
+/** Compiled matcher: turns `/p/:id` into a regex that captures params. */
+interface RouteMatcher {
+  route: DiscoveredRoute
+  regex: RegExp
+}
+function compileMatcher(route: DiscoveredRoute): RouteMatcher {
+  // Translate Hono-pattern (`/p/:id`) into a regex that matches a literal
+  // URL path and captures each param value.
+  // A rest segment (`*name`) consumes the remainder including its leading slash,
+  // so it can match zero segments (`/files` for `/files/[...path]`).
+  const parts = route.urlPath.split('/')
+  let pattern = ''
+  for (let i = 0; i < parts.length; i++) {
+    const seg = parts[i]!
+    if (seg.startsWith('*')) {
+      // Absorb the preceding `/` and match the (possibly empty) remainder.
+      pattern = `${pattern.replace(/\/$/, '')}(?:/(.*))?`
+    } else if (seg.startsWith(':')) {
+      pattern += '([^/]+)'
+      if (i < parts.length - 1) pattern += '/'
+    } else {
+      pattern += seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      if (i < parts.length - 1) pattern += '/'
+    }
+  }
+  return { route, regex: new RegExp(`^${pattern}$`) }
+}
+/**
+ * Match a literal URL path against compiled matchers. Returns the matched
+ * route + extracted params, or null if nothing matches.
+ */
+function matchPath(
+  matchers: RouteMatcher[],
+  literalPath: string,
+): { route: DiscoveredRoute; params: Record<string, string> } | null {
+  for (const m of matchers) {
+    const result = m.regex.exec(literalPath)
+    if (!result) continue
+    const params: Record<string, string> = {}
+    m.route.paramNames.forEach((name, i) => {
+      params[name] = decodeURIComponent(result[i + 1] ?? '')
+    })
+    return { route: m.route, params }
+  }
+  return null
+}
+/** Parse a route key like "GET /p/abc-123" into method + literal path. */
+function parseRouteKey(
+  routeKey: string,
+): { method: string; path: string; query: Record<string, string | undefined> } | null {
+  const space = routeKey.indexOf(' ')
+  if (space < 0) return null
+  const target = routeKey.slice(space + 1)
+  // The page's ?query travels IN the route key — a baseline re-render for a
+  // query-dependent page (facets, pagination) must see the same request the
+  // GET did, or its diffs describe a page the browser isn't showing.
+  const q = target.indexOf('?')
+  const path = q === -1 ? target : target.slice(0, q)
+  const query: Record<string, string | undefined> = {}
+  if (q !== -1) {
+    for (const [k, v] of new URLSearchParams(target.slice(q + 1))) query[k] = v
+  }
+  return { method: routeKey.slice(0, space), path, query }
+}
+export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
+  const app = new Hono()
+  const clientJs = await bundleClient()
+  // Request logger: one line per request with method, path, status, duration.
+  // SSE endpoints stay open indefinitely; we log on entry, not on close.
+  app.use('*', async (c, next) => {
+    const start = performance.now()
+    await next()
+    const ms = Math.round(performance.now() - start)
+    const status = c.res.status
+    const isLive = c.req.path === '/__sse'
+    httpLog[status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info'](
+      {
+        method: c.req.method,
+        path: c.req.path,
+        status,
+        ms,
+        sse: isLive || undefined,
+      },
+      isLive ? 'sse open' : 'request',
+    )
+  })
+  // Compile matchers for every route, in discovery's specificity order. Our own
+  // matcher (not Hono's router) is the routing authority: GET/API dispatch and
+  // SSE/POST resolution all go through `matchPath`, so rest params (`*name`) and
+  // specificity ordering behave identically everywhere. Hono only routes the
+  // fixed framework endpoints (static exact paths it prioritizes over `*`).
+  const matchers: RouteMatcher[] = config.routes.map(compileMatcher)
+  const getMatchers = matchers // SSE/POST filter by `.GET` after matching
+  app.get('/static/client.js', (c) => {
+    c.header('Content-Type', 'application/javascript; charset=utf-8')
+    c.header('Cache-Control', 'no-cache')
+    return c.body(clientJs)
+  })
+  // Dev inspector asset — served only when enabled (the dev server injects the
+  // matching script tag). Bundled lazily on first build of the app.
+  if (config.inspector) {
+    const inspectorJs = await bundleInspector()
+    app.get('/@stator/inspector.js', (c) => {
+      c.header('Content-Type', 'application/javascript; charset=utf-8')
+      c.header('Cache-Control', 'no-cache')
+      return c.body(inspectorJs)
+    })
+  }
+  if (config.staticDir) {
+    const staticDir = config.staticDir
+    app.get('/static/*', async (c) => {
+      const rel = c.req.path.replace(/^\/static\//, '')
+      if (rel.includes('..')) return c.text('forbidden', 403)
+      try {
+        const buf = await readFile(resolve(staticDir, rel))
+        c.header('Content-Type', contentTypeFor(rel))
+        return c.body(buf)
+      } catch {
+        return c.text('not found', 404)
+      }
+    })
+  }
+  // SSE endpoint. The connection's runtime + renderState stay alive for
+  // the connection's lifetime — this is the one place per-session state
+  // outlives a request, because the connection *is* one (very long) request.
+  app.get('/__sse', async (c) => {
+    const routeKey = c.req.query('route')
+    if (!routeKey) return c.text('missing route param', 400)
+    const parsed = parseRouteKey(routeKey)
+    if (parsed?.method !== 'GET') {
+      return c.text(`malformed route key "${routeKey}"`, 400)
+    }
+    const matched = matchPath(getMatchers, parsed.path)
+    if (!matched?.route.GET) {
+      return c.text(`unknown route "${routeKey}"`, 404)
+    }
+    const route = matched.route.GET
+    if (!route.live) {
+      return c.text(`route "${routeKey}" is not declared live: true`, 400)
+    }
+    // The SSE endpoint's own Request becomes the connection's request
+    // object for fan-out renders. params come from the matched literal path;
+    // the page's ?query rides in the route key.
+    const request = {
+      ...buildRouteRequest(c, matched.route.paramNames),
+      params: matched.params,
+      query: parsed.query,
+    }
+    const { sessionId } = getOrCreateSessionId(c)
+    // Tell intermediate proxies (Fly edge, nginx, others) not to buffer the
+    // response. Without this, small SSE messages can accumulate in a proxy
+    // buffer waiting for a fill threshold, producing batched / dropped-
+    // looking delivery on the client.
+    c.header('X-Accel-Buffering', 'no')
+    return streamSSE(c, async (stream) => {
+      const runtime = new SessionRuntime(sessionId, config.store)
+      await runtime.loadGraph(route.reads)
+      const { renderState } = renderRoute(route, routeKey, sessionId, runtime, request)
+      const conn = registerConnection({
+        sessionId,
+        clientId: c.req.query('client'),
+        routeKey,
+        route,
+        request,
+        runtime,
+        renderState,
+        send: async (data: string) => {
+          await stream.writeSSE({ data })
+        },
+      })
+      // Force an immediate flush so edge proxies commit response headers
+      // and consider the stream "alive" before any fan-out arrives.
+      await stream.write(': open\n\n')
+      // Converge the page onto this connection's baseline: the DOM was
+      // rendered at page-GET time, the baseline at connect time, and any
+      // state change in between (an effect settling mid-navigation) would
+      // otherwise never reach this page.
+      const sync = initialSyncPatches(renderState, runtime)
+      if (sync.length > 0) {
+        await conn.send(JSON.stringify({ patches: sync }))
+      }
+      // Keep-alive every 25s so proxy idle timeouts don't close the
+      // connection between real events.
+      const keepAlive = setInterval(() => {
+        stream.write(': keep-alive\n\n').catch(() => {
+          // Stream closed; will be cleaned up by abort handler.
+        })
+      }, 25_000)
+      try {
+        await new Promise<void>((resolveFn) => {
+          stream.onAbort(() => resolveFn())
+        })
+      } finally {
+        clearInterval(keepAlive)
+        unregisterConnection(conn.id)
+      }
+    })
+  })
+  app.post('/__events', async (c) => {
+    const { sessionId } = getOrCreateSessionId(c)
+    const routeKey = c.req.header('X-Stator-Route')
+    if (!routeKey) {
+      return c.json({ error: 'missing X-Stator-Route header' }, 400)
+    }
+    const parsed = parseRouteKey(routeKey)
+    if (parsed?.method !== 'GET') {
+      return c.json({ error: `malformed route key "${routeKey}"` }, 400)
+    }
+    const matched = matchPath(getMatchers, parsed.path)
+    if (!matched?.route.GET) {
+      return c.json({ error: `unknown route "${routeKey}"` }, 404)
+    }
+    const route = matched.route.GET
+    const request = {
+      ...buildRouteRequest(c, matched.route.paramNames),
+      params: matched.params,
+      query: parsed.query,
+    }
+    let body: z.infer<typeof eventSchema>
+    try {
+      body = eventSchema.parse(await c.req.json())
+    } catch (e) {
+      return c.json({ error: 'invalid event payload', detail: String(e) }, 400)
+    }
+    const originDef = config.store.getDef(body.machine)
+    if (!originDef) {
+      return c.json({ error: `unknown machine "${body.machine}"` }, 404)
+    }
+    return withSessionLock(sessionId, async () => {
+      const runtime = new SessionRuntime(sessionId, config.store)
+      try {
+        await runtime.loadGraph([...route.reads, originDef])
+        runtime.wireSubscriptions()
+        const { renderState } = renderRoute(route, routeKey, sessionId, runtime, request)
+        const touched = runtime.processEvent(body.machine, body.event)
+        // Reads-aware selectors: bindings of machines whose selectors READ a
+        // touched machine must re-diff too. Persistence stays direct-only —
+        // derived machines' own state didn't move.
+        const { all: recomputeSet } = config.store.expandTouchedForRecompute(touched)
+        const patches = []
+        for (const name of recomputeSet) {
+          patches.push(...recompute(renderState, name, runtime))
+        }
+        await runtime.persistTouched(touched)
+        await fanOut(touched, {
+          sessionId,
+          originClientId: c.req.header('X-Stator-Client'),
+        })
+        // Fire-and-forget: the effects' I/O runs after this callback returns
+        // (the lock is never held across it); completions re-enter via the
+        // normal event path in server/effects.ts.
+        scheduleSessionEffects(runtime, config.store, sessionId)
+        return c.json({ patches, directives: [], committed: touched.size > 0 })
+      } finally {
+        runtime.dispose()
+      }
+    })
+  })
+  // User-route dispatch: catch-alls resolved by our matcher, registered LAST so
+  // the fixed framework endpoints (/__events, /__sse, /static/*) — all registered
+  // above — take their requests first. A request that matches no user route falls
+  // through to Hono's default (so framework paths handled above are untouched).
+  for (const method of ['POST', 'PUT', 'PATCH', 'DELETE'] as const) {
+    app.on(method, '*', async (c, next) => {
+      const matched = matchPath(matchers, c.req.path)
+      const apiRoute = matched?.route[method]
+      if (!matched || !apiRoute) return next()
+      return runApiRoute(c, matched.route, apiRoute, config.store, matched.params)
+    })
+  }
+  app.get('*', async (c, next) => {
+    const matched = matchPath(matchers, c.req.path)
+    if (!matched?.route.GET) return next()
+    return handleGet(
+      c,
+      matched.route,
+      matched.route.GET,
+      matched.params,
+      config.store,
+      config.headExtras,
+    )
+  })
+  return app
+}
+let cachedClientJs: string | null = null
+async function bundleClient(): Promise<string> {
+  if (cachedClientJs) return cachedClientJs
+  const here = dirname(fileURLToPath(import.meta.url))
+  const entry = resolve(here, '../client/runtime.ts')
+  const result = await build({
+    entryPoints: [entry],
+    bundle: true,
+    format: 'iife',
+    target: 'es2020',
+    write: false,
+    minify: false,
+    logLevel: 'silent',
+  })
+  cachedClientJs = result.outputFiles[0]!.text
+  return cachedClientJs
+}
+let cachedInspectorJs: string | null = null
+async function bundleInspector(): Promise<string> {
+  if (cachedInspectorJs) return cachedInspectorJs
+  const here = dirname(fileURLToPath(import.meta.url))
+  const entry = resolve(here, '../client/inspector.ts')
+  const result = await build({
+    entryPoints: [entry],
+    bundle: true,
+    format: 'iife',
+    target: 'es2020',
+    write: false,
+    minify: false,
+    logLevel: 'silent',
+  })
+  cachedInspectorJs = result.outputFiles[0]!.text
+  return cachedInspectorJs
+}
+/**
+ * Insert framework HTML at the document's `<head>` and end-of-`<body>`
+ * boundaries — each a no-op when its boundary is absent (e.g. a route that
+ * renders a bare fragment, which can't host the runtime anyway). One
+ * consolidated injector rather than stacked `.replace()` calls.
+ */
+function injectIntoDocument(html: string, parts: { head?: string; bodyEnd?: string }): string {
+  let out = html
+  if (parts.head && out.includes('</head>')) {
+    out = out.replace('</head>', `${parts.head}</head>`)
+  }
+  if (parts.bodyEnd && out.includes('</body>')) {
+    out = out.replace('</body>', `${parts.bodyEnd}</body>`)
+  }
+  return out
+}
+async function handleGet(
+  c: Context,
+  discovered: DiscoveredRoute,
+  route: RouteDefinition,
+  params: Record<string, string>,
+  store: MachineStore,
+  headExtras?: (filePath: string) => string | Promise<string>,
+): Promise<Response> {
+  {
+    const { sessionId } = getOrCreateSessionId(c)
+    const literalPath = c.req.path
+    const routeKey = `GET ${literalPath}`
+    const request = { ...buildRouteRequest(c, discovered.paramNames), params }
+    const runtime = new SessionRuntime(sessionId, store)
+    try {
+      await runtime.loadGraph(route.reads)
+      const result = renderRoute(route, routeKey, sessionId, runtime, request)
+      let html = result.html
+      const headHtml: string[] = []
+      if (headExtras) {
+        const extra = await headExtras(discovered.filePath)
+        if (extra) headHtml.push(extra)
+      }
+      if (route.live) headHtml.push('<meta name="stator-live" content="true">')
+      // Auto-inject the client runtime (delegated events + patch application).
+      // Apps never hand-include it — a forgotten <script> is a silently dead
+      // page (events fire nothing, no patches apply). Idempotent: skipped if the
+      // document already references it, so a layout that still carries the tag
+      // (or two passes sharing a doc) never loads it twice.
+      const bodyHtml: string[] = []
+      if (!html.includes('/static/client.js')) {
+        bodyHtml.push('<script src="/static/client.js"></script>')
+      }
+      html = injectIntoDocument(html, {
+        head: headHtml.join(''),
+        bodyEnd: bodyHtml.join(''),
+      })
+      applyRenderedEffects(c, result.response)
+      return c.html(html)
+    } finally {
+      runtime.dispose()
+    }
+  }
+}
+function contentTypeFor(path: string): string {
+  const ext = extname(path).toLowerCase()
+  if (ext === '.css') return 'text/css; charset=utf-8'
+  if (ext === '.js' || ext === '.mjs') return 'application/javascript; charset=utf-8'
+  if (ext === '.json') return 'application/json; charset=utf-8'
+  if (ext === '.svg') return 'image/svg+xml'
+  if (ext === '.png') return 'image/png'
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg'
+  return 'application/octet-stream'
+}

package/src/server/index.ts ADDED Viewed

@@ -0,0 +1,101 @@
+export type {
+  ElementTarget,
+  Patch,
+  PatchTarget,
+  SlotTarget,
+  WireEnvelope,
+} from '../wire/index.ts'
+export { dispatchToApp } from './app-dispatch.ts'
+export type { AppStore } from './app-store.ts'
+export { InMemoryAppStore } from './app-store.ts'
+export type { CachedStoreOptions } from './cached-store.ts'
+export { CachedStore } from './cached-store.ts'
+export type { CreateAppConfig, StatorApp } from './create-app.ts'
+export { createApp } from './create-app.ts'
+export type {
+  ActionHelpers,
+  DefineMachineConfig,
+  Lifecycle,
+  MachineDef,
+  SelectorMap,
+  SubscribeEntry,
+  SubscribeEvent,
+} from './define-machine.ts'
+export { defineMachine, isStatorMachine } from './define-machine.ts'
+export type { DiscoveryResult } from './discovery.ts'
+export { discoverMachines } from './discovery.ts'
+export type { DispatchContext } from './dispatch-context.ts'
+export {
+  getDispatchContext,
+  recordTouch,
+  withDispatchContext,
+} from './dispatch-context.ts'
+export { scheduleSessionEffects, wireAppEffects } from './effects.ts'
+export type { HttpConfig } from './http.ts'
+export { buildHonoApp } from './http.ts'
+export type { InstanceHandle } from './instance-proxy.ts'
+export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
+export { logger, scopedLogger } from './logger.ts'
+export { MachineStore } from './machine-store.ts'
+export { recompute } from './recompute.ts'
+export { RedisAppStore, RedisStore } from './redis-store.ts'
+export type { RenderResult } from './render.ts'
+export { renderRoute } from './render.ts'
+export type {
+  Binding,
+  BindingKind,
+  ElementId,
+  EventDescriptor,
+  MachineName,
+  RenderState,
+  SessionId,
+  SlotId,
+} from './render-context.ts'
+export {
+  allocElementId,
+  allocSlotId,
+  createEventDescriptor,
+  createRenderState,
+  getCurrentRenderState,
+  isEventDescriptor,
+  popListScope,
+  pushListScope,
+  registerBinding,
+  requireCurrentRenderState,
+  runInRender,
+  unregisterBindingsForScope,
+} from './render-context.ts'
+export type { DiscoveredRoute } from './route-discovery.ts'
+export { discoverRoutes } from './route-discovery.ts'
+export type {
+  ApiRouteDefinition,
+  ApiRouteEnvelope,
+  ApiRouteHelpers,
+  ApiRouteResult,
+  DefineApiRouteConfig,
+  DefineRouteConfig,
+  Directive,
+  RouteContext,
+  RouteCookieOptions,
+  RouteDefinition,
+  RouteRenderContext,
+  RouteRequest,
+  RouteResponseContext,
+} from './routing.ts'
+export {
+  defineApiRoute,
+  defineRoute,
+  isStatorApiRoute,
+  isStatorRoute,
+} from './routing.ts'
+export { getOrCreateSessionId, SESSION_COOKIE } from './session.ts'
+export { SessionRuntime } from './session-runtime.ts'
+export type { Connection } from './sse.ts'
+export {
+  activeConnectionCount,
+  fanOut,
+  registerConnection,
+  unregisterConnection,
+} from './sse.ts'
+export type { Store } from './store.ts'
+export { InMemoryStore } from './store.ts'

package/src/server/instance-proxy.ts ADDED Viewed

@@ -0,0 +1,95 @@
+import type { ActionHelpers, AnyActor, AnyMachineDef, MachineDef } from '../engine/index.ts'
+import type { InstanceOf } from '../template/types.ts'
+import {
+  createEventDescriptor,
+  type EventDescriptor,
+  getCurrentRenderState,
+} from './render-context.ts'
+export interface InstanceHandle<TDef extends MachineDef = MachineDef> {
+  readonly def: TDef
+  readonly actor: AnyActor
+  readonly proxy: InstanceOf<TDef>
+}
+const proxyToDef = new WeakMap<object, AnyMachineDef>()
+export function defForProxy(proxy: object): AnyMachineDef | undefined {
+  return proxyToDef.get(proxy)
+}
+export function createInstanceProxy<TDef extends MachineDef>(
+  def: TDef,
+  actor: AnyActor,
+  /** Resolve a sibling machine's proxy for reads-aware selectors. Lazy —
+   *  called at selector-access time, so graph load order doesn't matter.
+   *  Omitted (tests, contexts without a graph): reads access throws. */
+  resolveRead?: (name: string) => unknown,
+): InstanceHandle<TDef> {
+  const proxy = Object.create(null) as Record<string, unknown>
+  // Selectors receive the same helpers shape actions/guards get. The reads
+  // views are the sibling proxies themselves, so a read machine's own
+  // reads-aware selectors recurse naturally. (A reads-cycle between
+  // selectors is an author error and shows up as a stack overflow.)
+  const helpers: ActionHelpers = {
+    reads: new Proxy({} as Record<string, unknown>, {
+      get(_t, prop: string) {
+        const sibling = resolveRead?.(prop)
+        if (sibling === undefined) {
+          throw new Error(
+            `stator: selector on "${def.name}" accessed reads.${prop}, but "${prop}" ` +
+              `is not resolvable here — declare it in reads: and evaluate selectors ` +
+              `through a runtime/store-backed instance.`,
+          )
+        }
+        return sibling
+      },
+    }),
+  }
+  for (const [name, selector] of Object.entries(def.selectors)) {
+    Object.defineProperty(proxy, name, {
+      enumerable: true,
+      configurable: false,
+      get: () => selector(actor.getSnapshot().context, helpers),
+    })
+  }
+  Object.defineProperty(proxy, 'send', {
+    enumerable: false,
+    configurable: false,
+    value: (event: { type: string; [k: string]: unknown }): EventDescriptor | undefined => {
+      if (getCurrentRenderState()) {
+        return createEventDescriptor(def.name, event)
+      }
+      actor.send(event as never)
+      return undefined
+    },
+  })
+  Object.defineProperty(proxy, 'state', {
+    enumerable: true,
+    configurable: false,
+    // Engine state value is a path array (`['idle']`); expose the leaf name as
+    // a string so templates/selectors see the current state key as before.
+    get: () => {
+      const v = actor.getSnapshot().value
+      return v[v.length - 1]
+    },
+  })
+  Object.defineProperty(proxy, 'snapshot', {
+    enumerable: true,
+    configurable: false,
+    get: () => actor.getSnapshot(),
+  })
+  proxyToDef.set(proxy, def)
+  return {
+    def,
+    actor,
+    proxy: proxy as unknown as InstanceOf<TDef>,
+  }
+}