@nanobpm/urban 0.49.1 → 0.51.0

package/src/runtime/core/form-contract.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  buildFormSchema,
+  parseFormSchema,
+  pickFormLinkage,
+  resolveFormIdentifier,
+} from "./form-contract.ts";
+
+test("resolveFormIdentifier prefers a present formKey over a formId", () => {
+  assert.deepEqual(resolveFormIdentifier({ formKey: "42", formId: "myForm" }), {
+    kind: "key",
+    value: "42",
+  });
+});
+
+test("resolveFormIdentifier falls back to formId when formKey is absent/blank/whitespace", () => {
+  assert.deepEqual(resolveFormIdentifier({ formId: "myForm" }), { kind: "id", value: "myForm" });
+  for (const formKey of ["", "   "]) {
+    assert.deepEqual(
+      resolveFormIdentifier({ formKey, formId: "myForm" }),
+      { kind: "id", value: "myForm" },
+      `formKey=${JSON.stringify(formKey)} must fall through to formId`,
+    );
+  }
+});
+
+test("resolveFormIdentifier trims the resolved value and returns null when neither is present", () => {
+  assert.deepEqual(resolveFormIdentifier({ formKey: "  42  " }), { kind: "key", value: "42" });
+  assert.equal(resolveFormIdentifier({}), null);
+  assert.equal(resolveFormIdentifier({ formKey: "  ", formId: "" }), null);
+});
+
+test("parseFormSchema parses a JSON-object string, passes an object through, and rejects the rest", () => {
+  assert.deepEqual(parseFormSchema('{"a":1}'), { a: 1 });
+  const obj = { a: 1 };
+  assert.equal(parseFormSchema(obj), obj);
+  assert.equal(parseFormSchema("not json"), null);
+  assert.equal(parseFormSchema("[1,2]"), null, "a JSON array is not a form schema object");
+  assert.equal(parseFormSchema(42), null);
+  assert.equal(parseFormSchema(null), null);
+});
+
+test("buildFormSchema applies presence guards and stringifies a numeric formKey", () => {
+  const schema = { components: [] };
+  assert.deepEqual(buildFormSchema({ schema, formKey: 42, formId: "myForm", version: 3 }), {
+    schema,
+    formKey: "42",
+    formId: "myForm",
+    version: 3,
+  });
+  // Blank/garbage parts are omitted rather than surfaced as empty values.
+  assert.deepEqual(buildFormSchema({ schema, formKey: "", formId: "", version: "3" }), { schema });
+  assert.deepEqual(buildFormSchema({ schema }), { schema });
+});
+
+test("buildFormSchema trims padded identifiers and drops whitespace-only ones (the #252 drift bug)", () => {
+  const schema = { components: [] };
+  // Whitespace-only key/id are absent, not surfaced as " ".
+  assert.deepEqual(buildFormSchema({ schema, formKey: "   ", formId: "  " }), { schema });
+  // A padded key/id is trimmed to its space-free value, not surfaced with the padding.
+  assert.deepEqual(buildFormSchema({ schema, formKey: "  42  ", formId: "  myForm  " }), {
+    schema,
+    formKey: "42",
+    formId: "myForm",
+  });
+});
+
+test("pickFormLinkage prefers a direct formKey and carries an externalFormReference", () => {
+  assert.deepEqual(
+    pickFormLinkage({ formKey: 42, externalFormReference: "https://x/form" }),
+    { formKey: "42", externalFormReference: "https://x/form" },
+  );
+  // Blank linkage fields are treated as absent.
+  assert.deepEqual(pickFormLinkage({ formKey: "", externalFormReference: "" }), {});
+});
+
+test("pickFormLinkage trims padded linkage fields and drops whitespace-only ones", () => {
+  // Whitespace-only key/id/ref are absent, not surfaced with whitespace.
+  assert.deepEqual(
+    pickFormLinkage({ formKey: "   ", externalFormReference: "  " }),
+    {},
+  );
+  // A padded key/ref is trimmed; a padded authored id is trimmed before the resolver sees it.
+  assert.deepEqual(
+    pickFormLinkage({ formKey: "  7  ", externalFormReference: "  https://x/form  " }),
+    { formKey: "7", externalFormReference: "https://x/form" },
+  );
+  assert.deepEqual(
+    pickFormLinkage({ formId: "  myForm  " }, (id) => (id === "myForm" ? "form-7" : undefined)),
+    { formKey: "form-7" },
+    "the authored formId is trimmed before the key resolver is called",
+  );
+});
+
+test("pickFormLinkage resolves an authored formId to a deploy key only via the callback", () => {
+  const raw = { formId: "myForm" };
+  // No resolver (the gateway path): an authored id is not turned into a key.
+  assert.deepEqual(pickFormLinkage(raw), {});
+  // With a resolver (the WASM/key-addressed path): the id maps to the latest deploy key.
+  assert.deepEqual(
+    pickFormLinkage(raw, (id) => (id === "myForm" ? "form-7" : undefined)),
+    { formKey: "form-7" },
+  );
+});

package/src/runtime/core/form-contract.ts

@@ -0,0 +1,121 @@
+// The shared, transport-agnostic normalization glue for the form + user-task parts of
+// the {@link EngineClient} contract. Both engine adapters — the live SDK/REST adapter
+// (`engine/nanosdk.ts`, `SdkEngineClient`) and the in-process WASM test adapter
+// (`@nanobpm/urban-testkit`, `WasmEngineClient`) — reproduce the same API-layer
+// conveniences (form storage + `formId`→`formKey` resolution, form-schema parsing,
+// user-task form linkage) on top of their own transport. Historically each adapter
+// hand-mirrored these rules (with literal `// Mirror … exactly` comments), and that
+// copy-paste drifted — e.g. a local `presentFormIdentifier` copy that trimmed for the
+// emptiness check but returned the *untrimmed* value. Centralizing the rules here so
+// both adapters call the *same* code removes that drift class (issue #252).
+
+import { presentFormIdentifier } from "./host.ts";
+import type { FormSchema } from "./host.ts";
+import { isRecord } from "./guards.ts";
+
+export { presentFormIdentifier };
+
+/**
+ * Presence-check a possibly-numeric identifier under the shared trim rule. The REST body may
+ * carry a `formKey` as a number, so coerce it to a string; an empty or whitespace-only string
+ * is *absent* (via {@link presentFormIdentifier}, which also trims). Any other type is absent.
+ * This is the same trimming presence rule {@link resolveFormIdentifier} applies, so a blank
+ * key can never be surfaced as an empty/whitespace value — the drift-bug class #252 targets.
+ */
+function presentKey(v: unknown): string | undefined {
+  if (typeof v === "number") return presentFormIdentifier(String(v));
+  if (typeof v === "string") return presentFormIdentifier(v);
+  return undefined;
+}
+
+/**
+ * Resolve which identifier addresses a form for {@link EngineClient.getForm}, applying the
+ * contract's shared presence + preference rule: prefer a present `formKey`, else fall back
+ * to a present `formId`; an empty/whitespace-only value is *absent* (via
+ * {@link presentFormIdentifier}), so a blank `?formKey=` falls through to a valid `formId`
+ * instead of short-circuiting to null. Returns `null` when neither identifier is present.
+ *
+ * `kind` distinguishes a resolved deploy key (`"key"`) from an authored form id (`"id"`),
+ * which a key-addressed store (the WASM adapter) must itself resolve to a deploy key; a
+ * key/id-agnostic backend (the REST gateway) can ignore `kind` and address by `value`.
+ */
+export function resolveFormIdentifier(
+  input: { formKey?: string; formId?: string },
+): { kind: "key" | "id"; value: string } | null {
+  const key = presentFormIdentifier(input.formKey);
+  if (key != null) return { kind: "key", value: key };
+  const id = presentFormIdentifier(input.formId);
+  if (id != null) return { kind: "id", value: id };
+  return null;
+}
+
+/**
+ * Parse a deployed form-js schema into the object the surface renders. The engine
+ * serializes it as a JSON string, so parse it; tolerate an already-parsed object (an
+ * in-memory/embedded engine). Returns `null` for anything that is neither a JSON object
+ * string nor an object (which the caller treats as "no such form").
+ */
+export function parseFormSchema(raw: unknown): Record<string, unknown> | null {
+  if (isRecord(raw)) return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assemble the {@link FormSchema} result with the contract's presence guards: a blank or
+ * whitespace-only `formKey`/`formId`, or a non-numeric `version`, is omitted rather than
+ * surfaced as an empty/garbage value. Identifiers are trimmed (the shared presence rule), so
+ * a padded `formKey` never leaks whitespace; `formKey` is stringified (the REST body may carry
+ * it as a number).
+ */
+export function buildFormSchema(parts: {
+  schema: Record<string, unknown>;
+  formKey?: unknown;
+  formId?: unknown;
+  version?: unknown;
+}): FormSchema {
+  const formKey = presentKey(parts.formKey);
+  const formId = typeof parts.formId === "string" ? presentFormIdentifier(parts.formId) : undefined;
+  return {
+    schema: parts.schema,
+    ...(formKey != null ? { formKey } : {}),
+    ...(formId != null ? { formId } : {}),
+    ...(typeof parts.version === "number" ? { version: parts.version } : {}),
+  };
+}
+
+/**
+ * Select a user task's form linkage from a raw engine record for
+ * {@link EngineClient.searchUserTasks}, applying the contract's non-empty rule (a blank
+ * `formKey`/`externalFormReference` is absent). The engine resolves a
+ * `<zeebe:formDefinition formId="X" />` linkage to the latest deployed form's key at task
+ * creation, so a resolved `formKey` (not a form id) is the linkage a task reports.
+ *
+ * A key-addressed engine that does *not* itself resolve that linkage (the WASM adapter)
+ * can pass `resolveFormKeyByFormId` to map an authored `formId` on the task to the deploy
+ * key; a backend that already resolved it (the REST gateway) omits the resolver, and the
+ * authored-id path is simply not taken. A blank or whitespace-only `formKey`/`formId`/
+ * `externalFormReference` is treated as absent (the shared trimming presence rule).
+ */
+export function pickFormLinkage(
+  raw: Record<string, unknown>,
+  resolveFormKeyByFormId?: (formId: string) => string | undefined,
+): { formKey?: string; externalFormReference?: string } {
+  const directKey = presentKey(raw.formKey);
+  const authoredId = typeof raw.formId === "string" ? presentFormIdentifier(raw.formId) : undefined;
+  const formKey =
+    directKey ?? (authoredId && resolveFormKeyByFormId ? resolveFormKeyByFormId(authoredId) : undefined);
+  const externalFormReference =
+    typeof raw.externalFormReference === "string"
+      ? presentFormIdentifier(raw.externalFormReference)
+      : undefined;
+  return {
+    ...(formKey ? { formKey } : {}),
+    ...(externalFormReference ? { externalFormReference } : {}),
+  };
+}

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

@@ -371,6 +371,91 @@ test("renderer interpolates a column's per-cell template into DOM text (#214)",
   assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : rawText;/);
 });
 
+test("renderer renders a column's subtitle as a muted second line, never an href (#257)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column may render an optional muted second line beneath the primary text
+  // (the identity key under a title, GitHub/Linear style). The value comes from
+  // col.subtitleField (raw) or col.subtitleTemplate (interpolated), null/absent →
+  // "" → no extra line. Guard the shape: subtitleTemplate wins via interpTemplate,
+  // the subtitle is emitted as a .pc-cell-sub DOM-text line, and — crucially for
+  // the security posture — it is NEVER an href source (only linkField/keyField
+  // drive anchors; the subtitle stays plain text).
+  assert.match(js, /col\.subtitleField != null && row\[col\.subtitleField\] != null \? String\(row\[col\.subtitleField\]\) : ""/);
+  assert.match(js, /const subText = typeof col\.subtitleTemplate === "string" \? interpTemplate\(col\.subtitleTemplate, row\) : subRaw;/);
+  assert.match(js, /class: "pc-cell-sub"/);
+  // Absent subtitle (empty) and no truncation collapses back to the single inline
+  // node, so existing grids render exactly as before (backward compatible).
+  assert.match(js, /if \(subText === "" && !truncate\) return el\("td", \{\}, primary\);/);
+});
+
+test("renderer truncates a column to one line with an ellipsis + full-text tooltip (#257)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // col.truncate:true clamps the primary (and any subtitle) line to a single row
+  // with an ellipsis, carrying the full value in a native title= tooltip and
+  // aria-label so the clipped text stays recoverable on hover and to assistive
+  // tech. Guard the shape: opt-in on `=== true`, a .pc-truncate class is added to
+  // the line, and the full text is mirrored into title/aria-label.
+  assert.match(js, /const truncate = col\.truncate === true;/);
+  assert.match(js, /"pc-cell-main"\s*\+\s*\(truncate \? " pc-truncate" : ""\)/);
+  assert.match(js, /mainAttrs\.title = primaryText; mainAttrs\["aria-label"\] = primaryText;/);
+  // title/aria-label are NOT inherited by descendants in HTML, so a link cell's
+  // <a> primary would miss the full-text tooltip/accessible name the wrapper div
+  // carries. Guard that they're also mirrored onto the primary element itself when
+  // it's a node (an anchor), so link cells get the same full-text recovery as text.
+  assert.match(js, /if \(primary && typeof primary\.setAttribute === "function"\) \{/);
+  assert.match(js, /primary\.setAttribute\("title", primaryText\); primary\.setAttribute\("aria-label", primaryText\);/);
+  assert.match(js, /"pc-cell-sub"\s*\+\s*\(truncate \? " pc-truncate" : ""\)/);
+});
+
+test("renderer emits a <colgroup> sizing columns by width/weight (#257)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column may declare an explicit `width` ("40%", "22rem") or a relative
+  // integer `weight`, so table-layout:fixed stops splitting width equally. This
+  // emits a <colgroup> of <col style="width:…"> (fixed layout honours <col>
+  // widths). Guard the shape: an explicit width string wins verbatim, a positive
+  // weight is normalised across weighted columns into a percentage of the width
+  // the explicit columns leave (the remainder), unsized columns get no width
+  // (share the remainder), and no colgroup is emitted at all when no column
+  // declares sizing (so unsized grids are unchanged).
+  assert.match(js, /function buildColgroup\(cols, extraCount\)/);
+  assert.match(js, /if \(!hasSizing\) return null;/);
+  assert.match(js, /function hasExplicitWidth\(col\)/);
+  assert.match(js, /if \(hasExplicitWidth\(col\)\) return col\.width;/);
+  assert.match(js, /Math\.round\(\(col\.weight \/ weightTotal\) \* remainderPct \* 100\) \/ 100 \+ "%"/);
+  assert.match(js, /el\("col", w \? \{ style: "width:" \+ w \} : \{\}\)/);
+  // Regression (#258 review): mixing explicit % widths with weighted columns
+  // must not oversubscribe past 100% — weighted columns share only the remainder
+  // (100 - sum of explicit %), and only when every explicit width is a
+  // percentage (rem/px explicit widths fall back to a share of the full width).
+  assert.match(js, /const remainderPct = allExplicitArePct \? Math\.max\(0, 100 - explicitPctTotal\) : 100;/);
+  // Regression (#258 review): a column carrying both an explicit width and a
+  // weight uses its width verbatim and never consumes its weight, so it must be
+  // excluded from weightTotal or the truly-weighted columns' share is shrunk.
+  assert.match(js, /if \(!hasExplicitWidth\(c\) && typeof c\.weight === "number" && c\.weight > 0\) weightTotal \+= c\.weight;/);
+  assert.match(js, /function colWidthPct\(width\)/);
+  // The colgroup precedes <thead> in the table, and only when sizing is present.
+  assert.match(js, /\? el\("table", \{ class: "pc-grid" \}, colgroup, thead, tbody\)/);
+});
+
+test("the shell styles the subtitle line muted and the truncate clamp to one line (#257)", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  // The muted subtitle line and the one-line clamp are styled in the shell CSS
+  // (served with the shell HTML, like the other pc-grid rules). Guard both rules.
+  const subRule = (html.match(/\.pc-cell-sub\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(subRule, ".pc-cell-sub rule must be present");
+  assert.match(subRule, /color:var\(--nano-text-muted\)/);
+  assert.match(subRule, /font-size:\.8rem/);
+  const truncRule = (html.match(/\.pc-truncate\s*\{[^}]*\}/) ?? [""])[0];
+  assert.ok(truncRule, ".pc-truncate rule must be present");
+  assert.match(truncRule, /white-space:nowrap/);
+  assert.match(truncRule, /overflow:hidden/);
+  assert.match(truncRule, /text-overflow:ellipsis/);
+});
+
 test("renderer wires a column's processExplorer link to the console explorer", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";

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

@@ -549,6 +549,16 @@ table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-lay
    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); }
+/* A cell's optional muted second line (col.subtitleField / subtitleTemplate):
+   the identity key rendered under the title, GitHub/Linear style. Plain DOM
+   text (never a link/href source), smaller and muted so the primary line leads. */
+.pc-cell-sub { font-size:.8rem; color:var(--nano-text-muted); margin-top:.1rem; }
+/* One-line clamp (col.truncate): stop a bounded column wrapping and show an
+   ellipsis, with the full value carried in a title=/aria-label tooltip. Needs a
+   bounded column (per-column width/weight) to clip against; a native <col> width
+   is honoured under table-layout:fixed. Applied to the primary and, when present,
+   the subtitle line so both stay single-line. */
+.pc-truncate { white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
 .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; }
 .pc-tab.active { background:var(--nano-accent); color:var(--nano-on-accent); border-color:var(--nano-accent); }
@@ -1039,6 +1049,15 @@ function renderButton(node) {
 // tooltip stay keyed to the raw 'field' value (a badge shows a fixed glyph, not
 // the field text), so a template does not change badge behaviour. Sorting,
 // groupBy and orderBy also key off real fields, never the rendered template.
+//
+// Two-line identity + one-line clamp (additive, opt-in, backward-compatible):
+// a column may also declare 'subtitleField'/'subtitleTemplate' to render a muted
+// second line under the primary text (the identity key beneath a title, GitHub/
+// Linear style) and 'truncate: true' to clamp each line to one row with an
+// ellipsis and a full-text title/aria-label tooltip (pairs with a per-column
+// width/weight — see buildColgroup — to give the clip a bounded column). The
+// subtitle is ALWAYS plain DOM text, never an href source. With none of these
+// set the cell is a single inline node exactly as before (see cellTd).
 function gridCell(col, row) {
   // Raw single-field value: drives the badge presence gate + tooltip and any
   // field-derived defaults. Kept separate from the (possibly templated) display
@@ -1068,17 +1087,28 @@ function gridCell(col, row) {
       el("span", { class: "pc-badge pc-badge-" + tone, title: rawText, "aria-label": rawText }, label),
     );
   }
+  // Optional second line (col.subtitleField / subtitleTemplate): a muted key
+  // under the primary title. subtitleTemplate wins (interpolated from the row);
+  // else the raw subtitleField value. Absent/null → "" → no extra line. It is
+  // ALWAYS plain DOM text (see cellTd), never a link/href source — a subtitle
+  // cannot smuggle a scheme or path, only linkField/keyField drive hrefs.
+  const subRaw =
+    col.subtitleField != null && row[col.subtitleField] != null ? String(row[col.subtitleField]) : "";
+  const subText = typeof col.subtitleTemplate === "string" ? interpTemplate(col.subtitleTemplate, row) : subRaw;
+  const truncate = col.truncate === true;
+  // Primary inline content: an anchor for a valid link mode (checked in the same
+  // badge < linkField < link(page) < link(processExplorer) precedence as before),
+  // else the plain display text. Each link mode only claims the cell while
+  // 'primary' is still the bare text — an invalid href falls through to the next
+  // mode and ultimately to plain text, exactly as the early-return chain did.
+  let primary = text;
   if (col.linkField) {
     const href = row[col.linkField] == null ? "" : String(row[col.linkField]);
     if (text !== "" && /^https?:\/\//i.test(href)) {
-      return el(
-        "td",
-        {},
-        el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text),
-      );
+      primary = el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text);
     }
   }
-  if (col.link && col.link.kind === "page" && col.link.page && col.link.keyField) {
+  if (primary === text && col.link && col.link.kind === "page" && col.link.page && col.link.keyField) {
     // An in-app link to another page, scoped to this row: #/<page>/<key>. The
     // key (e.g. a plan_key "owner/repo#123") is URL-encoded into the route's
     // param tail, which parseRoute() decodes back verbatim; the page id is
@@ -1089,37 +1119,130 @@ function gridCell(col, row) {
     const keyStr = key == null ? "" : String(key).trim();
     if (text !== "" && safePageId(col.link.page) && keyStr !== "") {
       const href = "#/" + encodeURIComponent(col.link.page) + "/" + encodeURIComponent(keyStr);
-      return el("td", {}, el("a", { class: "pc-link", href }, text));
+      primary = el("a", { class: "pc-link", href }, text);
     }
   }
-  if (col.link && col.link.kind === "processExplorer" && col.link.keyField) {
+  if (primary === text && col.link && col.link.kind === "processExplorer" && col.link.keyField) {
     const key = row[col.link.keyField];
     const keyStr = key == null ? "" : String(key).trim();
     if (text !== "" && keyStr !== "") {
       const href = "/console/explorer?instance=" + encodeURIComponent(keyStr);
-      return el(
-        "td",
-        {},
-        el("a", {
-          class: "pc-link",
-          href,
-          target: "_blank",
-          rel: "noopener noreferrer",
-          // Embedded in the console a plain primary click routes the host's
-          // explorer in place (via the nano-navigate bridge) instead of opening
-          // a new window. A non-primary button (middle/right = new-tab/context
-          // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
-          // any standalone run fall through to the native anchor above.
-          onclick: (ev) => {
-            if (ev.button !== 0) return;
-            if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
-            if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
-          },
-        }, text),
-      );
+      primary = el("a", {
+        class: "pc-link",
+        href,
+        target: "_blank",
+        rel: "noopener noreferrer",
+        // Embedded in the console a plain primary click routes the host's
+        // explorer in place (via the nano-navigate bridge) instead of opening
+        // a new window. A non-primary button (middle/right = new-tab/context
+        // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
+        // any standalone run fall through to the native anchor above.
+        onclick: (ev) => {
+          if (ev.button !== 0) return;
+          if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+          if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
+        },
+      }, text);
+    }
+  }
+  return cellTd(primary, text, subText, truncate);
+}
+
+// Compose a grid <td> from its primary inline content (a string or an anchor),
+// an optional muted subtitle line, and optional one-line truncation. With
+// NEITHER a subtitle nor truncation the cell is exactly the single inline node
+// as before, so existing grids render byte-for-byte unchanged (backward
+// compatible). When either is set the content is wrapped in a .pc-cell-main
+// line and, if a subtitle is present, a .pc-cell-sub line beneath it. truncate
+// adds .pc-truncate (nowrap + ellipsis) to each line and mirrors the full text
+// into title=/aria-label so the clipped value is still recoverable on hover and
+// to assistive tech. When the primary is an element (a link cell's <a>), title=/
+// aria-label= are ALSO mirrored onto it: HTML does not inherit those to
+// descendants, so hovering the link text or naming the anchor for assistive tech
+// would otherwise miss the full value the wrapper carries. The subtitle is set as
+// DOM text only — never an href.
+function cellTd(primary, primaryText, subText, truncate) {
+  if (subText === "" && !truncate) return el("td", {}, primary);
+  const mainAttrs = { class: "pc-cell-main" + (truncate ? " pc-truncate" : "") };
+  if (truncate && primaryText !== "") {
+    mainAttrs.title = primaryText; mainAttrs["aria-label"] = primaryText;
+    if (primary && typeof primary.setAttribute === "function") {
+      primary.setAttribute("title", primaryText); primary.setAttribute("aria-label", primaryText);
+    }
+  }
+  const main = el("div", mainAttrs, primary);
+  if (subText === "") return el("td", {}, main);
+  const subAttrs = { class: "pc-cell-sub" + (truncate ? " pc-truncate" : "") };
+  if (truncate) { subAttrs.title = subText; subAttrs["aria-label"] = subText; }
+  return el("td", {}, main, el("div", subAttrs, subText));
+}
+
+// Parse a "<number>%" width into its numeric percentage, or null if the string
+// is not a bare percentage (e.g. "22rem", "120px") — used to decide whether the
+// remainder left for weighted columns can be computed.
+function colWidthPct(width) {
+  const m = /^\s*([0-9]*\.?[0-9]+)%\s*$/.exec(width);
+  return m ? parseFloat(m[1]) : null;
+}
+
+// A column carries an explicit width only when it is a non-empty string. Single
+// source of truth so colWidthStyle/buildColgroup can't drift on what "explicit"
+// means (which columns win verbatim, consume the remainder, or use their weight).
+function hasExplicitWidth(col) {
+  return typeof col.width === "string" && col.width !== "";
+}
+
+// A column's <col> width for the grid's <colgroup>: an explicit col.width string
+// ("40%", "22rem") wins verbatim; else a positive numeric col.weight is
+// normalised across the weighted columns into a percentage share of the width
+// left over by explicit columns (remainderPct); else null (no width — the column
+// shares the remainder equally under table-layout:fixed).
+function colWidthStyle(col, weightTotal, remainderPct) {
+  if (hasExplicitWidth(col)) return col.width;
+  if (typeof col.weight === "number" && col.weight > 0 && weightTotal > 0) {
+    return Math.round((col.weight / weightTotal) * remainderPct * 100) / 100 + "%";
+  }
+  return null;
+}
+
+// Build a <colgroup> that sizes the grid's columns so table-layout:fixed stops
+// splitting width equally. Returns null when no column declares width/weight, so
+// an unsized grid emits no colgroup and lays out exactly as today. 'extraCount'
+// adds trailing unsized <col>s for the row-actions/detail column so the sized
+// data columns stay aligned with their headers.
+function buildColgroup(cols, extraCount) {
+  const hasSizing = cols.some(
+    (c) => hasExplicitWidth(c) || (typeof c.weight === "number" && c.weight > 0),
+  );
+  if (!hasSizing) return null;
+  // Only columns that will actually use their weight (no explicit width — an
+  // explicit width wins verbatim in colWidthStyle and never consumes weight)
+  // contribute to weightTotal; counting a width-bearing column's weight here
+  // would inflate the divisor and shrink the truly-weighted columns' share.
+  let weightTotal = 0;
+  for (const c of cols)
+    if (!hasExplicitWidth(c) && typeof c.weight === "number" && c.weight > 0) weightTotal += c.weight;
+  // Weighted columns share only the width the explicit columns leave behind, so
+  // mixing e.g. width:"40%" with weighted columns can't oversubscribe past 100%.
+  // The remainder is only computable when every explicit width is a percentage;
+  // if any uses an absolute/relative unit (rem/px) we can't subtract it from
+  // 100%, so weighted columns fall back to a share of the full width.
+  let explicitPctTotal = 0;
+  let allExplicitArePct = true;
+  for (const c of cols) {
+    if (hasExplicitWidth(c)) {
+      const pct = colWidthPct(c.width);
+      if (pct === null) allExplicitArePct = false;
+      else explicitPctTotal += pct;
     }
   }
-  return el("td", {}, text);
+  const remainderPct = allExplicitArePct ? Math.max(0, 100 - explicitPctTotal) : 100;
+  const colEls = cols.map((c) => {
+    const w = colWidthStyle(c, weightTotal, remainderPct);
+    return el("col", w ? { style: "width:" + w } : {});
+  });
+  for (let i = 0; i < extraCount; i++) colEls.push(el("col", {}));
+  return el("colgroup", {}, ...colEls);
 }
 
 function renderActionForm(node) {
@@ -1315,7 +1438,13 @@ function renderDataGrid(node) {
   if (hasExtra) headCells.push(el("th", {}, ""));
   const thead = el("thead", {}, el("tr", {}, ...headCells));
   const tbody = el("tbody", {});
-  const table = el("table", { class: "pc-grid" }, thead, tbody);
+  // A <colgroup> (present only when a column declares width/weight) sizes the
+  // columns so table-layout:fixed stops splitting width equally; it must precede
+  // <thead> in the table.
+  const colgroup = buildColgroup(cols, hasExtra ? 1 : 0);
+  const table = colgroup
+    ? el("table", { class: "pc-grid" }, colgroup, thead, tbody)
+    : el("table", { class: "pc-grid" }, thead, tbody);
   card.append(table);
   const span = String((cols.length || 1) + (hasExtra ? 1 : 0));
 
@@ -1407,9 +1536,12 @@ function renderDataGrid(node) {
     if (cg.title) wrap.append(el("div", { class: "pc-child-title" }, cg.title));
     const ccols = cg.columns || [];
     const cbody = el("tbody", {});
-    const ctable = el("table", { class: "pc-grid" },
-      el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
-        ...(cg.lazyField ? [el("th", {}, "")] : []))), cbody);
+    const ccolgroup = buildColgroup(ccols, cg.lazyField ? 1 : 0);
+    const cthead = el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
+      ...(cg.lazyField ? [el("th", {}, "")] : [])));
+    const ctable = ccolgroup
+      ? el("table", { class: "pc-grid" }, ccolgroup, cthead, cbody)
+      : el("table", { class: "pc-grid" }, cthead, cbody);
     wrap.append(ctable);
     try {
       const { rows } = await getJSON(dataUrl(cg.source || "app", cg.table,

package/src/runtime/engine/nanosdk.test.ts

@@ -194,10 +194,11 @@ test("searchUserTasks passes zero-wait consistency and maps items", async () =>
   const engine = new SdkEngineClient(client);
   const tasks = await engine.searchUserTasks({ processInstanceKey: "pi" });
   assert.deepEqual(consistency, { consistency: { waitUpToMs: 0 } });
-  // The search is constrained to open (CREATED) tasks so terminal tasks never
-  // surface as answerable, while caller filters (processInstanceKey) still apply.
-  // Assert individual fields so the check is independent of key insertion order.
-  assert.equal(input?.filter?.state, "CREATED");
+  // The adapter forwards the caller's filter verbatim and no longer injects a lifecycle
+  // state (#252): the search is unfiltered by state unless the caller opts in, so the
+  // taskInbox surface — not the adapter — owns the open-only (CREATED) policy. Assert
+  // individual fields so the check is independent of key insertion order.
+  assert.equal(input?.filter?.state, undefined, "no state is injected when the caller passes none");
   assert.equal(input?.filter?.processInstanceKey, "pi");
   assert.deepEqual(tasks, [
     { userTaskKey: "7", elementId: "task_a", variables: { x: 1 } },
@@ -205,6 +206,22 @@ test("searchUserTasks passes zero-wait consistency and maps items", async () =>
   ]);
 });
 
+test("searchUserTasks forwards a caller-provided lifecycle state filter", async () => {
+  let input: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchUserTasks: async (i) => {
+      input = i;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchUserTasks({ state: "CREATED", processInstanceKey: "pi" });
+  // The caller's `state` reaches the engine unchanged — the adapter neither drops nor
+  // overrides it (the taskInbox surface passes `state: "CREATED"` to constrain the inbox).
+  assert.equal(input?.filter?.state, "CREATED");
+  assert.equal(input?.filter?.processInstanceKey, "pi");
+});
+
 test("searchUserTasks surfaces the resolved form linkage", async () => {
   const client = fakeSdkClient({
     searchUserTasks: async () => ({