@nanobpm/urban 0.90.2 → 0.92.0

package/dist/runtime/engine/nanosdk.js

@@ -640,9 +640,10 @@ export class SdkEngineClient {
     }
     async searchElementInstanceWaitStates(filter) {
         // The wait-states search surfaces the parks the deployed engine's read model serves.
-        // A `waitStateType` selector outside the deployed floor (`JOB | MESSAGE`) is rejected by
-        // the gateway with HTTP 422; fail fast client-side with a clear error instead, so the
-        // divergence is caught offline and identically to the WASM adapter (No Drift Surfaces).
+        // A `waitStateType` selector outside the deployed floor (`JOB | MESSAGE | USER_TASK`) is
+        // rejected by the gateway with HTTP 422; fail fast client-side with a clear error instead,
+        // so the divergence is caught offline and identically to the WASM adapter (No Drift
+        // Surfaces).
         assertDeployedWaitStateType(filter?.waitStateType);
         // Same zero-wait read + per-row mapping-gate shape as `searchElementInstances`; the SDK
         // nests park-specific fields under `details`, which `mapElementInstanceWaitStateRow`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.90.2",
+	"version": "0.92.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/browser/runtime.browser.js

@@ -1955,9 +1955,17 @@ function buildEngineForm(cfg, row, onSuccess) {
   const formKey = row[cfg.formKeyField || "form_key"];
   const box = el("div", { class: "pc-subform" });
   const msg = el("p", { class: "njf-msg", role: "status", "aria-live": "polite" });
+  // Optional page-author knob: route completion through the app's own canonical
+  // door instead of the runtime's generic seam. Defaults to /app/actions/complete
+  // when unset (existing pages unchanged). Same trust class as detail.form's
+  // action.path; rebased through apiUrl() by getJSON like every other page fetch.
+  const completePath =
+    typeof cfg.completePath === "string" && cfg.completePath.trim() !== ""
+      ? cfg.completePath.trim()
+      : "/app/actions/complete";
   /** @param {Record<string, any>} variables */
   const complete = (variables) =>
-    getJSON("/app/actions/complete", {
+    getJSON(completePath, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ userTaskKey, variables }),

package/src/runtime/browser/runtime.engineform.test.ts

@@ -84,6 +84,7 @@ test("buildEngineForm resolves the row's formKey and completes with the entered
   assert.ok(input, "the deployed form-js schema was rendered by the shared renderer");
   input!.value = "done";
   const form = created.find((n) => n.tagName === "FORM");
+  assert.ok(form, "the deployed schema rendered a form element to submit");
   await form!.fire("submit");
   await new Promise((r) => setTimeout(r, 0));
   const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
@@ -116,6 +117,7 @@ test("buildEngineForm surfaces a completion failure in the rendered-form path",
   assert.ok(msg, "a failed completion is surfaced to the operator (not silent)");
   assert.notEqual(msg!.textContent, "", "the error message element has text");
   const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.ok(submit, "the completion path rendered a submit button");
   assert.equal(submit!.disabled, false, "the submit button is re-enabled so the operator can retry");
 });
 
@@ -156,3 +158,101 @@ test("buildEngineForm degrades to bare completion when the formKey resolves to n
   const button = created.find((n) => n.tagName === "BUTTON" && n.textContent === "Complete");
   assert.ok(button, "a 204 (no form) falls back to the bare completion button");
 });
+
+test("buildEngineForm routes the rendered-form completion through a configured completePath", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  const box = buildEngineForm(
+    { ...CFG, completePath: "/app/api/actions/complete-user-task" },
+    { form_key: "form-c", user_task_key: "ut-c" },
+    () => {},
+  );
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input, "the deployed form-js schema was rendered by the shared renderer");
+  input!.value = "done";
+  const form = created.find((n) => n.tagName === "FORM");
+  assert.ok(form, "the deployed schema rendered a form element to submit");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/api/actions/complete-user-task"));
+  assert.ok(completeReq, "completion POSTs to the configured completePath, not the generic seam");
+  assert.equal(completeReq!.method, "POST");
+  assert.deepEqual(completeReq!.body, { userTaskKey: "ut-c", variables: { note: "done" } });
+  assert.equal(
+    calls.some((c) => c.url.includes("/app/actions/complete")),
+    false,
+    "the generic seam is not called when completePath is set",
+  );
+});
+
+test("buildEngineForm routes the bare completion through a configured completePath", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(installFakeFetch(() => ({ status: 200, json: { ok: true } }), calls));
+  const box = buildEngineForm(
+    { ...CFG, completePath: "/app/custom-complete" },
+    { user_task_key: "ut-b" },
+    () => {},
+  );
+  assert.ok(box);
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(button, "the bare completion path rendered a Complete button");
+  await button!.fire("click");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/custom-complete"));
+  assert.ok(completeReq, "the bare button completes via the configured completePath");
+  assert.equal(completeReq!.body.userTaskKey, "ut-b");
+  assert.deepEqual(completeReq!.body.variables, {}, "bare completion sends empty variables");
+  assert.equal(
+    calls.some((c) => c.url.includes("/app/actions/complete")),
+    false,
+    "the generic seam is not called when completePath is set",
+  );
+});
+
+test("buildEngineForm falls back to the generic seam when completePath is empty/absent", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(installFakeFetch(() => ({ status: 200, json: { ok: true } }), calls));
+  // An empty-string completePath is treated as absent (default seam preserved).
+  const box = buildEngineForm({ ...CFG, completePath: "" }, { user_task_key: "ut-d" }, () => {});
+  assert.ok(box);
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(button, "the bare completion path rendered a Complete button");
+  await button!.fire("click");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "an empty completePath still targets the default /app/actions/complete seam");
+  assert.equal(completeReq!.body.userTaskKey, "ut-d");
+});
+
+test("buildEngineForm treats a whitespace-only completePath as absent", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(installFakeFetch(() => ({ status: 200, json: { ok: true } }), calls));
+  // A whitespace-only completePath is normalized away so it never becomes an
+  // unintended relative fetch target — the default seam is preserved.
+  const box = buildEngineForm({ ...CFG, completePath: "   " }, { user_task_key: "ut-e" }, () => {});
+  assert.ok(box);
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(button, "the bare completion path rendered a Complete button");
+  await button!.fire("click");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "a whitespace-only completePath still targets the default /app/actions/complete seam");
+  assert.equal(completeReq!.body.userTaskKey, "ut-e");
+});

package/src/runtime/core/host.ts

@@ -350,7 +350,9 @@ export interface ElementInstanceSummary {
  * {@link ElementInstanceWaitStateFilter} whose `waitStateType` falls outside that floor is
  * rejected (the gateway answers HTTP 422); {@link assertDeployedWaitStateType} enforces the
  * same floor client-side so the divergence surfaces as a clear error offline, in tests, and
- * against a live engine alike. Ref: Magikcraft/nano-bpm#1042.
+ * against a live engine alike. The floor now covers `JOB | MESSAGE | USER_TASK`
+ * (Magikcraft/nano-bpm#1042 shipped `USER_TASK` parks); `TIMER`/`SIGNAL`/`CONDITION` remain
+ * the follow-on. Ref: Magikcraft/nano-bpm#1042.
  */
 export type WaitStateType =
   | "JOB"
@@ -363,10 +365,12 @@ export type WaitStateType =
 /**
  * The `waitStateType` values the *currently deployed* nanobpmn gateway's wait-state read
  * model actually implements — the **deployed floor**, a strict subset of the canonical
- * {@link WaitStateType} union. The gateway's read model is a snapshot of the Zeebe contract
- * taken 2026-06-09 (the same day Zeebe extended it with `USER_TASK`, then `TIMER`/`SIGNAL`/
- * `CONDITION`), so it recognizes only `JOB | MESSAGE` and rejects any other filter value
- * with HTTP 422.
+ * {@link WaitStateType} union. The gateway's read model started as a snapshot of the Zeebe
+ * contract taken 2026-06-09 that recognized only `JOB | MESSAGE`; Magikcraft/nano-bpm#1042
+ * has since shipped `USER_TASK` parks (added on user-task CREATED, removed on
+ * COMPLETED/CANCELED, with the park identity under `details.taskKey`), moving the floor up to
+ * `JOB | MESSAGE | USER_TASK`. `TIMER`/`SIGNAL`/`CONDITION` are still rejected with HTTP 422
+ * (the 8.10 follow-on tracked in Magikcraft/nano-bpm#1042).
  *
  * This constant is the **single source of truth** for that floor: the SDK-backed and
  * WASM-backed {@link EngineClient} adapters both gate through {@link assertDeployedWaitStateType},
@@ -375,7 +379,7 @@ export type WaitStateType =
  * backed by the real gateway) only once the engine actually serves the richer type — the
  * tracking gap is Magikcraft/nano-bpm#1042.
  */
-export const DEPLOYED_WAIT_STATE_TYPES: readonly WaitStateType[] = ["JOB", "MESSAGE"];
+export const DEPLOYED_WAIT_STATE_TYPES: readonly WaitStateType[] = ["JOB", "MESSAGE", "USER_TASK"];
 
 /**
  * Thrown when a wait-state search is asked to filter on a {@link WaitStateType} the deployed
@@ -701,14 +705,14 @@ export interface EngineClient {
    * (see {@link ElementInstanceWaitState}), so a consumer can read the job/message parks a
    * {@link searchUserTasks} cannot surface.
    *
-   * **Deployed floor.** The currently deployed nanobpmn gateway implements only
-   * `JOB | MESSAGE` ({@link DEPLOYED_WAIT_STATE_TYPES}) — a `USER_TASK` park is read via
-   * {@link searchUserTasks}, not here. A `waitStateType` filter outside the floor is rejected
-   * with {@link UnsupportedWaitStateTypeError} (the live gateway answers HTTP 422); an
-   * unfiltered search returns only in-floor parks. The `waitStateType` union is
-   * forward-looking (richer engines may serve more), but this adapter contract pins the
-   * floor so a query cannot pass in emulation while a real engine rejects it. Ref:
-   * Magikcraft/nano-bpm#1042.
+   * **Deployed floor.** The currently deployed nanobpmn gateway implements
+   * `JOB | MESSAGE | USER_TASK` ({@link DEPLOYED_WAIT_STATE_TYPES}); a `USER_TASK` park can be
+   * read here (or through {@link searchUserTasks}). A `waitStateType` filter outside the floor
+   * (`TIMER`/`SIGNAL`/`CONDITION`) is rejected with {@link UnsupportedWaitStateTypeError} (the
+   * live gateway answers HTTP 422); an unfiltered search returns only in-floor parks. The
+   * `waitStateType` union is forward-looking (richer engines may serve more), but this adapter
+   * contract pins the floor so a query cannot pass in emulation while a real engine rejects it.
+   * Ref: Magikcraft/nano-bpm#1042.
    */
   searchElementInstanceWaitStates(
     filter?: ElementInstanceWaitStateFilter,