@colixsystems/widget-sdk 0.3.0 → 0.6.0

package/dist/linter.js

@@ -2,29 +2,62 @@
 // Scans widget source for banned patterns. Pure text scanning — no AST parsing
 // dep — which is sufficient to gate v0.1 submissions and gives clear pointers
 // to humans during review.
+//
+// The banned-identifier list is derived from `CONTRACT.bannedApis` so the
+// system prompt, the linter, and the runtime allowlist agree.
 
-const RULES = [
-  {
-    id: "no-eval",
-    label: "eval() is forbidden",
-    pattern: /\beval\s*\(/,
-  },
-  {
-    id: "no-new-function",
-    label: "new Function() is forbidden",
-    pattern: /\bnew\s+Function\s*\(/,
-  },
-  {
-    id: "no-function-constructor",
-    label: "Function() constructor is forbidden",
-    // Bare Function( call not preceded by identifier/property char.
-    pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
-  },
-  {
-    id: "no-dynamic-import",
-    label: "dynamic import() is forbidden",
-    pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
-  },
+import { CONTRACT } from "./contract.js";
+
+// Per-identifier match rule. Most banned identifiers compile to a
+// whole-word match; a few have special syntax (`Function(`, `new Function`,
+// `import(`) that needs a tighter regex.
+function _ruleForIdentifier(identifier, reason) {
+  const id = identifier;
+  if (id === "Function") {
+    return {
+      id: "no-function-constructor",
+      label: `${reason} (banned: Function() constructor)`,
+      pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
+    };
+  }
+  if (id === "new Function") {
+    return {
+      id: "no-new-function",
+      label: `${reason} (banned: new Function())`,
+      pattern: /\bnew\s+Function\s*\(/,
+    };
+  }
+  if (id === "import(") {
+    return {
+      id: "no-dynamic-import",
+      label: `${reason} (banned: dynamic import())`,
+      pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
+    };
+  }
+  if (id === "eval") {
+    return {
+      id: "no-eval",
+      label: `${reason} (banned: eval)`,
+      pattern: /\beval\s*\(/,
+    };
+  }
+  // Default: word-boundary anchored. Used for the simple identifier
+  // forms (`window`, `document`, `process`, ...).
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return {
+    id: `no-${id.toLowerCase()}`,
+    label: `${reason} (banned: ${id})`,
+    pattern: new RegExp(`\\b${escaped}\\b`),
+  };
+}
+
+const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
+  _ruleForIdentifier(b.identifier, b.reason),
+);
+
+// Extra rules that don't map 1:1 to a banned identifier in the contract:
+// host-internal imports that widgets must never touch.
+const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
     label: "widgets must not import the host's auth store",
@@ -32,11 +65,24 @@ const RULES = [
   },
   {
     id: "no-axios-import",
-    label: "widgets must not import axios directly; use the injected datastore client",
+    label:
+      "widgets must not import axios directly; use the injected datastore client",
     pattern: /from\s+['"]axios['"]|require\s*\(\s*['"]axios['"]\s*\)/,
   },
 ];
 
+const RULES = [...CONTRACT_RULES, ...EXTRA_RULES];
+
+/**
+ * Returns the contract-derived list of banned identifiers. Exposed so the
+ * SDK contract test (and any host build step that wants to surface the
+ * list to humans) can read the canonical set without re-parsing the
+ * source.
+ */
+export function bannedIdentifiers() {
+  return CONTRACT.bannedApis.map((b) => b.identifier);
+}
+
 /**
  * Lint a JavaScript source string.
  * @param {string} source
@@ -46,7 +92,9 @@ export function lintSource(source) {
   if (typeof source !== "string") {
     return {
       ok: false,
-      findings: [{ rule: "input", label: "source must be a string", line: 0, snippet: "" }],
+      findings: [
+        { rule: "input", label: "source must be a string", line: 0, snippet: "" },
+      ],
     };
   }
   const findings = [];

package/dist/manifest.cjs

@@ -0,0 +1,144 @@
+// CommonJS mirror of manifest.js. Lets backend services (CJS) call
+// `validateManifest(...)` without a dynamic-import detour. The two files
+// share their constants by mutual import via createRequire — manifest.js
+// re-exports the same functions defined here so there is exactly one
+// implementation.
+
+const VALID_CATEGORIES = new Set([
+  "input", "display", "layout", "data", "media", "communication", "custom",
+  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
+]);
+const VALID_PLATFORMS = new Set(["web", "native"]);
+
+function canonicalCategory(c) {
+  if (typeof c !== "string") return null;
+  const upper = c.toUpperCase();
+  return [
+    "INPUT",
+    "DISPLAY",
+    "LAYOUT",
+    "DATA",
+    "MEDIA",
+    "COMMUNICATION",
+    "CUSTOM",
+  ].includes(upper)
+    ? upper
+    : null;
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SEMVER_RANGE_RE = /^[\^~>=<]*\s*\d+\.\d+\.\d+/;
+const ID_RE = /^[a-z0-9]+(?:\.[a-z0-9-]+)+$/;
+
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+
+function pushIf(errors, cond, msg) {
+  if (!cond) errors.push(msg);
+}
+
+function validateManifest(m) {
+  const errors = [];
+  if (m === null || typeof m !== "object") {
+    return { ok: false, errors: ["manifest must be an object"] };
+  }
+  const manifest = m;
+
+  pushIf(errors, isNonEmptyString(manifest.id), "manifest.id must be a non-empty string");
+  if (isNonEmptyString(manifest.id)) {
+    pushIf(
+      errors,
+      ID_RE.test(manifest.id),
+      "manifest.id must be reverse-DNS, e.g. com.acme.charts.barchart",
+    );
+  }
+
+  pushIf(errors, isNonEmptyString(manifest.name), "manifest.name must be a non-empty string");
+
+  pushIf(errors, isNonEmptyString(manifest.version), "manifest.version must be a non-empty string");
+  if (isNonEmptyString(manifest.version)) {
+    pushIf(errors, SEMVER_RE.test(manifest.version), "manifest.version must be a valid semver");
+  }
+
+  pushIf(
+    errors,
+    typeof manifest.category === "string" && VALID_CATEGORIES.has(manifest.category),
+    `manifest.category must be one of ${[...VALID_CATEGORIES].join(", ")}`,
+  );
+
+  pushIf(errors, isNonEmptyString(manifest.icon), "manifest.icon must be a non-empty string");
+  pushIf(errors, isNonEmptyString(manifest.description), "manifest.description must be a non-empty string");
+
+  if (manifest.author === null || typeof manifest.author !== "object") {
+    errors.push("manifest.author must be an object with a name");
+  } else {
+    const author = manifest.author;
+    pushIf(errors, isNonEmptyString(author.name), "manifest.author.name must be a non-empty string");
+    if (author.url !== undefined) {
+      pushIf(errors, isNonEmptyString(author.url), "manifest.author.url must be a string");
+    }
+    if (author.email !== undefined) {
+      pushIf(errors, isNonEmptyString(author.email), "manifest.author.email must be a string");
+    }
+  }
+
+  if (!Array.isArray(manifest.supportedPlatforms) || manifest.supportedPlatforms.length === 0) {
+    errors.push("manifest.supportedPlatforms must be a non-empty array");
+  } else {
+    for (const p of manifest.supportedPlatforms) {
+      if (!VALID_PLATFORMS.has(p)) {
+        errors.push(`manifest.supportedPlatforms contains invalid value "${p}"`);
+      }
+    }
+  }
+
+  pushIf(
+    errors,
+    isNonEmptyString(manifest.minAppStudioVersion),
+    "manifest.minAppStudioVersion must be a non-empty string",
+  );
+  if (isNonEmptyString(manifest.minAppStudioVersion)) {
+    pushIf(
+      errors,
+      SEMVER_RANGE_RE.test(manifest.minAppStudioVersion),
+      "manifest.minAppStudioVersion must be a semver range, e.g. >=2.4.0",
+    );
+  }
+
+  if (!Array.isArray(manifest.requestedScopes)) {
+    errors.push("manifest.requestedScopes must be an array (use [] for none)");
+  } else {
+    for (const s of manifest.requestedScopes) {
+      if (!isNonEmptyString(s)) {
+        errors.push("manifest.requestedScopes entries must be non-empty strings");
+        break;
+      }
+    }
+  }
+
+  if (manifest.propertySchema === null || typeof manifest.propertySchema !== "object") {
+    errors.push("manifest.propertySchema must be an object");
+  }
+
+  if (!Array.isArray(manifest.events)) {
+    errors.push("manifest.events must be an array (use [] for none)");
+  } else {
+    for (const e of manifest.events) {
+      if (e === null || typeof e !== "object") {
+        errors.push("manifest.events entries must be objects");
+        break;
+      }
+      if (!isNonEmptyString(e.name)) {
+        errors.push("manifest.events[].name must be a non-empty string");
+      }
+    }
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+module.exports = {
+  validateManifest,
+  canonicalCategory,
+};

package/dist/manifest.js

@@ -1,27 +1,31 @@
-// Shape validation for WidgetManifest per docs/architecture/widget-marketplace.md §2.1.
-// Pure JS — no third-party deps. Banned-identifier scanning lives in linter.js.
+// CommonJS mirror of manifest.js. Lets backend services (CJS) call
+// `validateManifest(...)` without a dynamic-import detour. The two files
+// share their constants by mutual import via createRequire — manifest.js
+// re-exports the same functions defined here so there is exactly one
+// implementation.
 
-// REQ-MKT canonical category values are uppercase (matching the Prisma
-// `WidgetCategory` enum used to persist them server-side). We accept both
-// cases on input — lowercase is the form spelled out in design doc §2.2
-// and the TS types — and canonicalize internally via `canonicalCategory`.
 const VALID_CATEGORIES = new Set([
   "input", "display", "layout", "data", "media", "communication", "custom",
   "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
 ]);
 const VALID_PLATFORMS = new Set(["web", "native"]);
 
-/**
- * Normalize a manifest category to its canonical (uppercase) form.
- * Returns `null` if the input is not a recognised category.
- * @param {unknown} c
- * @returns {string | null}
- */
-export function canonicalCategory(c) {
+function canonicalCategory(c) {
   if (typeof c !== "string") return null;
   const upper = c.toUpperCase();
-  return ["INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM"].includes(upper) ? upper : null;
+  return [
+    "INPUT",
+    "DISPLAY",
+    "LAYOUT",
+    "DATA",
+    "MEDIA",
+    "COMMUNICATION",
+    "CUSTOM",
+  ].includes(upper)
+    ? upper
+    : null;
 }
+
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const SEMVER_RANGE_RE = /^[\^~>=<]*\s*\d+\.\d+\.\d+/;
 const ID_RE = /^[a-z0-9]+(?:\.[a-z0-9-]+)+$/;
@@ -34,37 +38,34 @@ function pushIf(errors, cond, msg) {
   if (!cond) errors.push(msg);
 }
 
-/**
- * Validates a WidgetManifest shape.
- * @param {unknown} m
- * @returns {{ ok: true } | { ok: false, errors: string[] }}
- */
-export function validateManifest(m) {
+function validateManifest(m) {
   const errors = [];
-
   if (m === null || typeof m !== "object") {
     return { ok: false, errors: ["manifest must be an object"] };
   }
-
-  const manifest = /** @type {Record<string, unknown>} */ (m);
+  const manifest = m;
 
   pushIf(errors, isNonEmptyString(manifest.id), "manifest.id must be a non-empty string");
   if (isNonEmptyString(manifest.id)) {
-    pushIf(errors, ID_RE.test(/** @type {string} */ (manifest.id)),
-      "manifest.id must be reverse-DNS, e.g. com.acme.charts.barchart");
+    pushIf(
+      errors,
+      ID_RE.test(manifest.id),
+      "manifest.id must be reverse-DNS, e.g. com.acme.charts.barchart",
+    );
   }
 
   pushIf(errors, isNonEmptyString(manifest.name), "manifest.name must be a non-empty string");
 
   pushIf(errors, isNonEmptyString(manifest.version), "manifest.version must be a non-empty string");
   if (isNonEmptyString(manifest.version)) {
-    pushIf(errors, SEMVER_RE.test(/** @type {string} */ (manifest.version)),
-      "manifest.version must be a valid semver");
+    pushIf(errors, SEMVER_RE.test(manifest.version), "manifest.version must be a valid semver");
   }
 
-  pushIf(errors,
+  pushIf(
+    errors,
     typeof manifest.category === "string" && VALID_CATEGORIES.has(manifest.category),
-    `manifest.category must be one of ${[...VALID_CATEGORIES].join(", ")}`);
+    `manifest.category must be one of ${[...VALID_CATEGORIES].join(", ")}`,
+  );
 
   pushIf(errors, isNonEmptyString(manifest.icon), "manifest.icon must be a non-empty string");
   pushIf(errors, isNonEmptyString(manifest.description), "manifest.description must be a non-empty string");
@@ -72,7 +73,7 @@ export function validateManifest(m) {
   if (manifest.author === null || typeof manifest.author !== "object") {
     errors.push("manifest.author must be an object with a name");
   } else {
-    const author = /** @type {Record<string, unknown>} */ (manifest.author);
+    const author = manifest.author;
     pushIf(errors, isNonEmptyString(author.name), "manifest.author.name must be a non-empty string");
     if (author.url !== undefined) {
       pushIf(errors, isNonEmptyString(author.url), "manifest.author.url must be a string");
@@ -92,11 +93,17 @@ export function validateManifest(m) {
     }
   }
 
-  pushIf(errors, isNonEmptyString(manifest.minAppStudioVersion),
-    "manifest.minAppStudioVersion must be a non-empty string");
+  pushIf(
+    errors,
+    isNonEmptyString(manifest.minAppStudioVersion),
+    "manifest.minAppStudioVersion must be a non-empty string",
+  );
   if (isNonEmptyString(manifest.minAppStudioVersion)) {
-    pushIf(errors, SEMVER_RANGE_RE.test(/** @type {string} */ (manifest.minAppStudioVersion)),
-      "manifest.minAppStudioVersion must be a semver range, e.g. >=2.4.0");
+    pushIf(
+      errors,
+      SEMVER_RANGE_RE.test(manifest.minAppStudioVersion),
+      "manifest.minAppStudioVersion must be a semver range, e.g. >=2.4.0",
+    );
   }
 
   if (!Array.isArray(manifest.requestedScopes)) {
@@ -122,8 +129,7 @@ export function validateManifest(m) {
         errors.push("manifest.events entries must be objects");
         break;
       }
-      const ev = /** @type {Record<string, unknown>} */ (e);
-      if (!isNonEmptyString(ev.name)) {
+      if (!isNonEmptyString(e.name)) {
         errors.push("manifest.events[].name must be a non-empty string");
       }
     }
@@ -131,3 +137,8 @@ export function validateManifest(m) {
 
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
+
+export {
+  validateManifest,
+  canonicalCategory,
+};

package/dist/primitives.js

@@ -1,51 +1,35 @@
-// Web primitive wrappers. Map to plain DOM elements via React.createElement.
-// API surface only — host CSS / theme tokens drive styling.
-
-import React from "react";
-
-const el = React.createElement;
-
-function asStyle(style) {
-  return style && typeof style === "object" ? style : undefined;
-}
-
-export function Text({ children, style, ...rest }) {
-  return el("span", { style: asStyle(style), ...rest }, children);
-}
-
-export function View({ children, style, ...rest }) {
-  return el("div", { style: asStyle(style), ...rest }, children);
-}
-
-export function Pressable({ children, onPress, style, ...rest }) {
-  const handle = onPress
-    ? (ev) => {
-        ev.preventDefault?.();
-        onPress(ev);
-      }
-    : undefined;
-  return el(
-    "button",
-    {
-      type: "button",
-      onClick: handle,
-      style: asStyle(style),
-      ...rest,
-    },
-    children
-  );
-}
-
-export function Image({ source, style, alt, ...rest }) {
-  const src = typeof source === "string" ? source : source?.uri;
-  return el("img", { src, alt: alt ?? "", style: asStyle(style), ...rest });
-}
-
-export function ScrollView({ children, style, horizontal, ...rest }) {
-  const merged = {
-    overflowX: horizontal ? "auto" : "hidden",
-    overflowY: horizontal ? "hidden" : "auto",
-    ...(asStyle(style) || {}),
-  };
-  return el("div", { style: merged, ...rest }, children);
-}
+// REQ-WSDK-RN-WEB: the SDK ships ONE primitive surface. On the web
+// (Studio + Player) the host's bundler aliases `react-native` to
+// `react-native-web` (see `frontend/vite.config.js`), which renders the
+// same React Native API as DOM elements. The exported Expo app's Metro
+// bundler resolves `react-native` to the real library via the SDK
+// package.json `react-native` field — pointing at
+// `primitives.native.js`, which mirrors this file.
+//
+// The previous hand-written DOM wrappers (one function per primitive,
+// two implementations to keep in sync) are gone: the React Native API
+// is the contract, react-native-web does the platform mapping for us,
+// and adding a new primitive (FlatList, ActivityIndicator, …) becomes
+// a one-line re-export rather than a paired implementation.
+//
+// Authors continue to import these from `@colixsystems/widget-sdk` — the
+// SDK's index re-exports them under the names we document in CONTRACT.
+// The static analyzer's allowedBareImports still rejects direct
+// `react-native` imports; the SDK is the single entry point.
+
+export {
+  Text,
+  View,
+  Pressable,
+  Image,
+  ScrollView,
+  TextInput,
+  // Additional cross-platform primitives the AI agent + handwritten
+  // widgets commonly reach for. All work in both react-native-web and
+  // native react-native without per-platform code.
+  FlatList,
+  SectionList,
+  ActivityIndicator,
+  Switch,
+  StyleSheet,
+} from "react-native";

package/dist/primitives.native.js

@@ -1,11 +1,21 @@
-// React Native primitive wrappers. Metro picks this entry through the
-// package.json `react-native` field. `react-native` is an optional peer
-// dependency — web-only consumers never import this file.
+// REQ-WSDK-RN-WEB: native primitive re-exports. Metro picks this entry
+// via the `react-native` field in package.json. Web mirror in
+// `./primitives.js` re-exports from the SAME `react-native` module —
+// the frontend's Vite alias rewrites it to `react-native-web` for
+// browser builds, so the two files only differ in which `react-native`
+// resolves at bundle time. Keep the export list in lockstep with
+// `./primitives.js`.
 
-import { Text as RNText, View as RNView, Pressable as RNPressable, Image as RNImage, ScrollView as RNScrollView } from "react-native";
-
-export const Text = RNText;
-export const View = RNView;
-export const Pressable = RNPressable;
-export const Image = RNImage;
-export const ScrollView = RNScrollView;
+export {
+  Text,
+  View,
+  Pressable,
+  Image,
+  ScrollView,
+  TextInput,
+  FlatList,
+  SectionList,
+  ActivityIndicator,
+  Switch,
+  StyleSheet,
+} from "react-native";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,12 @@
     "./linter": {
       "import": "./dist/linter.js",
       "default": "./dist/linter.js"
+    },
+    "./contract": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/contract.cjs",
+      "import": "./dist/contract.js",
+      "default": "./dist/contract.cjs"
     }
   },
   "bin": {
@@ -29,7 +35,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src"
+    "test": "node --test src/__tests__/contract.test.js"
   },
   "engines": {
     "node": ">=18"
@@ -45,7 +51,8 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "react-native": "*"
+    "react-native": "*",
+    "react-native-web": ">=0.19.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -53,6 +60,9 @@
     },
     "react-native": {
       "optional": true
+    },
+    "react-native-web": {
+      "optional": true
     }
   },
   "keywords": [