@colixsystems/widget-sdk 0.227.0 → 0.229.0

package/README.md

@@ -84,7 +84,38 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.227.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.229.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.229.0 (contract unchanged)
+
+**A field's focus ring and a card's border stay inside the widget.** The hosts clip a widget at its own edge, so anything painted outside it is cut off.
+
+- **`<TextField>` and the `<Select>` trigger draw focus inside their own box.** A focused field shows a 2px ring in the accent: its border plus an inset 1px `boxShadow`, in the error colour while the field is invalid. On the web it turns the browser's outer focus outline off, because that outline sat outside the field and was cut off wherever the field touched the widget's edge. `<SearchField>` and the built-in form fields use the same field, so they get it too. The text field also takes `minWidth: 0`, so it shrinks in a row instead of pushing its neighbour past the edge. A caller's `style` still comes last.
+- **New linter rule `full-width-margin-overflow` (severity `warning`, non-blocking).** It flags a style object that sets `width: "100%"` together with a non-zero side margin (`margin`, `marginHorizontal`, `marginLeft`/`Right`/`Start`/`End`, `marginInline`/`InlineStart`/`InlineEnd`; a zero, `undefined` or `null` value is not counted). The percentage is already the parent's whole width, so the margin pushes the box past its parent and the host cuts off its right edge, border included. Drop the width, because a `View` already stretches, and inset with the parent's `padding`. The scan reads one style literal, not the tree, so it stays a warning. Comments are not scanned.
+
+`CONTRACT` is unchanged (no new field), and no export changed signature.
+
+### What's new in 0.228.0 (contract 1.184.0)
+
+**A widget can ask for the whole screen — manifest `prefersFitToScreen` and `useFitScreen()`.** A page section can be set to "Fit to screen": it runs edge to edge across the app's content area (no page margins, no width cap) and takes the rest of the screen below the sections above it, on every screen size, in the Player and in the exported app. Set `prefersFitToScreen: true` in your manifest when your widget is built for that — it scrolls its own content inside the height it is given and keeps its controls in view, like a messenger, a map or a full-height board. In a fit section the host then gives your widget a box exactly the height left; a widget without the field grows with its content there, and the page scrolls. A maker who drops your widget at the top level of a page then gets the setting turned on for that section (they can switch it off, and it stays off), and the AppStudio app-builder fits the section it plans your widget into. Leave it `false` or omit it otherwise.
+
+When your widget is that section's surface, `useFill()` is `true` and so is the new `useFitScreen()`. Drop your own frame then — border, rounded corners, shadow — so the widget meets the screen's edges cleanly; the host has already removed your outer margin.
+
+```jsx
+import { useFill, useFitScreen, View } from "@colixsystems/widget-sdk";
+
+export default function Board() {
+  const fill = useFill();
+  const edgeToEdge = useFitScreen();
+  return (
+    <View style={[fill ? { flex: 1, minHeight: 0 } : { height: 480 }, !edgeToEdge && { borderWidth: 1, borderRadius: 12 }]}>
+      {/* ... */}
+    </View>
+  );
+}
+```
+
+Additive: existing manifests omit the field and read `false`, and a host that never fits a widget leaves both hooks `false`. A published widget that must also run in an app whose Player is older than 0.228.0 reads the hook off a namespace import and treats a missing one as `false` (`import * as sdk from "@colixsystems/widget-sdk"; const useFitScreen = typeof sdk.useFitScreen === "function" ? sdk.useFitScreen : () => false;`, at module level): a named import of an export the host does not have stops the widget loading.
 
 ### What's new in 0.227.0 (contract 1.183.0)
 

package/dist/contract.cjs

@@ -991,6 +991,24 @@ const HOOKS = [
     requiredContextSlice: ["fill"],
     scopes: null,
   },
+  {
+    name: "useFitScreen",
+    signature: "useFitScreen()",
+    description:
+      "Returns true when this widget is the surface of a page section set to " +
+      "\"Fit to screen\": the section runs edge to edge across the app's " +
+      "content area and takes the rest of the screen, so the widget should " +
+      "drop its own frame (border, rounded corners, shadow) and meet the " +
+      "edges cleanly. useFill() is true as well then, and the host has already " +
+      "removed the widget's outer margin. Defaults to false wherever the host " +
+      "has not fitted the widget, so calling it is always safe. The SAME value " +
+      "is injected by the web Player and the native export.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fitScreen"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -3572,6 +3590,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
+  prefersFitToScreen: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -3647,6 +3672,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11348 — optional host hint backing useFitScreen(): the widget is the
+  // surface of a section set to Fit to screen, so it drops its own frame.
+  fitScreen: {
+    description:
+      "Optional host layout hint (boolean). True when this widget is the " +
+      "surface of a page section set to Fit to screen: edge to edge, the rest " +
+      "of the screen. Backs useFitScreen(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -5938,7 +5973,12 @@ const CONTRACT = deepFreeze({
   //    `copyOf: { via, column }` (a server-kept copy read through one), and
   //    a table may declare `constraints` (`unique` with `unlessRelated`,
   //    `no-overlap`, `related-open`, `related-index`).
-  version: "1.183.0",
+  // 1.184.0: additive (sc-11348) — OPTIONAL manifest field
+  //    `prefersFitToScreen` (dropping the widget at a page's top level turns
+  //    that section's Fit to screen on), and `useFitScreen()` with its
+  //    optional `fitScreen` host hint: the widget is a fit section's surface,
+  //    so it drops its own frame. Existing manifests and hosts read false.
+  version: "1.184.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -991,6 +991,24 @@ const HOOKS = [
     requiredContextSlice: ["fill"],
     scopes: null,
   },
+  {
+    name: "useFitScreen",
+    signature: "useFitScreen()",
+    description:
+      "Returns true when this widget is the surface of a page section set to " +
+      "\"Fit to screen\": the section runs edge to edge across the app's " +
+      "content area and takes the rest of the screen, so the widget should " +
+      "drop its own frame (border, rounded corners, shadow) and meet the " +
+      "edges cleanly. useFill() is true as well then, and the host has already " +
+      "removed the widget's outer margin. Defaults to false wherever the host " +
+      "has not fitted the widget, so calling it is always safe. The SAME value " +
+      "is injected by the web Player and the native export.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fitScreen"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -3568,6 +3586,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
+  prefersFitToScreen: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -3643,6 +3668,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11348 — optional host hint backing useFitScreen(): the widget is the
+  // surface of a section set to Fit to screen, so it drops its own frame.
+  fitScreen: {
+    description:
+      "Optional host layout hint (boolean). True when this widget is the " +
+      "surface of a page section set to Fit to screen: edge to edge, the rest " +
+      "of the screen. Backs useFitScreen(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -5934,7 +5969,12 @@ const CONTRACT = deepFreeze({
   //    `copyOf: { via, column }` (a server-kept copy read through one), and
   //    a table may declare `constraints` (`unique` with `unlessRelated`,
   //    `no-overlap`, `related-open`, `related-index`).
-  version: "1.183.0",
+  // 1.184.0: additive (sc-11348) — OPTIONAL manifest field
+  //    `prefersFitToScreen` (dropping the widget at a page's top level turns
+  //    that section's Fit to screen on), and `useFitScreen()` with its
+  //    optional `fitScreen` host hint: the widget is a fit section's surface,
+  //    so it drops its own frame. Existing manifests and hosts read false.
+  version: "1.184.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/form-control-tokens.js

@@ -71,6 +71,26 @@ export function focusHaloStyle(t, focused, radius) {
   };
 }
 
+// Web: a field shell draws its own ring, so the host's outer one stays off.
+export const FIELD_OUTLINE_OFF = Object.freeze({ outlineColor: "transparent" });
+
+/**
+ * A field shell's state border (`<TextField>`, a `<Select>` trigger). Focus is
+ * the border plus an inset 1px ring, 2px in all and inside the box, so a parent
+ * clipping at the field's edge cannot cut it. An invalid field rings in the
+ * error colour while it is being fixed.
+ *
+ * @param {object} t — resolved form-control tokens.
+ * @param {{focused: boolean, invalid: boolean}} state
+ */
+export function fieldStateStyle(t, { focused, invalid }) {
+  if (focused) {
+    const color = invalid ? t.errorColor : t.focusColor;
+    return { borderColor: color, boxShadow: `inset 0 0 0 1px ${color}` };
+  }
+  return invalid ? { borderColor: t.errorColor } : null;
+}
+
 /**
  * The colours a switch hands the platform control. A caller's `trackColor`
  * overrides the theme per state, and iOS, which paints the off track from

package/dist/hooks.js

@@ -488,6 +488,19 @@ export function useFill() {
   return ctx.fill === true;
 }
 
+/**
+ * Returns `true` when this widget is the surface of a page section set to
+ * "Fit to screen": the section runs edge to edge across the app's content
+ * area and takes the rest of the screen. Drop the widget's own frame then —
+ * border, rounded corners, shadow — so it meets the edges cleanly; `useFill()`
+ * is `true` as well, and the host has already removed the outer margin.
+ * Defaults to `false`, and both hosts inject the same value.
+ */
+export function useFitScreen() {
+  const ctx = useWidgetContextOrThrow("useFitScreen");
+  return ctx.fitScreen === true;
+}
+
 /**
  * Returns the host's child-node renderer:
  *   { renderNode(node) }.

package/dist/index.d.ts

@@ -462,6 +462,13 @@ export interface WidgetManifest {
    * while the widget's page is closed so its menu badge stays live.
    */
   badgeCounter?: boolean;
+  /**
+   * Optional (sc-11348, default false). True when the widget owns the rest of
+   * the screen (a messenger, a map): dropping it at the top level of a page
+   * turns that section's "Fit to screen" on. Honour `useFill()` and
+   * `useFitScreen()` with it.
+   */
+  prefersFitToScreen?: boolean;
 }
 
 /**
@@ -786,6 +793,12 @@ export interface WidgetContext<TProps = unknown> {
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
+  /**
+   * sc-11348 — optional host hint backing `useFitScreen()`: `true` when this
+   * widget is the surface of a section set to Fit to screen (edge to edge,
+   * the rest of the screen). Absent / `false` everywhere else.
+   */
+  fitScreen?: boolean;
   /** Active end-user identity from the host-built context (camelCase, not a wire payload). `id` is null when anonymous. */
   user: {
     id: string | null;
@@ -2139,6 +2152,14 @@ export function useAnonymousAccount(): AnonymousAccountApi;
  */
 export function useFill(): boolean;
 
+/**
+ * sc-11348 — returns `true` when this widget is the surface of a page section
+ * set to "Fit to screen": it runs edge to edge and takes the rest of the
+ * screen, so drop your own frame (border, rounded corners, shadow).
+ * `useFill()` is `true` too. Defaults to `false`; the same on web and native.
+ */
+export function useFitScreen(): boolean;
+
 /**
  * The host-provided navigation surface. `goTo(pageId, params?)` navigates
  * to an internal app page; `goBack()` pops the stack. `goToStartPage()`

package/dist/index.js

@@ -80,6 +80,7 @@ export {
   useUserPhoto,
   useAnonymousAccount,
   useFill,
+  useFitScreen,
   useNavigation,
   useRouteParams,
   usePageBadge,

package/dist/index.native.js

@@ -80,6 +80,7 @@ export {
   useUserPhoto,
   useAnonymousAccount,
   useFill,
+  useFitScreen,
   useNavigation,
   useRouteParams,
   usePageBadge,

package/dist/linter.cjs

@@ -1477,6 +1477,92 @@ function _flexBasisPercentRules(source) {
   return findings;
 }
 
+// sc-11277 — `width: "100%"` plus a side margin is wider than its parent.
+//
+// The percentage is the parent's whole content width and the margin is added
+// outside it, so the box overflows by the margin. The hosts clip a widget at
+// its own edge (the Player's sideways guard, a fixed-height slot), which cuts
+// off the right edge of a bordered card or input. A `View` already stretches
+// across a column, so the width is redundant; the inset belongs in the
+// parent's padding.
+//
+// A warning: the scan reads one style literal, not the tree, so a row parent
+// that absorbs the excess still matches.
+const _FULL_WIDTH_RE = /\bwidth\s*:\s*(["'`])100%\1/g;
+const _SIDE_MARGIN_KEY_RE =
+  /\bmargin(?:Horizontal|Left|Right|Start|End|Inline(?:Start|End)?)?\s*:/g;
+const _ZERO_VALUE_RE =
+  /^\s*(?:(["'`]?)-?0(?:\.0*)?(?:px)?\1\s*(?:[,}]|$)|(?:undefined|null)\b)/m;
+
+// The innermost `{ … }` around `at`, as [start, end); null outside any.
+function _enclosingObject(code, at) {
+  let start = -1;
+  for (let i = at - 1, depth = 0; i >= 0; i--) {
+    if (code[i] === "}") depth++;
+    else if (code[i] === "{" && depth-- === 0) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  for (let j = at, depth = 0; j < code.length; j++) {
+    if (code[j] === "{") depth++;
+    else if (code[j] === "}" && depth-- === 0) return [start, j + 1];
+  }
+  return null;
+}
+
+// The object's own keys only: a nested object's margin is not this box's.
+// Blanked rather than cut, so an offset here is the same offset in the source.
+function _ownKeysMask(structure, [start, end]) {
+  let body = structure.slice(start, end);
+  let previous;
+  do {
+    previous = body;
+    body = body.replace(/(?<!^)\{[^{}]*\}(?!$)/g, (nested) => " ".repeat(nested.length));
+  } while (body !== previous);
+  return body;
+}
+
+function _hasSideMargin(code, structure, span) {
+  const keys = _ownKeysMask(structure, span);
+  _SIDE_MARGIN_KEY_RE.lastIndex = 0;
+  let key;
+  while ((key = _SIDE_MARGIN_KEY_RE.exec(keys))) {
+    const valueAt = span[0] + key.index + key[0].length;
+    if (!_ZERO_VALUE_RE.test(code.slice(valueAt, valueAt + 40))) return true;
+  }
+  return false;
+}
+
+function _fullWidthMarginRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source, { keepStrings: true });
+  // Strings blanked, so a brace inside a literal never unbalances the match.
+  const structure = _stripNonCode(source);
+  const sourceLines = source.split(/\r?\n/);
+  _FULL_WIDTH_RE.lastIndex = 0;
+  let hit;
+  while ((hit = _FULL_WIDTH_RE.exec(code))) {
+    const span = _enclosingObject(structure, hit.index);
+    if (!span) continue;
+    if (!_hasSideMargin(code, structure, span)) continue;
+    const line = code.slice(0, hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "full-width-margin-overflow",
+      severity: "warning",
+      label:
+        `width: "100%" plus a side margin is wider than the parent by that ` +
+        `margin, so the host clips the box's right edge and its border. Drop ` +
+        `the width (a View already stretches) or move the inset to the ` +
+        `parent's padding.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding, so cells sized
 // from it overflow the content box and the last one wraps into an empty column.
 // Mirror of linter.js (see there for the full rationale).
@@ -2100,6 +2186,8 @@ function lintSource(source, options) {
   // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
   // column it claims the parent's whole height and overflows.
   findings.push(..._flexBasisPercentRules(source));
+  // sc-11277 — soft warning: a full-width box with a side margin is clipped.
+  findings.push(..._fullWidthMarginRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/linter.js

@@ -1518,6 +1518,92 @@ function _flexBasisPercentRules(source) {
   return findings;
 }
 
+// sc-11277 — `width: "100%"` plus a side margin is wider than its parent.
+//
+// The percentage is the parent's whole content width and the margin is added
+// outside it, so the box overflows by the margin. The hosts clip a widget at
+// its own edge (the Player's sideways guard, a fixed-height slot), which cuts
+// off the right edge of a bordered card or input. A `View` already stretches
+// across a column, so the width is redundant; the inset belongs in the
+// parent's padding.
+//
+// A warning: the scan reads one style literal, not the tree, so a row parent
+// that absorbs the excess still matches.
+const _FULL_WIDTH_RE = /\bwidth\s*:\s*(["'`])100%\1/g;
+const _SIDE_MARGIN_KEY_RE =
+  /\bmargin(?:Horizontal|Left|Right|Start|End|Inline(?:Start|End)?)?\s*:/g;
+const _ZERO_VALUE_RE =
+  /^\s*(?:(["'`]?)-?0(?:\.0*)?(?:px)?\1\s*(?:[,}]|$)|(?:undefined|null)\b)/m;
+
+// The innermost `{ … }` around `at`, as [start, end); null outside any.
+function _enclosingObject(code, at) {
+  let start = -1;
+  for (let i = at - 1, depth = 0; i >= 0; i--) {
+    if (code[i] === "}") depth++;
+    else if (code[i] === "{" && depth-- === 0) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  for (let j = at, depth = 0; j < code.length; j++) {
+    if (code[j] === "{") depth++;
+    else if (code[j] === "}" && depth-- === 0) return [start, j + 1];
+  }
+  return null;
+}
+
+// The object's own keys only: a nested object's margin is not this box's.
+// Blanked rather than cut, so an offset here is the same offset in the source.
+function _ownKeysMask(structure, [start, end]) {
+  let body = structure.slice(start, end);
+  let previous;
+  do {
+    previous = body;
+    body = body.replace(/(?<!^)\{[^{}]*\}(?!$)/g, (nested) => " ".repeat(nested.length));
+  } while (body !== previous);
+  return body;
+}
+
+function _hasSideMargin(code, structure, span) {
+  const keys = _ownKeysMask(structure, span);
+  _SIDE_MARGIN_KEY_RE.lastIndex = 0;
+  let key;
+  while ((key = _SIDE_MARGIN_KEY_RE.exec(keys))) {
+    const valueAt = span[0] + key.index + key[0].length;
+    if (!_ZERO_VALUE_RE.test(code.slice(valueAt, valueAt + 40))) return true;
+  }
+  return false;
+}
+
+function _fullWidthMarginRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source, { keepStrings: true });
+  // Strings blanked, so a brace inside a literal never unbalances the match.
+  const structure = _stripNonCode(source);
+  const sourceLines = source.split(/\r?\n/);
+  _FULL_WIDTH_RE.lastIndex = 0;
+  let hit;
+  while ((hit = _FULL_WIDTH_RE.exec(code))) {
+    const span = _enclosingObject(structure, hit.index);
+    if (!span) continue;
+    if (!_hasSideMargin(code, structure, span)) continue;
+    const line = code.slice(0, hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "full-width-margin-overflow",
+      severity: "warning",
+      label:
+        `width: "100%" plus a side margin is wider than the parent by that ` +
+        `margin, so the host clips the box's right edge and its border. Drop ` +
+        `the width (a View already stretches) or move the inset to the ` +
+        `parent's padding.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding.
 //
 // `onLayout` reports the frame width, and padding sits inside that frame. A
@@ -2168,6 +2254,8 @@ export function lintSource(source, options) {
   // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
   // column it claims the parent's whole height and overflows.
   findings.push(..._flexBasisPercentRules(source));
+  // sc-11277 — soft warning: a full-width box with a side margin is clipped.
+  findings.push(..._fullWidthMarginRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/manifest.cjs

@@ -331,6 +331,12 @@ function validateManifest(m) {
     "manifest.badgeCounter must be a boolean when present",
   );
 
+  pushIf(
+    errors,
+    manifest.prefersFitToScreen === undefined || typeof manifest.prefersFitToScreen === "boolean",
+    "manifest.prefersFitToScreen must be a boolean when present",
+  );
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/manifest.js

@@ -377,6 +377,12 @@ function validateManifest(m) {
     "manifest.badgeCounter must be a boolean when present",
   );
 
+  pushIf(
+    errors,
+    manifest.prefersFitToScreen === undefined || typeof manifest.prefersFitToScreen === "boolean",
+    "manifest.prefersFitToScreen must be a boolean when present",
+  );
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/select-view.js

@@ -13,6 +13,8 @@ import { Icon } from "./icon.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
 import {
   CONTROL_MIN_TARGET,
+  FIELD_OUTLINE_OFF,
+  fieldStateStyle,
   nextOptionIndex,
   resolveFormControlTokens,
   selectedOption,
@@ -253,8 +255,8 @@ export function makeSelect(rn) {
               borderRadius: t.radius,
               backgroundColor: t.background,
             },
-            focused ? { borderColor: t.focusColor } : null,
-            invalid ? { borderColor: t.errorColor } : null,
+            FIELD_OUTLINE_OFF,
+            fieldStateStyle(t, { focused, invalid }),
             style,
           ],
         },

package/dist/text-field-view.js

@@ -6,7 +6,11 @@ import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
-import { resolveFormControlTokens } from "./form-control-tokens.js";
+import {
+  FIELD_OUTLINE_OFF,
+  fieldStateStyle,
+  resolveFormControlTokens,
+} from "./form-control-tokens.js";
 import {
   errorMessage,
   hasNote,
@@ -45,7 +49,6 @@ export function makeTextField(rn) {
       ...others
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
-    // Native draws no focus ring, so the border itself shows focus.
     const [focused, setFocused] = React.useState(false);
     const overrides = {};
     const rest = {};
@@ -80,10 +83,11 @@ export function makeTextField(rn) {
           color: t.textColor,
           fontFamily: t.fontFamily,
           fontSize: t.fontSize,
+          // An input will not shrink below its text width in a row otherwise.
+          minWidth: 0,
         },
-        focused ? { borderColor: t.focusColor } : null,
-        // After focus: an invalid field stays marked while it is being fixed.
-        invalid ? { borderColor: t.errorColor } : null,
+        FIELD_OUTLINE_OFF,
+        fieldStateStyle(t, { focused, invalid }),
         // The frame dims a framed field as a whole.
         disabled && !framed ? { opacity: t.disabledOpacity } : null,
         style,

package/package.json

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

package/src/contract.js

@@ -991,6 +991,24 @@ const HOOKS = [
     requiredContextSlice: ["fill"],
     scopes: null,
   },
+  {
+    name: "useFitScreen",
+    signature: "useFitScreen()",
+    description:
+      "Returns true when this widget is the surface of a page section set to " +
+      "\"Fit to screen\": the section runs edge to edge across the app's " +
+      "content area and takes the rest of the screen, so the widget should " +
+      "drop its own frame (border, rounded corners, shadow) and meet the " +
+      "edges cleanly. useFill() is true as well then, and the host has already " +
+      "removed the widget's outer margin. Defaults to false wherever the host " +
+      "has not fitted the widget, so calling it is always safe. The SAME value " +
+      "is injected by the web Player and the native export.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fitScreen"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -3568,6 +3586,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
+  prefersFitToScreen: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -3643,6 +3668,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11348 — optional host hint backing useFitScreen(): the widget is the
+  // surface of a section set to Fit to screen, so it drops its own frame.
+  fitScreen: {
+    description:
+      "Optional host layout hint (boolean). True when this widget is the " +
+      "surface of a page section set to Fit to screen: edge to edge, the rest " +
+      "of the screen. Backs useFitScreen(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -5934,7 +5969,12 @@ const CONTRACT = deepFreeze({
   //    `copyOf: { via, column }` (a server-kept copy read through one), and
   //    a table may declare `constraints` (`unique` with `unlessRelated`,
   //    `no-overlap`, `related-open`, `related-index`).
-  version: "1.183.0",
+  // 1.184.0: additive (sc-11348) — OPTIONAL manifest field
+  //    `prefersFitToScreen` (dropping the widget at a page's top level turns
+  //    that section's Fit to screen on), and `useFitScreen()` with its
+  //    optional `fitScreen` host hint: the widget is a fit section's surface,
+  //    so it drops its own frame. Existing manifests and hosts read false.
+  version: "1.184.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,