@colixsystems/widget-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppStudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @colixsystems/widget-sdk
+
+Common widget interface for [AppStudio](https://github.com/appstudio). This package implements the contract that every widget — built-in or third-party, web or native — speaks: a `WidgetManifest`, a `WidgetContext`, a property schema, the helper hooks, and the static linter that gates submissions.
+
+See the design reference for the full architecture: [`docs/architecture/widget-marketplace.md`](../../docs/architecture/widget-marketplace.md), specifically section 3.1.
+
+## Status
+
+`v0.1.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**.
+
+## Public API
+
+```js
+import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@colixsystems/widget-sdk";
+```
+
+- `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.
+- `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
+
+## Linter
+
+```sh
+npx appstudio-widget lint path/to/widget.js
+```
+
+Scans for banned patterns (`eval`, `new Function`, dynamic `import()`, direct imports of host stores, raw axios). Exits 1 on findings.
+
+```js
+import { lintSource } from "@colixsystems/widget-sdk/linter";
+const report = lintSource(source);
+```
+
+## Why no TypeScript dependency?
+
+The package is plain ESM JavaScript with hand-written `.d.ts` ambient types. Consumers using TypeScript get full IntelliSense; consumers using JavaScript pay nothing.

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// CLI entry for `appstudio-widget lint <path>`.
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+import { lintSource } from "./linter.js";
+
+function usage() {
+  stderr.write("Usage: appstudio-widget lint <path>\n");
+  exit(2);
+}
+
+const args = argv.slice(2);
+if (args.length === 0) usage();
+const [cmd, ...rest] = args;
+
+if (cmd === "lint") {
+  if (rest.length === 0) usage();
+  const filePath = resolve(rest[0]);
+  let source;
+  try {
+    source = readFileSync(filePath, "utf8");
+  } catch (err) {
+    stderr.write(`Could not read ${filePath}: ${err.message}\n`);
+    exit(1);
+  }
+  const { ok, findings } = lintSource(source);
+  if (ok) {
+    stdout.write(`${filePath}: clean\n`);
+    exit(0);
+  }
+  stderr.write(`${filePath}: ${findings.length} finding(s)\n`);
+  for (const f of findings) {
+    stderr.write(`  [${f.rule}] line ${f.line}: ${f.label}\n    ${f.snippet}\n`);
+  }
+  exit(1);
+} else {
+  stderr.write(`Unknown command "${cmd}"\n`);
+  usage();
+}

package/dist/define-widget.js

@@ -0,0 +1,29 @@
+// defineWidget per docs/architecture/widget-marketplace.md §3.1.
+// Runs manifest shape validation synchronously and throws on failure.
+
+import { validateManifest } from "./manifest.js";
+
+/**
+ * Define an AppStudio widget module.
+ * @param {{ manifest: object, component: Function }} opts
+ * @returns {{ manifest: object, component: Function, _kind: 'appstudio-widget-module' }}
+ */
+export function defineWidget(opts) {
+  if (opts === null || typeof opts !== "object") {
+    throw new TypeError("defineWidget: opts must be an object");
+  }
+  const { manifest, component } = opts;
+  if (typeof component !== "function") {
+    throw new TypeError("defineWidget: component must be a function");
+  }
+  const result = validateManifest(manifest);
+  if (!result.ok) {
+    const msg = `Invalid widget manifest:\n  - ${result.errors.join("\n  - ")}`;
+    throw new Error(msg);
+  }
+  return {
+    manifest,
+    component,
+    _kind: "appstudio-widget-module",
+  };
+}

package/dist/hooks.js

@@ -0,0 +1,76 @@
+// 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.
+//
+// This file avoids JSX so it can ship as a plain .js without a transform.
+
+import React, { createContext, useContext, useCallback } from "react";
+
+/** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
+const HostWidgetContext = createContext(null);
+
+/**
+ * Wraps children with the host-provided WidgetContext.
+ * The host (Studio/Player/native shell) builds the value and renders this provider.
+ */
+export function WidgetContextProvider({ value, children }) {
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
+function useWidgetContextOrThrow(hookName) {
+  const ctx = useContext(HostWidgetContext);
+  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.`
+    );
+  }
+  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.
+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);
+}
+
+// v0.1 scope: returns { create, update, delete } from the injected datastore client.
+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");
+  }
+  const ns = ctx.datastore.records(table);
+  return {
+    create: (values) => ns.create(values),
+    update: (id, values) => ns.update(id, values),
+    delete: (id) => ns.delete(id),
+  };
+}
+
+// v0.1 scope: emits a named 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.
+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.
+export function useI18n() {
+  const ctx = useWidgetContextOrThrow("useI18n");
+  return ctx.i18n;
+}

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+// Hand-written ambient types for @colixsystems/widget-sdk.
+// The package itself is plain ESM JavaScript; this file is shipped through the
+// `types` field for IDE IntelliSense without forcing consumers to install
+// TypeScript. Keep in sync with src/index.js when adding exports.
+
+import type { ReactNode, JSX } from "react";
+
+export type WidgetCategory =
+  | "input"
+  | "display"
+  | "layout"
+  | "data"
+  | "media"
+  | "communication"
+  | "custom";
+
+export type WidgetScope = string; // e.g. "datastore.read:orders"
+
+export type WidgetPropertyType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "color"
+  | "icon"
+  | "image"
+  | "select"
+  | "multiselect"
+  | "tableRef"
+  | "columnRef"
+  | "recordBinding"
+  | "expression"
+  | "eventBinding"
+  | "object"
+  | "array";
+
+export interface WidgetPropertyDef {
+  type: WidgetPropertyType;
+  label: string;
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  enum?: Array<{ value: unknown; label: string }>;
+  items?: WidgetPropertyDef;
+  properties?: Record<string, WidgetPropertyDef>;
+  ui?: { widget?: "textarea" | "slider" | "code"; group?: string; order?: number };
+  validation?: { min?: number; max?: number; pattern?: string };
+}
+
+export type WidgetPropertySchema = Record<string, WidgetPropertyDef>;
+
+export interface WidgetEventDescriptor {
+  name: string;
+  description?: string;
+  payloadSchema?: WidgetPropertySchema;
+}
+
+export interface WidgetManifest {
+  id: string;
+  name: string;
+  version: string;
+  category: WidgetCategory;
+  icon: string;
+  description: string;
+  author: { name: string; url?: string; email?: string };
+  supportedPlatforms: Array<"web" | "native">;
+  minAppStudioVersion: string;
+  requestedScopes: WidgetScope[];
+  propertySchema: WidgetPropertySchema;
+  events: WidgetEventDescriptor[];
+}
+
+export interface ThemeTokens {
+  colors: {
+    primary: string;
+    surface: string;
+    onSurface: string;
+    danger: string;
+    [k: string]: string;
+  };
+  spacing: { xs: number; sm: number; md: number; lg: number; xl: number };
+  radii: { sm: number; md: number; lg: number; pill: number };
+  typography: {
+    fontFamily: string;
+    sizes: { xs: number; sm: number; md: number; lg: number; xl: number };
+  };
+}
+
+export interface WidgetContext<TProps = unknown> {
+  props: TProps;
+  widget: { id: string; instanceId: string; version: string };
+  user: {
+    id: string | null;
+    email: string | null;
+    displayName: string | null;
+    roles: string[];
+    groupIds: string[];
+  };
+  workspace: {
+    id: string;
+    name: string;
+    locale: string;
+    theme: ThemeTokens;
+  };
+  navigation: {
+    goTo(pageId: string, params?: Record<string, string>): void;
+    goBack(): void;
+    currentRoute: { pageId: string; params: Record<string, string> };
+  };
+  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 };
+  platform: "web" | "native";
+  logger: {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
+}
+
+export interface WidgetModule<TProps = unknown> {
+  manifest: WidgetManifest;
+  component: (ctx: WidgetContext<TProps>) => JSX.Element;
+  _kind: "appstudio-widget-module";
+}
+
+export function defineWidget<TProps = unknown>(opts: {
+  manifest: WidgetManifest;
+  component: (ctx: WidgetContext<TProps>) => JSX.Element;
+}): WidgetModule<TProps>;
+
+export function validateManifest(
+  manifest: unknown
+): { ok: true } | { ok: false; errors: string[] };
+
+export function validatePropertySchema(
+  schema: unknown
+): { ok: true } | { ok: false; errors: string[] };
+
+export function validateProps<T = Record<string, unknown>>(
+  schema: WidgetPropertySchema,
+  props: unknown
+): { ok: true; value: T } | { ok: false; errors: string[] };
+
+export interface Query {
+  filter?: Record<string, unknown>;
+  sort?: Array<{ field: string; dir: "asc" | "desc" }>;
+  limit?: number;
+  cursor?: string;
+}
+
+export interface QueryResult<T> {
+  data: T[];
+  loading: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+}
+
+export interface MutationApi<T> {
+  create(values: Partial<T>): Promise<T>;
+  update(id: string, values: Partial<T>): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+
+export function useDatastoreQuery<T = unknown>(
+  table: string,
+  query?: Query
+): QueryResult<T>;
+
+export function useDatastoreMutation<T = unknown>(
+  table: string
+): MutationApi<T>;
+
+export function useWidgetEvent(
+  name: string
+): (payload?: unknown) => void;
+
+export function useTheme(): ThemeTokens;
+
+export function useI18n(): {
+  locale: string;
+  t(key: string, vars?: Record<string, unknown>): string;
+};
+
+export function WidgetContextProvider(props: {
+  value: WidgetContext;
+  children?: ReactNode;
+}): JSX.Element;
+
+// Primitives — platform-aware. Type as opaque components.
+export const Text: any;
+export const View: any;
+export const Pressable: any;
+export const Image: any;
+export const ScrollView: any;
+
+// Linter
+export interface LintFinding {
+  rule: string;
+  label: string;
+  line: number;
+  snippet: string;
+}
+export function lintSource(source: string): {
+  ok: boolean;
+  findings: LintFinding[];
+};

package/dist/index.js

@@ -0,0 +1,17 @@
+// Web entry. Re-exports the public surface of @colixsystems/widget-sdk.
+// The `react-native` field in package.json points Metro at index.native.js
+// instead — keep these two files synchronised when adding exports.
+
+export { defineWidget } from "./define-widget.js";
+export { validateManifest, canonicalCategory } from "./manifest.js";
+export { validatePropertySchema, validateProps } from "./property-schema.js";
+export {
+  WidgetContextProvider,
+  useDatastoreQuery,
+  useDatastoreMutation,
+  useWidgetEvent,
+  useTheme,
+  useI18n,
+} from "./hooks.js";
+export { Text, View, Pressable, Image, ScrollView } from "./primitives.js";
+export { lintSource } from "./linter.js";

package/dist/index.native.js

@@ -0,0 +1,17 @@
+// React Native entry. Identical to index.js except primitives are sourced from
+// react-native instead of the DOM-backed implementation. Metro selects this
+// file via the `react-native` field in package.json.
+
+export { defineWidget } from "./define-widget.js";
+export { validateManifest, canonicalCategory } from "./manifest.js";
+export { validatePropertySchema, validateProps } from "./property-schema.js";
+export {
+  WidgetContextProvider,
+  useDatastoreQuery,
+  useDatastoreMutation,
+  useWidgetEvent,
+  useTheme,
+  useI18n,
+} from "./hooks.js";
+export { Text, View, Pressable, Image, ScrollView } from "./primitives.native.js";
+export { lintSource } from "./linter.js";

package/dist/linter.js

@@ -0,0 +1,68 @@
+// Static-analysis linter per docs/architecture/widget-marketplace.md §3.1.
+// 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.
+
+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*\(/,
+  },
+  {
+    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*\)/,
+  },
+];
+
+/**
+ * Lint a JavaScript source string.
+ * @param {string} source
+ * @returns {{ ok: boolean, findings: Array<{ rule: string, label: string, line: number, snippet: string }> }}
+ */
+export 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 };
+}

package/dist/manifest.js

@@ -0,0 +1,133 @@
+// 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.
+
+// REQ-MKT canonical category values are uppercase (matching the Prisma
+// `WidgetCategory` enum used to persist them server-side). We accept both
+// cases on input — lowercase is the form spelled out in design doc §2.2
+// and the TS types — and canonicalize internally via `canonicalCategory`.
+const VALID_CATEGORIES = new Set([
+  "input", "display", "layout", "data", "media", "communication", "custom",
+  "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "CUSTOM",
+]);
+const VALID_PLATFORMS = new Set(["web", "native"]);
+
+/**
+ * Normalize a manifest category to its canonical (uppercase) form.
+ * Returns `null` if the input is not a recognised category.
+ * @param {unknown} c
+ * @returns {string | null}
+ */
+export function canonicalCategory(c) {
+  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);
+}
+
+/**
+ * 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 };
+}

package/dist/primitives.js

@@ -0,0 +1,51 @@
+// 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);
+}

package/dist/primitives.native.js

@@ -0,0 +1,11 @@
+// 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.
+
+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;

package/dist/property-schema.js

@@ -0,0 +1,163 @@
+// Property schema validation per docs/architecture/widget-marketplace.md §2.2.
+// Drives the schema-driven Properties Panel and validates persisted page JSON.
+
+const VALID_TYPES = new Set([
+  "string", "number", "boolean",
+  "color", "icon", "image",
+  "select", "multiselect",
+  "tableRef", "columnRef", "recordBinding",
+  "expression", "eventBinding",
+  "object", "array",
+]);
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function validateDef(def, path, errors) {
+  if (!isPlainObject(def)) {
+    errors.push(`${path}: must be an object`);
+    return;
+  }
+  if (!VALID_TYPES.has(def.type)) {
+    errors.push(`${path}.type: invalid type "${def.type}"`);
+  }
+  if (typeof def.label !== "string" || def.label.length === 0) {
+    errors.push(`${path}.label: must be a non-empty string`);
+  }
+  if (def.description !== undefined && typeof def.description !== "string") {
+    errors.push(`${path}.description: must be a string when present`);
+  }
+  if (def.enum !== undefined) {
+    if (!Array.isArray(def.enum)) {
+      errors.push(`${path}.enum: must be an array`);
+    } else {
+      def.enum.forEach((entry, i) => {
+        if (!isPlainObject(entry) || typeof entry.label !== "string") {
+          errors.push(`${path}.enum[${i}]: must be { value, label }`);
+        }
+      });
+    }
+  }
+  if (def.type === "array") {
+    if (!isPlainObject(def.items)) {
+      errors.push(`${path}.items: array type requires nested items definition`);
+    } else {
+      validateDef(def.items, `${path}.items`, errors);
+    }
+  }
+  if (def.type === "object") {
+    if (!isPlainObject(def.properties)) {
+      errors.push(`${path}.properties: object type requires nested properties`);
+    } else {
+      for (const [k, child] of Object.entries(def.properties)) {
+        validateDef(child, `${path}.properties.${k}`, errors);
+      }
+    }
+  }
+}
+
+/**
+ * Validates a WidgetPropertySchema (top-level shape: Record<string, WidgetPropertyDef>).
+ * @param {unknown} schema
+ * @returns {{ ok: true } | { ok: false, errors: string[] }}
+ */
+export function validatePropertySchema(schema) {
+  const errors = [];
+  if (!isPlainObject(schema)) {
+    return { ok: false, errors: ["propertySchema must be an object"] };
+  }
+  for (const [k, def] of Object.entries(schema)) {
+    validateDef(def, `propertySchema.${k}`, errors);
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+function coerceLeaf(def, value, path, errors) {
+  const t = def.type;
+  if (value === undefined || value === null) {
+    if (def.required) errors.push(`${path}: required`);
+    return def.default !== undefined ? def.default : value;
+  }
+  switch (t) {
+    case "string":
+    case "color":
+    case "icon":
+    case "image":
+    case "tableRef":
+    case "columnRef":
+    case "recordBinding":
+    case "expression":
+    case "eventBinding":
+      if (typeof value !== "string") errors.push(`${path}: expected string`);
+      return value;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        errors.push(`${path}: expected number`);
+      } else {
+        if (def.validation?.min !== undefined && value < def.validation.min) {
+          errors.push(`${path}: must be >= ${def.validation.min}`);
+        }
+        if (def.validation?.max !== undefined && value > def.validation.max) {
+          errors.push(`${path}: must be <= ${def.validation.max}`);
+        }
+      }
+      return value;
+    case "boolean":
+      if (typeof value !== "boolean") errors.push(`${path}: expected boolean`);
+      return value;
+    case "select":
+      if (Array.isArray(def.enum) && !def.enum.some((e) => e.value === value)) {
+        errors.push(`${path}: value not in enum`);
+      }
+      return value;
+    case "multiselect":
+      if (!Array.isArray(value)) {
+        errors.push(`${path}: expected array`);
+      } else if (Array.isArray(def.enum)) {
+        const allowed = new Set(def.enum.map((e) => e.value));
+        value.forEach((v, i) => {
+          if (!allowed.has(v)) errors.push(`${path}[${i}]: value not in enum`);
+        });
+      }
+      return value;
+    case "array":
+      if (!Array.isArray(value)) {
+        errors.push(`${path}: expected array`);
+        return value;
+      }
+      return value.map((item, i) => coerceLeaf(def.items, item, `${path}[${i}]`, errors));
+    case "object": {
+      if (!isPlainObject(value)) {
+        errors.push(`${path}: expected object`);
+        return value;
+      }
+      const out = {};
+      for (const [k, child] of Object.entries(def.properties || {})) {
+        out[k] = coerceLeaf(child, value[k], `${path}.${k}`, errors);
+      }
+      return out;
+    }
+    default:
+      return value;
+  }
+}
+
+/**
+ * Validates `props` against a property schema. Applies defaults for missing leaves.
+ * @param {Record<string, any>} schema
+ * @param {unknown} props
+ * @returns {{ ok: true, value: Record<string, unknown> } | { ok: false, errors: string[] }}
+ */
+export function validateProps(schema, props) {
+  const errors = [];
+  if (!isPlainObject(schema)) {
+    return { ok: false, errors: ["schema must be an object"] };
+  }
+  const input = isPlainObject(props) ? props : {};
+  const out = {};
+  for (const [k, def] of Object.entries(schema)) {
+    out[k] = coerceLeaf(def, input[k], k, errors);
+  }
+  return errors.length === 0 ? { ok: true, value: out } : { ok: false, errors };
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@colixsystems/widget-sdk",
+  "version": "0.1.0",
+  "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "react-native": "./dist/index.native.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.native.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./linter": {
+      "import": "./dist/linter.js",
+      "default": "./dist/linter.js"
+    }
+  },
+  "bin": {
+    "appstudio-widget": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "node --test src"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colixwestin/appstudio.git",
+    "directory": "packages/widget-sdk"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "appstudio",
+    "widget",
+    "sdk",
+    "low-code"
+  ],
+  "license": "MIT"
+}