@teacharium/widget 0.2.1 → 0.3.0

package/dist/components/AudioPlayer.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+interface AudioPlayerProps {
+    audioUrl: string;
+    className?: string;
+    size?: "sm" | "md" | "lg";
+    onPlay?: () => void;
+    onPause?: () => void;
+    onError?: (error: string) => void;
+}
+export declare const AudioPlayer: React.FC<AudioPlayerProps>;
+export {};

package/dist/main.d.ts

@@ -2,4 +2,7 @@ export * from './teacharium-widget';
 export * from './teacharium-widget-api';
 export * from './teacharium-custom-fields';
 export * from './standard-layout-options';
+export { AudioPlayer } from './components/AudioPlayer';
+export * from './utils/voiceover';
+export * from './utils/actions';
 export declare const hi = "world";

package/dist/teacharium-custom-fields.d.ts

@@ -1,34 +1,66 @@
 import { BaseField } from '@measured/puck';
-export interface ImageMediaField extends BaseField {
+export type TeachariumCustomFieldType = "imageMedia" | "videoMedia" | "audioMedia" | "voiceover" | "action" | "variable" | "numericExpression" | "stringExpression" | "placeholder" | "step" | "condition" | "textStyle" | "frame";
+export type TeachariumCustomField = BaseField & {
+    type: TeachariumCustomFieldType;
+    label?: string;
+    placeholder?: string;
+    description?: string;
+    value?: string;
+};
+export type ImageMediaField = TeachariumCustomField & {
     type: "imageMedia";
     label: string;
-}
-export interface VideoMediaField extends BaseField {
+};
+export type VideoMediaField = TeachariumCustomField & {
     type: "videoMedia";
     label: string;
-}
-export interface AudioMediaField extends BaseField {
+};
+export type AudioMediaField = TeachariumCustomField & {
     type: "audioMedia";
     label: string;
-}
-export interface ActionField extends BaseField {
+};
+export type VoiceoverField = TeachariumCustomField & {
+    type: "voiceover";
+    label?: string;
+};
+export type ActionField = TeachariumCustomField & {
     type: "action";
     label: string;
-}
-export interface VariableField extends BaseField {
+};
+export type VariableField = TeachariumCustomField & {
     type: "variable";
     label: string;
-}
-export interface NumericExpressionField extends BaseField {
+};
+export type NumericExpressionField = TeachariumCustomField & {
     type: "numericExpression";
     label: string;
-}
-export interface StringExpressionField extends BaseField {
+};
+export type StringExpressionField = TeachariumCustomField & {
     type: "stringExpression";
     label: string;
-}
-export interface ConditionField extends BaseField {
+};
+export type ConditionField = TeachariumCustomField & {
     type: "condition";
     label: string;
-}
-export type TeachariumCustomFields = ImageMediaField | VideoMediaField | AudioMediaField | ActionField | VariableField | NumericExpressionField | StringExpressionField | ConditionField;
+};
+export type PlaceholderField = TeachariumCustomField & {
+    type: "placeholder";
+    label?: string;
+    description?: string;
+    value?: string;
+};
+export type StepField = TeachariumCustomField & {
+    type: "step";
+    label: string;
+    placeholder?: string;
+    description?: string;
+};
+export type TextStyleField = TeachariumCustomField & {
+    type: "textStyle";
+    label?: string;
+};
+export type FrameField = TeachariumCustomField & {
+    type: "frame";
+    label?: string;
+};
+export type TeachariumCustomFields = TeachariumCustomField;

package/dist/teacharium-widget-api.d.ts

@@ -1,4 +1,14 @@
 import { default as React } from 'react';
+export type VoiceType = "alloy" | "ash" | "ballad" | "coral" | "echo" | "fable" | "onyx" | "nova" | "sage" | "shimmer" | "verse";
+export interface VoiceoverData {
+    enabled: boolean;
+    voice: VoiceType;
+    speed?: number;
+    showPlayButton: boolean;
+    cached?: boolean;
+    content?: string;
+    contentHash?: string;
+}
 export declare const EVENT_SOURCE_PLAYER = "player";
 export declare const EVENT_SOURCE_FOOTER = "footer";
 type EventListener<T = any> = (event: T) => void;
@@ -8,21 +18,17 @@ export interface BaseEvent {
     emittedBy?: string;
 }
 export type VariableValue = string | number | boolean;
-export interface UseNumberExpression {
-    (expression: string, defaultValue: number): number;
-    (expression: string): number | null;
-}
-export interface UseStringExpression {
-    (expression: string, defaultValue?: string): string;
+export interface UseNumberExpressions {
+    (expressions: string[], defaultValues?: number[]): (number)[];
 }
-export interface UseVariableValue {
-    (name: string): VariableValue | undefined;
+export interface UseStringExpressions {
+    (expressions: (string | undefined)[], defaultValues?: string[]): string[];
 }
 export interface UseVariableValues {
-    (names: string[]): (VariableValue | undefined)[];
+    (names: Array<string | null | undefined>): (VariableValue | undefined)[];
 }
-export interface UseUpdateVariable {
-    (newValue: VariableValue): void;
+export interface UseUpdateVariables {
+    (values: Record<string, VariableValue>): void;
 }
 export interface UseMediaUrl {
     (src: string, expiresIn?: number): {
@@ -33,6 +39,20 @@ export interface UseMediaUrl {
         isLoadingError: boolean;
     };
 }
+export interface UseVoiceoverUrl {
+    (contentHash?: string | null, voice?: VoiceType | null, options?: {
+        enabled?: boolean;
+        model?: string | null;
+    }): {
+        data: string | undefined;
+        error: Error | null;
+        isError: boolean;
+        isLoading: boolean;
+        isLoadingError: boolean;
+        refetch: () => Promise<any>;
+        voiceoverId: string | undefined;
+    };
+}
 export interface ConditionValue {
     leftOperand: string;
     operator: string;
@@ -46,25 +66,67 @@ export interface UseConditionEvaluationResult {
 export interface UseConditionEvaluation {
     (condition: ConditionValue): UseConditionEvaluationResult;
 }
-export interface ItemOptions {
-    correctVariableName: string;
-    feedbackVariableName?: string;
-    attemptedVariableName?: string;
+export type ItemType = "instructional" | "practice" | "scored";
+export interface CurrentAnswer {
+    humanReadable: string;
+    machineReadable: string | number;
 }
-export interface UseIsItem {
-    (widgetId: string, options: ItemOptions): void;
+export interface ItemStatus {
+    correct: boolean;
+    attempted: boolean;
+    currentAnswer?: CurrentAnswer;
+    maxScore: number;
+    currentScore: number;
 }
 export interface ItemData {
     widgetId: string;
-    correctVariableName: string;
-    feedbackVariableName?: string;
-    attemptedVariableName?: string;
+    widgetName?: string;
+    stepId: string;
+    type: ItemType;
+    status: ItemStatus;
+}
+export interface ItemUpdateApi {
+    updateCorrect: (correct: boolean) => void;
+    updateAttempted: (attempted: boolean) => void;
+    updateAnswer: (answer: CurrentAnswer | undefined) => void;
+    updateStatus: (updates: Partial<ItemStatus>) => void;
+    updateScore: (currentScore: number, maxScore?: number) => void;
+    updateMaxScore: (maxScore: number) => void;
+}
+export interface UseIsItemOptions {
+    stepId: string;
+    type?: ItemType;
+    maxScore?: number;
+    widgetName?: string;
+}
+/**
+ * Hook for widgets to register as items and get the update API.
+ * When used via api.hooks.useIsItem (curried version), widgets can optionally pass configuration.
+ */
+export interface UseIsItem {
+    (options?: {
+        widgetId?: string;
+        options?: Omit<UseIsItemOptions, "stepId">;
+    }): ItemUpdateApi;
+}
+/**
+ * Hook for registering sub-items with custom IDs (e.g., rows in a matrix).
+ * Requires passing a custom widget ID and optional type.
+ */
+export interface UseIsItemWithId {
+    (customWidgetId: string, options?: {
+        type?: ItemType;
+        maxScore?: number;
+        widgetName?: string;
+    }): ItemUpdateApi;
 }
 export interface ItemsContextValue {
     items: Map<string, ItemData>;
-    registerItem: (widgetId: string, options: ItemOptions) => void;
+    registerItem: (widgetId: string, stepId: string, type?: ItemType, maxScore?: number, widgetName?: string) => void;
     unregisterItem: (widgetId: string) => void;
     getItems: () => ItemData[];
+    getItemsByStepId: (stepId: string) => ItemData[];
+    getItemUpdateApi: (widgetId: string) => ItemUpdateApi;
 }
 export interface UseItemsContext {
     (): ItemsContextValue;
@@ -78,6 +140,7 @@ export interface UseLessonEventSubscription {
 export interface TeachariumWidgetApi {
     isEditing: boolean;
     playerMode: "editing" | "preview" | "playbook";
+    stepId: string | undefined;
     events: {
         /**
          * Emit an event with type and params
@@ -88,28 +151,50 @@ export interface TeachariumWidgetApi {
         unsubscribe(eventType: string, listener: EventListener): void;
     };
     React: any;
+    updateVariables: (values: Record<string, VariableValue>) => void;
     hooks: {
-        useNumberExpression: UseNumberExpression;
-        useStringExpression: UseStringExpression;
-        useVariableValue: UseVariableValue;
+        useNumberExpressions: UseNumberExpressions;
+        useStringExpressions: UseStringExpressions;
         useVariableValues: UseVariableValues;
-        useUpdateVariable: (variableName: string) => UseUpdateVariable;
         useMediaUrl: UseMediaUrl;
+        useVoiceoverUrl: UseVoiceoverUrl;
         useConditionEvaluation: UseConditionEvaluation;
         useIsItem: UseIsItem;
+        useIsItemWithId: UseIsItemWithId;
         useItemsContext: UseItemsContext;
         useLessonEventEmitter: UseLessonEventEmitter;
         useLessonEventSubscription: UseLessonEventSubscription;
     };
     /**
-     * Create a transient variable that exists only during runtime
-     * Automatically prefixes the variable name with the widget ID
+     * Create a variable that can be either transient (runtime only) or persistent (lesson-wide)
+     * By default, creates a transient variable automatically prefixed with the widget ID
      * Example: addVariable('selectedAnswer', 0) might create 'mcwidget1_selectedAnswer'
-     * @param name - Base name for the variable (will be prefixed with widget ID)
+     *
+     * For lesson-wide variables, pass { scope: "lesson", skipPrefix: true }
+     * Example: addVariable('TotalTime', 0, "number", { scope: "lesson", skipPrefix: true })
+     *
+     * @param name - Base name for the variable (will be prefixed with widget ID unless skipPrefix is true)
      * @param initialValue - Initial value for the variable
      * @param type - Optional type specification (auto-inferred if not provided)
+     * @param options - Optional configuration for the variable
      * @returns The full variable name that was created
      */
-    addVariable: (name: string, initialValue: VariableValue, type?: "string" | "number" | "boolean") => string;
+    addVariable: (name: string, initialValue: VariableValue, type?: "string" | "number" | "boolean", options?: {
+        scope?: "lesson" | "step";
+        skipPrefix?: boolean;
+        description?: string;
+    }) => string;
+    /**
+     * Increment a numeric variable by a specified amount
+     * @param name - Variable name to increment
+     * @param amount - Amount to increment by (default: 1)
+     */
+    incrementVariable: (name: string, amount?: number) => void;
+    /**
+     * Decrement a numeric variable by a specified amount
+     * @param name - Variable name to decrement
+     * @param amount - Amount to decrement by (default: 1)
+     */
+    decrementVariable: (name: string, amount?: number) => void;
 }
 export {};

package/dist/teacharium-widget.d.ts

@@ -1,3 +1,4 @@
+import { default as React } from 'react';
 import { DefaultComponentProps, Fields, PuckComponent } from '@measured/puck';
 import { TeachariumWidgetApi } from './teacharium-widget-api';
 import { TeachariumCustomFields } from './teacharium-custom-fields';
@@ -5,13 +6,26 @@ interface TeachariumComponentProps {
     api: TeachariumWidgetApi;
 }
 export interface TeachariumComponentConfig<T = {}> {
+    usagePrompt: string;
     fields: Fields<DefaultComponentProps, TeachariumCustomFields>;
     defaultProps: DefaultComponentProps;
+    resolveData?: (arg: {
+        props: any;
+        changed: any;
+    }) => Promise<any>;
+    resolveFields?: (data: unknown, context: {
+        fields: Fields<DefaultComponentProps, TeachariumCustomFields>;
+    }) => Fields<DefaultComponentProps, TeachariumCustomFields>;
     render: PuckComponent<T & TeachariumComponentProps>;
 }
 export interface TeachariumWidget<T> {
     name: string;
     category: string;
+    description?: string;
+    aiPrompt?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }> | string;
     config: TeachariumComponentConfig<T>;
 }
 export declare const registerWidget: (widget: TeachariumWidget<any>) => void;

package/dist/teacharium-widget.es.js

@@ -1,8 +1,10 @@
-import re from "react";
-const ce = (n) => {
+import * as x from "react";
+import oe from "react";
+import { VolumeX as Q, Loader2 as ae, Pause as se, Play as ce, Volume2 as ie } from "lucide-react";
+const be = (n) => {
   window.TeachariumComponents = window.TeachariumComponents || {}, window.TeachariumComponents[n.name] = n;
-}, le = () => Object.values(window.TeachariumComponents || {}), ie = "player", fe = "footer";
-var p = { exports: {} }, _ = {};
+}, Re = () => Object.values(window.TeachariumComponents || {}), Te = "player", ye = "footer";
+var M = { exports: {} }, k = {};
 /**
  * @license React
  * react-jsx-runtime.production.js
@@ -12,29 +14,29 @@ var p = { exports: {} }, _ = {};
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-var I;
-function te() {
-  if (I) return _;
-  I = 1;
-  var n = Symbol.for("react.transitional.element"), i = Symbol.for("react.fragment");
-  function s(m, u, c) {
-    var E = null;
-    if (c !== void 0 && (E = "" + c), u.key !== void 0 && (E = "" + u.key), "key" in u) {
-      c = {};
-      for (var R in u)
-        R !== "key" && (c[R] = u[R]);
-    } else c = u;
-    return u = c.ref, {
+var K;
+function le() {
+  if (K) return k;
+  K = 1;
+  var n = Symbol.for("react.transitional.element"), o = Symbol.for("react.fragment");
+  function t(m, i, l) {
+    var s = null;
+    if (l !== void 0 && (s = "" + l), i.key !== void 0 && (s = "" + i.key), "key" in i) {
+      l = {};
+      for (var E in i)
+        E !== "key" && (l[E] = i[E]);
+    } else l = i;
+    return i = l.ref, {
       $$typeof: n,
       type: m,
-      key: E,
-      ref: u !== void 0 ? u : null,
-      props: c
+      key: s,
+      ref: i !== void 0 ? i : null,
+      props: l
     };
   }
-  return _.Fragment = i, _.jsx = s, _.jsxs = s, _;
+  return k.Fragment = o, k.jsx = t, k.jsxs = t, k;
 }
-var b = {};
+var O = {};
 /**
  * @license React
  * react-jsx-runtime.development.js
@@ -44,44 +46,44 @@ var b = {};
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-var L;
-function ne() {
-  return L || (L = 1, process.env.NODE_ENV !== "production" && (function() {
+var ee;
+function ue() {
+  return ee || (ee = 1, process.env.NODE_ENV !== "production" && (function() {
     function n(e) {
       if (e == null) return null;
       if (typeof e == "function")
-        return e.$$typeof === Q ? null : e.displayName || e.name || null;
+        return e.$$typeof === I ? null : e.displayName || e.name || null;
       if (typeof e == "string") return e;
       switch (e) {
-        case v:
+        case y:
           return "Fragment";
-        case q:
+        case W:
           return "Profiler";
-        case V:
+        case R:
           return "StrictMode";
-        case X:
+        case _:
           return "Suspense";
-        case B:
+        case N:
           return "SuspenseList";
-        case Z:
+        case Y:
           return "Activity";
       }
       if (typeof e == "object")
         switch (typeof e.tag == "number" && console.error(
           "Received an unexpected object in getComponentNameFromType(). This is likely a bug in React. Please file an issue."
         ), e.$$typeof) {
-          case U:
+          case $:
             return "Portal";
-          case z:
+          case S:
             return (e.displayName || "Context") + ".Provider";
-          case J:
+          case D:
             return (e._context.displayName || "Context") + ".Consumer";
-          case G:
+          case c:
             var r = e.render;
             return e = e.displayName, e || (e = r.displayName || r.name || "", e = e !== "" ? "ForwardRef(" + e + ")" : "ForwardRef"), e;
-          case H:
+          case L:
             return r = e.displayName || null, r !== null ? r : n(e.type) || "Memo";
-          case y:
+          case j:
             r = e._payload, e = e._init;
             try {
               return n(e(r));
@@ -90,29 +92,29 @@ function ne() {
         }
       return null;
     }
-    function i(e) {
+    function o(e) {
       return "" + e;
     }
-    function s(e) {
+    function t(e) {
       try {
-        i(e);
+        o(e);
         var r = !1;
       } catch {
         r = !0;
       }
       if (r) {
         r = console;
-        var t = r.error, o = typeof Symbol == "function" && Symbol.toStringTag && e[Symbol.toStringTag] || e.constructor.name || "Object";
-        return t.call(
+        var a = r.error, u = typeof Symbol == "function" && Symbol.toStringTag && e[Symbol.toStringTag] || e.constructor.name || "Object";
+        return a.call(
           r,
           "The provided key is an unsupported type %s. This value must be coerced to a string before using it here.",
-          o
-        ), i(e);
+          u
+        ), o(e);
       }
     }
     function m(e) {
-      if (e === v) return "<>";
-      if (typeof e == "object" && e !== null && e.$$typeof === y)
+      if (e === y) return "<>";
+      if (typeof e == "object" && e !== null && e.$$typeof === j)
         return "<...>";
       try {
         var r = n(e);
@@ -121,48 +123,48 @@ function ne() {
         return "<...>";
       }
     }
-    function u() {
-      var e = O.A;
+    function i() {
+      var e = h.A;
       return e === null ? null : e.getOwner();
     }
-    function c() {
+    function l() {
       return Error("react-stack-top-frame");
     }
-    function E(e) {
-      if (g.call(e, "key")) {
+    function s(e) {
+      if (G.call(e, "key")) {
         var r = Object.getOwnPropertyDescriptor(e, "key").get;
         if (r && r.isReactWarning) return !1;
       }
       return e.key !== void 0;
     }
-    function R(e, r) {
-      function t() {
-        N || (N = !0, console.error(
+    function E(e, r) {
+      function a() {
+        H || (H = !0, console.error(
           "%s: `key` is not a prop. Trying to access it will result in `undefined` being returned. If you need to access the same value within the child component, you should pass it as a different prop. (https://react.dev/link/special-props)",
           r
         ));
       }
-      t.isReactWarning = !0, Object.defineProperty(e, "key", {
-        get: t,
+      a.isReactWarning = !0, Object.defineProperty(e, "key", {
+        get: a,
         configurable: !0
       });
     }
-    function W() {
+    function w() {
       var e = n(this.type);
-      return C[e] || (C[e] = !0, console.error(
+      return z[e] || (z[e] = !0, console.error(
         "Accessing element.ref was removed in React 19. ref is now a regular prop. It will be removed from the JSX Element type in a future release."
       )), e = this.props.ref, e !== void 0 ? e : null;
     }
-    function M(e, r, t, o, f, l, w, S) {
-      return t = l.ref, e = {
-        $$typeof: h,
+    function A(e, r, a, u, T, p, V, J) {
+      return a = p.ref, e = {
+        $$typeof: C,
         type: e,
         key: r,
-        props: l,
-        _owner: f
-      }, (t !== void 0 ? t : null) !== null ? Object.defineProperty(e, "ref", {
+        props: p,
+        _owner: T
+      }, (a !== void 0 ? a : null) !== null ? Object.defineProperty(e, "ref", {
         enumerable: !1,
-        get: W
+        get: w
       }) : Object.defineProperty(e, "ref", { enumerable: !1, value: null }), e._store = {}, Object.defineProperty(e._store, "validated", {
         configurable: !1,
         enumerable: !1,
@@ -177,112 +179,112 @@ function ne() {
         configurable: !1,
         enumerable: !1,
         writable: !0,
-        value: w
+        value: V
       }), Object.defineProperty(e, "_debugTask", {
         configurable: !1,
         enumerable: !1,
         writable: !0,
-        value: S
+        value: J
       }), Object.freeze && (Object.freeze(e.props), Object.freeze(e)), e;
     }
-    function j(e, r, t, o, f, l, w, S) {
-      var a = r.children;
-      if (a !== void 0)
-        if (o)
-          if (K(a)) {
-            for (o = 0; o < a.length; o++)
-              P(a[o]);
-            Object.freeze && Object.freeze(a);
+    function v(e, r, a, u, T, p, V, J) {
+      var d = r.children;
+      if (d !== void 0)
+        if (u)
+          if (te(d)) {
+            for (u = 0; u < d.length; u++)
+              P(d[u]);
+            Object.freeze && Object.freeze(d);
           } else
             console.error(
               "React.jsx: Static children should always be an array. You are likely explicitly calling React.jsxs or React.jsxDEV. Use the Babel transform instead."
             );
-        else P(a);
-      if (g.call(r, "key")) {
-        a = n(e);
-        var d = Object.keys(r).filter(function(ee) {
-          return ee !== "key";
+        else P(d);
+      if (G.call(r, "key")) {
+        d = n(e);
+        var g = Object.keys(r).filter(function(ne) {
+          return ne !== "key";
         });
-        o = 0 < d.length ? "{key: someKey, " + d.join(": ..., ") + ": ...}" : "{key: someKey}", F[a + o] || (d = 0 < d.length ? "{" + d.join(": ..., ") + ": ...}" : "{}", console.error(
+        u = 0 < g.length ? "{key: someKey, " + g.join(": ..., ") + ": ...}" : "{key: someKey}", Z[d + u] || (g = 0 < g.length ? "{" + g.join(": ..., ") + ": ...}" : "{}", console.error(
           `A props object containing a "key" prop is being spread into JSX:
   let props = %s;
   <%s {...props} />
 React keys must be passed directly to JSX without using spread:
   let props = %s;
   <%s key={someKey} {...props} />`,
-          o,
-          a,
+          u,
           d,
-          a
-        ), F[a + o] = !0);
+          g,
+          d
+        ), Z[d + u] = !0);
       }
-      if (a = null, t !== void 0 && (s(t), a = "" + t), E(r) && (s(r.key), a = "" + r.key), "key" in r) {
-        t = {};
-        for (var A in r)
-          A !== "key" && (t[A] = r[A]);
-      } else t = r;
-      return a && R(
-        t,
+      if (d = null, a !== void 0 && (t(a), d = "" + a), s(r) && (t(r.key), d = "" + r.key), "key" in r) {
+        a = {};
+        for (var q in r)
+          q !== "key" && (a[q] = r[q]);
+      } else a = r;
+      return d && E(
+        a,
         typeof e == "function" ? e.displayName || e.name || "Unknown" : e
-      ), M(
+      ), A(
         e,
+        d,
+        p,
+        T,
+        i(),
         a,
-        l,
-        f,
-        u(),
-        t,
-        w,
-        S
+        V,
+        J
       );
     }
     function P(e) {
-      typeof e == "object" && e !== null && e.$$typeof === h && e._store && (e._store.validated = 1);
+      typeof e == "object" && e !== null && e.$$typeof === C && e._store && (e._store.validated = 1);
     }
-    var T = re, h = Symbol.for("react.transitional.element"), U = Symbol.for("react.portal"), v = Symbol.for("react.fragment"), V = Symbol.for("react.strict_mode"), q = Symbol.for("react.profiler"), J = Symbol.for("react.consumer"), z = Symbol.for("react.context"), G = Symbol.for("react.forward_ref"), X = Symbol.for("react.suspense"), B = Symbol.for("react.suspense_list"), H = Symbol.for("react.memo"), y = Symbol.for("react.lazy"), Z = Symbol.for("react.activity"), Q = Symbol.for("react.client.reference"), O = T.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, g = Object.prototype.hasOwnProperty, K = Array.isArray, k = console.createTask ? console.createTask : function() {
+    var b = oe, C = Symbol.for("react.transitional.element"), $ = Symbol.for("react.portal"), y = Symbol.for("react.fragment"), R = Symbol.for("react.strict_mode"), W = Symbol.for("react.profiler"), D = Symbol.for("react.consumer"), S = Symbol.for("react.context"), c = Symbol.for("react.forward_ref"), _ = Symbol.for("react.suspense"), N = Symbol.for("react.suspense_list"), L = Symbol.for("react.memo"), j = Symbol.for("react.lazy"), Y = Symbol.for("react.activity"), I = Symbol.for("react.client.reference"), h = b.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, G = Object.prototype.hasOwnProperty, te = Array.isArray, U = console.createTask ? console.createTask : function() {
       return null;
     };
-    T = {
+    b = {
       react_stack_bottom_frame: function(e) {
         return e();
       }
     };
-    var N, C = {}, Y = T.react_stack_bottom_frame.bind(
-      T,
-      c
-    )(), $ = k(m(c)), F = {};
-    b.Fragment = v, b.jsx = function(e, r, t, o, f) {
-      var l = 1e4 > O.recentlyCreatedOwnerStacks++;
-      return j(
+    var H, z = {}, X = b.react_stack_bottom_frame.bind(
+      b,
+      l
+    )(), B = U(m(l)), Z = {};
+    O.Fragment = y, O.jsx = function(e, r, a, u, T) {
+      var p = 1e4 > h.recentlyCreatedOwnerStacks++;
+      return v(
         e,
         r,
-        t,
+        a,
         !1,
-        o,
-        f,
-        l ? Error("react-stack-top-frame") : Y,
-        l ? k(m(e)) : $
+        u,
+        T,
+        p ? Error("react-stack-top-frame") : X,
+        p ? U(m(e)) : B
       );
-    }, b.jsxs = function(e, r, t, o, f) {
-      var l = 1e4 > O.recentlyCreatedOwnerStacks++;
-      return j(
+    }, O.jsxs = function(e, r, a, u, T) {
+      var p = 1e4 > h.recentlyCreatedOwnerStacks++;
+      return v(
         e,
         r,
-        t,
+        a,
         !0,
-        o,
-        f,
-        l ? Error("react-stack-top-frame") : Y,
-        l ? k(m(e)) : $
+        u,
+        T,
+        p ? Error("react-stack-top-frame") : X,
+        p ? U(m(e)) : B
       );
     };
-  })()), b;
+  })()), O;
 }
-var D;
-function oe() {
-  return D || (D = 1, process.env.NODE_ENV === "production" ? p.exports = te() : p.exports = ne()), p.exports;
+var re;
+function de() {
+  return re || (re = 1, process.env.NODE_ENV === "production" ? M.exports = le() : M.exports = ue()), M.exports;
 }
-var x = oe();
-const ae = {
+var f = de();
+const fe = {
   margin: {
     type: "number",
     label: "Margin",
@@ -298,26 +300,157 @@ const ae = {
   //       { label: "Partial", value: "partial" },
   //     ],
   //   },
-}, se = ({ margin: n, children: i }) => {
-  const s = {};
-  return n && (s.padding = `${n}px`), /* @__PURE__ */ x.jsx("div", { style: s, children: i });
-}, de = (n) => {
-  const i = n.render;
+}, me = ({ margin: n, children: o }) => {
+  const t = {};
+  return n && (t.padding = `${n}px`), /* @__PURE__ */ f.jsx("div", { style: t, children: o });
+}, _e = (n) => {
+  const o = n.render;
   return {
     ...n,
-    render: (s) => /* @__PURE__ */ x.jsx(se, { ...s, children: /* @__PURE__ */ x.jsx(i, { ...s }) }),
+    render: (t) => /* @__PURE__ */ f.jsx(me, { ...t, children: /* @__PURE__ */ f.jsx(o, { ...t }) }),
     fields: {
       ...n.fields,
-      ...ae
+      ...fe
     }
   };
-}, me = "world";
+}, F = (...n) => n.filter(Boolean).join(" "), he = ({
+  audioUrl: n,
+  className: o,
+  size: t = "sm",
+  onPlay: m,
+  onPause: i,
+  onError: l
+}) => {
+  const s = x.useRef(null), [E, w] = x.useState(!1), [A, v] = x.useState(!1), [P, b] = x.useState(null), [C, $] = x.useState(!1), y = {
+    sm: "h-6 w-6",
+    md: "h-8 w-8",
+    lg: "h-10 w-10"
+  }, R = {
+    sm: 12,
+    md: 16,
+    lg: 20
+  }, W = async () => {
+    if (s.current)
+      try {
+        v(!0), b(null), E ? s.current.pause() : await s.current.play();
+      } catch (c) {
+        const _ = c instanceof Error ? c.message : "Failed to play audio";
+        b(_), l?.(_);
+      } finally {
+        v(!1);
+      }
+  }, D = () => {
+    s.current && (s.current.muted = !s.current.muted, $(s.current.muted));
+  };
+  x.useEffect(() => {
+    const c = s.current;
+    if (!c) return;
+    const _ = () => {
+      w(!0), m?.();
+    }, N = () => {
+      w(!1), i?.();
+    }, L = () => {
+      w(!1), i?.();
+    }, j = () => {
+      v(!0);
+    }, Y = () => {
+      v(!1);
+    }, I = () => {
+      const h = "Failed to load audio";
+      b(h), v(!1), l?.(h);
+    };
+    return c.addEventListener("play", _), c.addEventListener("pause", N), c.addEventListener("ended", L), c.addEventListener("loadstart", j), c.addEventListener("canplay", Y), c.addEventListener("error", I), () => {
+      c.removeEventListener("play", _), c.removeEventListener("pause", N), c.removeEventListener("ended", L), c.removeEventListener("loadstart", j), c.removeEventListener("canplay", Y), c.removeEventListener("error", I);
+    };
+  }, [m, i, l]);
+  const S = "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 ring-offset-background bg-transparent hover:bg-gray-100";
+  return P ? /* @__PURE__ */ f.jsx(
+    "button",
+    {
+      type: "button",
+      className: F(
+        S,
+        y[t],
+        "text-red-500",
+        o
+      ),
+      disabled: !0,
+      children: /* @__PURE__ */ f.jsx(Q, { size: R[t] })
+    }
+  ) : /* @__PURE__ */ f.jsxs("div", { className: F("flex items-center gap-1", o), children: [
+    /* @__PURE__ */ f.jsx("audio", { ref: s, src: n, preload: "metadata" }),
+    /* @__PURE__ */ f.jsx(
+      "button",
+      {
+        type: "button",
+        className: F(S, y[t]),
+        onClick: W,
+        disabled: A,
+        children: A ? /* @__PURE__ */ f.jsx(ae, { size: R[t], className: "animate-spin" }) : E ? /* @__PURE__ */ f.jsx(se, { size: R[t] }) : /* @__PURE__ */ f.jsx(ce, { size: R[t] })
+      }
+    ),
+    t !== "sm" && /* @__PURE__ */ f.jsx(
+      "button",
+      {
+        type: "button",
+        className: F(S, y[t]),
+        onClick: D,
+        children: C ? /* @__PURE__ */ f.jsx(Q, { size: R[t] }) : /* @__PURE__ */ f.jsx(ie, { size: R[t] })
+      }
+    )
+  ] });
+}, Ee = "SHA-256";
+async function ge(n) {
+  const o = globalThis.crypto?.subtle;
+  if (!o)
+    throw new Error("Web Crypto is not available to compute voiceover hashes");
+  const m = new TextEncoder().encode(n), i = await o.digest(Ee, m), l = new Uint8Array(i);
+  let s = "";
+  for (let E = 0; E < l.length; E += 1)
+    s += l[E].toString(16).padStart(2, "0");
+  return s;
+}
+function xe(n, o) {
+  !o || o.length === 0 || o.forEach((t) => {
+    if (!t.actionType) {
+      console.warn("Skipping action with no actionType:", t);
+      return;
+    }
+    try {
+      n.events.emit({
+        type: t.actionType,
+        params: t.parameters || {}
+      });
+    } catch (m) {
+      console.error(`Error executing action ${t.actionType}:`, m);
+    }
+  });
+}
+function we(n, o) {
+  if (!o || !o.actionType) {
+    console.warn("Cannot execute action with no actionType:", o);
+    return;
+  }
+  try {
+    n.events.emit({
+      type: o.actionType,
+      params: o.parameters || {}
+    });
+  } catch (t) {
+    console.error(`Error executing action ${o.actionType}:`, t);
+  }
+}
+const Se = "world";
 export {
-  fe as EVENT_SOURCE_FOOTER,
-  ie as EVENT_SOURCE_PLAYER,
-  se as LayoutContainer,
-  de as addStandardLayoutOptions,
-  le as getWidgets,
-  me as hi,
-  ce as registerWidget
+  he as AudioPlayer,
+  ye as EVENT_SOURCE_FOOTER,
+  Te as EVENT_SOURCE_PLAYER,
+  me as LayoutContainer,
+  _e as addStandardLayoutOptions,
+  we as executeAction,
+  xe as executeActions,
+  ge as getVoiceoverHash,
+  Re as getWidgets,
+  Se as hi,
+  be as registerWidget
 };

package/dist/utils/actions.d.ts

@@ -0,0 +1,39 @@
+import { TeachariumWidgetApi } from '../teacharium-widget-api';
+/**
+ * Action configuration type
+ */
+export interface ActionConfiguration {
+    actionType: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Execute multiple actions in sequence
+ *
+ * @param api - The TeachariumWidgetApi instance
+ * @param actions - Array of action configurations to execute
+ *
+ * @example
+ * ```typescript
+ * executeActions(api, [
+ *   { actionType: "setVariable", parameters: { variableName: "score", value: 10 } },
+ *   { actionType: "showFeedback", parameters: { message: "Great!", variant: "correct" } },
+ *   { actionType: "nextStep", parameters: {} }
+ * ]);
+ * ```
+ */
+export declare function executeActions(api: TeachariumWidgetApi, actions: ActionConfiguration[]): void;
+/**
+ * Execute a single action
+ *
+ * @param api - The TeachariumWidgetApi instance
+ * @param action - Action configuration to execute
+ *
+ * @example
+ * ```typescript
+ * executeAction(api, {
+ *   actionType: "nextStep",
+ *   parameters: {}
+ * });
+ * ```
+ */
+export declare function executeAction(api: TeachariumWidgetApi, action: ActionConfiguration): void;

package/dist/utils/voiceover.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Compute a stable hash for voiceover content so the same script
+ * reuses cached audio. Relies solely on browser-compatible Web Crypto APIs.
+ */
+export declare function getVoiceoverHash(content: string): Promise<string>;

package/package.json

@@ -1,21 +1,30 @@
 {
   "name": "@teacharium/widget",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist"
   ],
   "module": "dist/teacharium-widget.es.js",
   "types": "dist/main.d.ts",
+  "scripts": {
+    "dev": "tsc -b && vite build --watch",
+    "build:watch": "tsc -b && vite build --watch",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit"
+  },
   "dependencies": {
-    "@measured/puck": "^0.20.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1"
+    "@measured/puck": "catalog:",
+    "@next/eslint-plugin-next": "^15.5.4",
+    "lucide-react": "^0.511.0",
+    "react": "catalog:",
+    "react-dom": "catalog:"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",
-    "@types/react": "^19.1.12",
-    "@types/react-dom": "^19.1.9",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "@vitejs/plugin-react": "^5.0.2",
     "eslint": "^9.35.0",
     "eslint-plugin-react-hooks": "^5.2.0",
@@ -26,10 +35,5 @@
     "vite": "^7.1.5",
     "vite-plugin-dts": "^4.5.4"
   },
-  "scripts": {
-    "dev": "tsc -b && vite build --watch",
-    "build:watch": "tsc -b && vite build --watch",
-    "build": "tsc -b && vite build",
-    "lint": "eslint ."
-  }
-}
+  "packageManager": "pnpm@10.12.4+sha512.5ea8b0deed94ed68691c9bad4c955492705c5eeb8a87ef86bc62c74a26b037b08ff9570f108b2e4dbd1dd1a9186fea925e527f141c648e85af45631074680184"
+}