@statorjs/stator 1.0.0

package/src/client/dispatch.ts

@@ -0,0 +1,62 @@
+import type { AnyMachineDef, EventOf } from '../engine/index.ts'
+import { applyDirectives, applyPatches } from '../wire/apply.ts'
+import type { WireEnvelope } from '../wire/index.ts'
+import { clientId } from './client-id.ts'
+
+export interface DispatchResult {
+  /** The POST reached the server and returned 200. */
+  ok: boolean
+  /** The event committed a transition. `ok && !committed` means a guard
+   *  dropped it — the UI should not pretend something happened. */
+  committed: boolean
+  /** Patches applied to THIS page (a committed event may patch zero slots
+   *  here if the touched machines aren't bound on the current route). */
+  patchCount: number
+}
+
+/**
+ * Commit an event to a SERVER machine over the existing `/__events` wire — the
+ * one visible boundary crossing from a client island. Addressed by the imported
+ * machine def (not a magic string); the event is typed against that machine's
+ * event union. Applies the returned patches and reports what actually
+ * happened: transport success, commit, and patch count are three different
+ * facts, and buttons that say "done" should be looking at `committed`.
+ *
+ * This is the client half of [[typed-events-and-machine-mediated-dispatch]].
+ * The compiler resolves a server-machine identity import into a stub carrying
+ * `{ name }`; this helper reads the name and posts.
+ */
+export async function dispatch<D extends AnyMachineDef>(
+  machine: D,
+  event: EventOf<D>,
+): Promise<DispatchResult> {
+  let res: Response
+  try {
+    res = await fetch('/__events', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'X-Stator-Route': `GET ${location.pathname}${location.search}`,
+        'X-Stator-Client': clientId,
+      },
+      credentials: 'same-origin',
+      body: JSON.stringify({ machine: machine.name, event }),
+    })
+  } catch (err) {
+    console.error('stator: dispatch network error', err)
+    return { ok: false, committed: false, patchCount: 0 }
+  }
+  if (!res.ok) {
+    console.error('stator: dispatch failed', res.status)
+    return { ok: false, committed: false, patchCount: 0 }
+  }
+  const data = (await res.json()) as WireEnvelope
+  applyPatches(data.patches ?? [])
+  applyDirectives(data.directives ?? [])
+  return {
+    ok: true,
+    committed: data.committed ?? true,
+    patchCount: data.patches?.length ?? 0,
+  }
+}

package/src/client/element.ts

@@ -0,0 +1,156 @@
+import { type CollectedActor, popCollector, pushCollector } from './use.ts'
+
+const ACTORS = Symbol('stator.actors')
+const DISPOSERS = Symbol('stator.disposers')
+
+/** camelCase author name → kebab DOM attribute (`unitPrice` → `unit-price`). */
+function camelToKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+}
+
+/** kebab DOM attribute → camelCase author name (`unit-price` → `unitPrice`). */
+function kebabToCamel(name: string): string {
+  return name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
+}
+
+/**
+ * Base class for a client island. The author writes
+ * `export class QuantityStepper extends StatorElement { ... }`; the compiler
+ * registers it (via `defineElement`) against the kebab-case tag.
+ *
+ * Lifecycle: on connect, start the actors created by `use()` during
+ * construction and run the element's `setup()` (where the compiler emits the
+ * `bind()` / `on:` wiring); on disconnect, dispose bindings and stop actors.
+ * Element lifetime owns actor lifetime — full-page navigation resets client
+ * state, which is the intended default for ephemeral UI.
+ */
+export class StatorElement extends HTMLElement {
+  /** @internal — actors (+ deferred seed thunks) collected during construction
+   *  (set by `defineElement`). */
+  [ACTORS]: CollectedActor[] = [];
+  /** @internal — binding disposers registered during setup. */
+  [DISPOSERS]: Array<() => void> = []
+
+  /** Named handles to `ref:`-marked elements within this island, resolved
+   *  lazily by `data-ref`. `this.refs.btn` → the nearest `[data-ref="btn"]`. */
+  get refs(): Record<string, HTMLElement> {
+    const self = this
+    return new Proxy(
+      {},
+      {
+        get(_t, name: string) {
+          return self.querySelector(`[data-ref="${name}"]`) as HTMLElement | null
+        },
+      },
+    ) as Record<string, HTMLElement>
+  }
+
+  /** Read + coerce a single attribute by its literal name (raw escape hatch for
+   *  dynamic / undeclared attributes). */
+  attr<T = string>(name: string, coerce?: (raw: string) => T): T | undefined {
+    const raw = this.getAttribute(name)
+    if (raw === null) return undefined
+    return coerce ? coerce(raw) : (raw as unknown as T)
+  }
+
+  /** Typed, coerced view of the element's declared attributes.
+   *
+   *  `static attrs = { unitPrice: Number, selected: Boolean }` declares the
+   *  surface; `this.attrs.unitPrice` reads the kebab DOM attribute (`unit-price`)
+   *  and coerces it. `Number`/parse coercers run on the string; `Boolean` is
+   *  treated as a presence flag (attribute present → true). camelCase author name
+   *  ↔ kebab DOM attribute is framework-managed. */
+  get attrs(): Record<string, unknown> {
+    const decl = (this.constructor as { attrs?: Record<string, (raw: string) => unknown> }).attrs
+    const self = this
+    return new Proxy(
+      {},
+      {
+        get(_t, prop: string) {
+          const coerce = decl?.[prop]
+          const attrName = camelToKebab(prop)
+          if (coerce === (Boolean as unknown)) {
+            return self.hasAttribute(attrName)
+          }
+          const raw = self.getAttribute(attrName)
+          if (raw === null) return undefined
+          return coerce ? coerce(raw) : raw
+        },
+      },
+    )
+  }
+
+  /** Register a disposer to run on disconnect (used by generated bind wiring). */
+  protected track(dispose: () => void): void {
+    this[DISPOSERS].push(dispose)
+  }
+
+  /** Overridden by the compiler-generated subclass: wires bindings + listeners.
+   *  Runs after actors start, on connect. */
+  protected setup(): void {}
+
+  connectedCallback(): void {
+    // Apply deferred seeds now that attributes are available, then start.
+    for (const { actor, seedThunk } of this[ACTORS]) {
+      if (seedThunk) actor.seed(seedThunk())
+      actor.start()
+    }
+    this.setup()
+  }
+
+  disconnectedCallback(): void {
+    for (const dispose of this[DISPOSERS]) dispose()
+    this[DISPOSERS] = []
+    for (const { actor } of this[ACTORS]) actor.stop()
+  }
+}
+
+/**
+ * Register a client-island class against its custom-element tag. Brackets
+ * construction so `use()` calls (which run as field initializers during
+ * construction) are collected onto the instance for lifecycle management.
+ *
+ * The compiler emits `defineElement(QuantityStepper, 'quantity-stepper')`.
+ */
+export function defineElement(UserClass: typeof StatorElement, tag: string): void {
+  const decl = (UserClass as unknown as { attrs?: Record<string, (raw: string) => unknown> }).attrs
+  const observed = decl ? Object.keys(decl).map(camelToKebab) : []
+
+  const Wrapped = class extends UserClass {
+    constructor() {
+      const bucket = pushCollector()
+      try {
+        super()
+      } finally {
+        popCollector()
+      }
+      this[ACTORS] = bucket
+    }
+
+    /** Declared attrs are observed; a change invokes the author's
+     *  `${key}Changed(next)` method (coerced per the attrs declaration).
+     *  This is how live server state flows INTO an island: bind an attr on
+     *  the island's tag to a read(), implement `${key}Changed`. */
+    static get observedAttributes(): string[] {
+      return observed
+    }
+
+    attributeChangedCallback(name: string, oldRaw: string | null, newRaw: string | null): void {
+      if (oldRaw === newRaw || !this.isConnected) return
+      const key = kebabToCamel(name)
+      const handler = (this as unknown as Record<string, unknown>)[`${key}Changed`]
+      if (typeof handler !== 'function') return
+      const coerce = decl?.[key]
+      const value =
+        coerce === (Boolean as unknown)
+          ? newRaw !== null
+          : newRaw === null
+            ? undefined
+            : coerce
+              ? coerce(newRaw)
+              : newRaw
+      ;(handler as (v: unknown) => void).call(this, value)
+    }
+  }
+  if (!customElements.get(tag)) customElements.define(tag, Wrapped)
+}

package/src/client/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Client authoring API for `.stator` `<script>` islands — `@statorjs/stator/client`.
+ * Browser-safe (no server imports). The compiler auto-injects what a generated
+ * island needs; these are also the symbols an author references directly.
+ */
+
+export { bind, effect } from './bind.ts'
+export { dispatch } from './dispatch.ts'
+export { defineElement, StatorElement } from './element.ts'
+export type { MachineConfig } from './machine.ts'
+export { machine } from './machine.ts'
+export type { ClientInstance } from './use.ts'
+export { use } from './use.ts'

package/src/client/inspector.ts

@@ -0,0 +1,237 @@
+/**
+ * Stator dev inspector — a framework-owned, dev-only observability toolbar.
+ *
+ * Auto-injected by `createDevApp` (never in production). It subscribes to the
+ * public `stator:*` CustomEvent contract the client runtime dispatches on
+ * `window` and renders a bottom drawer with one row per outgoing event (↑) and
+ * per incoming patch batch (↓), plus a brief flash on each patched element.
+ *
+ * It depends on nothing but that event contract — the same surface any external
+ * devtool would use. Self-contained: it injects its own styles.
+ */
+
+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; } }
+`
+
+const STORAGE_KEY = 'stator:inspector:open'
+const MAX_ENTRIES = 40
+const FLASH_MS = 1200
+
+const w = window as unknown as { __statorInspectorMounted?: boolean }
+
+function escapeHtml(s: unknown): string {
+  if (s == null) return ''
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+function fmtTime(t: number): string {
+  const d = new Date(t)
+  const p = (n: number, w = 2) => String(n).padStart(w, '0')
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`
+}
+
+function summarizePatches(patches: Array<{ op: string }>): string {
+  const counts: Record<string, number> = {}
+  for (const p of patches) counts[p.op] = (counts[p.op] || 0) + 1
+  return Object.keys(counts)
+    .sort()
+    .map((op) => `${op}·${counts[op]}`)
+    .join('  ')
+}
+
+function formatEventParams(event: Record<string, unknown>): string {
+  const { type: _type, ...rest } = event
+  const keys = Object.keys(rest)
+  if (keys.length === 0) return ''
+  return keys.map((k) => `${k}=${JSON.stringify(rest[k])}`).join(' ')
+}
+
+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 = `
+    <button class="stator-inspector-toggle" type="button" aria-label="Show stator inspector">
+      <span aria-hidden="true">{ }</span> Inspect
+    </button>
+    <section class="stator-inspector-drawer" aria-label="Stator inspector" hidden>
+      <header class="stator-inspector-header">
+        <span class="stator-inspector-title"><span class="stator-inspector-dot" aria-hidden="true"></span> Stator inspector</span>
+        <span class="stator-inspector-legend">
+          <span class="stator-inspector-key stator-inspector-key--up">↑ event</span>
+          <span class="stator-inspector-key stator-inspector-key--down">↓ patches</span>
+        </span>
+        <button class="stator-inspector-clear" type="button" title="Clear log">clear</button>
+        <button class="stator-inspector-close" type="button" aria-label="Close inspector">×</button>
+      </header>
+      <div class="stator-inspector-body">
+        <p class="stator-inspector-empty">Interact with the page to see events and patches.</p>
+      </div>
+    </section>`
+  document.body.appendChild(root)
+
+  const q = (sel: string) => root.querySelector(sel) as HTMLElement
+  const drawer = q('.stator-inspector-drawer')
+  const body = q('.stator-inspector-body')
+  const toggle = q('.stator-inspector-toggle')
+
+  const setOpen = (open: boolean) => {
+    try {
+      localStorage.setItem(STORAGE_KEY, open ? 'true' : 'false')
+    } catch {}
+    ;(drawer as HTMLElement).hidden = !open
+    ;(toggle as HTMLElement).hidden = open
+  }
+  let initiallyOpen = true
+  try {
+    initiallyOpen = localStorage.getItem(STORAGE_KEY) !== 'false'
+  } catch {}
+  setOpen(initiallyOpen)
+
+  toggle.addEventListener('click', () => setOpen(true))
+  q('.stator-inspector-close').addEventListener('click', () => setOpen(false))
+  q('.stator-inspector-clear').addEventListener('click', () => {
+    body.innerHTML = '<p class="stator-inspector-empty">Log cleared.</p>'
+  })
+
+  const addEntry = (kind: 'up' | 'down', html: string, detail: unknown) => {
+    const empty = body.querySelector('.stator-inspector-empty')
+    if (empty) empty.remove()
+    const row = document.createElement('div')
+    row.className = `stator-inspector-row stator-inspector-row--${kind}`
+    row.innerHTML = html
+    const expand = document.createElement('pre')
+    expand.className = 'stator-inspector-detail'
+    expand.hidden = true
+    expand.textContent = JSON.stringify(detail, null, 2)
+    row.appendChild(expand)
+    ;(row.querySelector('.stator-inspector-summary') as HTMLElement).addEventListener(
+      'click',
+      () => {
+        expand.hidden = !expand.hidden
+      },
+    )
+    body.insertBefore(row, body.firstChild)
+    while (body.children.length > MAX_ENTRIES) body.removeChild(body.lastChild as Node)
+  }
+
+  window.addEventListener('stator:event-sent', (e: Event) => {
+    const { machine, event, timestamp } = (e as CustomEvent).detail
+    addEntry(
+      'up',
+      `<div class="stator-inspector-summary">
+        <span class="stator-inspector-time">${fmtTime(timestamp)}</span>
+        <span class="stator-inspector-arrow">↑</span>
+        <span class="stator-inspector-machine">${escapeHtml(machine)}</span>
+        <span class="stator-inspector-event-type">${escapeHtml(event.type)}</span>
+        <span class="stator-inspector-params">${escapeHtml(formatEventParams(event))}</span>
+      </div>`,
+      (e as CustomEvent).detail,
+    )
+  })
+
+  window.addEventListener('stator:patches-received', (e: Event) => {
+    const { patches, source, durationMs, timestamp } = (e as CustomEvent).detail
+    const timing = durationMs != null ? `${durationMs}ms` : ''
+    const sourceLabel = source === 'sse' ? '(sse push)' : '(post)'
+    addEntry(
+      'down',
+      `<div class="stator-inspector-summary">
+        <span class="stator-inspector-time">${fmtTime(timestamp)}</span>
+        <span class="stator-inspector-arrow">↓</span>
+        <span class="stator-inspector-machine">${patches.length} patch${patches.length === 1 ? '' : 'es'}</span>
+        <span class="stator-inspector-event-type">${escapeHtml(summarizePatches(patches))}</span>
+        <span class="stator-inspector-params">${sourceLabel} ${timing}</span>
+      </div>`,
+      (e as CustomEvent).detail,
+    )
+  })
+
+  window.addEventListener('stator:patch-applied', (e: Event) => {
+    const { patch, element } = (e as CustomEvent).detail
+    if (!element) return
+    const opClass = `stator-flash--${patch.op}`
+    ;(element as HTMLElement).classList.add('stator-flash', opClass)
+    window.setTimeout(() => {
+      ;(element as HTMLElement).classList.remove('stator-flash', opClass)
+    }, FLASH_MS)
+  })
+}
+
+if (!w.__statorInspectorMounted) {
+  w.__statorInspectorMounted = true
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', mount)
+  } else {
+    mount()
+  }
+}

package/src/client/machine.ts

@@ -0,0 +1,39 @@
+import { defineMachine, type EventObject, 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.
+ *
+ *   machine({ count: 1, on: { INC: s => s.count++ }, select: { atMax: s => s.count >= 99 } })
+ *
+ * Client machines run only via `createActor` (never the Store), so the name is
+ * just a label and need not be unique.
+ */
+export interface MachineConfig {
+  /** 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
+  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
+  return defineMachine({
+    name: name ?? 'ClientMachine',
+    lifecycle: 'session',
+    events: {} as EventObject,
+    context: context as object,
+    initial: 'active',
+    states: { active: { on } },
+    selectors: select,
+  }) as MachineDef
+}