@colixsystems/widget-sdk 0.3.0 → 0.4.1

package/README.md

@@ -6,11 +6,34 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.3.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.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**.
 
-### What's new in 0.3.0
+### What's new in 0.4.1
 
-Additive: `WidgetManifest` now carries an optional `datastoreTemplate` field. When a tenant installs a widget that declares one, the table set is seeded into their workspace alongside the install. Tables follow the existing built-in template semantics (auto-suffixed naming, REQ-ACL-05 creator-grants, REQ-TEMPLATES-ACL public grants, REQ-ACL-RELINHERIT cross-relation inheritance) and persist when the widget is later uninstalled. See `WidgetDatastoreTemplate` in `src/index.d.ts` for the structural constraints — at most 8 tables per widget, 24 columns per table, RELATION columns address siblings by `suffix`.
+- **`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.
+
+### What's new in 0.4.0
+
+- **`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.
+  - `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.
+  - `bundleExportContract` — the two default-export shapes the loader accepts.
+  - `bannedApis` — the global allowlist gate.
+  - `allowedBareImports` — `react`, `@colixsystems/widget-sdk`.
+
+- **`useDatastoreQuery` is now stateful.** Returns `{ data, loading, error, refetch }`. Previously the hook returned the raw `list(...)` promise; widgets that called `.map(...)` synchronously on the result threw on first render. Migration: replace `const rows = useDatastoreQuery(...)` with `const { data, loading, error } = useDatastoreQuery(...)`. `data` is always an array (empty when the table is unbound or loading).
+
+- **`DatastoreError` is now a named export.** Mutations throw a structured `DatastoreError` with `.code` (`VALIDATION` / `CONSTRAINT_VIOLATION` / `FORBIDDEN` / `NOT_FOUND` / `INTERNAL`) and an optional `.fieldErrors` map populated from the host's 422 payload. Widgets can branch on `err.code` without parsing axios messages.
+
+- **`useI18n().t` now honours `fallback`.** `t(key, fallback)` returns `fallback` when the host's translation table has no entry for `key`.
+
+### What was in 0.3.0
+
+Additive: `WidgetManifest` carries an optional `datastoreTemplate` field. When a tenant installs a widget that declares one, the table set is seeded into their workspace alongside the install. Tables follow the existing built-in template semantics (auto-suffixed naming, REQ-ACL-05 creator-grants, REQ-TEMPLATES-ACL public grants, REQ-ACL-RELINHERIT cross-relation inheritance) and persist when the widget is later uninstalled. See `WidgetDatastoreTemplate` in `src/index.d.ts` for the structural constraints — at most 8 tables per widget, 24 columns per table, RELATION columns address siblings by `suffix`.
 
 ## Public API
 

package/dist/_theme-tokens.js

@@ -0,0 +1,10 @@
+// Re-export of the default theme tokens from the canonical contract data.
+// Exists so the frontend's `widgetTheme.js` can keep its existing
+// `DEFAULT_THEME_TOKENS` named export without reaching into the contract
+// path itself. The values are the same Object.freeze'd reference as
+// CONTRACT.themeTokens — assertion #6 in the contract test relies on
+// referential identity.
+
+import { CONTRACT } from "./contract.js";
+
+export const DEFAULT_THEME_TOKENS = CONTRACT.themeTokens;

package/dist/contract.cjs

@@ -0,0 +1,404 @@
+// CommonJS-flavoured copy of the contract data so backend services (CJS
+// runtime) can `require()` it directly without dynamic import gymnastics.
+//
+// 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,
+  },
+];
+
+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." },
+    },
+  },
+  {
+    name: "View",
+    description:
+      "Block container. Web: <div>. Native: react-native View. Use for layout boxes.",
+    props: {
+      children: { type: "ReactNode" },
+      style: { type: "CSSObject | StyleObject" },
+    },
+  },
+  {
+    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.",
+      },
+    },
+  },
+  {
+    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" },
+    },
+  },
+  {
+    name: "ScrollView",
+    description:
+      "Scrollable container. Pass `horizontal` to scroll on the x-axis.",
+    props: {
+      children: { type: "ReactNode" },
+      horizontal: { type: "boolean" },
+      style: { type: "CSSObject | StyleObject" },
+    },
+  },
+];
+
+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,
+});
+
+function isHookAllowed(name) {
+  return CONTRACT.hooks.some((h) => h.name === name);
+}
+
+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];
+}
+
+module.exports = { CONTRACT, isHookAllowed, requiredContextKeys };

package/dist/contract.js

@@ -0,0 +1,17 @@
+// 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.
+//
+// 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.
+
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const cjs = require("./contract.cjs");
+
+export const CONTRACT = cjs.CONTRACT;
+export const isHookAllowed = cjs.isHookAllowed;
+export const requiredContextKeys = cjs.requiredContextKeys;

package/dist/hooks.js

@@ -1,15 +1,58 @@
-// Widget hooks per docs/architecture/widget-marketplace.md §3.1.
-// Each hook reads from the host-provided WidgetContext via React context, then
-// delegates to the host implementation. Bodies are intentionally slim — the
-// hosts (Studio, Player, exported app) own the runtime semantics.
+// Widget hooks per docs/architecture/widget-marketplace.md §3.1 and the
+// CONTRACT in ./contract.js (the single source of truth — when a hook's
+// signature or return shape changes, update both this file and the
+// CONTRACT entry in lockstep).
+//
+// Each hook reads from the host-provided WidgetContext via React context,
+// then delegates to the host implementation. The hosts (Studio, Player,
+// exported app) own the runtime semantics — this file is the SDK surface
+// widgets call.
 //
 // This file avoids JSX so it can ship as a plain .js without a transform.
 
-import React, { createContext, useContext, useCallback } from "react";
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
 
+/**
+ * Structured error thrown by `useDatastoreMutation` callbacks (and surfaced
+ * by `useDatastoreQuery` in its `error` slot). Carries a stable `code` so
+ * widgets can branch on the error class without parsing axios message
+ * strings.
+ *
+ * `code` is one of:
+ *   - "VALIDATION"            — 400 / 422 from the datastore
+ *   - "CONSTRAINT_VIOLATION"  — 409 from the datastore
+ *   - "FORBIDDEN"             — 403 from the datastore
+ *   - "NOT_FOUND"             — 404 from the datastore
+ *   - "INTERNAL"              — anything else (network, 5xx, axios timeout)
+ *
+ * `fieldErrors` (when present) is a flat map of field name to per-field
+ * error message, populated when the datastore returned a structured
+ * 400/422 payload with `errors: [{ field, code }, ...]`.
+ */
+export class DatastoreError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "DatastoreError";
+    this.code = code;
+    if (opts && opts.fieldErrors && typeof opts.fieldErrors === "object") {
+      this.fieldErrors = opts.fieldErrors;
+    }
+    if (opts && opts.cause) {
+      this.cause = opts.cause;
+    }
+  }
+}
+
 /**
  * Wraps children with the host-provided WidgetContext.
  * The host (Studio/Player/native shell) builds the value and renders this provider.
@@ -29,19 +72,147 @@ function useWidgetContextOrThrow(hookName) {
   return ctx;
 }
 
-// v0.1 scope: returns the host's datastore-backed query result.
-// The host owns suspense/caching; this hook is a passthrough to ctx.datastore.
+// --------------------------------------------------------------- helpers
+
+/**
+ * Coerce an arbitrary thrown value (axios error, plain Error, string) into
+ * a DatastoreError with a stable `.code`. Reads `error.response.status` if
+ * present (axios shape) and falls back to inspecting the message string.
+ */
+function toDatastoreError(err) {
+  if (err instanceof DatastoreError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyMessage =
+    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");
+  let code = "INTERNAL";
+  if (status === 400 || status === 422) code = "VALIDATION";
+  else if (status === 409) code = "CONSTRAINT_VIOLATION";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "NOT_FOUND";
+  // 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)) {
+    const map = {};
+    for (const entry of err.response.data.errors) {
+      if (entry && typeof entry.field === "string") {
+        map[entry.field] = entry.message || entry.code || "Invalid value";
+      }
+    }
+    if (Object.keys(map).length > 0) fieldErrors = map;
+  }
+  return new DatastoreError(code, fallbackMessage, {
+    cause: err,
+    fieldErrors,
+  });
+}
+
+// --------------------------------------------------------------- hooks
+
+/**
+ * Stateful datastore query hook. Returns { data, loading, error, refetch }.
+ *
+ * The host's datastore client exposes `records(table).list(query)` which
+ * returns a Promise<Record[]>. We hold the result in component state and
+ * re-fetch when [table, JSON.stringify(query)] changes. `refetch` re-runs
+ * the same call on demand.
+ *
+ * When `table` is falsy (e.g. the user hasn't bound a `tableRef` property
+ * yet), the hook resolves to { data: [], loading: false, error: null,
+ * refetch } so the widget can render its empty state without throwing.
+ */
 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");
   }
-  // The host-injected datastore is expected to expose a `useRecords(table, query)` hook;
-  // v0.1 stub returns the raw promise interface and lets the host wire React Query.
-  return ctx.datastore.records(table).list(query);
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(Boolean(table));
+  const [error, setError] = useState(null);
+
+  // Capture the latest table + query in refs so refetch() — a stable
+  // callback identity — always reads the current arguments without having
+  // to be re-bound on every render.
+  //
+  // We hold ctx.datastore.records in a ref for the same reason: the
+  // Studio / Player / PageRenderer rebuild the WidgetContext value
+  // inside their render closure on every render, so `ctx` is a fresh
+  // object identity every render. If `doFetch` listed `[ctx]` in its
+  // dep array, the callback identity (and therefore the `refetch`
+  // surface) would change every render and any widget that put
+  // `refetch` in a useEffect dep array would loop forever. The effect
+  // that drives the actual initial fetch keeps `[table, queryKey]` so
+  // it only re-runs when the bound table or the query payload changes.
+  const tableRef = useRef(table);
+  const queryRef = useRef(query);
+  const recordsRef = useRef(ctx.datastore.records);
+  tableRef.current = table;
+  queryRef.current = query;
+  recordsRef.current = ctx.datastore.records;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const t = tableRef.current;
+    if (!t) {
+      // No table bound yet — collapse to a stable empty result without
+      // a network round-trip.
+      setLoading(false);
+      setError(null);
+      setData([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const ns = recordsRef.current(t);
+      const rows = await ns.list(queryRef.current);
+      // Discard the result if a newer fetch has started since we kicked off.
+      if (runRef.current !== myRun) return;
+      setData(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  // Re-run on mount and whenever [table, JSON.stringify(query)] changes.
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table, queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { data, loading, error, refetch };
 }
 
-// v0.1 scope: returns { create, update, delete } from the injected datastore client.
+/**
+ * Datastore mutation hook. Returns { create, update, delete }, each method
+ * returning a Promise. Rejected promises throw a DatastoreError carrying a
+ * stable `.code` (`VALIDATION`, `CONSTRAINT_VIOLATION`, `FORBIDDEN`,
+ * `NOT_FOUND`, `INTERNAL`) plus an optional `fieldErrors` map.
+ */
 export function useDatastoreMutation(table) {
   const ctx = useWidgetContextOrThrow("useDatastoreMutation");
   if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
@@ -49,28 +220,79 @@ export function useDatastoreMutation(table) {
   }
   const ns = ctx.datastore.records(table);
   return {
-    create: (values) => ns.create(values),
-    update: (id, values) => ns.update(id, values),
-    delete: (id) => ns.delete(id),
+    create: async (values) => {
+      try {
+        return await ns.create(values);
+      } catch (err) {
+        throw toDatastoreError(err);
+      }
+    },
+    update: async (id, values) => {
+      try {
+        return await ns.update(id, values);
+      } catch (err) {
+        throw toDatastoreError(err);
+      }
+    },
+    delete: async (id) => {
+      try {
+        return await ns.delete(id);
+      } catch (err) {
+        throw toDatastoreError(err);
+      }
+    },
   };
 }
 
-// v0.1 scope: emits a named event through ctx.events.emit. Page-level event
-// bindings (subscribed by the host) decide what happens next.
+/**
+ * Emit a named widget event through ctx.events.emit. Page-level event
+ * bindings (subscribed by the host) decide what happens next.
+ */
 export function useWidgetEvent(name) {
   const ctx = useWidgetContextOrThrow("useWidgetEvent");
   return useCallback((payload) => ctx.events.emit(name, payload), [ctx, name]);
 }
 
-// v0.1 scope: returns ThemeTokens. Host owns theme resolution per workspace.
+/**
+ * Returns the host-provided theme tokens. The host guarantees every field
+ * documented in CONTRACT.themeTokens is present (defaults merged with
+ * tenant overrides), so widgets read `theme.colors.primary` without
+ * optional chaining.
+ */
 export function useTheme() {
   const ctx = useWidgetContextOrThrow("useTheme");
   return ctx.workspace.theme;
 }
 
-// v0.1 scope: returns { locale, t }. Host owns translation tables;
-// the SDK does not bundle a translation engine.
+/**
+ * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
+ * the host's translation table and falls back to `fallback ?? key` when
+ * the key is missing. The host's i18n.t may or may not honour the two-arg
+ * form; we degrade gracefully either way.
+ */
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
-  return ctx.i18n;
+  const i18n = ctx.i18n || {};
+  const locale = typeof i18n.locale === "string" ? i18n.locale : "en";
+  const hostT = typeof i18n.t === "function" ? i18n.t : null;
+  const t = useCallback(
+    (key, fallback) => {
+      if (typeof key !== "string" || !key) {
+        return typeof fallback === "string" ? fallback : "";
+      }
+      if (hostT) {
+        // Try the two-arg form first; if the host's `t` ignores `fallback`
+        // and returns the bare key on a miss, swap in the fallback.
+        const out = hostT(key, fallback);
+        if (typeof out === "string" && out.length > 0 && out !== key) {
+          return out;
+        }
+        // Host returned the key (unresolved) or nothing usable.
+        return typeof fallback === "string" ? fallback : key;
+      }
+      return typeof fallback === "string" ? fallback : key;
+    },
+    [hostT]
+  );
+  return { t, locale };
 }

package/dist/index.d.ts

@@ -275,9 +275,28 @@ export function useTheme(): ThemeTokens;
 
 export function useI18n(): {
   locale: string;
-  t(key: string, vars?: Record<string, unknown>): string;
+  t(key: string, fallback?: string): string;
 };
 
+/**
+ * Error class thrown by useDatastoreMutation callbacks (and surfaced by
+ * useDatastoreQuery in its `error` slot). The `code` is a stable
+ * categorisation widgets can branch on.
+ */
+export class DatastoreError extends Error {
+  code:
+    | "VALIDATION"
+    | "CONSTRAINT_VIOLATION"
+    | "FORBIDDEN"
+    | "NOT_FOUND"
+    | "INTERNAL";
+  fieldErrors?: Record<string, string>;
+  constructor(code: DatastoreError["code"], message: string, opts?: {
+    fieldErrors?: Record<string, string>;
+    cause?: unknown;
+  });
+}
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;
@@ -301,3 +320,69 @@ export function lintSource(source: string): {
   ok: boolean;
   findings: LintFinding[];
 };
+
+// --------------------------------------------------------------- CONTRACT
+//
+// Single-source-of-truth contract artefact. See docs/design/ai-widget-contract.md.
+// The runtime value is `Object.freeze`d; the type below describes the
+// public shape consumers can read.
+
+export interface ContractHookEntry {
+  name: string;
+  signature: string;
+  returnShape: Record<string, string>;
+  requiredContextSlice: string[];
+  scopes: string[] | null;
+}
+
+export interface ContractPrimitiveEntry {
+  name: string;
+  description: string;
+  props: Record<
+    string,
+    { type: string; required?: boolean; description?: string }
+  >;
+}
+
+export interface ContractManifestField {
+  type: string;
+  required: boolean;
+  description?: string;
+  default?: unknown;
+  values?: readonly string[];
+  example?: unknown;
+}
+
+export interface ContractBundleShape {
+  name: string;
+  description: string;
+  predicate: string;
+  manifestSource: string;
+  audience: string;
+}
+
+export interface ContractBannedApi {
+  identifier: string;
+  reason: string;
+}
+
+export interface AiWidgetContract {
+  readonly version: string;
+  readonly hooks: ReadonlyArray<ContractHookEntry>;
+  readonly primitives: ReadonlyArray<ContractPrimitiveEntry>;
+  readonly manifestSchema: Readonly<Record<string, ContractManifestField>>;
+  readonly manifestCategories: ReadonlyArray<string>;
+  readonly manifestPlatforms: ReadonlyArray<string>;
+  readonly themeTokens: ThemeTokens;
+  readonly widgetContextShape: Readonly<
+    Record<string, { description: string; required: boolean; fields: Record<string, unknown> }>
+  >;
+  readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
+  readonly bannedApis: ReadonlyArray<ContractBannedApi>;
+  readonly allowedBareImports: ReadonlyArray<string>;
+}
+
+export const CONTRACT: AiWidgetContract;
+
+export function isHookAllowed(name: string): boolean;
+export function requiredContextKeys(): string[];

package/dist/index.js

@@ -7,6 +7,7 @@ export { validateManifest, canonicalCategory } from "./manifest.js";
 export { validatePropertySchema, validateProps } from "./property-schema.js";
 export {
   WidgetContextProvider,
+  DatastoreError,
   useDatastoreQuery,
   useDatastoreMutation,
   useWidgetEvent,
@@ -14,4 +15,5 @@ export {
   useI18n,
 } from "./hooks.js";
 export { Text, View, Pressable, Image, ScrollView } from "./primitives.js";
-export { lintSource } from "./linter.js";
+export { lintSource, bannedIdentifiers } from "./linter.js";
+export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

package/dist/index.native.js

@@ -7,6 +7,7 @@ export { validateManifest, canonicalCategory } from "./manifest.js";
 export { validatePropertySchema, validateProps } from "./property-schema.js";
 export {
   WidgetContextProvider,
+  DatastoreError,
   useDatastoreQuery,
   useDatastoreMutation,
   useWidgetEvent,
@@ -14,4 +15,5 @@ export {
   useI18n,
 } from "./hooks.js";
 export { Text, View, Pressable, Image, ScrollView } from "./primitives.native.js";
-export { lintSource } from "./linter.js";
+export { lintSource, bannedIdentifiers } from "./linter.js";
+export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";

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,133 +1,15 @@
 // 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.
 
-// 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"]);
+import { createRequire } from "module";
 
-/**
- * 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) {
-  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-]+)+$/;
+const require = createRequire(import.meta.url);
+const cjs = require("./manifest.cjs");
 
-function isNonEmptyString(v) {
-  return typeof v === "string" && v.length > 0;
-}
-
-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) {
-  const errors = [];
-
-  if (m === null || typeof m !== "object") {
-    return { ok: false, errors: ["manifest must be an object"] };
-  }
-
-  const manifest = /** @type {Record<string, unknown>} */ (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, 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,
-    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 = /** @type {Record<string, unknown>} */ (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(/** @type {string} */ (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;
-      }
-      const ev = /** @type {Record<string, unknown>} */ (e);
-      if (!isNonEmptyString(ev.name)) {
-        errors.push("manifest.events[].name must be a non-empty string");
-      }
-    }
-  }
-
-  return errors.length === 0 ? { ok: true } : { ok: false, errors };
-}
+export const validateManifest = cjs.validateManifest;
+export const canonicalCategory = cjs.canonicalCategory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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"