@colixsystems/widget-sdk 0.4.1 → 0.6.0

package/README.md

@@ -6,9 +6,22 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.4.1` — 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.6.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.4.1
+### What's new in 0.6.0
+
+- **Primitives are now React Native through-and-through.** Web (Studio + Player) bundles with `react-native-web`; native (exported Expo app) uses the real `react-native`. The hand-written DOM wrappers in `primitives.js` are gone — both web and native files are now one-line re-exports from `react-native`. The widget API surface is unchanged for the components that already existed (`Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`), so existing 0.5.0 widgets keep running without source edits.
+- **More primitives available for free.** `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, and `StyleSheet` are now exported alongside the original five. Authors who want them just import from `@colixsystems/widget-sdk` like any other primitive.
+- **Per-component API docs link out to React Native.** The Developer Widgets page and the AI agent's system prompt now point at https://reactnative.dev/docs/<component> for prop details instead of duplicating them in the SDK contract. Less drift, more breadth (every RN prop — `accessibilityLabel`, `testID`, gesture handlers, …, works without explicit allowlisting).
+- **Adding a new primitive is now a single edit.** Append the export name to `primitives.js` + `primitives.native.js` + the `CONTRACT.primitives` array. No web/native implementation split.
+- **New peer dep.** `react-native-web >=0.19.0` (optional, marked under `peerDependenciesMeta`). The web bundler picks it up via an alias (`react-native` → `react-native-web` in the host's Vite / webpack config); the native bundler ignores it.
+
+### What was in 0.5.0
+
+- **`TextInput` primitive.** Cross-platform controlled text field — web maps to `<input type="text">` (or `<textarea>` when `multiline` is true), native maps to `react-native` `TextInput`. Props: `value`, `onChangeText`, `placeholder`, `multiline`, `rows`, `disabled`, `style`. Fixes the gap that forced widgets to fall back to raw `<textarea>` (web-only). The AI Widget Agent's system prompt now documents this primitive.
+- **`useDatastoreMutation(...).update(id, partial)` is wired.** Hits `PATCH /api/v1/tables/:tableId/records/:id`, which now exists on the backend (REQ-DML-PATCH). Partial-update semantics — only the supplied columns are mutated, the rest of the row is left intact. MANY_TO_MANY relations follow replace-set semantics when supplied; omitting the column leaves the existing links alone. Constraint enforcement (REQ-CONS-04) runs against the merged row, excluding self so a re-affirm doesn't trip its own UNIQUE.
+
+### What was in 0.4.1
 
 - **`useDatastoreQuery` returns a stable `refetch` identity.** The hook no longer rebinds the underlying callback when the host's `WidgetContext` value (a fresh object identity on every render in Studio + PageRenderer) changes. Widgets that put `refetch` in a `useEffect` dep array no longer loop.
 
@@ -17,7 +30,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 - **`CONTRACT` is now a named export.** A frozen object literal describing the SDK surface every consumer (LLM system prompt, static analyzer, host builder, contract tests) derives from instead of declaring its own copy. See `docs/design/ai-widget-contract.md` for the full design and `src/contract.js` for the source. The contract carries:
 
   - `hooks` — name, signature, return shape, required `WidgetContext` slices, manifest scopes.
-  - `primitives` — `Text` / `View` / `Pressable` / `Image` / `ScrollView` props.
+  - `primitives` — the cross-platform primitive list (names + the React Native component each one backs).
   - `manifestSchema` — the authoritative `WidgetManifest` field list (with `id` and `minAppStudioVersion`, not the legacy `manifestId` / `minAppStudioVer`).
   - `themeTokens` — the default `useTheme()` payload.
   - `widgetContextShape` — what the host must populate.
@@ -44,7 +57,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
 - `useDatastoreQuery`, `useDatastoreMutation`, `useWidgetEvent`, `useTheme`, `useI18n` — hooks that read from the host-provided `WidgetContext`.
-- `Text`, `View`, `Pressable`, `Image`, `ScrollView` — platform-aware primitives. Web entry maps them to DOM elements; the `react-native` entry maps them to React Native components.
+- `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet` — re-exported from `react-native`. The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
 ## Linter

package/dist/contract.cjs

@@ -87,61 +87,90 @@ const HOOKS = [
   },
 ];
 
+// REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
+// (backed by react-native-web on the browser, by react-native on the
+// exported Expo app). The contract describes the *cross-platform
+// subset* the SDK re-exports; the per-prop reference for each
+// component is whatever React Native documents. Adding a new primitive
+// = add the name to `./primitives.js` + `./primitives.native.js` (both
+// one-line re-exports) and append it to this list.
 const PRIMITIVES = [
   {
     name: "Text",
     description:
-      "Text node. Web: <span>. Native: react-native Text. Use `style` for typography.",
-    props: {
-      children: { type: "ReactNode", description: "Text content." },
-      style: { type: "CSSObject | StyleObject", description: "Inline style." },
-    },
+      "Text node. Backed by react-native Text (web: react-native-web maps to a styled <div>). See https://reactnative.dev/docs/text.",
+    rnComponent: "Text",
+    docsUrl: "https://reactnative.dev/docs/text",
   },
   {
     name: "View",
     description:
-      "Block container. Web: <div>. Native: react-native View. Use for layout boxes.",
-    props: {
-      children: { type: "ReactNode" },
-      style: { type: "CSSObject | StyleObject" },
-    },
+      "Block container. Backed by react-native View. The cross-platform equivalent of a <div>. See https://reactnative.dev/docs/view.",
+    rnComponent: "View",
+    docsUrl: "https://reactnative.dev/docs/view",
   },
   {
     name: "Pressable",
     description:
-      "Clickable wrapper. Use instead of raw <button> so cross-platform styling stays consistent.",
-    props: {
-      children: { type: "ReactNode" },
-      style: { type: "CSSObject | StyleObject" },
-      onPress: {
-        type: "(event) => void",
-        description: "Fires on click/tap. Web preventDefault is auto-applied.",
-      },
-    },
+      "Tappable / clickable wrapper. Use `onPress` (NOT `onClick`). See https://reactnative.dev/docs/pressable.",
+    rnComponent: "Pressable",
+    docsUrl: "https://reactnative.dev/docs/pressable",
   },
   {
     name: "Image",
     description:
-      "Image. Pass an object with a `uri` (or a bare string on web). Falls back to `alt`.",
-    props: {
-      source: {
-        type: "{ uri: string } | string",
-        required: true,
-        description: "Source object or bare URL string.",
-      },
-      alt: { type: "string", description: "Alt text for accessibility." },
-      style: { type: "CSSObject | StyleObject" },
-    },
+      "Image. `source` accepts `{ uri }` or a string URL. See https://reactnative.dev/docs/image.",
+    rnComponent: "Image",
+    docsUrl: "https://reactnative.dev/docs/image",
   },
   {
     name: "ScrollView",
     description:
-      "Scrollable container. Pass `horizontal` to scroll on the x-axis.",
-    props: {
-      children: { type: "ReactNode" },
-      horizontal: { type: "boolean" },
-      style: { type: "CSSObject | StyleObject" },
-    },
+      "Scrollable container. Pass `horizontal` to scroll on the x-axis. See https://reactnative.dev/docs/scrollview.",
+    rnComponent: "ScrollView",
+    docsUrl: "https://reactnative.dev/docs/scrollview",
+  },
+  {
+    name: "TextInput",
+    description:
+      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). See https://reactnative.dev/docs/textinput.",
+    rnComponent: "TextInput",
+    docsUrl: "https://reactnative.dev/docs/textinput",
+  },
+  {
+    name: "FlatList",
+    description:
+      "Virtualised list. Render large arrays without paying for every row up front. Required props: `data`, `renderItem`, `keyExtractor`. See https://reactnative.dev/docs/flatlist.",
+    rnComponent: "FlatList",
+    docsUrl: "https://reactnative.dev/docs/flatlist",
+  },
+  {
+    name: "SectionList",
+    description:
+      "Like FlatList but grouped by section header. See https://reactnative.dev/docs/sectionlist.",
+    rnComponent: "SectionList",
+    docsUrl: "https://reactnative.dev/docs/sectionlist",
+  },
+  {
+    name: "ActivityIndicator",
+    description:
+      "Loading spinner. See https://reactnative.dev/docs/activityindicator.",
+    rnComponent: "ActivityIndicator",
+    docsUrl: "https://reactnative.dev/docs/activityindicator",
+  },
+  {
+    name: "Switch",
+    description:
+      "Toggle. Controlled — `value` + `onValueChange`. See https://reactnative.dev/docs/switch.",
+    rnComponent: "Switch",
+    docsUrl: "https://reactnative.dev/docs/switch",
+  },
+  {
+    name: "StyleSheet",
+    description:
+      "Helper for building style objects. `StyleSheet.create({ ... })` returns the same shape you can pass to `style={...}`. See https://reactnative.dev/docs/stylesheet.",
+    rnComponent: "StyleSheet",
+    docsUrl: "https://reactnative.dev/docs/stylesheet",
   },
 ];
 

package/dist/contract.js

@@ -1,17 +1,425 @@
-// Single-source-of-truth contract for the AI Widget Agent and every layer
-// that derives from it. See docs/design/ai-widget-contract.md for the full
-// rationale.
+// ESM mirror of contract.cjs. Generated from contract.cjs — keep both in lockstep.
+// runtime) can `require()` it directly without dynamic import gymnastics.
 //
-// The canonical data lives in `contract.cjs` so backend services (CJS
-// runtime) can `require()` it without dynamic import gymnastics. This file
-// is the ESM mirror — both modules export the exact same frozen
-// `CONTRACT` object, and the contract test asserts they stay in lockstep.
+// The ESM `contract.js` re-exports the SAME object as the `CONTRACT` named
+// export. The contract test asserts the two are identical (deep-equal) so
+// drift between this file and the ESM source-of-truth is caught in CI.
+//
+// Keep edits in lockstep between `contract.cjs` and `contract.js`. The
+// SDK build script copies both into `dist/`.
+
+const DEFAULT_THEME_TOKENS = Object.freeze({
+  colors: Object.freeze({
+    primary: "#ff6b5b",
+    onPrimary: "#ffffff",
+    surface: "#ffffff",
+    onSurface: "#111827",
+    surfaceMuted: "#f8fafc",
+    onSurfaceMuted: "#475569",
+    border: "#e2e8f0",
+    danger: "#dc2626",
+    success: "#059669",
+    warning: "#d97706",
+    info: "#0284c7",
+  }),
+  spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
+  radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
+  typography: Object.freeze({
+    fontFamily:
+      'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
+  }),
+});
+
+const HOOKS = [
+  {
+    name: "useTheme",
+    signature: "useTheme()",
+    returnShape: {
+      colors:
+        "{ primary, onPrimary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }",
+      spacing: "{ xs, sm, md, lg, xl }",
+      radii: "{ sm, md, lg, pill }",
+      typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
+    },
+    requiredContextSlice: ["workspace.theme"],
+    scopes: null,
+  },
+  {
+    name: "useI18n",
+    signature: "useI18n()",
+    returnShape: {
+      t: "(key: string, fallback?: string) => string",
+      locale: "string",
+    },
+    requiredContextSlice: ["i18n.t", "i18n.locale"],
+    scopes: null,
+  },
+  {
+    name: "useDatastoreQuery",
+    signature: "useDatastoreQuery(tableId, options?)",
+    returnShape: {
+      data: "Record[]",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
+  {
+    name: "useDatastoreMutation",
+    signature: "useDatastoreMutation(tableId)",
+    returnShape: {
+      create: "(record) => Promise<Record>  // rejects with DatastoreError",
+      update:
+        "(id, partial) => Promise<Record>  // rejects with DatastoreError",
+      delete: "(id) => Promise<void>  // rejects with DatastoreError",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.write:*"],
+  },
+  {
+    name: "useWidgetEvent",
+    signature: "useWidgetEvent(eventName)",
+    returnShape: { emit: "(payload?) => void" },
+    requiredContextSlice: ["events.emit"],
+    scopes: null,
+  },
+];
+
+// REQ-WSDK-RN-WEB: see contract.cjs for the source-of-truth comment.
+const PRIMITIVES = [
+  {
+    name: "Text",
+    description:
+      "Text node. Backed by react-native Text (web: react-native-web maps to a styled <div>). See https://reactnative.dev/docs/text.",
+    rnComponent: "Text",
+    docsUrl: "https://reactnative.dev/docs/text",
+  },
+  {
+    name: "View",
+    description:
+      "Block container. Backed by react-native View. The cross-platform equivalent of a <div>. See https://reactnative.dev/docs/view.",
+    rnComponent: "View",
+    docsUrl: "https://reactnative.dev/docs/view",
+  },
+  {
+    name: "Pressable",
+    description:
+      "Tappable / clickable wrapper. Use `onPress` (NOT `onClick`). See https://reactnative.dev/docs/pressable.",
+    rnComponent: "Pressable",
+    docsUrl: "https://reactnative.dev/docs/pressable",
+  },
+  {
+    name: "Image",
+    description:
+      "Image. `source` accepts `{ uri }` or a string URL. See https://reactnative.dev/docs/image.",
+    rnComponent: "Image",
+    docsUrl: "https://reactnative.dev/docs/image",
+  },
+  {
+    name: "ScrollView",
+    description:
+      "Scrollable container. Pass `horizontal` to scroll on the x-axis. See https://reactnative.dev/docs/scrollview.",
+    rnComponent: "ScrollView",
+    docsUrl: "https://reactnative.dev/docs/scrollview",
+  },
+  {
+    name: "TextInput",
+    description:
+      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). See https://reactnative.dev/docs/textinput.",
+    rnComponent: "TextInput",
+    docsUrl: "https://reactnative.dev/docs/textinput",
+  },
+  {
+    name: "FlatList",
+    description:
+      "Virtualised list. Render large arrays without paying for every row up front. Required props: `data`, `renderItem`, `keyExtractor`. See https://reactnative.dev/docs/flatlist.",
+    rnComponent: "FlatList",
+    docsUrl: "https://reactnative.dev/docs/flatlist",
+  },
+  {
+    name: "SectionList",
+    description:
+      "Like FlatList but grouped by section header. See https://reactnative.dev/docs/sectionlist.",
+    rnComponent: "SectionList",
+    docsUrl: "https://reactnative.dev/docs/sectionlist",
+  },
+  {
+    name: "ActivityIndicator",
+    description:
+      "Loading spinner. See https://reactnative.dev/docs/activityindicator.",
+    rnComponent: "ActivityIndicator",
+    docsUrl: "https://reactnative.dev/docs/activityindicator",
+  },
+  {
+    name: "Switch",
+    description:
+      "Toggle. Controlled — `value` + `onValueChange`. See https://reactnative.dev/docs/switch.",
+    rnComponent: "Switch",
+    docsUrl: "https://reactnative.dev/docs/switch",
+  },
+  {
+    name: "StyleSheet",
+    description:
+      "Helper for building style objects. `StyleSheet.create({ ... })` returns the same shape you can pass to `style={...}`. See https://reactnative.dev/docs/stylesheet.",
+    rnComponent: "StyleSheet",
+    docsUrl: "https://reactnative.dev/docs/stylesheet",
+  },
+];
+
+const CATEGORIES = [
+  "INPUT",
+  "DISPLAY",
+  "LAYOUT",
+  "DATA",
+  "MEDIA",
+  "COMMUNICATION",
+  "CUSTOM",
+];
+const PLATFORMS = ["web", "native"];
+
+// Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
+// more labels, lowercase alnum + hyphen, label starts with a letter. The
+// analyzer + the SDK validator both read this from the contract so a
+// rename / relaxation can only happen in one place.
+const MANIFEST_ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+
+const MANIFEST_SCHEMA = {
+  id: {
+    type: "string",
+    required: true,
+    description: "Reverse-DNS identifier, e.g. com.acme.hello.",
+    example: "com.acme.hello",
+    pattern: MANIFEST_ID_PATTERN,
+  },
+  name: {
+    type: "string",
+    required: true,
+    description: "Human-readable widget name.",
+  },
+  version: {
+    type: "string",
+    required: true,
+    description: "Semver. Patch bump per publish unless author overrides.",
+    example: "1.0.0",
+  },
+  category: {
+    type: "enum",
+    required: true,
+    description:
+      "One of " + CATEGORIES.join(", ") + ". Drives the palette section.",
+    values: CATEGORIES,
+  },
+  icon: {
+    type: "string",
+    required: true,
+    description: "Icon identifier, e.g. lucide:sparkles.",
+    default: "lucide:sparkles",
+  },
+  description: {
+    type: "string",
+    required: true,
+    description: "1-2 sentence storefront description.",
+  },
+  author: {
+    type: "object",
+    required: true,
+    description: "{ name: string, url?: string, email?: string }",
+  },
+  supportedPlatforms: {
+    type: "string[]",
+    required: true,
+    description: "Subset of " + PLATFORMS.join(", ") + ".",
+    default: ["web"],
+  },
+  minAppStudioVersion: {
+    type: "string",
+    required: true,
+    description: "Semver range, e.g. >=2.4.0.",
+    default: ">=0.1.0",
+  },
+  requestedScopes: {
+    type: "string[]",
+    required: true,
+    description:
+      "Permission scopes; use [] unless the widget reads/writes data.",
+    default: [],
+  },
+  propertySchema: {
+    type: "object",
+    required: true,
+    description: "Map of prop name to property definition.",
+    default: {},
+  },
+  events: {
+    type: "object[]",
+    required: true,
+    description: "Declared events. Each entry { name, payloadSchema? }.",
+    default: [],
+  },
+};
+
+const WIDGET_CONTEXT_SHAPE = {
+  props: {
+    description: "Resolved property values, shape per manifest.propertySchema.",
+    required: true,
+    fields: {},
+  },
+  widget: {
+    description:
+      "Identity of the currently rendered widget instance ({ id, version }).",
+    required: true,
+    fields: { id: "manifest.id", version: "manifest.version" },
+  },
+  user: {
+    description: "Signed-in user ({ id, email, displayName }).",
+    required: true,
+    fields: { id: "string", email: "string", displayName: "string" },
+  },
+  workspace: {
+    description:
+      "Workspace identity + resolved theme ({ id, slug, theme, locale }).",
+    required: true,
+    fields: {
+      id: "string",
+      slug: "string",
+      theme: "ThemeTokens",
+      locale: "string",
+    },
+  },
+  navigation: {
+    description: "{ push(path), replace(path), back() }.",
+    required: true,
+    fields: { push: "function", replace: "function", back: "function" },
+  },
+  datastore: {
+    description:
+      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) } }.",
+    required: true,
+    fields: { records: "function" },
+  },
+  events: {
+    description: "{ emit(name, payload) }.",
+    required: true,
+    fields: { emit: "function" },
+  },
+  i18n: {
+    description: "{ t(key, fallback?), locale }.",
+    required: true,
+    fields: { t: "function", locale: "string" },
+  },
+  logger: {
+    description:
+      "{ debug, info, warn, error } — host-routed; never use console.*.",
+    required: true,
+    fields: {
+      debug: "function",
+      info: "function",
+      warn: "function",
+      error: "function",
+    },
+  },
+};
+
+const BUNDLE_EXPORT_CONTRACT = [
+  {
+    name: "wrapped",
+    description:
+      "default export = defineWidget({ manifest, component }) → resolves to { manifest, component, _kind: 'widget' }. Public marketplace widgets.",
+    predicate:
+      "typeof mod.default === 'object' && typeof mod.default.component === 'function' && typeof mod.default.manifest === 'object'",
+    manifestSource: "mod.default.manifest",
+    audience: "public-marketplace",
+  },
+  {
+    name: "bare-component",
+    description:
+      "default export = function MyWidget(props) {...} → host pairs it with the installation's pinnedVersion.manifestJson. AI-agent widgets.",
+    predicate: "typeof mod.default === 'function'",
+    manifestSource: "installation.pinnedVersion.manifestJson",
+    audience: "ai-agent",
+  },
+];
+
+const BANNED_APIS = [
+  { identifier: "eval", reason: "Arbitrary code evaluation." },
+  {
+    identifier: "Function",
+    reason: "Function() constructor evaluates strings.",
+  },
+  {
+    identifier: "new Function",
+    reason: "Function() constructor evaluates strings.",
+  },
+  { identifier: "window", reason: "Host environment escape." },
+  {
+    identifier: "document",
+    reason: "Host environment escape; use SDK primitives.",
+  },
+  {
+    identifier: "process",
+    reason: "Node global; unavailable in the browser, banned for parity.",
+  },
+  {
+    identifier: "localStorage",
+    reason: "Bypasses host data model; not portable to native.",
+  },
+  {
+    identifier: "sessionStorage",
+    reason: "Same reason as localStorage.",
+  },
+  {
+    identifier: "fetch",
+    reason: "Direct network calls bypass the datastore client + tenant auth.",
+  },
+  {
+    identifier: "XMLHttpRequest",
+    reason: "Direct network calls bypass the datastore client + tenant auth.",
+  },
+  {
+    identifier: "import(",
+    reason: "Dynamic import bypasses the loader's allowlist.",
+  },
+  { identifier: "globalThis", reason: "Host environment escape." },
+];
+
+const ALLOWED_BARE_IMPORTS = ["react", "@colixsystems/widget-sdk"];
+
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Object.isFrozen(value)) return value;
+  for (const key of Object.keys(value)) deepFreeze(value[key]);
+  return Object.freeze(value);
+}
+
+const CONTRACT = deepFreeze({
+  version: "1.0.0",
+  hooks: HOOKS,
+  primitives: PRIMITIVES,
+  manifestSchema: MANIFEST_SCHEMA,
+  manifestCategories: CATEGORIES,
+  manifestPlatforms: PLATFORMS,
+  themeTokens: DEFAULT_THEME_TOKENS,
+  widgetContextShape: WIDGET_CONTEXT_SHAPE,
+  bundleExportContract: BUNDLE_EXPORT_CONTRACT,
+  bannedApis: BANNED_APIS,
+  allowedBareImports: ALLOWED_BARE_IMPORTS,
+});
 
-import { createRequire } from "module";
+function isHookAllowed(name) {
+  return CONTRACT.hooks.some((h) => h.name === name);
+}
 
-const require = createRequire(import.meta.url);
-const cjs = require("./contract.cjs");
+function requiredContextKeys() {
+  const keys = new Set();
+  for (const hook of CONTRACT.hooks) {
+    for (const dotPath of hook.requiredContextSlice) {
+      keys.add(dotPath.split(".")[0]);
+    }
+  }
+  return [...keys];
+}
 
-export const CONTRACT = cjs.CONTRACT;
-export const isHookAllowed = cjs.isHookAllowed;
-export const requiredContextKeys = cjs.requiredContextKeys;
+export { CONTRACT, isHookAllowed, requiredContextKeys };

package/dist/hooks.js

@@ -66,7 +66,7 @@ function useWidgetContextOrThrow(hookName) {
   if (ctx == null) {
     throw new Error(
       `${hookName} must be used inside a WidgetContextProvider. ` +
-        `The host (Studio, Player, or exported app) is responsible for mounting it.`
+        `The host (Studio, Player, or exported app) is responsible for mounting it.`,
     );
   }
   return ctx;
@@ -86,12 +86,17 @@ function toDatastoreError(err) {
       ? err.response.status
       : null;
   const bodyMessage =
-    err && err.response && err.response.data && typeof err.response.data.error === "string"
+    err &&
+    err.response &&
+    err.response.data &&
+    typeof err.response.data.error === "string"
       ? err.response.data.error
       : null;
   const fallbackMessage =
     bodyMessage ||
-    (err && typeof err.message === "string" ? err.message : "Datastore call failed");
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Datastore call failed");
   let code = "INTERNAL";
   if (status === 400 || status === 422) code = "VALIDATION";
   else if (status === 409) code = "CONSTRAINT_VIOLATION";
@@ -100,7 +105,12 @@ function toDatastoreError(err) {
   // Surface a structured fieldErrors map when the server emitted one
   // (record.controller.js shapes 422 bodies as `{ errors: [{ field, code }] }`).
   let fieldErrors;
-  if (err && err.response && err.response.data && Array.isArray(err.response.data.errors)) {
+  if (
+    err &&
+    err.response &&
+    err.response.data &&
+    Array.isArray(err.response.data.errors)
+  ) {
     const map = {};
     for (const entry of err.response.data.errors) {
       if (entry && typeof entry.field === "string") {
@@ -132,7 +142,9 @@ function toDatastoreError(err) {
 export function useDatastoreQuery(table, query) {
   const ctx = useWidgetContextOrThrow("useDatastoreQuery");
   if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
-    throw new Error("useDatastoreQuery: host did not inject a datastore client");
+    throw new Error(
+      "useDatastoreQuery: host did not inject a datastore client",
+    );
   }
   const [data, setData] = useState([]);
   const [loading, setLoading] = useState(Boolean(table));
@@ -216,7 +228,9 @@ export function useDatastoreQuery(table, query) {
 export function useDatastoreMutation(table) {
   const ctx = useWidgetContextOrThrow("useDatastoreMutation");
   if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
-    throw new Error("useDatastoreMutation: host did not inject a datastore client");
+    throw new Error(
+      "useDatastoreMutation: host did not inject a datastore client",
+    );
   }
   const ns = ctx.datastore.records(table);
   return {
@@ -292,7 +306,7 @@ export function useI18n() {
       }
       return typeof fallback === "string" ? fallback : key;
     },
-    [hostT]
+    [hostT],
   );
   return { t, locale };
 }

package/dist/index.d.ts

@@ -42,7 +42,11 @@ export interface WidgetPropertyDef {
   enum?: Array<{ value: unknown; label: string }>;
   items?: WidgetPropertyDef;
   properties?: Record<string, WidgetPropertyDef>;
-  ui?: { widget?: "textarea" | "slider" | "code"; group?: string; order?: number };
+  ui?: {
+    widget?: "textarea" | "slider" | "code";
+    group?: string;
+    order?: number;
+  };
   validation?: { min?: number; max?: number; pattern?: string };
 }
 
@@ -181,7 +185,10 @@ export interface WidgetContext<TProps = unknown> {
   };
   datastore: unknown; // typed by @colixsystems/datastore-client
   events: { emit(eventName: string, payload?: unknown): void };
-  i18n: { locale: string; t(key: string, vars?: Record<string, unknown>): string };
+  i18n: {
+    locale: string;
+    t(key: string, vars?: Record<string, unknown>): string;
+  };
   platform: "web" | "native";
   logger: {
     debug: (...args: unknown[]) => void;
@@ -226,16 +233,16 @@ export function defineWidget<TProps = Record<string, unknown>>(opts: {
 }): WidgetModule<TProps>;
 
 export function validateManifest(
-  manifest: unknown
+  manifest: unknown,
 ): { ok: true } | { ok: false; errors: string[] };
 
 export function validatePropertySchema(
-  schema: unknown
+  schema: unknown,
 ): { ok: true } | { ok: false; errors: string[] };
 
 export function validateProps<T = Record<string, unknown>>(
   schema: WidgetPropertySchema,
-  props: unknown
+  props: unknown,
 ): { ok: true; value: T } | { ok: false; errors: string[] };
 
 export interface Query {
@@ -260,16 +267,14 @@ export interface MutationApi<T> {
 
 export function useDatastoreQuery<T = unknown>(
   table: string,
-  query?: Query
+  query?: Query,
 ): QueryResult<T>;
 
 export function useDatastoreMutation<T = unknown>(
-  table: string
+  table: string,
 ): MutationApi<T>;
 
-export function useWidgetEvent(
-  name: string
-): (payload?: unknown) => void;
+export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
 export function useTheme(): ThemeTokens;
 
@@ -291,10 +296,14 @@ export class DatastoreError extends Error {
     | "NOT_FOUND"
     | "INTERNAL";
   fieldErrors?: Record<string, string>;
-  constructor(code: DatastoreError["code"], message: string, opts?: {
-    fieldErrors?: Record<string, string>;
-    cause?: unknown;
-  });
+  constructor(
+    code: DatastoreError["code"],
+    message: string,
+    opts?: {
+      fieldErrors?: Record<string, string>;
+      cause?: unknown;
+    },
+  );
 }
 
 export function WidgetContextProvider(props: {
@@ -302,12 +311,21 @@ export function WidgetContextProvider(props: {
   children?: ReactNode;
 }): JSX.Element;
 
-// Primitives — platform-aware. Type as opaque components.
+// Primitives — re-exported from `react-native` (web build aliases to
+// `react-native-web`). Typed as opaque components here; widget authors
+// targeting TypeScript should install `@types/react-native` for full
+// prop typing.
 export const Text: any;
 export const View: any;
 export const Pressable: any;
 export const Image: any;
 export const ScrollView: any;
+export const TextInput: any;
+export const FlatList: any;
+export const SectionList: any;
+export const ActivityIndicator: any;
+export const Switch: any;
+export const StyleSheet: any;
 
 // Linter
 export interface LintFinding {
@@ -375,7 +393,14 @@ export interface AiWidgetContract {
   readonly manifestPlatforms: ReadonlyArray<string>;
   readonly themeTokens: ThemeTokens;
   readonly widgetContextShape: Readonly<
-    Record<string, { description: string; required: boolean; fields: Record<string, unknown> }>
+    Record<
+      string,
+      {
+        description: string;
+        required: boolean;
+        fields: Record<string, unknown>;
+      }
+    >
   >;
   readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
   readonly bannedApis: ReadonlyArray<ContractBannedApi>;

package/dist/index.js

@@ -14,6 +14,18 @@ export {
   useTheme,
   useI18n,
 } from "./hooks.js";
-export { Text, View, Pressable, Image, ScrollView } from "./primitives.js";
+export {
+  Text,
+  View,
+  Pressable,
+  Image,
+  ScrollView,
+  TextInput,
+  FlatList,
+  SectionList,
+  ActivityIndicator,
+  Switch,
+  StyleSheet,
+} from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/index.native.js

@@ -14,6 +14,18 @@ export {
   useTheme,
   useI18n,
 } from "./hooks.js";
-export { Text, View, Pressable, Image, ScrollView } from "./primitives.native.js";
+export {
+  Text,
+  View,
+  Pressable,
+  Image,
+  ScrollView,
+  TextInput,
+  FlatList,
+  SectionList,
+  ActivityIndicator,
+  Switch,
+  StyleSheet,
+} from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/linter.cjs

@@ -0,0 +1,104 @@
+// CommonJS-flavoured copy of the linter so backend services (CJS runtime)
+// can `require()` it directly without dynamic-import gymnastics.
+//
+// The ESM `linter.js` is the source-of-truth. This file MUST mirror its
+// rule set byte-for-byte — the contract test in packages/widget-sdk
+// asserts the two are behaviour-equivalent. When you edit one, edit the
+// other in the same PR. (Pattern matches `contract.cjs` / `contract.js`.)
+//
+// The SDK build script copies both into `dist/`.
+
+"use strict";
+
+const { CONTRACT } = require("./contract.cjs");
+
+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*\(/,
+    };
+  }
+  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),
+);
+
+const EXTRA_RULES = [
+  {
+    id: "no-auth-store-import",
+    label: "widgets must not import the host's auth store",
+    pattern: /useAuthStore/,
+  },
+  {
+    id: "no-axios-import",
+    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];
+
+function bannedIdentifiers() {
+  return CONTRACT.bannedApis.map((b) => b.identifier);
+}
+
+function lintSource(source) {
+  if (typeof source !== "string") {
+    return {
+      ok: false,
+      findings: [
+        { rule: "input", label: "source must be a string", line: 0, snippet: "" },
+      ],
+    };
+  }
+  const findings = [];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const rule of RULES) {
+      if (rule.pattern.test(line)) {
+        findings.push({
+          rule: rule.id,
+          label: rule.label,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+      }
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+
+module.exports = { lintSource, bannedIdentifiers };

package/dist/manifest.js

@@ -1,15 +1,144 @@
-// 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.
-//
-// The implementation lives in `manifest.cjs` so backend services (CJS
-// runtime) can `require` the same validator the SDK ships to ESM
-// consumers. This file is a thin re-export so ESM imports keep working
-// unchanged.
+// 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.
 
-import { createRequire } from "module";
+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"]);
 
-const require = createRequire(import.meta.url);
-const cjs = require("./manifest.cjs");
+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;
+}
 
-export const validateManifest = cjs.validateManifest;
-export const canonicalCategory = cjs.canonicalCategory;
+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 };
+}
+
+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.4.1",
+  "version": "0.6.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,7 +51,8 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "react-native": "*"
+    "react-native": "*",
+    "react-native-web": ">=0.19.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -59,6 +60,9 @@
     },
     "react-native": {
       "optional": true
+    },
+    "react-native-web": {
+      "optional": true
     }
   },
   "keywords": [