@colixsystems/widget-sdk 0.85.1 → 0.87.0

package/dist/contract.js

@@ -72,6 +72,9 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   }),
   elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
+  // REQ-THEME-LOOK: multiplies every layout spacing value at render. 1 is
+  // unchanged, so a theme that never sets it renders exactly as before.
+  spacingScale: 1,
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
     fontFamily:
@@ -86,6 +89,12 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   // host so ONE channel carries them to the Player and the export. Empty by
   // default — an unconfigured theme resolves to no component overrides.
   components: Object.freeze({}),
+  // REQ-THEME-ELEMENT: the tenant's per-WIDGET-TYPE style values, keyed by
+  // manifest id. `components` above restyles a whole scope through a shared
+  // vocabulary, which only reaches a widget the vocabulary knows about; this
+  // reaches ANY widget by naming it, using that widget's OWN styleSchema field
+  // names. Empty by default.
+  widgetStyles: Object.freeze({}),
 });
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
@@ -130,6 +139,32 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   defaultAngle: 180,
 });
 
+// REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
+// NODES -- a container states its own `padding` / `gap` / `margin` -- so a plain
+// theme key could never make an existing app breathe: every node already
+// carried a value and there was no default left to change. This scales those
+// node values at RENDER time instead, on both hosts, which is why it moves a
+// page that was authored long ago. SPACING only -- never radii, font sizes or
+// minHeight -- so a look keeps its shape while its air moves, and the author’s
+// relative proportions survive: a tight table stays tighter than the card
+// beside it.
+// REQ-THEME-ELEMENT: bounds on the per-widget-type style map. `theme_config` is
+// an unbounded JSON bag that an UNAUTHENTICATED GET /tenant/config returns on
+// every cold Player start and that the compiler bakes verbatim into the native
+// export -- so a map that grows with the widget catalog needs a stated ceiling.
+// Declared here so the coercer, the Studio control and the planner prompt agree.
+const THEME_WIDGET_STYLES = Object.freeze({
+  // One entry per widget TYPE, not per instance, so this is generous.
+  maxWidgets: 200,
+  // Matches the styleSchema field cap the widget agent is held to.
+  maxFieldsPerWidget: 12,
+});
+const THEME_SPACING_SCALE = Object.freeze({
+  min: 0.5,
+  max: 2,
+  default: 1,
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -159,6 +194,23 @@ const FORM_SUBMIT_FIELDS = Object.freeze({
   gradient: "submitGradient",
 });
 
+// REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
+// ANY widget that reads them -- including a Mason-generated one, whose id can
+// never appear in a hand-maintained allowlist. That allowlist is why "make the
+// cards darker" reached the nine built-ins and nothing else.
+//
+// `shadow` is deliberately ABSENT: its name is bare and shared with the button
+// scope, so binding it by name would cross the scopes. The bare names stay on
+// the allowlist for exactly that reason -- `appstudio.image` also reads a
+// `background` field, and the button scope must not leak into it.
+const CARD_UNIVERSAL_FIELDS = Object.freeze({
+  background: "cardBackground",
+  borderColor: "cardBorderColor",
+  radius: "cardRadius",
+  padding: "cardPadding",
+  gradient: "cardGradient",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -187,6 +239,7 @@ const THEME_COMPONENTS = Object.freeze({
   }),
   card: Object.freeze({
     label: "Cards",
+    universalFields: CARD_UNIVERSAL_FIELDS,
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
@@ -243,8 +296,18 @@ const HOOKS = [
     signature: "useTheme()",
     returnShape: {
       colors:
-        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }",
+        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info } — " +
+        "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
+        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "page: a container painting its own background re-derives them for its " +
+        "subtree. Read them and your text is readable wherever the widget lands; " +
+        "there is nothing to opt into.",
       spacing: "{ xs, sm, md, lg, xl }",
+      spacingScale:
+        "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
+        "HOST-OWNED: the host already scales layout spacing by it. Read it only " +
+        "if your widget draws its own internal spacing and wants to breathe with " +
+        "the rest of the app.",
       radii: "{ sm, md, lg, pill }",
       typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
       components:
@@ -436,6 +499,7 @@ const HOOKS = [
     signature: "useNavigation()",
     returnShape: {
       goTo: "(pageId: string, params?: object) => void",
+      openLink: "(link: string) => boolean",
       goBack: "() => void",
       push: "(pageId: string, params?: object) => void",
       replace: "(pageId: string, params?: object) => void",
@@ -1091,10 +1155,12 @@ const HOOKS = [
     description:
       "Surfaces a short auto-dismissing notification. Returns { showToast }. " +
       "showToast({ kind: 'success' | 'error' | 'info' | 'warning', message }) " +
-      "asks the host to render a workspace-themed toast. If the host hasn't " +
-      "wired a renderer, the web variant dispatches an 'appstudio:widget-toast' " +
-      "CustomEvent on window; native logs to the console. The widget never " +
-      "owns the toast UI — that's the host's responsibility.",
+      "renders a workspace-themed toast. Both shipping hosts paint it — the " +
+      "web Player and the exported Expo app — so a confirmation you raise IS " +
+      "seen by the user; use it to confirm every write. The widget never owns " +
+      "the toast UI, so never build your own banner or call Alert.alert for a " +
+      "routine save. An authoring preview (the Studio canvas) wires no " +
+      "renderer, and there the call is simply a no-op.",
     returnShape: {
       showToast: "({ kind, message }) => void",
     },
@@ -1658,9 +1724,10 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Optional host toast slot. { showToast({ kind, message }): void }. " +
       "The host populates this to render workspace-themed notifications " +
-      "from any widget that calls useToast(). When omitted the SDK falls " +
-      "back to dispatching an 'appstudio:widget-toast' CustomEvent on web " +
-      "and console.log on native.",
+      "from any widget that calls useToast(). Both rendering hosts wire it " +
+      "(the web Player and the compiler's native WidgetHost); authoring " +
+      "surfaces omit it, and the SDK then falls back to dispatching an " +
+      "'appstudio:widget-toast' CustomEvent on web and console.log on native.",
     required: false,
     fields: { showToast: "function" },
   },
@@ -2635,6 +2702,28 @@ const CONTRACT = deepFreeze({
   //    public endpoint instead, which skips the cache, the metering and the
   //    workspace's provider. Publishing the host list here keeps the linter,
   //    the Developer guide and the agent prompt reading one source.
+  // 1.52.0: additive (REQ-THEME-LOOK) -- `themeTokens.spacingScale` (default 1)
+  //    and `themeSpacingScale`, its clamp bounds. A spacing control in the
+  //    Studio could reach nothing that mattered, because layout spacing is
+  //    authored ONTO each node (`padding` / `gap` / `margin`) rather than
+  //    inherited from the theme -- so no theme key could make a built app
+  //    breathe. Both hosts now multiply a node’s resolved spacing by this scale
+  //    at render. SPACING only: radii, font sizes and minHeight are untouched,
+  //    so a look keeps its shape and the author’s proportions hold. Additive:
+  //    no export changed signature and a theme without the key resolves to 1,
+  //    rendering identically to before.
+  // 1.53.0: fix (REQ-THEME-17) -- `isHexColor` accepts the 8-digit
+  //    `#RRGGBBAA` form. The Studio has put an opacity row on every colour
+  //    field since sc-4158, so a brand colour or a page background routinely
+  //    arrives with alpha -- and this predicate rejecting it made
+  //    `themeConfigToTokens` DROP the key, so a translucent dark background
+  //    stopped reaching deriveSurfaceTokens and every panel fell back to white.
+  //    A second, alpha-aware predicate already existed beside it for gradients,
+  //    which is why the asymmetry kept being rediscovered surface by surface;
+  //    there is now one. `hexChannels` ignores the alpha pair, so contrast and
+  //    the derived tints still reason about the opaque colour while the value
+  //    keeps its transparency. Widening only: every input accepted before is
+  //    accepted now, and unchanged.
   // 1.54.0: additive (sc-4399, epic 4395) — `useContainerWidth()` +
   //    `isNarrowWidth(width)` / `NARROW_WIDTH_PX`. Built-in widgets laid
   //    themselves out at a fixed size — UserManagement's rows alone carried
@@ -2666,7 +2755,36 @@ const CONTRACT = deepFreeze({
   //    Developer guide have always said, so a widget written against the
   //    declared shape destructured a function and threw on first interaction.
   //    Declared as a bare callable now; no runtime behaviour changed.
-  version: "1.60.1",
+  // 1.61.0: additive (REQ-THEME-SURFACE / -CARD / -WIDGET / -ELEMENT) -- the
+  //    theme reaches the elements an app is built from. Four things it could
+  //    not touch before, and one mechanism each:
+  //    * `deriveSurfaceTokens` (host export) -- the surface/text/border set is
+  //      derived per PAINTED SURFACE, not once per page, so an UNSET text
+  //      colour is readable inside a coloured container. It was a hand-mirrored
+  //      copy per host; now one symmetric implementation (a light fill resolves
+  //      to the light tokens instead of returning null).
+  //    * `themeComponents.card.universalFields` -- the card scope's unambiguous
+  //      field NAMES bind to any widget that declares them, so a widget whose id
+  //      can never appear in a hand-maintained allowlist still follows "Cards".
+  //      The bare names (`background`, `textColor`, `color`, `fontSize`,
+  //      `shadow`) keep the allowlist: they mean different things per scope.
+  //      `applyThemeComponentStyle` takes an optional 4th `styleSchema` so the
+  //      name-bound fields land only on a widget that reads them.
+  //    * `themeTokens.widgetStyles` + `themeWidgetStyles` bounds +
+  //      `normaliseWidgetStyles` (host export) -- app-wide values keyed by
+  //      widget MANIFEST ID and then by that widget's OWN styleSchema field
+  //      names, so `panelFill` is as reachable as `cardBackground`: no shared
+  //      vocabulary, no allowlist, no naming requirement. Validated
+  //      structurally, because the key space is a workspace's widget catalog
+  //      rather than this contract, and bounded because `theme_config` is
+  //      unbounded, read unauthenticated on every cold Player start, and baked
+  //      verbatim into the native export.
+  //    Precedence: contract default -> palette -> `components.<scope>` ->
+  //    `widgetStyles[manifestId]` -> the author's per-instance `props.style`.
+  //    Naming one widget is strictly more specific than restyling a scope, and
+  //    the Properties Panel stays the final word. Additive throughout: a theme
+  //    that sets none of it resolves exactly as before.
+  version: "1.61.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2681,6 +2799,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeSpacingScale: THEME_SPACING_SCALE,
+  themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2720,12 +2840,31 @@ function requiredContextKeys() {
 // one source removes that drift (CLAUDE.md §3).
 // ---------------------------------------------------------------------------
 
-const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+// REQ-THEME-17 / sc-4158 — 3, 6 or 8 digits. The 8-digit form carries alpha,
+// and this predicate accepting it is load-bearing: the Studio puts an opacity
+// row on every colour field, so `primaryColor` and `backgroundColor` routinely
+// arrive as `#RRGGBBAA`. While this rejected them, `themeConfigToTokens` DROPPED
+// the key outright — a translucent page background stopped reaching
+// deriveSurfaceTokens and every panel in the app fell back to white.
+//
+// There used to be a second, alpha-aware predicate beside this one for
+// gradients, which is how the asymmetry kept being rediscovered: each new
+// alpha-carrying surface met the strict one first. There is now only this.
+const HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 
 function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+/**
+ * The R/G/B bytes, with any alpha pair IGNORED.
+ *
+ * Deliberate: everything downstream of this is luminance maths — contrast,
+ * readable text, derived tints — and none of it can composite without knowing
+ * the backdrop, which a token table does not have. Alpha survives in the VALUE
+ * (the host hands `#RRGGBBAA` straight to the renderer); it just takes no part
+ * in deciding whether a colour reads as light or dark.
+ */
 function hexChannels(hex) {
   let h = hex.slice(1);
   if (h.length === 3) {
@@ -2810,6 +2949,54 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// REQ-THEME-SURFACE: how far a derived surface travels toward white, and the
+// light-on-dark text pair a dark surface carries.
+const SURFACE_LIFT = Object.freeze({ surface: 0.1, surfaceMuted: 0.05, border: 0.18 });
+const DARK_SURFACE_TEXT = Object.freeze({
+  onSurface: "#f8fafc",
+  onSurfaceMuted: "#cbd5e1",
+});
+
+/**
+ * REQ-THEME-DARK: the coherent surface / text / border set one background wants.
+ * A dark background lifts its panels toward white and goes light-on-dark; a
+ * light one resolves to the contract's own light tokens.
+ *
+ * REQ-THEME-SURFACE: applied to the PAGE background and — because every surface
+ * a page is built from may paint its own fill — to a CONTAINER background too.
+ * That is what makes an UNSET text colour readable inside a dark card on a light
+ * page, which is in turn what lets a built app follow its theme instead of
+ * carrying a baked-in hex for every heading.
+ *
+ * Returns all five keys together, never a subset: layering a dark card's text
+ * colour over a light ancestor's surface is exactly how light-on-light happens.
+ * `null` only when the colour is unusable, letting the caller keep what it had.
+ */
+function deriveSurfaceTokens(backgroundColor) {
+  if (!isHexColor(backgroundColor)) return null;
+  // "Dark" = the background wants light text (same luminance test as the
+  // on-color contrast picker).
+  const wantsLightText =
+    readableTextColor(backgroundColor, "__dark__", "__light__") === "__light__";
+  if (!wantsLightText) {
+    const base = DEFAULT_THEME_TOKENS.colors;
+    return {
+      surface: base.surface,
+      surfaceMuted: base.surfaceMuted,
+      onSurface: base.onSurface,
+      onSurfaceMuted: base.onSurfaceMuted,
+      border: base.border,
+    };
+  }
+  return {
+    surface: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surface),
+    surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
+    onSurface: DARK_SURFACE_TEXT.onSurface,
+    onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
+  };
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -2828,9 +3015,10 @@ function gradientAngleToVector(angle) {
   };
 }
 
-// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
-// persists 8-digit component colours; the host must not drop what it accepted.
-const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+// Gradients used to need their own alpha-aware predicate because HEX_RE was not.
+// HEX_RE is now, so this is the same check by another name — kept only as a
+// local alias so the call sites below read as before.
+const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
@@ -2855,8 +3043,33 @@ function normaliseComponentGradient(raw) {
   return { from, to, angle: ((deg % 360) + 360) % 360 };
 }
 
+// REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
+// because BOTH hosts multiply node spacing by it and a disagreement here would
+// re-space an exported page against the Player. Anything absent, non-finite or
+// out of band resolves to 1 (unchanged) rather than throwing -- `theme_config`
+// is a JSON bag a workspace admin can PUT verbatim.
+function clampSpacingScale(value) {
+  // Absent means UNSET, not "as tight as possible" — Number(null) and Number("")
+  // are both 0, which would otherwise clamp an untouched theme to the minimum.
+  if (value === null || value === undefined || value === "") {
+    return THEME_SPACING_SCALE.default;
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return THEME_SPACING_SCALE.default;
+  return Math.min(Math.max(n, THEME_SPACING_SCALE.min), THEME_SPACING_SCALE.max);
+}
+
+// REQ-THEME-LOOK: apply that scale to ONE spacing value. Rounded to whole
+// pixels so a scaled gap stays on the same pixel grid as an unscaled one.
+function scaleSpacing(value, scale) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return value;
+  return Math.round(value * clampSpacingScale(scale));
+}
+
 export {
   CONTRACT,
+  clampSpacingScale,
+  scaleSpacing,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,
@@ -2864,6 +3077,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveSurfaceTokens,
   gradientAngleToVector,
   normaliseComponentGradient,
   formatMoneyIn,

package/dist/host.d.ts

@@ -25,6 +25,12 @@ export type ThemeComponentStyle = Record<
 >;
 export type ThemeComponents = Record<string, ThemeComponentStyle>;
 
+// REQ-THEME-ELEMENT: app-wide style values keyed by widget MANIFEST ID, then by
+// that widget's own styleSchema field name. Values are structural (the
+// authoritative type is the widget's own schema), so this mirrors
+// ThemeComponentStyle rather than naming a closed vocabulary.
+export type ThemeWidgetStyles = Record<string, ThemeComponentStyle>;
+
 /**
  * REQ-THEME-15 host helper: validates a raw `themeConfig.components` blob down
  * to `CONTRACT.themeComponents` — unknown scopes/tokens and malformed values are
@@ -33,6 +39,14 @@ export type ThemeComponents = Record<string, ThemeComponentStyle>;
  */
 export function normaliseThemeComponents(raw: unknown): ThemeComponents;
 
+/**
+ * REQ-THEME-ELEMENT host helper: validates a raw `themeConfig.widgetStyles` blob.
+ * Structural only — the key space is the workspace's widget catalog, not the
+ * contract, so the authoritative field type is the widget's own styleSchema.
+ * Bounded by `CONTRACT.themeWidgetStyles`.
+ */
+export function normaliseWidgetStyles(raw: unknown): ThemeWidgetStyles;
+
 /**
  * REQ-THEME-15 host render-boundary helper: folds the theme's per-component
  * tokens into a widget's props as `style` DEFAULTS, with the author's
@@ -41,6 +55,81 @@ export function normaliseThemeComponents(raw: unknown): ThemeComponents;
  */
 export function applyThemeComponentStyle<T = Record<string, unknown>>(
   manifestId: string,
-  theme: { components?: ThemeComponents } | null | undefined,
+  theme:
+    | { components?: ThemeComponents; widgetStyles?: ThemeWidgetStyles }
+    | null
+    | undefined,
   props: T,
+  styleSchema?: Record<string, unknown> | null,
 ): T;
+
+// sc-4939 — the host half of `useToast()`. A widget only ever calls the hook;
+// these are what a platform host puts behind `WidgetContext.toast`.
+
+export type ToastKind = "success" | "error" | "warning" | "info";
+
+export interface ToastPayload {
+  kind?: ToastKind | string;
+  message?: string;
+}
+
+export interface HostToast {
+  id: string;
+  kind: ToastKind;
+  message: string;
+}
+
+/** Resolved values a host paints one toast with. `elevation` is the React
+ *  Native style object; `boxShadow` is the CSS string derived from it. */
+export interface ToastTokens {
+  kind: ToastKind;
+  accent: string;
+  surface: string;
+  text: string;
+  border: string;
+  radius: number;
+  padding: number;
+  gap: number;
+  stackGap: number;
+  accentBarWidth: number;
+  fontFamily?: string;
+  fontSize: number;
+  elevation: Record<string, unknown>;
+  boxShadow: string;
+}
+
+export interface ToastController {
+  /** Enqueue a toast. Returns its id, or null when the message is empty. */
+  show(payload: ToastPayload): string | null;
+  dismiss(id: string): void;
+  getToasts(): HostToast[];
+  /** Subscribe to the queue; returns an unsubscribe function. */
+  subscribe(listener: (toasts: HostToast[]) => void): () => void;
+  /** Clear every pending timer and listener. */
+  destroy(): void;
+}
+
+export interface ToastControllerOptions {
+  durationMs?: number;
+  maxVisible?: number;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+export const TOAST_DEFAULTS: { durationMs: number; maxVisible: number };
+
+export function normalizeToastKind(kind: unknown): ToastKind;
+
+export function resolveToastTokens(
+  theme: unknown,
+  kind: ToastKind | string,
+): ToastTokens;
+
+/**
+ * The host-side toast queue: newest-first stacking capped at `maxVisible`,
+ * auto-dismiss after `durationMs`, injectable timers. Shared by the web Player
+ * and the compiler's native WidgetHost so the two cannot drift.
+ */
+export function createToastController(
+  opts?: ToastControllerOptions,
+): ToastController;

package/dist/host.js

@@ -18,5 +18,24 @@ export { resolveProps } from "./property-schema.js";
 // hosts, so the Player and the Expo export cannot diverge.
 export {
   normaliseThemeComponents,
+  normaliseWidgetStyles,
   applyThemeComponentStyle,
 } from "./theme-components.js";
+
+// REQ-THEME-SURFACE: the surface-token derivation both hosts apply per painted
+// surface — the page background and every container that carries its own fill.
+// Host plumbing, deliberately off the author entry point: a widget reads the
+// already-correct `useTheme().colors`, it never derives them itself.
+export { deriveSurfaceTokens } from "./contract.js";
+
+// REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
+// auto-dismiss timing, and the themed values a toast is painted with. The
+// widget-facing hook only forwards to `ctx.toast.showToast`; the host owns the
+// surface, and sharing everything but the JSX is what keeps the web Player and
+// the Expo export rendering the same notification (CLAUDE.md §8).
+export {
+  createToastController,
+  resolveToastTokens,
+  normalizeToastKind,
+  TOAST_DEFAULTS,
+} from "./toast-host.js";

package/dist/index.js

@@ -99,5 +99,7 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  clampSpacingScale,
+  scaleSpacing,
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/index.native.js

@@ -97,5 +97,7 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  clampSpacingScale,
+  scaleSpacing,
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/linter.cjs

@@ -877,6 +877,72 @@ function _imagePercentHeightRules(source) {
   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).
+const _JSX_TAG_RE = /<([A-Z][\w.]*)\b/g;
+const _ON_LAYOUT_ATTR_RE = /\bonLayout\s*=/;
+const _OWN_PADDING_RE = /\bpadding(?:Horizontal|Left|Right|Start|End)?\s*:/;
+const _WIDTH_HOLDER_RE =
+  /const\s*\[\s*([\w$]+)\s*,\s*([\w$]+)\s*\]\s*=\s*(useState|useContainerWidth)\b/g;
+const _LAYOUT_FEED_WINDOW = 80;
+
+function _measuredWidthNames(code) {
+  const names = [];
+  _WIDTH_HOLDER_RE.lastIndex = 0;
+  let held;
+  while ((held = _WIDTH_HOLDER_RE.exec(code))) {
+    const [, value, setter, hook] = held;
+    if (hook === "useContainerWidth") {
+      names.push(value);
+      continue;
+    }
+    const fedByLayout = new RegExp(
+      `\\b${setter}\\s*\\([\\s\\S]{0,${_LAYOUT_FEED_WINDOW}}?\\blayout\\.width\\b`,
+    );
+    if (fedByLayout.test(code)) names.push(value);
+  }
+  return names;
+}
+
+function _sizesFromMeasuredWidth(code, names) {
+  return names.some((name) =>
+    new RegExp(`\\b${name}\\s*[-/*]|[-/*]\\s*\\b${name}\\b`).test(code),
+  );
+}
+
+function _measuredPaddingRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const measured = _measuredWidthNames(code);
+  if (!_sizesFromMeasuredWidth(code, measured)) return [];
+  const sourceLines = source.split(/\r?\n/);
+  const findings = [];
+  _JSX_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _JSX_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    const attrs = code.slice(tag.index, end);
+    _JSX_TAG_RE.lastIndex = end;
+    if (!_ON_LAYOUT_ATTR_RE.test(attrs)) continue;
+    const padded = _OWN_PADDING_RE.exec(attrs);
+    if (!padded) continue;
+    const line = code
+      .slice(0, tag.index + padded.index)
+      .split(/\r?\n/).length;
+    findings.push({
+      rule: "measured-width-ignores-padding",
+      severity: "warning",
+      label:
+        `<${tag[1]}> has onLayout AND its own padding: the measured width ` +
+        `INCLUDES that padding, so cells sized from it overflow and the last ` +
+        `wraps, leaving an empty column. Measure an unpadded inner View.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // Narrow a split-impl widget's manifest to the platform a single bundle file
 // ships to, so `import-platform-mismatch` lints each file against what it
 // actually targets. Mirror of linter.js.
@@ -939,6 +1005,9 @@ function lintSource(source, options) {
   findings.push(..._lucideIconRules(source));
   findings.push(..._reactInScopeRules(source));
   findings.push(..._imagePercentHeightRules(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));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));