@colixsystems/widget-sdk 0.2.0 → 0.4.1

package/README.md

@@ -6,7 +6,34 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.2.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.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.
+
+### 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;