tw-framework 1.0.7 → 1.0.8

package/dist/testing.cjs

@@ -78,11 +78,158 @@ function setSignal(name, value, opts) {
   }
   return getSignalHub().setSignal(name, value, session ? { session } : void 0);
 }
-var BATCH_MS, HISTORY_LIMIT, SignalHub, hub;
+function sseFrameWithId(payload) {
+  try {
+    const seq = JSON.parse(payload).seq;
+    if (typeof seq === "number") return "id: " + seq + "\ndata: " + payload + "\n\n";
+  } catch {
+  }
+  return "data: " + payload + "\n\n";
+}
+function createSignalStream(request, url, opts) {
+  const hub2 = getSignalHub();
+  if (opts && !hub2.__cfg) {
+    hub2.__cfg = true;
+    try {
+      hub2.configure({ maxClients: opts.maxClients, maxHistory: opts.maxHistory });
+    } catch {
+    }
+  }
+  if (url.searchParams.get("stats")) {
+    return new Response(JSON.stringify(hub2.getStats(), null, 2), {
+      status: 200,
+      headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }
+    });
+  }
+  if (!hub2.canAcceptClient()) {
+    return new Response("Too many signal-stream connections", {
+      status: 503,
+      headers: { "Content-Type": "text/plain", "Retry-After": "5" }
+    });
+  }
+  const names = (url.searchParams.get("s") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+  let since = Number(url.searchParams.get("since") ?? "0") || 0;
+  if (!since) {
+    const lei = Number(request.headers.get("last-event-id") ?? "0") || 0;
+    if (lei) since = lei;
+  }
+  const declared = /* @__PURE__ */ new Map();
+  for (const n of names) declared.set(n, "public");
+  let session;
+  try {
+    const header = request.headers.get("cookie") ?? "";
+    const m = /(?:^|;\s*)tw_session=([^;]+)/.exec(header);
+    if (m) session = decodeURIComponent(m[1].trim().replace(/^"|"$/g, ""));
+  } catch {
+  }
+  const enc = new TextEncoder();
+  const sse = (payload) => enc.encode(sseFrameWithId(payload));
+  let registered = null;
+  let keepAlive = null;
+  const stream = new ReadableStream({
+    start(controller) {
+      const client = hub2.register(declared, session);
+      registered = client;
+      const cleanup = () => {
+        if (keepAlive) clearInterval(keepAlive);
+        hub2.unregister(client.id);
+        try {
+          controller.close();
+        } catch {
+        }
+      };
+      client.send = (payload) => {
+        try {
+          controller.enqueue(sse(payload));
+        } catch {
+          cleanup();
+        }
+      };
+      client.close = cleanup;
+      for (const payload of hub2.connectPayloads(since, declared, session)) {
+        try {
+          controller.enqueue(sse(payload));
+        } catch {
+          break;
+        }
+      }
+      keepAlive = setInterval(() => {
+        try {
+          controller.enqueue(enc.encode(": keep-alive\n\n"));
+        } catch {
+          cleanup();
+        }
+      }, 25e3);
+    },
+    // v2: when the browser drops the connection (tab close, network
+    // loss) cancel fires -- remove THIS hub entry immediately instead
+    // of waiting for the next failed send.
+    cancel() {
+      if (keepAlive) clearInterval(keepAlive);
+      try {
+        registered?.close?.();
+      } catch {
+      }
+    }
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-store",
+      "X-Accel-Buffering": "no",
+      Connection: "keep-alive"
+    }
+  });
+}
+async function writeSignalFromClient(request, opts) {
+  if (!opts?.clientWrites) {
+    return new Response(JSON.stringify({ error: "client signal writes are disabled" }), {
+      status: 403,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  let body = null;
+  try {
+    body = await request.json();
+  } catch {
+  }
+  const name = body?.name;
+  if (typeof name !== "string" || !("value" in (body ?? {}))) {
+    return new Response(JSON.stringify({ error: "body must be { name, value }" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  const hub2 = getSignalHub();
+  const kind = (hub2.getStats().signals ?? {})[name];
+  if (kind && kind !== "public") {
+    return new Response(JSON.stringify({ error: "only public signals are client-writable" }), {
+      status: 403,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  const res = hub2.setSignal(name, body.value);
+  if (!res.queued) {
+    return new Response(JSON.stringify({ error: res.error ?? "rejected" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  return new Response(JSON.stringify({ ok: true, kind: res.kind }), {
+    status: 202,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+var BATCH_MS, HISTORY_LIMIT, MAX_CLIENTS, MAX_VALUE_BYTES, MAX_NAME_LEN, NAME_RE, SignalHub, hub;
 var init_signal_stream = __esm({
   "../../packages/server/tw/routing/signal-stream.ts"() {
     BATCH_MS = 100;
     HISTORY_LIMIT = 1e3;
+    MAX_CLIENTS = 500;
+    MAX_VALUE_BYTES = 64 * 1024;
+    MAX_NAME_LEN = 64;
+    NAME_RE = /^[A-Za-z0-9_$.-]{1,64}$/;
     SignalHub = class {
       clients = /* @__PURE__ */ new Map();
       nextClientId = 1;
@@ -93,12 +240,82 @@ var init_signal_stream = __esm({
       pending = /* @__PURE__ */ new Map();
       pendingSession;
       timer = null;
+      // v2 stats + caps
+      maxClients = MAX_CLIENTS;
+      createdAt = Date.now();
+      totalUpdates = 0;
+      batchesFlushed = 0;
+      rejectedCount = 0;
+      /** v2: configure caps (from tw.config.ts signalStream options). */
+      configure(opts) {
+        if (opts?.maxClients && opts.maxClients > 0) this.maxClients = opts.maxClients;
+        if (opts?.maxHistory && opts.maxHistory > 0) this.historyLimit = opts.maxHistory;
+      }
+      historyLimit = HISTORY_LIMIT;
+      /** v2: observability for /_tw/stream?stats=1 and window.__tw stats. */
+      getStats() {
+        const signals = {};
+        for (const [n, k] of this.kinds) signals[n] = k;
+        return {
+          clients: this.clients.size,
+          clientCap: this.maxClients,
+          seq: this.seq,
+          signals,
+          valueCount: this.values.size,
+          history: this.history.length,
+          historyCap: this.historyLimit,
+          pending: this.pending.size,
+          totalUpdates: this.totalUpdates,
+          batchesFlushed: this.batchesFlushed,
+          rejected: this.rejectedCount,
+          uptimeMs: Date.now() - this.createdAt
+        };
+      }
+      /** v2: graceful shutdown -- close every connected stream now. */
+      closeAll() {
+        for (const c of [...this.clients.values()]) {
+          try {
+            c.close();
+          } catch {
+          }
+        }
+        this.clients.clear();
+        if (this.timer != null) {
+          clearTimeout(this.timer);
+          this.timer = null;
+        }
+        this.pending.clear();
+      }
+      /** v2: connection cap check BEFORE registering a stream client. */
+      canAcceptClient() {
+        return this.clients.size < this.maxClients;
+      }
+      /** v2: validate a setSignal name/value without throwing. */
+      validateSignal(name, value) {
+        if (typeof name !== "string" || name.length === 0 || name.length > MAX_NAME_LEN) {
+          return "signal name must be 1-" + MAX_NAME_LEN + " chars";
+        }
+        if (!NAME_RE.test(name)) return "signal name has invalid characters";
+        if (value === void 0) return "signal value is undefined";
+        try {
+          const size = typeof value === "string" ? value.length : JSON.stringify(value)?.length ?? 0;
+          if (size > MAX_VALUE_BYTES) return "signal value exceeds " + MAX_VALUE_BYTES + " bytes";
+        } catch {
+          return "signal value is not serializable";
+        }
+        return null;
+      }
       /**
        * Server-side mutation (route handlers): queue an update, batch-flush.
        * With `session` (derived from the request's tw_session cookie) private
        * signals are delivered only to clients authenticated as that session.
        */
       setSignal(name, value, opts) {
+        const invalid = this.validateSignal(name, value);
+        if (invalid) {
+          this.rejectedCount++;
+          return { queued: false, kind: this.kinds.get(name), error: invalid };
+        }
         const kind = this.kinds.get(name) ?? "public";
         this.values.set(name, value);
         this.kinds.set(name, kind);
@@ -129,9 +346,27 @@ var init_signal_stream = __esm({
         this.clients.set(id, client);
         return client;
       }
+      /** v2: remove a stream client (its connection died / was cancelled).
+       *  The old handler overwrote client.close() with a closure that only
+       *  closed the controller -- the Map entry leaked forever, so every
+       *  disconnected browser still occupied a slot (and got flushed frames).
+       */
+      unregister(id) {
+        this.clients.delete(id);
+      }
       /** Build the replay/snapshot preamble for a connecting client. */
       connectPayloads(since, declared, session) {
         const out = [];
+        if (since <= 0 && this.values.size > 0) {
+          const snap = {};
+          for (const [name, value] of this.values) {
+            if (this.sessionMatches(session, { names: [name], session: this.valueSessions.get(name) }) && this.deliversTo(declared, [name])) snap[name] = value;
+          }
+          if (Object.keys(snap).length > 0) {
+            out.push(this.frame({ v: 1, seq: this.seq, snapshot: snap }));
+          }
+          return out;
+        }
         const hasCoverage = since <= this.seq && this.history.length > 0 && since >= this.history[0].seq - 1;
         if (hasCoverage) {
           for (const entry of this.history) {
@@ -174,7 +409,9 @@ var init_signal_stream = __esm({
         for (const [n] of updates) this.valueSessions.set(n, session);
         const payload = this.frame({ v: 1, seq: this.seq, updates });
         this.history.push({ seq: this.seq, payload, names, session });
-        if (this.history.length > HISTORY_LIMIT) this.history.shift();
+        this.totalUpdates += updates.length;
+        this.batchesFlushed++;
+        if (this.history.length > this.historyLimit) this.history.shift();
         for (const client of this.clients.values()) {
           if (this.sessionMatches(client.session, { names, session }) && this.deliversTo(client.declared, names)) client.send(payload);
         }
@@ -331,6 +568,8 @@ function matchPath(pattern, pathname) {
 }
 function ruleBlocked(rule, request, pathname) {
   const headers = request.headers;
+  const hasCondition = rule.userAgent || rule.path || rule.auth || rule.rateLimit || rule.origin || rule.methods && rule.methods.length > 0;
+  if (!hasCondition) return true;
   if (rule.userAgent) {
     const ua = (headers.get("user-agent") ?? "").toLowerCase();
     if (!ua) {
@@ -14584,6 +14823,13 @@ function consumeSignalDeclaration(cursor) {
 function consumeStateValue(cursor) {
   const t2 = cursor.peek();
   if (!t2) return "";
+  if (t2.value === "-" || t2.value === "+") {
+    const after = cursor.peek(1);
+    if (after && (after.type === "NUMBER" || after.type === "IDENT" || after.type === "KEYWORD")) {
+      cursor.advance();
+      return (t2.value === "-" ? "-" : "") + String(after.value);
+    }
+  }
   if (t2.type === "STRING" || t2.type === "NUMBER" || t2.type === "IDENT" || t2.type === "KEYWORD") {
     cursor.advance();
     if (t2.type === "STRING") return String(t2.value).replace(/\\([{}"])/g, "$1");
@@ -15601,6 +15847,20 @@ function parseTWSelector(cursor, errors, state, parseBody) {
         }
         cursor.consumeIf("RBRACE");
       } else {
+        for (; ; ) {
+          const t2 = cursor.peek();
+          if (!t2 || t2.type === "RBRACE" || t2.type === "EOF") break;
+          if ((t2.type === "IDENT" || t2.type === "KEYWORD") && ATTR_PAIR_NAMES.has(t2.value)) {
+            const after = cursor.peek(1);
+            if (after && (after.type === "STRING" || after.type === "NUMBER")) {
+              cursor.advance();
+              cursor.advance();
+              el.attrs.push(createAttribute(t2.value, after.value, t2.pos.line, t2.pos.col));
+              continue;
+            }
+          }
+          break;
+        }
         el.children = parseBody(["RBRACE"]);
         cursor.consumeIf("RBRACE");
       }
@@ -16219,10 +16479,13 @@ function parseWhileStatement(cursor, errors, parseBody) {
   const whileToken = cursor.advance();
   if (!whileToken) return null;
   cursor.skipWhitespace();
-  const condToken = cursor.peek();
   let condition = "";
-  if (condToken) {
-    condition = condToken.value;
+  while (!cursor.done) {
+    cursor.skipWhitespace();
+    const t2 = cursor.peek();
+    if (!t2 || t2.type === "EOF") break;
+    if (t2.type === "LBRACE" || t2.value === "{") break;
+    condition += (condition ? " " : "") + t2.value;
     cursor.advance();
   }
   const body = parseBlockBody2(cursor, parseBody);
@@ -16343,13 +16606,133 @@ function parseBlockBody2(cursor, parseBody) {
   }
   return parseBody(["KEYWORD", "RBRACE"]);
 }
-var CLASS_BOUNDARY_BOOLEAN_ATTRS;
+var ATTR_PAIR_NAMES, CLASS_BOUNDARY_BOOLEAN_ATTRS;
 var init_statements = __esm({
   "../../packages/compiler/tw/parser/statements/index.ts"() {
     init_nodes();
     init_recovery();
     init_directives();
     init_tw();
+    ATTR_PAIR_NAMES = /* @__PURE__ */ new Set([
+      "href",
+      "src",
+      "type",
+      "id",
+      "name",
+      "value",
+      "placeholder",
+      "action",
+      "method",
+      "title",
+      "alt",
+      "rel",
+      "target",
+      "lang",
+      "charset",
+      "content",
+      "width",
+      "height",
+      "loading",
+      "for",
+      "role",
+      "min",
+      "max",
+      "step",
+      "pattern",
+      "accept",
+      "list",
+      "download",
+      "tabindex",
+      "cols",
+      "rows",
+      "wrap",
+      "datetime",
+      "method",
+      "action",
+      "placeholder",
+      "disabled",
+      "required",
+      "readonly",
+      "checked",
+      "selected",
+      "target",
+      "rel",
+      "download",
+      "autocomplete",
+      "autofocus",
+      "min",
+      "max",
+      "step",
+      "pattern",
+      "multiple",
+      "size",
+      "cols",
+      "rows",
+      "wrap",
+      "for",
+      "hidden",
+      "width",
+      "height",
+      "loading",
+      "loop",
+      "muted",
+      "controls",
+      "poster",
+      "preload",
+      "contenteditable",
+      "draggable",
+      "spellcheck",
+      "translate",
+      "accesskey",
+      "tabindex",
+      "role",
+      "slot",
+      "is",
+      "part",
+      "enterkeyhint",
+      "inert",
+      "inputmode",
+      "sandbox",
+      "allow",
+      "allowfullscreen",
+      "referrerpolicy",
+      "fetchpriority",
+      "blocking",
+      "property",
+      "itemprop",
+      "itemtype",
+      "itemid",
+      "itemref",
+      "itemscope",
+      "charset",
+      "http-equiv",
+      "data",
+      "nonce",
+      "crossorigin",
+      "integrity",
+      "async",
+      "defer",
+      "srcset",
+      "sizes",
+      "media",
+      "ping",
+      "coords",
+      "shape",
+      "usemap",
+      "ismap",
+      "kind",
+      "srclang",
+      "default",
+      "autoplay",
+      "playsinline",
+      "enctype",
+      "novalidate",
+      "formaction",
+      "formmethod",
+      "formtarget",
+      "formenctype",
+      "formnovalidate"
+    ]);
     CLASS_BOUNDARY_BOOLEAN_ATTRS = /* @__PURE__ */ new Set([
       "disabled",
       "required",
@@ -24162,7 +24545,7 @@ var init_types4 = __esm({
 var TW_VERSION, TW_GENERATOR_META;
 var init_version = __esm({
   "../../packages/compiler/tw/codegen/version.ts"() {
-    TW_VERSION = "1.0.7";
+    TW_VERSION = "1.0.8";
     TW_GENERATOR_META = `<meta name="generator" content="TW Framework ${TW_VERSION}">`;
   }
 });
@@ -24229,6 +24612,16 @@ function collectBuiltinImports(program) {
   for (const dir of program.directives ?? []) {
     if (dir.type !== "ImportDirective") continue;
     const imp = dir;
+    if (imp.source === "tw" || imp.source === "@tw/server") {
+      for (const item of imp.items ?? []) {
+        const name = item.split(" as ").pop().trim();
+        const spec = TW_NAMED_BUILTINS[name];
+        if (spec) out.set(name, spec);
+      }
+      if (imp.defaultImport && TW_NAMED_BUILTINS[imp.defaultImport]) {
+        out.set(imp.defaultImport, TW_NAMED_BUILTINS[imp.defaultImport]);
+      }
+    }
     if (!BUILTIN_COMPONENT_SPECIFIERS.includes(imp.source)) continue;
     if (imp.defaultImport) out.set(imp.defaultImport, imp.source);
     for (const item of imp.items ?? []) {
@@ -24298,7 +24691,7 @@ function normalizePrefetchProp(props) {
   return p;
 }
 function generateRouterLinkTag(props, textContent) {
-  const href = (props.href ?? "").trim();
+  const href = (props.href ?? props.to ?? "").trim();
   if (!href) return `<!-- @tw/RouterLink: missing href -->`;
   const opts = {
     href,
@@ -24325,13 +24718,18 @@ function generateBuiltinTag(specifier, props, textContent) {
   if (specifier === "@tw/RouterLink") return generateRouterLinkTag(props, textContent);
   return null;
 }
-var BUILTIN_COMPONENT_SPECIFIERS, imageConfig;
+var BUILTIN_COMPONENT_SPECIFIERS, imageConfig, TW_NAMED_BUILTINS;
 var init_builtin_components = __esm({
   "../../packages/compiler/tw/codegen/builtin-components.ts"() {
     init_tw2();
     init_tw3();
     BUILTIN_COMPONENT_SPECIFIERS = ["@tw/optImage", "@tw/RouterLink"];
     imageConfig = DEFAULT_IMAGE_CONFIG;
+    TW_NAMED_BUILTINS = {
+      RouterLink: "@tw/RouterLink",
+      optImage: "@tw/optImage",
+      Image: "@tw/optImage"
+    };
   }
 });
 
@@ -24968,6 +25366,58 @@ function stripTssComments(src) {
   return out;
 }
 function compileTSS(source) {
+  {
+    let depth = 0;
+    let line = 1;
+    let inString = null;
+    let inComment = false;
+    let inUrl = false;
+    for (let i = 0; i < source.length; i++) {
+      const ch = source[i];
+      const prev = i > 0 ? source[i - 1] : "";
+      if (ch === "\n") {
+        line++;
+        inComment = false;
+        continue;
+      }
+      if (inComment) continue;
+      if (inString) {
+        if (ch === inString && prev !== "\\") inString = null;
+        continue;
+      }
+      if (inUrl) {
+        if (ch === ")") inUrl = false;
+        continue;
+      }
+      if (ch === "/" && source[i + 1] === "/" && source.slice(Math.max(0, i - 3), i).includes(":")) {
+        inUrl = true;
+        continue;
+      }
+      if (ch === "u" && source.slice(i, i + 4) === "url(") {
+        inUrl = true;
+        i += 3;
+        continue;
+      }
+      if (ch === "/" && source[i + 1] === "/") {
+        inComment = true;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        inString = ch;
+        continue;
+      }
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth < 0) {
+          throw new Error("TW303: unbalanced '}' in stylesheet (line " + line + ")\n  " + (source.split("\n")[line - 1] ?? "").trim().slice(0, 80));
+        }
+      }
+    }
+    if (depth !== 0) {
+      throw new Error("TW303: " + depth + " unclosed '{' in stylesheet -- a rule block is never closed\n  last line: " + (source.split("\n").pop() ?? "").trim().slice(0, 80));
+    }
+  }
   const __twOut = __twCompileTSSInner(source);
   const leftover = __twOut.match(/\$[A-Za-z_][\w-]*/g);
   if (leftover && !/\$\{/.test(__twOut)) {
@@ -25512,11 +25962,11 @@ function emit(items, parent, env, mixins, out) {
 }
 function compileSCSS(source) {
   const cleaned0 = stripComments(source);
-  const UNSUPPORTED = /@(import|mixin|include|extend|use|forward|function|each|if)\b/g;
+  const UNSUPPORTED = /@(import|extend|use|forward|function|each|if|else|for|while)\b/g;
   const m = cleaned0.match(UNSUPPORTED);
   if (m) {
     const seen = Array.from(new Set(m.map((x) => x.trim())));
-    console.warn("[scss] unsupported at-rule(s) ignored: " + seen.join(", ") + " -- TW's SCSS subset supports nesting, $vars and & references only");
+    console.warn("[scss] unsupported at-rule(s) ignored: " + seen.join(", ") + " -- TW's SCSS subset supports nesting, $vars, & references and @mixin/@include");
   }
   const items = parseItems(stripComments(source));
   const out = [];
@@ -25656,13 +26106,13 @@ function collectTssImports(programs, ctx) {
               else ctx.inlineStyles.push(css);
             }
           } catch (e) {
-            if (e && typeof e.message === "string" && /^TW30[12]/.test(e.message)) throw e;
+            if (e && typeof e.message === "string" && /^TW30[123]/.test(e.message)) throw e;
           }
         }
       }
     }
   } catch (e) {
-    if (e && typeof e.message === "string" && /^TW30[12]/.test(e.message)) throw e;
+    if (e && typeof e.message === "string" && /^TW30[123]/.test(e.message)) throw e;
   }
 }
 function resolveTssPath(fromDir, rel) {
@@ -25882,6 +26332,10 @@ function generateSuspense(el, ctx) {
 function generateElement(el, ctx) {
   const tag = el.tag;
   const voidTag = VOID_TAGS5.has(tag.toLowerCase());
+  if (tag.length > 0 && tag[0] === tag[0].toUpperCase() && !["Link", "Suspense"].includes(tag) && !componentRegistry.has(tag) && !resolveBuiltin(tag, activeBuiltinImports)) {
+    console.warn("[tw] unknown component <" + tag + "> (" + el.line + ":" + el.col + ") -- no import resolves it; nothing was rendered");
+    return "<!-- TW: unknown component '" + tag + "' -- check the import -->";
+  }
   {
     const builtinSpec = resolveBuiltin(tag, activeBuiltinImports);
     if (builtinSpec) {
@@ -26141,7 +26595,13 @@ function generateComponent(comp, ctx) {
     ctx.slotContent = savedSlot;
     ctx.inHead = compSavedInHead;
   } else {
-    childrenHTML = comp.children.map((c) => generateNode(c, ctx)).join("");
+    const known = ["Link", "Suspense"];
+    if (!known.includes(compName)) {
+      console.warn("[tw] unknown component <" + compName + "> (" + comp.line + ":" + comp.col + ") -- unresolvable import; nothing was rendered");
+      childrenHTML = "<!-- TW: unknown component '" + compName + "' -- check the import -->";
+    } else {
+      childrenHTML = comp.children.map((c) => generateNode(c, ctx)).join("");
+    }
   }
   ctx.stateVars = savedStateVars;
   ctx.componentStack.pop();
@@ -29938,13 +30398,27 @@ ${indentation})` : type;
 });
 
 // ../../packages/compiler/tw/codegen/vdom.ts
+function stateLiteralForRender(raw) {
+  const evalNum = (v) => typeof v === "number" || typeof v === "boolean" ? String(v) : null;
+  try {
+    const n = evalNum(JSON.parse(raw));
+    if (n !== null) return n;
+  } catch {
+  }
+  try {
+    const n = evalNum(new Function("return (" + raw + ")")());
+    if (n !== null) return n;
+  } catch {
+  }
+  return raw;
+}
 function generateWithLayout(layoutProgram, pageProgram, stateVars) {
   const ctx = createContext("ssr");
   if (stateVars) ctx.stateVars = { ...stateVars };
   for (const dir of pageProgram.directives || []) {
     if (dir.type === "StateDirective") {
       for (const decl of dir.declarations || []) {
-        ctx.stateVars[decl.name] = decl.value;
+        ctx.stateVars[decl.name] = stateLiteralForRender(decl.value);
       }
     }
   }
@@ -29976,7 +30450,7 @@ function generateWithLayoutChain(layoutPrograms, pageProgram, stateVars) {
     for (const dir of pageProgram.directives || []) {
       if (dir.type === "StateDirective") {
         for (const decl of dir.declarations || []) {
-          ctx2.stateVars[decl.name] = decl.value;
+          ctx2.stateVars[decl.name] = stateLiteralForRender(decl.value);
         }
       }
     }
@@ -30167,7 +30641,9 @@ function generate(program, stateVars) {
           ctx.hasInteractivity = true;
           continue;
         }
-        ctx.stateVars[decl.name] = decl.value;
+        if (!(decl.name in ctx.stateVars)) {
+          ctx.stateVars[decl.name] = stateLiteralForRender(decl.value);
+        }
         let v = decl.value;
         try {
           v = JSON.parse(decl.value);
@@ -30500,7 +30976,11 @@ var init_codes = __esm({
       TW090: { message: "cache { } requires a revalidate window or a life profile", severity: "error", category: "syntax" },
       TW091: { message: "fn cached handler is impure (request.cookies/headers/body or setSignal)", severity: "error", category: "semantic" },
       TW092: { message: "Unknown cache profile", severity: "error", category: "semantic" },
-      TW093: { message: "Non-deterministic call in a cached handler (value freezes into the cache entry)", severity: "warning", category: "best-practice" }
+      TW093: { message: "Non-deterministic call in a cached handler (value freezes into the cache entry)", severity: "warning", category: "best-practice" },
+      TW094: { message: "Invalid state literal -- array/object elements must be comma-separated (and objects need colons)", severity: "error", category: "syntax" },
+      TW095: { message: "Invalid for-loop iterable -- use {varName} or a valid comma-separated literal", severity: "error", category: "syntax" },
+      TW096: { message: "Unknown state variable in interpolation (renders empty)", severity: "warning", category: "semantic" },
+      TW097: { message: "while with a comparison renders its body ONCE at build time (state cannot mutate during SSR) -- use for loops for repetition", severity: "warning", category: "semantic" }
     };
   }
 });
@@ -30821,6 +31301,124 @@ function checkUnusedDeclarations(program, filePath, diags) {
     }
   }
 }
+function literalIsBroken(value) {
+  const v = value.trim();
+  if (!v.startsWith("[") && !v.startsWith("{")) return false;
+  try {
+    new Function("return (" + v + ")");
+    return false;
+  } catch {
+    return true;
+  }
+}
+function checkStateLiterals(program, filePath, diags) {
+  for (const decl of collectStateDecls(program)) {
+    if (decl.signalKind === "derived") continue;
+    if (literalIsBroken(String(decl.value))) {
+      diags.push(createDiagnostic(
+        "TW094",
+        decl.line,
+        decl.col,
+        filePath,
+        `${decl.name} = ${decl.value}`,
+        [
+          `Comma-separate array elements: ${decl.name} = ["a", "b", "c"]`,
+          `Objects need colons: ${decl.name} = { key: "value" }`
+        ]
+      ));
+    }
+  }
+}
+function checkLoopIterables(program, filePath, diags) {
+  forEachNode(program, (node) => {
+    if (!node || node.type !== "For") return;
+    const iterable = String(node.iterable ?? "").trim();
+    if (!iterable) {
+      diags.push(createDiagnostic(
+        "TW095",
+        node.line,
+        node.col,
+        filePath,
+        "for-loop has no iterable",
+        [`Use: for item in {list} { ... }`]
+      ));
+      return;
+    }
+    if (/^\{[A-Za-z_][\w.]*\}$/.test(iterable)) return;
+    if (/^[A-Za-z_][\w.]*$/.test(iterable)) return;
+    if (literalIsBroken(iterable)) {
+      diags.push(createDiagnostic(
+        "TW095",
+        node.line,
+        node.col,
+        filePath,
+        "for x in " + iterable,
+        [
+          `Wrap a state variable in braces: for item in {items}`,
+          `Literals need commas: for item in {["a", "b", "c"]}`
+        ]
+      ));
+    }
+  });
+}
+function checkUnknownStateVars(program, filePath, diags) {
+  const known = /* @__PURE__ */ new Set();
+  for (const decl of collectStateDecls(program)) known.add(decl.name);
+  forEachNode(program, (node) => {
+    if (node && node.type === "For" && node.varName) known.add(node.varName);
+    if (node && node.type === "For" && node.indexName) known.add(node.indexName);
+  });
+  const BUILTINS2 = /* @__PURE__ */ new Set([
+    "params",
+    "props",
+    "Math",
+    "Date",
+    "JSON",
+    "String",
+    "Number",
+    "Boolean",
+    "Array",
+    "Object",
+    "window",
+    "true",
+    "false",
+    "null",
+    "undefined"
+  ]);
+  forEachNode(program, (node) => {
+    if (!isText(node)) return;
+    const text = String(node.value ?? "");
+    if (!text.includes("{")) return;
+    for (const m of text.matchAll(/\{\s*([A-Za-z_][\w]*)\s*\}/g)) {
+      const name = m[1];
+      if (known.has(name) || BUILTINS2.has(name)) continue;
+      diags.push(createDiagnostic(
+        "TW096",
+        node.line,
+        node.col,
+        filePath,
+        `{${name}}`,
+        [`Declare it in the state block, or check the spelling`]
+      ));
+    }
+  });
+}
+function checkWhileComparisons(program, filePath, diags) {
+  forEachNode(program, (node) => {
+    if (!node || node.type !== "While") return;
+    const cond = String(node.condition ?? "");
+    if (/[<>=!]/.test(cond)) {
+      diags.push(createDiagnostic(
+        "TW097",
+        node.line,
+        node.col,
+        filePath,
+        "while " + cond,
+        ["Use `for item in {list}` for repetition", "while is for boolean flags (state { loading = true })"]
+      ));
+    }
+  });
+}
 var HTML_ELEMENTS2, HTML_ATTRIBUTES2, GLOBAL_ATTRIBUTES2, CSS_PROPERTIES2, CSS_ALIASES2, EVENT_TYPES2, ARIA_ROLES2, ARIA_ATTRIBUTES2;
 var init_rules = __esm({
   "../../packages/compiler/tw/diagnostics/rules.ts"() {
@@ -31711,6 +32309,10 @@ function diagnose(program, filePath) {
   checkSemanticErrors(program, filePath, diagnostics);
   checkDirectives(program, filePath, diagnostics);
   checkUnusedDeclarations(program, filePath, diagnostics);
+  checkStateLiterals(program, filePath, diagnostics);
+  checkLoopIterables(program, filePath, diagnostics);
+  checkUnknownStateVars(program, filePath, diagnostics);
+  checkWhileComparisons(program, filePath, diagnostics);
   return diagnostics;
 }
 var RuleEngine;
@@ -41625,6 +42227,7 @@ var init_render_pipeline = __esm({
     init_twm_loader();
     init_scanner();
     init_layout_chain();
+    init_signal_stream();
     init_helpers();
     init_tw6();
     init_twm_loader();
@@ -41778,6 +42381,17 @@ var init_render_pipeline = __esm({
         try {
           const pageState = { ...stateVars ?? {}, ...match.params ?? {}, params: match.params ?? {} };
           const requestVarKeys = new Set(Object.keys({ ...stateVars ?? {}, ...match.params ?? {} }));
+          try {
+            const hub2 = getSignalHub();
+            const snap = hub2.snapshot();
+            if (snap && snap.snapshot && typeof snap.snapshot === "object") {
+              for (const [k, v] of Object.entries(snap.snapshot)) {
+                pageState[k] = v;
+                requestVarKeys.add(k);
+              }
+            }
+          } catch {
+          }
           const pageCompiled = this.compileFile(ctx.page, pageState);
           {
             const seed = pageCompiled.stateSeed;
@@ -41823,24 +42437,30 @@ var init_render_pipeline = __esm({
           let layoutTitle;
           const liftedParts = [];
           {
-            for (const headMatch of bodyHTML.matchAll(/<head[^>]*>([\s\S]*?)<\/head>/gi)) {
+            const collectedTitles = [];
+            for (const headMatch of bodyHTML.matchAll(/<head(?:\s[^>]*)?>([\s\S]*?)<\/head\s*>/gi)) {
               const headInner = headMatch[1];
               const tMatch = headInner.match(/<title>([^<]*)<\/title>/i);
-              if (tMatch) layoutTitle = tMatch[1].trim().replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
-              const kids = headInner.replace(/<title>[^<]*<\/title>/gi, "").replace(/<meta[^>]+charset[^>]*>/gi, "").replace(/<meta[^>]+viewport[^>]*>/gi, "").trim();
+              if (tMatch) collectedTitles.push(tMatch[1].trim().replace(/&(amp|lt|gt|quot);/g, (m, k) => k === "amp" ? String.fromCharCode(38) : k === "lt" ? String.fromCharCode(60) : k === "gt" ? String.fromCharCode(62) : String.fromCharCode(34)));
+              else collectedTitles.push("");
+              const kids = headInner.replace(/<title>[^<]*<\/title>/gi, "").replace(/<meta[^>]+charset[^>]*>/gi, "").replace(/<meta[^>]+viewport[^>]*>/gi, "").replace(/<meta[^>]+generator[^>]*>/gi, "").trim();
               if (kids) liftedParts.push(kids);
             }
-            bodyHTML = bodyHTML.replace(/<head[^>]*>[\s\S]*?<\/head>/gi, "");
+            bodyHTML = bodyHTML.replace(/<head(?:\s[^>]*)?>[\s\S]*?<\/head\s*>/gi, "");
+            const templateTitle = collectedTitles.find((t2) => t2.includes("__TW_PAGETITLE__"));
+            layoutTitle = templateTitle ?? collectedTitles.filter(Boolean).pop();
             bodyHTML = bodyHTML.replace(/<\/?(?:html|body)[^>]*>/gi, "");
             bodyHTML = bodyHTML.replace(/<!DOCTYPE[^>]*>/gi, "");
           }
           const liftedHead = liftedParts.join("\n");
-          if (ctx.error) {
+          const liveRenderMode = this.extractRenderMode(ctx.page);
+          if (ctx.error && (liveRenderMode === "ssr" || liveRenderMode === "stream")) {
             const errorCompiled = this.compileFile(ctx.error);
             allCSS = errorCompiled.css + "\n" + allCSS;
             bodyHTML = `<div data-error-boundary>${bodyHTML}</div>`;
           }
-          if (ctx.loading) {
+          const needsSkeleton = bodyHTML.includes("data-tw-suspense") || bodyHTML.includes("data-tw-ppr");
+          if (ctx.loading && needsSkeleton) {
             const loadingCompiled = this.compileFile(ctx.loading);
             allCSS = loadingCompiled.css + "\n" + allCSS;
             let lh = String(loadingCompiled.html || "");
@@ -41852,7 +42472,7 @@ ${bodyHTML}`;
           const pageTitle = this.extractTitle(ctx.page) || "TW Page";
           let title = pageTitle;
           if (layoutTitle !== void 0) {
-            title = layoutTitle.replace(/\{\s*page\.title\s*\}/g, pageTitle);
+            title = layoutTitle.replace(/__TW_PAGETITLE__/g, pageTitle).replace(/\{\s*page\.title\s*\}/g, pageTitle);
             if (!title.trim()) title = pageTitle;
           }
           const metaTags = this.buildMetaTags(ctx.page);
@@ -41872,7 +42492,9 @@ ${bodyHTML}`;
           } catch {
           }
           let fullHTML = this.assembleHTML(bodyHTML, allCSS, allJS, title, metaTags + headExtra);
-          if (!/__tw_runtime\.js/.test(fullHTML)) {
+          const pageRenderMode = this.extractRenderMode(ctx.page);
+          const needsClientRuntime = /data-tw-event|data-tw-i|__TW_SIGNALS__|data-tw-suspense|data-tw-ppr/.test(fullHTML) || pageRenderMode === "csr" || pageRenderMode === "stream" || pageRenderMode === "ppr" || pageRenderMode === "signalStream";
+          if (needsClientRuntime && !/__tw_runtime\.js/.test(fullHTML)) {
             let stateSeed = "{}";
             try {
               stateSeed = JSON.stringify(pageState ?? {});
@@ -41991,7 +42613,8 @@ ${bodyHTML}`;
           throw new Error(`Route file not found: ${file.absolutePath}`);
         }
         const source = (0, import_node_fs6.readFileSync)(file.absolutePath, "utf-8");
-        const result = compileSync(source, {
+        const srcWithSentinel = source.replace(/\{\s*page\.title\s*\}/g, "__TW_PAGETITLE__");
+        const result = compileSync(srcWithSentinel, {
           filePath: file.absolutePath,
           optimize: true,
           diagnostics: false,
@@ -42065,12 +42688,13 @@ ${bodyHTML}`;
         try {
           const source = (0, import_node_fs6.readFileSync)(file.absolutePath, "utf-8");
           const masked = maskSourceStringsAndComments(source);
-          const m = masked.match(/page\s*\{[^}]*title\s+"/);
+          const m = masked.match(/page\s*\{[^}]*title\s/);
           if (!m || m.index === void 0) return null;
           const start = m.index + m[0].length;
-          const end = source.indexOf('"', start);
-          if (end === -1 || end === start) return null;
-          return source.slice(start, end).replace(/\\([{}"])/g, "$1");
+          if (source[start] !== '"') return null;
+          const end = source.indexOf('"', start + 1);
+          if (end === -1 || end === start + 1) return null;
+          return source.slice(start + 1, end).replace(/\\([{}"])/g, "$1");
         } catch {
           return null;
         }
@@ -42119,7 +42743,8 @@ ${bodyHTML}`;
        *     render-cache never reads `stale`.
        */
       stampCacheHeaders(headers, entry, now, verdict) {
-        const out = { ...headers ?? {}, "x-tw-cache": verdict };
+        const out = { ...headers ?? {} };
+        if (process.env.TW_DEBUG_CACHE || process.env.NODE_ENV === "test") out["x-tw-cache"] = verdict;
         const c = entry?.cache;
         if (c) {
           const ageSec = entry?.createdAt ? Math.max(0, Math.floor((now - entry.createdAt) / 1e3)) : 0;
@@ -43653,7 +44278,6 @@ function securityHeadersMiddleware() {
   return (req, res, next) => {
     res.headers.set("X-Content-Type-Options", "nosniff");
     res.headers.set("X-Frame-Options", "SAMEORIGIN");
-    res.headers.set("X-XSS-Protection", "1; mode=block");
     res.headers.set("X-Permitted-Cross-Domain-Policies", "none");
     res.headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
     res.headers.set("Cross-Origin-Opener-Policy", "same-origin");
@@ -43830,13 +44454,15 @@ function compressionMiddleware() {
     await next();
   };
 }
-function securityHeadersMiddleware2() {
+function securityHeadersMiddleware2(opts) {
   return async (ctx, next) => {
     ctx.headers["x-content-type-options"] = "nosniff";
     ctx.headers["x-frame-options"] = "DENY";
-    ctx.headers["x-xss-protection"] = "1; mode=block";
     ctx.headers["referrer-policy"] = "strict-origin-when-cross-origin";
     ctx.headers["permissions-policy"] = "camera=(), microphone=(), geolocation=()";
+    if (opts?.csp !== false && !ctx.headers["content-security-policy"]) {
+      ctx.headers["content-security-policy"] = typeof opts?.csp === "string" ? opts.csp : "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; media-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'";
+    }
     await next();
   };
 }
@@ -43919,6 +44545,161 @@ var init_middleware2 = __esm({
   }
 });
 
+// ../../packages/server/tw/compression.ts
+function shouldCompress(contentType, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS4, ...options };
+  const ct = contentType.split(";")[0].trim();
+  return opts.contentTypes.includes(ct);
+}
+function isLargeEnough(size, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS4, ...options };
+  return size >= opts.threshold;
+}
+async function compress(data, encoding = "gzip", options = {}) {
+  const opts = { ...DEFAULT_OPTIONS4, ...options };
+  const input = typeof data === "string" ? new TextEncoder().encode(data) : data;
+  if (input.length < opts.threshold) {
+    return input;
+  }
+  try {
+    if (typeof Bun !== "undefined" && Bun.gzipSync) {
+      if (encoding === "gzip") return Bun.gzipSync(input, { level: opts.level });
+      if (encoding === "deflate" && Bun.deflateSync) return Bun.deflateSync(input, { level: opts.level });
+    }
+  } catch {
+  }
+  try {
+    const zlib = await import("node:zlib");
+    if (encoding === "gzip") {
+      return zlib.gzipSync(input, { level: opts.level });
+    }
+    if (encoding === "deflate") {
+      return zlib.deflateSync(input, { level: opts.level });
+    }
+    if (encoding === "brotli" && zlib.brotliCompressSync) {
+      return zlib.brotliCompressSync(input, {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: opts.level
+        }
+      });
+    }
+  } catch {
+  }
+  return input;
+}
+async function decompress(data, encoding = "gzip") {
+  try {
+    if (typeof Bun !== "undefined" && Bun.gunzipSync) {
+      if (encoding === "gzip") return Bun.gunzipSync(data);
+      if (encoding === "deflate" && Bun.inflateSync) return Bun.inflateSync(data);
+    }
+  } catch {
+  }
+  try {
+    const zlib = await import("node:zlib");
+    if (encoding === "gzip") return zlib.gunzipSync(data);
+    if (encoding === "deflate") return zlib.inflateSync(data);
+    if (encoding === "brotli" && zlib.brotliDecompressSync) return zlib.brotliDecompressSync(data);
+  } catch {
+  }
+  return data;
+}
+function negotiateEncoding(acceptEncoding) {
+  const encodings = acceptEncoding.split(",").map((e) => e.trim().split(";")[0].trim()).filter(Boolean);
+  if (encodings.includes("br")) return "brotli";
+  if (encodings.includes("gzip")) return "gzip";
+  if (encodings.includes("deflate")) return "deflate";
+  return null;
+}
+function createCompressionHeaders(encoding, originalSize, compressedSize) {
+  return {
+    "Content-Encoding": encoding === "brotli" ? "br" : encoding,
+    "Vary": "Accept-Encoding",
+    "X-Original-Size": String(originalSize),
+    "X-Compressed-Size": String(compressedSize),
+    "X-Compression-Ratio": originalSize > 0 ? `${((1 - compressedSize / originalSize) * 100).toFixed(1)}%` : "0%"
+  };
+}
+async function compressResponse(body, contentType, acceptEncoding, options = {}) {
+  const input = typeof body === "string" ? new TextEncoder().encode(body) : body;
+  const opts = { ...DEFAULT_OPTIONS4, ...options };
+  if (!shouldCompress(contentType, opts) || !isLargeEnough(input.length, opts)) {
+    return { body: input, headers: {}, compressed: false };
+  }
+  const encoding = negotiateEncoding(acceptEncoding);
+  if (!encoding) {
+    return { body: input, headers: {}, compressed: false };
+  }
+  try {
+    const compressed = await compress(input, encoding, opts);
+    const headers = createCompressionHeaders(encoding, input.length, compressed.length);
+    return { body: compressed, headers, compressed: true };
+  } catch {
+    return { body: input, headers: {}, compressed: false };
+  }
+}
+var DEFAULT_OPTIONS4, StreamingCompressor;
+var init_compression = __esm({
+  "../../packages/server/tw/compression.ts"() {
+    DEFAULT_OPTIONS4 = {
+      level: 6,
+      threshold: 1024,
+      // Don't compress < 1KB
+      brotli: true,
+      contentTypes: [
+        "text/html",
+        "text/css",
+        "text/plain",
+        "text/javascript",
+        "application/javascript",
+        "application/json",
+        "application/xml",
+        "application/xhtml+xml",
+        "image/svg+xml",
+        "font/woff",
+        "font/woff2",
+        "application/wasm"
+      ]
+    };
+    StreamingCompressor = class {
+      chunks = [];
+      encoding;
+      options;
+      constructor(encoding = "gzip", options = {}) {
+        this.encoding = encoding;
+        this.options = { ...DEFAULT_OPTIONS4, ...options };
+      }
+      /**
+       * Add a chunk of data to be compressed.
+       */
+      push(data) {
+        const input = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        this.chunks.push(input);
+      }
+      /**
+       * Flush all data and return compressed result.
+       */
+      async flush() {
+        const totalLength = this.chunks.reduce((sum, c) => sum + c.length, 0);
+        const combined = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of this.chunks) {
+          combined.set(chunk, offset);
+          offset += chunk.length;
+        }
+        this.chunks = [];
+        return compress(combined, this.encoding, this.options);
+      }
+      /**
+       * Get the total uncompressed size so far.
+       */
+      get uncompressedSize() {
+        return this.chunks.reduce((sum, c) => sum + c.length, 0);
+      }
+    };
+  }
+});
+
 // ../../packages/server/tw/static/index.ts
 var import_node_fs8, import_node_path15, StaticHandler;
 var init_static = __esm({
@@ -44128,7 +44909,7 @@ var init_policy = __esm({
           "Content-Security-Policy": this.build(),
           "X-Content-Type-Options": "nosniff",
           "X-Frame-Options": "DENY",
-          "X-XSS-Protection": "1; mode=block",
+          // BUG 48: x-xss-protection removed (deprecated, harmful in old browsers)
           "Referrer-Policy": "strict-origin-when-cross-origin",
           "Permissions-Policy": "geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()",
           "Cross-Origin-Opener-Policy": "same-origin",
@@ -48762,9 +49543,10 @@ function devSecurityHeaders() {
     removePoweredBy: true
   });
 }
-var DEFAULTS2, SecurityHeaders2;
+var BASELINE_CSP, DEFAULTS2, SecurityHeaders2;
 var init_security_headers = __esm({
   "../../packages/security/tw/headers/security-headers.ts"() {
+    BASELINE_CSP = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; media-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'";
     DEFAULTS2 = {
       hstsMaxAge: 31536e3,
       // 1 year
@@ -48773,7 +49555,9 @@ var init_security_headers = __esm({
       frameOptions: "SAMEORIGIN",
       contentTypeOptions: true,
       referrerPolicy: "strict-origin-when-cross-origin",
-      xssProtection: "1; mode=block",
+      // v1.0.8 round 5 (BUG 48): x-xss-protection deprecated since 2019 --
+      // OFF by default now; opt back in with security.xssProtection.
+      xssProtection: void 0,
       removePoweredBy: true,
       coep: "unsafe-none",
       coop: "same-origin",
@@ -48829,6 +49613,9 @@ var init_security_headers = __esm({
         if (this.config.serverHeader) {
           headers["Server"] = this.config.serverHeader;
         }
+        if (this.config.csp !== false && !headers["Content-Security-Policy"]) {
+          headers["Content-Security-Policy"] = typeof this.config.csp === "string" ? this.config.csp : BASELINE_CSP;
+        }
         return headers;
       }
       /** Returns the security headers object. */
@@ -53039,161 +53826,6 @@ var init_ssr = __esm({
   }
 });
 
-// ../../packages/server/tw/compression.ts
-function shouldCompress(contentType, options = {}) {
-  const opts = { ...DEFAULT_OPTIONS4, ...options };
-  const ct = contentType.split(";")[0].trim();
-  return opts.contentTypes.includes(ct);
-}
-function isLargeEnough(size, options = {}) {
-  const opts = { ...DEFAULT_OPTIONS4, ...options };
-  return size >= opts.threshold;
-}
-async function compress(data, encoding = "gzip", options = {}) {
-  const opts = { ...DEFAULT_OPTIONS4, ...options };
-  const input = typeof data === "string" ? new TextEncoder().encode(data) : data;
-  if (input.length < opts.threshold) {
-    return input;
-  }
-  try {
-    if (typeof Bun !== "undefined" && Bun.gzipSync) {
-      if (encoding === "gzip") return Bun.gzipSync(input, { level: opts.level });
-      if (encoding === "deflate" && Bun.deflateSync) return Bun.deflateSync(input, { level: opts.level });
-    }
-  } catch {
-  }
-  try {
-    const zlib = await import("node:zlib");
-    if (encoding === "gzip") {
-      return zlib.gzipSync(input, { level: opts.level });
-    }
-    if (encoding === "deflate") {
-      return zlib.deflateSync(input, { level: opts.level });
-    }
-    if (encoding === "brotli" && zlib.brotliCompressSync) {
-      return zlib.brotliCompressSync(input, {
-        params: {
-          [zlib.constants.BROTLI_PARAM_QUALITY]: opts.level
-        }
-      });
-    }
-  } catch {
-  }
-  return input;
-}
-async function decompress(data, encoding = "gzip") {
-  try {
-    if (typeof Bun !== "undefined" && Bun.gunzipSync) {
-      if (encoding === "gzip") return Bun.gunzipSync(data);
-      if (encoding === "deflate" && Bun.inflateSync) return Bun.inflateSync(data);
-    }
-  } catch {
-  }
-  try {
-    const zlib = await import("node:zlib");
-    if (encoding === "gzip") return zlib.gunzipSync(data);
-    if (encoding === "deflate") return zlib.inflateSync(data);
-    if (encoding === "brotli" && zlib.brotliDecompressSync) return zlib.brotliDecompressSync(data);
-  } catch {
-  }
-  return data;
-}
-function negotiateEncoding(acceptEncoding) {
-  const encodings = acceptEncoding.split(",").map((e) => e.trim().split(";")[0].trim()).filter(Boolean);
-  if (encodings.includes("br")) return "brotli";
-  if (encodings.includes("gzip")) return "gzip";
-  if (encodings.includes("deflate")) return "deflate";
-  return null;
-}
-function createCompressionHeaders(encoding, originalSize, compressedSize) {
-  return {
-    "Content-Encoding": encoding === "brotli" ? "br" : encoding,
-    "Vary": "Accept-Encoding",
-    "X-Original-Size": String(originalSize),
-    "X-Compressed-Size": String(compressedSize),
-    "X-Compression-Ratio": originalSize > 0 ? `${((1 - compressedSize / originalSize) * 100).toFixed(1)}%` : "0%"
-  };
-}
-async function compressResponse(body, contentType, acceptEncoding, options = {}) {
-  const input = typeof body === "string" ? new TextEncoder().encode(body) : body;
-  const opts = { ...DEFAULT_OPTIONS4, ...options };
-  if (!shouldCompress(contentType, opts) || !isLargeEnough(input.length, opts)) {
-    return { body: input, headers: {}, compressed: false };
-  }
-  const encoding = negotiateEncoding(acceptEncoding);
-  if (!encoding) {
-    return { body: input, headers: {}, compressed: false };
-  }
-  try {
-    const compressed = await compress(input, encoding, opts);
-    const headers = createCompressionHeaders(encoding, input.length, compressed.length);
-    return { body: compressed, headers, compressed: true };
-  } catch {
-    return { body: input, headers: {}, compressed: false };
-  }
-}
-var DEFAULT_OPTIONS4, StreamingCompressor;
-var init_compression = __esm({
-  "../../packages/server/tw/compression.ts"() {
-    DEFAULT_OPTIONS4 = {
-      level: 6,
-      threshold: 1024,
-      // Don't compress < 1KB
-      brotli: true,
-      contentTypes: [
-        "text/html",
-        "text/css",
-        "text/plain",
-        "text/javascript",
-        "application/javascript",
-        "application/json",
-        "application/xml",
-        "application/xhtml+xml",
-        "image/svg+xml",
-        "font/woff",
-        "font/woff2",
-        "application/wasm"
-      ]
-    };
-    StreamingCompressor = class {
-      chunks = [];
-      encoding;
-      options;
-      constructor(encoding = "gzip", options = {}) {
-        this.encoding = encoding;
-        this.options = { ...DEFAULT_OPTIONS4, ...options };
-      }
-      /**
-       * Add a chunk of data to be compressed.
-       */
-      push(data) {
-        const input = typeof data === "string" ? new TextEncoder().encode(data) : data;
-        this.chunks.push(input);
-      }
-      /**
-       * Flush all data and return compressed result.
-       */
-      async flush() {
-        const totalLength = this.chunks.reduce((sum, c) => sum + c.length, 0);
-        const combined = new Uint8Array(totalLength);
-        let offset = 0;
-        for (const chunk of this.chunks) {
-          combined.set(chunk, offset);
-          offset += chunk.length;
-        }
-        this.chunks = [];
-        return compress(combined, this.encoding, this.options);
-      }
-      /**
-       * Get the total uncompressed size so far.
-       */
-      get uncompressedSize() {
-        return this.chunks.reduce((sum, c) => sum + c.length, 0);
-      }
-    };
-  }
-});
-
 // ../../packages/server/tw/edge.ts
 function createEdgeHandler(config) {
   const cache = /* @__PURE__ */ new Map();
@@ -53912,8 +54544,11 @@ var init_tw6 = __esm({
     init_routing2();
     import_node_path17 = require("node:path");
     import_node_fs11 = require("node:fs");
+    init_twm_rules();
     init_router();
     init_middleware2();
+    init_compression();
+    init_signal_stream();
     init_static();
     init_tw5();
     init_ssr();
@@ -53962,6 +54597,7 @@ var init_tw6 = __esm({
       }
       ssr = null;
       server = null;
+      compressionMode = "off";
       isRunning = false;
       pluginManager = null;
       imageHandler = null;
@@ -53978,6 +54614,40 @@ var init_tw6 = __esm({
             const entries = Object.entries(cfgIn.redirects);
             cfgIn.redirects = entries.map(([from, to]) => typeof to === "string" ? { from, to } : { from, ...to });
           }
+          if (Array.isArray(cfgIn.redirects)) {
+            const REDIRECT_KNOWN = /* @__PURE__ */ new Set(["from", "to", "status", "source", "destination", "permanent"]);
+            let redirectDropped = false;
+            const normalizedRedirects = cfgIn.redirects.map((r) => {
+              if (!r || typeof r !== "object") return r;
+              let touched = false;
+              const mapped = { ...r };
+              if (mapped.from === void 0 && mapped.source !== void 0) {
+                mapped.from = mapped.source;
+                touched = true;
+              }
+              if (mapped.to === void 0 && mapped.destination !== void 0) {
+                mapped.to = mapped.destination;
+                touched = true;
+              }
+              if (mapped.status === void 0 && mapped.permanent !== void 0) {
+                mapped.status = mapped.permanent ? 301 : 302;
+                touched = true;
+              }
+              const unknown = Object.keys(mapped).filter((k) => !REDIRECT_KNOWN.has(k));
+              if (unknown.length > 0) {
+                console.warn("[tw] redirects: unrecognized field" + (unknown.length > 1 ? "s" : "") + " " + unknown.join(", ") + " in entry { from: " + JSON.stringify(mapped.from) + " } -- accepted fields: from, to, status");
+              }
+              if (typeof mapped.from !== "string" || typeof mapped.to !== "string") {
+                console.warn("[tw] redirects: entry missing from/to after normalization -- skipped (" + JSON.stringify(r).slice(0, 80) + ")");
+                redirectDropped = true;
+                return null;
+              }
+              return touched ? mapped : r;
+            }).filter((x) => x !== null || (redirectDropped = true));
+            if (redirectDropped || normalizedRedirects.some((x, i) => x !== cfgIn.redirects[i])) {
+              cfgIn.redirects = normalizedRedirects.filter(Boolean);
+            }
+          }
           if (cfgIn.headers && !Array.isArray(cfgIn.headers)) {
             const entries = Object.entries(cfgIn.headers);
             cfgIn.headers = entries.map(([source, headers]) => ({ source, headers }));
@@ -53995,6 +54665,12 @@ var init_tw6 = __esm({
           }
         }
         this.pluginManager = this.options.plugins ?? null;
+        {
+          const raw = this.options.compression ?? true;
+          if (raw === false || raw === "none" || raw === "off" || raw === "false") this.compressionMode = "off";
+          else if (raw === "gzip") this.compressionMode = "gzip";
+          else this.compressionMode = "brotli";
+        }
         try {
           this.imageHandler = createImageHandler({
             rootDir: this.options.rootDir,
@@ -54104,31 +54780,72 @@ var init_tw6 = __esm({
         if ((0, import_node_fs11.existsSync)(middlewarePath)) {
           this.middlewarePath = middlewarePath;
           console.log("  Middleware: middleware.twm loaded");
+          try {
+            const src = (0, import_node_fs11.readFileSync)(middlewarePath, "utf-8");
+            const rules = parseRules(src, "middleware.twm");
+            for (const r of rules) {
+              const conds = [];
+              if (r.userAgent) conds.push("user_agent");
+              if (r.path) conds.push("path");
+              if (r.auth) conds.push("auth");
+              if (r.rateLimit) conds.push("rate_limit");
+              if (r.origin) conds.push("origin");
+              if (r.methods && r.methods.length > 0) conds.push("methods");
+              const label = conds.length > 0 ? conds.join(" + ") : "no conditions -> every matching request gets this response";
+              console.log(`    \u2022 "${r.name}" [${label}]`);
+            }
+          } catch {
+          }
         }
         return this;
       }
       async start() {
         if (this.isRunning) return;
-        const { port, host } = this.options;
-        this.server = (typeof Bun !== "undefined" ? Bun : null)?.serve({
-          port,
-          hostname: host,
-          fetch: async (request) => {
-            const res = await this.handleRequest(request);
-            if (this.securityHeaders) {
-              try {
-                return this.securityHeaders.apply(res);
-              } catch {
-                return res;
+        const host = this.options.host ?? "0.0.0.0";
+        const wanted = this.options.port ?? 8e3;
+        let port = wanted;
+        let bound = null;
+        let lastErr = null;
+        for (let p = wanted; p < wanted + 10; p++) {
+          try {
+            bound = (typeof Bun !== "undefined" ? Bun : null)?.serve({
+              port: p,
+              hostname: host,
+              fetch: async (request) => {
+                const res = await this.handleRequest(request);
+                let withHeaders = res;
+                if (this.securityHeaders) {
+                  try {
+                    withHeaders = this.securityHeaders.apply(res);
+                  } catch {
+                    withHeaders = res;
+                  }
+                }
+                return this.compressResponse(withHeaders, request);
+              },
+              error: (err3) => {
+                console.error("Server error:", err3);
+                return new Response("Internal Server Error", { status: 500 });
               }
-            }
-            return res;
-          },
-          error: (err3) => {
-            console.error("Server error:", err3);
-            return new Response("Internal Server Error", { status: 500 });
+            });
+            port = p;
+            break;
+          } catch (e) {
+            lastErr = e;
+            const msg = String(e?.message ?? e);
+            if (!/address already in use|EADDRINUSE|Failed to start server/i.test(msg)) throw e;
+            if (p < wanted + 9) console.log(`  Port ${p} busy \u2014 trying ${p + 1}...`);
           }
-        });
+        }
+        if (!bound) {
+          console.error(`
+  ERROR: could not bind ${host} on ports ${wanted}\u2013${wanted + 9}.`);
+          console.error(`  ${lastErr?.message ?? lastErr}
+`);
+          throw lastErr ?? new Error("could not start server");
+        }
+        this.server = bound;
+        this.options.port = port;
         this.isRunning = true;
         console.log(`
   TW Server running at http://${host}:${port}
@@ -54142,6 +54859,10 @@ var init_tw6 = __esm({
       // finishes ongoing requests, then closes
       async gracefulShutdown(timeout = 5e3) {
         this.isRunning = false;
+        try {
+          getSignalHub().closeAll();
+        } catch {
+        }
         if (this.server) {
           this.server.stop?.(false);
           const start = Date.now();
@@ -54167,6 +54888,35 @@ var init_tw6 = __esm({
        *   - return { headers: {...} }  -> headers merged into the final response
        *   - return null/undefined      -> continue
        */
+      /** BUG 7 (v1.0.8): real response compression. `compression` in
+       * tw.config.ts was silently ignored -- the middleware was a no-op and
+       * nothing on the response path ever set Content-Encoding. */
+      async compressResponse(res, request) {
+        if (this.compressionMode === "off") return res;
+        try {
+          if (res.headers.get("content-encoding")) return res;
+          const ct = res.headers.get("content-type") || "";
+          if (ct.includes("text/event-stream")) return res;
+          if (res.__twRawStream) return res;
+          const buf = new Uint8Array(await res.arrayBuffer());
+          if (!isLargeEnough(buf.length)) return new Response(buf, { status: res.status, headers: res.headers });
+          const accept = request.headers.get("accept-encoding") || "";
+          let enc = negotiateEncoding(accept);
+          if (this.compressionMode === "gzip" && enc === "brotli") enc = "gzip";
+          if (!enc) return new Response(buf, { status: res.status, headers: res.headers });
+          const out = await compress(buf, enc);
+          if (out.length >= buf.length) return new Response(buf, { status: res.status, headers: res.headers });
+          const h = new Headers(res.headers);
+          h.set("Content-Encoding", enc === "brotli" ? "br" : enc);
+          h.set("Vary", "Accept-Encoding");
+          h.delete("Content-Length");
+          return new Response(out, { status: res.status, headers: h });
+        } catch {
+          return res;
+        }
+      }
+      /** v1.0.8 round 5 (BUG 39): public now -- serverless adapters (Vercel
+       *  functions, edge runtimes) drive the server through this entry. */
       async handleRequest(request) {
         try {
           const u = new URL(request.url);
@@ -54339,69 +55089,12 @@ var init_tw6 = __esm({
        * `data: {"v":1,"seq":N,"updates":[...]}` frames.
        */
       handleSignalStream(request, url) {
-        const hub2 = getSignalHub();
-        const names = (url.searchParams.get("s") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
-        const since = Number(url.searchParams.get("since") ?? "0") || 0;
-        const declared = /* @__PURE__ */ new Map();
-        for (const n of names) declared.set(n, "public");
-        let session;
-        try {
-          const header = request.headers.get("cookie") ?? "";
-          const m = /(?:^|;\s*)tw_session=([^;]+)/.exec(header);
-          if (m) session = decodeURIComponent(m[1].trim().replace(/^"|"$/g, ""));
-        } catch {
-        }
-        const enc = new TextEncoder();
-        const sse = (payload) => enc.encode("data: " + payload + "\n\n");
-        const stream = new ReadableStream({
-          start(controller) {
-            const client = hub2.register(declared, session);
-            client.send = (payload) => {
-              try {
-                controller.enqueue(sse(payload));
-              } catch {
-                client.close();
-              }
-            };
-            client.close = () => {
-              try {
-                controller.close();
-              } catch {
-              }
-              hub2["clients"];
-            };
-            for (const payload of hub2.connectPayloads(since, declared, session)) {
-              try {
-                controller.enqueue(sse(payload));
-              } catch {
-                break;
-              }
-            }
-            const keepAlive = setInterval(() => {
-              try {
-                controller.enqueue(enc.encode(": keep-alive\n\n"));
-              } catch {
-                clearInterval(keepAlive);
-              }
-            }, 25e3);
-            client.close = () => {
-              clearInterval(keepAlive);
-              try {
-                controller.close();
-              } catch {
-              }
-            };
-          }
-        });
-        return new Response(stream, {
-          status: 200,
-          headers: {
-            "Content-Type": "text/event-stream; charset=utf-8",
-            "Cache-Control": "no-store",
-            "X-Accel-Buffering": "no",
-            Connection: "keep-alive"
-          }
-        });
+        const cfg = this.options.config?.signalStream;
+        return createSignalStream(request, url, cfg ? { maxClients: cfg.maxClients, maxHistory: cfg.maxHistory } : void 0);
+      }
+      async handleClientSignalWrite(request) {
+        const cfg = this.options.config?.signalStream;
+        return writeSignalFromClient(request, { clientWrites: cfg?.clientWrites });
       }
       /**
        * PPR hole fill: render the page fresh and return only the requested
@@ -54475,15 +55168,33 @@ var init_tw6 = __esm({
             controller.close();
           }
         });
-        return new Response(stream, {
+        const streamRes = new Response(stream, {
           status: 200,
           headers: { "Content-Type": "text/html; charset=utf-8" }
         });
+        streamRes.__twRawStream = true;
+        return streamRes;
       }
       async handleRequestInner(request) {
         const url = new URL(request.url);
         const method = request.method;
-        const pathname = normalizePathname(url.pathname);
+        let rawPath = url.pathname;
+        try {
+          const decoded = decodeURIComponent(rawPath);
+          if (decoded !== rawPath) rawPath = decoded;
+        } catch {
+        }
+        let canonical = normalizePathname(rawPath);
+        if (canonical.length > 1 && canonical.endsWith("/")) {
+          canonical = canonical.slice(0, -1);
+        }
+        if (canonical !== rawPath) {
+          return new Response(null, {
+            status: 308,
+            headers: { Location: encodeURI(canonical) + url.search }
+          });
+        }
+        const pathname = canonical;
         if (pathname === "/_tw/img" || pathname.startsWith("/_tw/img/")) {
           const imgRes = await this.imageHandler.handle(request);
           if (imgRes) return imgRes;
@@ -54491,6 +55202,9 @@ var init_tw6 = __esm({
         if (pathname === "/_tw/stream") {
           return this.handleSignalStream(request, url);
         }
+        if (pathname === "/_tw/signal" && method === "POST") {
+          return this.handleClientSignalWrite(request);
+        }
         if (pathname === "/_tw/ppr") {
           return this.handlePPRHoleFill(url);
         }
@@ -54655,11 +55369,37 @@ __export(twm_loader_exports, {
   loadTWMModule: () => loadTWMModule,
   revalidateRoute: () => revalidateRoute,
   shouldMatchMiddleware: () => shouldMatchMiddleware,
-  stripCommentsSafe: () => stripCommentsSafe
+  stripCommentsSafe: () => stripCommentsSafe,
+  validateTWMSyntax: () => validateTWMSyntax
 });
 function clearTWMCache() {
   moduleCache.clear();
 }
+function validateTWMSyntax(filePath) {
+  let source;
+  try {
+    source = (0, import_node_fs12.readFileSync)(filePath, "utf-8");
+  } catch (err3) {
+    return "cannot read: " + (err3?.message ?? err3);
+  }
+  if (isRuleDsl(source)) {
+    try {
+      parseRules(source, filePath);
+      return null;
+    } catch (err3) {
+      return "rule DSL: " + (err3?.message ?? String(err3));
+    }
+  }
+  try {
+    const imports = extractImports(source);
+    const jsCode = compileTwm(source);
+    const codeWithoutImports = stripImports(jsCode);
+    new Function("__tw_unused", codeWithoutImports);
+    return null;
+  } catch (err3) {
+    return (err3?.message ?? String(err3)).replace(/\n/g, " ").slice(0, 200);
+  }
+}
 function stripCommentsSafe(src) {
   let out = "";
   let i = 0;
@@ -54897,7 +55637,7 @@ async function loadTWMModule(filePath, rootDir) {
       console.error("[tw] " + e.message + " (" + filePath + ":" + cm[1] + ")");
     }
   }
-  const moduleCode = codeWithoutImports + "\nreturn { get: typeof get !== 'undefined' ? get : null, post: typeof post !== 'undefined' ? post : null, put: typeof put !== 'undefined' ? put : null, patch: typeof patch !== 'undefined' ? patch : null, deleteFn: typeof deleteFn !== 'undefined' ? deleteFn : null, GET: typeof GET !== 'undefined' ? GET : null, POST: typeof POST !== 'undefined' ? POST : null, PUT: typeof PUT !== 'undefined' ? PUT : null, PATCH: typeof PATCH !== 'undefined' ? PATCH : null, DELETE: typeof DELETE !== 'undefined' ? DELETE : null, middleware: typeof middleware !== 'undefined' ? middleware : null, generate: typeof generate !== 'undefined' ? generate : null, config: typeof config !== 'undefined' ? config : null, action: typeof action !== 'undefined' ? action : null, revalidate: typeof revalidate !== 'undefined' ? revalidate : null, " + [...actionNames].map((n) => `${n}: typeof ${n} !== 'undefined' ? ${n} : null`).join(", ") + " };";
+  const moduleCode = codeWithoutImports + "\nreturn { get: typeof get !== 'undefined' ? get : null, post: typeof post !== 'undefined' ? post : null, put: typeof put !== 'undefined' ? put : null, patch: typeof patch !== 'undefined' ? patch : null, deleteFn: typeof deleteFn !== 'undefined' ? deleteFn : null, GET: typeof GET !== 'undefined' ? GET : null, POST: typeof POST !== 'undefined' ? POST : null, PUT: typeof PUT !== 'undefined' ? PUT : null, PATCH: typeof PATCH !== 'undefined' ? PATCH : null, DELETE: typeof DELETE !== 'undefined' ? DELETE : null, options: typeof options !== 'undefined' ? options : null, OPTIONS: typeof OPTIONS !== 'undefined' ? OPTIONS : null, middleware: typeof middleware !== 'undefined' ? middleware : null, generate: typeof generate !== 'undefined' ? generate : null, config: typeof config !== 'undefined' ? config : null, action: typeof action !== 'undefined' ? action : null, revalidate: typeof revalidate !== 'undefined' ? revalidate : null, " + [...actionNames].map((n) => `${n}: typeof ${n} !== 'undefined' ? ${n} : null`).join(", ") + " };";
   const injectedKeys = Object.keys(injected);
   let module2 = {};
   try {
@@ -54912,6 +55652,8 @@ async function loadTWMModule(filePath, rootDir) {
       put: H.put || H.PUT || void 0,
       delete: H.deleteFn || H.DELETE || void 0,
       patch: H.patch || H.PATCH || void 0,
+      // v1.0.8 round 4 (BUG 33): route-level OPTIONS handlers
+      options: H.options || H.OPTIONS || void 0,
       middleware: H.middleware || void 0,
       generate: H.generate || void 0,
       config: H.config || void 0,
@@ -55047,9 +55789,22 @@ async function executeRouteHandler(filePath, method, request, rootDir) {
       if (rawBody2.length > MAX_BODY_BYTES) {
         return { status: 413, json: { ok: false, error: "Payload too large" } };
       }
-      parsedBody = rawBody2 ? JSON.parse(rawBody2) : {};
+      if (!rawBody2) {
+        parsedBody = {};
+      } else if (__ct.includes("application/x-www-form-urlencoded")) {
+        parsedBody = Object.fromEntries(new URLSearchParams(rawBody2).entries());
+      } else if (__ct.startsWith("text/")) {
+        parsedBody = rawBody2;
+      } else if (__ct.includes("json") || __ct === "") {
+        try {
+          parsedBody = JSON.parse(rawBody2);
+        } catch (e) {
+          return { status: 400, json: { ok: false, error: "Invalid JSON body: " + (e?.message ?? "parse error") } };
+        }
+      } else {
+        return { status: 415, json: { ok: false, error: "Unsupported Content-Type: " + (__ct || "(none)") } };
+      }
     } catch {
-      parsedBody = {};
     }
   } else if (request?.body && typeof request.body === "object") {
     parsedBody = request.body;
@@ -55057,7 +55812,18 @@ async function executeRouteHandler(filePath, method, request, rootDir) {
   let query2 = {};
   try {
     const u = new URL(request.url);
-    query2 = Object.fromEntries(u.searchParams.entries());
+    for (const [rawKey, value] of u.searchParams.entries()) {
+      const isPhpArray = rawKey.endsWith("[]");
+      const key = isPhpArray ? rawKey.slice(0, -2) : rawKey;
+      const existing = query2[key];
+      if (existing === void 0) {
+        query2[key] = isPhpArray ? [value] : value;
+      } else if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        query2[key] = [existing, value];
+      }
+    }
   } catch {
   }
   const headersObj = typeof request.headers?.entries === "function" ? Object.fromEntries(request.headers.entries()) : request.headers ?? {};
@@ -55186,9 +55952,17 @@ async function executeRouteHandler(filePath, method, request, rootDir) {
     console.error("[tw] route handler error (" + filePath + "):", err3?.message ?? err3);
     return { status: 500, json: { ok: false, error: "Internal Server Error" } };
   }
-  if (!result || typeof result !== "object") {
-    console.error("[tw] route handler returned no result (" + filePath + ")");
-    return { status: 500, json: { ok: false, error: "Internal Server Error" } };
+  if (typeof result === "string") {
+    result = { status: 200, text: result };
+  } else if (!result || typeof result !== "object") {
+    console.error("[tw] route handler returned " + JSON.stringify(result) + " (" + filePath + ")");
+    return {
+      status: 500,
+      json: {
+        ok: false,
+        error: "Unsupported handler return shape: " + (result === null ? "null" : typeof result) + ". Return { status, json|text|html } (or a plain string for text/plain)."
+      }
+    };
   }
   const finalResult = {
     status: typeof result.status === "number" ? result.status : 200,