footprintjs 4.16.0 → 4.17.1

package/CLAUDE.md

@@ -548,6 +548,63 @@ This closes the long-standing gap where `$metric` / `$debug` went to side bags n
 
 Example: [examples/runtime-features/emit/01-custom-events.ts](examples/runtime-features/emit/01-custom-events.ts).
 
+## Detach — Fire-and-Forget Child Flowcharts (`footprintjs/detach`)
+
+Schedule a child chart on a chosen **driver** without blocking the parent stage. Two semantics + two surfaces:
+
+| Method                                | Returns        | Caller                                   |
+|---------------------------------------|----------------|------------------------------------------|
+| `scope.$detachAndJoinLater(d, c, i)`  | `DetachHandle` | Inside a stage (refId = stage's runtimeStageId) |
+| `scope.$detachAndForget(d, c, i)`     | `void`         | Inside a stage (handle discarded)        |
+| `executor.detachAndJoinLater(d, c, i)`| `DetachHandle` | Outside any chart (refId prefix `__executor__`) |
+| `executor.detachAndForget(d, c, i)`   | `void`         | Outside any chart                        |
+
+```ts
+import { microtaskBatchDriver } from 'footprintjs/detach';
+
+flowChart('process', async (scope) => {
+  scope.result = await heavyWork();
+  scope.$detachAndForget(microtaskBatchDriver, telemetryChart, { event: 'done' });
+}, 'process').build();
+```
+
+**Built-in drivers** (more in v4.17.1):
+- `microtaskBatchDriver` — coalesces N detaches into one `queueMicrotask` flush. Default for in-process.
+- `immediateDriver` — runs sync inside `schedule()`. Test fixture / debugging aid.
+
+**Custom drivers**: `createMicrotaskBatchDriver(runChild)` / `createImmediateDriver(runChild)` accept a custom `ChildRunner` so consumers can wrap the executor (e.g., for tracing context). Drivers are **passed explicitly** as the first arg — no library-default to keep the engine free of driver imports.
+
+**Handle**: `{ id, status: 'queued'|'running'|'done'|'failed', result?, error?, wait() }`. NOT Promise-shaped (no `.then()` — defeats fire-and-forget). Status is sync property; `wait()` returns a CACHED Promise on every call.
+
+**Graceful shutdown**: `flushAllDetached({ timeoutMs })` drains every in-flight handle to terminal. Use in SIGTERM handlers / test cleanup. Returns `{ done, failed, pending }` — `pending === 0` means full drain.
+
+**Gotcha**: don't store handles in shared state — `StageContext.setValue` calls `structuredClone`, which drops the handle's class prototype (and `.wait()` method). Keep handles in closure-local variables. The builder-native `addDetachAndJoinLater` enforces this by delivering the handle to a consumer-supplied `onHandle` callback rather than to a shared-state key.
+
+**Builder-native composition** — make detach a labeled chart stage (visible in narrative + visualizations):
+
+```ts
+const handles: DetachHandle[] = [];
+const chart = flowChart('process', processFn, 'process')
+  .addDetachAndForget('telemetry', telemetryChart, {
+    driver: microtaskBatchDriver,
+    inputMapper: (scope) => ({ event: 'processed', orderId: scope.orderId }),
+  })
+  .addDetachAndJoinLater('eval', evalChart, {
+    driver: microtaskBatchDriver,
+    inputMapper: (s) => s.input,
+    onHandle: (h) => handles.push(h),
+  })
+  .addFunction('join', async (scope) => {
+    const settled = await Promise.all(handles.map((h) => h.wait()));
+    scope.results = settled.map((r) => r.result);
+  }, 'join')
+  .build();
+```
+
+Pure sugar over `addFunction` — zero engine changes. For server-side concurrent runs, allocate a fresh `handles` closure per run (factory-build the chart) so handles don't bleed across requests.
+
+Examples: [examples/runtime-features/detach/](examples/runtime-features/detach/) — 7 scenarios (telemetry, fan-out, bare-executor, immediate driver, error handling, status polling, graceful shutdown).
+
 ## Combined Recorder
 
 A `CombinedRecorder` is an observer that hooks into multiple event streams (scope data-flow, control-flow, AND emit — all three channels). One object, one `id`, one `attachCombinedRecorder()` call — the library routes to the right channels via runtime method-shape detection.

package/README.md

@@ -164,6 +164,7 @@ The LLM calls the tool, gets back the decision and causal trace, and explains th
 | **Cancellation** | AbortSignal, timeout, early termination via `scope.$break(reason?)` with optional reason |
 | **Subflow break propagation** | Mount a subflow with `propagateBreak: true` — inner `$break` terminates the parent loop, with drill-down preserved |
 | **Emit channel** | `scope.$emit(name, payload)` — user-authored structured events to `EmitRecorder`, pass-through, zero-allocation when no recorder attached, redactable via `emitPatterns` |
+| **Detach** *(new in 4.17)* | `scope.$detachAndForget(driver, child, input)` and `scope.$detachAndJoinLater(driver, child, input)` — fire-and-forget child flowcharts via the `footprintjs/detach` subpath. Six built-in drivers (microtask / immediate / setImmediate / setTimeout / sendBeacon / workerThread) + custom-driver protocol. Builder-native composition (`addDetachAndForget` / `addDetachAndJoinLater`) makes detach a labeled chart stage. `flushAllDetached()` for graceful shutdown. [Guide →](https://footprintjs.github.io/footPrint/guides/patterns/detach/) |
 
 ---
 

package/dist/detach.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * footprintjs/detach — Fire-and-forget child flowchart execution.
+ *
+ * A library of scheduling drivers that lets you detach work from the
+ * parent stage's hot path. The parent stage returns immediately; the
+ * child runs on whichever driver you pick (microtask, immediate, plus
+ * setImmediate / setTimeout / sendBeacon / worker-thread in v4.17.1+).
+ *
+ * Two shapes:
+ *
+ *   - `detachAndJoinLater(driver, child, input)` — returns a `DetachHandle`
+ *     you can `wait()` on (Promise) or read `.status` from (sync).
+ *   - `detachAndForget(driver, child, input)` — discards the handle.
+ *     Use for fire-and-forget telemetry where the caller never needs to
+ *     know how the child finished.
+ *
+ * Two entry points:
+ *
+ *   - `scope.$detachAndJoinLater(driver, child, input)` — from inside a
+ *     stage. refIds are minted from the calling stage's runtimeStageId
+ *     for diagnostic correlation.
+ *   - `executor.detachAndJoinLater(driver, child, input)` — from outside
+ *     any chart (consumer code). refIds use the synthetic `__executor__`
+ *     prefix.
+ *
+ * @example
+ * ```typescript
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ * import { flowChart, FlowChartExecutor } from 'footprintjs';
+ *
+ * const telemetry = flowChart('telemetry', async (scope) => {
+ *   await fetch('/log', { method: 'POST', body: JSON.stringify(scope.$getArgs()) });
+ * }, 'telemetry').build();
+ *
+ * const main = flowChart('process', async (scope) => {
+ *   scope.result = await heavyWork();
+ *   // Fire telemetry without blocking the parent.
+ *   scope.$detachAndForget(microtaskBatchDriver, telemetry, { event: 'processed' });
+ * }, 'process').build();
+ *
+ * await new FlowChartExecutor(main).run();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flushAllDetached = exports.lookupDetachedHandle = exports.listDetachedIds = exports.detachedCount = exports.defaultRunChild = exports.HandleImpl = exports.createHandle = exports.asImpl = exports.createWorkerThreadDriver = exports.setTimeoutDriver = exports.createSetTimeoutDriver = exports.setImmediateDriver = exports.createSetImmediateDriver = exports.createSendBeaconDriver = exports.microtaskBatchDriver = exports.createMicrotaskBatchDriver = exports.immediateDriver = exports.createImmediateDriver = void 0;
+// ─── Driver factories + default singletons ───────────────────────────
+var immediate_js_1 = require("./lib/detach/drivers/immediate.js");
+Object.defineProperty(exports, "createImmediateDriver", { enumerable: true, get: function () { return immediate_js_1.createImmediateDriver; } });
+Object.defineProperty(exports, "immediateDriver", { enumerable: true, get: function () { return immediate_js_1.immediateDriver; } });
+var microtaskBatch_js_1 = require("./lib/detach/drivers/microtaskBatch.js");
+Object.defineProperty(exports, "createMicrotaskBatchDriver", { enumerable: true, get: function () { return microtaskBatch_js_1.createMicrotaskBatchDriver; } });
+Object.defineProperty(exports, "microtaskBatchDriver", { enumerable: true, get: function () { return microtaskBatch_js_1.microtaskBatchDriver; } });
+var sendBeacon_js_1 = require("./lib/detach/drivers/sendBeacon.js");
+Object.defineProperty(exports, "createSendBeaconDriver", { enumerable: true, get: function () { return sendBeacon_js_1.createSendBeaconDriver; } });
+var setImmediate_js_1 = require("./lib/detach/drivers/setImmediate.js");
+Object.defineProperty(exports, "createSetImmediateDriver", { enumerable: true, get: function () { return setImmediate_js_1.createSetImmediateDriver; } });
+Object.defineProperty(exports, "setImmediateDriver", { enumerable: true, get: function () { return setImmediate_js_1.setImmediateDriver; } });
+var setTimeout_js_1 = require("./lib/detach/drivers/setTimeout.js");
+Object.defineProperty(exports, "createSetTimeoutDriver", { enumerable: true, get: function () { return setTimeout_js_1.createSetTimeoutDriver; } });
+Object.defineProperty(exports, "setTimeoutDriver", { enumerable: true, get: function () { return setTimeout_js_1.setTimeoutDriver; } });
+var workerThread_js_1 = require("./lib/detach/drivers/workerThread.js");
+Object.defineProperty(exports, "createWorkerThreadDriver", { enumerable: true, get: function () { return workerThread_js_1.createWorkerThreadDriver; } });
+// ─── Handle factory + helpers (for custom-driver authors) ────────────
+var handle_js_1 = require("./lib/detach/handle.js");
+Object.defineProperty(exports, "asImpl", { enumerable: true, get: function () { return handle_js_1.asImpl; } });
+Object.defineProperty(exports, "createHandle", { enumerable: true, get: function () { return handle_js_1.createHandle; } });
+Object.defineProperty(exports, "HandleImpl", { enumerable: true, get: function () { return handle_js_1.HandleImpl; } });
+var runChild_js_1 = require("./lib/detach/runChild.js");
+Object.defineProperty(exports, "defaultRunChild", { enumerable: true, get: function () { return runChild_js_1.defaultRunChild; } });
+// ─── Registry — diagnostic surface ───────────────────────────────────
+var registry_js_1 = require("./lib/detach/registry.js");
+Object.defineProperty(exports, "detachedCount", { enumerable: true, get: function () { return registry_js_1.size; } });
+Object.defineProperty(exports, "listDetachedIds", { enumerable: true, get: function () { return registry_js_1.ids; } });
+Object.defineProperty(exports, "lookupDetachedHandle", { enumerable: true, get: function () { return registry_js_1.lookup; } });
+var flush_js_1 = require("./lib/detach/flush.js");
+Object.defineProperty(exports, "flushAllDetached", { enumerable: true, get: function () { return flush_js_1.flushAllDetached; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGV0YWNoLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2RldGFjaC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQTBDRzs7O0FBV0gsd0VBQXdFO0FBQ3hFLGtFQUEyRjtBQUFsRixxSEFBQSxxQkFBcUIsT0FBQTtBQUFFLCtHQUFBLGVBQWUsT0FBQTtBQUMvQyw0RUFBMEc7QUFBakcsK0hBQUEsMEJBQTBCLE9BQUE7QUFBRSx5SEFBQSxvQkFBb0IsT0FBQTtBQUV6RCxvRUFBNEU7QUFBbkUsdUhBQUEsc0JBQXNCLE9BQUE7QUFDL0Isd0VBQW9HO0FBQTNGLDJIQUFBLHdCQUF3QixPQUFBO0FBQUUscUhBQUEsa0JBQWtCLE9BQUE7QUFFckQsb0VBQThGO0FBQXJGLHVIQUFBLHNCQUFzQixPQUFBO0FBQUUsaUhBQUEsZ0JBQWdCLE9BQUE7QUFFakQsd0VBQWdGO0FBQXZFLDJIQUFBLHdCQUF3QixPQUFBO0FBRWpDLHdFQUF3RTtBQUN4RSxvREFBMEU7QUFBakUsbUdBQUEsTUFBTSxPQUFBO0FBQUUseUdBQUEsWUFBWSxPQUFBO0FBQUUsdUdBQUEsVUFBVSxPQUFBO0FBRXpDLHdEQUEyRDtBQUFsRCw4R0FBQSxlQUFlLE9BQUE7QUFFeEIsd0VBQXdFO0FBQ3hFLHdEQUlrQztBQUhoQyw0R0FBQSxJQUFJLE9BQWlCO0FBQ3JCLDhHQUFBLEdBQUcsT0FBbUI7QUFDdEIsbUhBQUEsTUFBTSxPQUF3QjtBQUtoQyxrREFBeUQ7QUFBaEQsNEdBQUEsZ0JBQWdCLE9BQUEiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIGZvb3RwcmludGpzL2RldGFjaCDigJQgRmlyZS1hbmQtZm9yZ2V0IGNoaWxkIGZsb3djaGFydCBleGVjdXRpb24uXG4gKlxuICogQSBsaWJyYXJ5IG9mIHNjaGVkdWxpbmcgZHJpdmVycyB0aGF0IGxldHMgeW91IGRldGFjaCB3b3JrIGZyb20gdGhlXG4gKiBwYXJlbnQgc3RhZ2UncyBob3QgcGF0aC4gVGhlIHBhcmVudCBzdGFnZSByZXR1cm5zIGltbWVkaWF0ZWx5OyB0aGVcbiAqIGNoaWxkIHJ1bnMgb24gd2hpY2hldmVyIGRyaXZlciB5b3UgcGljayAobWljcm90YXNrLCBpbW1lZGlhdGUsIHBsdXNcbiAqIHNldEltbWVkaWF0ZSAvIHNldFRpbWVvdXQgLyBzZW5kQmVhY29uIC8gd29ya2VyLXRocmVhZCBpbiB2NC4xNy4xKykuXG4gKlxuICogVHdvIHNoYXBlczpcbiAqXG4gKiAgIC0gYGRldGFjaEFuZEpvaW5MYXRlcihkcml2ZXIsIGNoaWxkLCBpbnB1dClgIOKAlCByZXR1cm5zIGEgYERldGFjaEhhbmRsZWBcbiAqICAgICB5b3UgY2FuIGB3YWl0KClgIG9uIChQcm9taXNlKSBvciByZWFkIGAuc3RhdHVzYCBmcm9tIChzeW5jKS5cbiAqICAgLSBgZGV0YWNoQW5kRm9yZ2V0KGRyaXZlciwgY2hpbGQsIGlucHV0KWAg4oCUIGRpc2NhcmRzIHRoZSBoYW5kbGUuXG4gKiAgICAgVXNlIGZvciBmaXJlLWFuZC1mb3JnZXQgdGVsZW1ldHJ5IHdoZXJlIHRoZSBjYWxsZXIgbmV2ZXIgbmVlZHMgdG9cbiAqICAgICBrbm93IGhvdyB0aGUgY2hpbGQgZmluaXNoZWQuXG4gKlxuICogVHdvIGVudHJ5IHBvaW50czpcbiAqXG4gKiAgIC0gYHNjb3BlLiRkZXRhY2hBbmRKb2luTGF0ZXIoZHJpdmVyLCBjaGlsZCwgaW5wdXQpYCDigJQgZnJvbSBpbnNpZGUgYVxuICogICAgIHN0YWdlLiByZWZJZHMgYXJlIG1pbnRlZCBmcm9tIHRoZSBjYWxsaW5nIHN0YWdlJ3MgcnVudGltZVN0YWdlSWRcbiAqICAgICBmb3IgZGlhZ25vc3RpYyBjb3JyZWxhdGlvbi5cbiAqICAgLSBgZXhlY3V0b3IuZGV0YWNoQW5kSm9pbkxhdGVyKGRyaXZlciwgY2hpbGQsIGlucHV0KWAg4oCUIGZyb20gb3V0c2lkZVxuICogICAgIGFueSBjaGFydCAoY29uc3VtZXIgY29kZSkuIHJlZklkcyB1c2UgdGhlIHN5bnRoZXRpYyBgX19leGVjdXRvcl9fYFxuICogICAgIHByZWZpeC5cbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHlwZXNjcmlwdFxuICogaW1wb3J0IHsgbWljcm90YXNrQmF0Y2hEcml2ZXIgfSBmcm9tICdmb290cHJpbnRqcy9kZXRhY2gnO1xuICogaW1wb3J0IHsgZmxvd0NoYXJ0LCBGbG93Q2hhcnRFeGVjdXRvciB9IGZyb20gJ2Zvb3RwcmludGpzJztcbiAqXG4gKiBjb25zdCB0ZWxlbWV0cnkgPSBmbG93Q2hhcnQoJ3RlbGVtZXRyeScsIGFzeW5jIChzY29wZSkgPT4ge1xuICogICBhd2FpdCBmZXRjaCgnL2xvZycsIHsgbWV0aG9kOiAnUE9TVCcsIGJvZHk6IEpTT04uc3RyaW5naWZ5KHNjb3BlLiRnZXRBcmdzKCkpIH0pO1xuICogfSwgJ3RlbGVtZXRyeScpLmJ1aWxkKCk7XG4gKlxuICogY29uc3QgbWFpbiA9IGZsb3dDaGFydCgncHJvY2VzcycsIGFzeW5jIChzY29wZSkgPT4ge1xuICogICBzY29wZS5yZXN1bHQgPSBhd2FpdCBoZWF2eVdvcmsoKTtcbiAqICAgLy8gRmlyZSB0ZWxlbWV0cnkgd2l0aG91dCBibG9ja2luZyB0aGUgcGFyZW50LlxuICogICBzY29wZS4kZGV0YWNoQW5kRm9yZ2V0KG1pY3JvdGFza0JhdGNoRHJpdmVyLCB0ZWxlbWV0cnksIHsgZXZlbnQ6ICdwcm9jZXNzZWQnIH0pO1xuICogfSwgJ3Byb2Nlc3MnKS5idWlsZCgpO1xuICpcbiAqIGF3YWl0IG5ldyBGbG93Q2hhcnRFeGVjdXRvcihtYWluKS5ydW4oKTtcbiAqIGBgYFxuICovXG5cbi8vIOKUgOKUgOKUgCBUeXBlcyDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbmV4cG9ydCB0eXBlIHtcbiAgRGV0YWNoRHJpdmVyLFxuICBEZXRhY2hIYW5kbGUsXG4gIERldGFjaFBvbGxSZXN1bHQsXG4gIERldGFjaFdhaXRSZXN1bHQsXG4gIERyaXZlckNhcGFiaWxpdGllcyxcbn0gZnJvbSAnLi9saWIvZGV0YWNoL3R5cGVzLmpzJztcblxuLy8g4pSA4pSA4pSAIERyaXZlciBmYWN0b3JpZXMgKyBkZWZhdWx0IHNpbmdsZXRvbnMg4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG5leHBvcnQgeyBjcmVhdGVJbW1lZGlhdGVEcml2ZXIsIGltbWVkaWF0ZURyaXZlciB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL2ltbWVkaWF0ZS5qcyc7XG5leHBvcnQgeyBjcmVhdGVNaWNyb3Rhc2tCYXRjaERyaXZlciwgbWljcm90YXNrQmF0Y2hEcml2ZXIgfSBmcm9tICcuL2xpYi9kZXRhY2gvZHJpdmVycy9taWNyb3Rhc2tCYXRjaC5qcyc7XG5leHBvcnQgdHlwZSB7IFNlbmRCZWFjb25Ecml2ZXJPcHRpb25zIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvc2VuZEJlYWNvbi5qcyc7XG5leHBvcnQgeyBjcmVhdGVTZW5kQmVhY29uRHJpdmVyIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvc2VuZEJlYWNvbi5qcyc7XG5leHBvcnQgeyBjcmVhdGVTZXRJbW1lZGlhdGVEcml2ZXIsIHNldEltbWVkaWF0ZURyaXZlciB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL3NldEltbWVkaWF0ZS5qcyc7XG5leHBvcnQgdHlwZSB7IFNldFRpbWVvdXREcml2ZXJPcHRpb25zIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvc2V0VGltZW91dC5qcyc7XG5leHBvcnQgeyBjcmVhdGVTZXRUaW1lb3V0RHJpdmVyLCBzZXRUaW1lb3V0RHJpdmVyIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvc2V0VGltZW91dC5qcyc7XG5leHBvcnQgdHlwZSB7IFdvcmtlclRocmVhZERyaXZlck9wdGlvbnMgfSBmcm9tICcuL2xpYi9kZXRhY2gvZHJpdmVycy93b3JrZXJUaHJlYWQuanMnO1xuZXhwb3J0IHsgY3JlYXRlV29ya2VyVGhyZWFkRHJpdmVyIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvd29ya2VyVGhyZWFkLmpzJztcblxuLy8g4pSA4pSA4pSAIEhhbmRsZSBmYWN0b3J5ICsgaGVscGVycyAoZm9yIGN1c3RvbS1kcml2ZXIgYXV0aG9ycykg4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG5leHBvcnQgeyBhc0ltcGwsIGNyZWF0ZUhhbmRsZSwgSGFuZGxlSW1wbCB9IGZyb20gJy4vbGliL2RldGFjaC9oYW5kbGUuanMnO1xuZXhwb3J0IHR5cGUgeyBDaGlsZFJ1bm5lciB9IGZyb20gJy4vbGliL2RldGFjaC9ydW5DaGlsZC5qcyc7XG5leHBvcnQgeyBkZWZhdWx0UnVuQ2hpbGQgfSBmcm9tICcuL2xpYi9kZXRhY2gvcnVuQ2hpbGQuanMnO1xuXG4vLyDilIDilIDilIAgUmVnaXN0cnkg4oCUIGRpYWdub3N0aWMgc3VyZmFjZSDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbmV4cG9ydCB7XG4gIHNpemUgYXMgZGV0YWNoZWRDb3VudCxcbiAgaWRzIGFzIGxpc3REZXRhY2hlZElkcyxcbiAgbG9va3VwIGFzIGxvb2t1cERldGFjaGVkSGFuZGxlLFxufSBmcm9tICcuL2xpYi9kZXRhY2gvcmVnaXN0cnkuanMnO1xuXG4vLyDilIDilIDilIAgRmx1c2gg4oCUIGdyYWNlZnVsLXNodXRkb3duIGhlbHBlciDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbmV4cG9ydCB0eXBlIHsgRmx1c2hPcHRpb25zLCBGbHVzaFJlc3VsdCB9IGZyb20gJy4vbGliL2RldGFjaC9mbHVzaC5qcyc7XG5leHBvcnQgeyBmbHVzaEFsbERldGFjaGVkIH0gZnJvbSAnLi9saWIvZGV0YWNoL2ZsdXNoLmpzJztcbiJdfQ==

package/dist/esm/detach.js

@@ -0,0 +1,57 @@
+/**
+ * footprintjs/detach — Fire-and-forget child flowchart execution.
+ *
+ * A library of scheduling drivers that lets you detach work from the
+ * parent stage's hot path. The parent stage returns immediately; the
+ * child runs on whichever driver you pick (microtask, immediate, plus
+ * setImmediate / setTimeout / sendBeacon / worker-thread in v4.17.1+).
+ *
+ * Two shapes:
+ *
+ *   - `detachAndJoinLater(driver, child, input)` — returns a `DetachHandle`
+ *     you can `wait()` on (Promise) or read `.status` from (sync).
+ *   - `detachAndForget(driver, child, input)` — discards the handle.
+ *     Use for fire-and-forget telemetry where the caller never needs to
+ *     know how the child finished.
+ *
+ * Two entry points:
+ *
+ *   - `scope.$detachAndJoinLater(driver, child, input)` — from inside a
+ *     stage. refIds are minted from the calling stage's runtimeStageId
+ *     for diagnostic correlation.
+ *   - `executor.detachAndJoinLater(driver, child, input)` — from outside
+ *     any chart (consumer code). refIds use the synthetic `__executor__`
+ *     prefix.
+ *
+ * @example
+ * ```typescript
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ * import { flowChart, FlowChartExecutor } from 'footprintjs';
+ *
+ * const telemetry = flowChart('telemetry', async (scope) => {
+ *   await fetch('/log', { method: 'POST', body: JSON.stringify(scope.$getArgs()) });
+ * }, 'telemetry').build();
+ *
+ * const main = flowChart('process', async (scope) => {
+ *   scope.result = await heavyWork();
+ *   // Fire telemetry without blocking the parent.
+ *   scope.$detachAndForget(microtaskBatchDriver, telemetry, { event: 'processed' });
+ * }, 'process').build();
+ *
+ * await new FlowChartExecutor(main).run();
+ * ```
+ */
+// ─── Driver factories + default singletons ───────────────────────────
+export { createImmediateDriver, immediateDriver } from './lib/detach/drivers/immediate.js';
+export { createMicrotaskBatchDriver, microtaskBatchDriver } from './lib/detach/drivers/microtaskBatch.js';
+export { createSendBeaconDriver } from './lib/detach/drivers/sendBeacon.js';
+export { createSetImmediateDriver, setImmediateDriver } from './lib/detach/drivers/setImmediate.js';
+export { createSetTimeoutDriver, setTimeoutDriver } from './lib/detach/drivers/setTimeout.js';
+export { createWorkerThreadDriver } from './lib/detach/drivers/workerThread.js';
+// ─── Handle factory + helpers (for custom-driver authors) ────────────
+export { asImpl, createHandle, HandleImpl } from './lib/detach/handle.js';
+export { defaultRunChild } from './lib/detach/runChild.js';
+// ─── Registry — diagnostic surface ───────────────────────────────────
+export { size as detachedCount, ids as listDetachedIds, lookup as lookupDetachedHandle, } from './lib/detach/registry.js';
+export { flushAllDetached } from './lib/detach/flush.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGV0YWNoLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2RldGFjaC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBMENHO0FBV0gsd0VBQXdFO0FBQ3hFLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxlQUFlLEVBQUUsTUFBTSxtQ0FBbUMsQ0FBQztBQUMzRixPQUFPLEVBQUUsMEJBQTBCLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSx3Q0FBd0MsQ0FBQztBQUUxRyxPQUFPLEVBQUUsc0JBQXNCLEVBQUUsTUFBTSxvQ0FBb0MsQ0FBQztBQUM1RSxPQUFPLEVBQUUsd0JBQXdCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxzQ0FBc0MsQ0FBQztBQUVwRyxPQUFPLEVBQUUsc0JBQXNCLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxvQ0FBb0MsQ0FBQztBQUU5RixPQUFPLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSxzQ0FBc0MsQ0FBQztBQUVoRix3RUFBd0U7QUFDeEUsT0FBTyxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsVUFBVSxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFMUUsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBRTNELHdFQUF3RTtBQUN4RSxPQUFPLEVBQ0wsSUFBSSxJQUFJLGFBQWEsRUFDckIsR0FBRyxJQUFJLGVBQWUsRUFDdEIsTUFBTSxJQUFJLG9CQUFvQixHQUMvQixNQUFNLDBCQUEwQixDQUFDO0FBSWxDLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHVCQUF1QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBmb290cHJpbnRqcy9kZXRhY2gg4oCUIEZpcmUtYW5kLWZvcmdldCBjaGlsZCBmbG93Y2hhcnQgZXhlY3V0aW9uLlxuICpcbiAqIEEgbGlicmFyeSBvZiBzY2hlZHVsaW5nIGRyaXZlcnMgdGhhdCBsZXRzIHlvdSBkZXRhY2ggd29yayBmcm9tIHRoZVxuICogcGFyZW50IHN0YWdlJ3MgaG90IHBhdGguIFRoZSBwYXJlbnQgc3RhZ2UgcmV0dXJucyBpbW1lZGlhdGVseTsgdGhlXG4gKiBjaGlsZCBydW5zIG9uIHdoaWNoZXZlciBkcml2ZXIgeW91IHBpY2sgKG1pY3JvdGFzaywgaW1tZWRpYXRlLCBwbHVzXG4gKiBzZXRJbW1lZGlhdGUgLyBzZXRUaW1lb3V0IC8gc2VuZEJlYWNvbiAvIHdvcmtlci10aHJlYWQgaW4gdjQuMTcuMSspLlxuICpcbiAqIFR3byBzaGFwZXM6XG4gKlxuICogICAtIGBkZXRhY2hBbmRKb2luTGF0ZXIoZHJpdmVyLCBjaGlsZCwgaW5wdXQpYCDigJQgcmV0dXJucyBhIGBEZXRhY2hIYW5kbGVgXG4gKiAgICAgeW91IGNhbiBgd2FpdCgpYCBvbiAoUHJvbWlzZSkgb3IgcmVhZCBgLnN0YXR1c2AgZnJvbSAoc3luYykuXG4gKiAgIC0gYGRldGFjaEFuZEZvcmdldChkcml2ZXIsIGNoaWxkLCBpbnB1dClgIOKAlCBkaXNjYXJkcyB0aGUgaGFuZGxlLlxuICogICAgIFVzZSBmb3IgZmlyZS1hbmQtZm9yZ2V0IHRlbGVtZXRyeSB3aGVyZSB0aGUgY2FsbGVyIG5ldmVyIG5lZWRzIHRvXG4gKiAgICAga25vdyBob3cgdGhlIGNoaWxkIGZpbmlzaGVkLlxuICpcbiAqIFR3byBlbnRyeSBwb2ludHM6XG4gKlxuICogICAtIGBzY29wZS4kZGV0YWNoQW5kSm9pbkxhdGVyKGRyaXZlciwgY2hpbGQsIGlucHV0KWAg4oCUIGZyb20gaW5zaWRlIGFcbiAqICAgICBzdGFnZS4gcmVmSWRzIGFyZSBtaW50ZWQgZnJvbSB0aGUgY2FsbGluZyBzdGFnZSdzIHJ1bnRpbWVTdGFnZUlkXG4gKiAgICAgZm9yIGRpYWdub3N0aWMgY29ycmVsYXRpb24uXG4gKiAgIC0gYGV4ZWN1dG9yLmRldGFjaEFuZEpvaW5MYXRlcihkcml2ZXIsIGNoaWxkLCBpbnB1dClgIOKAlCBmcm9tIG91dHNpZGVcbiAqICAgICBhbnkgY2hhcnQgKGNvbnN1bWVyIGNvZGUpLiByZWZJZHMgdXNlIHRoZSBzeW50aGV0aWMgYF9fZXhlY3V0b3JfX2BcbiAqICAgICBwcmVmaXguXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IG1pY3JvdGFza0JhdGNoRHJpdmVyIH0gZnJvbSAnZm9vdHByaW50anMvZGV0YWNoJztcbiAqIGltcG9ydCB7IGZsb3dDaGFydCwgRmxvd0NoYXJ0RXhlY3V0b3IgfSBmcm9tICdmb290cHJpbnRqcyc7XG4gKlxuICogY29uc3QgdGVsZW1ldHJ5ID0gZmxvd0NoYXJ0KCd0ZWxlbWV0cnknLCBhc3luYyAoc2NvcGUpID0+IHtcbiAqICAgYXdhaXQgZmV0Y2goJy9sb2cnLCB7IG1ldGhvZDogJ1BPU1QnLCBib2R5OiBKU09OLnN0cmluZ2lmeShzY29wZS4kZ2V0QXJncygpKSB9KTtcbiAqIH0sICd0ZWxlbWV0cnknKS5idWlsZCgpO1xuICpcbiAqIGNvbnN0IG1haW4gPSBmbG93Q2hhcnQoJ3Byb2Nlc3MnLCBhc3luYyAoc2NvcGUpID0+IHtcbiAqICAgc2NvcGUucmVzdWx0ID0gYXdhaXQgaGVhdnlXb3JrKCk7XG4gKiAgIC8vIEZpcmUgdGVsZW1ldHJ5IHdpdGhvdXQgYmxvY2tpbmcgdGhlIHBhcmVudC5cbiAqICAgc2NvcGUuJGRldGFjaEFuZEZvcmdldChtaWNyb3Rhc2tCYXRjaERyaXZlciwgdGVsZW1ldHJ5LCB7IGV2ZW50OiAncHJvY2Vzc2VkJyB9KTtcbiAqIH0sICdwcm9jZXNzJykuYnVpbGQoKTtcbiAqXG4gKiBhd2FpdCBuZXcgRmxvd0NoYXJ0RXhlY3V0b3IobWFpbikucnVuKCk7XG4gKiBgYGBcbiAqL1xuXG4vLyDilIDilIDilIAgVHlwZXMg4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG5leHBvcnQgdHlwZSB7XG4gIERldGFjaERyaXZlcixcbiAgRGV0YWNoSGFuZGxlLFxuICBEZXRhY2hQb2xsUmVzdWx0LFxuICBEZXRhY2hXYWl0UmVzdWx0LFxuICBEcml2ZXJDYXBhYmlsaXRpZXMsXG59IGZyb20gJy4vbGliL2RldGFjaC90eXBlcy5qcyc7XG5cbi8vIOKUgOKUgOKUgCBEcml2ZXIgZmFjdG9yaWVzICsgZGVmYXVsdCBzaW5nbGV0b25zIOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgFxuZXhwb3J0IHsgY3JlYXRlSW1tZWRpYXRlRHJpdmVyLCBpbW1lZGlhdGVEcml2ZXIgfSBmcm9tICcuL2xpYi9kZXRhY2gvZHJpdmVycy9pbW1lZGlhdGUuanMnO1xuZXhwb3J0IHsgY3JlYXRlTWljcm90YXNrQmF0Y2hEcml2ZXIsIG1pY3JvdGFza0JhdGNoRHJpdmVyIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvbWljcm90YXNrQmF0Y2guanMnO1xuZXhwb3J0IHR5cGUgeyBTZW5kQmVhY29uRHJpdmVyT3B0aW9ucyB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL3NlbmRCZWFjb24uanMnO1xuZXhwb3J0IHsgY3JlYXRlU2VuZEJlYWNvbkRyaXZlciB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL3NlbmRCZWFjb24uanMnO1xuZXhwb3J0IHsgY3JlYXRlU2V0SW1tZWRpYXRlRHJpdmVyLCBzZXRJbW1lZGlhdGVEcml2ZXIgfSBmcm9tICcuL2xpYi9kZXRhY2gvZHJpdmVycy9zZXRJbW1lZGlhdGUuanMnO1xuZXhwb3J0IHR5cGUgeyBTZXRUaW1lb3V0RHJpdmVyT3B0aW9ucyB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL3NldFRpbWVvdXQuanMnO1xuZXhwb3J0IHsgY3JlYXRlU2V0VGltZW91dERyaXZlciwgc2V0VGltZW91dERyaXZlciB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL3NldFRpbWVvdXQuanMnO1xuZXhwb3J0IHR5cGUgeyBXb3JrZXJUaHJlYWREcml2ZXJPcHRpb25zIH0gZnJvbSAnLi9saWIvZGV0YWNoL2RyaXZlcnMvd29ya2VyVGhyZWFkLmpzJztcbmV4cG9ydCB7IGNyZWF0ZVdvcmtlclRocmVhZERyaXZlciB9IGZyb20gJy4vbGliL2RldGFjaC9kcml2ZXJzL3dvcmtlclRocmVhZC5qcyc7XG5cbi8vIOKUgOKUgOKUgCBIYW5kbGUgZmFjdG9yeSArIGhlbHBlcnMgKGZvciBjdXN0b20tZHJpdmVyIGF1dGhvcnMpIOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgOKUgFxuZXhwb3J0IHsgYXNJbXBsLCBjcmVhdGVIYW5kbGUsIEhhbmRsZUltcGwgfSBmcm9tICcuL2xpYi9kZXRhY2gvaGFuZGxlLmpzJztcbmV4cG9ydCB0eXBlIHsgQ2hpbGRSdW5uZXIgfSBmcm9tICcuL2xpYi9kZXRhY2gvcnVuQ2hpbGQuanMnO1xuZXhwb3J0IHsgZGVmYXVsdFJ1bkNoaWxkIH0gZnJvbSAnLi9saWIvZGV0YWNoL3J1bkNoaWxkLmpzJztcblxuLy8g4pSA4pSA4pSAIFJlZ2lzdHJ5IOKAlCBkaWFnbm9zdGljIHN1cmZhY2Ug4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG5leHBvcnQge1xuICBzaXplIGFzIGRldGFjaGVkQ291bnQsXG4gIGlkcyBhcyBsaXN0RGV0YWNoZWRJZHMsXG4gIGxvb2t1cCBhcyBsb29rdXBEZXRhY2hlZEhhbmRsZSxcbn0gZnJvbSAnLi9saWIvZGV0YWNoL3JlZ2lzdHJ5LmpzJztcblxuLy8g4pSA4pSA4pSAIEZsdXNoIOKAlCBncmFjZWZ1bC1zaHV0ZG93biBoZWxwZXIg4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG5leHBvcnQgdHlwZSB7IEZsdXNoT3B0aW9ucywgRmx1c2hSZXN1bHQgfSBmcm9tICcuL2xpYi9kZXRhY2gvZmx1c2guanMnO1xuZXhwb3J0IHsgZmx1c2hBbGxEZXRhY2hlZCB9IGZyb20gJy4vbGliL2RldGFjaC9mbHVzaC5qcyc7XG4iXX0=