@statorjs/stator 1.0.0

package/src/components/json-ld.ts

@@ -0,0 +1,85 @@
+import type { Graph, Thing, WithContext } from 'schema-dts'
+import { raw } from '../template/html.ts'
+import type { HtmlFragment } from '../template/types.ts'
+
+/**
+ * `<JsonLd>` — render a typed schema.org JSON-LD `<script>` block.
+ *
+ * The payload is typed against `schema-dts`, serialized once, and emitted as a
+ * raw `<script type="application/ld+json">` via `raw()`. There is no literal
+ * `<script>` in any template, so it sidesteps both text auto-escaping and the
+ * inline-`<script>`-is-a-client-component rule — a server data block is neither.
+ *
+ *   import { JsonLd } from '@statorjs/stator/components'
+ *   <JsonLd json={{ "@type": "Product", name: "Pocket Notebook" }} />
+ */
+export interface JsonLdProps {
+  /** A single schema.org entity, or an array (rendered as an `@graph`). */
+  json: Thing | Thing[]
+  /** Pretty-print indent, forwarded to {@link JSON.stringify}. */
+  space?: string | number
+}
+
+export function JsonLd(props: JsonLdProps): HtmlFragment {
+  return raw(`<script type="application/ld+json">${ldToString(props.json, props.space)}</script>`)
+}
+
+type JsonValueScalar = string | boolean | number
+type JsonValue = JsonValueScalar | Array<JsonValue> | { [key: string]: JsonValue }
+type JsonReplacer = (_: string, value: JsonValue) => JsonValue | undefined
+
+const ESCAPE_ENTITIES = Object.freeze({
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&apos;',
+})
+const ESCAPE_REGEX = new RegExp(`[${Object.keys(ESCAPE_ENTITIES).join('')}]`, 'g')
+const ESCAPE_REPLACER = (t: string): string => ESCAPE_ENTITIES[t as keyof typeof ESCAPE_ENTITIES]
+
+/**
+ * A `JSON.stringify` replacer that strips JSON-LD of HTML sequences illegal in a
+ * `<script>` element, per
+ * https://www.w3.org/TR/json-ld11/#restrictions-for-contents-of-json-ld-script-elements
+ * Escaping `<`/`>` is what guarantees no `</script>` breakout in the raw output.
+ */
+const safeJsonLdReplacer: JsonReplacer = (_: string, value: JsonValue): JsonValue | undefined => {
+  switch (typeof value) {
+    case 'object':
+      // Omit null values.
+      if (value === null) return undefined
+      return value // JSON.stringify recurses, re-applying this replacer.
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+      return value // Not risky.
+    case 'string':
+      return value.replace(ESCAPE_REGEX, ESCAPE_REPLACER)
+    default: {
+      // No other types are expected; JSON.stringify drops an `undefined` return.
+      isNever(value)
+      return undefined
+    }
+  }
+}
+
+function isNever(_: never): void {}
+
+function withContext<T extends Thing>(thing: T): WithContext<T> {
+  return {
+    '@context': 'https://schema.org',
+    ...(thing as object),
+  } as WithContext<T>
+}
+
+function asGraph(things: Thing[]): Graph {
+  return { '@context': 'https://schema.org', '@graph': things }
+}
+
+/** Serialize one entity (with `@context`) or many (as an `@graph`) to a
+ *  JSON-LD string, safe to embed verbatim in a `<script>` element. */
+export function ldToString(json: Thing | Thing[], space?: number | string): string {
+  const ld = Array.isArray(json) ? asGraph(json) : withContext(json)
+  return JSON.stringify(ld, safeJsonLdReplacer, space)
+}

package/src/engine/actor.ts

@@ -0,0 +1,248 @@
+import type {
+  ActionHelpers,
+  EffectInvocation,
+  EventObject,
+  MachineDef,
+  Snapshot,
+  TransitionConfig,
+} from './types.ts'
+
+/** The actor surface the rest of the framework consumes. Designed to the
+ *  framework's actual needs — not XState's actor protocol. */
+export interface Actor<C, E extends EventObject> {
+  start(): Actor<C, E>
+  stop(): void
+  send(event: E): void
+  /** Merge into the initial context before `start()`. Used for the deferred
+   *  client seed (attribute values aren't available at actor creation — only at
+   *  the element's connect). No-op after start. */
+  seed(partial: Partial<C>): void
+  getSnapshot(): Snapshot<C>
+  /** Monotonic count of HANDLED events (a matching transition fired or an
+   *  `@set` applied). Guard-dropped and unhandled events don't count — this
+   *  is how the server distinguishes "committed" from "silently dropped". */
+  getCommitCount(): number
+  subscribe(listener: (snapshot: Snapshot<C>) => void): { unsubscribe(): void }
+  /** Listen for a declared emit. Returns a remover. Used by cross-machine
+   *  subscription wiring. */
+  on(
+    emitName: string,
+    listener: (event: { type: string; [k: string]: unknown }) => void,
+  ): () => void
+  /** Compact snapshot for the Store / client hydration seed. */
+  getPersistedSnapshot(): Snapshot<C>
+}
+
+/** The "top type" for an actor — same variance argument as `AnyMachineDef`:
+ *  `C` appears in both co- and contravariant positions, so only `any` admits
+ *  every concrete actor. */
+// biome-ignore lint/suspicious/noExplicitAny: existential slots (see doc comment)
+export type AnyActor = Actor<any, any>
+
+/** The shape delivered to `Actor.on` emit listeners. */
+export type EmittedEvent = { type: string; [k: string]: unknown }
+
+export interface CreateActorOptions<C> {
+  /** Hydrate from a persisted snapshot (Store) or a client seed. */
+  snapshot?: Snapshot<C>
+  /** Host-provided resolver for action/guard `reads` helpers. The server wires
+   *  this to the active dispatch context; the client omits it (a reads-free
+   *  machine never dereferences it). This injection is what keeps the engine
+   *  isomorphic — it imports no server-only module. */
+  resolveHelpers?: () => ActionHelpers
+  /** Host-provided effect scheduler. When set, the actor hands each pending
+   *  effect to the host instead of running it (the server queues effects and
+   *  runs them after the session lock releases, dispatching completions
+   *  through the full event path). When omitted, the actor schedules the
+   *  effect locally on a microtask and sends its completion event to itself —
+   *  the client-plane (and unit-test) behavior. */
+  onEffect?: (invocation: EffectInvocation) => void
+}
+
+/** Unique per-invocation effect id — usable as an idempotency key, so it must
+ *  be unique across process restarts (randomUUID, not a counter). */
+function newEffectId(): string {
+  const uuid = globalThis.crypto?.randomUUID?.()
+  return uuid ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+/** Helpers that throw on any `reads` access — used when no resolver is wired
+ *  (e.g. a client actor, or a direct unit-test send). A machine that ignores
+ *  reads keeps working; one that dereferences them gets a clear error. */
+function throwingHelpers(machineName: string): ActionHelpers {
+  return {
+    reads: new Proxy({} as Record<string, unknown>, {
+      get(_t, prop) {
+        throw new Error(
+          `stator: "${machineName}" accessed reads.${String(prop)} with no reads resolver — ` +
+            `actions/guards that use reads must run through the server dispatch path.`,
+        )
+      },
+    }),
+  }
+}
+
+export function createActor<C extends object, E extends EventObject, S extends string>(
+  def: MachineDef<C, E, S>,
+  opts: CreateActorOptions<C> = {},
+): Actor<C, E> {
+  let value: string[] = opts.snapshot ? [...opts.snapshot.value] : [def.initial]
+  let context: C = opts.snapshot
+    ? (structuredClone(opts.snapshot.context) as C)
+    : (structuredClone(def.context) as C)
+
+  const subscribers = new Set<(s: Snapshot<C>) => void>()
+  const emitListeners = new Map<string, Set<(e: EmittedEvent) => void>>()
+  let started = false
+
+  const helpers = (): ActionHelpers => opts.resolveHelpers?.() ?? throwingHelpers(def.name)
+
+  let commits = 0
+
+  const snapshot = (): Snapshot<C> => ({ value: [...value], context })
+
+  const notify = (): void => {
+    const snap = snapshot()
+    for (const fn of subscribers) fn(snap)
+  }
+
+  const actor: Actor<C, E> = {
+    seed(partial: Partial<C>) {
+      if (!started) context = { ...context, ...partial }
+    },
+    start() {
+      if (!started) {
+        started = true
+        notify() // let subscribe-before-start consumers sync initial state
+      }
+      return actor
+    },
+
+    stop() {
+      started = false
+      subscribers.clear()
+      emitListeners.clear()
+    },
+
+    send(event: E) {
+      // Built-in `@set`: assign one context key. Powers two-way `bind:value`
+      // (DOM → state) without a per-field transition. Available in every state.
+      if ((event as { type: string }).type === '@set') {
+        const e = event as unknown as { key: string; value: unknown }
+        context = { ...context, [e.key]: e.value }
+        commits += 1
+        notify()
+        return
+      }
+      // Resolve the current leaf state (depth-1 today: value[0]).
+      const stateKey = value[value.length - 1]!
+      const node = def.states[stateKey]
+      // The `on` map narrows the event per key; internally we treat every
+      // transition uniformly against the full event union (the runtime event
+      // IS the narrowed type for this key, so the coercion is sound).
+      type RawTransition = ((ctx: C, ev: E, h: ActionHelpers) => void) | TransitionConfig<C, E, S>
+      const entry = node?.on?.[event.type as E['type']] as
+        | RawTransition
+        | RawTransition[]
+        | undefined
+      if (!entry) return
+
+      const h = helpers()
+
+      // Resolve to the first candidate whose guard passes. A bare function or
+      // a config with no `when` always matches.
+      const candidates = Array.isArray(entry) ? entry : [entry]
+      let config: TransitionConfig<C, E, S> | undefined
+      for (const candidate of candidates) {
+        const c: TransitionConfig<C, E, S> =
+          typeof candidate === 'function' ? { do: candidate } : candidate
+        if (!c.when || c.when(context, event as never, h)) {
+          config = c
+          break
+        }
+      }
+      if (!config) return
+
+      commits += 1 // a transition matched and fired — the event was HANDLED
+
+      if (config.do) {
+        const draft = structuredClone(context) as C
+        config.do(draft, event as never, h)
+        context = draft
+      }
+
+      if (config.to) value = [config.to]
+
+      // Emits fire after the action commits, so payload selectors see
+      // post-mutation context.
+      if (config.emit) {
+        const names = Array.isArray(config.emit) ? config.emit : [config.emit]
+        for (const name of names) {
+          const decl = def.emits[name]
+          const payload = decl?.payload ? decl.payload(context, event as never) : {}
+          const emitted = { type: name, ...payload }
+          const listeners = emitListeners.get(name)
+          if (listeners) for (const fn of listeners) fn(emitted)
+        }
+      }
+
+      // Effects surface after commit with commit-time snapshots (same clone
+      // discipline as actions). The engine never awaits them — the host
+      // schedules (server), or the local default runs on a microtask (client,
+      // unit tests) and sends the completion back to this actor.
+      if (config.effect) {
+        const effect = config.effect
+        const effectId = newEffectId()
+        const ctxSnapshot = structuredClone(context)
+        const evSnapshot = structuredClone(event)
+        const invocation: EffectInvocation = {
+          machineName: def.name,
+          effectId,
+          run: () => Promise.resolve(effect(ctxSnapshot, evSnapshot as never, { 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: effect ${effectId} of "${def.name}" threw — effects must catch and ` +
+                  `return their failure event. Dropped.`,
+                err,
+              )
+            })
+        }
+      }
+
+      notify()
+    },
+
+    getSnapshot: snapshot,
+    getPersistedSnapshot: snapshot,
+    getCommitCount: () => commits,
+
+    subscribe(listener) {
+      subscribers.add(listener)
+      return {
+        unsubscribe() {
+          subscribers.delete(listener)
+        },
+      }
+    },
+
+    on(emitName, listener) {
+      const set = emitListeners.get(emitName) ?? new Set<(e: EmittedEvent) => void>()
+      emitListeners.set(emitName, set)
+      set.add(listener)
+      return () => {
+        set.delete(listener)
+      }
+    },
+  }
+
+  return actor
+}

package/src/engine/define-machine.ts

@@ -0,0 +1,113 @@
+import type {
+  AnyMachineDef,
+  Capabilities,
+  EmitDeclaration,
+  EmitsConfig,
+  EventObject,
+  Lifecycle,
+  MachineDef,
+  ReadsMap,
+  SelectorMap,
+  StateNode,
+  SubscribeEntry,
+} from './types.ts'
+
+export interface DefineMachineConfig<
+  C extends object,
+  E extends EventObject,
+  S extends string,
+  Name extends string,
+  TReads extends readonly AnyMachineDef[],
+  Sel extends SelectorMap<C, ReadsMap<TReads>>,
+> {
+  name: Name
+  lifecycle: Lifecycle
+  /** Machines this one reads. Inferred as a tuple so `helpers.reads` is typed
+   *  per read machine (keyed by name, selectors preserved). */
+  reads?: TReads
+  subscribes?: SubscribeEntry[]
+  /** Typed event surface. Pass `{} as MyEvents` — a phantom carrier the engine
+   *  reads only for its type. Actions/guards then narrow per transition. */
+  events?: E
+  emits?: EmitsConfig<C, E>
+  context: C
+  initial: NoInfer<S>
+  /** Transitions see `helpers.reads` typed as `ReadsMap<TReads>`. */
+  states: Record<S, StateNode<C, E, S, ReadsMap<TReads>>>
+  selectors?: Sel
+  /** APP machines only: persist this machine's snapshot through the AppStore
+   *  so its state survives restarts. Opt-in — caches and other
+   *  reset-on-restart machines should leave it off. Session machines always
+   *  persist through the session Store; setting this on one is an error. */
+  persist?: boolean
+}
+
+function normalizeEmits<C, E extends EventObject>(
+  emits: EmitsConfig<C, E> | undefined,
+): Record<string, EmitDeclaration<C, E>> {
+  if (!emits) return {}
+  const out: Record<string, EmitDeclaration<C, E>> = {}
+  if (Array.isArray(emits)) {
+    for (const name of emits) out[name] = {}
+    return out
+  }
+  for (const [name, decl] of Object.entries(
+    emits as Record<string, EmitDeclaration<C, E> | null>,
+  )) {
+    out[name] = decl ?? {}
+  }
+  return out
+}
+
+/**
+ * Derive the machine's capability classification.
+ *
+ * Initial heuristic (refined in the full capability pass): a machine is
+ * server-pinned if it reads another machine — cross-machine reads can't be
+ * resolved in the browser. A pure context/states/selectors machine with no
+ * reads is portable (the client-model spike's reads-free counter ran
+ * client-side for exactly this reason). Secrets and cross-session emit are
+ * future inputs to this function; they're noted as TODO, not silently ignored.
+ */
+function computeCapabilities(reads: readonly AnyMachineDef[]): Capabilities {
+  const reasons: string[] = []
+  for (const r of reads) {
+    reasons.push(`reads machine "${r.name}" (cross-machine reads resolve server-side only)`)
+  }
+  // TODO(capability-pass): also flag secret access and cross-session emit.
+  return { serverPinned: reasons.length > 0, reasons }
+}
+
+export function defineMachine<
+  C extends object,
+  E extends EventObject = EventObject,
+  S extends string = string,
+  Name extends string = string,
+  const TReads extends readonly AnyMachineDef[] = readonly [],
+  Sel extends SelectorMap<C, ReadsMap<TReads>> = SelectorMap<C, ReadsMap<TReads>>,
+>(config: DefineMachineConfig<C, E, S, Name, TReads, Sel>): MachineDef<C, E, S, Sel, Name> {
+  const reads = (config.reads ?? []) as unknown as AnyMachineDef[]
+  if (config.persist && config.lifecycle === 'session') {
+    throw new Error(
+      `stator: machine "${config.name}" sets persist: true but is session-lifecycle — ` +
+        `session machines always persist through the session Store. ` +
+        `\`persist\` opts an APP machine into AppStore persistence.`,
+    )
+  }
+  return {
+    __isStatorMachine: true,
+    name: config.name,
+    lifecycle: config.lifecycle as Lifecycle,
+    persist: config.persist ?? false,
+    reads,
+    subscribes: config.subscribes ?? [],
+    emits: normalizeEmits<C, E>(config.emits),
+    selectors: (config.selectors ?? {}) as Sel,
+    capabilities: computeCapabilities(reads),
+    initial: config.initial,
+    states: config.states as Record<string, StateNode<C, E, S>>,
+    context: config.context,
+    __context: undefined as unknown as C,
+    __event: undefined as unknown as E,
+  }
+}

package/src/engine/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Stator's custom isomorphic state-machine engine. Public surface.
+ *
+ * Replaces the XState-backed POC `defineMachine`. Lean feature set, fresh API
+ * (inline transitions, typed events), runs identically server- and client-side.
+ * See spec: custom-isomorphic-state-machine-engine.
+ */
+
+export type { Actor, AnyActor, CreateActorOptions } from './actor.ts'
+export { createActor } from './actor.ts'
+export type { DefineMachineConfig } from './define-machine.ts'
+export { defineMachine } from './define-machine.ts'
+export type {
+  Action,
+  ActionHelpers,
+  AnyMachineDef,
+  Capabilities,
+  Effect,
+  EffectInvocation,
+  EffectMeta,
+  EmitDeclaration,
+  EmitsConfig,
+  EventObject,
+  EventOf,
+  Guard,
+  InstanceOf,
+  Lifecycle,
+  MachineDef,
+  ReadsMap,
+  SelectorMap,
+  Snapshot,
+  StateNode,
+  SubscribeEntry,
+  Transition,
+  TransitionConfig,
+} from './types.ts'
+export { isStatorMachine } from './types.ts'