@colixsystems/widget-sdk 0.260.0 → 0.262.0

package/dist/hooks.js

@@ -3843,6 +3843,140 @@ export function useAgent(agentRef) {
   };
 }
 
+/**
+ * sc-13843 — structured error thrown by `useAction().run`. Carries a stable
+ * `code` so a widget branches without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "UNAVAILABLE"              — no Action is bound, or the host brokers no
+ *                                  actions client (render the unbound state)
+ *   - "INVALID_ACTION_INPUT"     — 400 (the input is not plain JSON within the
+ *                                  limits, or the Action's own check refused it)
+ *   - "ACTION_NOT_APP_INVOKABLE" — 403 (the workspace has not let the app run
+ *                                  this Action; retrying will not help)
+ *   - "ACTION_NOT_FOUND"         — 404 (the bound Action was deleted)
+ *   - "RATE_LIMITED"             — 429 (too many runs — retry shortly)
+ *   - "AUTH_REQUIRED"            — 401 (no signed-in app user)
+ *   - "TOKEN_EXPIRED" / "TOKEN_INVALID" — 401 (the app user's session ended)
+ *   - "ACTION_FAILED"            — the Action ran and failed, or no answer came
+ *
+ * The actions client owns these codes; any other server code passes through.
+ */
+export class ActionError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "ActionError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toActionError(err) {
+  if (err instanceof ActionError) return err;
+  const code = err && typeof err.code === "string" && err.code ? err.code : "ACTION_FAILED";
+  const message = (err && err.message) || "The action could not run";
+  return new ActionError(code, message, { cause: err });
+}
+
+/**
+ * sc-13843 — run one of the workspace's Actions and read what it returned.
+ * Returns `{ available, run, running, result, error }`.
+ *
+ *   run(input?) → Promise<result>   the Action's `respond()` value, or null
+ *
+ * IMPERATIVE — it never runs on mount or render; call `run` from an event
+ * handler. An Action can write data and send messages, so running it because
+ * a widget was placed would be a side effect nobody asked for.
+ *
+ * `actionRef` is the Action id an author bound through an `actionRef`
+ * property. When it is absent, or the host brokers no actions client,
+ * `available` is false and `run` rejects UNAVAILABLE rather than throwing at
+ * render — the widget must render a visible unbound state (CLAUDE.md §8).
+ *
+ * Routes through the injected `@colixsystems/actions-client` at `ctx.actions`,
+ * so the Player and the Expo export resolve against the identical client.
+ */
+export function useAction(actionRef) {
+  const ctx = useWidgetContextOrThrow("useAction");
+  const available =
+    Boolean(actionRef) &&
+    Boolean(ctx.actions) &&
+    typeof ctx.actions.run === "function";
+
+  const clientRef = useRef(null);
+  clientRef.current = available ? ctx.actions : null;
+  const actionIdRef = useRef(actionRef);
+  actionIdRef.current = actionRef;
+
+  // Bumped in render on a rebind, so an A→B→A rebind never resurfaces A's result.
+  const generationRef = useRef(0);
+  const boundRef = useRef(actionRef);
+  if (boundRef.current !== actionRef) {
+    boundRef.current = actionRef;
+    generationRef.current += 1;
+  }
+
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const latestRunRef = useRef(0);
+  // `pending` counts this binding's runs, so an old binding's run never shows.
+  const [outcome, setOutcome] = useState({ generation: 0, pending: 0, result: null, error: null });
+
+  const run = useCallback(async (input) => {
+    const client = clientRef.current;
+    const actionId = actionIdRef.current;
+    if (!client || !actionId) {
+      throw new ActionError("UNAVAILABLE", "No action is available for this host");
+    }
+    const generation = generationRef.current;
+    const runId = ++latestRunRef.current;
+    // Only the newest run on the shown binding may write its outcome.
+    const settle = (next) => {
+      if (!mountedRef.current) return;
+      const latest = runId === latestRunRef.current;
+      setOutcome((prior) => {
+        if (prior.generation !== generation) return prior;
+        const pending = Math.max(0, prior.pending - 1);
+        return latest ? { ...prior, ...next, pending } : { ...prior, pending };
+      });
+    };
+
+    setOutcome((prior) =>
+      prior.generation === generation
+        ? { ...prior, pending: prior.pending + 1, error: null }
+        : { generation, pending: 1, result: null, error: null },
+    );
+    try {
+      const response = await client.run(actionId, input);
+      if (!response || response.ok !== true) {
+        throw new ActionError("ACTION_FAILED", "The action did not complete");
+      }
+      const value = response.result === undefined ? null : response.result;
+      settle({ result: value, error: null });
+      return value;
+    } catch (err) {
+      const e = toActionError(err);
+      settle({ error: e });
+      throw e;
+    }
+  }, []);
+
+  const current = outcome.generation === generationRef.current;
+  return {
+    available,
+    run,
+    running: current && outcome.pending > 0,
+    result: current ? outcome.result : null,
+    error: current ? outcome.error : null,
+  };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/index.d.ts

@@ -885,6 +885,10 @@ export interface WidgetContext<TProps = unknown> {
   identification: IdentificationClient;
   /** sc-7991 — injected @colixsystems/agents-client backing useAgent(). */
   agents?: { conversations(agentId: string): unknown };
+  /** sc-13843 — injected @colixsystems/actions-client backing useAction(). */
+  actions?: {
+    run(actionId: string, input?: Record<string, unknown> | null): Promise<{ ok: boolean; result: unknown }>;
+  };
   /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
   linkPreviews?: { get(url: string): Promise<LinkPreview> };
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
@@ -1858,6 +1862,28 @@ export interface AgentApi {
  */
 export function useAgent(agentRef: string | null | undefined): AgentApi;
 
+export interface ActionApi {
+  /** False when no Action is bound, or the host brokers no actions client. */
+  available: boolean;
+  /**
+   * Imperative — call from an event handler, never on mount. Resolves with the
+   * value the Action passed to `respond()`, or null; rejects with ActionError.
+   */
+  run(input?: Record<string, unknown> | null): Promise<unknown>;
+  /** True while any run is in flight. */
+  running: boolean;
+  /** The last successful run's result; cleared when the binding changes. */
+  result: unknown;
+  error: ActionError | null;
+}
+
+/**
+ * sc-13843 — run one of the workspace's Actions and read its result. The
+ * Action must have the app trigger; the widget needs `actions.run:*` in
+ * `requestedScopes`. Never runs on mount.
+ */
+export function useAction(actionRef: string | null | undefined): ActionApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"
@@ -3140,6 +3166,27 @@ export class AgentError extends Error {
   constructor(code: string, message: string, opts?: { cause?: unknown });
 }
 
+/**
+ * sc-13843 — structured error thrown by `useAction().run`. Branch on `code`:
+ * `ACTION_NOT_APP_INVOKABLE` and `ACTION_NOT_FOUND` will not clear on a retry,
+ * `RATE_LIMITED` will. `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID`
+ * mean the app user must sign in. Never show an app user the raw message.
+ */
+export class ActionError extends Error {
+  code:
+    | "UNAVAILABLE"
+    | "INVALID_ACTION_INPUT"
+    | "ACTION_NOT_APP_INVOKABLE"
+    | "ACTION_NOT_FOUND"
+    | "RATE_LIMITED"
+    | "AUTH_REQUIRED"
+    | "TOKEN_EXPIRED"
+    | "TOKEN_INVALID"
+    | "ACTION_FAILED"
+    | (string & {});
+  constructor(code: string, message: string, opts?: { cause?: unknown });
+}
+
 /**
  * Error surfaced by `useLinkPreview().error`. A page that simply has no
  * preview is not an error. `retryAfter` (seconds) is set on RATE_LIMITED.

package/dist/index.js

@@ -29,6 +29,7 @@ export {
   DirectoryError,
   PermissionError,
   AgentError,
+  ActionError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -37,6 +38,7 @@ export {
   useCanWrite,
   useInterpretDraft,
   useAgent,
+  useAction,
   useAsset,
   useAssetsByTag,
   useBundledAsset,

package/dist/index.native.js

@@ -29,6 +29,7 @@ export {
   DirectoryError,
   PermissionError,
   AgentError,
+  ActionError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -37,6 +38,7 @@ export {
   useCanWrite,
   useInterpretDraft,
   useAgent,
+  useAction,
   useAsset,
   useAssetsByTag,
   useBundledAsset,

package/dist/linter.cjs

@@ -740,6 +740,17 @@ function _scopeRules(source, manifest) {
       });
     }
   }
+
+  // sc-13843 — DISCLOSURE, like ai.invoke: the server gate is the app-user JWT
+  // plus the Action's app trigger, never this scope.
+  if (/\buseAction\s*\(/.test(source) && !declared.has("actions.run:*")) {
+    findings.push({
+      rule: "scope-required-for-useAction",
+      label: "useAction() requires `actions.run:*` in manifest.requestedScopes",
+      line: 0,
+      snippet: "",
+    });
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/linter.js

@@ -695,6 +695,17 @@ function _scopeRules(source, manifest) {
       });
     }
   }
+
+  // sc-13843 — DISCLOSURE, like ai.invoke: the server gate is the app-user JWT
+  // plus the Action's app trigger, never this scope.
+  if (/\buseAction\s*\(/.test(source) && !declared.has("actions.run:*")) {
+    findings.push({
+      rule: "scope-required-for-useAction",
+      label: "useAction() requires `actions.run:*` in manifest.requestedScopes",
+      line: 0,
+      snippet: "",
+    });
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/list.js

@@ -1,7 +1,7 @@
 // `<List>`, `<ListRow>`, `<ListHeader>`, `<EmptyState>` (web). Binds
 // ./list-view.js to react-native-web; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { Card } from "./card.js";
 import { makeList } from "./list-view.js";
 

package/dist/loading.js

@@ -1,7 +1,7 @@
 // `<Spinner>` and `<Skeleton>` (web). Binds ./loading-view.js to
 // react-native-web; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeLoading } from "./loading-view.js";
 
 export const { Spinner, Skeleton } = makeLoading(ReactNative, { useNativeDriver: false });

package/dist/markdown-input.js

@@ -2,7 +2,7 @@
 // ./markdown-input-view.js to react-native-web's primitives, and to the web
 // `<RichText>` it renders its preview with.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.js";
 import { Modal } from "./modal.js";

package/dist/modal.js

@@ -1,7 +1,7 @@
 // `<Modal>` (web). Binds ./modal-view.js to react-native-web and the web
 // `<Overlay>`; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeModal } from "./modal-view.js";
 import { Overlay } from "./overlay.js";
 

package/dist/overlay.js

@@ -8,7 +8,7 @@
 // container at `position: fixed`, which is exactly what makes the overlay
 // escape the widget's clipping ancestors.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeOverlay } from "./overlay-view.js";
 import { WebModal } from "./web-modal.js";
 

package/dist/people-picker.js

@@ -1,7 +1,7 @@
 // `<PeoplePicker>` (web). Binds ./people-picker-view.js to the web `<Select>`
 // and `<Avatar>`; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makePeoplePicker } from "./people-picker-view.js";
 import { Select } from "./select.js";
 import { Avatar } from "./detail-parts.js";

package/dist/popover.js

@@ -2,7 +2,7 @@
 // ./menu-view.js and ./tooltip-view.js to react-native-web and the web
 // `<Overlay>`; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makePopover } from "./popover-view.js";
 import { makeMenu } from "./menu-view.js";
 import { makeTooltip } from "./tooltip-view.js";

package/dist/primitives.js

@@ -39,7 +39,7 @@
 // installed dep (no stub), and runtime property access sidesteps the
 // static re-export tracing. Behaviour is identical to the old
 // `react-native` alias path on the web.
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeTextInput } from "./text-input-view.js";
 
 export const Text = ReactNative.Text;

package/dist/property-schema.js

@@ -28,6 +28,9 @@ const VALID_TYPES = new Set([
   // and calls `useAgent(agentRef)`. Bare uuid string like `groupRef`/`pageRef`,
   // so tenant-copy remaps it through the layout walk's merged id map.
   "agentRef",
+  // sc-13843: `actionRef` picks one of the workspace's Actions, a bare
+  // Action UUID a widget passes to `useAction(actionRef)`. Remapped like agentRef.
+  "actionRef",
   // REQ-WDG-PAGEREF: `pageRef` is a page picker that emits a bare AppPage
   // UUID into the page JSON. Renders a page `<select>` in the Studio
   // Properties Panel; a widget reads it and navigates via
@@ -160,6 +163,7 @@ function coerceLeaf(def, value, path, errors) {
     case "pageRef":
     case "sectionRef":
     case "agentRef":
+    case "actionRef":
     case "richText":
     case "asset":
     case "folderRef":

package/dist/radio-group.js

@@ -1,7 +1,7 @@
 // `<RadioGroup>` (web). Binds ./radio-group-view.js to react-native-web; see
 // ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeRadioGroup } from "./radio-group-view.js";
 
 export const RadioGroup = makeRadioGroup({

package/dist/richtext.js

@@ -5,7 +5,7 @@
 // specifier for the rolldown optional-peer-dep reason spelled out at the top of
 // ./primitives.js.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeRichText } from "./richtext-view.js";
 
 export const RichText = makeRichText(ReactNative);

package/dist/search-field.js

@@ -1,7 +1,7 @@
 // `<SearchField>` (web). Binds ./search-field-view.js to react-native-web and
 // the web `<TextField>`; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeSearchField } from "./search-field-view.js";
 import { TextField } from "./text-field.js";
 

package/dist/select.js

@@ -2,7 +2,7 @@
 // `<Overlay>`, `<Button>`, `<Chip>`, `<SearchField>` and `<Spinner>`; see
 // ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeSelect } from "./select-view.js";
 import { Overlay } from "./overlay.js";
 import { Button } from "./button.js";

package/dist/sortable.js

@@ -1,7 +1,7 @@
 // `<SortableList>` and `<Board>` (web). Bind ./sortable-view.js to
 // react-native-web; see ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { List, ListRow } from "./list.js";
 import { Card } from "./card.js";
 import { Menu } from "./popover.js";

package/dist/switch.js

@@ -10,7 +10,7 @@
 //  - it forwards only a label to its `<input>`, dropping the other ARIA props.
 
 import React from "react";
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeSwitch } from "./switch-view.js";
 import { DISABLED_OPACITY } from "./form-control-tokens.js";
 import { shareRef } from "./form-control-logic.js";

package/dist/tabs.js

@@ -1,7 +1,7 @@
 // `<Tabs>` (web). Binds ./tabs-view.js to react-native-web; see
 // ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeTabs } from "./tabs-view.js";
 
 export const Tabs = makeTabs(ReactNative);

package/dist/text-field.js

@@ -1,7 +1,7 @@
 // `<TextField>` (web). Binds ./text-field-view.js to react-native-web; see
 // ./primitives.js for why not the bare specifier.
 
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 import { makeTextField } from "./text-field-view.js";
 import { TextInput } from "./primitives.js";
 

package/dist/text-scale-style.js

@@ -0,0 +1,60 @@
+// sc-12791: device font-scale arithmetic, React-free so node tests can load it.
+
+// Unstyled text renders at 14px in both React Native and react-native-web.
+export const DEFAULT_FONT_SIZE = 14;
+
+// `em` is relative to an already-scaled parent, so it is left alone.
+const ABSOLUTE_LENGTH = /\d(?:px|rem)$/;
+
+function flattenStyle(style, into = {}) {
+  if (Array.isArray(style)) {
+    for (const entry of style) flattenStyle(entry, into);
+  } else if (style && typeof style === "object") {
+    Object.assign(into, style);
+  }
+  return into;
+}
+
+function scaleLength(value, factor) {
+  if (typeof value === "number") return value * factor;
+  if (typeof value === "string" && ABSOLUTE_LENGTH.test(value.trim())) {
+    return `calc(${value.trim()} * ${factor})`;
+  }
+  return undefined;
+}
+
+/**
+ * The multiplier one text element gets under a preview scale, honouring the
+ * same per-element props React Native does.
+ *
+ * @param {number} scale The previewed device font scale.
+ * @param {{ allowFontScaling?: boolean, maxFontSizeMultiplier?: number }} props
+ * @returns {number}
+ */
+export function textScaleFactor(scale, props) {
+  if (!(scale > 1) || props?.allowFontScaling === false) return 1;
+  const cap = props?.maxFontSizeMultiplier;
+  return typeof cap === "number" && cap >= 1 ? Math.min(scale, cap) : scale;
+}
+
+/**
+ * `style` with its font size and line height multiplied by `factor`.
+ *
+ * @param {any} style A React Native style (object, array, or falsy).
+ * @param {number} factor
+ * @param {{ inheritsSize?: boolean }} [options] `inheritsSize` marks text
+ *   nested in already-scaled text: without its own size it inherits the
+ *   parent's, which must not be multiplied twice.
+ * @returns {any} The original style when nothing changes.
+ */
+export function scaleTextStyle(style, factor, { inheritsSize = false } = {}) {
+  if (factor === 1) return style;
+  const flat = flattenStyle(style);
+  const override = {};
+  const fontSize = flat.fontSize ?? (inheritsSize ? undefined : DEFAULT_FONT_SIZE);
+  const scaledFontSize = scaleLength(fontSize, factor);
+  if (scaledFontSize !== undefined) override.fontSize = scaledFontSize;
+  const scaledLineHeight = scaleLength(flat.lineHeight, factor);
+  if (scaledLineHeight !== undefined) override.lineHeight = scaledLineHeight;
+  return Object.keys(override).length > 0 ? [style, override] : style;
+}

package/dist/text-scale.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Previews a device font scale for every SDK `Text` / `TextInput` below it, as
+ * a phone's text-size setting would: font sizes and line heights grow, layout
+ * boxes do not. Web hosts only — native text already follows the device.
+ */
+export function TextScaleProvider(props: { scale?: number; children?: unknown }): unknown;
+
+/** react-native-web's `Text`, following the nearest `TextScaleProvider`. */
+export const Text: unknown;
+/** react-native-web's `TextInput`, following the nearest `TextScaleProvider`. */
+export const TextInput: unknown;

package/dist/text-scale.js

@@ -0,0 +1,40 @@
+// Web twin of ./bounded-text.native.js: previews a device text-size setting.
+// Every SDK web module takes react-native-web from here (text-scale.test.js).
+import React from "react";
+import * as ReactNativeWeb from "react-native-web";
+import { scaleTextStyle, textScaleFactor } from "./text-scale-style.js";
+
+const TextScaleContext = React.createContext(1);
+const ScaledTextAncestorContext = React.createContext(false);
+
+/**
+ * Previews a device font scale for every SDK Text / TextInput below it.
+ * Web hosts only: native text already follows the device setting.
+ *
+ * @param {{ scale?: number, children?: React.ReactNode }} props
+ */
+export function TextScaleProvider({ scale = 1, children }) {
+  const value = Number.isFinite(scale) && scale > 0 ? scale : 1;
+  return React.createElement(TextScaleContext.Provider, { value }, children);
+}
+
+function withTextScale(Base, { displayName, nests = false }) {
+  const Scaled = React.forwardRef(function ScaledText(props, ref) {
+    const scale = React.useContext(TextScaleContext);
+    const insideScaledText = React.useContext(ScaledTextAncestorContext);
+    if (scale === 1) return React.createElement(Base, { ...props, ref });
+    const factor = textScaleFactor(scale, props);
+    const style = scaleTextStyle(props.style, factor, { inheritsSize: insideScaledText });
+    const element = React.createElement(Base, { ...props, ref, style });
+    // Children inherit this size even when this element opted out of scaling.
+    if (!nests || insideScaledText) return element;
+    return React.createElement(ScaledTextAncestorContext.Provider, { value: true }, element);
+  });
+  Scaled.displayName = displayName;
+  return Scaled;
+}
+
+export const Text = withTextScale(ReactNativeWeb.Text, { displayName: "Text", nests: true });
+export const TextInput = withTextScale(ReactNativeWeb.TextInput, { displayName: "TextInput" });
+// Spread, not re-exported; see ./primitives.js for why.
+export const ReactNative = { ...ReactNativeWeb, Text, TextInput };

package/dist/video.js

@@ -9,7 +9,7 @@
 // thumbnail; Safari draws nothing before playback without the fragment.
 
 import React from "react";
-import * as ReactNative from "react-native-web";
+import { ReactNative } from "./text-scale.js";
 
 const FIRST_FRAME = "#t=0.001";
 const FITS = { contain: "contain", cover: "cover" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.260.0",
+  "version": "0.262.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -29,6 +29,11 @@
       "import": "./dist/host.js",
       "default": "./dist/host.js"
     },
+    "./text-scale": {
+      "types": "./dist/text-scale.d.ts",
+      "import": "./dist/text-scale.js",
+      "default": "./dist/text-scale.js"
+    },
     "./contract": {
       "types": "./dist/index.d.ts",
       "require": "./dist/contract.cjs",