@statorjs/stator 2.10.0-next.1 → 2.11.0-next.0

package/src/server/routing.ts

@@ -198,6 +198,7 @@ export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
       __isStatorQueryRoute: true,
       reads: config.reads ? [...config.reads] : [],
       handler: config.handler,
+      revision: config.revision,
     }
   }
   return {
@@ -248,6 +249,7 @@ export interface QueryRouteDefinition {
     request: RouteRequest,
     helpers: QueryRouteHelpers,
   ) => Promise<QueryRouteResult> | QueryRouteResult
+  revision?: () => string | number | Promise<string | number>
 }
 
 export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineDef> = readonly []> {
@@ -259,6 +261,12 @@ export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineD
     request: RouteRequest,
     helpers: QueryRouteHelpers<TReads>,
   ) => Promise<QueryRouteResult> | QueryRouteResult
+  /** The revision ledger: a CHEAP fingerprint of everything the body depends
+   *  on (e.g. `() => String(maxUpdatedAt())` — one indexed SELECT). When
+   *  present, the ETag derives from it and a matching `If-None-Match`
+   *  answers 304 WITHOUT invoking the handler — a polling crawler costs the
+   *  fingerprint, not the render. Must change whenever the body could. */
+  revision?: () => string | number | Promise<string | number>
 }
 
 export function isStatorQueryRoute(v: unknown): v is QueryRouteDefinition {

package/src/server/session.ts

@@ -23,9 +23,18 @@ export interface SessionState {
   claimsDirty: boolean
 }
 
+/** Layer-3 provability tracking: did this request USE the session plane
+ *  (establish/dispatch/session-read) or READ claims? Either makes the
+ *  response unprovable as anonymous-identical, so no derived Cache-Control. */
+export interface SessionUse {
+  used: boolean
+  claimsRead: boolean
+}
+
 declare module 'hono' {
   interface ContextVariableMap {
     statorSession: SessionState
+    statorSessionUse: SessionUse
   }
 }
 
@@ -34,6 +43,40 @@ export function getSessionState(c: Context): SessionState | undefined {
   return c.get('statorSession')
 }
 
+/** The request's session-use flags (created on first access). */
+export function sessionUse(c: Context): SessionUse {
+  let use = c.get('statorSessionUse')
+  if (!use) {
+    use = { used: false, claimsRead: false }
+    c.set('statorSessionUse', use)
+  }
+  return use
+}
+
+/** The session id this request WOULD have — established state or the arriving
+ *  cookie — without creating anything. Null for a first-contact visitor. */
+export function peekSessionId(c: Context): string | null {
+  return getSessionState(c)?.sid ?? getCookie(c, SESSION_COOKIE) ?? null
+}
+
+/** Resume an EXISTING session from the arriving cookie (populate the shared
+ *  state, no cookie write) — or return null for first contact. Resuming is
+ *  not establishment: laziness governs CREATION only. */
+export function resumeSession(c: Context): SessionState | null {
+  const established = getSessionState(c)
+  if (established) return established
+  const cookieSid = getCookie(c, SESSION_COOKIE)
+  if (cookieSid === undefined) return null
+  const state: SessionState = {
+    sid: cookieSid,
+    isNew: false,
+    claims: undefined,
+    claimsDirty: false,
+  }
+  c.set('statorSession', state)
+  return state
+}
+
 /** Secure cookie flag — set when running behind HTTPS. Enabled by
  *  NODE_ENV=production; can be overridden via STATOR_SECURE_COOKIE. */
 function shouldUseSecureCookie(): boolean {
@@ -65,22 +108,26 @@ export function setSessionCookie(c: Context, sessionId: string): void {
   })
 }
 
+/**
+ * ESTABLISH the session — the lazy-creation trigger (dispatches, session-
+ * machine reads, SSE connects, explicit session ops call this; anonymous
+ * page/data GETs never do). Idempotent per request: the first caller
+ * establishes, everyone after reads the same state. A first-contact visitor
+ * gets a fresh sid + Set-Cookie HERE and nowhere earlier — the whole
+ * cacheable-read-path layer 1.
+ */
 export function getOrCreateSessionId(c: Context): {
   sessionId: string
   isNew: boolean
 } {
-  // Idempotent per request: the first caller (middleware or handler) establishes
-  // the session; everyone after reads the same one. Closes the double-create bug.
-  const established = c.get('statorSession')
-  if (established) return { sessionId: established.sid, isNew: established.isNew }
-
-  const cookieSid = getCookie(c, SESSION_COOKIE)
-  const sessionId = cookieSid ?? randomUUID()
-  const isNew = cookieSid === undefined
-  if (isNew) setSessionCookie(c, sessionId)
+  sessionUse(c).used = true
+  const resumed = resumeSession(c)
+  if (resumed) return { sessionId: resumed.sid, isNew: resumed.isNew }
 
-  c.set('statorSession', { sid: sessionId, isNew, claims: undefined, claimsDirty: false })
-  return { sessionId, isNew }
+  const sessionId = randomUUID()
+  setSessionCookie(c, sessionId)
+  c.set('statorSession', { sid: sessionId, isNew: true, claims: undefined, claimsDirty: false })
+  return { sessionId, isNew: true }
 }
 
 /**

package/src/template/html-attributes.ts

@@ -94,6 +94,11 @@ export interface ElementSpecificAttributes {
     autofocus?: boolean
     accept?: string
     multiple?: boolean
+    /** Associates this element with a `<form>` elsewhere in the document by
+     *  id — the standard way to submit an element that can't live inside
+     *  the form's own DOM subtree (e.g. a per-row control alongside a
+     *  page-wide bulk-action form). `button` already carries this. */
+    form?: string
   }
   label: { for?: string }
   form: {
@@ -101,6 +106,11 @@ export interface ElementSpecificAttributes {
     method?: 'get' | 'post' | 'GET' | 'POST' | 'dialog'
     enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'
     novalidate?: boolean
+    /** Native inline event-handler attribute — a literal JS source string
+     *  (`"return confirm(...)"`), distinct from the `on:submit={...}`
+     *  Stator directive. Useful for a plain, no-hydration `confirm()`
+     *  guard that doesn't otherwise need an island. */
+    onsubmit?: string
   }
   select: {
     name?: string