@gesslar/actioneer 2.1.0 → 2.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Actioneer
 
-Actioneer is a small, focused action orchestration library for Node.js and browser environments. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and simple loop semantics (while/until). The project is written as ES modules and targets Node 20+ and modern browsers.
+Actioneer is a small, focused action orchestration library for Node.js and browser environments. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and control flow semantics (while/until/if/break/continue). The project is written as ES modules and targets Node 20+ and modern browsers.
 
 This repository extracts the action orchestration pieces from a larger codebase and exposes a compact API for building pipelines of work that can run concurrently with hook support and nested pipelines.
 
@@ -16,7 +16,7 @@ These classes work in browsers, Node.js, and browser-like environments such as T
 | ActionHooks | Lifecycle hook management (requires pre-instantiated hooks in browser) |
 | ActionRunner | Concurrent pipeline executor with configurable concurrency |
 | ActionWrapper | Activity container and iterator |
-| Activity | Activity definitions with WHILE, UNTIL, and SPLIT modes |
+| Activity | Activity definitions with WHILE, UNTIL, IF, BREAK, CONTINUE, and SPLIT modes |
 | Piper | Base concurrent processing with worker pools |
 
 ### Node.js
@@ -133,7 +133,7 @@ If you'd like more complete typings or additional JSDoc, open an issue or send a
 
 ## Activity Modes
 
-Actioneer supports four distinct execution modes for activities, allowing you to control how operations are executed:
+Actioneer supports six distinct execution modes for activities, allowing you to control how operations are executed:
 
 ### Execute Once (Default)
 
@@ -203,6 +203,133 @@ class ProcessorAction {
 
 The activity executes at least once, then continues while the predicate returns `false`. Once it returns `true`, execution moves to the next activity.
 
+### IF Mode
+
+Conditionally executes an activity based on a predicate. Unlike WHILE/UNTIL, IF executes at most once:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class ConditionalAction {
+  #shouldProcess = (ctx) => ctx.value > 10
+
+  #processLargeValue = (ctx) => {
+    ctx.processed = ctx.value * 2
+  }
+
+  setup(builder) {
+    builder
+      .do("initialize", ctx => { ctx.value = 15 })
+      .do("maybeProcess", ACTIVITY.IF, this.#shouldProcess, this.#processLargeValue)
+      .do("finish", ctx => { return ctx })
+  }
+}
+```
+
+If the predicate returns `true`, the activity executes once. If `false`, the activity is skipped entirely and execution moves to the next activity.
+
+### BREAK Mode
+
+Breaks out of a WHILE or UNTIL loop when a predicate returns `true`. BREAK must be used inside a nested ActionBuilder within a loop:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class BreakExample {
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.count = 0
+        ctx.items = []
+      })
+      .do("loop", ACTIVITY.WHILE, ctx => ctx.count < 100,
+        new ActionBuilder()
+          .do("increment", ctx => {
+            ctx.count++
+            ctx.items.push(ctx.count)
+            return ctx
+          })
+          .do("earlyExit", ACTIVITY.BREAK, ctx => ctx.count >= 5)
+      )
+      .do("finish", ctx => { return ctx.items }) // Returns [1, 2, 3, 4, 5]
+  }
+}
+```
+
+When the BREAK predicate returns `true`, the loop terminates immediately and execution continues with the next activity after the loop.
+
+**Important:** BREAK only works inside a nested ActionBuilder that is the operation of a WHILE or UNTIL activity. Using BREAK outside of a loop context will throw an error.
+
+### CONTINUE Mode
+
+Skips the remaining activities in the current loop iteration and continues to the next iteration. Like BREAK, CONTINUE must be used inside a nested ActionBuilder within a loop:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class ContinueExample {
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.count = 0
+        ctx.processed = []
+      })
+      .do("loop", ACTIVITY.WHILE, ctx => ctx.count < 5,
+        new ActionBuilder()
+          .do("increment", ctx => {
+            ctx.count++
+            return ctx
+          })
+          .do("skipEvens", ACTIVITY.CONTINUE, ctx => ctx.count % 2 === 0)
+          .do("process", ctx => {
+            ctx.processed.push(ctx.count)
+            return ctx
+          })
+      )
+      .do("finish", ctx => { return ctx.processed }) // Returns [1, 3, 5]
+  }
+}
+```
+
+When the CONTINUE predicate returns `true`, the remaining activities in that iteration are skipped, and the loop continues with its next iteration (re-evaluating the loop predicate for WHILE, or executing the operation then evaluating for UNTIL).
+
+**Important:** Like BREAK, CONTINUE only works inside a nested ActionBuilder within a WHILE or UNTIL loop.
+
+### Combining Control Flow
+
+You can combine IF, BREAK, and CONTINUE within the same loop for complex control flow:
+
+```js
+class CombinedExample {
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.count = 0
+        ctx.results = []
+      })
+      .do("loop", ACTIVITY.WHILE, ctx => ctx.count < 100,
+        new ActionBuilder()
+          .do("increment", ctx => { ctx.count++; return ctx })
+          .do("exitAt10", ACTIVITY.BREAK, ctx => ctx.count > 10)
+          .do("skipEvens", ACTIVITY.CONTINUE, ctx => ctx.count % 2 === 0)
+          .do("processLarge", ACTIVITY.IF, ctx => ctx.count > 5, ctx => {
+            ctx.results.push(ctx.count * 10)
+            return ctx
+          })
+          .do("processAll", ctx => {
+            ctx.results.push(ctx.count)
+            return ctx
+          })
+      )
+  }
+}
+// Results: [1, 3, 5, 70, 7, 90, 9]
+// - 1, 3, 5: odd numbers <= 5, just pushed
+// - 7, 9: odd numbers > 5, pushed with *10 first, then pushed
+// - evens skipped by CONTINUE
+// - loop exits when count > 10
+```
+
 ### SPLIT Mode
 
 Executes with a split/rejoin pattern for parallel execution. This mode requires a splitter function to divide the context and a rejoiner function to recombine results:
@@ -301,18 +428,22 @@ class NestedParallel {
 
 ### Mode Constraints
 
-- **Only one mode per activity**: You cannot combine WHILE, UNTIL, and SPLIT. Attempting to use multiple modes will throw an error: `"You can't combine activity kinds. Pick one: WHILE, UNTIL, or SPLIT!"`
+- **Only one mode per activity**: Each activity can have only one mode. Attempting to combine modes will throw an error
 - **SPLIT requires both functions**: The splitter and rejoiner are both mandatory for SPLIT mode
-- **Predicates must return boolean**: For WHILE and UNTIL modes, predicates should return `true` or `false`
+- **Predicates must return boolean**: All predicates (WHILE, UNTIL, IF, BREAK, CONTINUE) should return `true` or `false`
+- **BREAK/CONTINUE require loop context**: These modes only work inside a nested ActionBuilder within a WHILE or UNTIL loop
 
 ### Mode Summary Table
 
-| Mode        | Signature                                                  | Predicate Timing | Use Case                             |
-| ----------- | ---------------------------------------------------------- | ---------------- | ------------------------------------ |
-| **Default** | `.do(name, operation)`                                     | N/A              | Execute once per context             |
-| **WHILE**   | `.do(name, ACTIVITY.WHILE, predicate, operation)`          | Before iteration | Loop while condition is true         |
-| **UNTIL**   | `.do(name, ACTIVITY.UNTIL, predicate, operation)`          | After iteration  | Loop until condition is true         |
-| **SPLIT**   | `.do(name, ACTIVITY.SPLIT, splitter, rejoiner, operation)` | N/A              | Parallel execution with split/rejoin |
+| Mode         | Signature                                                  | Predicate Timing | Use Case                                    |
+| ------------ | ---------------------------------------------------------- | ---------------- | ------------------------------------------- |
+| **Default**  | `.do(name, operation)`                                     | N/A              | Execute once per context                    |
+| **WHILE**    | `.do(name, ACTIVITY.WHILE, predicate, operation)`          | Before iteration | Loop while condition is true                |
+| **UNTIL**    | `.do(name, ACTIVITY.UNTIL, predicate, operation)`          | After iteration  | Loop until condition is true                |
+| **IF**       | `.do(name, ACTIVITY.IF, predicate, operation)`             | Before execution | Conditional execution (once or skip)        |
+| **BREAK**    | `.do(name, ACTIVITY.BREAK, predicate)`                     | When reached     | Exit enclosing WHILE/UNTIL loop             |
+| **CONTINUE** | `.do(name, ACTIVITY.CONTINUE, predicate)`                  | When reached     | Skip to next iteration of enclosing loop    |
+| **SPLIT**    | `.do(name, ACTIVITY.SPLIT, splitter, rejoiner, operation)` | N/A              | Parallel execution with split/rejoin        |
 
 ## Running Actions: `run()` vs `pipe()`
 
@@ -376,6 +507,74 @@ The `pipe()` method uses `Promise.allSettled()` internally and returns an array
 
 This design ensures error handling responsibility stays at the call site - you decide how to handle failures rather than the framework deciding for you.
 
+## Pipeline Completion: `done()`
+
+The `done()` method registers a callback that executes after all activities in the pipeline complete, regardless of whether an error occurred. This is useful for cleanup, finalization, or returning a transformed result.
+
+```js
+import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
+
+class MyAction {
+  setup(builder) {
+    builder
+      .do("step1", ctx => { ctx.a = 1 })
+      .do("step2", ctx => { ctx.b = 2 })
+      .done(ctx => {
+        // This runs after all activities complete
+        return { total: ctx.a + ctx.b }
+      })
+  }
+}
+
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+const result = await runner.run({})
+console.log(result) // { total: 3 }
+```
+
+### Key Behaviors
+
+- **Always executes**: The `done()` callback runs even if an earlier activity throws an error (similar to `finally` in try/catch)
+- **Top-level only**: The callback only runs for the outermost pipeline, not for nested builders inside loops (WHILE/UNTIL). However, for SPLIT activities, `done()` runs for each split context since each is an independent execution
+- **Transform the result**: Whatever you return from `done()` becomes the final pipeline result
+- **Access to action context**: The callback is bound to the action instance, so `this` refers to your action class
+- **Async support**: The callback can be async and return a Promise
+
+### Use Cases
+
+**Cleanup resources:**
+
+```js
+builder
+  .do("openConnection", ctx => { ctx.conn = openDb() })
+  .do("query", ctx => { ctx.data = ctx.conn.query("SELECT *") })
+  .done(ctx => {
+    ctx.conn.close() // Always close, even on error
+    return ctx.data
+  })
+```
+
+**Transform the final result:**
+
+```js
+builder
+  .do("gather", ctx => { ctx.items = [1, 2, 3] })
+  .do("process", ctx => { ctx.items = ctx.items.map(x => x * 2) })
+  .done(ctx => ctx.items) // Return just the items array, not the whole context
+```
+
+**Logging and metrics:**
+
+```js
+builder
+  .do("start", ctx => { ctx.startTime = Date.now() })
+  .do("work", ctx => { /* ... */ })
+  .done(ctx => {
+    console.log(`Pipeline completed in ${Date.now() - ctx.startTime}ms`)
+    return ctx
+  })
+```
+
 ## ActionHooks
 
 Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks can be configured by file path (Node.js only) or by providing a pre-instantiated hooks object (Node.js and browser).
@@ -558,9 +757,9 @@ Run the comprehensive test suite with Node's built-in test runner:
 npm test
 ```
 
-The test suite includes 150+ tests covering all core classes and behaviors:
+The test suite includes 200+ tests covering all core classes and behaviors:
 
-- **Activity** - Activity definitions, ACTIVITY flags (WHILE, UNTIL, SPLIT), and execution
+- **Activity** - Activity definitions, ACTIVITY flags (WHILE, UNTIL, IF, BREAK, CONTINUE, SPLIT), and execution
 - **ActionBuilder** - Fluent builder API, activity registration, and hooks configuration
 - **ActionWrapper** - Activity iteration and integration with ActionBuilder
 - **ActionRunner** - Pipeline execution, loop semantics, nested builders, and error handling

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -49,10 +49,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gesslar/toolkit": "^3.23.0"
+    "@gesslar/toolkit": "^3.24.0"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^1.1.0",
+    "@gesslar/uglier": "^1.2.0",
     "eslint": "^9.39.2",
     "typescript": "^5.9.3"
   },

package/src/browser/lib/ActionBuilder.js

@@ -66,9 +66,13 @@ export default class ActionBuilder {
   #debug = null
   /** @type {symbol|null} */
   #tag = null
+  /** @type {string|null} */
   #hooksFile = null
+  /** @type {string|null} */
   #hooksKind = null
+  /** @type {import("./ActionHooks.js").default|null} */
   #hooks = null
+  /** @type {ActionFunction|null} */
   #done = null
 
   /**
@@ -100,9 +104,10 @@ export default class ActionBuilder {
    * Register an activity that the runner can execute.
    *
    * Overloads:
-   * - do(name, op)
-   * - do(name, kind, pred, opOrWrapper)
-   * - do(name, kind, splitter, rejoiner, opOrWrapper)
+   * - do(name, op) - Simple once-off activity
+   * - do(name, kind, pred) - BREAK/CONTINUE control flow (no op, just predicate)
+   * - do(name, kind, pred, opOrWrapper) - WHILE/UNTIL/IF with predicate and operation
+   * - do(name, kind, splitter, rejoiner, opOrWrapper) - SPLIT with parallel execution
    *
    * @overload
    * @param {string|symbol} name Activity name
@@ -113,9 +118,17 @@ export default class ActionBuilder {
   /**
    * @overload
    * @param {string|symbol} name Activity name
-   * @param {number} kind Kind bitfield from {@link ActivityFlags}.
+   * @param {number} kind ACTIVITY.BREAK or ACTIVITY.CONTINUE flag.
+   * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate to evaluate for control flow.
+   * @returns {ActionBuilder}
+   */
+
+  /**
+   * @overload
+   * @param {string|symbol} name Activity name
+   * @param {number} kind Activity kind (WHILE, UNTIL, or IF) from {@link ActivityFlags}.
    * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate executed before/after the op.
-   * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+   * @param {ActionFunction|ActionBuilder} op Operation or nested builder to execute.
    * @returns {ActionBuilder}
    */
 
@@ -125,7 +138,7 @@ export default class ActionBuilder {
    * @param {number} kind ACTIVITY.SPLIT flag.
    * @param {(context: unknown) => unknown} splitter Splitter function for SPLIT mode.
    * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner Rejoiner function for SPLIT mode.
-   * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+   * @param {ActionFunction|ActionBuilder} op Operation or nested builder to execute.
    * @returns {ActionBuilder}
    */
 
@@ -142,6 +155,7 @@ export default class ActionBuilder {
     // signatures
     // name, [function] => once
     // name, [number,function,function] => some kind of control operation (WHILE/UNTIL)
+    // name, [number,function] => some kind of control operation (BREAK/CONTINUE)
     // name, [number,function,function,function] => SPLIT operation with splitter/rejoiner
     // name, [number,function,ActionBuilder] => some kind of branch
 
@@ -155,6 +169,13 @@ export default class ActionBuilder {
       Valid.type(op, "Function")
 
       Object.assign(activityDefinition, {op, kind})
+    } else if(args.length === 2) {
+      const [kind, pred] = args
+      Valid.type(kind, "Number")
+      Valid.type(pred, "Function")
+      Valid.assert(kind === ACTIVITY.BREAK || kind === ACTIVITY.CONTINUE, "Invalid arguments for BREAK/CONTINUE.")
+
+      Object.assign(activityDefinition, {kind, pred})
     } else if(args.length === 3) {
       const [kind, pred, op] = args
 
@@ -172,7 +193,7 @@ export default class ActionBuilder {
       Valid.type(op, "Function|ActionBuilder")
 
       // Validate that kind is SPLIT
-      if((kind & ACTIVITY.SPLIT) !== ACTIVITY.SPLIT)
+      if(kind !== ACTIVITY.SPLIT)
         throw Sass.new("4-argument form of 'do' is only valid for ACTIVITY.SPLIT")
 
       Object.assign(activityDefinition, {kind, splitter, rejoiner, op})

package/src/browser/lib/ActionRunner.js

@@ -1,4 +1,4 @@
-import {Promised, Data, Sass, Valid} from "@gesslar/toolkit"
+import {Promised, Data, Sass, Valid, Notify} from "@gesslar/toolkit"
 
 import {ACTIVITY} from "./Activity.js"
 import Piper from "./Piper.js"
@@ -36,6 +36,13 @@ export default class ActionRunner extends Piper {
    */
   #debug = () => {}
 
+  /**
+   * Event emitter for cross-runner communication (BREAK/CONTINUE signals).
+   *
+   * @type {typeof Notify}
+   */
+  #notify = Notify
+
   /**
    * Instantiate a runner over an optional action wrapper.
    *
@@ -63,24 +70,29 @@ export default class ActionRunner extends Piper {
   /**
    * Executes the configured action pipeline.
    * Builds the ActionWrapper on first run and caches it for subsequent calls.
-   * Supports WHILE, UNTIL, and SPLIT activity kinds.
+   * Supports WHILE, UNTIL, IF, SPLIT, BREAK, and CONTINUE activity kinds.
    *
    * @param {unknown} context - Seed value passed to the first activity.
+   * @param {import("./ActionWrapper.js").default|null} [parentWrapper] - Parent wrapper for BREAK/CONTINUE signaling.
    * @returns {Promise<unknown>} Final value produced by the pipeline.
    * @throws {Sass} When no activities are registered, conflicting activity kinds are used, or execution fails.
    */
-  async run(context) {
+  async run(context, parentWrapper=null) {
     if(!this.#actionWrapper)
       this.#actionWrapper = await this.#actionBuilder.build()
 
     const actionWrapper = this.#actionWrapper
-    const activities = actionWrapper.activities
+    const activities = Array.from(actionWrapper.activities)
 
     try {
-      for(const activity of activities) {
-        try {
-          // await timeout(500)
+      for(
+        let cursor = 0, max = activities.length;
+        cursor < max && cursor !== -1;
+        cursor++
+      ) {
+        const activity = activities[cursor]
 
+        try {
           const kind = activity.kind
 
           // If we have no kind, then it's just a once.
@@ -88,33 +100,50 @@ export default class ActionRunner extends Piper {
           if(!kind) {
             context = await this.#execute(activity, context)
           } else {
-            // Validate that only one activity kind bit is set
-            // (kind & (kind - 1)) !== 0 means multiple bits are set
-            const multipleBitsSet = (kind & (kind - 1)) !== 0
-            if(multipleBitsSet)
-              throw Sass.new(
-                "For Kathy Griffin's sake! You can't combine activity kinds. " +
-                "Pick one: WHILE, UNTIL, or SPLIT!"
-              )
-
-            const {WHILE,UNTIL,SPLIT} = ACTIVITY
-            const kindWhile = kind & WHILE
-            const kindUntil = kind & UNTIL
-            const kindSplit = kind & SPLIT
-
-            if(kindWhile || kindUntil) {
-              const predicate = activity.pred
-
+            const {UNTIL, WHILE, IF, SPLIT, BREAK, CONTINUE} = ACTIVITY
+            const kindUntil = kind === UNTIL
+            const kindWhile = kind === WHILE
+            const kindIf = kind === IF
+            const kindSplit = kind === SPLIT
+            const kindBreak = kind === BREAK
+            const kindContinue = kind === CONTINUE
+
+            if(kindBreak || kindContinue) {
+              if(!parentWrapper)
+                throw Sass.new(`Invalid use of control flow outside of context.`)
+
+              if(await this.#evalPredicate(activity, context)) {
+                if(kindBreak) {
+                  this.#notify.emit("loop.break", parentWrapper)
+                  break
+                }
+
+                if(kindContinue)
+                  cursor = max
+              }
+            } else if(kindIf) {
+              if(await this.#evalPredicate(activity, context))
+                context = await this.#execute(activity, context)
+            } else if(kindWhile || kindUntil) {
+              // Simple if, no loop, only gainz.
               for(;;) {
-
                 if(kindWhile)
-                  if(!await this.#hasPredicate(activity,predicate,context))
+                  if(!await this.#evalPredicate(activity, context))
                     break
 
-                context = await this.#execute(activity,context)
+                let weWereOnABreak = false
+                const breakReceiver = this.#notify.on("loop.break", wrapper => {
+                  if(wrapper.id === actionWrapper.id) {
+                    weWereOnABreak = true
+                  }
+                })
+                context = await this.#execute(activity, context)
+                breakReceiver()
+                if(weWereOnABreak)
+                  break
 
                 if(kindUntil)
-                  if(await this.#hasPredicate(activity,predicate,context))
+                  if(await this.#evalPredicate(activity, context))
                     break
               }
             } else if(kindSplit) {
@@ -130,8 +159,10 @@ export default class ActionRunner extends Piper {
 
               const original = context
               const splitContexts = await splitter.call(
-                activity.action, context
+                activity.action,
+                context
               )
+
               let settled
 
               if(activity.opKind === "ActionBuilder") {
@@ -145,7 +176,6 @@ export default class ActionRunner extends Piper {
                   debug: this.#debug, name: activity.name
                 })
 
-                // pipe() returns settled results with concurrency control
                 settled = await runner.pipe(splitContexts)
               } else {
                 // For plain functions, process each split context
@@ -171,7 +201,8 @@ export default class ActionRunner extends Piper {
       }
     } finally {
       // Execute done callback if registered - always runs, even on error
-      if(actionWrapper.done) {
+      // Only run for top-level pipelines, not nested builders (inside loops)
+      if(actionWrapper.done && !parentWrapper) {
         try {
           context = await actionWrapper.done.call(
             actionWrapper.action, context
@@ -220,11 +251,11 @@ export default class ActionRunner extends Piper {
       if(parallel) {
         return await runner.pipe(context)
       } else {
-        return await runner.run(context)
+        return await runner.run(context, activity.wrapper)
       }
     } else if(opKind === "Function") {
       try {
-        const result = await activity.run(context)
+        const result = await activity.run(context, activity.wrapper)
 
         if(Data.isType(result, "ActionBuilder")) {
           if(activity.action)
@@ -240,7 +271,7 @@ export default class ActionRunner extends Piper {
           if(parallel) {
             return await runner.pipe(context)
           } else {
-            return await runner.run(context)
+            return await runner.run(context, activity.wrapper)
           }
         } else {
           return result
@@ -256,18 +287,17 @@ export default class ActionRunner extends Piper {
   }
 
   /**
-   * Evaluate the predicate for WHILE/UNTIL activity kinds.
+   * Evaluate the predicate for WHILE/UNTIL/IF/BREAK/CONTINUE activity kinds.
    *
    * @param {import("./Activity.js").default} activity Activity currently executing.
-   * @param {(context: unknown) => boolean|Promise<boolean>} predicate Predicate to evaluate.
    * @param {unknown} context Current pipeline context.
-   * @returns {Promise<boolean>} True when the predicate allows another iteration.
+   * @returns {Promise<boolean>} True when the predicate condition is met.
    * @private
    */
-  async #hasPredicate(activity,predicate,context) {
-    Valid.type(predicate, "Function")
+  async #evalPredicate(activity, context) {
+    Valid.type(activity?.pred, "Function")
 
-    return !!(await predicate.call(activity.action, context))
+    return !!(await activity.pred.call(activity.action, context))
   }
 
   toString() {

package/src/browser/lib/ActionWrapper.js

@@ -24,6 +24,7 @@ export default class ActionWrapper {
    * @type {Map<string|symbol, WrappedActivityConfig>}
    */
   #activities = new Map()
+
   /**
    * Logger invoked for wrapper lifecycle events.
    *
@@ -31,11 +32,14 @@ export default class ActionWrapper {
    */
   #debug = () => {}
 
+  /** @type {import("./ActionHooks.js").default|null} */
   #hooks = null
-
+  /** @type {((context: unknown) => unknown|Promise<unknown>)|null} */
   #done = null
-
+  /** @type {unknown} */
   #action = null
+  /** @type {symbol} */
+  #id = Symbol(performance.now())
 
   /**
    * Create a wrapper from the builder payload.
@@ -47,7 +51,18 @@ export default class ActionWrapper {
     this.#hooks = hooks
     this.#done = doneCallback
     this.#action = action
-    this.#activities = activities
+
+    for(const [key, value] of activities) {
+      this.#activities.set(
+        key,
+        new Activity({
+          ...value,
+          hooks: this.#hooks,
+          wrapper: this
+        })
+      )
+    }
+
     this.#debug(
       "Instantiating ActionWrapper with %o activities.",
       2,
@@ -55,18 +70,23 @@ export default class ActionWrapper {
     )
   }
 
-  *#_activities() {
-    for(const [,activity] of this.#activities)
-      yield new Activity({...activity, hooks: this.#hooks})
+  /**
+   * Unique identifier for this wrapper instance.
+   * Used by BREAK/CONTINUE to match events to the correct loop.
+   *
+   * @returns {symbol} Unique symbol identifier
+   */
+  get id() {
+    return this.#id
   }
 
   /**
    * Iterator over the registered activities.
    *
-   * @returns {ActivityIterator} Lazy iterator yielding Activity instances.
+   * @returns {Iterator<Activity>} Iterator yielding Activity instances.
    */
   get activities() {
-    return this.#_activities()
+    return this.#activities.values()
   }
 
   /**

package/src/browser/lib/Activity.js

@@ -8,14 +8,20 @@ import {Data} from "@gesslar/toolkit"
  *
  * @readonly
  * @enum {number}
- * @property {number} WHILE - Execute activity while predicate returns true (2)
- * @property {number} UNTIL - Execute activity until predicate returns true (4)
- * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution (8)
+ * @property {number} WHILE - Execute activity while predicate returns true 1
+ * @property {number} UNTIL - Execute activity until predicate returns true 2
+ * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution 3
+ * @property {number} IF - Execute activity if predicate returns true 4
+ * @property {number} BREAK - Break out of a WHILE/UNTIL if predicate returns true 5
+ * @property {number} CONTINUE - Returns to the top of a WHILE/UNTIL if predicate returns true 6
  */
 export const ACTIVITY = Object.freeze({
-  WHILE: 1<<1,
-  UNTIL: 1<<2,
-  SPLIT: 1<<3,
+  WHILE: 1,
+  UNTIL: 2,
+  SPLIT: 3,
+  IF: 4,
+  BREAK: 5,
+  CONTINUE: 6,
 })
 
 export default class Activity {
@@ -37,6 +43,10 @@ export default class Activity {
   #rejoiner = null
   /** @type {((context: unknown) => unknown)|null} */
   #splitter = null
+  /** @type {import("./ActionWrapper.js").default|null} */
+  #wrapper = null
+  /** @type {symbol} */
+  #id = Symbol(performance.now())
 
   /**
    * Construct an Activity definition wrapper.
@@ -50,8 +60,9 @@ export default class Activity {
    * @param {ActionHooks} [init.hooks] - Optional hooks instance
    * @param {(context: unknown) => unknown} [init.splitter] - Optional splitter function for SPLIT activities
    * @param {(originalContext: unknown, splitResults: unknown) => unknown} [init.rejoiner] - Optional rejoiner function for SPLIT activities
+   * @param {import("./ActionWrapper.js").default} [init.wrapper] - Optional wrapper containing this activity
    */
-  constructor({action,name,op,kind,pred,hooks,splitter,rejoiner}) {
+  constructor({action,name,op,kind,pred,hooks,splitter,rejoiner,wrapper}) {
     this.#action = action
     this.#hooks = hooks
     this.#kind = kind
@@ -60,6 +71,16 @@ export default class Activity {
     this.#pred = pred
     this.#rejoiner = rejoiner
     this.#splitter = splitter
+    this.#wrapper = wrapper ?? null
+  }
+
+  /**
+   * Unique identifier for this activity instance.
+   *
+   * @returns {symbol} Unique symbol identifier
+   */
+  get id() {
+    return this.#id
   }
 
   /**
@@ -81,7 +102,7 @@ export default class Activity {
   }
 
   /**
-   * The predicate function for WHILE/UNTIL flows.
+   * The predicate function for WHILE/UNTIL/IF flows.
    *
    * @returns {(context: unknown) => boolean|Promise<boolean>|undefined} - Predicate used to continue/stop loops
    */
@@ -143,6 +164,16 @@ export default class Activity {
     return this.#action
   }
 
+  /**
+   * Get the ActionWrapper containing this activity.
+   * Used by BREAK/CONTINUE to signal the parent loop.
+   *
+   * @returns {import("./ActionWrapper.js").default|null} The wrapper or null
+   */
+  get wrapper() {
+    return this.#wrapper ?? null
+  }
+
   /**
    * Execute the activity with before/after hooks.
    *

package/src/types/browser/lib/ActionBuilder.d.ts

@@ -58,9 +58,10 @@ export default class ActionBuilder {
      * Register an activity that the runner can execute.
      *
      * Overloads:
-     * - do(name, op)
-     * - do(name, kind, pred, opOrWrapper)
-     * - do(name, kind, splitter, rejoiner, opOrWrapper)
+     * - do(name, op) - Simple once-off activity
+     * - do(name, kind, pred) - BREAK/CONTINUE control flow (no op, just predicate)
+     * - do(name, kind, pred, opOrWrapper) - WHILE/UNTIL/IF with predicate and operation
+     * - do(name, kind, splitter, rejoiner, opOrWrapper) - SPLIT with parallel execution
      *
      * @overload
      * @param {string|symbol} name Activity name
@@ -71,22 +72,30 @@ export default class ActionBuilder {
     /**
      * @overload
      * @param {string|symbol} name Activity name
-     * @param {number} kind Kind bitfield from {@link ActivityFlags}.
+     * @param {number} kind ACTIVITY.BREAK or ACTIVITY.CONTINUE flag.
+     * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate to evaluate for control flow.
+     * @returns {ActionBuilder}
+     */
+    do(name: string | symbol, kind: number, pred: (context: unknown) => boolean | Promise<boolean>): ActionBuilder;
+    /**
+     * @overload
+     * @param {string|symbol} name Activity name
+     * @param {number} kind Activity kind (WHILE, UNTIL, or IF) from {@link ActivityFlags}.
      * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate executed before/after the op.
-     * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+     * @param {ActionFunction|ActionBuilder} op Operation or nested builder to execute.
      * @returns {ActionBuilder}
      */
-    do(name: string | symbol, kind: number, pred: (context: unknown) => boolean | Promise<boolean>, op: ActionFunction | import("./ActionWrapper.js").default): ActionBuilder;
+    do(name: string | symbol, kind: number, pred: (context: unknown) => boolean | Promise<boolean>, op: ActionFunction | ActionBuilder): ActionBuilder;
     /**
      * @overload
      * @param {string|symbol} name Activity name
      * @param {number} kind ACTIVITY.SPLIT flag.
      * @param {(context: unknown) => unknown} splitter Splitter function for SPLIT mode.
      * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner Rejoiner function for SPLIT mode.
-     * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+     * @param {ActionFunction|ActionBuilder} op Operation or nested builder to execute.
      * @returns {ActionBuilder}
      */
-    do(name: string | symbol, kind: number, splitter: (context: unknown) => unknown, rejoiner: (originalContext: unknown, splitResults: unknown) => unknown, op: ActionFunction | import("./ActionWrapper.js").default): ActionBuilder;
+    do(name: string | symbol, kind: number, splitter: (context: unknown) => unknown, rejoiner: (originalContext: unknown, splitResults: unknown) => unknown, op: ActionFunction | ActionBuilder): ActionBuilder;
     /**
      * Configure hooks to be loaded from a file when the action is built.
      *

package/src/types/browser/lib/ActionBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionBuilder.js"],"names":[],"mappings":"AAMA,kEAAkE;AAClE,uEAAuE;AAEvE;;GAEG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAcE;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAe7B;IAED,yBAEC;;;;;;;;;;;;;;IAUE,SACQ,MAAM,GAAC,MAAM,MACb,cAAc,GACZ,aAAa,CACzB;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,MAC9C,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO,GACjD,aAAa,CACzB;;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,YACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,YAC7B,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,MAC5D,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO,GACjD,aAAa,CACzB;IA0DD;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAYzB;IAED;;;;;;OAMG;IACH,iBAJW,OAAO,kBAAkB,EAAE,OAAO,GAChC,aAAa,CAgBzB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,aAAa,CAczB;IAED;;;;;OAKG;IACH,eAHW,cAAc,GACZ,aAAa,CAOzB;IAeD;;;;;OAKG;IACH,SAFa,OAAO,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CAoBzD;;CAqBF;2BA1Ta,OAAO,mBAAmB,EAAE,OAAO;4BACnC,cAAc,eAAe,EAAE,QAAQ;sBAGxC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;WAKjE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;YAYhC,mBAAmB,GAAC,IAAI;;;;WACxB,OAAO,GAAC,IAAI;;;;UACZ,MAAM,GAAC,MAAM;;;;QACb,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzC,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;6BAI/C,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC"}
+{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionBuilder.js"],"names":[],"mappings":"AAMA,kEAAkE;AAClE,uEAAuE;AAEvE;;GAEG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAkBE;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAe7B;IAED,yBAEC;;;;;;;;;;;;;;;IAWE,SACQ,MAAM,GAAC,MAAM,MACb,cAAc,GACZ,aAAa,CACzB;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAC5C,aAAa,CACzB;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,MAC9C,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,YACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,YAC7B,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,MAC5D,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;IAkED;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAYzB;IAED;;;;;;OAMG;IACH,iBAJW,OAAO,kBAAkB,EAAE,OAAO,GAChC,aAAa,CAgBzB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,aAAa,CAczB;IAED;;;;;OAKG;IACH,eAHW,cAAc,GACZ,aAAa,CAOzB;IAeD;;;;;OAKG;IACH,SAFa,OAAO,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CAqBzD;;CAqBF;2BAhVa,OAAO,mBAAmB,EAAE,OAAO;4BACnC,cAAc,eAAe,EAAE,QAAQ;sBAGxC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;WAKjE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;YAYhC,mBAAmB,GAAC,IAAI;;;;WACxB,OAAO,GAAC,IAAI;;;;UACZ,MAAM,GAAC,MAAM;;;;QACb,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzC,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;6BAI/C,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC"}

package/src/types/browser/lib/ActionRunner.d.ts

@@ -26,13 +26,14 @@ export default class ActionRunner extends Piper {
     /**
      * Executes the configured action pipeline.
      * Builds the ActionWrapper on first run and caches it for subsequent calls.
-     * Supports WHILE, UNTIL, and SPLIT activity kinds.
+     * Supports WHILE, UNTIL, IF, SPLIT, BREAK, and CONTINUE activity kinds.
      *
      * @param {unknown} context - Seed value passed to the first activity.
+     * @param {import("./ActionWrapper.js").default|null} [parentWrapper] - Parent wrapper for BREAK/CONTINUE signaling.
      * @returns {Promise<unknown>} Final value produced by the pipeline.
      * @throws {Sass} When no activities are registered, conflicting activity kinds are used, or execution fails.
      */
-    run(context: unknown): Promise<unknown>;
+    run(context: unknown, parentWrapper?: import("./ActionWrapper.js").default | null): Promise<unknown>;
     #private;
 }
 export type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void;

package/src/types/browser/lib/ActionRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionRunner.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;;GAEG;AAEH;;;GAGG;AACH;;;;;;GAMG;AACH;IAaE;;;;;OAKG;IACH,2BAHW,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,cACzC,mBAAmB,EAkB7B;IAED;;;;;;;;OAQG;IACH,aAJW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CAgH5B;;CA0FF;sBAvQY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;4BAIlE,OAAO,oBAAoB,EAAE,OAAO;;;;;;;kBAP/B,YAAY"}
+{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionRunner.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;;GAEG;AAEH;;;GAGG;AAEH;;;;;;GAMG;AACH;IAoBE;;;;;OAKG;IACH,2BAHW,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,cACzC,mBAAmB,EAkB7B;IAED;;;;;;;;;OASG;IACH,aALW,OAAO,kBACP,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,GACvC,OAAO,CAAC,OAAO,CAAC,CA4I5B;;CAyFF;sBA3SY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;4BAIlE,OAAO,oBAAoB,EAAE,OAAO;;;;;;;kBAP/B,YAAY"}

package/src/types/browser/lib/ActionWrapper.d.ts

@@ -19,22 +19,35 @@ export default class ActionWrapper {
      *
      * @param {{activities: Map<string|symbol, WrappedActivityConfig>, debug: (message: string, level?: number, ...args: Array<unknown>) => void}} init Builder payload containing activities + logger.
      */
-    constructor({ activities, hooks, debug, done: doneCallback }: {
+    constructor({ activities, hooks, debug, done: doneCallback, action }: {
         activities: Map<string | symbol, WrappedActivityConfig>;
         debug: (message: string, level?: number, ...args: Array<unknown>) => void;
     });
+    /**
+     * Unique identifier for this wrapper instance.
+     * Used by BREAK/CONTINUE to match events to the correct loop.
+     *
+     * @returns {symbol} Unique symbol identifier
+     */
+    get id(): symbol;
     /**
      * Iterator over the registered activities.
      *
-     * @returns {ActivityIterator} Lazy iterator yielding Activity instances.
+     * @returns {Iterator<Activity>} Iterator yielding Activity instances.
      */
-    get activities(): ActivityIterator;
+    get activities(): Iterator<Activity>;
     /**
      * Get the done callback if registered.
      *
      * @returns {((context: unknown) => unknown|Promise<unknown>)|null} Done callback or null.
      */
     get done(): ((context: unknown) => unknown | Promise<unknown>) | null;
+    /**
+     * Get the action instance.
+     *
+     * @returns {unknown|null} Action instance or null.
+     */
+    get action(): unknown | null;
     #private;
 }
 export type WrappedActivityConfig = {

package/src/types/browser/lib/ActionWrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionWrapper.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;GAEG;AACH;IAkBE;;;;OAIG;IACH,8DAFW;QAAC,UAAU,EAAE,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;KAAC,EAY5I;IAOD;;;;OAIG;IACH,kBAFa,gBAAgB,CAI5B;IAED;;;;OAIG;IACH,YAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAC,IAAI,CAIjE;;CACF;;;;;UAxEa,MAAM,GAAC,MAAM;;;;QACb,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,aAAa;;;;;;;;sBAElD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;aAC9C,OAAO;;;;uBACG,MAAM,UAAU,MAAM,WAAW,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;+BAInE,OAAO,kBAAkB,EAAE,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;qBAbrD,eAAe"}
+{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionWrapper.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;GAEG;AACH;IAwBE;;;;OAIG;IACH,sEAFW;QAAC,UAAU,EAAE,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;KAAC,EAwB5I;IAED;;;;;OAKG;IACH,UAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,kBAFa,QAAQ,CAAC,QAAQ,CAAC,CAI9B;IAED;;;;OAIG;IACH,YAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAC,IAAI,CAIjE;IAED;;;;OAIG;IACH,cAFa,OAAO,GAAC,IAAI,CAIxB;;CACF;;;;;UAxGa,MAAM,GAAC,MAAM;;;;QACb,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,aAAa;;;;;;;;sBAElD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;aAC9C,OAAO;;;;uBACG,MAAM,UAAU,MAAM,WAAW,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;+BAInE,OAAO,kBAAkB,EAAE,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;qBAbrD,eAAe"}

package/src/types/browser/lib/Activity.d.ts

@@ -9,14 +9,20 @@ export type ACTIVITY = number;
  *
  * @readonly
  * @enum {number}
- * @property {number} WHILE - Execute activity while predicate returns true (2)
- * @property {number} UNTIL - Execute activity until predicate returns true (4)
- * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution (8)
+ * @property {number} WHILE - Execute activity while predicate returns true 1
+ * @property {number} UNTIL - Execute activity until predicate returns true 2
+ * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution 3
+ * @property {number} IF - Execute activity if predicate returns true 4
+ * @property {number} BREAK - Break out of a WHILE/UNTIL if predicate returns true 5
+ * @property {number} CONTINUE - Returns to the top of a WHILE/UNTIL if predicate returns true 6
  */
 export const ACTIVITY: Readonly<{
-    WHILE: number;
-    UNTIL: number;
-    SPLIT: number;
+    WHILE: 1;
+    UNTIL: 2;
+    SPLIT: 3;
+    IF: 4;
+    BREAK: 5;
+    CONTINUE: 6;
 }>;
 export default class Activity {
     /**
@@ -31,8 +37,9 @@ export default class Activity {
      * @param {ActionHooks} [init.hooks] - Optional hooks instance
      * @param {(context: unknown) => unknown} [init.splitter] - Optional splitter function for SPLIT activities
      * @param {(originalContext: unknown, splitResults: unknown) => unknown} [init.rejoiner] - Optional rejoiner function for SPLIT activities
+     * @param {import("./ActionWrapper.js").default} [init.wrapper] - Optional wrapper containing this activity
      */
-    constructor({ action, name, op, kind, pred, hooks, splitter, rejoiner }: {
+    constructor({ action, name, op, kind, pred, hooks, splitter, rejoiner, wrapper }: {
         action: unknown;
         name: string | symbol;
         op: (context: unknown) => unknown | Promise<unknown> | import("./ActionBuilder.js").default;
@@ -41,7 +48,14 @@ export default class Activity {
         hooks?: import("./ActionHooks.js").default | undefined;
         splitter?: ((context: unknown) => unknown) | undefined;
         rejoiner?: ((originalContext: unknown, splitResults: unknown) => unknown) | undefined;
+        wrapper?: import("./ActionWrapper.js").default | undefined;
     });
+    /**
+     * Unique identifier for this activity instance.
+     *
+     * @returns {symbol} Unique symbol identifier
+     */
+    get id(): symbol;
     /**
      * The activity name.
      *
@@ -55,7 +69,7 @@ export default class Activity {
      */
     get kind(): number | null;
     /**
-     * The predicate function for WHILE/UNTIL flows.
+     * The predicate function for WHILE/UNTIL/IF flows.
      *
      * @returns {(context: unknown) => boolean|Promise<boolean>|undefined} - Predicate used to continue/stop loops
      */
@@ -96,6 +110,13 @@ export default class Activity {
      * @returns {unknown} - Bound action instance
      */
     get action(): unknown;
+    /**
+     * Get the ActionWrapper containing this activity.
+     * Used by BREAK/CONTINUE to signal the parent loop.
+     *
+     * @returns {import("./ActionWrapper.js").default|null} The wrapper or null
+     */
+    get wrapper(): import("./ActionWrapper.js").default | null;
     /**
      * Execute the activity with before/after hooks.
      *

package/src/types/browser/lib/Activity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Activity.d.ts","sourceRoot":"","sources":["../../../browser/lib/Activity.js"],"names":[],"mappings":";;;uBASU,MAAM;AAPhB,gEAAgE;AAEhE;;;;;;;;;GASG;AACH;;;;GAIE;AAEF;IAoBE;;;;;;;;;;;;OAYG;IACH,yEATG;QAAsB,MAAM,EAApB,OAAO;QACa,IAAI,EAAxB,MAAM,GAAC,MAAM;QAC6E,EAAE,EAA5F,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO;QACrE,IAAI;QACoC,IAAI,cAAhD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;QAC3B,KAAK;QACa,QAAQ,cAAnC,OAAO,KAAK,OAAO;QACuC,QAAQ,sBAA1D,OAAO,gBAAgB,OAAO,KAAK,OAAO;KACtE,EAUA;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,YAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,SAAS,CAIpE;IAED;;;;OAIG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO,CAI/F;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAIhD;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAI/E;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAHW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CAa5B;IAED;;;;;OAKG;IACH,sBAHW,WAAW,GACT,IAAI,CAOhB;IAED;;;;OAIG;IACH,aAFa,WAAW,GAAC,IAAI,CAI5B;;CACF;0BAvLa,OAAO,kBAAkB,EAAE,OAAO"}
+{"version":3,"file":"Activity.d.ts","sourceRoot":"","sources":["../../../browser/lib/Activity.js"],"names":[],"mappings":";;;uBASU,MAAM;AAPhB,gEAAgE;AAEhE;;;;;;;;;;;;GAYG;AACH;;;;;;;GAOE;AAEF;IAwBE;;;;;;;;;;;;;OAaG;IACH,kFAVG;QAAsB,MAAM,EAApB,OAAO;QACa,IAAI,EAAxB,MAAM,GAAC,MAAM;QAC6E,EAAE,EAA5F,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO;QACrE,IAAI;QACoC,IAAI,cAAhD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;QAC3B,KAAK;QACa,QAAQ,cAAnC,OAAO,KAAK,OAAO;QACuC,QAAQ,sBAA1D,OAAO,gBAAgB,OAAO,KAAK,OAAO;QAChB,OAAO;KAC7D,EAWA;IAED;;;;OAIG;IACH,UAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,YAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,SAAS,CAIpE;IAED;;;;OAIG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO,CAI/F;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAIhD;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAI/E;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAFa,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,CAIrD;IAED;;;;;OAKG;IACH,aAHW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CAa5B;IAED;;;;;OAKG;IACH,sBAHW,WAAW,GACT,IAAI,CAOhB;IAED;;;;OAIG;IACH,aAFa,WAAW,GAAC,IAAI,CAI5B;;CACF;0BAtNa,OAAO,kBAAkB,EAAE,OAAO"}