k3-plugin-api 1.5.0 → 1.6.0

package/README.md

@@ -13,7 +13,7 @@
 
 ## What is this package?
 
-`k3-plugin-api` contains the **TypeScript types** required to build K3 plugins — packages that extend the K3 configurator runtime with custom UI components, 3D models, pricing logic, and lifecycle hooks. The package ships zero runtime code; every export is a type, interface, or const enum.
+`k3-plugin-api` provides the **TypeScript types and runtime hooks** required to build K3 plugins — packages that extend the K3 configurator runtime with custom UI components, 3D models, pricing logic, and lifecycle hooks. It ships a thin runtime layer (reactive hooks like `useBOM()`, `useApp()`, etc.) that K3 injects at load time, plus all the type definitions for the plugin descriptor API.
 
 ---
 
@@ -41,14 +41,20 @@ const plugin: K3PluginDescriptor = {
   ui: {
     layout: {
       // wrap the default header with your own component
-      header: (Default) => (props) => <MyCustomHeader fallback={Default} {...props} />,
+      header: {
+        hoc: (Default) => (props) => <MyCustomHeader fallback={Default} {...props} />,
+        description: "Custom branded header",
+      },
     },
   },
 
   logic: {
     config: {
       // attach a custom order code to the configuration before it is persisted
-      onSave: (config) => ({ ...config, code: `TEST-${config.code}` }),
+      onSave: {
+        fn: (config) => ({ ...config, code: `TEST-${config.code}` }),
+        description: "Prepend TEST- to configuration code",
+      },
     },
   },
 };
@@ -64,35 +70,62 @@ K3 plugins can extend three layers of the configurator.
 
 ### Runtime Hooks
 
-Plugins can access K3 configurator state at runtime using React hooks. These hooks are automatically injected when the plugin is loaded.
+Plugins can access K3 configurator state at runtime using React hooks. These are automatically injected when the plugin is loaded via `init()`.
 
 ```ts
-import { useSettings, useBOM, usePrice } from "k3-plugin-api";
+import {
+  useK3PluginSettings,
+  useConfigurationVariables,
+  useConfigurationVariable,
+  useBOM,
+  useTotalPrice,
+  useFormattedTotalPrice,
+  useApp,
+  getSettings,
+} from "k3-plugin-api";
 
 const MyComponent = () => {
-  // Access plugin-specific settings
-  const settings = useSettings("acme.my-plugin");
-  
-  // Access current Bill-of-Materials
+  // Reactive plugin settings
+  const settings = useK3PluginSettings("acme.my-plugin") as { apiKey?: string };
+
+  // All configuration variables as a key-value map
+  const variables = useConfigurationVariables();
+
+  // Single variable by key
+  const color = useConfigurationVariable("color");
+
+  // Bill-of-Materials
   const bom = useBOM();
-  
-  // Access current total price
-  const price = usePrice();
-  
+
+  // Price (raw number or formatted string)
+  const price = useTotalPrice();
+  const formattedPrice = useFormattedTotalPrice();
+
+  // App metadata (product, subscription, etc.)
+  const app = useApp();
+
   return (
     <div>
       <p>API Key: {settings.apiKey}</p>
       <p>Total items: {bom.length}</p>
-      <p>Price: €{price}</p>
+      <p>Price: {formattedPrice}</p>
     </div>
   );
 };
 ```
 
-Available hooks:
-- `useSettings(pluginId: string)` — Access settings for a specific plugin
-- `useBOM()` — Get current Bill-of-Materials entries
-- `usePrice()` — Get current total price (MOV-adjusted or overall)
+Available hooks & functions:
+
+| Export                          | Description                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `getSettings(pluginId)`         | Non-reactive snapshot of plugin settings                                      |
+| `useK3PluginSettings(pluginId)` | Reactive hook — re-renders on settings change                                 |
+| `useConfigurationVariables()`   | All configuration variables as `Record<string, K3ConfigurationVariableEntry>` |
+| `useConfigurationVariable(key)` | Single variable value by its stable key                                       |
+| `useBOM()`                      | Current Bill-of-Materials (`K3BomEntry[]`)                                    |
+| `useTotalPrice()`               | Raw total price as `number`                                                   |
+| `useFormattedTotalPrice()`      | Locale-formatted price string (e.g. `"1.299,00 €"`)                           |
+| `useApp()`                      | App metadata (`K3AppInfo \| null`) — product, subscription, feature flags     |
 
 ### `settings` — Plugin Settings Component
 
@@ -120,6 +153,7 @@ const plugin: K3PluginDescriptor = {
 ```
 
 The `settings` component receives:
+
 - `settings: unknown` — The current settings object (initially `{}`)
 - `onSave: (settings: unknown) => void` — Callback to persist updated settings
 
@@ -187,18 +221,24 @@ const plugin: K3PluginDescriptor = {
 
 ## Key Types
 
-| Type                        | Description                                                     |
-| --------------------------- | --------------------------------------------------------------- |
-| `K3PluginDescriptor`        | Root descriptor object exported by a plugin                     |
-| `K3Hooks`                   | Runtime hooks interface (useSettings, useBOM, usePrice)         |
-| `HOC<P>`                    | Higher-Order Component: `(Default: FC<P>) => FC<P>`             |
-| `VariableVisualisation`     | Descriptor for a custom input visualisation                     |
-| `K3VariableComponentProps`  | Props injected into a custom variable renderer                  |
-| `DynamicModel`              | 3D model type definition for the viewer                         |
-| `K3Configuration`           | A persisted configuration with code, price, and selection JSON  |
-| `K3ConfigurationSavedEvent` | Event payload dispatched on completed save                      |
-| `K3BomEntry`                | Single Bill-of-Materials entry                                  |
-| `VariableType`              | Const enum of all variable types                                |
+| Type                           | Description                                                    |
+| ------------------------------ | -------------------------------------------------------------- |
+| `K3PluginDescriptor`           | Root descriptor object exported by a plugin                    |
+| `HOC<P>`                       | Higher-Order Component: `(Default: FC<P>) => FC<P>`            |
+| `HOCWithDescription`           | HOC + admin description (used in layout/dialog slots)          |
+| `CallbackWithDescription<T>`   | Logic callback + admin description                             |
+| `VariableVisualisation`        | Descriptor for a custom input visualisation                    |
+| `K3VariableComponentProps`     | Props injected into a custom variable renderer                 |
+| `DynamicModel`                 | 3D model type definition for the viewer                        |
+| `K3Configuration`              | A persisted configuration with code, price, and selection JSON |
+| `K3ConfigurationSavedEvent`    | Event payload dispatched on completed save                     |
+| `K3BomEntry`                   | Single Bill-of-Materials entry                                 |
+| `K3ConfigurationVariables`     | Full variables map keyed by variable key                       |
+| `K3ConfigurationVariableEntry` | Single variable value (number, string, or simplified value)    |
+| `K3SimplifiedValue`            | Resolved value option (id, key, label, value, thumbnail)       |
+| `K3AppInfo`                    | App metadata (product, subscription, feature flags)            |
+| `K3FullApp`                    | Full app snapshot passed to `preprocessFullApp`                |
+| `VariableType`                 | Const enum of all variable types                               |
 
 ---
 

package/dist/index.cjs

@@ -8,6 +8,18 @@ let _getSettings = null;
 * Internal reactive hook injected by K3 at runtime.
 */
 let _usePluginSettings = null;
+/** @internal */
+let _useSelections = null;
+/** @internal */
+let _useSelectionByVariableKey = null;
+/** @internal */
+let _useBOM = null;
+/** @internal */
+let _useTotalPrice = null;
+/** @internal */
+let _useFormattedTotalPrice = null;
+/** @internal */
+let _useApp = null;
 /**
 * Get plugin-specific settings from the K3 store.
 * Returns a snapshot of the current settings - not reactive.
@@ -46,12 +58,96 @@ function useK3PluginSettings(pluginId) {
 	return _usePluginSettings(pluginId);
 }
 /**
+* Reactive hook – returns all current configuration variables as a key-value map.
+* Keys are the variable's stable `key` string. Values are resolved (labels, not raw IDs).
+* Re-renders whenever any selection changes.
+*
+* @example
+* ```typescript
+* const variables = useConfigurationVariables();
+* const color = variables["color"] as K3SimplifiedValue;
+* ```
+*/
+function useConfigurationVariables() {
+	if (!_useSelections) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useConfigurationVariables().");
+	return _useSelections();
+}
+/**
+* Reactive hook – returns the resolved value for a specific variable by its key,
+* or `undefined` if the variable has no active selection.
+*
+* @param variableKey - The stable key of the variable (as defined in the admin)
+*
+* @example
+* ```typescript
+* const width = useConfigurationVariable("width") as number;
+* const material = useConfigurationVariable("material") as K3SimplifiedValue;
+* ```
+*/
+function useConfigurationVariable(variableKey) {
+	if (!_useSelectionByVariableKey) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useConfigurationVariable().");
+	return _useSelectionByVariableKey(variableKey);
+}
+/**
+* Reactive hook – returns the current Bill of Materials (Stückliste).
+* Re-renders whenever the BOM changes (i.e. on any selection change).
+*
+* @example
+* ```typescript
+* const bom = useBOM() as K3BomEntry[];
+* const total = bom.reduce((sum, e) => sum + e.price.price * e.qty, 0);
+* ```
+*/
+function useBOM() {
+	if (!_useBOM) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useBOM().");
+	return _useBOM();
+}
+/**
+* Reactive hook – returns the current total price as a raw number.
+* Re-renders whenever the price changes.
+*/
+function useTotalPrice() {
+	if (!_useTotalPrice) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useTotalPrice().");
+	return _useTotalPrice();
+}
+/**
+* Reactive hook – returns the current total price formatted as a locale string
+* (e.g. `"1.299,00 €"`), ready for display.
+* Re-renders whenever the price changes.
+*/
+function useFormattedTotalPrice() {
+	if (!_useFormattedTotalPrice) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useFormattedTotalPrice().");
+	return _useFormattedTotalPrice();
+}
+/**
+* Reactive hook – returns the current K3 app metadata, including the booked
+* product identifier. Returns `null` while the app has not yet loaded.
+*
+* @example
+* ```typescript
+* const app = useApp() as K3AppInfo | null;
+* if (app?.product === "k3-pro") {
+*   // enable pro-only features
+* }
+* ```
+*/
+function useApp() {
+	if (!_useApp) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useApp().");
+	return _useApp();
+}
+/**
 * Called by K3 when the plugin is loaded to inject runtime API functions.
 * @internal This function is called by K3 automatically - plugins should not call it directly.
 */
 function init(api) {
 	_getSettings = api.getSettings;
 	_usePluginSettings = api.usePluginSettings;
+	_useSelections = api.useConfigurationVariables;
+	_useSelectionByVariableKey = api.useConfigurationVariable;
+	_useBOM = api.useBOM;
+	_useTotalPrice = api.useTotalPrice;
+	_useFormattedTotalPrice = api.useFormattedTotalPrice;
+	_useApp = api.useApp;
 }
 /** All variable type string literals. */
 const VariableType = {
@@ -70,4 +166,10 @@ const VariableType = {
 exports.VariableType = VariableType;
 exports.getSettings = getSettings;
 exports.init = init;
+exports.useApp = useApp;
+exports.useBOM = useBOM;
+exports.useConfigurationVariable = useConfigurationVariable;
+exports.useConfigurationVariables = useConfigurationVariables;
+exports.useFormattedTotalPrice = useFormattedTotalPrice;
 exports.useK3PluginSettings = useK3PluginSettings;
+exports.useTotalPrice = useTotalPrice;

package/dist/index.d.cts

@@ -33,6 +33,66 @@ declare function getSettings(pluginId: string): unknown;
  * ```
  */
 declare function useK3PluginSettings(pluginId: string): unknown;
+/**
+ * Reactive hook – returns all current configuration variables as a key-value map.
+ * Keys are the variable's stable `key` string. Values are resolved (labels, not raw IDs).
+ * Re-renders whenever any selection changes.
+ *
+ * @example
+ * ```typescript
+ * const variables = useConfigurationVariables();
+ * const color = variables["color"] as K3SimplifiedValue;
+ * ```
+ */
+declare function useConfigurationVariables(): K3ConfigurationVariables;
+/**
+ * Reactive hook – returns the resolved value for a specific variable by its key,
+ * or `undefined` if the variable has no active selection.
+ *
+ * @param variableKey - The stable key of the variable (as defined in the admin)
+ *
+ * @example
+ * ```typescript
+ * const width = useConfigurationVariable("width") as number;
+ * const material = useConfigurationVariable("material") as K3SimplifiedValue;
+ * ```
+ */
+declare function useConfigurationVariable(variableKey: string): K3ConfigurationVariableEntry | undefined;
+/**
+ * Reactive hook – returns the current Bill of Materials (Stückliste).
+ * Re-renders whenever the BOM changes (i.e. on any selection change).
+ *
+ * @example
+ * ```typescript
+ * const bom = useBOM() as K3BomEntry[];
+ * const total = bom.reduce((sum, e) => sum + e.price.price * e.qty, 0);
+ * ```
+ */
+declare function useBOM(): K3BomEntry[];
+/**
+ * Reactive hook – returns the current total price as a raw number.
+ * Re-renders whenever the price changes.
+ */
+declare function useTotalPrice(): number;
+/**
+ * Reactive hook – returns the current total price formatted as a locale string
+ * (e.g. `"1.299,00 €"`), ready for display.
+ * Re-renders whenever the price changes.
+ */
+declare function useFormattedTotalPrice(): string;
+/**
+ * Reactive hook – returns the current K3 app metadata, including the booked
+ * product identifier. Returns `null` while the app has not yet loaded.
+ *
+ * @example
+ * ```typescript
+ * const app = useApp() as K3AppInfo | null;
+ * if (app?.product === "k3-pro") {
+ *   // enable pro-only features
+ * }
+ * ```
+ */
+declare function useApp(): K3AppInfo | null;
 /**
  * Called by K3 when the plugin is loaded to inject runtime API functions.
  * @internal This function is called by K3 automatically - plugins should not call it directly.
@@ -40,6 +100,12 @@ declare function useK3PluginSettings(pluginId: string): unknown;
 declare function init(api: {
   getSettings: (pluginId: string) => unknown;
   usePluginSettings: (pluginId: string) => unknown;
+  useConfigurationVariables: () => K3ConfigurationVariables;
+  useConfigurationVariable: (variableKey: string) => K3ConfigurationVariableEntry | undefined;
+  useBOM: () => unknown[];
+  useTotalPrice: () => number;
+  useFormattedTotalPrice: () => string;
+  useApp: () => unknown | null;
 }): void;
 /** A Higher-Order Component: takes the default component, returns a new one. */
 type HOC<P = Record<string, unknown>> = (comp: React.FC<P>) => React.FC<P>;
@@ -270,6 +336,60 @@ interface K3WarningExtensions {
   /** Wraps the tooltip content shown when a number variable value is out of bounds. */
   numberWarningTooltip?: HOCWithDescription;
 }
+/**
+ * Simplified app metadata exposed to plugins.
+ * Useful for reading the booked product and subscription info.
+ */
+interface K3AppInfo {
+  /** Database ID of the app. */
+  id: number;
+  /** Human-readable app label. */
+  label: string;
+  /** Unique stable app code. */
+  code: string;
+  /**
+   * Identifier of the booked product (e.g. `"k3-pro"`).
+   * Use this to conditionally enable features based on the customer's plan.
+   */
+  product?: string;
+  /** Subscription billing interval for this app. */
+  interval?: "month" | "year";
+  /** Feature flags of the currently booked product. */
+  productDetails?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * A resolved value option (list, color, boolean, image, upload, multiSelect).
+ * Contains human-readable labels and the underlying data value.
+ */
+interface K3SimplifiedValue {
+  /** Database ID of the value. */
+  id: number | string;
+  /** Stable key of the value, if defined. */
+  key?: string | null;
+  /** Translated display label. */
+  label: string;
+  /** Underlying data: hex color string, boolean flag, or generic string payload. */
+  value?: string | boolean | null;
+  /** Thumbnail image URL. */
+  thumbnail?: string | null;
+}
+/**
+ * A single configuration variable entry. The concrete type depends on the variable type:
+ * - Number variables → `number`
+ * - Text variables → `string`
+ * - List / Color / Boolean / Image / Upload → `K3SimplifiedValue`
+ * - MultiSelect → `K3SimplifiedValue[]`
+ * - Component variables → `K3ComponentInstanceVariables[]` (recursive)
+ */
+type K3ConfigurationVariableEntry = number | string | K3SimplifiedValue | K3SimplifiedValue[] | K3ComponentInstanceVariables[];
+/** A single component instance's variables, keyed by variable key. */
+type K3ComponentInstanceVariables = Record<string, K3ConfigurationVariableEntry>;
+/**
+ * The full configuration variables map, keyed by the variable's stable `key` string.
+ * Returned by `useConfigurationVariables()`.
+ */
+type K3ConfigurationVariables = Record<string, K3ConfigurationVariableEntry>;
 /**
  * A single Bill-of-Materials entry exposed to plugin components.
  * Mirrors the internal BOMEntry shape using only primitive/simple types.
@@ -796,4 +916,4 @@ interface PluginModelContext {
 /** @deprecated Use K3PluginDescriptor */
 type K3Plugin = Pick<K3PluginDescriptor, "dynamicModels">;
 //#endregion
-export { CallbackWithDescription, CustomLayoutComponentProps, DynamicModel, DynamicModelComponentProps, HOC, HOCWithDescription, K3ARExportContext, K3ARPlatform, K3BomEntry, K3Camera, K3CameraScope, K3Configuration, K3ConfigurationSavedEvent, K3Coordinates, K3DialogExtensions, K3FullApp, K3InputExtensions, K3LayoutExtensions, K3LogicExtensions, K3NewConfiguration, K3OrderDialogExtensions, K3OrthographicCamera, K3PerspectiveCamera, K3Plugin, K3PluginDescriptor, K3SaveResult, K3Scene, K3ScreenshotDimensions, K3Selection, K3UIExtensions, K3UploadFile, K3VariableComponentProps, K3ViewerExtensions, K3WarningExtensions, LocalizedString, ModelProp, ModelPropDefault, PluginModelContext, SlotDefinition, SlotModelInstance, Value, VariableType, VariableTypes, VariableVisualisation, getSettings, init, useK3PluginSettings };
+export { CallbackWithDescription, CustomLayoutComponentProps, DynamicModel, DynamicModelComponentProps, HOC, HOCWithDescription, K3ARExportContext, K3ARPlatform, K3AppInfo, K3BomEntry, K3Camera, K3CameraScope, K3ComponentInstanceVariables, K3Configuration, K3ConfigurationSavedEvent, K3ConfigurationVariableEntry, K3ConfigurationVariables, K3Coordinates, K3DialogExtensions, K3FullApp, K3InputExtensions, K3LayoutExtensions, K3LogicExtensions, K3NewConfiguration, K3OrderDialogExtensions, K3OrthographicCamera, K3PerspectiveCamera, K3Plugin, K3PluginDescriptor, K3SaveResult, K3Scene, K3ScreenshotDimensions, K3Selection, K3SimplifiedValue, K3UIExtensions, K3UploadFile, K3VariableComponentProps, K3ViewerExtensions, K3WarningExtensions, LocalizedString, ModelProp, ModelPropDefault, PluginModelContext, SlotDefinition, SlotModelInstance, Value, VariableType, VariableTypes, VariableVisualisation, getSettings, init, useApp, useBOM, useConfigurationVariable, useConfigurationVariables, useFormattedTotalPrice, useK3PluginSettings, useTotalPrice };

package/dist/index.d.ts

@@ -33,6 +33,66 @@ declare function getSettings(pluginId: string): unknown;
  * ```
  */
 declare function useK3PluginSettings(pluginId: string): unknown;
+/**
+ * Reactive hook – returns all current configuration variables as a key-value map.
+ * Keys are the variable's stable `key` string. Values are resolved (labels, not raw IDs).
+ * Re-renders whenever any selection changes.
+ *
+ * @example
+ * ```typescript
+ * const variables = useConfigurationVariables();
+ * const color = variables["color"] as K3SimplifiedValue;
+ * ```
+ */
+declare function useConfigurationVariables(): K3ConfigurationVariables;
+/**
+ * Reactive hook – returns the resolved value for a specific variable by its key,
+ * or `undefined` if the variable has no active selection.
+ *
+ * @param variableKey - The stable key of the variable (as defined in the admin)
+ *
+ * @example
+ * ```typescript
+ * const width = useConfigurationVariable("width") as number;
+ * const material = useConfigurationVariable("material") as K3SimplifiedValue;
+ * ```
+ */
+declare function useConfigurationVariable(variableKey: string): K3ConfigurationVariableEntry | undefined;
+/**
+ * Reactive hook – returns the current Bill of Materials (Stückliste).
+ * Re-renders whenever the BOM changes (i.e. on any selection change).
+ *
+ * @example
+ * ```typescript
+ * const bom = useBOM() as K3BomEntry[];
+ * const total = bom.reduce((sum, e) => sum + e.price.price * e.qty, 0);
+ * ```
+ */
+declare function useBOM(): K3BomEntry[];
+/**
+ * Reactive hook – returns the current total price as a raw number.
+ * Re-renders whenever the price changes.
+ */
+declare function useTotalPrice(): number;
+/**
+ * Reactive hook – returns the current total price formatted as a locale string
+ * (e.g. `"1.299,00 €"`), ready for display.
+ * Re-renders whenever the price changes.
+ */
+declare function useFormattedTotalPrice(): string;
+/**
+ * Reactive hook – returns the current K3 app metadata, including the booked
+ * product identifier. Returns `null` while the app has not yet loaded.
+ *
+ * @example
+ * ```typescript
+ * const app = useApp() as K3AppInfo | null;
+ * if (app?.product === "k3-pro") {
+ *   // enable pro-only features
+ * }
+ * ```
+ */
+declare function useApp(): K3AppInfo | null;
 /**
  * Called by K3 when the plugin is loaded to inject runtime API functions.
  * @internal This function is called by K3 automatically - plugins should not call it directly.
@@ -40,6 +100,12 @@ declare function useK3PluginSettings(pluginId: string): unknown;
 declare function init(api: {
   getSettings: (pluginId: string) => unknown;
   usePluginSettings: (pluginId: string) => unknown;
+  useConfigurationVariables: () => K3ConfigurationVariables;
+  useConfigurationVariable: (variableKey: string) => K3ConfigurationVariableEntry | undefined;
+  useBOM: () => unknown[];
+  useTotalPrice: () => number;
+  useFormattedTotalPrice: () => string;
+  useApp: () => unknown | null;
 }): void;
 /** A Higher-Order Component: takes the default component, returns a new one. */
 type HOC<P = Record<string, unknown>> = (comp: React.FC<P>) => React.FC<P>;
@@ -270,6 +336,60 @@ interface K3WarningExtensions {
   /** Wraps the tooltip content shown when a number variable value is out of bounds. */
   numberWarningTooltip?: HOCWithDescription;
 }
+/**
+ * Simplified app metadata exposed to plugins.
+ * Useful for reading the booked product and subscription info.
+ */
+interface K3AppInfo {
+  /** Database ID of the app. */
+  id: number;
+  /** Human-readable app label. */
+  label: string;
+  /** Unique stable app code. */
+  code: string;
+  /**
+   * Identifier of the booked product (e.g. `"k3-pro"`).
+   * Use this to conditionally enable features based on the customer's plan.
+   */
+  product?: string;
+  /** Subscription billing interval for this app. */
+  interval?: "month" | "year";
+  /** Feature flags of the currently booked product. */
+  productDetails?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * A resolved value option (list, color, boolean, image, upload, multiSelect).
+ * Contains human-readable labels and the underlying data value.
+ */
+interface K3SimplifiedValue {
+  /** Database ID of the value. */
+  id: number | string;
+  /** Stable key of the value, if defined. */
+  key?: string | null;
+  /** Translated display label. */
+  label: string;
+  /** Underlying data: hex color string, boolean flag, or generic string payload. */
+  value?: string | boolean | null;
+  /** Thumbnail image URL. */
+  thumbnail?: string | null;
+}
+/**
+ * A single configuration variable entry. The concrete type depends on the variable type:
+ * - Number variables → `number`
+ * - Text variables → `string`
+ * - List / Color / Boolean / Image / Upload → `K3SimplifiedValue`
+ * - MultiSelect → `K3SimplifiedValue[]`
+ * - Component variables → `K3ComponentInstanceVariables[]` (recursive)
+ */
+type K3ConfigurationVariableEntry = number | string | K3SimplifiedValue | K3SimplifiedValue[] | K3ComponentInstanceVariables[];
+/** A single component instance's variables, keyed by variable key. */
+type K3ComponentInstanceVariables = Record<string, K3ConfigurationVariableEntry>;
+/**
+ * The full configuration variables map, keyed by the variable's stable `key` string.
+ * Returned by `useConfigurationVariables()`.
+ */
+type K3ConfigurationVariables = Record<string, K3ConfigurationVariableEntry>;
 /**
  * A single Bill-of-Materials entry exposed to plugin components.
  * Mirrors the internal BOMEntry shape using only primitive/simple types.
@@ -796,4 +916,4 @@ interface PluginModelContext {
 /** @deprecated Use K3PluginDescriptor */
 type K3Plugin = Pick<K3PluginDescriptor, "dynamicModels">;
 //#endregion
-export { CallbackWithDescription, CustomLayoutComponentProps, DynamicModel, DynamicModelComponentProps, HOC, HOCWithDescription, K3ARExportContext, K3ARPlatform, K3BomEntry, K3Camera, K3CameraScope, K3Configuration, K3ConfigurationSavedEvent, K3Coordinates, K3DialogExtensions, K3FullApp, K3InputExtensions, K3LayoutExtensions, K3LogicExtensions, K3NewConfiguration, K3OrderDialogExtensions, K3OrthographicCamera, K3PerspectiveCamera, K3Plugin, K3PluginDescriptor, K3SaveResult, K3Scene, K3ScreenshotDimensions, K3Selection, K3UIExtensions, K3UploadFile, K3VariableComponentProps, K3ViewerExtensions, K3WarningExtensions, LocalizedString, ModelProp, ModelPropDefault, PluginModelContext, SlotDefinition, SlotModelInstance, Value, VariableType, VariableTypes, VariableVisualisation, getSettings, init, useK3PluginSettings };
+export { CallbackWithDescription, CustomLayoutComponentProps, DynamicModel, DynamicModelComponentProps, HOC, HOCWithDescription, K3ARExportContext, K3ARPlatform, K3AppInfo, K3BomEntry, K3Camera, K3CameraScope, K3ComponentInstanceVariables, K3Configuration, K3ConfigurationSavedEvent, K3ConfigurationVariableEntry, K3ConfigurationVariables, K3Coordinates, K3DialogExtensions, K3FullApp, K3InputExtensions, K3LayoutExtensions, K3LogicExtensions, K3NewConfiguration, K3OrderDialogExtensions, K3OrthographicCamera, K3PerspectiveCamera, K3Plugin, K3PluginDescriptor, K3SaveResult, K3Scene, K3ScreenshotDimensions, K3Selection, K3SimplifiedValue, K3UIExtensions, K3UploadFile, K3VariableComponentProps, K3ViewerExtensions, K3WarningExtensions, LocalizedString, ModelProp, ModelPropDefault, PluginModelContext, SlotDefinition, SlotModelInstance, Value, VariableType, VariableTypes, VariableVisualisation, getSettings, init, useApp, useBOM, useConfigurationVariable, useConfigurationVariables, useFormattedTotalPrice, useK3PluginSettings, useTotalPrice };

package/dist/index.js

@@ -7,6 +7,18 @@ let _getSettings = null;
 * Internal reactive hook injected by K3 at runtime.
 */
 let _usePluginSettings = null;
+/** @internal */
+let _useSelections = null;
+/** @internal */
+let _useSelectionByVariableKey = null;
+/** @internal */
+let _useBOM = null;
+/** @internal */
+let _useTotalPrice = null;
+/** @internal */
+let _useFormattedTotalPrice = null;
+/** @internal */
+let _useApp = null;
 /**
 * Get plugin-specific settings from the K3 store.
 * Returns a snapshot of the current settings - not reactive.
@@ -45,12 +57,96 @@ function useK3PluginSettings(pluginId) {
 	return _usePluginSettings(pluginId);
 }
 /**
+* Reactive hook – returns all current configuration variables as a key-value map.
+* Keys are the variable's stable `key` string. Values are resolved (labels, not raw IDs).
+* Re-renders whenever any selection changes.
+*
+* @example
+* ```typescript
+* const variables = useConfigurationVariables();
+* const color = variables["color"] as K3SimplifiedValue;
+* ```
+*/
+function useConfigurationVariables() {
+	if (!_useSelections) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useConfigurationVariables().");
+	return _useSelections();
+}
+/**
+* Reactive hook – returns the resolved value for a specific variable by its key,
+* or `undefined` if the variable has no active selection.
+*
+* @param variableKey - The stable key of the variable (as defined in the admin)
+*
+* @example
+* ```typescript
+* const width = useConfigurationVariable("width") as number;
+* const material = useConfigurationVariable("material") as K3SimplifiedValue;
+* ```
+*/
+function useConfigurationVariable(variableKey) {
+	if (!_useSelectionByVariableKey) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useConfigurationVariable().");
+	return _useSelectionByVariableKey(variableKey);
+}
+/**
+* Reactive hook – returns the current Bill of Materials (Stückliste).
+* Re-renders whenever the BOM changes (i.e. on any selection change).
+*
+* @example
+* ```typescript
+* const bom = useBOM() as K3BomEntry[];
+* const total = bom.reduce((sum, e) => sum + e.price.price * e.qty, 0);
+* ```
+*/
+function useBOM() {
+	if (!_useBOM) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useBOM().");
+	return _useBOM();
+}
+/**
+* Reactive hook – returns the current total price as a raw number.
+* Re-renders whenever the price changes.
+*/
+function useTotalPrice() {
+	if (!_useTotalPrice) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useTotalPrice().");
+	return _useTotalPrice();
+}
+/**
+* Reactive hook – returns the current total price formatted as a locale string
+* (e.g. `"1.299,00 €"`), ready for display.
+* Re-renders whenever the price changes.
+*/
+function useFormattedTotalPrice() {
+	if (!_useFormattedTotalPrice) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useFormattedTotalPrice().");
+	return _useFormattedTotalPrice();
+}
+/**
+* Reactive hook – returns the current K3 app metadata, including the booked
+* product identifier. Returns `null` while the app has not yet loaded.
+*
+* @example
+* ```typescript
+* const app = useApp() as K3AppInfo | null;
+* if (app?.product === "k3-pro") {
+*   // enable pro-only features
+* }
+* ```
+*/
+function useApp() {
+	if (!_useApp) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useApp().");
+	return _useApp();
+}
+/**
 * Called by K3 when the plugin is loaded to inject runtime API functions.
 * @internal This function is called by K3 automatically - plugins should not call it directly.
 */
 function init(api) {
 	_getSettings = api.getSettings;
 	_usePluginSettings = api.usePluginSettings;
+	_useSelections = api.useConfigurationVariables;
+	_useSelectionByVariableKey = api.useConfigurationVariable;
+	_useBOM = api.useBOM;
+	_useTotalPrice = api.useTotalPrice;
+	_useFormattedTotalPrice = api.useFormattedTotalPrice;
+	_useApp = api.useApp;
 }
 /** All variable type string literals. */
 const VariableType = {
@@ -66,4 +162,4 @@ const VariableType = {
 	Information: "information"
 };
 //#endregion
-export { VariableType, getSettings, init, useK3PluginSettings };
+export { VariableType, getSettings, init, useApp, useBOM, useConfigurationVariable, useConfigurationVariables, useFormattedTotalPrice, useK3PluginSettings, useTotalPrice };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k3-plugin-api",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Official TypeScript types and plugin API for the K3 product configurator",
   "type": "module",
   "main": "dist/index.cjs",