@nanobpm/urban 0.45.1 → 0.47.0

package/dist/runtime/adapters/node.js

@@ -229,11 +229,33 @@ async function startNodeServer(port, handler) {
             nres.end(String(err));
         }
     });
+    // Track every raw TCP socket so `stop()` can force teardown. `server.close()` only
+    // stops accepting new connections and waits for existing ones to end; a lingering
+    // long-lived socket would keep it pending forever and hang `app.stop()`. Now that we
+    // expose `native` for same-port WebSocket upgrades, that is a real risk — and
+    // `server.closeAllConnections()` does NOT cover sockets that have already been
+    // upgraded (they are detached from the server's HTTP connection tracking after the
+    // `upgrade` event). The underlying TCP socket from the `connection` event is the same
+    // object that a later upgrade reuses, so destroying those is what actually unblocks
+    // shutdown regardless of what an upgrade handler left open. Attach the listener
+    // BEFORE `listen()` so no connection can slip through untracked in the window between
+    // the server accepting sockets and the tracker being wired up.
+    const sockets = new Set();
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    });
     await new Promise((res) => server.listen(port, res));
     const addr = server.address();
     const actualPort = typeof addr === "object" && addr ? addr.port : port;
     return {
         port: actualPort,
-        stop: () => new Promise((res) => server.close(() => res())),
+        stop: () => new Promise((res) => {
+            server.close(() => res());
+            for (const socket of sockets)
+                socket.destroy();
+            sockets.clear();
+        }),
+        native: server,
     };
 }

package/dist/runtime/core/host.d.ts

@@ -20,6 +20,16 @@ export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse> | HttpResp
 export interface HttpServer {
     readonly port: number;
     stop(): Promise<void>;
+    /**
+     * The host's native server object, when it exposes one — the Node adapter's `node:http` `Server`.
+     * Lets an app attach a WebSocket upgrade (e.g. `ws`'s `WebSocketServer({ server })`) to the *same*
+     * port the app already serves. `undefined` on hosts that don't surface an upgradeable server object
+     * (the Deno adapter, whose WS story is `upgradeWebSocket` on the Deno global in the request
+     * handler). Typed
+     * `unknown` because this is the host-adapter boundary — the consumer narrows it with a runtime
+     * check (e.g. `instanceof Server`) before use, rather than a type assertion.
+     */
+    readonly native?: unknown;
 }
 /** A handle to an active filesystem watch; call close() to stop watching. */
 export interface WatchHandle {

package/dist/runtime/core/modules/pages.js

@@ -482,14 +482,21 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
 .pc-msg.err { color:var(--nano-danger); }
 .pc-msg.ok { color:var(--nano-ok); }
-table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; }
-/* Wrap long, space-less cell values (e.g. a JSON blob or a 40-char SHA) so one
-   cell can't force its column wide and blow the whole table past the page.
-   overflow-wrap:anywhere reduces the cell's min-content width so the auto table
-   layout can shrink it to fit; max-width caps a single column when there is
-   ample room. vertical-align:top keeps a multi-line cell aligned with its
-   single-line neighbours. */
-table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; max-width:32rem; vertical-align:top; }
+.pc-req { color:var(--nano-danger); font-weight:600; }
+.pc-field-err { font-size:.75rem; color:var(--nano-danger); margin:.1rem 0 0; }
+.pc-field-err:empty { display:none; }
+.pc-field input.pc-invalid, .pc-field-check input.pc-invalid { border-color:var(--nano-danger); outline-color:var(--nano-danger); }
+table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-layout:fixed; }
+/* table-layout:fixed divides the available width across columns and wraps text
+   within each, so a grid with several long free-text columns (e.g. the epic
+   detail's coordination-notes / trial-merge-results) can't sum its columns'
+   content widths past the page — the failure mode of table-layout:auto, where a
+   per-cell max-width let two wide columns each claim ~32rem and overrun the page.
+   overflow-wrap:anywhere additionally breaks space-less tokens (a 40-char SHA, a
+   JSON blob) so they wrap inside the column instead of forcing a scrollbar.
+   vertical-align:top keeps a multi-line cell aligned with its single-line
+   neighbours. */
+table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; vertical-align:top; }
 table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-tabs { display:flex; gap:.5rem; margin-bottom:.75rem; }
 .pc-tab { padding:.35rem .8rem; border:1px solid var(--nano-edge); border-radius:.4rem; background:transparent; color:inherit; font:inherit; cursor:pointer; }
@@ -1028,9 +1035,38 @@ function renderActionForm(node) {
   // pollute Object.prototype or shadow inherited props (prototype-pollution class).
   const inputs = new Map();
   const fieldTypes = new Map();
+  // Client-side required-field validation state: the set of required keys, each
+  // field's custom message, and its inline error node (populated on a blocked
+  // submit, cleared as soon as the user edits the field).
+  const required = new Set();
+  const reqMsg = new Map();
+  const errs = new Map();
+  // A required field's label carries a danger-toned "*" so the requirement is
+  // visible BEFORE submit; spread into el(...) — an empty array adds no child.
+  const reqMark = (f) => (f.required === true ? [el("span", { class: "pc-req", title: "Required" }, " *")] : []);
+  // Register a field's inline error node and, when required, mark the input
+  // (aria-required) and wire a clear-on-edit handler so a hint disappears the
+  // moment the user starts fixing it. Editing a required field also clears the
+  // blocked-submit summary ("Please fill in the required fields.") so it never
+  // lingers as a stale/misleading banner while the user is correcting input.
+  const wireField = (f, input, ferr, evt) => {
+    errs.set(f.key, ferr);
+    if (f.required !== true) return;
+    required.add(f.key);
+    if (typeof f.requiredMessage === "string" && f.requiredMessage !== "") reqMsg.set(f.key, f.requiredMessage);
+    input.setAttribute("aria-required", "true");
+    input.addEventListener(evt, () => {
+      input.classList.remove("pc-invalid");
+      input.removeAttribute("aria-invalid");
+      ferr.textContent = "";
+      msg.textContent = "";
+      msg.className = "pc-msg";
+    });
+  };
   for (const f of p.fields || []) {
     const kind = f.type === "checkbox" ? "checkbox" : (f.type === "number" ? "number" : "text");
     fieldTypes.set(f.key, kind);
+    const ferr = el("p", { class: "pc-field-err" });
     if (kind === "checkbox") {
       // A boolean field renders a real checkbox; its default checked state comes
       // from default/checked on the field (unset -> unchecked). We record that on
@@ -1041,9 +1077,10 @@ function renderActionForm(node) {
       input.defaultChecked = checked;
       input.checked = checked;
       inputs.set(f.key, input);
+      wireField(f, input, ferr, "change");
       // Input-first, wrapped in the label so the whole row is a click target.
       card.append(
-        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key))),
+        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key), ...reqMark(f)), ferr),
       );
       continue;
     }
@@ -1056,11 +1093,43 @@ function renderActionForm(node) {
     }
     const input = el("input", attrs);
     inputs.set(f.key, input);
-    card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key), input));
+    wireField(f, input, ferr, "input");
+    card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key, ...reqMark(f)), input, ferr));
   }
   const msg = el("p", { class: "pc-msg" });
   const btn = el("button", { class: "pc-btn" }, p.submitLabel || "Submit");
   btn.addEventListener("click", async () => {
+    // Required-field gate: block the submit and surface an inline hint on each
+    // empty required field (a text/number left blank, a required checkbox left
+    // unchecked), focusing the first offender — so a missing value never
+    // round-trips to the server only to bounce back as a generic error.
+    let firstInvalid = null;
+    for (const [k, input] of inputs) {
+      const ferr = errs.get(k);
+      if (ferr) ferr.textContent = "";
+      input.classList.remove("pc-invalid");
+      input.removeAttribute("aria-invalid");
+      if (!required.has(k)) continue;
+      const type = fieldTypes.get(k);
+      const val = String(input.value).trim();
+      const missing = type === "checkbox"
+        ? input.checked !== true
+        : type === "number"
+          ? (val === "" || !Number.isFinite(Number(val)))
+          : val === "";
+      if (missing) {
+        if (ferr) ferr.textContent = reqMsg.get(k) || "Required";
+        input.classList.add("pc-invalid");
+        input.setAttribute("aria-invalid", "true");
+        if (!firstInvalid) firstInvalid = input;
+      }
+    }
+    if (firstInvalid) {
+      msg.className = "pc-msg err";
+      msg.textContent = "Please fill in the required fields.";
+      firstInvalid.focus();
+      return;
+    }
     const variables = Object.create(null);
     for (const [k, input] of inputs) {
       if (fieldTypes.get(k) === "checkbox") {

package/dist/runtime/core/runtime.d.ts

@@ -65,5 +65,14 @@ export interface UrbanApp {
     readonly data: DataLayer | undefined;
     readonly security: SecurityPolicy | undefined;
     readonly httpPort: number | undefined;
+    /**
+     * The runtime's native HTTP server object once `start()` has bound it (the Node adapter's
+     * `node:http` `Server`), for attaching a WebSocket upgrade on the app's *own* port. Snapshot it
+     * into a local `const` and narrow that with a runtime `instanceof` check before use (no type
+     * assertion needed) — reading the property again after the check would not narrow — e.g.
+     * `const { Server } = await import("node:http"); const server = app.httpServer; if (server instanceof Server) new WebSocketServer({ server, path: "/agentic" });`.
+     * `undefined` before `start()`, after `stop()`, and on hosts that don't surface one (Deno).
+     */
+    readonly httpServer: object | undefined;
 }
 export declare function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp>;

package/dist/runtime/core/runtime.js

@@ -114,6 +114,10 @@ export async function createUrbanApp(opts) {
         get httpPort() {
             return httpPort;
         },
+        get httpServer() {
+            const native = server?.native;
+            return typeof native === "object" && native !== null ? native : undefined;
+        },
         async start() {
             if (started)
                 throw new Error("app already started");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.45.1",
+	"version": "0.47.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/adapters/node.ts

@@ -5,6 +5,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
+import type { Socket } from "node:net";
 import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -246,11 +247,33 @@ async function startNodeServer(port: number, handler: HttpHandler): Promise<Http
       nres.end(String(err));
     }
   });
+  // Track every raw TCP socket so `stop()` can force teardown. `server.close()` only
+  // stops accepting new connections and waits for existing ones to end; a lingering
+  // long-lived socket would keep it pending forever and hang `app.stop()`. Now that we
+  // expose `native` for same-port WebSocket upgrades, that is a real risk — and
+  // `server.closeAllConnections()` does NOT cover sockets that have already been
+  // upgraded (they are detached from the server's HTTP connection tracking after the
+  // `upgrade` event). The underlying TCP socket from the `connection` event is the same
+  // object that a later upgrade reuses, so destroying those is what actually unblocks
+  // shutdown regardless of what an upgrade handler left open. Attach the listener
+  // BEFORE `listen()` so no connection can slip through untracked in the window between
+  // the server accepting sockets and the tracker being wired up.
+  const sockets = new Set<Socket>();
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+  });
   await new Promise<void>((res) => server.listen(port, res));
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : port;
   return {
     port: actualPort,
-    stop: () => new Promise<void>((res) => server.close(() => res())),
+    stop: () =>
+      new Promise<void>((res) => {
+        server.close(() => res());
+        for (const socket of sockets) socket.destroy();
+        sockets.clear();
+      }),
+    native: server,
   };
 }

package/src/runtime/core/host.ts

@@ -28,6 +28,16 @@ export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse> | HttpResp
 export interface HttpServer {
   readonly port: number;
   stop(): Promise<void>;
+  /**
+   * The host's native server object, when it exposes one — the Node adapter's `node:http` `Server`.
+   * Lets an app attach a WebSocket upgrade (e.g. `ws`'s `WebSocketServer({ server })`) to the *same*
+   * port the app already serves. `undefined` on hosts that don't surface an upgradeable server object
+   * (the Deno adapter, whose WS story is `upgradeWebSocket` on the Deno global in the request
+   * handler). Typed
+   * `unknown` because this is the host-adapter boundary — the consumer narrows it with a runtime
+   * check (e.g. `instanceof Server`) before use, rather than a type assertion.
+   */
+  readonly native?: unknown;
 }
 
 /** A handle to an active filesystem watch; call close() to stop watching. */

package/src/runtime/core/modules/pages.test.ts

@@ -154,18 +154,25 @@ test("the warn badge stays legible in light appearance", async () => {
   );
 });
 
-test("grid cells wrap long, space-less values so one cell can't overflow the table", async () => {
-  // Regression: a dataGrid cell holding a long space-less value (e.g. a JSON
-  // blob or a 40-char SHA) has no soft-wrap opportunity, so with table-layout
-  // auto it forces its column to the value's full width and pushes the whole
-  // table past the page. The shared grid CSS must let such a cell break so the
-  // column can shrink to fit its container.
+test("grid uses fixed layout + wrapping so several wide columns can't overflow the page", async () => {
+  // Regression: with table-layout:auto a per-cell max-width let two long
+  // free-text columns (e.g. the epic detail's coordination-notes files+note, or
+  // trial-merge-results heads+conflicts+failing+summary) each claim ~32rem, and
+  // their summed content widths overran the page's width regardless of the
+  // viewport. table-layout:fixed divides the width across columns and wraps text
+  // within each; overflow-wrap:anywhere still breaks space-less tokens (a 40-char
+  // SHA, a JSON blob) inside the column instead of forcing a horizontal scrollbar.
   const res = await dispatch("GET", "/");
   const html = res.body ?? "";
-  const rule = (html.match(/table\.pc-grid th,\s*table\.pc-grid td\s*\{[^}]*\}/) ?? [""])[0];
-  assert.ok(rule, "grid th/td rule must be present");
-  assert.match(rule, /overflow-wrap:anywhere/);
-  assert.match(rule, /max-width:/);
+  const tableRule = (html.match(/table\.pc-grid\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(tableRule, "table.pc-grid rule must be present");
+  assert.match(tableRule, /table-layout:\s*fixed/);
+  const cellRule = (html.match(/table\.pc-grid th,\s*table\.pc-grid td\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(cellRule, "grid th/td rule must be present");
+  assert.match(cellRule, /overflow-wrap:anywhere/);
+  // The per-cell max-width cap was the root cause of the overflow: guard against
+  // any future change silently reintroducing it (which would pass the checks above).
+  assert.doesNotMatch(cellRule, /max-width:/);
 });
 
 test("GET /app/runtime.js serves the renderer module", async () => {
@@ -495,6 +502,48 @@ test("the renderer honours boolean (checkbox) actionForm fields", async () => {
   assert.match(js, /input\.checked = input\.defaultChecked;/);
 });
 
+test("the renderer enforces required actionForm fields client-side, blocking submit with an inline hint", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A field declared `required: true` is tracked in a Set and given an inline
+  // error node; the label carries a danger-toned "*" marker before submit.
+  assert.match(js, /required\.add\(f\.key\)/);
+  assert.match(js, /reqMark = \(f\) =>/);
+  assert.match(js, /class: "pc-req"/);
+  // The input is marked aria-required, and a clear-on-edit handler wipes the hint
+  // the moment the user starts fixing the field (input for text/number, change for
+  // a checkbox).
+  assert.match(js, /input\.setAttribute\("aria-required", "true"\)/);
+  assert.match(js, /wireField\(f, input, ferr, "input"\)/);
+  assert.match(js, /wireField\(f, input, ferr, "change"\)/);
+  // Submit is GATED: an empty required text/number or an unchecked required
+  // checkbox is "missing"; the first offender is focused and the submit RETURNS
+  // early (never round-trips to the server).
+  assert.match(js, /input\.checked !== true/);
+  assert.match(js, /!Number\.isFinite\(Number\(val\)\)/);
+  assert.match(js, /if \(firstInvalid\)/);
+  assert.match(js, /Please fill in the required fields\./);
+  assert.match(js, /firstInvalid\.focus\(\)/);
+  assert.match(js, /input\.classList\.add\("pc-invalid"\)/);
+  // Editing a required field after a blocked submit clears the summary banner too,
+  // so "Please fill in the required fields." never lingers stale while correcting.
+  assert.match(js, /msg\.textContent = "";\s*\n\s*msg\.className = "pc-msg";/);
+  // A per-field custom message (`requiredMessage`) overrides the default "Required".
+  assert.match(js, /reqMsg\.get\(k\) \|\| "Required"/);
+  assert.match(js, /f\.requiredMessage/);
+});
+
+test("the shell styles required-field markers and inline field errors", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  // The "*" required marker and the inline per-field error both resolve through
+  // the shared danger token, and an empty error node collapses (no reserved gap).
+  assert.match(html, /\.pc-req \{ color:var\(--nano-danger\)/);
+  assert.match(html, /\.pc-field-err \{ font-size:.75rem; color:var\(--nano-danger\)/);
+  assert.match(html, /\.pc-field-err:empty \{ display:none; \}/);
+  assert.match(html, /input\.pc-invalid/);
+});
+
 test("renderer makes collapsible nodes persist their state across sessions", async () => {
   // A node with `collapsible` gets a clickable header that hides/shows the card
   // body, and the collapsed state is written to localStorage keyed by the home

package/src/runtime/core/modules/pages.ts

@@ -533,14 +533,21 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
 .pc-msg.err { color:var(--nano-danger); }
 .pc-msg.ok { color:var(--nano-ok); }
-table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; }
-/* Wrap long, space-less cell values (e.g. a JSON blob or a 40-char SHA) so one
-   cell can't force its column wide and blow the whole table past the page.
-   overflow-wrap:anywhere reduces the cell's min-content width so the auto table
-   layout can shrink it to fit; max-width caps a single column when there is
-   ample room. vertical-align:top keeps a multi-line cell aligned with its
-   single-line neighbours. */
-table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; max-width:32rem; vertical-align:top; }
+.pc-req { color:var(--nano-danger); font-weight:600; }
+.pc-field-err { font-size:.75rem; color:var(--nano-danger); margin:.1rem 0 0; }
+.pc-field-err:empty { display:none; }
+.pc-field input.pc-invalid, .pc-field-check input.pc-invalid { border-color:var(--nano-danger); outline-color:var(--nano-danger); }
+table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-layout:fixed; }
+/* table-layout:fixed divides the available width across columns and wraps text
+   within each, so a grid with several long free-text columns (e.g. the epic
+   detail's coordination-notes / trial-merge-results) can't sum its columns'
+   content widths past the page — the failure mode of table-layout:auto, where a
+   per-cell max-width let two wide columns each claim ~32rem and overrun the page.
+   overflow-wrap:anywhere additionally breaks space-less tokens (a 40-char SHA, a
+   JSON blob) so they wrap inside the column instead of forcing a scrollbar.
+   vertical-align:top keeps a multi-line cell aligned with its single-line
+   neighbours. */
+table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; vertical-align:top; }
 table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-tabs { display:flex; gap:.5rem; margin-bottom:.75rem; }
 .pc-tab { padding:.35rem .8rem; border:1px solid var(--nano-edge); border-radius:.4rem; background:transparent; color:inherit; font:inherit; cursor:pointer; }
@@ -1080,9 +1087,38 @@ function renderActionForm(node) {
   // pollute Object.prototype or shadow inherited props (prototype-pollution class).
   const inputs = new Map();
   const fieldTypes = new Map();
+  // Client-side required-field validation state: the set of required keys, each
+  // field's custom message, and its inline error node (populated on a blocked
+  // submit, cleared as soon as the user edits the field).
+  const required = new Set();
+  const reqMsg = new Map();
+  const errs = new Map();
+  // A required field's label carries a danger-toned "*" so the requirement is
+  // visible BEFORE submit; spread into el(...) — an empty array adds no child.
+  const reqMark = (f) => (f.required === true ? [el("span", { class: "pc-req", title: "Required" }, " *")] : []);
+  // Register a field's inline error node and, when required, mark the input
+  // (aria-required) and wire a clear-on-edit handler so a hint disappears the
+  // moment the user starts fixing it. Editing a required field also clears the
+  // blocked-submit summary ("Please fill in the required fields.") so it never
+  // lingers as a stale/misleading banner while the user is correcting input.
+  const wireField = (f, input, ferr, evt) => {
+    errs.set(f.key, ferr);
+    if (f.required !== true) return;
+    required.add(f.key);
+    if (typeof f.requiredMessage === "string" && f.requiredMessage !== "") reqMsg.set(f.key, f.requiredMessage);
+    input.setAttribute("aria-required", "true");
+    input.addEventListener(evt, () => {
+      input.classList.remove("pc-invalid");
+      input.removeAttribute("aria-invalid");
+      ferr.textContent = "";
+      msg.textContent = "";
+      msg.className = "pc-msg";
+    });
+  };
   for (const f of p.fields || []) {
     const kind = f.type === "checkbox" ? "checkbox" : (f.type === "number" ? "number" : "text");
     fieldTypes.set(f.key, kind);
+    const ferr = el("p", { class: "pc-field-err" });
     if (kind === "checkbox") {
       // A boolean field renders a real checkbox; its default checked state comes
       // from default/checked on the field (unset -> unchecked). We record that on
@@ -1093,9 +1129,10 @@ function renderActionForm(node) {
       input.defaultChecked = checked;
       input.checked = checked;
       inputs.set(f.key, input);
+      wireField(f, input, ferr, "change");
       // Input-first, wrapped in the label so the whole row is a click target.
       card.append(
-        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key))),
+        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key), ...reqMark(f)), ferr),
       );
       continue;
     }
@@ -1108,11 +1145,43 @@ function renderActionForm(node) {
     }
     const input = el("input", attrs);
     inputs.set(f.key, input);
-    card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key), input));
+    wireField(f, input, ferr, "input");
+    card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key, ...reqMark(f)), input, ferr));
   }
   const msg = el("p", { class: "pc-msg" });
   const btn = el("button", { class: "pc-btn" }, p.submitLabel || "Submit");
   btn.addEventListener("click", async () => {
+    // Required-field gate: block the submit and surface an inline hint on each
+    // empty required field (a text/number left blank, a required checkbox left
+    // unchecked), focusing the first offender — so a missing value never
+    // round-trips to the server only to bounce back as a generic error.
+    let firstInvalid = null;
+    for (const [k, input] of inputs) {
+      const ferr = errs.get(k);
+      if (ferr) ferr.textContent = "";
+      input.classList.remove("pc-invalid");
+      input.removeAttribute("aria-invalid");
+      if (!required.has(k)) continue;
+      const type = fieldTypes.get(k);
+      const val = String(input.value).trim();
+      const missing = type === "checkbox"
+        ? input.checked !== true
+        : type === "number"
+          ? (val === "" || !Number.isFinite(Number(val)))
+          : val === "";
+      if (missing) {
+        if (ferr) ferr.textContent = reqMsg.get(k) || "Required";
+        input.classList.add("pc-invalid");
+        input.setAttribute("aria-invalid", "true");
+        if (!firstInvalid) firstInvalid = input;
+      }
+    }
+    if (firstInvalid) {
+      msg.className = "pc-msg err";
+      msg.textContent = "Please fill in the required fields.";
+      firstInvalid.focus();
+      return;
+    }
     const variables = Object.create(null);
     for (const [k, input] of inputs) {
       if (fieldTypes.get(k) === "checkbox") {

package/src/runtime/core/runtime.test.ts

@@ -1,5 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import * as http from "node:http";
 import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -226,6 +227,145 @@ test("app.sdk is undefined when the engine exposes no SDK client", async () => {
   }
 });
 
+test("exposes the native http server for a same-port WebSocket upgrade", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+
+  // undefined before start
+  const httpServerBeforeStart = app.httpServer;
+  assert.equal(httpServerBeforeStart, undefined);
+
+  await app.start();
+  try {
+    // the live node:http Server, on the app's own port — narrow the getter's `object | undefined`
+    // to a concrete server with runtime checks (no type assertion needed).
+    const server = app.httpServer;
+    if (server === undefined) throw new Error("httpServer should be defined after start");
+    assert.ok(server instanceof http.Server, "httpServer is a node:http Server after start");
+
+    // an attached 'upgrade' handler completes a WebSocket handshake on the app's port —
+    // exactly what @nanobpm/agentic's WebSocketChannelTransport({ server }) needs.
+    server.on("upgrade", (_req, socket) => {
+      socket.write(
+        "HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n",
+      );
+      socket.destroy();
+    });
+
+    const upgraded = await new Promise<boolean>((resolve, reject) => {
+      const req = http.request({
+        port: app.httpPort!,
+        path: "/agentic",
+        headers: { Connection: "Upgrade", Upgrade: "websocket" },
+      });
+      // fail fast rather than hang the runner if the handshake never happens
+      const timer = setTimeout(() => {
+        req.destroy();
+        reject(new Error("upgrade handshake timed out"));
+      }, 5000);
+      req.on("upgrade", (_res, socket) => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(true);
+      });
+      // a plain HTTP response means the server did NOT upgrade — surface it clearly
+      req.on("response", (res) => {
+        clearTimeout(timer);
+        res.resume();
+        req.destroy();
+        reject(new Error(`expected upgrade, got HTTP ${res.statusCode}`));
+      });
+      req.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+      req.end();
+    });
+    assert.equal(upgraded, true, "upgrade handshake completed on the app port");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+
+  // undefined again after stop
+  assert.equal(app.httpServer, undefined);
+});
+
+test("stop() completes promptly even with a lingering upgraded socket", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+
+  await app.start();
+  const openSockets: import("node:stream").Duplex[] = [];
+  try {
+    const server = app.httpServer;
+    if (server === undefined) throw new Error("httpServer should be defined after start");
+    assert.ok(server instanceof http.Server, "httpServer is a node:http Server after start");
+
+    // Complete the handshake but deliberately KEEP the upgraded socket open on both
+    // ends — this is exactly the long-lived WebSocket case that would make a plain
+    // `server.close()` hang forever.
+    server.on("upgrade", (_req, socket) => {
+      openSockets.push(socket);
+      socket.write(
+        "HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n",
+      );
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      const req = http.request({
+        port: app.httpPort!,
+        path: "/agentic",
+        headers: { Connection: "Upgrade", Upgrade: "websocket" },
+      });
+      const timer = setTimeout(() => {
+        req.destroy();
+        reject(new Error("upgrade handshake timed out"));
+      }, 5000);
+      req.on("upgrade", (_res, socket) => {
+        clearTimeout(timer);
+        openSockets.push(socket);
+        resolve();
+      });
+      req.on("response", (res) => {
+        clearTimeout(timer);
+        res.resume();
+        req.destroy();
+        reject(new Error(`expected upgrade, got HTTP ${res.statusCode}`));
+      });
+      req.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+      req.end();
+    });
+
+    // stop() must resolve without waiting on the still-open upgraded socket.
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("app.stop() hung on an open upgraded socket")), 5000);
+      app.stop().then(
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+      );
+    });
+
+    assert.equal(app.httpServer, undefined, "httpServer is undefined after stop");
+  } finally {
+    for (const s of openSockets) s.destroy();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("stop() resets state so the app can be cleanly restarted", async () => {
   const dir = await makeFixture();
   const host = createNodeHost({ cwd: dir, log: () => {} });

package/src/runtime/core/runtime.ts

@@ -108,6 +108,15 @@ export interface UrbanApp {
   readonly data: DataLayer | undefined;
   readonly security: SecurityPolicy | undefined;
   readonly httpPort: number | undefined;
+  /**
+   * The runtime's native HTTP server object once `start()` has bound it (the Node adapter's
+   * `node:http` `Server`), for attaching a WebSocket upgrade on the app's *own* port. Snapshot it
+   * into a local `const` and narrow that with a runtime `instanceof` check before use (no type
+   * assertion needed) — reading the property again after the check would not narrow — e.g.
+   * `const { Server } = await import("node:http"); const server = app.httpServer; if (server instanceof Server) new WebSocketServer({ server, path: "/agentic" });`.
+   * `undefined` before `start()`, after `stop()`, and on hosts that don't surface one (Deno).
+   */
+  readonly httpServer: object | undefined;
 }
 
 export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp> {
@@ -193,6 +202,10 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     get httpPort() {
       return httpPort;
     },
+    get httpServer(): object | undefined {
+      const native = server?.native;
+      return typeof native === "object" && native !== null ? native : undefined;
+    },
 
     async start() {
       if (started) throw new Error("app already started");

package/src/runtime/devserver.test.ts

@@ -231,6 +231,7 @@ function fakeApp(stops: string[], id: string): UrbanApp {
     data: undefined,
     security: undefined,
     httpPort: undefined,
+    httpServer: undefined,
   };
 }