@colixsystems/widget-sdk 0.154.0 → 0.156.0

package/README.md

@@ -31,6 +31,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
 | **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. |
 | **CORE** | `isNarrowWidth(width)` | `boolean` | No context slice, no scope. True when a MEASURED width is below `NARROW_WIDTH_PX` (480) — the one threshold every widget switches at, so a page reflows together rather than raggedly. An unmeasured width (0) is NOT narrow, so nothing flashes through the narrow form on first paint. |
+| **CORE** | `widthTier(width)` | `"narrow" \| "medium" \| "wide"` | No context slice, no scope. Which of THREE layouts a measured width calls for: narrow below `NARROW_WIDTH_PX` (480), wide at or above `WIDE_WIDTH_PX` (960), medium between. `widthTier(w) === "narrow"` exactly when `isNarrowWidth(w)`; an unmeasured width (0) is "wide". |
 | **CORE** | `useSectionEmpty(isEmpty)` | `void` | `ctx.section.reportEmpty` — no scope. Declares that the widget has NO content to show, so the host drops its layout slot instead of reserving space (and its parent's `gap`) for it. Returning `null` is not enough: the host wraps every widget in an entrance element, so a widget rendering nothing still leaves an empty box the parent stack gaps around. For a CONDITIONALLY ABSENT section (a per-record child collection with no rows for this record), never to suppress a genuine empty state. Stays mounted while collapsed, so passing `false` brings it back. Authoring surfaces never collapse. No-op on a host that doesn't implement it. |
 | **CORE** | `useScreenTitle(title)` | `void` | `ctx.screen.reportTitle` — no scope. Names the screen the widget is on, so the host paints that name in the app header beside the back control instead of the app brand. The page's own name is the default; only the widget knows the screen is really "Order #1423" rather than "Orders". The MOST RECENT call wins — with several widgets on one screen the last to report owns the title, and on unmount (or an empty title) the host falls back to the most recent surviving report and finally to the page name. Only a screen showing the back control paints a title; a root page keeps the brand. No-op on a host that doesn't implement it. |
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
@@ -72,7 +73,23 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.154.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.156.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.156.0 (contract 1.122.0)
+
+**A third layout tier: `widthTier(width)` and `WIDE_WIDTH_PX` (sc-8508).** `isNarrowWidth` splits widths into narrow and everything else, so a widget alone on a desktop page rendered the same layout it uses in a half-width cell and left most of a 1200px box empty. `widthTier` returns `"narrow"`, `"medium"` or `"wide"` — lay a form out in one column, then paired fields, then two or three columns; a list as stacked cards, then one-line cards, then rows with real columns.
+
+Additive: `isNarrowWidth` and `NARROW_WIDTH_PX` are unchanged, and `widthTier(w) === "narrow"` exactly when `isNarrowWidth(w)` is true.
+
+### What's new in 0.155.0 (contract 1.121.0)
+
+**`useAgent()` returns `cancel()` — and two error codes that tell the truth about a slow turn (sc-8519).** A turn can legitimately run for minutes; the client used to give up after 10 seconds and report it as `NETWORK`, so a widget showed "you appear to be offline" to a user whose connection was fine, while the server finished the turn and the workspace paid for a reply nobody saw.
+
+- **`cancel()`** stops WAITING for the turn in flight. The abort never reaches the server, which finishes and bills the turn either way — so label the control **stop**, not *cancel*, and never imply the work was called off.
+- **`TIMEOUT`** — the client stopped waiting. Still running, still billed: say it is taking longer than usual, never that it failed.
+- **`CANCELLED`** — the user pressed your stop control. Render no error at all.
+
+Additive: `send` is unchanged for callers who ignore the new return key, and a widget that never calls `cancel()` behaves exactly as before.
 
 ### What's new in 0.154.0 (contract 1.120.0)
 
@@ -1736,10 +1753,10 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
-- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces above ~720px measured width** (`flexDirection: width >= 720 ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead. **A metric / stat-tile row WRAPS** — it is a card grid with smaller cells (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }` plus `maxWidth: TILE_MIN * 1.6`), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
-- **Compose forms — pair fields into rows, don't stack one per row.** Cap the form column itself around 560–720px and centre it with the three declarations above, so it neither stretches across a full-width desktop section nor sits flush left with half the canvas empty beside it. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
+- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a cell whose definite size is computed from the width (a calendar day, a chart), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
+- **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
-- **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` below `isNarrowWidth`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
+- **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
 - **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a `16 / 9` card cover, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.

package/dist/container-width.js

@@ -26,3 +26,30 @@ export const NARROW_WIDTH_PX = 480;
 export function isNarrowWidth(width) {
   return typeof width === "number" && width > 0 && width < NARROW_WIDTH_PX;
 }
+
+/**
+ * sc-8508 — the width above which a widget has room for its WIDE form: a form
+ * in two or three columns, a list whose rows carry real columns, a filter bar
+ * on one toolbar row. Twice the narrow threshold, which is the three-column
+ * break the Developer guide already showed as `NARROW_WIDTH_PX * 2`.
+ */
+export const WIDE_WIDTH_PX = 960;
+
+/**
+ * Which of the three layouts a MEASURED width calls for: "narrow" below
+ * `NARROW_WIDTH_PX`, "wide" at or above `WIDE_WIDTH_PX`, "medium" between.
+ *
+ * Two tiers were not enough. With only "narrow" and "not narrow", a widget
+ * alone on a desktop page rendered the layout it would use in a half-width
+ * cell and left the rest of its box empty.
+ *
+ * An unmeasured width (0, before the first `onLayout`) is "wide", for the same
+ * reason `isNarrowWidth(0)` is false: the wide rendering is the historical one,
+ * and a widget using both helpers must never get two different answers.
+ */
+export function widthTier(width) {
+  if (typeof width !== "number" || !(width > 0)) return "wide";
+  if (width < NARROW_WIDTH_PX) return "narrow";
+  if (width < WIDE_WIDTH_PX) return "medium";
+  return "wide";
+}

package/dist/contract.cjs

@@ -771,7 +771,7 @@ const HOOKS = [
       "callback, so ONE implementation serves the web Player (through " +
       "react-native-web) and the native export. Before the first layout the " +
       "width is 0: treat that as \"not yet measured\" and render the wide " +
-      "form. Pair it with `isNarrowWidth(width)` so every widget switches at " +
+      "form. Pair it with `widthTier(width)` (or `isNarrowWidth(width)`) so every widget switches at " +
       "the same threshold. Takes no host context, so it is safe everywhere " +
       "including the Studio canvas.",
     returnShape: {
@@ -796,6 +796,25 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  {
+    name: "widthTier",
+    signature: "widthTier(width)",
+    description:
+      "Which of the THREE layouts a MEASURED width calls for: \"narrow\" " +
+      "below `NARROW_WIDTH_PX` (480), \"wide\" at or above `WIDE_WIDTH_PX` " +
+      "(960), \"medium\" between. A widget alone on a desktop page has far " +
+      "more room than one in a half-width cell, and two tiers treated both " +
+      "the same, so the lone widget left most of its box empty. Branch on " +
+      "this for every list, form, table and filter bar: a form goes one " +
+      "column, then paired fields, then two or three columns; a list goes " +
+      "stacked cards, then one-line cards, then rows with real columns. An " +
+      "unmeasured width (0) is \"wide\", matching `isNarrowWidth(0)`.",
+    returnShape: {
+      "(returns)": "\"narrow\" | \"medium\" | \"wide\"",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useSectionEmpty",
     signature: "useSectionEmpty(isEmpty)",
@@ -1308,7 +1327,12 @@ const HOOKS = [
       "AI_QUOTA_EXCEEDED (429) is the workspace's credit ceiling and will " +
       "NOT clear on a retry — never offer 'try again' for it — where " +
       "RATE_LIMITED (429) will; AGENT_DISABLED (409) means the author turned " +
-      "it off, so hide the affordance rather than retrying. NEVER surface a " +
+      "it off, so hide the affordance rather than retrying; TIMEOUT means the " +
+      "client stopped waiting and the turn is STILL running and billed, so " +
+      "say it is taking longer, never that it failed or that they are " +
+      "offline; CANCELLED is the user pressing your stop control, so render " +
+      "no error at all. Call cancel() to stop waiting -- it ends the WAIT, " +
+      "not the turn. NEVER surface a " +
       "raw error or the workspace's billing state to an app user. " +
       "Reads ctx.agents.",
     returnShape: {
@@ -4232,6 +4256,12 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.121.0: additive (sc-8519) — `useAgent()` returns `cancel()`, which
+  // stops WAITING for the turn in flight. The abort is client-side: the
+  // server finishes the turn and the workspace is billed, so label the
+  // control 'stop', never 'cancel'. Two new AgentError codes ride with it —
+  // TIMEOUT (the client stopped waiting; still running, still billed) and
+  // CANCELLED (the user pressed stop; render no error at all).
   // 1.120.0: additive (sc-8332) — an assistant `AgentMessage` may carry
   // `activity`, a compact record of what the agent DID with the user's data
   // (the table it read; the table and columns it CHANGED). Absent on a
@@ -4298,7 +4328,13 @@ const CONTRACT = deepFreeze({
   //    untouched and renders byte-identically, and an unresolvable binding
   //    fails the existing hex guard, dropping the wash rather than painting it
   //    blank.
-  version: "1.120.0",
+  // 1.122.0: additive (sc-8508) — `widthTier(width)` + `WIDE_WIDTH_PX`, a
+  //    third layout tier. `isNarrowWidth` split widths into "phone" and
+  //    "everything else", so a widget alone on a desktop page rendered the
+  //    layout it would use in a half-width cell. Additive: `isNarrowWidth` and
+  //    `NARROW_WIDTH_PX` are unchanged, and `widthTier(w) === "narrow"` exactly
+  //    when `isNarrowWidth(w)` is true.
+  version: "1.122.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -771,7 +771,7 @@ const HOOKS = [
       "callback, so ONE implementation serves the web Player (through " +
       "react-native-web) and the native export. Before the first layout the " +
       "width is 0: treat that as \"not yet measured\" and render the wide " +
-      "form. Pair it with `isNarrowWidth(width)` so every widget switches at " +
+      "form. Pair it with `widthTier(width)` (or `isNarrowWidth(width)`) so every widget switches at " +
       "the same threshold. Takes no host context, so it is safe everywhere " +
       "including the Studio canvas.",
     returnShape: {
@@ -796,6 +796,25 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  {
+    name: "widthTier",
+    signature: "widthTier(width)",
+    description:
+      "Which of the THREE layouts a MEASURED width calls for: \"narrow\" " +
+      "below `NARROW_WIDTH_PX` (480), \"wide\" at or above `WIDE_WIDTH_PX` " +
+      "(960), \"medium\" between. A widget alone on a desktop page has far " +
+      "more room than one in a half-width cell, and two tiers treated both " +
+      "the same, so the lone widget left most of its box empty. Branch on " +
+      "this for every list, form, table and filter bar: a form goes one " +
+      "column, then paired fields, then two or three columns; a list goes " +
+      "stacked cards, then one-line cards, then rows with real columns. An " +
+      "unmeasured width (0) is \"wide\", matching `isNarrowWidth(0)`.",
+    returnShape: {
+      "(returns)": "\"narrow\" | \"medium\" | \"wide\"",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useSectionEmpty",
     signature: "useSectionEmpty(isEmpty)",
@@ -1308,7 +1327,12 @@ const HOOKS = [
       "AI_QUOTA_EXCEEDED (429) is the workspace's credit ceiling and will " +
       "NOT clear on a retry — never offer 'try again' for it — where " +
       "RATE_LIMITED (429) will; AGENT_DISABLED (409) means the author turned " +
-      "it off, so hide the affordance rather than retrying. NEVER surface a " +
+      "it off, so hide the affordance rather than retrying; TIMEOUT means the " +
+      "client stopped waiting and the turn is STILL running and billed, so " +
+      "say it is taking longer, never that it failed or that they are " +
+      "offline; CANCELLED is the user pressing your stop control, so render " +
+      "no error at all. Call cancel() to stop waiting -- it ends the WAIT, " +
+      "not the turn. NEVER surface a " +
       "raw error or the workspace's billing state to an app user. " +
       "Reads ctx.agents.",
     returnShape: {
@@ -4228,6 +4252,12 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.121.0: additive (sc-8519) — `useAgent()` returns `cancel()`, which
+  // stops WAITING for the turn in flight. The abort is client-side: the
+  // server finishes the turn and the workspace is billed, so label the
+  // control 'stop', never 'cancel'. Two new AgentError codes ride with it —
+  // TIMEOUT (the client stopped waiting; still running, still billed) and
+  // CANCELLED (the user pressed stop; render no error at all).
   // 1.120.0: additive (sc-8332) — an assistant `AgentMessage` may carry
   // `activity`, a compact record of what the agent DID with the user's data
   // (the table it read; the table and columns it CHANGED). Absent on a
@@ -4294,7 +4324,13 @@ const CONTRACT = deepFreeze({
   //    untouched and renders byte-identically, and an unresolvable binding
   //    fails the existing hex guard, dropping the wash rather than painting it
   //    blank.
-  version: "1.120.0",
+  // 1.122.0: additive (sc-8508) — `widthTier(width)` + `WIDE_WIDTH_PX`, a
+  //    third layout tier. `isNarrowWidth` split widths into "phone" and
+  //    "everything else", so a widget alone on a desktop page rendered the
+  //    layout it would use in a half-width cell. Additive: `isNarrowWidth` and
+  //    `NARROW_WIDTH_PX` are unchanged, and `widthTier(w) === "narrow"` exactly
+  //    when `isNarrowWidth(w)` is true.
+  version: "1.122.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2713,7 +2713,15 @@ export function useInterpretDraft(tableId) {
  *   - "AI_UNAVAILABLE"        — 503 (no AI provider configured)
  *   - "AI_GENERATION_FAILED"  — 502 (the provider did not answer)
  *   - "AUTH_REQUIRED"         — 401 (no signed-in app user)
- *   - "INTERNAL"              — anything else (network, 5xx)
+ *   - "NETWORK"               — the request never reached the server
+ *   - "TIMEOUT"               — the client stopped waiting. NOT a failed
+ *                               turn: the server finishes it and the
+ *                               workspace is billed, so say "still
+ *                               working", never "failed"
+ *   - "CANCELLED"             — `cancel()` was called. The user chose it,
+ *                               so render no error at all (the turn is
+ *                               still billed — never imply it stopped)
+ *   - "INTERNAL"              — anything else (a 5xx carrying no code)
  */
 export class AgentError extends Error {
   constructor(code, message, opts) {
@@ -2816,12 +2824,21 @@ export function useAgent(agentRef) {
     pendingResetRef.current = true;
   }
 
+  const abortRef = useRef(null);
+
   const reset = useCallback(() => {
     conversationRef.current = null;
     setMessages([]);
     setError(null);
   }, []);
 
+  // Ends the WAIT, not the turn: the abort never reaches the server, which
+  // finishes and bills it either way. Never imply the work was stopped.
+  const cancel = useCallback(() => {
+    const controller = abortRef.current;
+    if (controller) controller.abort();
+  }, []);
+
   const send = useCallback(async (text) => {
     const client = clientRef.current;
     const agentId = agentIdRef.current;
@@ -2855,7 +2872,13 @@ export function useAgent(agentRef) {
         conversationRef.current = null;
         throw err;
       }
-      const turn = await thread.messages(conversationId).send({ content });
+      const controller =
+        typeof AbortController === "function" ? new AbortController() : null;
+      abortRef.current = controller;
+      const turn = await thread
+        .messages(conversationId)
+        .send({ content }, controller ? { signal: controller.signal } : undefined);
+      abortRef.current = null;
       // A rebind during the round trip makes this the PREVIOUS agent's reply;
       // writing it now would render it under the new one.
       if (agentIdRef.current !== agentId) {
@@ -2874,8 +2897,10 @@ export function useAgent(agentRef) {
       // A stale thread is recoverable on the next send rather than permanently
       // broken: drop it so the widget opens a fresh one.
       if (e.code === "CONVERSATION_NOT_FOUND") conversationRef.current = null;
+      abortRef.current = null;
       // Same rebind guard: a new agent must not inherit the old one's error.
-      if (agentIdRef.current === agentId) setError(e);
+      // A cancel is the user's own choice, so it is not a failure to report.
+      if (e.code !== "CANCELLED" && agentIdRef.current === agentId) setError(e);
       setSending(false);
       throw e;
     }
@@ -2897,6 +2922,7 @@ export function useAgent(agentRef) {
 
   return {
     send,
+    cancel,
     reset,
     messages: visibleMessages,
     sending,

package/dist/index.d.ts

@@ -1239,6 +1239,12 @@ export interface AgentActivity {
 export interface AgentApi {
   /** Imperative — call from an event handler. The first send opens the thread. */
   send(text: string): Promise<AgentMessage | null>;
+  /**
+   * Stop WAITING for the turn in flight. The abort never reaches the server,
+   * which finishes and bills it either way — label the control "stop", not
+   * "cancel", and show no error when the user presses it.
+   */
+  cancel(): void;
   /** Drop the open thread and clear the transcript this widget has seen. */
   reset(): void;
   /** Oldest first. The SERVER owns the real transcript. */
@@ -1557,6 +1563,16 @@ export const NARROW_WIDTH_PX: number;
  */
 export function isNarrowWidth(width: number): boolean;
 
+/** The width at or above which a widget has room for its wide form (960). */
+export const WIDE_WIDTH_PX: number;
+
+/**
+ * Which of the three layouts a MEASURED width calls for: `"narrow"` below
+ * `NARROW_WIDTH_PX`, `"wide"` at or above `WIDE_WIDTH_PX`, `"medium"` between.
+ * An unmeasured width (0) is `"wide"`, matching `isNarrowWidth(0) === false`.
+ */
+export function widthTier(width: number): "narrow" | "medium" | "wide";
+
 /** Pass-through options for `useGeolocation().getCurrentPosition(...)`. */
 export interface GeolocationOptions {
   enableHighAccuracy?: boolean;
@@ -1997,6 +2013,9 @@ export class AgentError extends Error {
     | "AI_UNAVAILABLE"
     | "AI_GENERATION_FAILED"
     | "AUTH_REQUIRED"
+    | "NETWORK"
+    | "TIMEOUT"
+    | "CANCELLED"
     | "INTERNAL"
     | (string & {});
   constructor(code: string, message: string, opts?: { cause?: unknown });

package/dist/index.js

@@ -91,7 +91,12 @@ export {
   BarcodeError,
   WidgetTree,
 } from "./hooks.js";
-export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
+export {
+  isNarrowWidth,
+  NARROW_WIDTH_PX,
+  widthTier,
+  WIDE_WIDTH_PX,
+} from "./container-width.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file
 // (./clipboard.js / .native.js, ./toast.js / .native.js); index.js picks
 // the web variant and index.native.js picks the native variant.

package/dist/index.native.js

@@ -91,7 +91,12 @@ export {
   BarcodeError,
   WidgetTree,
 } from "./hooks.js";
-export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
+export {
+  isNarrowWidth,
+  NARROW_WIDTH_PX,
+  widthTier,
+  WIDE_WIDTH_PX,
+} from "./container-width.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.154.0",
+  "version": "0.156.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",