@colixsystems/widget-sdk 0.102.1 → 0.103.0

package/README.md

@@ -68,7 +68,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.95.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.103.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.103.0 (contract 1.78.0)
+
+**An app-wide style value may have SHAPE — `widgetStyles` is no longer scalars-only.** Your `styleSchema` is offered in two places: the widget editor (per placed instance) and Theme Settings (app-wide, under your widget's own name). A field holding a structured value — an overlay object, a list of ids — persisted in the first and was silently dropped by the second, so the same edit behaved two ways depending on where the author made it.
+
+`normaliseWidgetStyles` now carries objects and arrays, bounded by `CONTRACT.themeWidgetStyles`: `maxValueDepth` (3), `maxValueEntries` (24 per level), `maxValueBytes` (512 per field), and a new `maxBytes` (64000) over the whole map — a ceiling the per-scalar limits never stated, so the worst-case payload of that unauthenticated cold-start read is now *smaller* than before. `__proto__`-style keys are refused at every level.
+
+Host-integration surface only — nothing a widget imports changed, and your widget still reads `props.style` without learning which layer supplied a value. `CONTRACT.version` → `1.78.0`. Additive: every value accepted before is accepted now.
 
 ### What's new in 0.95.0 (contract 1.68.0)
 

package/dist/contract.cjs

@@ -158,6 +158,15 @@ const THEME_WIDGET_STYLES = Object.freeze({
   maxWidgets: 200,
   // Matches the styleSchema field cap the widget agent is held to.
   maxFieldsPerWidget: 12,
+  // sc-5646: a styleSchema field may hold a STRUCTURED value (a container's
+  // overlay, a list of ids), so the ceiling is stated in bytes rather than
+  // assumed to be one short scalar.
+  maxValueBytes: 512,
+  // The whole map, because it rides that unauthenticated cold-start read.
+  maxBytes: 64000,
+  // Nesting/width a structured value may reach before it is dropped.
+  maxValueDepth: 3,
+  maxValueEntries: 24,
 });
 // REQ-NAV-STRUCTURE: the SHAPE an app's navigation takes. One catalogue, four
 // consumers -- the Studio's Navigation page, Mason's set_theme coercion, the web
@@ -3266,7 +3275,18 @@ const CONTRACT = deepFreeze({
   //    PAGE_ROUTES maps both to the screen name), but the contract said
   //    `pageId` only, so data-driven widgets — whose rows carry slugs —
   //    invented params patterns that navigate nowhere. No code changed shape.
-  version: "1.77.0",
+  // 1.78.0: additive (sc-5646) — `widgetStyles` carries every value shape a
+  //    `styleSchema` field can produce, not just scalars and gradients. The
+  //    Studio offers the SAME field in the widget editor and in Theme
+  //    Settings, so a structured value (a container-style overlay, a list of
+  //    ids) that persisted per instance but was dropped app-wide made one
+  //    edit behave two ways. Objects and arrays are now carried, bounded by
+  //    `themeWidgetStyles.maxValueDepth` / `maxValueEntries` /
+  //    `maxValueBytes`, with `maxBytes` capping the whole map — a ceiling the
+  //    per-scalar limits never stated, so the worst-case unauthenticated
+  //    payload is SMALLER than before. `__proto__`-style keys are refused at
+  //    every level. Additive: every value accepted before is accepted now.
+  version: "1.78.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -158,6 +158,15 @@ const THEME_WIDGET_STYLES = Object.freeze({
   maxWidgets: 200,
   // Matches the styleSchema field cap the widget agent is held to.
   maxFieldsPerWidget: 12,
+  // sc-5646: a styleSchema field may hold a STRUCTURED value (a container's
+  // overlay, a list of ids), so the ceiling is stated in bytes rather than
+  // assumed to be one short scalar.
+  maxValueBytes: 512,
+  // The whole map, because it rides that unauthenticated cold-start read.
+  maxBytes: 64000,
+  // Nesting/width a structured value may reach before it is dropped.
+  maxValueDepth: 3,
+  maxValueEntries: 24,
 });
 // REQ-NAV-STRUCTURE: the SHAPE an app's navigation takes. One catalogue, four
 // consumers -- the Studio's Navigation page, Mason's set_theme coercion, the web
@@ -3266,7 +3275,18 @@ const CONTRACT = deepFreeze({
   //    PAGE_ROUTES maps both to the screen name), but the contract said
   //    `pageId` only, so data-driven widgets — whose rows carry slugs —
   //    invented params patterns that navigate nowhere. No code changed shape.
-  version: "1.77.0",
+  // 1.78.0: additive (sc-5646) — `widgetStyles` carries every value shape a
+  //    `styleSchema` field can produce, not just scalars and gradients. The
+  //    Studio offers the SAME field in the widget editor and in Theme
+  //    Settings, so a structured value (a container-style overlay, a list of
+  //    ids) that persisted per instance but was dropped app-wide made one
+  //    edit behave two ways. Objects and arrays are now carried, bounded by
+  //    `themeWidgetStyles.maxValueDepth` / `maxValueEntries` /
+  //    `maxValueBytes`, with `maxBytes` capping the whole map — a ceiling the
+  //    per-scalar limits never stated, so the worst-case unauthenticated
+  //    payload is SMALLER than before. `__proto__`-style keys are refused at
+  //    every level. Additive: every value accepted before is accepted now.
+  version: "1.78.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -45,6 +45,17 @@ export function normaliseThemeComponents(raw: unknown): ThemeComponents;
  * contract, so the authoritative field type is the widget's own styleSchema.
  * Bounded by `CONTRACT.themeWidgetStyles`.
  */
+/**
+ * sc-5646 host helper: validates ONE widget style object — a placed node's
+ * `props.style` or an app-wide `widgetStyles[id]` entry. Both scopes hold the
+ * same vocabulary, so both are validated the same way; `maxFields` applies the
+ * per-widget cap only the app-wide map needs.
+ */
+export function normaliseWidgetStyleFields(
+  raw: unknown,
+  options?: { maxFields?: number },
+): Record<string, unknown>;
+
 export function normaliseWidgetStyles(raw: unknown): ThemeWidgetStyles;
 
 /**

package/dist/host.js

@@ -18,6 +18,7 @@ export { resolveProps } from "./property-schema.js";
 // hosts, so the Player and the Expo export cannot diverge.
 export {
   normaliseThemeComponents,
+  normaliseWidgetStyleFields,
   normaliseWidgetStyles,
   applyThemeComponentStyle,
 } from "./theme-components.js";

package/dist/theme-components.cjs

@@ -99,12 +99,30 @@ function normaliseThemeComponents(raw) {
 }
 
 
+// Values are assigned onto plain object literals, so `__proto__` would set a
+// PROTOTYPE rather than a style field. Refused at every level.
+const UNSAFE_STYLE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isUsableStyleKey(key) {
+  return (
+    typeof key === "string" &&
+    key.length > 0 &&
+    key.length <= 64 &&
+    !UNSAFE_STYLE_KEYS.has(key)
+  );
+}
+
 // REQ-THEME-ELEMENT: one value out of the per-widget map. Unlike a component
 // token, there is no declared `type` to coerce against -- the key space is the
 // workspace's widget catalog, not the contract -- so validation here is
 // STRUCTURAL. The authoritative type is the widget's own styleSchema, which the
 // Studio honours by only ever offering fields that widget declares.
-function coerceWidgetStyleValue(value) {
+//
+// sc-5646: that same field is offered per instance AND app-wide, so carrying
+// only scalars here made one edit behave two ways. A structured value rides
+// along too -- bounded by depth, width and bytes, never by trust.
+function coerceWidgetStyleValue(value, depth = 0) {
+  const { maxValueDepth, maxValueEntries } = CONTRACT.themeWidgetStyles;
   if (typeof value === "string") {
     const trimmed = value.trim();
     // Long enough for a hex, an enum value or a font name; short enough that a
@@ -113,10 +131,75 @@ function coerceWidgetStyleValue(value) {
   }
   if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
   if (typeof value === "boolean") return value;
-  if (isPlainObject(value)) return normaliseComponentGradient(value) || undefined;
+  if (depth >= maxValueDepth) return undefined;
+  if (Array.isArray(value)) {
+    const items = [];
+    for (const item of value) {
+      if (items.length >= maxValueEntries) break;
+      const coerced = coerceWidgetStyleValue(item, depth + 1);
+      if (coerced !== undefined) items.push(coerced);
+    }
+    return items.length > 0 ? items : undefined;
+  }
+  if (isPlainObject(value)) {
+    // A gradient keeps its own normaliser -- its stops are interpolated into
+    // CSS and into generated export source, so they never ride the generic
+    // path. Claiming the grammar is enough to be held to it: an invalid one is
+    // dropped rather than carried through as a plain object.
+    if ("from" in value || "to" in value) {
+      return normaliseComponentGradient(value) || undefined;
+    }
+    const out = {};
+    let kept = 0;
+    for (const [key, item] of Object.entries(value)) {
+      if (kept >= maxValueEntries) break;
+      if (!isUsableStyleKey(key)) continue;
+      const coerced = coerceWidgetStyleValue(item, depth + 1);
+      if (coerced === undefined) continue;
+      out[key] = coerced;
+      kept += 1;
+    }
+    return kept > 0 ? out : undefined;
+  }
   return undefined;
 }
 
+// What the value actually costs the cold-start read and the baked export.
+function styleValueBytes(value) {
+  const json = JSON.stringify(value);
+  return typeof json === "string" ? json.length : Infinity;
+}
+
+/**
+ * sc-5646: ONE widget's style fields, validated. The app-wide layer and a placed
+ * node's `props.style` hold the SAME vocabulary at different scopes, so they must
+ * accept the same values — a field an author can set on a node and not app-wide
+ * (or the reverse) is exactly the divergence the two surfaces are meant not to
+ * have. The per-widget FIELD cap is deliberately not applied here: it bounds the
+ * app-wide map that rides the unauthenticated cold-start read, not one node in a
+ * page layout the builder already writes unbounded.
+ *
+ * @param {unknown} raw — a `props.style` / `widgetStyles[id]` object.
+ * @param {{ maxFields?: number }} [options]
+ * @returns {Record<string, unknown>} the fields that survived; `{}` for junk.
+ */
+function normaliseWidgetStyleFields(raw, { maxFields } = {}) {
+  if (!isPlainObject(raw)) return {};
+  const { maxValueBytes } = CONTRACT.themeWidgetStyles;
+  const out = {};
+  let count = 0;
+  for (const [field, value] of Object.entries(raw)) {
+    if (maxFields !== undefined && count >= maxFields) break;
+    if (!isUsableStyleKey(field)) continue;
+    const coerced = coerceWidgetStyleValue(value);
+    if (coerced === undefined) continue;
+    if (styleValueBytes(coerced) > maxValueBytes) continue;
+    out[field] = coerced;
+    count += 1;
+  }
+  return out;
+}
+
 /**
  * REQ-THEME-ELEMENT: validate `themeConfig.widgetStyles` -- app-wide style values
  * keyed by WIDGET MANIFEST ID, then by that widget's own styleSchema field name.
@@ -132,26 +215,31 @@ function coerceWidgetStyleValue(value) {
  */
 function normaliseWidgetStyles(raw) {
   if (!isPlainObject(raw)) return {};
-  const { maxWidgets, maxFieldsPerWidget } = CONTRACT.themeWidgetStyles;
+  const { maxWidgets, maxFieldsPerWidget, maxBytes } =
+    CONTRACT.themeWidgetStyles;
   const idPattern = CONTRACT.manifestSchema.id.pattern;
   const out = {};
   let widgets = 0;
+  let bytes = 0;
   for (const [manifestId, fields] of Object.entries(raw)) {
     if (widgets >= maxWidgets) break;
     if (!idPattern.test(manifestId) || !isPlainObject(fields)) continue;
-    const kept = {};
-    let count = 0;
-    for (const [field, value] of Object.entries(fields)) {
-      if (count >= maxFieldsPerWidget) break;
-      const coerced = coerceWidgetStyleValue(value);
-      if (coerced === undefined) continue;
-      kept[field] = coerced;
-      count += 1;
-    }
+    // The SAME per-field validation a placed node's style gets, plus the cap
+    // that only this map needs.
+    const kept = normaliseWidgetStyleFields(fields, {
+      maxFields: maxFieldsPerWidget,
+    });
+    const count = Object.keys(kept).length;
     // An emptied entry is dropped rather than persisted as `{}`, mirroring
     // normaliseThemeComponents.
     if (count === 0) continue;
+    // Whole entries, never half of one: a widget rendering with SOME of its
+    // app-wide fields reads as a bug, where one rendering with none reads as
+    // "not styled yet".
+    const entryBytes = styleValueBytes(kept) + manifestId.length;
+    if (bytes + entryBytes > maxBytes) break;
     out[manifestId] = kept;
+    bytes += entryBytes;
     widgets += 1;
   }
   return out;
@@ -245,4 +333,4 @@ function applyThemeComponentStyle(manifestId, theme, props, styleSchema) {
   return { ...base, style: { ...themed, ...authored } };
 }
 
-module.exports = { normaliseThemeComponents, normaliseWidgetStyles, applyThemeComponentStyle };
+module.exports = { normaliseThemeComponents, normaliseWidgetStyleFields, normaliseWidgetStyles, applyThemeComponentStyle };

package/dist/theme-components.js

@@ -91,12 +91,30 @@ export function normaliseThemeComponents(raw) {
 }
 
 
+// Values are assigned onto plain object literals, so `__proto__` would set a
+// PROTOTYPE rather than a style field. Refused at every level.
+const UNSAFE_STYLE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isUsableStyleKey(key) {
+  return (
+    typeof key === "string" &&
+    key.length > 0 &&
+    key.length <= 64 &&
+    !UNSAFE_STYLE_KEYS.has(key)
+  );
+}
+
 // REQ-THEME-ELEMENT: one value out of the per-widget map. Unlike a component
 // token, there is no declared `type` to coerce against -- the key space is the
 // workspace's widget catalog, not the contract -- so validation here is
 // STRUCTURAL. The authoritative type is the widget's own styleSchema, which the
 // Studio honours by only ever offering fields that widget declares.
-function coerceWidgetStyleValue(value) {
+//
+// sc-5646: that same field is offered per instance AND app-wide, so carrying
+// only scalars here made one edit behave two ways. A structured value rides
+// along too -- bounded by depth, width and bytes, never by trust.
+function coerceWidgetStyleValue(value, depth = 0) {
+  const { maxValueDepth, maxValueEntries } = CONTRACT.themeWidgetStyles;
   if (typeof value === "string") {
     const trimmed = value.trim();
     // Long enough for a hex, an enum value or a font name; short enough that a
@@ -105,10 +123,75 @@ function coerceWidgetStyleValue(value) {
   }
   if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
   if (typeof value === "boolean") return value;
-  if (isPlainObject(value)) return normaliseComponentGradient(value) || undefined;
+  if (depth >= maxValueDepth) return undefined;
+  if (Array.isArray(value)) {
+    const items = [];
+    for (const item of value) {
+      if (items.length >= maxValueEntries) break;
+      const coerced = coerceWidgetStyleValue(item, depth + 1);
+      if (coerced !== undefined) items.push(coerced);
+    }
+    return items.length > 0 ? items : undefined;
+  }
+  if (isPlainObject(value)) {
+    // A gradient keeps its own normaliser -- its stops are interpolated into
+    // CSS and into generated export source, so they never ride the generic
+    // path. Claiming the grammar is enough to be held to it: an invalid one is
+    // dropped rather than carried through as a plain object.
+    if ("from" in value || "to" in value) {
+      return normaliseComponentGradient(value) || undefined;
+    }
+    const out = {};
+    let kept = 0;
+    for (const [key, item] of Object.entries(value)) {
+      if (kept >= maxValueEntries) break;
+      if (!isUsableStyleKey(key)) continue;
+      const coerced = coerceWidgetStyleValue(item, depth + 1);
+      if (coerced === undefined) continue;
+      out[key] = coerced;
+      kept += 1;
+    }
+    return kept > 0 ? out : undefined;
+  }
   return undefined;
 }
 
+// What the value actually costs the cold-start read and the baked export.
+function styleValueBytes(value) {
+  const json = JSON.stringify(value);
+  return typeof json === "string" ? json.length : Infinity;
+}
+
+/**
+ * sc-5646: ONE widget's style fields, validated. The app-wide layer and a placed
+ * node's `props.style` hold the SAME vocabulary at different scopes, so they must
+ * accept the same values — a field an author can set on a node and not app-wide
+ * (or the reverse) is exactly the divergence the two surfaces are meant not to
+ * have. The per-widget FIELD cap is deliberately not applied here: it bounds the
+ * app-wide map that rides the unauthenticated cold-start read, not one node in a
+ * page layout the builder already writes unbounded.
+ *
+ * @param {unknown} raw — a `props.style` / `widgetStyles[id]` object.
+ * @param {{ maxFields?: number }} [options]
+ * @returns {Record<string, unknown>} the fields that survived; `{}` for junk.
+ */
+export function normaliseWidgetStyleFields(raw, { maxFields } = {}) {
+  if (!isPlainObject(raw)) return {};
+  const { maxValueBytes } = CONTRACT.themeWidgetStyles;
+  const out = {};
+  let count = 0;
+  for (const [field, value] of Object.entries(raw)) {
+    if (maxFields !== undefined && count >= maxFields) break;
+    if (!isUsableStyleKey(field)) continue;
+    const coerced = coerceWidgetStyleValue(value);
+    if (coerced === undefined) continue;
+    if (styleValueBytes(coerced) > maxValueBytes) continue;
+    out[field] = coerced;
+    count += 1;
+  }
+  return out;
+}
+
 /**
  * REQ-THEME-ELEMENT: validate `themeConfig.widgetStyles` -- app-wide style values
  * keyed by WIDGET MANIFEST ID, then by that widget's own styleSchema field name.
@@ -124,26 +207,31 @@ function coerceWidgetStyleValue(value) {
  */
 export function normaliseWidgetStyles(raw) {
   if (!isPlainObject(raw)) return {};
-  const { maxWidgets, maxFieldsPerWidget } = CONTRACT.themeWidgetStyles;
+  const { maxWidgets, maxFieldsPerWidget, maxBytes } =
+    CONTRACT.themeWidgetStyles;
   const idPattern = CONTRACT.manifestSchema.id.pattern;
   const out = {};
   let widgets = 0;
+  let bytes = 0;
   for (const [manifestId, fields] of Object.entries(raw)) {
     if (widgets >= maxWidgets) break;
     if (!idPattern.test(manifestId) || !isPlainObject(fields)) continue;
-    const kept = {};
-    let count = 0;
-    for (const [field, value] of Object.entries(fields)) {
-      if (count >= maxFieldsPerWidget) break;
-      const coerced = coerceWidgetStyleValue(value);
-      if (coerced === undefined) continue;
-      kept[field] = coerced;
-      count += 1;
-    }
+    // The SAME per-field validation a placed node's style gets, plus the cap
+    // that only this map needs.
+    const kept = normaliseWidgetStyleFields(fields, {
+      maxFields: maxFieldsPerWidget,
+    });
+    const count = Object.keys(kept).length;
     // An emptied entry is dropped rather than persisted as `{}`, mirroring
     // normaliseThemeComponents.
     if (count === 0) continue;
+    // Whole entries, never half of one: a widget rendering with SOME of its
+    // app-wide fields reads as a bug, where one rendering with none reads as
+    // "not styled yet".
+    const entryBytes = styleValueBytes(kept) + manifestId.length;
+    if (bytes + entryBytes > maxBytes) break;
     out[manifestId] = kept;
+    bytes += entryBytes;
     widgets += 1;
   }
   return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.102.1",
+  "version": "0.103.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",