@statorjs/stator 2.10.0-next.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.10.0-next.0",
+  "version": "2.10.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, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,10 @@
     "stator": "./src/cli/stator.js"
   },
   "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
     "./server": {
       "types": "./src/server/index.ts",
       "default": "./src/server/index.ts"
@@ -95,7 +99,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.10.0-next.0"
+    "@statorjs/stator": "2.10.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/copy-set.ts

@@ -3,6 +3,7 @@ import { readdir, readFile, stat } from 'node:fs/promises'
 import { builtinModules } from 'node:module'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { build } from 'esbuild'
+import ts from 'typescript'
 import { compile, regionResolverFor } from '../compiler/index.ts'
 
 /**
@@ -55,18 +56,10 @@ const NEVER_SOURCE = new Set(['node_modules', 'dist', 'tests', 'test', '__tests_
 
 const CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx|stator)$/
 const BUILTIN = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)])
-/** `new URL('./x', import.meta.url)` — invisible to the bundler, so read the
- *  literal directly. Same limit as the client seam: relative string literals.
- *  (Injecting an import instead does NOT work: esbuild's TS loader elides an
- *  import whose binding is unused, so the injected one disappears.) */
-const URL_ASSET_RE = /new\s+URL\(\s*(['"])(\.{1,2}\/[^'"\n]+)\1\s*,\s*import\.meta\.url\s*\)/g
 /** A `node_modules` path segment, either separator. Anything under one is a
  *  dependency, never app source — and a real app's `node_modules` sits INSIDE
  *  its root, so root containment alone cannot tell them apart. */
 const NODE_MODULES = /[\\/]node_modules[\\/]/
-/** `import(` not followed by a string or template literal. */
-const OPAQUE_IMPORT_RE = /(?<![.\w$])import\s*\(\s*([^'"`)\s])/g
-
 const norm = (p: string): string => p.replace(/\\/g, '/')
 
 export interface UntracedImport {
@@ -186,19 +179,67 @@ export async function resolveCopySet(opts: CopySetOptions): Promise<CopySet> {
   const unresolved = new Set<string>()
   const untraced: UntracedImport[] = []
 
-  /** Record the non-import dependencies a source text carries. */
+  /**
+   * The two dependencies a module carries that the bundler's own graph misses,
+   * read from the SYNTAX rather than the text.
+   *
+   * Both used to be regex scans over raw source, which cannot tell code from
+   * prose: a comment explaining why the app avoids `import(name)`, or a string
+   * documenting the pattern, was picked up as a real untraceable import and
+   * failed the build. Found by dogfooding, and the reason this parses. Comments
+   * and string contents are simply not part of the tree.
+   */
   const scan = (text: string, file: string): string => {
-    for (const m of text.matchAll(URL_ASSET_RE)) assets.add(resolve(dirname(file), m[2]!))
-    for (const m of text.matchAll(OPAQUE_IMPORT_RE)) {
-      untraced.push({
-        file: norm(relative(realRoot, file)),
-        line: text.slice(0, m.index).split('\n').length,
-        source: `${text
-          .slice(m.index, m.index + 60)
-          .split('\n')[0]!
-          .trim()}…`,
-      })
+    const sourceFile = ts.createSourceFile(
+      file,
+      text,
+      ts.ScriptTarget.Latest,
+      false,
+      /\.(tsx|jsx)$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    )
+
+    /** `import.meta.url`. */
+    const isImportMetaUrl = (node: ts.Node): boolean =>
+      ts.isPropertyAccessExpression(node) &&
+      node.name.text === 'url' &&
+      ts.isMetaProperty(node.expression) &&
+      node.expression.keywordToken === ts.SyntaxKind.ImportKeyword
+
+    /** A specifier the bundler can follow: a string literal, or a template —
+     *  esbuild glob-expands one with a fixed prefix, pulling in every match. */
+    const analysable = (node: ts.Node): boolean =>
+      ts.isStringLiteralLike(node) || ts.isTemplateExpression(node)
+
+    const visit = (node: ts.Node): void => {
+      // `new URL('./x', import.meta.url)` — an asset reference no import graph
+      // sees. String-literal specifiers only, the same limit as the client seam.
+      if (ts.isNewExpression(node) && ts.isIdentifier(node.expression)) {
+        if (node.expression.text === 'URL') {
+          const [spec, meta] = node.arguments ?? []
+          if (spec && ts.isStringLiteralLike(spec) && spec.text.startsWith('.')) {
+            if (meta && isImportMetaUrl(meta)) assets.add(resolve(dirname(file), spec.text))
+          }
+        }
+      }
+      // `import(expr)` the bundler cannot follow. It says nothing about these,
+      // so this is the only place they are caught.
+      if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+        const arg = node.arguments[0]
+        if (!arg || !analysable(arg)) {
+          const start = node.getStart(sourceFile)
+          untraced.push({
+            file: norm(relative(realRoot, file)),
+            line: sourceFile.getLineAndCharacterOfPosition(start).line + 1,
+            source: `${text
+              .slice(start, start + 60)
+              .split('\n')[0]!
+              .trim()}…`,
+          })
+        }
+      }
+      ts.forEachChild(node, visit)
     }
+    ts.forEachChild(sourceFile, visit)
     return text
   }
 

package/src/cli/commands/dev.ts

@@ -23,6 +23,8 @@ export async function run(ctx: CliContext): Promise<void> {
     trustedOrigins: config.trustedOrigins,
     origin: config.origin,
     cors: config.cors,
+    secret: config.secret,
+    logging: config.logging,
   })
   await app.listen(resolvePort(ctx.portFlag, config.port))
 }

package/src/cli/commands/start.ts

@@ -95,6 +95,8 @@ export async function run(ctx: CliContext): Promise<void> {
     host: config.host,
     secret: config.secret,
     cors: config.cors,
+    logging: config.logging,
+    caching: config.caching,
     headExtras,
     buildId,
     machineHashes: machines,

package/src/compiler/lower.ts

@@ -277,6 +277,47 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
   }
   checkNoReadInDefer(fragment, false)
 
+  // Build-time gate for RCDATA elements: inside <textarea> and <title> the
+  // parser treats children as RAW TEXT — a live-slot <span> (text-position
+  // read()) or a region comment marker (each/when/match/defer) is rendered as
+  // literal markup instead of becoming an element. Found in the wild: a
+  // textarea pre-filled via read() displayed `<span data-slot="…"></span>` to
+  // the user. Attributes on the element itself stay legal (attribute patches
+  // need no wrapper) — the gate covers children only.
+  const RCDATA_BINDINGS = new Set(['read', 'each', 'when', 'match', 'defer'])
+  const checkNoBindingInRcdata = (node: ts.Node, rcdataTag: string | null): void => {
+    if (
+      rcdataTag &&
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      RCDATA_BINDINGS.has(node.expression.text)
+    ) {
+      const callee = node.expression.text
+      throw new CompileError(
+        `stator: ${callee}() cannot appear inside <${rcdataTag}> — its content is raw text ` +
+          `(RCDATA), so the ${callee === 'read' ? 'live-slot wrapper' : 'region markers'} would ` +
+          `render as literal markup. Interpolate a static value instead (a selector property ` +
+          `like {machine.someSelector}, or a frontmatter constant); if the value must be live, ` +
+          `bind an attribute or use an island.`,
+        loc(node),
+      )
+    }
+    if (ts.isJsxElement(node)) {
+      const opening = node.openingElement
+      const tagName = ts.isIdentifier(opening.tagName) ? opening.tagName.text : null
+      const isRcdata = tagName === 'textarea' || tagName === 'title'
+      // Attributes keep the OUTER context; children enter the RCDATA scope.
+      checkNoBindingInRcdata(opening, rcdataTag)
+      for (const child of node.children) {
+        checkNoBindingInRcdata(child, isRcdata ? tagName : rcdataTag)
+      }
+      checkNoBindingInRcdata(node.closingElement, rcdataTag)
+      return
+    }
+    ts.forEachChild(node, (child) => checkNoBindingInRcdata(child, rcdataTag))
+  }
+  checkNoBindingInRcdata(fragment, null)
+
   // Build-time gate for item-read placement: a `read(<item>, …)` binding is
   // OWNED by its each() row — the row render supplies the item and collects the
   // binding, and the list's recompute is what re-diffs it. Three positions break

package/src/compiler/virtual-code.ts

@@ -102,7 +102,7 @@ const STATOR_AMBIENT = `declare const Stator: {
   reads<const T extends readonly __SMachineDef[]>(defs: T): { -readonly [K in keyof T]: __SInstanceOf<T[K]> };
   forwarded(name: \`on:\${string}\`): (() => unknown) | undefined;
   request: any;
-  response: { status: number; headers: Record<string, string>; cookies: any };
+  response: { status: number; headers: Headers; cookies: any };
 };
 declare global {
   namespace JSX {

package/src/config.ts

@@ -97,6 +97,22 @@ export interface StatorConfig {
    *  Opt in per route/app with the `cors()` middleware; `origins` defaults to
    *  `trustedOrigins`. */
   cors?: { origins?: string[]; credentials?: boolean }
+  /** Derived Cache-Control (the cacheable read path, layer 3): on GET
+   *  responses the framework can PROVE anonymous-identical — every declared
+   *  read app-lifecycle, no session use or claims read while handling — it
+   *  emits `Cache-Control: public, s-maxage, stale-while-revalidate` so a
+   *  CDN can absorb anonymous traffic. Hand-set headers always win; pages
+   *  that read session machines are never marked. On by default under
+   *  `stator start` (60s / 300s); set to `false` to disable; dev never
+   *  emits (editing must always re-render). */
+  caching?:
+    | {
+        /** Shared-cache lifetime in seconds. Default: 60. */
+        sMaxAge?: number
+        /** Serve-stale-while-refreshing window in seconds. Default: 300. */
+        staleWhileRevalidate?: number
+      }
+    | false
   /** Logging policy. */
   logging?: {
     /** Minimum level to emit. Default: `warn` in production, `info` in dev.

package/src/index.ts

@@ -0,0 +1,7 @@
+// Root export = the config-authoring surface only. `stator.config.ts` is the
+// first file anyone writes against the bare package name, and it must never
+// drag server-only dependencies (sharp, ioredis) into a config load — anything
+// beyond config keeps its own subpath.
+
+export type { LogLevel, StatorConfig } from './config.ts'
+export { defineConfig } from './config.ts'

package/src/server/api-route.ts

@@ -15,7 +15,7 @@ import type {
   Directive,
   RouteRequest,
 } from './routing.ts'
-import { getOrCreateSessionId, getSessionState, rotateSessionNow } from './session.ts'
+import { getOrCreateSessionId, getSessionState, rotateSessionNow, sessionUse } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -76,7 +76,10 @@ export async function runApiRoute(
         clearSession: () => {
           rotation = { clear: true }
         },
-        claims: <T = unknown>() => getSessionState(c)?.claims as T | undefined,
+        claims: <T = unknown>() => {
+          sessionUse(c).claimsRead = true
+          return getSessionState(c)?.claims as T | undefined
+        },
         setClaims: (claims) => {
           const s = getSessionState(c)
           if (s) {

package/src/server/config-compat.ts

@@ -34,6 +34,7 @@ interface NestedReads {
   host?: string
   secret?: string
   cors?: { origins?: readonly string[]; credentials?: boolean }
+  caching?: { sMaxAge?: number; staleWhileRevalidate?: number } | false
 }
 
 /** The flat internal values `createApp`/`createDevApp` actually consume. */
@@ -51,6 +52,8 @@ export interface ResolvedAppConfig {
   /** Signed-cookie signing key. `config.secret` ?? `STATOR_SECRET`. */
   secret?: string
   cors?: { origins: readonly string[]; credentials: boolean }
+  /** Derived Cache-Control knobs; `false` disables emission entirely. */
+  caching?: { sMaxAge?: number; staleWhileRevalidate?: number } | false
 }
 
 /**
@@ -93,5 +96,6 @@ export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): Re
           credentials: config.cors.credentials ?? false,
         }
       : undefined,
+    caching: config.caching,
   }
 }

package/src/server/context.ts

@@ -1,6 +1,6 @@
 import type { Context } from 'hono'
 import { type CookieJar, cookieJar } from './cookies.ts'
-import { getSessionState, rotateSessionNow } from './session.ts'
+import { getOrCreateSessionId, getSessionState, rotateSessionNow, sessionUse } from './session.ts'
 import type { Store } from './store.ts'
 
 /**
@@ -64,25 +64,34 @@ const DEFAULT: StatorConfigData = { trustedOrigins: [], sameSite: 'Lax' }
  */
 export function stator(c: Context): StatorContext {
   const cfg = c.get('stator') ?? DEFAULT
-  const session = getSessionState(c)
   return {
     origin: cfg.origin,
     trustedOrigins: cfg.trustedOrigins,
     sameSite: cfg.sameSite,
     cors: cfg.cors,
+    // Live reads (not a captured snapshot): the session may be established
+    // mid-request, after this context object was built.
     get sid() {
-      return session?.sid ?? ''
+      return getSessionState(c)?.sid ?? ''
     },
     claims<T = unknown>(): T | undefined {
-      return session?.claims as T | undefined
+      // A claims READ is a peek — it never establishes (an anonymous /admin
+      // probe redirects without minting state) — but it does make the
+      // response claims-dependent, so layer 3 marks it unprovable.
+      sessionUse(c).claimsRead = true
+      return getSessionState(c)?.claims as T | undefined
     },
     setClaims(claims: unknown): void {
+      // Writing claims is an explicit session op — an establishment trigger.
+      getOrCreateSessionId(c)
+      const session = getSessionState(c)
       if (session) {
         session.claims = claims
         session.claimsDirty = true
       }
     },
     clearClaims(): void {
+      const session = getSessionState(c)
       if (session) {
         session.claims = undefined
         session.claimsDirty = true

package/src/server/create-app.ts

@@ -89,6 +89,9 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
    *  keyed by file relative to `machinesDir`. Omitted ⇒ hashed live at boot;
    *  a discovered machine missing from a supplied map is a boot error. */
   machineHashes?: Readonly<Record<string, string>>
+  /** Derived Cache-Control (cacheable read path, layer 3). Defaults on with
+   *  modest values (60s / 300s); `false` disables emission. */
+  caching?: { sMaxAge?: number; staleWhileRevalidate?: number } | false
 }
 
 export interface StatorApp {
@@ -163,6 +166,16 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     buildId: config.buildId,
     cors: resolved.cors,
     middleware,
+    // Layer-3 derived Cache-Control: on by default with modest values; the
+    // whole block set to `false` disables. (createDevApp never passes it —
+    // dev pages must always re-render while editing.)
+    caching:
+      resolved.caching === false
+        ? undefined
+        : {
+            sMaxAge: resolved.caching?.sMaxAge ?? 60,
+            staleWhileRevalidate: resolved.caching?.staleWhileRevalidate ?? 300,
+          },
   })
 
   return {