@mantaq/sugar 0.4.0 → 2.0.0

package/README.md

@@ -32,7 +32,10 @@ const machine = new Actor({
   clock,
   setup: (m) => {
     m.on(s.idle, e.fetch, () => ({ state: s.loading }));
-    m.effect(s.loading, (input) => withTimeout(2000, input, () => e.resolve.create()));
+    m.effect(s.loading, {
+      name: "startFetchTimeout",
+      fn: (input) => withTimeout(2000, input, () => e.resolve.create()),
+    });
     m.on(s.loading, e.resolve, () => ({ state: s.success }));
     m.on(s.loading, e.fail, () => ({ state: s.error }));
   },
@@ -172,7 +175,7 @@ if (matches(actor, "idle") || matches(actor, "loading")) {
 // Breaks when hierarchy changes, verbose, error-prone
 ```
 
-`tag()` searches recursively through parallel regions and nested hierarchies — works regardless of depth.
+`tag()` searches recursively through parallel regions and nested hierarchies. Works regardless of depth.
 
 ### ActorMap patterns
 
@@ -206,7 +209,7 @@ map.spawn("child1", () => createChild());
 map.spawn("child1", () => createChild()); // warns, aborts the previous child, replaces
 ```
 
-`ensure()` is idempotent — safe to call repeatedly. `spawn()` always replaces.
+`ensure()` is idempotent. Safe to call repeatedly. `spawn()` always replaces.
 
 ### Effect utilities: `withPromise` vs manual handling
 
@@ -279,7 +282,7 @@ if (snap && isIn(snap, "active")) {
 }
 ```
 
-**`ensure(key, factory)`** — spawn only if key missing:
+**`ensure(key, factory)`**. Spawn only if key missing:
 
 ```ts
 map.ensure("child1", () => childActor); // no-op if exists
@@ -310,7 +313,7 @@ Works with `ActorMap` or any object implementing `{ keys(): string[]; send(key,
 ### `onOutput(actor, handler)`
 
 Route an actor's emitted outputs to a handler. `regions` auto-wire child
-outputs into the parent; ActorMap children do not — this is the public
+outputs into the parent; ActorMap children do not. This is the public
 wrapper for that wiring seam, no internal import needed:
 
 ```ts
@@ -373,7 +376,7 @@ e.click.is(emittedEvent); // boolean
 
 ### `withPromise(promise, signal, emit, events)`
 
-Bridge a promise into actor events. Emits `success` on resolve, `error` on reject. Respects `AbortSignal` — skips emit if aborted before settlement.
+Bridge a promise into actor events. Emits `success` on resolve, `error` on reject. Respects `AbortSignal`. Skips emit if aborted before settlement.
 
 ```ts
 import { withPromise } from "@mantaq/sugar";
@@ -434,7 +437,7 @@ const busy = tag(s.idle, s.loading);
 busy.has(actor.snapshot()); // recursive
 ```
 
-No migration needed. Sugar wraps core — use both side by side.
+No migration needed. Sugar wraps core. Use both side by side.
 
 ## License
 

package/dist/index.d.mts

@@ -1,48 +1,66 @@
 import { Actor, ActorBuilder, ActorOptions, AnyActor, AnyEventRef, AnyStateRef, Clock, EffectInput, EventRef, InitialState, InternalEvent, Snapshot, StateRef } from "@mantaq/core";
-//#region src/actors/matches.d.ts
-declare function matches(actor: {
+interface MatchTarget {
   snapshot(): Snapshot;
-}, pattern: string): boolean;
-//#endregion
-//#region src/transitions/broadcast.d.ts
+}
+/**
+ * True when the actor's snapshot matches the dotted pattern. Accepts the
+ * pattern as one dotted string or as separate segments. A segment containing
+ * dots matches states whose own name contains dots.
+ */
+export declare function matches(actor: MatchTarget, ...pattern: [pattern: string]): boolean;
+/**
+ * Plain event shape sugar helpers accept next to core event refs.
+ */
 type EventLike = {
   type: string;
   payload?: unknown;
 };
+/**
+ * Anything sendable through sugar helpers — a core ref or a plain object.
+ */
 type SendableEvent = AnyEventRef | EventLike;
 interface SendableMap<T extends SendableEvent = SendableEvent> {
   keys(): string[];
-  send(key: string, event: T): void;
+  send(key: string, ...events: [event: T]): void;
 }
-declare function broadcast<const T extends SendableEvent>(map: SendableMap<T>, event: T): void;
-//#endregion
-//#region src/actors/actor-map.d.ts
-interface ActorMapOptions {
-  /**
-   * When true, a child that reaches a final state (or dies into `__error`)
-   * is removed from the map automatically. Without it, completed children
-   * linger until explicitly `kill`ed.
-   */
-  autoReap?: boolean;
+/**
+ * Fan every given event out to all children of the map, once per key, in
+ * key order.
+ */
+export declare function broadcast<const T extends SendableEvent>(map: SendableMap<T>, ...events: [event: T]): void;
+/**
+ * Minimal actor surface the map needs. Real actors satisfy this
+ * structurally — tests can substitute tiny fakes.
+ */
+interface ActorMapChild {
+  snapshot(): Snapshot;
+  on(event: "done", listener: {
+    fn: () => void;
+  }): () => void;
+  send(...events: [event: SendableEvent]): void;
+  dispose(): void;
 }
 /**
  * Keyed registry of one actor type. `spawn(key)` builds a fresh instance via
  * the factory — same actor shape, keyed by id. The factory receives the key.
+ *
+ * With autoReap enabled, a child that reaches a final state (or dies into
+ * `__error`) is removed from the map automatically. Without it, completed
+ * children linger until explicitly killed.
  */
-declare class ActorMap implements SendableMap<SendableEvent> {
-  #private;
-  constructor(factory: (id: string) => AnyActor, options?: ActorMapOptions);
+interface ActorMap extends SendableMap<SendableEvent> {
   spawn(key: string): void;
-  send(key: string, event: SendableEvent): void;
   kill(key: string): void;
-  get size(): number;
+  dispose(): void;
+  ensure(key: string): void;
   has(key: string): boolean;
   keys(): string[];
-  ensure(key: string): void;
   snapshot(key: string): Snapshot | undefined;
+  readonly size: number;
 }
-//#endregion
-//#region src/state.d.ts
+export declare function createActorMap(factory: (id: string) => ActorMapChild, { autoReap }?: {
+  autoReap?: boolean;
+}): ActorMap;
 interface StatesEntry {
   name: string;
   final?: boolean;
@@ -55,47 +73,40 @@ type FinalOf<T> = T extends {
   final: true;
 } ? true : false;
 type StatesRecord<T extends StatesArg[]> = { [K in T[number] as NameOf<K>]: StateRef<NameOf<K>, unknown, FinalOf<K>>; };
-declare function states<const T extends StatesArg[]>(...entries: T): StatesRecord<T>;
-//#endregion
-//#region src/event.d.ts
-declare function events<T extends string>(...names: T[]): { [K in T]: EventRef<K>; };
-//#endregion
-//#region src/output.d.ts
+export declare function states<const T extends StatesArg[]>(...entries: T): StatesRecord<T>;
+export declare function events<T extends string>(...names: T[]): { [K in T]: EventRef<K>; };
 /**
- * Route an actor's emitted outputs to a handler.
+ * Route an actor's emitted outputs to one or more handlers.
  *
  * `regions` auto-wire child outputs into the parent. ActorMap children do
  * not — this is the public wrapper for that wiring seam. One call in the
- * factory connects a child's declared outputs to a receiver.
+ * factory connects a child's declared outputs to a receiver — pass several
+ * handlers to feed multiple receivers.
  */
-declare function onOutput(actor: AnyActor, handler: (event: InternalEvent) => void): void;
-//#endregion
-//#region src/effects/promise.d.ts
-type EmitFn = (event: {
+export declare function onOutput(actor: AnyActor, ...handlers: [handler: (event: InternalEvent) => void]): void;
+type AnyEvent = {
   type: string;
   payload?: unknown;
-}) => void;
-declare function withPromise<T>(promise: Promise<T>, signal: AbortSignal, emit: EmitFn, events: {
-  success: (data: T) => {
-    type: string;
-    payload?: unknown;
-  };
-  error: (err: unknown) => {
-    type: string;
-    payload?: unknown;
+};
+/** `Emit`: events the effect may send; follows the effect's `sends` list when declared. */
+interface WithPromiseOptions<T, Emit = AnyEvent> {
+  promise: Promise<T>;
+  signal: AbortSignal;
+  emit: (event: Emit) => void;
+  events: {
+    success: (data: T) => NoInfer<Emit>;
+    error: (err: unknown) => NoInfer<Emit>;
   };
+}
+export declare function withPromise<T, Emit = AnyEvent>(options: WithPromiseOptions<T, Emit>): Promise<void>;
+export declare function withTimeout<ActorContext, Payload = unknown, Emit = InternalEvent>(durationMs: number, options: {
+  input: EffectInput<ActorContext, Payload, Emit>;
+  event: () => NoInfer<Emit>;
 }): void;
-//#endregion
-//#region src/effects/timeout.d.ts
-declare function withTimeout<ActorContext>(ms: number, input: EffectInput<ActorContext>, event: () => InternalEvent): void;
-//#endregion
-//#region src/tags.d.ts
 interface Tag {
   has(snapshot: Snapshot): boolean;
 }
-declare function tag(...stateNames: StateRef<string, unknown>[]): Tag;
-//#endregion
-//#region src/parts.d.ts
+export declare function tag(...stateRefs: StateRef<string, unknown>[]): Tag;
 interface ActorSpec {
   states: readonly AnyStateRef[];
   inputs: readonly AnyEventRef[];
@@ -115,10 +126,11 @@ type InternalOf<S extends ActorSpec> = "internal" extends keyof S ? [NotUndef<S[
 type OutputsOf<S extends ActorSpec> = "outputs" extends keyof S ? [NotUndef<S["outputs"]>] extends [never] ? readonly [] : NotUndef<S["outputs"]> : readonly [];
 type ContextOf<S extends ActorSpec> = "context" extends keyof S ? [NotUndef<S["context"]>] extends [never] ? Record<string, unknown> : NotUndef<S["context"]> : Record<string, unknown>;
 type BuilderOf<S extends ActorSpec> = ActorBuilder<S["states"], S["inputs"], InternalOf<S>, OutputsOf<S>, ContextOf<S>>;
-type Fragment<S extends ActorSpec> = (m: BuilderOf<S>) => void;
-declare function definePart<S extends ActorSpec = never>(fn: (m: BuilderOf<S>) => void): Fragment<S>;
-declare function use<S extends ActorSpec>(m: BuilderOf<S>, part: Fragment<S>): void;
-type Part<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
+type Fragment<S extends ActorSpec> = (builder: BuilderOf<S>) => void;
+export declare function definePart<S extends ActorSpec = never>(part: (builder: BuilderOf<S>) => void): Fragment<S>;
+/** Apply one or more parts to a builder, in order. */
+export declare function use<S extends ActorSpec>(builder: BuilderOf<S>, ...parts: [Fragment<S>, ...Fragment<S>[]]): void;
+type Part<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (builder: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
 type SpecValue<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext, Initial> = {
   states: States;
   inputs: Inputs;
@@ -133,14 +145,18 @@ type SpecValue<States extends readonly AnyStateRef[], Inputs extends readonly An
 /**
  * Construct the actor's static spec — states, inputs, internal/output events,
  * context, initial state, clock, regions and budget. State/event tuples and
- * the initial ref narrow to literals; the context stays mutable, so
+ * the initial ref narrow to literals while the context stays mutable, so
  * `definePart` handlers read and write it with no `as` casts.
  */
-declare function actorSpec<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>, const Initial extends InitialState<States[number]> = InitialState<States[number]>>(spec: SpecValue<States, Inputs, Internal, Outputs, ActorContext, Initial>): SpecValue<States, Inputs, Internal, Outputs, ActorContext, Initial>;
-declare function withParts<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>>(base: Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup">, parts: Part<States, Inputs, Internal, Outputs, ActorContext> | readonly Part<States, Inputs, Internal, Outputs, ActorContext>[]): Actor<States, Inputs, Internal, Outputs, ActorContext>;
-//#endregion
-//#region src/snapshot.d.ts
-declare function isIn(snapshot: Snapshot, stateRefName: string): boolean;
-declare function activeLeaves(snapshot: Snapshot): string[];
-//#endregion
-export { ActorMap, type ActorSpec, type BuilderOf, type EventLike, type Fragment, type Part, type SendableEvent, type SendableMap, activeLeaves, actorSpec, broadcast, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };
+export declare function actorSpec<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>, const Initial extends InitialState<States[number]> = InitialState<States[number]>>(spec: SpecValue<States, Inputs, Internal, Outputs, ActorContext, Initial>): SpecValue<States, Inputs, Internal, Outputs, ActorContext, Initial>;
+/**
+ * Build an actor whose setup applies every given part in order. Pass parts
+ * as separate arguments — single part or many.
+ */
+export declare function withParts<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>>(base: Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup">, ...parts: Part<States, Inputs, Internal, Outputs, ActorContext>[]): Actor<States, Inputs, Internal, Outputs, ActorContext>;
+/**
+ * True when any of the named states is active anywhere in the snapshot tree.
+ */
+export declare function isIn(snapshot: Snapshot, ...stateNames: [stateName: string]): boolean;
+export declare function activeLeaves(snapshot: Snapshot): string[];
+export type { ActorMap, ActorMapChild, ActorSpec, BuilderOf, EventLike, Fragment, Part, SendableEvent, SendableMap, WithPromiseOptions };

package/dist/index.mjs

@@ -1,80 +1,118 @@
 import { Actor, event, state } from "@mantaq/core";
-//#region src/actors/matches.ts
-function matchSnapshot(snapshot, parts, index) {
-	const stateName = snapshot.path[0];
-	for (let end = index; end < parts.length; end++) {
-		if (parts.slice(index, end + 1).join(".") !== stateName) continue;
-		if (end === parts.length - 1) return true;
-		const regionSnap = snapshot.regions[parts[end + 1]];
-		if (!regionSnap) return false;
-		if (end + 1 === parts.length - 1) return true;
-		return matchSnapshot(regionSnap, parts, end + 2);
+// src/actors/matches.ts
+function matchFrom(patternParts) {
+	function matchRegion(options) {
+		const stateName = options.snapshot.path[0];
+		for (let end = options.index; end < patternParts.length; end++) {
+			if (patternParts.slice(options.index, end + 1).join(".") !== stateName) continue;
+			if (end === patternParts.length - 1) return true;
+			const regionSnap = options.snapshot.regions[patternParts[end + 1]];
+			if (!regionSnap) return false;
+			if (end + 1 === patternParts.length - 1) return true;
+			return matchRegion({
+				snapshot: regionSnap,
+				index: end + 2
+			});
+		}
+		return false;
 	}
-	return false;
-}
-function matches(actor, pattern) {
-	if (!pattern || pattern.endsWith(".") || pattern.startsWith(".") || pattern.includes("..")) return false;
-	const parts = pattern.split(".");
-	return matchSnapshot(actor.snapshot(), parts, 0);
+	return matchRegion;
 }
-//#endregion
-//#region src/actors/actor-map.ts
 /**
-* Keyed registry of one actor type. `spawn(key)` builds a fresh instance via
-* the factory — same actor shape, keyed by id. The factory receives the key.
+* True when the actor's snapshot matches the dotted pattern. Accepts the
+* pattern as one dotted string or as separate segments. A segment containing
+* dots matches states whose own name contains dots.
 */
-var ActorMap = class {
-	#actors = /* @__PURE__ */ new Map();
-	#reapers = /* @__PURE__ */ new Map();
-	#factory;
-	#autoReap;
-	constructor(factory, options = {}) {
-		this.#factory = factory;
-		this.#autoReap = options.autoReap === true;
-	}
-	spawn(key) {
-		if (this.#actors.has(key)) this.kill(key);
-		const child = this.#factory(key);
-		this.#actors.set(key, child);
-		if (this.#autoReap) {
-			if (child.snapshot().done) {
-				this.#actors.delete(key);
-				return;
-			}
-			const off = child.on("done", () => {
-				if (this.#actors.get(key) === child) this.#actors.delete(key);
-				this.#reapers.delete(key);
-			});
-			this.#reapers.set(key, off);
+function matches(actor, ...pattern) {
+	const joined = pattern.join(".");
+	if (!joined || joined.endsWith(".") || joined.startsWith(".") || joined.includes("..")) return false;
+	return matchFrom(joined.split("."))({
+		snapshot: actor.snapshot(),
+		index: 0
+	});
+}
+// src/actors/actor-map.ts
+function createActorMap(factory, { autoReap } = {}) {
+	const actors = /* @__PURE__ */ new Map();
+	const reapers = /* @__PURE__ */ new Map();
+	const reap = autoReap === true;
+	function spawn(key) {
+		if (actors.has(key)) kill(key);
+		const child = factory(key);
+		actors.set(key, child);
+		if (!reap) return;
+		if (child.snapshot().done) {
+			actors.delete(key);
+			Promise.resolve().then(() => child.dispose());
+			return;
 		}
+		const off = child.on("done", { fn: () => {
+			off();
+			if (actors.get(key) === child) actors.delete(key);
+			reapers.delete(key);
+			Promise.resolve().then(() => child.dispose());
+		} });
+		reapers.set(key, off);
 	}
-	send(key, event) {
-		this.#actors.get(key)?.send(event);
-	}
-	kill(key) {
-		this.#actors.get(key)?.dispose();
-		this.#reapers.get(key)?.();
-		this.#reapers.delete(key);
-		this.#actors.delete(key);
+	function kill(key) {
+		actors.get(key)?.dispose();
+		reapers.get(key)?.();
+		reapers.delete(key);
+		actors.delete(key);
 	}
-	get size() {
-		return this.#actors.size;
+	/**
+	* Tear down the map and every live child. Without this, dropping an
+	* actor map (e.g. when its owning actor is disposed) leaks every child
+	* actor whose effects/timers/reapers keep running. Idempotent.
+	*/
+	function dispose() {
+		for (const child of actors.values()) child.dispose();
+		for (const off of reapers.values()) off();
+		reapers.clear();
+		actors.clear();
 	}
-	has(key) {
-		return this.#actors.has(key);
+	function ensure(key) {
+		if (!actors.has(key)) spawn(key);
 	}
-	keys() {
-		return [...this.#actors.keys()];
+	function has(key) {
+		return actors.has(key);
 	}
-	ensure(key) {
-		if (!this.#actors.has(key)) this.spawn(key);
+	function keys() {
+		return [...actors.keys()];
 	}
-	snapshot(key) {
-		return this.#actors.get(key)?.snapshot();
+	function snapshotOf(key) {
+		return actors.get(key)?.snapshot();
 	}
-};
-//#endregion
-//#region src/state.ts
+	return {
+		spawn,
+		kill,
+		dispose,
+		ensure,
+		has,
+		keys,
+		snapshot: snapshotOf,
+		send(key, ...events) {
+			for (const event of events) actors.get(key)?.send(event);
+		},
+		get size() {
+			return actors.size;
+		}
+	};
+}
+// src/parse-refs.ts
+/**
+* Boundary utility for the `states()` and `events()` helpers. Ref records are
+* built dynamically, keyed by a literal name tuple. TypeScript cannot express
+* that assignment, so the narrowing from the runtime-shaped record to the
+* mapped tuple type happens here — the only place a cast is trusted.
+*/
+function parseStateRefs(record) {
+	return record;
+}
+function parseEventRefs(record) {
+	return record;
+}
+// src/state.ts
 function states(...entries) {
 	const result = {};
 	for (const entry of entries) {
@@ -82,93 +120,110 @@ function states(...entries) {
 		const ref = state(name)();
 		result[name] = typeof entry === "object" && entry.final ? ref.final() : ref;
 	}
-	return result;
+	return parseStateRefs(result);
 }
-//#endregion
-//#region src/event.ts
+// src/event.ts
 function events(...names) {
 	const result = {};
 	for (const name of names) result[name] = event(name)();
-	return result;
+	return parseEventRefs(result);
 }
-//#endregion
-//#region src/output.ts
+// src/output.ts
 /**
-* Route an actor's emitted outputs to a handler.
+* Route an actor's emitted outputs to one or more handlers.
 *
 * `regions` auto-wire child outputs into the parent. ActorMap children do
 * not — this is the public wrapper for that wiring seam. One call in the
-* factory connects a child's declared outputs to a receiver.
+* factory connects a child's declared outputs to a receiver — pass several
+* handlers to feed multiple receivers.
 */
-function onOutput(actor, handler) {
-	actor.on("output", handler);
+function onOutput(actor, ...handlers) {
+	for (const handler of handlers) actor.on("output", { fn: handler });
 }
-//#endregion
-//#region src/effects/promise.ts
-function withPromise(promise, signal, emit, events) {
-	promise.then((data) => {
+// src/effects/promise.ts
+function withPromise(options) {
+	const { promise, signal, emit, events } = options;
+	return promise.then((data) => {
 		if (!signal.aborted) emit(events.success(data));
-	}).catch((err) => {
+	}, (err) => {
 		if (!signal.aborted) emit(events.error(err));
 	});
 }
-//#endregion
-//#region src/effects/timeout.ts
-function withTimeout(ms, input, event) {
-	input.clock.setTimeout(ms, () => {
-		if (input.signal.aborted) return;
-		input.emit(event());
-	}, { signal: input.signal });
-}
-//#endregion
-//#region src/transitions/broadcast.ts
-function broadcast(map, event) {
-	for (const key of map.keys()) map.send(key, event);
-}
-//#endregion
-//#region src/snapshot.ts
-function isIn(snapshot, stateRefName) {
-	if (snapshot.path[0] === stateRefName) return true;
-	for (const region of Object.values(snapshot.regions)) if (isIn(region, stateRefName)) return true;
+// src/effects/timeout.ts
+function withTimeout(durationMs, options) {
+	const { input, event } = options;
+	input.clock.setTimeout(durationMs, {
+		signal: input.signal,
+		cb: () => {
+			if (input.signal.aborted) return;
+			input.emit(event());
+		}
+	});
+}
+// src/transitions/broadcast.ts
+/**
+* Fan every given event out to all children of the map, once per key, in
+* key order.
+*/
+function broadcast(map, ...events) {
+	for (const event of events) for (const key of map.keys()) map.send(key, event);
+}
+// src/snapshot.ts
+function isInState(options) {
+	if (options.snapshot.path[0] === options.stateName) return true;
+	for (const region of Object.values(options.snapshot.regions)) if (isInState({
+		snapshot: region,
+		stateName: options.stateName
+	})) return true;
 	return false;
 }
+/**
+* True when any of the named states is active anywhere in the snapshot tree.
+*/
+function isIn(snapshot, ...stateNames) {
+	return stateNames.some((stateName) => isInState({
+		snapshot,
+		stateName
+	}));
+}
 function activeLeaves(snapshot) {
 	if (Object.keys(snapshot.regions).length === 0) return [snapshot.path.join(".")];
 	const leaves = [];
 	for (const [regionName, region] of Object.entries(snapshot.regions)) for (const leaf of activeLeaves(region)) leaves.push(`${snapshot.path[0]}.${regionName}.${leaf}`);
 	return leaves;
 }
-//#endregion
-//#region src/tags.ts
-function tag(...stateNames) {
-	const names = stateNames.map((s) => s.name);
+// src/tags.ts
+function tag(...stateRefs) {
+	const names = stateRefs.map((ref) => ref.name);
 	return { has: (snapshot) => names.some((name) => isIn(snapshot, name)) };
 }
-//#endregion
-//#region src/parts.ts
-function definePart(fn) {
-	return fn;
+// src/parts.ts
+function definePart(part) {
+	return part;
 }
-function use(m, part) {
-	part(m);
+/** Apply one or more parts to a builder, in order. */
+function use(builder, ...parts) {
+	for (const part of parts) part(builder);
 }
 /**
 * Construct the actor's static spec — states, inputs, internal/output events,
 * context, initial state, clock, regions and budget. State/event tuples and
-* the initial ref narrow to literals; the context stays mutable, so
+* the initial ref narrow to literals while the context stays mutable, so
 * `definePart` handlers read and write it with no `as` casts.
 */
 function actorSpec(spec) {
 	return spec;
 }
-function withParts(base, parts) {
-	const list = Array.isArray(parts) ? parts : [parts];
-	return new Actor({
+/**
+* Build an actor whose setup applies every given part in order. Pass parts
+* as separate arguments — single part or many.
+*/
+function withParts(base, ...parts) {
+	return Actor({
 		...base,
-		setup: (m) => {
-			for (const part of list) part(m);
+		setup: (builder) => {
+			for (const part of parts) part(builder);
 		}
 	});
 }
-//#endregion
-export { ActorMap, activeLeaves, actorSpec, broadcast, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };
+export { activeLeaves, actorSpec, broadcast, createActorMap, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/sugar",
-  "version": "0.4.0",
+  "version": "2.0.0",
   "description": "Userland sugar for mantaq actors — matches, effect helpers, transition utilities.",
   "license": "MIT",
   "repository": {
@@ -20,19 +20,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/core": "0.3.0"
+    "@mantaq/core": "0.5.0"
   },
   "devDependencies": {
-    "@stryker-mutator/core": "^9",
-    "@stryker-mutator/vitest-runner": "^9",
+    "@stryker-mutator/core": "^10",
+    "@stryker-mutator/vitest-runner": "^10",
     "@types/node": "^26.2.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "@vitest/coverage-v8": "4.1.10",
-    "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
-    "vite-plus": "0.2.8",
-    "vitest": "4.1.10",
-    "@mantaq/pbt": "0.0.2"
+    "@vitest/coverage-v8": "5.0.5",
+    "typescript": "6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0",
+    "vitest": "5.0.5",
+    "@mantaq/pbt": "0.0.3"
   },
   "scripts": {
     "build": "vp pack",