@effect-app/vue 4.0.0-beta.99 → 4.0.0

package/src/commander.ts

@@ -1,19 +1,44 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { asResult, type MissingDependencies, reportRuntimeError } from "@effect-app/vue"
 import { reportMessage } from "@effect-app/vue/errorReporter"
-import { Cause, Context, Effect, type Exit, type Fiber, flow, Layer, Match, MutableHashMap, Option, Predicate, S } from "effect-app"
+import { deepToRaw, reportRuntimeError } from "@effect-app/vue/lib"
+import { type MissingDependencies } from "@effect-app/vue/makeClient"
+import { asResult, asStreamResult } from "@effect-app/vue/mutate"
 import { SupportedErrors } from "effect-app/client"
-import { OperationFailure, OperationSuccess } from "effect-app/Operations"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
+import * as Option from "effect-app/Option"
+import * as S from "effect-app/Schema"
 import { isGeneratorFunction, wrapEffect } from "effect-app/utils"
-import { type AsyncResult } from "effect/unstable/reactivity/AsyncResult"
+import * as Cause from "effect/Cause"
+import type * as Exit from "effect/Exit"
+import type * as Fiber from "effect/Fiber"
+import { flow } from "effect/Function"
+import * as MutableHashMap from "effect/MutableHashMap"
+import * as Predicate from "effect/Predicate"
+import { type Refinement } from "effect/Predicate"
+import * as AsyncResult from "effect/reactivity/AsyncResult"
+import * as Stream from "effect/Stream"
 import { type FormatXMLElementFn, type PrimitiveType } from "intl-messageformat"
-import { computed, type ComputedRef, reactive, ref } from "vue"
-import { Confirm } from "./confirm.js"
-import { I18n } from "./intl.js"
-import { WithToast } from "./withToast.js"
+import { computed, type ComputedRef, reactive, ref, toRaw } from "vue"
+import { Confirm } from "./confirm.ts"
+import { I18n } from "./intl.ts"
+import { CurrentToastId, Toast } from "./toast.ts"
+import { WithToast } from "./withToast.ts"
 
 type IntlRecord = Record<string, PrimitiveType | FormatXMLElementFn<string, string>>
-type FnOptions<Id extends string, I18nCustomKey extends string, State extends IntlRecord | undefined> = {
+
+/**
+ * Progress information surfaced by a stream command. Either a plain text label
+ * or a `{ text, percentage }` pair when concrete progress is known.
+ */
+export type Progress = string | { readonly text: string; readonly percentage: number }
+
+type FnOptions<
+  Id extends string,
+  I18nCustomKey extends string,
+  State extends IntlRecord | undefined
+> = {
   i18nCustomKey?: I18nCustomKey
   /**
    * passed to the i18n formatMessage calls so you can use it in translation messagee
@@ -78,6 +103,35 @@ export class CommandContext extends Context.Service<CommandContext, {
   "CommandContext"
 ) {}
 
+/**
+ * Service available inside `streamFn` stream handlers that lets you imperatively push
+ * progress updates to the command's reactive `progress` ref.
+ *
+ * Use `Command.mapProgress(fn)` or `Command.updateProgress(progress)` to interact with this service.
+ *
+ * @example
+ * ```ts
+ * // Using mapProgress (recommended) — applied as a stream pipe operator:
+ * const exportCmd = Command.streamFn("exportData")(
+ *   function*(arg, ctx) {
+ *     return makeExportStream(arg.id).pipe(
+ *       Command.mapProgress((r) =>
+ *         AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress"
+ *           ? { text: `${r.value.completed}/${r.value.total}`, percentage: r.value.completed / r.value.total * 100 }
+ *           : undefined
+ *       )
+ *     )
+ *   }
+ * )
+ * // exportCmd.progress is updated for every OperationProgress event
+ * ```
+ */
+export class CommandProgress extends Context.Reference<{
+  readonly update: (progress: Progress | undefined) => Effect.Effect<void>
+}>("Commander.CommandProgress", {
+  defaultValue: () => ({ update: (_progress: Progress | undefined): Effect.Effect<void> => Effect.void })
+}) {}
+
 export type EmitWithCallback<A, Event extends string> = (event: Event, value: A, onDone: () => void) => void
 
 /**
@@ -91,6 +145,19 @@ export const wrapEmit = <A, Event extends string>(
 (value: A) => new Promise<void>((resolve) => emit(event, value, resolve))
 
 export declare namespace Commander {
+  export type IntlRecord = Record<string, PrimitiveType | FormatXMLElementFn<string, string>>
+  export type FnOptions<
+    Id extends string,
+    I18nKey extends string,
+    State extends IntlRecord | undefined
+  > = {
+    i18nCustomKey?: I18nKey
+    state?: ComputedRef<State> | (() => State)
+    blockKey?: (id: Id) => string | undefined
+    waitKey?: (id: Id) => string | undefined
+    allowed?: (id: Id, state: ComputedRef<State>) => boolean
+  }
+
   export type CommanderBase<RT, Id extends string, I18nKey extends string, State extends IntlRecord | undefined> =
     & Gen<RT, Id, I18nKey, State>
     & NonGen<RT, Id, I18nKey, State>
@@ -138,7 +205,12 @@ export declare namespace Commander {
     /** reactive */
     label: string
     /** reactive */
-    result: AsyncResult<A, E>
+    result: AsyncResult.AsyncResult<A, E>
+    /**
+     * reactive – formatted progress info driven by `Command.mapProgress` or `Command.updateProgress`
+     * inside a `streamFn` handler. Undefined for non-stream commands.
+     */
+    progress: Progress | undefined
     /** reactive */
     waiting: boolean
     /** reactive */
@@ -161,7 +233,7 @@ export declare namespace Commander {
     new(): {}
 
     /** click handlers */
-    handle: ((arg: Arg) => Fiber.Fiber<Exit.Exit<A, E>, never>) & {
+    handle: ((arg: Arg) => Fiber.Fiber<Exit.Exit<A, E>>) & {
       /** @deprecated don't exist */
       effect: (arg: Arg) => Effect.Effect<A, E, R>
     }
@@ -208,7 +280,7 @@ export declare namespace Commander {
 
   export type Gen<RT, Id extends string, I18nKey extends string, State extends IntlRecord | undefined> = {
     <
-      Eff extends Effect.Yieldable<any, any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      Eff extends Effect.Effect<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
       AEff,
       Arg = void
     >(
@@ -217,17 +289,17 @@ export declare namespace Commander {
       Arg,
       AEff,
       [Eff] extends [never] ? never
-        : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+        : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
         : never,
       [Eff] extends [never] ? never
-        : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+        : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
         : never,
       Id,
       I18nKey,
       State
     >
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A extends Effect.Effect<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
       Arg = void
@@ -237,10 +309,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -248,7 +320,7 @@ export declare namespace Commander {
       ) => A
     ): CommandOutHelper<Arg, A, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B extends Effect.Effect<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
@@ -259,10 +331,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -275,7 +347,7 @@ export declare namespace Commander {
       ) => B
     ): CommandOutHelper<Arg, B, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -287,10 +359,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -308,7 +380,7 @@ export declare namespace Commander {
       ) => C
     ): CommandOutHelper<Arg, C, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -321,10 +393,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -347,7 +419,7 @@ export declare namespace Commander {
       ) => D
     ): CommandOutHelper<Arg, D, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -361,10 +433,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -392,7 +464,7 @@ export declare namespace Commander {
       ) => E
     ): CommandOutHelper<Arg, E, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -407,10 +479,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -443,7 +515,7 @@ export declare namespace Commander {
       ) => F
     ): CommandOutHelper<Arg, F, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -459,10 +531,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -500,7 +572,7 @@ export declare namespace Commander {
       ) => G
     ): CommandOutHelper<Arg, G, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -517,10 +589,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -563,7 +635,7 @@ export declare namespace Commander {
       ) => H
     ): CommandOutHelper<Arg, H, Id, I18nKey, State>
     <
-      Eff extends Effect.Yieldable<any, any, any, any>,
+      Eff extends Effect.Effect<any, any, any>,
       AEff,
       A,
       B,
@@ -581,10 +653,10 @@ export declare namespace Commander {
         _: Effect.Effect<
           AEff,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
             : never,
           [Eff] extends [never] ? never
-            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
             : never
         >,
         arg: ArgForCombinator<Arg>,
@@ -1657,46 +1729,288 @@ export declare namespace Commander {
       ) => Eff
     ): CommandOutHelper<Arg, Eff, Id, I18nKey, State>
   }
+
+  /**
+   * Type for `streamFn` — generator overload where the body yields Effects and returns a `Stream`.
+   * `waiting` stays `true` while the stream is running, and updates the `result` ref per emitted value.
+   */
+  export type StreamGen<RT, Id extends string, I18nKey extends string, State extends IntlRecord | undefined> = {
+    <
+      Eff extends Effect.Effect<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      SA,
+      SE,
+      SR,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Generator<Eff, Stream.Stream<SA, SE, SR>, never>
+    ): CommandOut<
+      Arg,
+      SA,
+      | SE
+      | ([Eff] extends [never] ? never
+        : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
+        : never),
+      | SR
+      | ([Eff] extends [never] ? never
+        : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
+        : never),
+      Id,
+      I18nKey,
+      State
+    >
+    <
+      Eff extends Effect.Effect<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      SA,
+      SE,
+      SR,
+      B,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Generator<Eff, Stream.Stream<SA, SE, SR>, never>,
+      a: (
+        _: Effect.Effect<
+          Stream.Stream<SA, SE, SR>,
+          ([Eff] extends [never] ? never
+            : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E
+            : never),
+          ([Eff] extends [never] ? never
+            : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R
+            : never)
+        >,
+        arg: ArgForCombinator<Arg>,
+        ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+      ) => B
+    ): B extends Stream.Stream<infer SA2, infer SE2, infer SR2> ? CommandOut<Arg, SA2, SE2, SR2, Id, I18nKey, State>
+      : B extends Effect.Effect<Stream.Stream<infer SA2, infer SE2, infer SR2>, infer EE2, infer ER2>
+        ? CommandOut<Arg, SA2, SE2 | EE2, SR2 | ER2, Id, I18nKey, State>
+      : never
+  }
+
+  /**
+   * Type for `streamFn` — non-generator overload accepting a function that returns a `Stream` directly,
+   * or an `Effect` that resolves to a `Stream`.
+   */
+  export type NonGenStream<RT, Id extends string, I18nKey extends string, State extends IntlRecord | undefined> = {
+    <
+      SA,
+      SE,
+      SR extends RT | CommandContext | `Commander.Command.${Id}.state`,
+      Arg = void
+    >(
+      body: (arg: Arg, ctx: CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>
+    ): CommandOut<Arg, SA, SE, SR, Id, I18nKey, State>
+    <
+      SA,
+      SE,
+      SR,
+      A extends Stream.Stream<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      Arg = void
+    >(
+      body: (arg: Arg, ctx: CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>,
+      a: (
+        _: Stream.Stream<SA, SE, SR>,
+        arg: ArgForCombinator<Arg>,
+        ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+      ) => A
+    ): CommandOut<Arg, Stream.Success<A>, Stream.Error<A>, Stream.Services<A>, Id, I18nKey, State>
+    <
+      SA,
+      SE,
+      SR,
+      EE,
+      ER extends RT | CommandContext | `Commander.Command.${Id}.state`,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Effect.Effect<Stream.Stream<SA, SE, SR>, EE, ER>
+    ): CommandOut<Arg, SA, SE | EE, SR | ER, Id, I18nKey, State>
+    <
+      SA,
+      SE,
+      SR,
+      EE,
+      ER,
+      B,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Effect.Effect<Stream.Stream<SA, SE, SR>, EE, ER>,
+      a: (
+        _: Effect.Effect<Stream.Stream<SA, SE, SR>, EE, ER>,
+        arg: ArgForCombinator<Arg>,
+        ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+      ) => B
+    ): B extends Stream.Stream<infer SA2, infer SE2, infer SR2> ? CommandOut<Arg, SA2, SE2, SR2, Id, I18nKey, State>
+      : B extends Effect.Effect<Stream.Stream<infer SA2, infer SE2, infer SR2>, infer EE2, infer ER2>
+        ? CommandOut<Arg, SA2, SE2 | EE2, SR2 | ER2, Id, I18nKey, State>
+      : never
+  }
+
+  /**
+   * Type returned by `mutate.wrap` on a stream handler — analogous to `CommanderWrap` but for streams.
+   * The handler is pre-baked (from the stream mutation), so this is called with only optional combinators.
+   */
+  export type StreamerWrap<
+    RT,
+    Id extends string,
+    I18nKey extends string,
+    State extends IntlRecord | undefined,
+    Arg,
+    SA,
+    SE,
+    SR
+  > =
+    & CommandContextLocal<Id, I18nKey>
+    & { readonly state: Context.Service<`Commander.Command.${Id}.state`, State> }
+    & {
+      (): Exclude<SR, RT> extends never ? CommandOut<Arg, SA, SE, SR, Id, I18nKey, State>
+        : MissingDependencies<RT, SR> & {}
+      <A extends Stream.Stream<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>>(
+        a: (
+          _: Stream.Stream<SA, SE, SR>,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => A
+      ): CommandOut<Arg, Stream.Success<A>, Stream.Error<A>, Stream.Services<A>, Id, I18nKey, State>
+      <
+        B,
+        A extends Stream.Stream<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>
+      >(
+        a: (
+          _: Stream.Stream<SA, SE, SR>,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => B,
+        b: (
+          _: B,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => A
+      ): CommandOut<Arg, Stream.Success<A>, Stream.Error<A>, Stream.Services<A>, Id, I18nKey, State>
+      <
+        B,
+        C,
+        A extends Stream.Stream<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>
+      >(
+        a: (
+          _: Stream.Stream<SA, SE, SR>,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => B,
+        b: (
+          _: B,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => C,
+        c: (
+          _: C,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => A
+      ): CommandOut<Arg, Stream.Success<A>, Stream.Error<A>, Stream.Services<A>, Id, I18nKey, State>
+      <
+        B,
+        C,
+        D,
+        A extends Stream.Stream<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>
+      >(
+        a: (
+          _: Stream.Stream<SA, SE, SR>,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => B,
+        b: (
+          _: B,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => C,
+        c: (
+          _: C,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => D,
+        d: (
+          _: D,
+          arg: ArgForCombinator<Arg>,
+          ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+        ) => A
+      ): CommandOut<Arg, Stream.Success<A>, Stream.Error<A>, Stream.Services<A>, Id, I18nKey, State>
+    }
 }
 
 type ErrorRenderer<E, Args extends readonly any[]> = (e: E, action: string, ...args: Args) => string | undefined
 
-const renderErrorMaker = I18n.useSync(
-  ({ intl }) =>
-  <E, Args extends readonly any[]>(action: string, errorRenderer?: ErrorRenderer<E, Args>) =>
-  (e: E, ...args: Args): string => {
-    if (errorRenderer) {
-      const m = errorRenderer(e, action, ...args)
-      if (m !== undefined) {
-        return m
+type RegisteredErrorRenderer<A> = {
+  guard: Refinement<unknown, A>
+  render: (guarded: A) => string | undefined
+}
+
+export class CommanderErrorRenderers extends Context.Reference("Commander.ErrorRenderers", {
+  defaultValue: () => [] as RegisteredErrorRenderer<any>[]
+}) {}
+
+export const makeRegisteredErrorRenderer = <A>(
+  guard: Predicate.Refinement<unknown, A>,
+  render: (guarded: A) => string | undefined
+): RegisteredErrorRenderer<A> => ({
+  guard,
+  render
+})
+
+const renderErrorMaker = Effect.gen(function*() {
+  const { intl } = yield* I18n
+  const registeredRenderers = yield* CommanderErrorRenderers
+  return (
+    <E, Args extends readonly any[]>(action: string, errorRenderer?: ErrorRenderer<E, Args>) =>
+    (e: E, ...args: Args): string => {
+      if (errorRenderer) {
+        const m = errorRenderer(e, action, ...args)
+        if (m !== undefined) {
+          return m
+        }
       }
-    }
-    if (!S.is(SupportedErrors)(e) && !S.isSchemaError(e)) {
-      if (typeof e === "object" && e !== null) {
-        if ("message" in e) {
-          return `${e.message}`
+      for (const entry of registeredRenderers) {
+        if (!entry.guard(e)) {
+          continue
         }
-        if ("_tag" in e) {
-          return `${e._tag}`
+        const m = entry.render(e)
+        if (m !== undefined) {
+          return m
         }
       }
-      return ""
-    }
-    const e2: SupportedErrors | S.SchemaError = e
-    return Match.value(e2).pipe(
-      Match.tags({
-        NotFoundError: (e) => {
-          return intl.formatMessage({ id: "handle.not_found" }, { type: e.type, id: e.id })
-        },
-        SchemaError: (e) => {
-          console.warn(e.toString())
-          return intl.formatMessage({ id: "validation.failed" })
+      if (!S.is(SupportedErrors)(e) && !S.isSchemaError(e)) {
+        if (typeof e === "object" && e !== null) {
+          if ("message" in e) {
+            return `${e.message}`
+          }
+          if ("_tag" in e) {
+            return `${e._tag}`
+          }
         }
-      }),
-      Match.orElse((e) => `${e.message ?? e._tag ?? e}`)
-    )
-  }
-)
+        return ""
+      }
+      const e2: SupportedErrors | S.SchemaError = e
+      if (e2._tag === "NotFoundError") {
+        return intl.formatMessage({ id: "handle.not_found" }, { type: e2.type, id: String(e2.id) })
+      }
+      if (e2._tag === "SchemaError") {
+        console.warn(e2.toString())
+        return intl.formatMessage({ id: "validation.failed" })
+      }
+      return e2.message ?? e2._tag ?? e2
+    }
+  )
+})
 
 const defaultFailureMessageHandler = <E, Args extends Array<unknown>, AME, AMR>(
   actionMaker:
@@ -1719,23 +2033,18 @@ const defaultFailureMessageHandler = <E, Args extends Array<unknown>, AME, AMR>(
             error: "" // TODO consider again Cause.pretty(cause), // will be reported to Sentry/Otel anyway.. and we shouldn't bother users with error dumps?
           }
         ),
-      onSome: (e) =>
-        S.is(OperationFailure)(e)
-          ? {
-            level: "warn" as const,
-            message: intl.formatMessage(
-                { id: "handle.with_warnings" },
-                { action }
-              ) + e.message
-              ? "\n" + e.message
-              : ""
-          }
-          : `${
+      onSome: (e) => {
+        const rendered = renderError(action, errorRenderer)(e, ...args)
+        return {
+          level: "warn" as const,
+          message: `${
             intl.formatMessage(
               { id: "handle.with_errors" },
               { action }
             )
-          }:\n` + renderError(action, errorRenderer)(e, ...args)
+          }:\n` + rendered
+        }
+      }
     })
   })
 
@@ -1745,9 +2054,69 @@ export const CommanderStatic = {
   ) =>
   (self: In, arg: Arg, arg2: Arg2) => cb(arg, arg2)(self),
 
+  /**
+   * Stream pipe operator that maps each emitted value to a `Progress` entry and updates the
+   * command's reactive `progress` ref via the `CommandProgress` service.
+   *
+   * The mapper receives an `AsyncResult<A, E>` (each emitted value wrapped as
+   * `AsyncResult.success(value, { waiting: true })`), matching the same shape used by
+   * `CommandButton`'s `:progress-map` prop.
+   *
+   * Designed to be used inside a `streamFn` handler (either directly with `.pipe()`, or as
+   * a combinator argument):
+   *
+   * @example
+   * ```ts
+   * // Inside the handler body:
+   * Command.streamFn("exportData")(function*(arg, ctx) {
+   *   return makeExportStream(arg.id).pipe(
+   *     Command.mapProgress((r) =>
+   *       AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress"
+   *         ? { text: `${r.value.completed}/${r.value.total}`, percentage: r.value.completed / r.value.total * 100 }
+   *         : undefined
+   *     )
+   *   )
+   * })
+   *
+   * // Or as a stream combinator argument:
+   * Command.streamFn("exportData")(
+   *   function*(arg, ctx) { return makeExportStream(arg.id) },
+   *   (s) => s.pipe(Command.mapProgress((r) => AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress" ? { text: `${r.value.completed}/${r.value.total}` } : undefined))
+   * )
+   * ```
+   */
+  mapProgress:
+    <A, E>(fn: (result: AsyncResult.AsyncResult<A, E>) => Progress | undefined) =>
+    <R>(stream: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>
+      stream.pipe(
+        Stream.tap((v) => {
+          const p = fn(AsyncResult.success(v, { waiting: true }))
+          return p !== undefined ? CommandProgress.use((s) => s.update(p)) : Effect.void
+        })
+      ),
+
+  /**
+   * Imperatively push a progress update from inside a `streamFn` handler.
+   * Requires `CommandProgress` to be in context — provided automatically for all `streamFn` streams.
+   *
+   * @example
+   * ```ts
+   * // In a streamFn handler:
+   * stream.pipe(
+   *   Stream.tap((event) =>
+   *     event._tag === "OperationProgress"
+   *       ? Command.updateProgress({ text: `${event.completed}/${event.total}`, percentage: event.completed / event.total * 100 })
+   *       : Effect.void
+   *   )
+   * )
+   * ```
+   */
+  updateProgress: (progress: Progress | undefined): Effect.Effect<void> =>
+    CommandProgress.use((s) => s.update(progress)),
+
   /** Version of @see confirmOrInterrupt that automatically includes the action name in the default messages */
   confirmOrInterrupt: Effect.fnUntraced(function*(
-    message: string | undefined = undefined
+    message?: string
   ) {
     const context = yield* CommandContext
     const { intl } = yield* I18n
@@ -1762,7 +2131,7 @@ export const CommanderStatic = {
   }),
   /** Version of @see confirm that automatically includes the action name in the default messages */
   confirm: Effect.fnUntraced(function*(
-    message: string | undefined = undefined
+    message?: string
   ) {
     const context = yield* CommandContext
     const { intl } = yield* I18n
@@ -1782,6 +2151,17 @@ export const CommanderStatic = {
         CommandContext,
         (c) => ({ ...c, action: update(c.action, ...input) })
       ),
+  registerErrorRenderer: <A>(
+    guard: Predicate.Refinement<unknown, A>,
+    render: (guarded: A) => string | undefined
+  ) =>
+    Layer.effect(
+      CommanderErrorRenderers,
+      Effect.gen(function*() {
+        const current = yield* CommanderErrorRenderers
+        return [...current, makeRegisteredErrorRenderer(guard, render)]
+      })
+    ),
   defaultFailureMessageHandler,
   renderError: renderErrorMaker,
   /**
@@ -1806,6 +2186,7 @@ export const CommanderStatic = {
         | string
         | ((id: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => true | string | undefined)
       errorRenderer?: (e: E, action: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | undefined
+      showSpanInfo?: false
       onWaiting?:
         | null
         | undefined
@@ -1818,11 +2199,10 @@ export const CommanderStatic = {
         | ((a: A, action: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | null | undefined)
     }
   ) =>
-  (
-    self: Effect.Effect<A, E, R>,
-    ...args: Args
-  ) =>
-    Effect.gen(function*() {
+    Effect.fnUntraced(function*(
+      self: Effect.Effect<A, E, R>,
+      ...args: Args
+    ) {
       const cc = yield* CommandContext
       const { intl } = yield* I18n
       const withToast = yield* WithToast
@@ -1859,23 +2239,216 @@ export const CommanderStatic = {
               ),
             onSuccess: options?.onSuccess === null
               ? null
-              : (a, ..._args) =>
+              : (_a, ..._args) =>
                 hasCustomSuccess
                   ? intl.formatMessage(
                     { id: customSuccess },
                     cc.state
                   )
-                  : (intl.formatMessage({ id: "handle.success" }, { action: cc.action })
-                    + (S.is(OperationSuccess)(a) && a.message ? "\n" + a.message : "")),
+                  : intl.formatMessage({ id: "handle.success" }, { action: cc.action }),
             onFailure: defaultFailureMessageHandler(
               hasCustomFailure ? intl.formatMessage({ id: customFailure }, cc.state) : cc.action,
               options?.errorRenderer as ErrorRenderer<E, Args> | undefined
             ),
-            stableToastId
+            stableToastId,
+            groupId: cc.id,
+            ...options?.showSpanInfo === false ? { showSpanInfo: options.showSpanInfo } : {}
           })(_, ...args)
       )
     }),
 
+  /**
+   * Stream-aware version of `withDefaultToast`. Use this as a combinator inside `streamFn`
+   * (or anywhere a `Stream` needs toast lifecycle handling) instead of `withDefaultToast`.
+   *
+   * Unlike `withDefaultToast` (which only wraps the initial `Effect`), this combinator:
+   * - Shows the "waiting" toast **before** the stream starts
+   * - Updates the waiting toast with progress text when `progress` is set and a new element arrives
+   * - Shows the "success" toast only **after** the stream drains fully without error
+   * - Shows the "failure" toast if the stream errors or fails
+   *
+   * Accepts either a `Stream<A, E, R>` or an `Effect<Stream<A, E, R>, EE, ER>` as input,
+   * so it works in both the `NonGenStream` and `StreamGen` overloads of `streamFn`.
+   *
+   * @example
+   * ```ts
+   * Command.streamFn("exportData")(
+   *   function*(arg, ctx) { return makeExportStream(arg.id) },
+   *   Command.withDefaultToastStream({
+   *     progress: (r) =>
+   *       AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress"
+   *         ? { text: `${r.value.completed}/${r.value.total}`, percentage: r.value.completed / r.value.total * 100 }
+   *         : undefined
+   *   })
+   * )
+   * ```
+   */
+  withDefaultToastStream: <A, E, R, Args extends Array<unknown>>(
+    options?: {
+      stableToastId?:
+        | undefined
+        | true
+        | string
+        | ((id: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => true | string | undefined)
+      errorRenderer?: (e: E, action: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | undefined
+      showSpanInfo?: false
+      onWaiting?:
+        | null
+        | undefined
+        | string
+        | ((id: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | null | undefined)
+      onSuccess?:
+        | null
+        | undefined
+        | string
+        | ((a: A, action: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | null | undefined)
+      /** Map each stream element to a progress label. When non-`undefined`, updates both the active waiting toast and the `CommandProgress` service (for CommandButton progress display). */
+      progress?: (result: AsyncResult.AsyncResult<A, E>) => Progress | undefined
+    }
+  ) =>
+  (
+    self: Stream.Stream<A, E, R> | Effect.Effect<Stream.Stream<A, E, R>, any, any>,
+    ...args: Args
+  ): Stream.Stream<A, E, R | I18n | Toast | CommandContext> => {
+    const rawStream: Stream.Stream<A, E, R> = Stream.isStream(self)
+      ? self
+      : Stream.unwrap(self)
+
+    return Stream.unwrap(Effect.gen(function*() {
+      const cc = yield* CommandContext
+      const { intl } = yield* I18n
+      const toast = yield* Toast
+
+      const customWaiting = cc.namespaced("waiting")
+      const hasCustomWaiting = !!intl.messages[customWaiting]
+      const customSuccess = cc.namespaced("success")
+      const hasCustomSuccess = !!intl.messages[customSuccess]
+      const customFailure = cc.namespaced("failure")
+      const hasCustomFailure = !!intl.messages[customFailure]
+
+      const stableToastId: string | undefined = options?.stableToastId
+        ? typeof options.stableToastId === "string"
+          ? options.stableToastId
+          : typeof options.stableToastId === "boolean"
+          ? cc.id
+          : typeof options.stableToastId === "function"
+          ? (() => {
+            const r = (options.stableToastId as (...a: any[]) => true | string | undefined)(cc.id, ...args)
+            if (typeof r === "string") return r
+            if (r === true) return cc.id
+            return undefined
+          })()
+          : undefined
+        : undefined
+
+      const baseTimeout = 3_000
+
+      const waitingMsg: string | null = options?.onWaiting === null
+        ? null
+        : typeof options?.onWaiting === "string"
+        ? options.onWaiting
+        : typeof options?.onWaiting === "function"
+        ? (options.onWaiting as (...a: any[]) => string | null | undefined)(cc.id, ...args) ?? null
+        : hasCustomWaiting
+        ? intl.formatMessage({ id: customWaiting }, cc.state)
+        : intl.formatMessage({ id: "handle.waiting" }, { action: cc.action })
+
+      const toastId: string | number | undefined = waitingMsg === null
+        ? stableToastId
+        : stableToastId ?? `wait-${Math.random().toString(36).slice(2)}`
+
+      const requestId: string = yield* Effect.currentSpan.pipe(
+        Effect.map((span) => span.traceId),
+        Effect.orElseSucceed(() => S.StringId.make())
+      )
+      const meta = { groupId: cc.id, requestId }
+
+      if (waitingMsg !== null) {
+        yield* toast.info(waitingMsg, { id: toastId!, timeout: Infinity, ...meta })
+      }
+
+      const failureHandler = defaultFailureMessageHandler<E, [], never, never>(
+        hasCustomFailure ? intl.formatMessage({ id: customFailure }, cc.state) : cc.action,
+        options?.errorRenderer as ErrorRenderer<E, []> | undefined
+      )
+
+      let lastValue: A | undefined = undefined
+      let didFail = false
+
+      const composed = rawStream.pipe(
+        Stream.tap((v) =>
+          Effect.gen(function*() {
+            lastValue = v
+            if (options?.progress !== undefined) {
+              const p = options.progress(AsyncResult.success(v, { waiting: true }))
+              if (p !== undefined) {
+                // Update CommandProgress so CommandButton progress indicator is also driven
+                yield* CommandProgress.use((s) => s.update(p))
+                if (toastId !== undefined) {
+                  const progressText = typeof p === "string" ? p : p.text
+                  const msg = waitingMsg ? `${waitingMsg}\n${progressText}` : progressText
+                  yield* toast.info(msg, { id: toastId, timeout: Infinity, ...meta })
+                }
+              }
+            }
+          })
+        ),
+        Stream.tapCause(Effect.fnUntraced(function*(cause) {
+          didFail = true
+          if (Cause.hasInterruptsOnly(cause)) {
+            if (toastId !== undefined) yield* toast.dismiss(toastId)
+            return
+          }
+
+          const spanInfo = options?.showSpanInfo !== false
+            ? yield* Effect.currentSpan.pipe(
+              Effect.map((span) => `\nTrace: ${span.traceId}\nSpan: ${span.spanId}`),
+              Effect.orElseSucceed(() => "")
+            )
+            : ""
+
+          const t = yield* failureHandler(Cause.findErrorOption(cause))
+          const opts = { timeout: baseTimeout * 2, ...meta }
+
+          if (typeof t === "object") {
+            const message = t.message + spanInfo
+            yield* t.level === "warn"
+              ? toast.warning(message, toastId !== undefined ? { ...opts, id: toastId } : opts)
+              : toast.error(message, toastId !== undefined ? { ...opts, id: toastId } : opts)
+          } else {
+            yield* toast.error(t + spanInfo, toastId !== undefined ? { ...opts, id: toastId } : opts)
+          }
+        }, Effect.uninterruptible)),
+        Stream.ensuring(Effect.suspend(() => {
+          if (didFail) return Effect.void
+
+          if (options?.onSuccess === null) return Effect.void
+
+          const successMsg: string | null = typeof options?.onSuccess === "string"
+            ? options.onSuccess
+            : typeof options?.onSuccess === "function"
+            ? (options.onSuccess as (...a: any[]) => string | null | undefined)(lastValue, cc.action, ...args) ?? null
+            : hasCustomSuccess
+            ? intl.formatMessage({ id: customSuccess }, cc.state)
+            : intl.formatMessage({ id: "handle.success" }, { action: cc.action })
+
+          if (successMsg === null) return Effect.void
+
+          return toast.success(
+            successMsg,
+            toastId !== undefined
+              ? { id: toastId, timeout: baseTimeout, ...meta }
+              : { timeout: baseTimeout, ...meta }
+          )
+        }))
+      )
+
+      return (toastId !== undefined
+        ? composed.pipe(Stream.provideService(CurrentToastId, CurrentToastId.of({ toastId })))
+        : composed) as unknown as Stream.Stream<A, E, R>
+    }))
+  },
+
   /** borrowing the idea from Families in Effect Atom */
   family: <T extends object, Arg, ArgIn = Arg>(
     maker: (arg: Arg) => T,
@@ -1936,7 +2509,11 @@ const unregisterWait = (id: string) => {
   }
 }
 
-const getStateValues = <const Id extends string, const I18nKey extends string, State extends IntlRecord | undefined>(
+const getStateValues = <
+  const Id extends string,
+  const I18nKey extends string,
+  State extends IntlRecord | undefined
+>(
   options?: FnOptions<Id, I18nKey, State>
 ): ComputedRef<State> => {
   const state_ = options?.state
@@ -1948,11 +2525,18 @@ const getStateValues = <const Id extends string, const I18nKey extends string, S
 
 // class preserves JSDoc throughout..
 export class CommanderImpl<RT, RTHooks> {
+  private readonly rt: Context.Context<RT>
+  private readonly intl: I18n
+  private readonly hooks: Layer.Layer<RTHooks, never, RT>
+
   constructor(
-    private readonly rt: Context.Context<RT>,
-    private readonly intl: I18n,
-    private readonly hooks: Layer.Layer<RTHooks, never, RT>
+    rt: Context.Context<RT>,
+    intl: I18n,
+    hooks: Layer.Layer<RTHooks, never, RT>
   ) {
+    this.rt = rt
+    this.intl = intl
+    this.hooks = hooks
   }
 
   readonly makeContext = <const Id extends string, const I18nKey extends string = Id>(
@@ -2109,6 +2693,7 @@ export class CommanderImpl<RT, RTHooks> {
         const runFork = Effect.runForkWith(rt)
 
         const handle = Object.assign((arg: Arg) => {
+          arg = toRaw(arg) // remove outside vue proxy bs
           // we capture the call site stack here
           const limit = Error.stackTraceLimit
           Error.stackTraceLimit = 2
@@ -2139,15 +2724,17 @@ export class CommanderImpl<RT, RTHooks> {
             }
           }
 
-          const command = currentState.pipe(Effect.flatMap((state) =>
-            Effect.withSpan(
+          const command = currentState.pipe(Effect.flatMap((state) => {
+            const rawArg = deepToRaw(arg)
+            const rawState = deepToRaw(state)
+            return Effect.withSpan(
               exec(arg, { ...context.value, state } as any),
               id,
               {
                 captureStackTrace,
                 attributes: {
-                  input: arg,
-                  state,
+                  input: rawArg,
+                  state: rawState,
                   action: initialContext.action,
                   label: initialContext.label,
                   id: initialContext.id,
@@ -2155,7 +2742,7 @@ export class CommanderImpl<RT, RTHooks> {
                 }
               }
             )
-          ))
+          }))
 
           return runFork(command)
         }, { action, label })
@@ -2174,6 +2761,8 @@ export class CommanderImpl<RT, RTHooks> {
 
           /** reactive */
           result,
+          /** always undefined for non-stream commands */
+          progress: undefined,
           /** reactive */
           waiting,
           /** reactive */
@@ -2281,8 +2870,9 @@ export class CommanderImpl<RT, RTHooks> {
     options?: FnOptions<Id, I18nKey, State>
   ): Commander.Gen<RT | RTHooks, Id, I18nKey, State> & Commander.NonGen<RT | RTHooks, Id, I18nKey, State> & {
     state: Context.Service<`Commander.Command.${Id}.state`, State>
-  } =>
-    Object.assign(
+  } => {
+    const resolvedId: Id = typeof id === "string" ? id : id.id
+    return Object.assign(
       (
         fn: any,
         ...combinators: any[]
@@ -2293,7 +2883,7 @@ export class CommanderImpl<RT, RTHooks> {
         const errorDef = new Error()
         Error.stackTraceLimit = limit
 
-        return this.makeCommand(id, options, errorDef)(
+        return this.makeCommand(resolvedId, options, errorDef)(
           Effect.fnUntraced(
             // fnUntraced only supports generators as first arg, so we convert to generator if needed
             isGeneratorFunction(fn) ? fn : function*(...args) {
@@ -2303,15 +2893,329 @@ export class CommanderImpl<RT, RTHooks> {
           ) as any
         )
       },
-      makeBaseInfo(typeof id === "string" ? id : id.id, options),
+      makeBaseInfo(resolvedId, options),
+      {
+        state: Context.Service<`Commander.Command.${Id}.state`, State>(
+          `Commander.Command.${resolvedId}.state`
+        )
+      }
+    )
+  }
+
+  /**
+   * Internal factory for stream-backed commands. Accepts a handler that returns a `Stream` directly.
+   * Services (`CommandContext`, `stateTag`) are provided to the stream via `Stream.provideServiceEffect`.
+   */
+  readonly makeStreamCommand = <
+    const Id extends string,
+    const State extends IntlRecord | undefined,
+    const I18nKey extends string = Id
+  >(
+    id_: Id | { id: Id },
+    options?: FnOptions<Id, I18nKey, State>,
+    errorDef?: Error
+  ) => {
+    const id = typeof id_ === "string" ? id_ : id_.id
+    const state = getStateValues(options)
+
+    return Object.assign(
+      <Arg, SA, SE, SR>(
+        handler: (arg: Arg, ctx: Commander.CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>
+      ) => {
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 2
+        const localErrorDef = new Error()
+        Error.stackTraceLimit = limit
+        if (!errorDef) {
+          errorDef = localErrorDef
+        }
+
+        const key = `Commander.Command.${id}.state` as const
+        const stateTag = Context.Service<typeof key, State>(key)
+
+        const makeContext_ = () => this.makeContext(id, { ...options, state: state?.value })
+        const initialContext = makeContext_()
+        const context = computed(() => makeContext_())
+        const action = computed(() => context.value.action)
+        const label = computed(() => context.value.label)
+
+        const currentState = Effect.sync(() => state.value)
+
+        // Reactive ref driven by the CommandProgress service — updated imperatively
+        // from inside the stream via `Command.mapProgress(fn)` or `Command.updateProgress(p)`.
+        const progressRef = ref<Progress | undefined>(undefined)
+        const commandProgressService = {
+          update: (p: Progress | undefined) =>
+            Effect.sync(() => {
+              progressRef.value = p
+            })
+        }
+
+        const streamErrorReporter = <A, E, R>(self: Stream.Stream<A, E, R>) =>
+          self.pipe(
+            Stream.tapCause(
+              Effect.fnUntraced(function*(cause) {
+                if (Cause.hasInterruptsOnly(cause)) {
+                  console.info(`Interrupted while trying to ${id}`)
+                  return
+                }
+
+                const fail = Cause.findErrorOption(cause)
+                if (Option.isSome(fail)) {
+                  const message = `Failure trying to ${id}`
+                  yield* reportMessage(message, {
+                    action: id,
+                    error: fail.value
+                  })
+                  return
+                }
+
+                const ctx = yield* CommandContext
+                const extra = {
+                  action: ctx.action,
+                  message: `Unexpected Error trying to ${id}`
+                }
+                yield* reportRuntimeError(cause, extra)
+              }, Effect.uninterruptible)
+            )
+          )
+
+        const theStreamHandler = (arg: Arg, ctx: Commander.CommandContextLocal2<Id, I18nKey, State>) =>
+          handler(arg, ctx).pipe(
+            streamErrorReporter,
+            Stream.provideService(CommandProgress, commandProgressService),
+            Stream.provideServiceEffect(stateTag, currentState),
+            Stream.provideServiceEffect(CommandContext, Effect.sync(() => makeContext_()))
+          )
+
+        const waitId = options?.waitKey ? options.waitKey(id) : undefined
+        const blockId = options?.blockKey ? options.blockKey(id) : undefined
+
+        const [result, exec_] = asStreamResult(theStreamHandler)
+
+        const exec = Effect
+          .fnUntraced(
+            function*(...args: [any, any]) {
+              if (waitId !== undefined) registerWait(waitId)
+              if (blockId !== undefined && blockId !== waitId) {
+                registerWait(blockId)
+              }
+              return yield* exec_(...args)
+            },
+            Effect.onExit(() =>
+              Effect.sync(() => {
+                if (waitId !== undefined) unregisterWait(waitId)
+                if (blockId !== undefined && blockId !== waitId) {
+                  unregisterWait(blockId)
+                }
+              })
+            )
+          )
+
+        const waiting = waitId !== undefined
+          ? computed(() => result.value.waiting || (waitState.value[waitId] ?? 0) > 0)
+          : computed(() => result.value.waiting)
+
+        const blocked = blockId !== undefined
+          ? computed(() => waiting.value || (waitState.value[blockId] ?? 0) > 0)
+          : computed(() => waiting.value)
+
+        const computeAllowed = options?.allowed
+        const allowed = computeAllowed ? computed(() => computeAllowed(id, state)) : true
+
+        const rt = Effect.context<RT | RTHooks>().pipe(Effect.provide(this.hooks)).pipe(Effect.runSyncWith(this.rt))
+        const runFork = Effect.runForkWith(rt)
+
+        const progress = progressRef
+
+        const handle = Object.assign((arg: Arg) => {
+          arg = toRaw(arg)
+          progressRef.value = undefined // reset progress on new invocation
+          const limit = Error.stackTraceLimit
+          Error.stackTraceLimit = 2
+          const errorCall = new Error()
+          Error.stackTraceLimit = limit
+
+          let cache: false | string = false
+          const captureStackTrace = () => {
+            if (cache !== false) {
+              return cache
+            }
+            if (errorCall.stack) {
+              const stackDef = errorDef!.stack!.trim().split("\n")
+              const stackCall = errorCall.stack.trim().split("\n")
+              let endStackDef = stackDef.slice(2).join("\n").trim()
+              if (!endStackDef.includes(`(`)) {
+                endStackDef = endStackDef.replace(/at (.*)/, "at ($1)")
+              }
+              let endStackCall = stackCall.slice(2).join("\n").trim()
+              if (!endStackCall.includes(`(`)) {
+                endStackCall = endStackCall.replace(/at (.*)/, "at ($1)")
+              }
+              cache = `${endStackDef}\n${endStackCall}`
+              return cache
+            }
+          }
+
+          const command = currentState.pipe(Effect.flatMap((state) => {
+            const rawArg = deepToRaw(arg)
+            const rawState = deepToRaw(state)
+            return Effect.withSpan(
+              exec(arg, { ...context.value, state } as any),
+              id,
+              {
+                captureStackTrace,
+                attributes: {
+                  input: rawArg,
+                  state: rawState,
+                  action: initialContext.action,
+                  label: initialContext.label,
+                  id: initialContext.id,
+                  i18nKey: initialContext.i18nKey
+                }
+              }
+            )
+          }))
+
+          return runFork(command as any)
+        }, { action, label })
+
+        return reactive({
+          id,
+          i18nKey: initialContext.i18nKey,
+          namespace: initialContext.namespace,
+          namespaced: initialContext.namespaced,
+          result,
+          /** reactive – progress driven by `Command.mapProgress` or `Command.updateProgress` inside the stream */
+          progress,
+          waiting,
+          blocked,
+          allowed,
+          action,
+          label,
+          state,
+          handle
+        })
+      },
+      { id }
+    )
+  }
+
+  /**
+   * Define a stream-backed Command for handling user actions.
+   *
+   * Like `fn`, but the body generator (or function) must **return** a `Stream` rather than
+   * an `Effect`. The command's `waiting` state stays `true` while the stream is running and
+   * is set to `false` once it terminates. The reactive `result` ref is updated for every
+   * value emitted by the stream.
+   *
+   * Three handler shapes are accepted:
+   * 1. **Generator returning a Stream** (primary) — may yield Effects freely before returning the stream:
+   *    ```ts
+   *    Command.streamFn("exportData")(
+   *      function*(arg, ctx) {
+   *        const token = yield* getAuthToken
+   *        return Stream.fromEffect(startExport(token, arg.id)).pipe(
+   *          Stream.flatMap((job) => pollProgress(job.id))
+   *        )
+   *      }
+   *    )
+   *    ```
+   * 2. **Function returning a Stream directly**: `(arg, ctx) => Stream.make(1, 2, 3)`
+   * 3. **Function returning `Effect<Stream>`**: `(arg, ctx) => Effect.map(setup, (s) => s.stream)`
+   *
+   * @param id The internal identifier for the action (used for tracing and i18n lookup).
+   * @param options Same options as `fn` (`state`, `blockKey`, `waitKey`, `allowed`, `i18nCustomKey`).
+   *
+   * **Progress** — use `Command.mapProgress(fn)` as a stream pipe operator; the mapper receives
+   * `AsyncResult<A, E>` (each value wrapped as `AsyncResult.success(v, { waiting: true })`),
+   * matching the same shape as CommandButton’s `:progress-map` prop. Or call
+   * `Command.updateProgress(p)` for imperative control:
+   *
+   * ```ts
+   * // mapProgress as a combinator arg (outside the handler):
+   * Command.streamFn("exportData")(
+   *   function*(arg, ctx) { return makeExportStream(arg.id) },
+   *   (s) => s.pipe(Command.mapProgress((r) => AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress" ? { text: `${r.value.completed}/${r.value.total}` } : undefined))
+   * )
+   *
+   * // Or inline inside the handler body:
+   * Command.streamFn("exportData")(function*(arg, ctx) {
+   *   return makeExportStream(arg.id).pipe(Command.mapProgress((r) => AsyncResult.isSuccess(r) ? ... : undefined))
+   * })
+   * ```
+   *
+   * **Pipeable combinators** — the 2nd–Nth args follow the same pattern as `fn`: each combinator
+   * receives `(stream, arg, ctx)` and returns a transformed stream:
+   * ```ts
+   * Command.streamFn("exportData")(
+   *   handler,
+   *   (s, arg, ctx) => s.pipe(Command.mapProgress(fn), Stream.take(100))
+   * )
+   * ```
+   *
+   * **Returned Properties**: `action`, `label`, `result`, `progress`, `waiting`, `blocked`,
+   * `allowed`, `handle`, `i18nKey`, `namespace`, `namespaced`.
+   */
+  streamFn = <
+    const Id extends string,
+    const State extends IntlRecord = IntlRecord,
+    const I18nKey extends string = Id
+  >(
+    id: Id | { id: Id },
+    options?: FnOptions<Id, I18nKey, State>
+  ):
+    & Commander.StreamGen<RT | RTHooks, Id, I18nKey, State>
+    & Commander.NonGenStream<RT | RTHooks, Id, I18nKey, State>
+    & {
+      state: Context.Service<`Commander.Command.${Id}.state`, State>
+    } =>
+  {
+    const resolvedId = typeof id === "string" ? id : id.id
+
+    type StreamOrEffect = Stream.Stream<any, any, any> | Effect.Effect<Stream.Stream<any, any, any>, any, any>
+
+    const toRawHandler = (fn: any): (arg: any, ctx: any) => StreamOrEffect => {
+      if (isGeneratorFunction(fn)) {
+        return Effect.fnUntraced(function*(arg: any, ctx: any) {
+          return yield* (fn as (arg: any, ctx: any) => Generator<any, Stream.Stream<any, any, any>>)(arg, ctx)
+        })
+      }
+      return fn
+    }
+
+    const toFinalStream = (value: StreamOrEffect): Stream.Stream<any, any, any> =>
+      Stream.isStream(value) ? value : Stream.unwrap(value as Effect.Effect<Stream.Stream<any, any, any>, any, any>)
+
+    return Object.assign(
+      (fn: any, ...combinators: Array<(s: any, arg: any, ctx: any) => any>): any => {
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 2
+        const errorDef = new Error()
+        Error.stackTraceLimit = limit
+
+        const rawHandler = toRawHandler(fn)
+        const handler = (arg: any, ctx: any) => {
+          let current: any = rawHandler(arg, ctx)
+          for (const combinator of combinators) {
+            current = combinator(current, arg, ctx)
+          }
+          return toFinalStream(current)
+        }
+
+        return this.makeStreamCommand(id, options, errorDef)(handler)
+      },
+      makeBaseInfo(resolvedId, options),
       {
         state: Context.Service<`Commander.Command.${Id}.state`, State>(
-          `Commander.Command.${typeof id === "string" ? id : id.id}.state`
+          `Commander.Command.${resolvedId}.state`
         )
       }
     )
+  }
 
   /** @deprecated */
+
   alt2: <
     const Id extends string,
     MutArg,
@@ -2403,6 +3307,46 @@ export class CommanderImpl<RT, RTHooks> {
    * **User Feedback**: Use the `withDefaultToast` helper for status notifications, or render
    * the `result` inline for custom UI feedback.
    */
+  streamWrap = <
+    const Id extends string,
+    Arg,
+    SA,
+    SE,
+    SR,
+    const State extends IntlRecord = IntlRecord,
+    I18nKey extends string = Id
+  >(
+    handler: (arg: Arg, ctx: Commander.CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>,
+    id: Id,
+    options?: FnOptions<Id, I18nKey, State>
+  ): Commander.StreamerWrap<RT | RTHooks, Id, I18nKey, State, Arg, SA, SE, SR> => {
+    return Object.assign(
+      (...combinators: any[]): any => {
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 2
+        const errorDef = new Error()
+        Error.stackTraceLimit = limit
+        return this.makeStreamCommand(id, options, errorDef)(
+          combinators.length === 0
+            ? handler
+            : (arg: Arg, ctx: Commander.CommandContextLocal2<Id, I18nKey, State>) => {
+              let current: any = handler(arg, ctx)
+              for (const combinator of combinators) {
+                current = combinator(current, arg, ctx)
+              }
+              return current
+            }
+        )
+      },
+      makeBaseInfo(id, options),
+      {
+        state: Context.Service<`Commander.Command.${Id}.state`, State>(
+          `Commander.Command.${id}.state`
+        )
+      }
+    )
+  }
+
   wrap = <
     const Id extends string,
     Arg,
@@ -2416,8 +3360,9 @@ export class CommanderImpl<RT, RTHooks> {
       | { mutate: (arg: Arg) => Effect.Effect<A, E, R>; id: Id }
       | ((arg: Arg) => Effect.Effect<A, E, R>) & { id: Id },
     options?: FnOptions<Id, I18nKey, State>
-  ): Commander.CommanderWrap<RT | RTHooks, Id, I18nKey, State, Arg, A, E, R> =>
-    Object.assign(
+  ): Commander.CommanderWrap<RT | RTHooks, Id, I18nKey, State, Arg, A, E, R> => {
+    const callMutation = mutation
+    return Object.assign(
       (
         ...combinators: any[]
       ): any => {
@@ -2426,9 +3371,11 @@ export class CommanderImpl<RT, RTHooks> {
         Error.stackTraceLimit = 2
         const errorDef = new Error()
         Error.stackTraceLimit = limit
-        const mutate = "mutate" in mutation ? mutation.mutate : mutation
+        const mutate = "mutate" in callMutation
+          ? callMutation.mutate
+          : callMutation
 
-        return this.makeCommand(mutation.id, options, errorDef)(
+        return this.makeCommand(callMutation.id, options, errorDef)(
           Effect.fnUntraced(
             // fnUntraced only supports generators as first arg, so we convert to generator if needed
             isGeneratorFunction(mutate) ? mutate : function*(arg: Arg) {
@@ -2438,13 +3385,14 @@ export class CommanderImpl<RT, RTHooks> {
           ) as any
         )
       },
-      makeBaseInfo(mutation.id, options),
+      makeBaseInfo(callMutation.id, options),
       {
         state: Context.Service<`Commander.Command.${Id}.state`, State>(
-          `Commander.Command.${mutation.id}.state`
+          `Commander.Command.${callMutation.id}.state`
         )
       }
     )
+  }
 }
 
 // @effect-diagnostics-next-line missingEffectServiceDependency:off