dazscript-framework 0.3.2 → 1.0.2

package/README.md

@@ -1,441 +1,537 @@
 # DazScript Framework
 
-> ⚠️ This framework is under active development. The API may still evolve between releases. If you need a stable long-term surface, wait for `v1.0`.
+**DazScript Framework** is a TypeScript toolkit for writing [Daz Studio](https://www.daz3d.com/daz-studio) scripts. It layers a full TypeScript development experience on top of [DAZ Script](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/start) (Qt Script / ECMAScript 5.1), and ships a fluent dialog builder so you can build UIs in code without touching the Qt widget API directly.
 
-The **DazScript Framework** is a TypeScript-based framework for writing Daz Studio scripts. It provides all the advantages of a typed language such as autocompletion, error checking, and method parameter documentation and hinting. The framework also includes a set of dialog helpers for rapid UI development.
+## Why use it?
 
-## Benefits
+DAZ Script gives you direct access to the entire Daz Studio API. The DazScript Framework builds on that foundation and adds:
 
-- **Autocompletion:** Take advantage of IDE autocompletion for faster and more efficient script development.
-- **Error Checking:** Catch potential errors early in the development process with TypeScript's static analysis.
-- **Method Documentation & Hinting:** Get contextual documentation and hints for methods, classes, and parameters.
+- **TypeScript everywhere** — full autocompletion and type checking for every Daz Studio API, your own models, and every helper in the framework.
+- **Fast UI development** — a fluent builder API lets you describe dialogs declaratively without touching the Qt widget API by hand.
+- **Two-way data binding** — link your data model to UI controls so they stay in sync automatically. The user types in a field and your model updates; you update the model in code and the UI reflects it instantly. No manual synchronization needed.
+- **One-command build** — `npm run build` compiles TypeScript to `.dsa` files that Daz Studio runs directly.
+- **Stable launcher shims** — built scripts use a two-level layout so iterating on your code never requires reinstalling actions in Daz Studio.
+- **Automated installer generation** — `npm run installer` produces a full setup dialog by reading action metadata from your source code.
 
-## Features
+---
 
-- TypeScript support with full IntelliSense.
-- A lightweight `action(...)` entrypoint plus helper methods for building interactive scripts.
-- A generated setup dialog for installing, updating, and removing custom action registrations.
-- Setup generation is fully automated from `action(...)` metadata, including menu path, toolbar, shortcut, description, grouping, icons, and bundle-based setup outputs.
-- Easy integration with Daz Studio for quick script deployment.
+## Quick Start: Hello World
 
-## Installation
+A script that shows a message box in Daz Studio.
 
-To install the **DazScript Framework**, run the following command:
+### 1. Install
 
 ```bash
 npm install dazscript-framework dazscript-types
 ```
 
-## Setup
-
-After installing the package, scaffold the project files:
+### 2. Scaffold the project
 
 ```bash
 npx dazscript init
 ```
 
-If `--app-data-path` is not provided, `init` prompts for the AppData author namespace up front and uses the current folder name as the default product segment.
+Follow the prompt for your AppData author namespace (e.g. `YourName/my-project`). This creates `dazscript.config.ts`, `tsconfig.json`, and wires the `build`, `watch`, `icons`, and `installer` scripts into `package.json`.
 
-This generates:
+### 3. Write the script
 
-- `dazscript.config.ts`
-- `tsconfig.json`
-- `package.json` script wiring for `build`, `watch`, `icons`, and `installer`
+Create `src/hello-world.dsa.ts`:
 
-The generated package scripts use the framework CLI directly, so consumer projects do not need their own webpack or Babel setup.
+```typescript
+import { action } from '@dsf/core/action';
+import { info } from '@dsf/helpers/message-box-helper';
 
-You can customize the generated defaults:
+action({ text: 'Hello World' }, () => {
+    info('Hello World!');
+});
+```
+
+Files ending in `.dsa.ts` are compiled as runnable Daz Studio entry points.
+
+### 4. Build
 
 ```bash
-npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out --app-data-path YourName/my-project
+npm run build
 ```
 
-- `--menu-path` sets which Daz Studio menu the scripts are added to by default. See [The `action(...)` Entrypoint](#the-action-entrypoint) for how a script can override that with `menuPath`.
-- `--scripts-path` tells the installer generator where to scan for runnable `.dsa.ts` entry files.
-- `--out-dir` sets the webpack build output directory for generated `.dsa` files and copied icons.
-- `--app-data-path` sets the AppData namespace used by launcher fallback resolution. Use a unique `Author/Product` path.
+Output lands in `./out/`.
 
-Use `--scripts-path ./src/scripts` for projects shaped like `scripts/common`, where runnable `.dsa.ts` files live under `src/scripts/`. Use `--scripts-path ./src` for packages shaped like `scripts/power-menu`, where runnable `.dsa.ts` files live at the source root.
+### 5. Load in Daz Studio
 
-Set `appDataPath` explicitly in `dazscript.config.ts` for every project. It is required for builds that generate launcher shims:
+**Option A — Copy:** copy the `out/` folder into your Daz Studio scripts directory.
+
+**Option B — Symlink** (recommended for development, re-runs pick up the latest build automatically):
+
+```bash
+# Windows — run as Administrator
+mklink /D "C:\Users\[Username]\Documents\DAZ 3D\Studio\My Library\Scripts\MyScripts" "C:\path\to\project\out"
+
+# macOS
+ln -s /path/to/project/out ~/Documents/DAZ\ 3D/Studio/My\ Library/Scripts/MyScripts
+```
+
+Then in Daz Studio: **Scripts > MyScripts > Hello World**. A message box appears.
+
+---
+
+## Quick Start: A Simple Dialog
+
+A dialog with a name input and an OK/Cancel button pair.
 
 ```typescript
-import { defineConfig } from 'dazscript-framework/config';
+import { action } from '@dsf/core/action';
+import { BasicDialog } from '@dsf/dialog/basic-dialog';
+import { Observable } from '@dsf/lib/observable';
+import { info } from '@dsf/helpers/message-box-helper';
 
-export default defineConfig({
-  scriptsPath: './src',
-  outDir: './out',
-  defaultMenuPath: '/MyScripts',
-  appDataPath: 'YourName/my-project',
-  bundleName: 'My Project',
+// The model holds state
+class GreetModel {
+    name$ = new Observable<string>('World');
+}
+
+// The dialog describes the UI
+class GreetDialog extends BasicDialog {
+    constructor(private model: GreetModel) {
+        super('Greet');
+    }
+
+    protected build(): void {
+        this.add.label('Enter your name:');
+        this.add.edit().value(this.model.name$);
+        this.add.button('Say Hello').clicked(() => this.dialog.accept());
+    }
+}
+
+action({ text: 'Greet Dialog' }, () => {
+    const model = new GreetModel();
+    const dialog = new GreetDialog(model);
+
+    if (dialog.ok()) {
+        info(`Hello, ${model.name$.value}!`);
+    }
 });
 ```
 
-`bundleName` is optional display metadata for generated setup dialogs. If omitted, the dialog falls back to `Setup Scripts`. `dazscript init` now scaffolds it automatically from the project folder name.
+`add.edit().value(observable)` creates a two-way binding: typing in the field updates `name$.value`, and assigning `name$.value` in code updates the field.
+
+---
+
+## Documentation
+
+### Installation & Setup
+
+Install the framework and its peer dependency:
+
+```bash
+npm install dazscript-framework dazscript-types
+```
+
+Scaffold a new project:
 
-Built action outputs now use stable launcher shims by default:
+```bash
+npx dazscript init
+```
 
-- `out/<script>.dsa` is the stable launcher registered with Daz Studio menus, toolbars, and shortcuts
-- `out/<folder>/lib/<script-name>/script.dsa` is the current implementation bundle that the launcher executes
+If `--app-data-path` is not provided, `init` prompts for the AppData author namespace and uses the current folder name as the product segment.
 
-Rebuilding updates the implementation bundle under the shim's sibling `lib/` folder. At runtime, each launcher checks that local `lib/` path first and falls back to `App.getAppDataPath()/...` second. Because the registered launcher path stays stable, action updates normally do not require reinstalling the action in Daz Studio.
+This generates:
+- `dazscript.config.ts`
+- `tsconfig.json`
+- `package.json` script wiring for `build`, `watch`, `icons`, and `installer`
+
+Available `init` flags:
 
-## Usage
+```bash
+npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out --app-data-path YourName/my-project
+```
 
-### Quick Start: Hello World
+| Flag | Description |
+|---|---|
+| `--menu-path` | Default menu where scripts appear in Daz Studio |
+| `--scripts-path` | Where the generator scans for runnable `.dsa.ts` entry files |
+| `--out-dir` | Where `build` writes `.dsa` files and copies icons |
+| `--app-data-path` | AppData namespace for launcher fallback (`Author/Product` format) |
 
-Create a simple script that logs to the console:
+Use `--scripts-path ./src/scripts` when runnable files live under a subfolder; use `--scripts-path ./src` when they are at the source root.
+
+---
+
+### Project Configuration
+
+`dazscript.config.ts` is the single configuration file for a project:
 
 ```typescript
-import { debug } from '@dsf/common/log';
-import { action } from '@dsf/core/action';
-import { info } from '@dsf/helpers/message-box-helper';
+import { defineConfig } from 'dazscript-framework/config';
 
-action({ text: 'Hello World' }, () => {
-    debug('Hello World!');
-    info('Hello World!');
+export default defineConfig({
+    scriptsPath: './src',
+    outDir: './out',
+    defaultMenuPath: '/MyScripts',
+    appDataPath: 'YourName/my-project',  // required
+    bundleName: 'My Project',            // optional — used in the setup dialog title
 });
 ```
 
+`appDataPath` is required for builds that generate launcher shims and must be unique across your projects.
+
+---
+
 ### The `action(...)` Entrypoint
 
-Use `action(...)` at module scope to define how a runnable `.dsa.ts` file should appear in Daz Studio and what it should execute.
+Every runnable `.dsa.ts` file calls `action(...)` at module scope. This defines how the script registers in Daz Studio and what it executes.
 
 ```typescript
 action({
-  text: 'Hello World',
-  menuPath: '#{defaultMenuPath}/Examples',
-  shortcut: 'CTRL+SHIFT+H',
-  toolbar: 'MyToolbar',
-  group: 'Examples',
-  description: 'Runs the Hello World script',
+    text: 'My Script',
+    menuPath: '#{defaultMenuPath}/Tools',
+    shortcut: 'CTRL+SHIFT+M',
+    toolbar: 'MyToolbar',
+    group: 'Tools',
+    description: 'Does something useful',
 }, () => {
-    info('Hello World!');
+    info('Running!');
 });
 ```
 
-`action(...)` also accepts a reusable class with a `run()` method:
+`action(...)` also accepts a class with a `run()` method:
 
 ```typescript
-class HelloWorldScript {
+class MyScript {
     run(): void {
-        info('Hello World!');
+        info('Running!');
     }
 }
 
-action({ text: 'Hello World' }, HelloWorldScript);
+action({ text: 'My Script' }, MyScript);
 ```
 
-Common `action(...)` parameters:
+| Parameter | Description |
+|---|---|
+| `text` | Label shown in Daz Studio |
+| `menuPath` | Menu path where the action is registered. Set to `false` to skip. Defaults to `defaultMenuPath` from config. |
+| `shortcut` | Keyboard shortcut (e.g. `CTRL+SHIFT+H`) |
+| `toolbar` | Toolbar name the action should appear on |
+| `group` | Grouping label for related actions in Daz Studio |
+| `description` | Longer description for the action |
+| `bundle` | Generates a setup script beside the action. `true` → `Setup.dsa.ts`, a string → `Setup <name>.dsa.ts` |
 
-- `text`: the label shown for the script in Daz Studio.
-- `menuPath`: the menu path where the script should be added. Set it to `false` to skip adding the script to a menu. If omitted, the default menu from `--menu-path` is used.
-- `shortcut`: the keyboard shortcut for the action.
-- `toolbar`: the toolbar name used when the action should appear on a toolbar.
-- `group`: an optional grouping label used by Daz Studio for related actions.
-- `description`: a longer description for the action.
-- `bundle`: generates an additional setup script next to the action file. Use `true` for `Setup.dsa.ts` or a string for `Setup <bundle>.dsa.ts`.
+---
 
-When an action is built, the framework emits two files for it:
+### Build Output: Launcher Shims
 
-- the stable launcher at the original output path
-- the implementation bundle under a sibling `lib/<script-name>/script.dsa` path
+Each built action produces two files:
 
-Generated installers register the launcher path, so menu placement, toolbars, shortcuts, and icons keep pointing at a stable target across rebuilds.
+- `out/<script>.dsa` — the stable **launcher** registered with Daz Studio (menus, toolbars, shortcuts)
+- `out/<folder>/lib/<script-name>/script.dsa` — the **implementation bundle** the launcher executes
 
-If the local `lib/` implementation is missing, the launcher falls back to the configured `appDataPath`. Builds now require this value and validate it as a unique `Author/Product` style path.
+When you rebuild, only the implementation bundle changes. The launcher path stays stable, so re-registering the action in Daz Studio is normally not required.
+
+At runtime the launcher looks for the local `lib/` bundle first, then falls back to `App.getAppDataPath()/<appDataPath>`.
+
+---
 
 ### Generated Setup Script
 
-Running `npm run installer` generates `src/Setup.dsa.ts` for the project.
+```bash
+npm run installer
+```
+
+This scans all `.dsa.ts` entry files, reads each top-level `action(...)` call, and generates `src/Setup.dsa.ts` automatically. No installer code to maintain by hand.
+
+The generated setup dialog:
+
+- Shows an install checkbox per action with columns for Action, Shortcut, Description, Menu, and Toolbar
+- Adds a `Keyboard Shortcuts` tab when a project defines shortcut JSON
+- Includes a search box that filters across all columns
+- Supports Select All / Deselect All on the visible rows
+- Lets the user right-click to set or reset a shortcut (overrides shown with `[ovr]`)
+- Initializes from the current Daz Studio install state — already-installed actions show as checked
+- Uses `bundleName` from `dazscript.config.ts` in the window title
 
-This flow is completely automated. The installer generator scans runnable `.dsa.ts` entry files, reads the top-level `action(...)` call, and derives the setup dialog rows and registration behavior directly from that metadata. In practice, the menu path, toolbar target, shortcut, description, grouping, icon usage, and bundle-specific setup outputs all come from the action definition rather than from separate installer code you have to maintain by hand.
+Applying the dialog:
+- Checked rows are installed or updated
+- Unchecked rows are removed from their menu and toolbar targets
+- Affected toolbars are rebuilt; empty framework-created toolbars are removed
+- Selected keyboard shortcut rows are applied after actions are installed
 
-The generated setup script:
+This replaces the older `Install.dsa.ts` / `Uninstall.dsa.ts` pattern. The installer generator removes those legacy files if they exist, except when shortcut restoration is needed.
 
-- Scans all runnable top-level `.dsa.ts` files under `scriptsPath`
-- Reads `action(...)` metadata directly from the source
-- Normalizes default menu paths relative to `defaultMenuPath`
-- Derives action labels, descriptions, shortcuts, toolbar targets, grouping, and icons from the action definition
-- Writes one searchable setup entry per discovered action
-- Uses `appDataPath/Installer` as the installer settings namespace
-- Passes `bundleName` through so the dialog title can be project-specific
+### Setup Keyboard Shortcuts
 
-The setup dialog initializes from the current Daz Studio install state rather than assuming a clean install. It checks which actions are already installed, which ones are present in menus or toolbars, and what shortcut is currently assigned.
+Projects can define keyboard shortcuts for both framework custom actions and built-in Daz Studio actions. The installer generator looks for shortcut JSON in this order:
 
-Current setup dialog behavior:
+- `keyboardShortcutsPath`, `shortcutsPath`, or `actionAcceleratorsPath` in `dazscript.config.ts`
+- `src/keyboard-shortcuts.json`
+- `src/action-accelerators.json`
+- `keyboard-shortcuts.json`
+- `action-accelerators.json`
 
-- Shows an install checkbox plus the columns `Action`, `Shortcut`, `Description`, `Menu`, and `Toolbar`
-- Includes a search box that filters by action name, shortcut, description, menu path, and toolbar
-- Supports `Select All` and `Deselect All` for the currently visible rows
-- Lets the user right-click an action to set a shortcut or reset it to the default shortcut
-- Shows shortcut overrides with an `[ovr]` marker
-- Displays the configured toolbar name directly instead of a generic yes/no flag
-- Uses the configured `bundleName` in the window title when available
+The JSON can be an array or an object containing `actions`, `shortcuts`, or `accelerators`. Each entry can use the Action Accelerator Finder style fields:
 
-Applying the setup dialog does both install and cleanup work:
+```json
+[
+  {
+    "name": "DzRenderAction",
+    "text": "Render",
+    "shortcut": "CTRL+R"
+  }
+]
+```
+
+Accepted shortcut fields are `shortcut`, `accelerator`, or `key`. Accepted action-name fields are `name` or `action`.
 
-- Selected rows are installed or updated through the framework custom action helpers
-- Unselected rows are removed from supported menu and toolbar targets
-- Affected toolbars are rebuilt after removal so remaining selected actions stay grouped correctly
-- Empty toolbars created by the framework are cleaned up automatically
+At build time the JSON is embedded into generated `Setup.dsa.ts`; Daz Studio does not need to read the original JSON file at setup time. During setup, the `Keyboard Shortcuts` tab shows the action label, current shortcut, new shortcut, action type, and conflicts. The user chooses which shortcut rows to apply.
 
-The generated project-level setup file replaces the older generated `Install.dsa.ts` and `Uninstall.dsa.ts` flow. The installer generator now removes those legacy files if they still exist.
+Before changing a non-custom Daz Studio action shortcut, setup writes the original value to:
+
+```text
+App.getAppDataPath()/<appDataPath>/Installer/keyboard-shortcuts-backup.json
+```
+
+When shortcut JSON exists, the generator also writes `src/Uninstall.dsa.ts`. Running that uninstall script restores backed-up non-custom shortcuts. Custom action shortcuts are not backed up because uninstalling the custom action removes the shortcut with the action.
+
+---
 
 ### Action-Level Bundles
 
-The `bundle` property on `action(...)` is separate from project `bundleName`.
+The `bundle` property on `action(...)` is separate from the project-level `bundleName` in config.
 
-- `bundleName` in `dazscript.config.ts` is project metadata used for the setup dialog title
-- `bundle` in an action definition changes installer generation behavior for that action
+When `bundle` is set, the installer generator also writes a setup script beside that action:
 
-When `bundle` is set on an action, the installer generator also writes a setup script beside that action:
+- `bundle: true` → writes `Setup.dsa.ts`
+- `bundle: 'Utilities'` → writes `Setup Utilities.dsa.ts`
 
-- `bundle: true` writes `Setup.dsa.ts`
-- `bundle: 'Utilities'` writes `Setup Utilities.dsa.ts`
+Those bundle-scoped setup files use the same setup dialog helper and also receive the project `bundleName`.
 
-Those bundle-generated setup files use the same setup dialog helper and now also receive the project `bundleName`.
+---
 
-### Building UIs with Observables & Dialogs
+### Building UIs: Dialogs & Observables
 
-The framework uses a **Model-View pattern** with reactive data bindings:
+The framework uses a **Model-View pattern** with reactive bindings.
 
-#### 1. Define Your Model
+#### 1. Define a model
 
 ```typescript
-import { BasicDialog } from '@dsf/dialog/basic-dialog';
-import { Observable } from '@dsf/lib/observable';
 import { AppSettings } from '@dsf/lib/settings';
+import { Observable } from '@dsf/lib/observable';
 
-// Model extends AppSettings for automatic persistence
-export class MyDialogModel extends AppSettings {
+// AppSettings adds automatic persistence under the given namespace
+class MyModel extends AppSettings {
     constructor() {
-        super('MyAuthor/MyDialog'); // Namespace for saved settings
+        super('YourName/MyDialog');
     }
 
-    selectedNode$ = new Observable<DzNode>();
-    nodeLabel$ = new Observable<string>();
+    name$    = new Observable<string>();
+    enabled$ = new Observable<boolean>(false);
 }
 ```
 
-#### 2. Build Your Dialog
+#### 2. Build the dialog
 
 ```typescript
 import { BasicDialog } from '@dsf/dialog/basic-dialog';
-import { MyDialogModel } from './my-dialog-model';
 
-export class MyDialog extends BasicDialog {
-    constructor(private readonly model: MyDialogModel) {
+class MyDialog extends BasicDialog {
+    constructor(private readonly model: MyModel) {
         super('My Dialog');
     }
 
     protected build(): void {
-        const add = this.add;  // Fluent builder API
-        const model = this.model;
+        const { add, model } = this;
+
+        add.group('Settings').build(() => {
+            add.label('Name:');
+            add.edit().value(model.name$);
 
-        add.group('Node Properties').build(() => {
-            add.label('Label:');
-            add.edit().value(model.nodeLabel$);  // Two-way binding
+            add.checkbox('Enabled').value(model.enabled$);
         });
     }
 }
 ```
 
-#### 3. Connect & Use in Your Script
+#### 3. Show it from a script
 
 ```typescript
-import { action } from '@dsf/core/action';
-import { getSelectedNode } from '@dsf/helpers/scene-helper';
-import { MyDialog, MyDialogModel } from './my-dialog';
-
 action({ text: 'My Dialog Script' }, () => {
-        const model = new MyDialogModel();
-        const selectedNode = getSelectedNode();
-
-        if (!selectedNode) {
-            console.error('Please select a node');
-            return;
-        }
-
-        // Set initial model values
-        model.selectedNode$.value = selectedNode;
-        model.nodeLabel$.value = selectedNode.getLabel();
-
-        // React to model changes (two-way binding)
-        model.nodeLabel$.connect((label) => {
-            selectedNode.setLabel(label);
-        });
+    const model = new MyModel();
+    const dialog = new MyDialog(model);
 
-        // Build and show dialog
-        const dialog = new MyDialog(model);
-        if (dialog.run()) {
-            console.log('Dialog accepted');
-        } else {
-            console.log('Dialog cancelled');
-        }
+    if (dialog.ok()) {
+        // model.name$.value holds whatever the user typed
+    }
 });
 ```
 
-### Core Concepts
+---
 
-#### Observables (`Observable<T>`)
+### Observables
 
-Reactive state management with change notifications:
+`Observable<T>` is lightweight reactive state. Controls bound with `.value(observable)` stay in sync automatically.
 
 ```typescript
-const name = new Observable<string>('John');
+const name$ = new Observable<string>('initial');
 
 // Subscribe to changes
-name.connect((value) => console.log(`Name: ${value}`));
+name$.connect((value) => console.log(value));
 
-// Set value (triggers callbacks)
-name.value = 'Jane';  // Logs: "Name: Jane"
+// Set value — fires all subscribers
+name$.value = 'updated';
 
-// Intercept/validate before change
-name.intercept(
-    (prev, current) => current.toUpperCase()  // Transform
-);
+// Transform values before they are applied
+name$.intercept((prev, next) => next.trim());
 
-// Pause/resume notifications
-name.pause(() => {
-    name.value = 'A';
-    name.value = 'B';  // Won't trigger callbacks
+// Batch updates without firing subscribers mid-batch
+name$.pause(() => {
+    name$.value = 'a';
+    name$.value = 'b';  // only 'b' fires after the pause block
 });
 ```
 
-#### Available Helpers
+---
 
-The framework includes 29 helper modules for common Daz Studio tasks:
+### Dialog Builder Reference
 
-- **Scene**: `getRoot()`, `getSelectedNode()`, `getNodes()`, scene modification
-- **Nodes**: Type checking (figure, bone, etc.), transforms, visibility, selection
-- **Properties**: Finding, adjusting, interpolating property values
-- **Dialogs**: `BasicDialog`, `InputDialog`, `SelectionDialog`
-- **Arrays**: `distinct()`, `flatten()`, `groupBy()`, unique operations
-- **Strings**: Upper/lowercase, trimming, splitting
-- **Files & Paths**: Reading, writing, directory operations
-- **UI Helpers**: Message boxes, progress dialogs, menus, keyboard shortcuts
+Use `this.add` inside `build()` to construct the UI declaratively.
 
-Example:
+**Widgets**
 
-```typescript
-import * as SceneHelper from '@dsf/helpers/scene-helper';
-import * as NodeHelper from '@dsf/helpers/node-helper';
-import * as ArrayHelper from '@dsf/helpers/array-helper';
+| Builder | Description |
+|---|---|
+| `add.label(text)` | Static text label |
+| `add.edit()` | Single-line text input |
+| `add.button(text)` | Push button |
+| `add.checkbox(text)` | Checkbox |
+| `add.radio(text)` | Radio button |
+| `add.comboBox()` | Drop-down list |
+| `add.listBox()` | Scrollable list |
+| `add.slider(min, max)` | Numeric slider |
+| `add.colorPicker()` | Color picker |
+| `add.nodeSelection()` | Daz Studio node selector |
 
-const allNodes = SceneHelper.getNodes();
-const figures = allNodes.filter(n => NodeHelper.isFigure(n));
-const unique = ArrayHelper.distinct(figures);
-```
+**Layout**
 
-#### Builder Pattern for UIs
+| Builder | Description |
+|---|---|
+| `add.group(text)` | Group box |
+| `add.tab(text)` | Tab page |
+| `add.horizontal(fn)` | Horizontal layout row |
+| `add.splitter()` | Resizable splitter |
 
-Fluent, chainable API for rapid dialog construction:
+Most widget builders expose a fluent chain:
 
 ```typescript
-add.tab('Settings').build(() => {
-    add.group('Colors').build(() => {
-        add.colorPicker().value(colorObservable);
-        add.label('Opacity:');
-        add.slider(0, 100).value(opacityObservable);
-    });
+add.edit()
+    .value(model.name$)         // two-way binding
+    .toolTip('Enter your name')
+    .readOnly(false);
 
-    add.horizontal((layout) => {
-        add.label('Name:');
-        add.edit().value(nameObservable);
-    });
+add.button('Apply')
+    .clicked(() => applyChanges());
 
-    add.listView()
-        .items(itemsObservable)
-        .value(selectedItemObservable)
-        .changed((item) => console.log(`Selected: ${item}`));
+add.tab('Options').build(() => {
+    add.group('Colors').build(() => {
+        add.colorPicker().value(model.color$);
+    });
 });
 ```
 
-Supported widgets:
-- Basic: Label, Edit (text input), Button, Checkbox, Radio
-- Selection: ComboBox, ListBox, Slider, ColorPicker
-- Layout: Tab, Group, Horizontal, Vertical, Splitter
-- Advanced: ListView, TreeView, Popup Menu
+---
 
-### Two-Way Data Binding
+### Available Helpers
 
-The power of this framework is reactive data binding between models and UI:
+The framework ships helpers for common Daz Studio tasks, all importable from `@dsf/helpers/*`.
 
-```typescript
-// User types in UI → updates model → triggers logic
-model.nodeLabel$ = new Observable<string>();
+| Module | Key functions |
+|---|---|
+| `scene-helper` | `getRoot()`, `getSelectedNode()`, `getNodes()` |
+| `node-helper` | Type checks (`isFigure`, `isBone`), transforms, visibility |
+| `property-helper` | Find, read, and adjust node properties |
+| `array-helper` | `distinct()`, `flatten()`, `groupBy()` |
+| `string-helper` | Case, trimming, splitting |
+| `directory-helper` | File and path operations |
+| `message-box-helper` | `info()`, `warn()`, `error()` message boxes |
+| `progress-helper` | Progress dialogs |
+| `menu-helper` | Custom menus |
+| `undo-helper` | Undo stack integration |
 
-model.nodeLabel$.connect((newLabel) => {
-    // React to UI changes
-    selectedNode.setLabel(newLabel);
-});
+```typescript
+import * as SceneHelper from '@dsf/helpers/scene-helper';
+import * as NodeHelper from '@dsf/helpers/node-helper';
 
-// Code updates model → UI automatically reflects
-model.nodeLabel$.value = 'New Label';  // UI edit box updates
+const figures = SceneHelper.getNodes().filter(n => NodeHelper.isFigure(n));
 ```
 
-This eliminates the need for manual synchronization between UI and data.
+---
 
 ### Directory Structure
 
-For a typical project using this framework:
-
 ```
 my-daz-scripts/
 ├── src/
-│   ├── scripts/
-│   │   ├── my-first-script.dsa.ts
-│   │   ├── my-dialog-model.ts
-│   │   ├── my-dialog.ts
-│   │   └── my-dialog-script.dsa.ts
-│   └── config.ts
-├── out/                    # Generated launchers, implementations, and copied icons
-├── package.json
+│   ├── hello-world.dsa.ts       # runnable entry point → compiles to .dsa
+│   ├── my-dialog-model.ts       # plain TypeScript — model or helper class
+│   ├── my-dialog.ts
+│   └── my-dialog-script.dsa.ts  # runnable entry point
+├── out/                         # build output — launchers, bundles, icons
+├── dazscript.config.ts
 ├── tsconfig.json
-└── dazscript.config.ts
+└── package.json
 ```
 
-**Key points:**
-- Scripts ending in `.dsa.ts` compile to `.dsa` files for Daz Studio
-- Regular `.ts` files are utility, model, or helper classes
-- Built action outputs are split into stable launchers plus sibling `lib/<script-name>/script.dsa` implementations
-- Run `npm run build` to compile TypeScript → Daz Scripts
-- Run `npm run watch` during development for live rebuild
-- Rebuild after script changes; reinstalling Daz actions is usually not required because the launcher path stays stable
+Files ending in `.dsa.ts` are treated as runnable entry points and compiled to `.dsa`. Plain `.ts` files are modules — imported by entry points but not compiled independently.
+
+**Common commands**
 
-## Development & Publishing
+| Command | What it does |
+|---|---|
+| `npm run build` | Compile TypeScript → Daz Script |
+| `npm run watch` | Recompile on every save |
+| `npm run installer` | Generate the setup dialog |
+| `npm run icons` | Copy icon assets to the output folder |
 
-This project uses **semantic-release** for automatic versioning and npm publishing.
+---
 
-### Commit Message Conventions
+### Development & Publishing
+
+This package uses **semantic-release** for automatic versioning and npm publishing.
+
+#### Commit message conventions
+
+| Prefix | Effect |
+|---|---|
+| `fix: ...` | Patch bump (`1.0.0` → `1.0.1`) |
+| `feat: ...` | Minor bump (`1.0.0` → `1.1.0`) |
+| `BREAKING CHANGE: ...` in commit body | Major bump (`1.0.0` → `2.0.0`) |
+| No prefix | No version bump |
+
+Examples:
+```
+fix: resolve layout overflow in group builder
+feat: add tree view builder
+feat: refactor action entrypoint
+
+BREAKING CHANGE: action() now requires an explicit menuPath
+```
 
-Use conventional commit messages to control version bumping:
+#### Publishing
 
-- **`fix: description`** → Patch version bump (`x.y.z` → `x.y.(z+1)`)
-  - Bug fixes, patches, or minor improvements
-  - Example: `fix: resolve dialog builder layout issue`
+Every push to `master` automatically:
 
-- **`feat: description`** → Minor version bump (`x.y.z` → `x.(y+1).0`)
-  - New features or significant enhancements
-  - Example: `feat: add tree view builder component`
+1. Analyzes commit messages since the last release
+2. Updates the version in `package.json`
+3. Builds the project
+4. Creates a GitHub release with changelog
+5. Publishes to npm
 
-- **`BREAKING CHANGE: description`** → Major version bump (`x.y.z` → `(x+1).0.0`)
-  - Add to commit body for breaking changes
-  - Example: `feat: refactor action decorator API\n\nBREAKING CHANGE: action() now requires explicit menu path`
+No manual steps required.
 
-- **No prefix** → No version bump
-  - Documentation, style, or non-publishing changes
-  - Example: `update README examples`
+---
 
-### Publishing
+## Resources
 
-Every push to the `master` branch automatically triggers:
+- [DAZ Script Reference](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/start) — official Daz Studio scripting documentation
+- [dazscript-types](https://www.npmjs.com/package/dazscript-types) — TypeScript type definitions for the Daz Studio API
 
-1. **Analyze** commit messages since last release
-2. **Update** version in `package.json`
-3. **Build** the project (`npm run build`)
-4. **Create** a GitHub release with changelog
-5. **Publish** to npm
+## Examples
 
-No manual steps required—just commit with proper conventions and push!
+The `src/examples/` folder contains ready-to-run scripts demonstrating common patterns and fuller reference implementations for common Daz Studio workflows.