@mikrojs/native 0.20.1 → 0.21.0-next.20260913195055

package/src/mik_observable.cpp

@@ -4,11 +4,21 @@
  *
  * Classes registered:
  *   - Observable: constructor(cb), subscribe(observer), pipe(...ops),
- *                 static from(src), static withEmitters()
+ *                 static withEmitters()
+ *                 (cb may return a function; it is registered as a teardown)
+ *   - from(src): module function, promise or iterable -> Observable
+ *   - of(...values): module function, from() over the argument array
  *   - Subscriber (internal handle passed to subscribe callback): next, complete,
  *                 addTeardown, closed
  *   - Subscription: unsubscribe
  *
+ * A second module, mikro/observable/operators, holds every operator (map,
+ * filter, take, timer, switchMap, debounceTime, ...). It is loaded lazily
+ * through the C-module table in modules.cpp, so runtimes that never import
+ * it pay nothing. Per-subscription operator state lives in a C struct and
+ * upstream subscribers dispatch straight into C handlers, so a chain costs no
+ * JS closures per value or per subscription and no bytecode per app.
+ *
  * Error semantics: a throw inside an observer, operator, or teardown callback
  * is caught at the dispatch boundary only to report it and apply the app's
  * onPanic policy; it is an application crash like any other uncaught error.
@@ -53,6 +63,7 @@
 #include <cstdint>
 #include <vector>
 
+#include "mikrojs/platform.h"
 #include "mikrojs/private.h"
 #include "mikrojs/utils.h"
 
@@ -95,7 +106,14 @@ struct SubscriberData {
     JSValue observer;
     JSValue next_fn;
     JSValue complete_fn;
+    /* Teardowns are functions, or upstream Subscriber objects that are
+     * unsubscribed in place of a call (see run_teardown_entry). */
     std::vector<JSValue> teardowns;
+    /* Set for a native operator's upstream subscriber: deliveries go to
+     * op_on_next/op_on_complete with this state instead of next_fn/complete_fn.
+     * Released once the subscriber closes. */
+    JSValue op_state = JS_UNDEFINED;
+    int op_index = 0;
 };
 
 struct SubscriptionData {
@@ -123,15 +141,19 @@ static void panic(JSContext* ctx, JSValue exception) {
     JS_FreeValue(ctx, exception);
 }
 
-/* Call `fn(argv...)` synchronously; a throw panics. Caller is not informed. */
-static void run_safely(JSContext* ctx, JSValue fn, int argc, JSValue* argv) {
+/* Call `fn(argv...)` synchronously and return its result (owned); a throw
+ * panics and yields JS_EXCEPTION. */
+static JSValue call_or_panic(JSContext* ctx, JSValueConst fn, int argc, JSValueConst* argv) {
     JSValue ret = JS_Call(ctx, fn, JS_UNDEFINED, argc, argv);
     if (JS_IsException(ret)) {
-        JSValue exc = JS_GetException(ctx);
-        panic(ctx, exc);
-    } else {
-        JS_FreeValue(ctx, ret);
+        panic(ctx, JS_GetException(ctx));
     }
+    return ret;
+}
+
+/* Call `fn(argv...)` synchronously; a throw panics. Caller is not informed. */
+static void run_safely(JSContext* ctx, JSValue fn, int argc, JSValue* argv) {
+    JS_FreeValue(ctx, call_or_panic(ctx, fn, argc, argv));
 }
 
 /* Same panic-on-throw semantics as run_safely, for invoke-by-method calls
@@ -148,21 +170,63 @@ static void invoke_safely(JSContext* ctx, JSValueConst this_val, JSAtom method,
     }
 }
 
+static void close_subscriber(JSContext* ctx, SubscriberData* d);
+static bool op_teardown(JSContext* ctx, JSValueConst entry);
+
+/* A teardown entry is a function to call, an upstream subscriber to close, or
+ * an operator state whose timer and inner subscription end with it. */
+static void run_teardown_entry(JSContext* ctx, JSValueConst entry) {
+    auto* up = static_cast<SubscriberData*>(JS_GetOpaque(entry, subscriber_class_id));
+    if (up) {
+        close_subscriber(ctx, up);
+    } else if (!op_teardown(ctx, entry)) {
+        run_safely(ctx, entry, 0, nullptr);
+    }
+}
+
 /* Run all registered teardowns in reverse insertion order. A throw panics,
  * but the remaining teardowns still run: they release resources for work
  * that is already ending. */
 static void run_teardowns(JSContext* ctx, SubscriberData* d) {
     /* Swap into a local list. If a teardown calls addTeardown synchronously,
      * the SubscriberData.closed flag is already true so addTeardown fires the
-     * new callback immediately (handled in subscriber_add_teardown). */
+     * new callback immediately (handled in add_teardown). */
     std::vector<JSValue> list;
     list.swap(d->teardowns);
     for (auto it = list.rbegin(); it != list.rend(); ++it) {
-        run_safely(ctx, *it, 0, nullptr);
+        run_teardown_entry(ctx, *it);
         JS_FreeValue(ctx, *it);
     }
 }
 
+/* Register `entry` (owned) as a teardown; on a closed subscriber it runs at
+ * once instead, so a late registration can never leak. */
+static void add_teardown(JSContext* ctx, SubscriberData* d, JSValue entry) {
+    if (d->closed) {
+        run_teardown_entry(ctx, entry);
+        JS_FreeValue(ctx, entry);
+    } else {
+        d->teardowns.push_back(entry);
+    }
+}
+
+static void release_op_state(JSContext* ctx, SubscriberData* d) {
+    JSValue state = d->op_state;
+    d->op_state = JS_UNDEFINED;
+    JS_FreeValue(ctx, state);
+}
+
+/* Silent close: teardowns run, the observer is not told. Idempotent. A
+ * pending complete owns the close: its queued entry delivers complete_fn +
+ * teardowns, matching the recursive-dispatch order where the complete had
+ * already run before unsubscribe could. */
+static void close_subscriber(JSContext* ctx, SubscriberData* d) {
+    if (d->closed || d->complete_pending) return;
+    d->closed = true;
+    run_teardowns(ctx, d);
+    release_op_state(ctx, d);
+}
+
 /* ── Dispatch trampoline ────────────────────────────────────────── */
 
 static MIKObservableDispatch* dispatch_state(JSContext* ctx) {
@@ -178,9 +242,18 @@ static bool dispatch_stopped(JSContext* ctx) {
     return mik_rt && MIK_IsStopRequested(mik_rt);
 }
 
+static void op_on_next(JSContext* ctx, JSValueConst state, int index, JSValueConst value);
+static void op_on_complete(JSContext* ctx, JSValueConst state, int index, SubscriberData* from);
+
 /* Deliver a value to the subscriber's next handler. `value` is borrowed. */
 static void deliver_next(JSContext* ctx, SubscriberData* d, JSValue value) {
-    if (!JS_IsUndefined(d->next_fn)) {
+    if (!JS_IsUndefined(d->op_state)) {
+        /* Hold the state: the handler may close this subscriber, which
+         * releases d->op_state. */
+        JSValue state = JS_DupValue(ctx, d->op_state);
+        op_on_next(ctx, state, d->op_index, value);
+        JS_FreeValue(ctx, state);
+    } else if (!JS_IsUndefined(d->next_fn)) {
         run_safely(ctx, d->next_fn, 1, &value);
     }
 }
@@ -188,10 +261,15 @@ static void deliver_next(JSContext* ctx, SubscriberData* d, JSValue value) {
 static void deliver_complete(JSContext* ctx, SubscriberData* d) {
     d->complete_pending = false;
     d->closed = true;
-    if (!JS_IsUndefined(d->complete_fn)) {
+    if (!JS_IsUndefined(d->op_state)) {
+        JSValue state = JS_DupValue(ctx, d->op_state);
+        op_on_complete(ctx, state, d->op_index, d);
+        JS_FreeValue(ctx, state);
+    } else if (!JS_IsUndefined(d->complete_fn)) {
         run_safely(ctx, d->complete_fn, 0, nullptr);
     }
     run_teardowns(ctx, d);
+    release_op_state(ctx, d);
 }
 
 /* Drain queued deliveries in FIFO order. Deliveries may enqueue more; the
@@ -231,6 +309,7 @@ static void subscriber_finalizer(JSRuntime* rt, JSValue val) {
     JS_FreeValueRT(rt, d->observer);
     JS_FreeValueRT(rt, d->next_fn);
     JS_FreeValueRT(rt, d->complete_fn);
+    JS_FreeValueRT(rt, d->op_state);
     for (auto& td : d->teardowns) JS_FreeValueRT(rt, td);
     delete d;
 }
@@ -241,6 +320,7 @@ static void subscriber_gc_mark(JSRuntime* rt, JSValue val, JS_MarkFunc* mark_fun
     JS_MarkValue(rt, d->observer, mark_func);
     JS_MarkValue(rt, d->next_fn, mark_func);
     JS_MarkValue(rt, d->complete_fn, mark_func);
+    JS_MarkValue(rt, d->op_state, mark_func);
     for (auto& td : d->teardowns) JS_MarkValue(rt, td, mark_func);
 }
 
@@ -306,12 +386,7 @@ static JSValue subscriber_add_teardown(JSContext* ctx, JSValueConst this_val, in
     if (argc < 1 || !JS_IsFunction(ctx, argv[0])) {
         return JS_ThrowTypeError(ctx, "addTeardown: argument must be a function");
     }
-    if (d->closed) {
-        /* Late teardown registration — fire immediately to avoid leaks. */
-        run_safely(ctx, argv[0], 0, nullptr);
-    } else {
-        d->teardowns.push_back(JS_DupValue(ctx, argv[0]));
-    }
+    add_teardown(ctx, d, JS_DupValue(ctx, argv[0]));
     return JS_UNDEFINED;
 }
 
@@ -360,14 +435,9 @@ static JSValue subscription_unsubscribe(JSContext* ctx, JSValueConst this_val, i
     if (!sd) return JS_EXCEPTION;
     auto* sub = static_cast<SubscriberData*>(JS_GetOpaque(sd->subscriber_value,
                                                           subscriber_class_id));
-    /* A pending complete owns the close: its queued entry delivers
-     * complete_fn + teardowns, matching the recursive-dispatch order where
-     * the complete had already run before unsubscribe could. */
-    if (!sub || sub->closed || sub->complete_pending) return JS_UNDEFINED;
-    sub->closed = true;
     /* unsubscribe() is silent — does NOT call observer.complete().
      * Only natural producer-driven completion fires observer.complete(). */
-    run_teardowns(ctx, sub);
+    if (sub) close_subscriber(ctx, sub);
     return JS_UNDEFINED;
 }
 
@@ -411,6 +481,43 @@ static JSClassDef observable_class_def = {
     nullptr,
 };
 
+/* Run the producer against a freshly built subscriber. Sync emission is
+ * allowed: the producer may call next/complete inside the callback, so the
+ * subscriber may already be closed on return; idempotent unsubscribe handles
+ * it. Returns subscriber_val (ownership passes back), or JS_EXCEPTION with it
+ * freed. */
+static JSValue start_subscriber(JSContext* ctx, JSValueConst subscribe_cb, JSValue subscriber_val,
+                                SubscriberData* d) {
+    JSValue cb_result = JS_Call(ctx, subscribe_cb, JS_UNDEFINED, 1, &subscriber_val);
+    if (JS_IsException(cb_result)) {
+        /* Producer setup threw — bubble up, but release whatever it already
+         * acquired first. No Subscription reaches the caller, so a teardown
+         * skipped here can never run: the handle it would close is
+         * unreachable for the rest of the runtime's life. Park the pending
+         * exception while the teardowns run, since they are JS calls and
+         * must not inherit it, then restore it for the caller.
+         * A queued completion is different: that entry owns the close and
+         * runs the teardowns when it drains. */
+        if (!d->complete_pending) {
+            d->closed = true;
+            JSValue pending = JS_GetException(ctx);
+            run_teardowns(ctx, d);
+            JS_Throw(ctx, pending);
+        }
+        JS_FreeValue(ctx, subscriber_val);
+        return cb_result;
+    }
+    if (JS_IsFunction(ctx, cb_result)) {
+        /* A returned function is a teardown, exactly as if the producer had
+         * passed it to addTeardown() last (owned; runs now if setup already
+         * closed the subscriber). */
+        add_teardown(ctx, d, cb_result);
+    } else {
+        JS_FreeValue(ctx, cb_result);
+    }
+    return subscriber_val;
+}
+
 /* Run a subscribe callback against an observer, return a Subscription.
  * subscribe_cb is borrowed (not freed). Observer is borrowed.
  * Used by both Observable.prototype.subscribe and the static factories. */
@@ -461,34 +568,10 @@ static JSValue subscribe_with_callback(JSContext* ctx, JSValueConst subscribe_cb
     };
     JS_SetOpaque(subscriber_val, d);
 
-    /* Sync emission is allowed: producer may call next/complete inside the
-     * subscribe callback. The Subscription returned to the caller may already
-     * be in a closed state by the time we return it — that's fine, idempotent
-     * unsubscribe handles it. */
-    JSValue cb_result = JS_Call(ctx, subscribe_cb, JS_UNDEFINED, 1, &subscriber_val);
-    if (JS_IsException(cb_result)) {
-        /* Producer setup threw — bubble up, but release whatever it already
-         * acquired first. No Subscription reaches the caller, so a teardown
-         * skipped here can never run: the handle it would close is
-         * unreachable for the rest of the runtime's life. Park the pending
-         * exception while the teardowns run, since they are JS calls and
-         * must not inherit it, then restore it for the caller.
-         * A queued completion is different: that entry owns the close and
-         * runs the teardowns when it drains. */
-        if (!d->complete_pending) {
-            d->closed = true;
-            JSValue pending = JS_GetException(ctx);
-            run_teardowns(ctx, d);
-            JS_Throw(ctx, pending);
-        }
-        JS_FreeValue(ctx, subscriber_val);
-        return cb_result;
-    }
-    JS_FreeValue(ctx, cb_result);
-
+    subscriber_val = start_subscriber(ctx, subscribe_cb, subscriber_val, d);
+    if (JS_IsException(subscriber_val)) return subscriber_val;
     return make_subscription(ctx, subscriber_val);
 }
-
 static JSValue observable_subscribe(JSContext* ctx, JSValueConst this_val, int argc,
                                     JSValueConst* argv) {
     auto* d = static_cast<ObservableData*>(JS_GetOpaque2(ctx, this_val, observable_class_id));
@@ -526,7 +609,7 @@ static JSValue observable_constructor(JSContext* ctx, JSValueConst new_target, i
     return obj;
 }
 
-/* ── Observable.from ─────────────────────────────────────────────── */
+/* ── from / of ────────────────────────────────────────────────────── */
 
 /* Build an Observable from an arbitrary subscribe callback (C function). */
 static JSValue make_observable_with_cb(JSContext* ctx, JSValue subscribe_cb_taking_ownership) {
@@ -596,7 +679,7 @@ static JSValue iterator_next(JSContext* ctx, JSValueConst iterator, bool* done)
     return value;
 }
 
-/* Helper: Observable.from(iterable) — sync drain. The iterable is captured
+/* Helper: from(iterable) — sync drain. The iterable is captured
  * via a small wrapper object so the C function can recover it on subscribe. */
 
 /* Closure data attached to a from-iterable subscribe callback. */
@@ -749,17 +832,11 @@ static JSValue observable_from(JSContext* ctx, JSValueConst this_val, int argc,
                                JSValueConst* argv) {
     (void)this_val;
     if (argc < 1) {
-        return JS_ThrowTypeError(ctx, "Observable.from: requires a source argument");
+        return JS_ThrowTypeError(ctx, "from: requires a source argument");
     }
     JSValueConst src = argv[0];
 
-    /* (1) Already an Observable — passthrough. */
-    if (JS_IsObject(src) &&
-        JS_GetOpaque(src, observable_class_id) != nullptr) {
-        return JS_DupValue(ctx, src);
-    }
-
-    /* (2) PromiseLike — has a callable .then */
+    /* (1) PromiseLike — has a callable .then */
     if (JS_IsObject(src)) {
         JSValue then_method = JS_GetPropertyStr(ctx, src, "then");
         bool is_thenable = JS_IsFunction(ctx, then_method);
@@ -776,7 +853,7 @@ static JSValue observable_from(JSContext* ctx, JSValueConst this_val, int argc,
         }
     }
 
-    /* (3) Iterable — has @@iterator. */
+    /* (2) Iterable — has @@iterator. */
     if (JS_IsObject(src) || JS_IsString(src)) {
         JSValue iter_test = get_iterator(ctx, src);
         if (!JS_IsException(iter_test)) {
@@ -795,8 +872,22 @@ static JSValue observable_from(JSContext* ctx, JSValueConst this_val, int argc,
         JS_GetException(ctx);
     }
 
-    return JS_ThrowTypeError(
-        ctx, "Observable.from: source must be a Promise, Iterable, or Observable");
+    return JS_ThrowTypeError(ctx, "from: source must be a Promise or an Iterable");
+}
+
+/* of(...values): from() over the argument array. */
+static JSValue observable_of(JSContext* ctx, JSValueConst this_val, int argc,
+                             JSValueConst* argv) {
+    (void)this_val;
+    std::vector<JSValue> owned;
+    owned.reserve(argc);
+    for (int i = 0; i < argc; i++) owned.push_back(JS_DupValue(ctx, argv[i]));
+    /* Takes ownership of the values, and frees them itself on failure. */
+    JSValue values = JS_NewArrayFrom(ctx, argc, owned.data());
+    if (JS_IsException(values)) return values;
+    JSValue result = observable_from(ctx, JS_UNDEFINED, 1, &values);
+    JS_FreeValue(ctx, values);
+    return result;
 }
 
 /* ── Observable.withEmitters ────────────────────────────────────── */
@@ -961,27 +1052,37 @@ static JSValue multicast_emit_complete(JSContext* ctx, JSValueConst this_val, in
     return JS_UNDEFINED;
 }
 
-static JSValue observable_with_emitters(JSContext* ctx, JSValueConst this_val, int argc,
-                                        JSValueConst* argv) {
-    (void)this_val;
-    (void)argc;
-    (void)argv;
-
+/* The {observable, next, complete} triple behind withEmitters(). Returns -1
+ * with an exception pending; on success the caller owns all three values. */
+static int multicast_new(JSContext* ctx, JSValue* observable, JSValue* next,
+                         JSValue* complete) {
     JSValue mc_obj = JS_NewObjectClass(ctx, multicast_class_id);
-    if (JS_IsException(mc_obj)) return mc_obj;
+    if (JS_IsException(mc_obj)) return -1;
     auto* m = new MulticastState{ctx, false, {}};
     JS_SetOpaque(mc_obj, m);
 
     JSValue subscribe_cb = JS_NewCFunctionData(ctx, multicast_subscribe, 1, 0, 1, &mc_obj);
-    JSValue observable = make_observable_with_cb(ctx, subscribe_cb);
-    if (JS_IsException(observable)) {
+    JSValue obs = make_observable_with_cb(ctx, subscribe_cb);
+    if (JS_IsException(obs)) {
         JS_FreeValue(ctx, mc_obj);
-        return observable;
+        return -1;
     }
 
-    JSValue next_fn = JS_NewCFunctionData(ctx, multicast_emit_next, 1, 0, 1, &mc_obj);
-    JSValue complete_fn = JS_NewCFunctionData(ctx, multicast_emit_complete, 0, 0, 1, &mc_obj);
+    *observable = obs;
+    *next = JS_NewCFunctionData(ctx, multicast_emit_next, 1, 0, 1, &mc_obj);
+    *complete = JS_NewCFunctionData(ctx, multicast_emit_complete, 0, 0, 1, &mc_obj);
     JS_FreeValue(ctx, mc_obj);
+    return 0;
+}
+
+static JSValue observable_with_emitters(JSContext* ctx, JSValueConst this_val, int argc,
+                                        JSValueConst* argv) {
+    (void)this_val;
+    (void)argc;
+    (void)argv;
+
+    JSValue observable, next_fn, complete_fn;
+    if (multicast_new(ctx, &observable, &next_fn, &complete_fn) < 0) return JS_EXCEPTION;
 
     JSValue result = JS_NewObject(ctx);
     JS_DefinePropertyValueStr(ctx, result, "observable", observable, JS_PROP_C_W_E);
@@ -990,6 +1091,816 @@ static JSValue observable_with_emitters(JSContext* ctx, JSValueConst this_val, i
     return result;
 }
 
+/* ── Operators (mikro/observable/operators) ─────────────────────────── */
+
+static void ensure_protos(JSContext* ctx);
+
+/* Each factory (map(fn), take(n), ...) validates its arguments and returns
+ * an operator function whose func_data holds them; applying it to a source
+ * builds an Observable whose subscribe callback (op_subscribe) carries
+ * [source, args...]. A C-function `magic` packs the kind in its low byte and
+ * the captured argument count above it. */
+enum OpKind : int {
+    OP_MAP,
+    OP_FILTER,
+    OP_TAP,
+    OP_TAKE,
+    OP_SKIP,
+    OP_SCAN,
+    OP_DISTINCT,
+    OP_START_WITH,
+    OP_FINALIZE,
+    OP_TAKE_UNTIL,
+    OP_MERGE_WITH,
+    OP_WITH_LATEST_FROM,
+    OP_COMBINE_LATEST,
+    OP_SWITCH_MAP,
+    OP_TIMER,
+    OP_DEBOUNCE,
+    OP_THROTTLE,
+    /* takeUntil(predicate), chosen by the takeUntil factory; not exported. */
+    OP_TAKE_WHILE,
+};
+
+/* Indexed by OpKind; export names, and the prefix of every error message. */
+static const char* const op_names[] = {
+    "map",      "filter",    "tap",       "take",           "skip",          "scan",
+    "distinctUntilChanged",  "startWith", "finalize",       "takeUntil",     "mergeWith",
+    "withLatestFrom",        "combineLatest",              "switchMap",      "timer",
+    "debounceTime",          "throttleTime",               "takeUntil",
+};
+static_assert(sizeof(op_names) / sizeof(op_names[0]) == OP_TAKE_WHILE + 1,
+              "op_names must name every OpKind");
+
+static inline int op_kind(int magic) { return magic & 0xff; }
+static inline int op_argc(int magic) { return magic >> 8; }
+static inline int op_magic(int kind, int argc) { return kind | (argc << 8); }
+
+/* Per-subscription operator state, shared by every upstream subscriber the
+ * operator opens. `down` is the subscriber the operator emits to. */
+struct OpState {
+    int kind = 0;
+    JSValue down = JS_UNDEFINED;
+    JSValue fn = JS_UNDEFINED;    /* callable argument, or JS_UNDEFINED */
+    JSValue value = JS_UNDEFINED; /* accumulator, last value, latest of `other`, pending value */
+    JSValue inner = JS_UNDEFINED; /* switchMap: the current inner upstream subscriber */
+    /* combineLatest: latest value per source, JS_UNINITIALIZED until seen. */
+    std::vector<JSValue> values;
+    int32_t count = 0;    /* take/skip: remaining; mergeWith/combineLatest: open; timer: ticks */
+    int32_t missing = 0;  /* combineLatest: sources yet to emit */
+    int32_t ms = 0;       /* debounce/throttle window; timer period (-1: one-shot) */
+    uint32_t timer_id = 0;
+    bool flag = false;    /* has a value (distinct, withLatestFrom); inclusive; timer repeating */
+    bool pending = false; /* debounce/throttle: `value` waits for the window to end */
+    bool leading = false;
+    bool trailing = false;
+    bool inner_open = false;
+    bool source_done = false;
+};
+
+static JSClassID op_state_class_id;
+
+static void op_state_finalizer(JSRuntime* rt, JSValue val) {
+    auto* s = static_cast<OpState*>(JS_GetOpaque(val, op_state_class_id));
+    if (!s) return;
+    JS_FreeValueRT(rt, s->down);
+    JS_FreeValueRT(rt, s->fn);
+    JS_FreeValueRT(rt, s->value);
+    JS_FreeValueRT(rt, s->inner);
+    for (auto& v : s->values) JS_FreeValueRT(rt, v);
+    delete s;
+}
+
+static void op_state_gc_mark(JSRuntime* rt, JSValue val, JS_MarkFunc* mark_func) {
+    auto* s = static_cast<OpState*>(JS_GetOpaque(val, op_state_class_id));
+    if (!s) return;
+    JS_MarkValue(rt, s->down, mark_func);
+    JS_MarkValue(rt, s->fn, mark_func);
+    JS_MarkValue(rt, s->value, mark_func);
+    JS_MarkValue(rt, s->inner, mark_func);
+    for (auto& v : s->values) JS_MarkValue(rt, v, mark_func);
+}
+
+static JSClassDef op_state_class_def = {
+    "OperatorState", op_state_finalizer, op_state_gc_mark, nullptr, nullptr,
+};
+
+static SubscriberData* op_down(OpState* s) {
+    return static_cast<SubscriberData*>(JS_GetOpaque(s->down, subscriber_class_id));
+}
+
+static bool down_closed(OpState* s) {
+    SubscriberData* d = op_down(s);
+    return !d || d->closed || d->complete_pending;
+}
+
+/* Emit downstream through the regular next/complete entry points, so the
+ * dispatch trampoline and closed checks apply exactly as for JS callers. */
+static void emit(JSContext* ctx, OpState* s, JSValueConst value) {
+    JSValue arg = value;
+    JS_FreeValue(ctx, subscriber_next(ctx, s->down, 1, &arg));
+}
+
+static void finish(JSContext* ctx, OpState* s) {
+    JS_FreeValue(ctx, subscriber_complete(ctx, s->down, 0, nullptr));
+}
+
+/* Emit a fresh array of `count` values (owned; consumed either way). */
+static void emit_array(JSContext* ctx, OpState* s, int count, JSValue* owned) {
+    JSValue arr = JS_NewArrayFrom(ctx, count, owned);
+    if (JS_IsException(arr)) {
+        panic(ctx, JS_GetException(ctx));
+        return;
+    }
+    emit(ctx, s, arr);
+    JS_FreeValue(ctx, arr);
+}
+
+/* Call `fn(argv...)` for its boolean result; a throw panics and yields false
+ * with *ok cleared. */
+static bool call_for_bool(JSContext* ctx, JSValueConst fn, int argc, JSValueConst* argv, bool* ok) {
+    JSValue ret = call_or_panic(ctx, fn, argc, argv);
+    *ok = !JS_IsException(ret);
+    if (!*ok) return false;
+    bool result = JS_ToBool(ctx, ret) == 1;
+    JS_FreeValue(ctx, ret);
+    return result;
+}
+
+static JSValue op_timer_fire(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                             int magic, JSValueConst* func_data);
+
+/* Arm the operator's timer through the registry (never the JS setTimeout
+ * global). The registry holds the callback, and with it `state`. */
+static void schedule(JSContext* ctx, OpState* s, JSValueConst state, int32_t ms, bool repeat) {
+    JSValue fn = JS_NewCFunctionData(ctx, op_timer_fire, 0, 0, 1, &state);
+    if (JS_IsException(fn)) {
+        panic(ctx, JS_GetException(ctx));
+        return;
+    }
+    s->timer_id = MIK_Timer_Schedule(MIK_GetRuntime(ctx)->timers, ctx, fn, 0, nullptr,
+                                     static_cast<int64_t>(ms) * 1000, repeat,
+                                     MIK_GetPlatform()->get_boot_us());
+    JS_FreeValue(ctx, fn);
+}
+
+static void unschedule(JSContext* ctx, OpState* s) {
+    if (s->timer_id == 0) return;
+    MIK_Timer_UnSchedule(MIK_GetRuntime(ctx)->timers, ctx, s->timer_id);
+    s->timer_id = 0;
+}
+
+/* Emit the pending value, if any. Held across the emit: a synchronous
+ * delivery may replace `s->value` before it returns. */
+static void flush(JSContext* ctx, OpState* s) {
+    if (!s->pending) return;
+    s->pending = false;
+    JSValue v = JS_DupValue(ctx, s->value);
+    emit(ctx, s, v);
+    JS_FreeValue(ctx, v);
+}
+
+static void set_pending(JSContext* ctx, OpState* s, JSValueConst value, bool pending) {
+    JS_FreeValue(ctx, s->value);
+    s->value = JS_DupValue(ctx, value);
+    s->pending = pending;
+}
+
+static void close_inner(JSContext* ctx, OpState* s) {
+    if (JS_IsUndefined(s->inner)) return;
+    auto* d = static_cast<SubscriberData*>(JS_GetOpaque(s->inner, subscriber_class_id));
+    if (d) close_subscriber(ctx, d);
+    JSValue inner = s->inner;
+    s->inner = JS_UNDEFINED;
+    JS_FreeValue(ctx, inner);
+}
+
+/* Teardown for an operator state registered on its downstream subscriber:
+ * ends the timer and the inner subscription. False if `entry` is no state. */
+static bool op_teardown(JSContext* ctx, JSValueConst entry) {
+    auto* s = static_cast<OpState*>(JS_GetOpaque(entry, op_state_class_id));
+    if (!s) return false;
+    unschedule(ctx, s);
+    close_inner(ctx, s);
+    return true;
+}
+
+static JSValue op_timer_fire(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                             int magic, JSValueConst* func_data) {
+    (void)this_val;
+    (void)argc;
+    (void)argv;
+    (void)magic;
+    JSValueConst state = func_data[0];
+    auto* s = static_cast<OpState*>(JS_GetOpaque(state, op_state_class_id));
+    if (!s || down_closed(s)) return JS_UNDEFINED;
+    switch (s->kind) {
+        case OP_TIMER: {
+            /* The registry drops a one-shot entry after it fires. */
+            bool first = !s->flag;
+            if (first) s->timer_id = 0;
+            emit(ctx, s, JS_NewInt32(ctx, s->count++));
+            if (!first || down_closed(s)) return JS_UNDEFINED;
+            if (s->ms < 0) {
+                finish(ctx, s);
+                return JS_UNDEFINED;
+            }
+            s->flag = true;
+            schedule(ctx, s, state, s->ms, true);
+            return JS_UNDEFINED;
+        }
+        case OP_DEBOUNCE:
+            s->timer_id = 0;
+            flush(ctx, s);
+            return JS_UNDEFINED;
+        case OP_THROTTLE:
+            s->timer_id = 0;
+            if (!s->pending) return JS_UNDEFINED;
+            flush(ctx, s);
+            /* A trailing emission opens the next window. */
+            if (!down_closed(s)) schedule(ctx, s, state, s->ms, false);
+            return JS_UNDEFINED;
+        default:
+            return JS_UNDEFINED;
+    }
+}
+
+/* Build an upstream subscriber that dispatches into `state` as number
+ * `index`. Not started. */
+static JSValue make_upstream(JSContext* ctx, JSValueConst state, int index) {
+    JSValue sub_val = JS_NewObjectClass(ctx, subscriber_class_id);
+    if (JS_IsException(sub_val)) return sub_val;
+    auto* d = new SubscriberData{
+        ctx, false, false, JS_UNDEFINED, JS_UNDEFINED, JS_UNDEFINED, {}, JS_DupValue(ctx, state),
+        index,
+    };
+    JS_SetOpaque(sub_val, d);
+    return sub_val;
+}
+
+/* switchMap: replace the inner subscription with one to `project(value)`.
+ * Runs inside a dispatch, so failures panic rather than throw. */
+static void switch_inner(JSContext* ctx, OpState* s, JSValueConst state, JSValueConst value) {
+    close_inner(ctx, s);
+    JSValue source = call_or_panic(ctx, s->fn, 1, &value);
+    if (JS_IsException(source)) return;
+    auto* src = static_cast<ObservableData*>(JS_GetOpaque(source, observable_class_id));
+    if (!src) {
+        JS_FreeValue(ctx, source);
+        JS_ThrowTypeError(ctx, "switchMap: project must return an Observable");
+        panic(ctx, JS_GetException(ctx));
+        return;
+    }
+    JSValue sub_val = make_upstream(ctx, state, 1);
+    if (JS_IsException(sub_val)) {
+        JS_FreeValue(ctx, source);
+        panic(ctx, JS_GetException(ctx));
+        return;
+    }
+    s->inner_open = true;
+    s->inner = JS_DupValue(ctx, sub_val);
+    auto* d = static_cast<SubscriberData*>(JS_GetOpaque(sub_val, subscriber_class_id));
+    JSValue started = start_subscriber(ctx, src->subscribe_cb, sub_val, d);
+    JS_FreeValue(ctx, source);
+    if (JS_IsException(started)) {
+        panic(ctx, JS_GetException(ctx));
+        return;
+    }
+    JS_FreeValue(ctx, started);
+}
+
+static void op_on_next(JSContext* ctx, JSValueConst state, int index, JSValueConst value) {
+    auto* s = static_cast<OpState*>(JS_GetOpaque(state, op_state_class_id));
+    bool ok = true;
+    switch (s->kind) {
+        case OP_MAP: {
+            JSValue out = call_or_panic(ctx, s->fn, 1, &value);
+            if (JS_IsException(out)) return;
+            emit(ctx, s, out);
+            JS_FreeValue(ctx, out);
+            return;
+        }
+        case OP_FILTER:
+            if (call_for_bool(ctx, s->fn, 1, &value, &ok)) emit(ctx, s, value);
+            return;
+        case OP_TAP: {
+            JSValue ret = call_or_panic(ctx, s->fn, 1, &value);
+            if (JS_IsException(ret)) return;
+            JS_FreeValue(ctx, ret);
+            emit(ctx, s, value);
+            return;
+        }
+        case OP_TAKE:
+            if (s->count <= 0) return;
+            s->count--;
+            emit(ctx, s, value);
+            if (s->count == 0) finish(ctx, s);
+            return;
+        case OP_SKIP:
+            if (s->count > 0) {
+                s->count--;
+                return;
+            }
+            emit(ctx, s, value);
+            return;
+        case OP_SCAN: {
+            JSValue args[2] = {s->value, value};
+            JSValue acc = call_or_panic(ctx, s->fn, 2, args);
+            if (JS_IsException(acc)) return;
+            JS_FreeValue(ctx, s->value);
+            s->value = acc;
+            emit(ctx, s, acc);
+            return;
+        }
+        case OP_DISTINCT: {
+            if (s->flag) {
+                bool same;
+                if (JS_IsUndefined(s->fn)) {
+                    same = JS_IsStrictEqual(ctx, s->value, value);
+                } else {
+                    JSValue args[2] = {s->value, value};
+                    same = call_for_bool(ctx, s->fn, 2, args, &ok);
+                    if (!ok) return;
+                }
+                if (same) return;
+            }
+            s->flag = true;
+            JS_FreeValue(ctx, s->value);
+            s->value = JS_DupValue(ctx, value);
+            emit(ctx, s, value);
+            return;
+        }
+        case OP_TAKE_UNTIL:
+            /* index 1 is the notifier: any value ends the stream. */
+            if (index == 1) {
+                finish(ctx, s);
+            } else {
+                emit(ctx, s, value);
+            }
+            return;
+        case OP_TAKE_WHILE: {
+            bool stop = call_for_bool(ctx, s->fn, 1, &value, &ok);
+            if (!ok) return;
+            if (!stop || s->flag) emit(ctx, s, value);
+            if (stop) finish(ctx, s);
+            return;
+        }
+        case OP_WITH_LATEST_FROM: {
+            /* index 1 is `other`: remember its latest value. */
+            if (index == 1) {
+                s->flag = true;
+                JS_FreeValue(ctx, s->value);
+                s->value = JS_DupValue(ctx, value);
+                return;
+            }
+            if (!s->flag) return;
+            JSValue pair[2] = {JS_DupValue(ctx, value), JS_DupValue(ctx, s->value)};
+            emit_array(ctx, s, 2, pair);
+            return;
+        }
+        case OP_COMBINE_LATEST: {
+            if (JS_IsUninitialized(s->values[index])) {
+                s->missing--;
+            } else {
+                JS_FreeValue(ctx, s->values[index]);
+            }
+            s->values[index] = JS_DupValue(ctx, value);
+            if (s->missing > 0) return;
+            int n = static_cast<int>(s->values.size());
+            std::vector<JSValue> copy;
+            copy.reserve(n);
+            for (auto& v : s->values) copy.push_back(JS_DupValue(ctx, v));
+            emit_array(ctx, s, n, copy.data());
+            return;
+        }
+        case OP_SWITCH_MAP:
+            if (index == 1) {
+                emit(ctx, s, value);
+            } else {
+                switch_inner(ctx, s, state, value);
+            }
+            return;
+        case OP_DEBOUNCE: {
+            bool quiet = s->timer_id == 0;
+            unschedule(ctx, s);
+            schedule(ctx, s, state, s->ms, false);
+            if (quiet && s->leading) {
+                emit(ctx, s, value);
+            } else {
+                set_pending(ctx, s, value, s->trailing);
+            }
+            return;
+        }
+        case OP_THROTTLE:
+            if (s->timer_id != 0) {
+                set_pending(ctx, s, value, s->trailing);
+                return;
+            }
+            if (s->leading) {
+                emit(ctx, s, value);
+            } else {
+                set_pending(ctx, s, value, s->trailing);
+            }
+            if (!down_closed(s)) schedule(ctx, s, state, s->ms, false);
+            return;
+        default:
+            /* startWith, finalize, mergeWith: pass through. */
+            emit(ctx, s, value);
+            return;
+    }
+}
+
+/* `from` is the upstream subscriber that completed. */
+static void op_on_complete(JSContext* ctx, JSValueConst state, int index, SubscriberData* from) {
+    auto* s = static_cast<OpState*>(JS_GetOpaque(state, op_state_class_id));
+    switch (s->kind) {
+        case OP_MERGE_WITH:
+            if (--s->count == 0) finish(ctx, s);
+            return;
+        case OP_COMBINE_LATEST:
+            /* A source ending without a value means no tuple can ever form. */
+            if (JS_IsUninitialized(s->values[index]) || --s->count == 0) finish(ctx, s);
+            return;
+        case OP_TAKE_UNTIL:
+        case OP_WITH_LATEST_FROM:
+            /* The notifier or `other` completing does not end the stream. */
+            if (index != 1) finish(ctx, s);
+            return;
+        case OP_SWITCH_MAP:
+            /* Completes once the source and the last inner stream both have.
+             * An inner that was switched away while its completion was still
+             * queued (complete_pending) drains here too; only the current
+             * inner's completion counts. */
+            if (index == 1) {
+                if (from == JS_GetOpaque(s->inner, subscriber_class_id)) s->inner_open = false;
+            } else {
+                s->source_done = true;
+            }
+            if (s->source_done && !s->inner_open) finish(ctx, s);
+            return;
+        case OP_DEBOUNCE:
+            unschedule(ctx, s);
+            flush(ctx, s);
+            finish(ctx, s);
+            return;
+        case OP_THROTTLE:
+            unschedule(ctx, s);
+            flush(ctx, s);
+            finish(ctx, s);
+            return;
+        default:
+            finish(ctx, s);
+            return;
+    }
+}
+
+/* Route `source` into the operator as upstream number `index`; the upstream
+ * ends with `down`. The upstream subscriber joins `down`'s teardowns before
+ * the producer runs, so a chain that completes during setup (startWith into
+ * take(1)) already closes it, and a closed `down` subscribes nothing. */
+static bool forward(JSContext* ctx, OpState* s, JSValueConst source, JSValueConst state,
+                    int index) {
+    auto* src = static_cast<ObservableData*>(JS_GetOpaque2(ctx, source, observable_class_id));
+    if (!src) return false;
+    if (down_closed(s)) return true;
+    JSValue sub_val = make_upstream(ctx, state, index);
+    if (JS_IsException(sub_val)) return false;
+    auto* d = static_cast<SubscriberData*>(JS_GetOpaque(sub_val, subscriber_class_id));
+    op_down(s)->teardowns.push_back(JS_DupValue(ctx, sub_val));
+    JSValue started = start_subscriber(ctx, src->subscribe_cb, sub_val, d);
+    if (JS_IsException(started)) return false;
+    JS_FreeValue(ctx, started);
+    return true;
+}
+
+/* Counts and durations: non-finite or huge values saturate, NaN counts as 0. */
+static int32_t to_count(JSContext* ctx, JSValueConst v) {
+    double n = 0;
+    JS_ToFloat64(ctx, &n, v);
+    if (!(n > 0)) return 0;
+    if (n >= INT32_MAX) return INT32_MAX;
+    return static_cast<int32_t>(n);
+}
+
+/* The subscribe callback of an operator-built Observable.
+ * func_data = [source, args...]; argv[0] = the downstream subscriber. */
+static JSValue op_subscribe(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                            int magic, JSValueConst* func_data) {
+    (void)this_val;
+    if (argc < 1) return JS_UNDEFINED;
+    int kind = op_kind(magic);
+    JSValueConst source = func_data[0];
+    JSValueConst* args = func_data + 1;
+
+    JSValue state = JS_NewObjectClass(ctx, op_state_class_id);
+    if (JS_IsException(state)) return state;
+    auto* s = new OpState();
+    s->kind = kind;
+    s->down = JS_DupValue(ctx, argv[0]);
+    JS_SetOpaque(state, s);
+
+    bool ok = true;
+    bool subscribed = false;
+    switch (kind) {
+        case OP_MAP:
+        case OP_FILTER:
+        case OP_TAP:
+            s->fn = JS_DupValue(ctx, args[0]);
+            break;
+        case OP_TAKE_WHILE:
+            s->fn = JS_DupValue(ctx, args[0]);
+            s->flag = JS_ToBool(ctx, args[1]) == 1;
+            break;
+        case OP_SCAN:
+            s->fn = JS_DupValue(ctx, args[0]);
+            s->value = JS_DupValue(ctx, args[1]);
+            break;
+        case OP_DISTINCT:
+            s->fn = JS_DupValue(ctx, args[0]);
+            break;
+        case OP_TAKE:
+            s->count = to_count(ctx, args[0]);
+            /* take(0): complete without ever subscribing upstream. */
+            if (s->count == 0) {
+                finish(ctx, s);
+                subscribed = true;
+            }
+            break;
+        case OP_SKIP:
+            s->count = to_count(ctx, args[0]);
+            break;
+        case OP_START_WITH:
+            emit(ctx, s, args[0]);
+            /* The first value may have closed the chain (take(1)). */
+            if (down_closed(s)) subscribed = true;
+            break;
+        case OP_FINALIZE:
+            /* Registered first, so it runs after the upstream unsubscribe. */
+            add_teardown(ctx, op_down(s), JS_DupValue(ctx, args[0]));
+            break;
+        case OP_TAKE_UNTIL:
+            /* Notifier first, as in RxJS: one that fires during its own
+             * subscribe ends the stream before the source is subscribed. */
+            ok = forward(ctx, s, args[0], state, 1) && forward(ctx, s, source, state, 0);
+            subscribed = true;
+            break;
+        case OP_MERGE_WITH: {
+            int n = op_argc(magic);
+            s->count = n + 1;
+            ok = forward(ctx, s, source, state, 0);
+            for (int i = 0; ok && i < n; i++) ok = forward(ctx, s, args[i], state, i + 1);
+            subscribed = true;
+            break;
+        }
+        case OP_WITH_LATEST_FROM:
+            ok = forward(ctx, s, args[0], state, 1) && forward(ctx, s, source, state, 0);
+            subscribed = true;
+            break;
+        case OP_COMBINE_LATEST: {
+            /* `source` is the array of sources. */
+            int64_t len = 0;
+            if (JS_GetLength(ctx, source, &len) < 0) {
+                ok = false;
+                subscribed = true;
+                break;
+            }
+            int n = static_cast<int>(len);
+            s->values.assign(n, JS_UNINITIALIZED);
+            s->count = n;
+            s->missing = n;
+            if (n == 0) {
+                emit_array(ctx, s, 0, nullptr);
+                finish(ctx, s);
+            }
+            for (int i = 0; ok && i < n; i++) {
+                /* A source that completed without a value already closed
+                 * `down`; the rest would be unsubscribed at once anyway. */
+                if (down_closed(s)) break;
+                JSValue elem = JS_GetPropertyUint32(ctx, source, i);
+                ok = !JS_IsException(elem) && forward(ctx, s, elem, state, i);
+                JS_FreeValue(ctx, elem);
+            }
+            subscribed = true;
+            break;
+        }
+        case OP_SWITCH_MAP:
+            s->fn = JS_DupValue(ctx, args[0]);
+            add_teardown(ctx, op_down(s), JS_DupValue(ctx, state));
+            break;
+        case OP_TIMER:
+            /* `source` is the delay; args[0] the period, or undefined. */
+            s->ms = JS_IsUndefined(args[0]) ? -1 : to_count(ctx, args[0]);
+            add_teardown(ctx, op_down(s), JS_DupValue(ctx, state));
+            schedule(ctx, s, state, to_count(ctx, source), false);
+            subscribed = true;
+            break;
+        case OP_DEBOUNCE:
+        case OP_THROTTLE:
+            s->ms = to_count(ctx, args[0]);
+            s->leading = JS_ToBool(ctx, args[1]) == 1;
+            s->trailing = JS_ToBool(ctx, args[2]) == 1;
+            add_teardown(ctx, op_down(s), JS_DupValue(ctx, state));
+            break;
+        default:
+            break;
+    }
+    if (ok && !subscribed) ok = forward(ctx, s, source, state, 0);
+    JS_FreeValue(ctx, state);
+    return ok ? JS_UNDEFINED : JS_EXCEPTION;
+}
+
+/* The operator function returned by a factory: (source) => Observable.
+ * func_data = the factory's arguments. */
+static JSValue op_apply(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                        int magic, JSValueConst* func_data) {
+    (void)this_val;
+    if (argc < 1 || !JS_GetOpaque(argv[0], observable_class_id)) {
+        return JS_ThrowTypeError(ctx, "%s: source must be an Observable",
+                                 op_names[op_kind(magic)]);
+    }
+    int n = op_argc(magic);
+    std::vector<JSValue> data;
+    data.reserve(n + 1);
+    data.push_back(argv[0]);
+    for (int i = 0; i < n; i++) data.push_back(func_data[i]);
+    /* JS_NewCFunctionData duplicates the data values. */
+    JSValue cb = JS_NewCFunctionData(ctx, op_subscribe, 1, magic, n + 1, data.data());
+    if (JS_IsException(cb)) return cb;
+    return make_observable_with_cb(ctx, cb);
+}
+
+static bool is_observable(JSValueConst v) {
+    return JS_GetOpaque(v, observable_class_id) != nullptr;
+}
+
+/* One factory for every operator; `magic` is the OpKind. */
+static JSValue op_factory(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                          int magic) {
+    (void)this_val;
+    int kind = magic;
+    const char* name = op_names[kind];
+    JSValueConst first = argc > 0 ? argv[0] : JS_UNDEFINED;
+    std::vector<JSValue> data;
+    JSValue owned = JS_UNDEFINED;
+    switch (kind) {
+        case OP_MAP:
+        case OP_FILTER:
+        case OP_TAP:
+        case OP_FINALIZE:
+        case OP_SCAN:
+        case OP_SWITCH_MAP:
+            if (!JS_IsFunction(ctx, first)) {
+                return JS_ThrowTypeError(ctx, "%s: argument must be a function", name);
+            }
+            data.push_back(first);
+            if (kind == OP_SCAN) data.push_back(argc > 1 ? argv[1] : JS_UNDEFINED);
+            break;
+        case OP_DISTINCT:
+            if (!JS_IsUndefined(first) && !JS_IsFunction(ctx, first)) {
+                return JS_ThrowTypeError(ctx, "%s: argument must be a function", name);
+            }
+            data.push_back(first);
+            break;
+        case OP_TAKE:
+        case OP_SKIP:
+            if (!JS_IsNumber(first)) {
+                return JS_ThrowTypeError(ctx, "%s: count must be a number", name);
+            }
+            data.push_back(first);
+            break;
+        case OP_START_WITH:
+            data.push_back(first);
+            break;
+        case OP_TAKE_UNTIL: {
+            if (JS_IsFunction(ctx, first)) {
+                kind = OP_TAKE_WHILE;
+                bool inclusive = true;
+                if (argc > 1 && JS_IsObject(argv[1])) {
+                    JSValue opt = JS_GetPropertyStr(ctx, argv[1], "inclusive");
+                    if (JS_IsException(opt)) return opt;
+                    if (!JS_IsUndefined(opt)) inclusive = JS_ToBool(ctx, opt) == 1;
+                    JS_FreeValue(ctx, opt);
+                }
+                owned = JS_NewBool(ctx, inclusive);
+                data.push_back(first);
+                data.push_back(owned);
+                break;
+            }
+            if (!is_observable(first)) {
+                return JS_ThrowTypeError(ctx, "%s: argument must be an Observable or a predicate",
+                                         name);
+            }
+            data.push_back(first);
+            break;
+        }
+        case OP_MERGE_WITH:
+        case OP_WITH_LATEST_FROM:
+            for (int i = 0; i < (kind == OP_MERGE_WITH ? argc : 1); i++) {
+                JSValueConst v = i < argc ? argv[i] : JS_UNDEFINED;
+                if (!is_observable(v)) {
+                    return JS_ThrowTypeError(ctx, "%s: arguments must be Observables", name);
+                }
+                data.push_back(v);
+            }
+            break;
+        case OP_TIMER: {
+            if (!JS_IsNumber(first) || (argc > 1 && !JS_IsUndefined(argv[1]) && !JS_IsNumber(argv[1]))) {
+                return JS_ThrowTypeError(ctx, "%s: delay and period must be numbers", name);
+            }
+            /* Not an operator: the delay is the "source" of op_subscribe. */
+            JSValue timer_args[2] = {first, argc > 1 ? argv[1] : JS_UNDEFINED};
+            JSValue cb =
+                JS_NewCFunctionData(ctx, op_subscribe, 1, op_magic(kind, 1), 2, timer_args);
+            if (JS_IsException(cb)) return cb;
+            return make_observable_with_cb(ctx, cb);
+        }
+        case OP_DEBOUNCE:
+        case OP_THROTTLE: {
+            if (!JS_IsNumber(first)) {
+                return JS_ThrowTypeError(ctx, "%s: duration must be a number", name);
+            }
+            /* {leading, trailing}: debounce defaults to the trailing edge,
+             * throttle to the leading one. */
+            bool leading = kind == OP_THROTTLE;
+            bool trailing = kind == OP_DEBOUNCE;
+            if (argc > 1 && JS_IsObject(argv[1])) {
+                JSValue l = JS_GetPropertyStr(ctx, argv[1], "leading");
+                if (JS_IsException(l)) return l;
+                JSValue t = JS_GetPropertyStr(ctx, argv[1], "trailing");
+                if (JS_IsException(t)) {
+                    JS_FreeValue(ctx, l);
+                    return t;
+                }
+                if (!JS_IsUndefined(l)) leading = JS_ToBool(ctx, l) == 1;
+                if (!JS_IsUndefined(t)) trailing = JS_ToBool(ctx, t) == 1;
+                JS_FreeValue(ctx, l);
+                JS_FreeValue(ctx, t);
+            }
+            data.push_back(first);
+            data.push_back(JS_NewBool(ctx, leading));
+            data.push_back(JS_NewBool(ctx, trailing));
+            break;
+        }
+        case OP_COMBINE_LATEST: {
+            int64_t len = -1;
+            if (!JS_IsArray(first) || JS_GetLength(ctx, first, &len) < 0) {
+                return JS_ThrowTypeError(ctx, "%s: argument must be an array of Observables",
+                                         name);
+            }
+            for (int64_t i = 0; i < len; i++) {
+                JSValue elem = JS_GetPropertyUint32(ctx, first, static_cast<uint32_t>(i));
+                bool valid = is_observable(elem);
+                JS_FreeValue(ctx, elem);
+                if (!valid) {
+                    return JS_ThrowTypeError(ctx, "%s: argument must be an array of Observables",
+                                             name);
+                }
+            }
+            /* Not an operator: the array is the "source" of op_subscribe. */
+            JSValue cb = JS_NewCFunctionData(ctx, op_subscribe, 1, kind, 1, &first);
+            if (JS_IsException(cb)) return cb;
+            return make_observable_with_cb(ctx, cb);
+        }
+        default:
+            break;
+    }
+    int n = static_cast<int>(data.size());
+    JSValue fn = JS_NewCFunctionData(ctx, op_apply, 1, op_magic(kind, n), n, data.data());
+    JS_FreeValue(ctx, owned);
+    return fn;
+}
+
+/* pipe(...ops): compose operators left to right into one operator.
+ * func_data = the operators; `magic` = their count. */
+static JSValue pipe_apply(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                          int magic, JSValueConst* func_data) {
+    (void)this_val;
+    JSValueConst source = argc > 0 ? argv[0] : JS_UNDEFINED;
+    return observable_pipe(ctx, source, magic, func_data);
+}
+
+static JSValue pipe_factory(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv) {
+    (void)this_val;
+    for (int i = 0; i < argc; i++) {
+        if (!JS_IsFunction(ctx, argv[i])) {
+            return JS_ThrowTypeError(ctx, "pipe: arguments must be operator functions");
+        }
+    }
+    return JS_NewCFunctionData(ctx, pipe_apply, 1, argc, argc, argv);
+}
+
+static int operators_module_init(JSContext* ctx, JSModuleDef* m) {
+    ensure_protos(ctx);
+    for (int kind = OP_MAP; kind < OP_TAKE_WHILE; kind++) {
+        const char* name = op_names[kind];
+        JS_SetModuleExport(
+            ctx, m, name,
+            JS_NewCFunctionMagic(ctx, op_factory, name, 1, JS_CFUNC_generic_magic, kind));
+    }
+    JS_SetModuleExport(ctx, m, "pipe", JS_NewCFunction(ctx, pipe_factory, "pipe", 0));
+    return 0;
+}
+
 /* ── Observable prototype ─────────────────────────────────────────── */
 
 static const JSCFunctionListEntry observable_proto_funcs[] = {
@@ -999,9 +1910,16 @@ static const JSCFunctionListEntry observable_proto_funcs[] = {
 
 /* ── Module init ──────────────────────────────────────────────────── */
 
-static int observable_module_init(JSContext* ctx, JSModuleDef* m) {
-    /* Build prototype objects and bind to class IDs. The classes themselves
-     * are registered by mik__observable_init below. */
+/* Build the prototypes and the constructor once per context, on the first
+ * import of either module: operators create Observables without the
+ * observable module ever being imported. The classes themselves are
+ * registered by mik__observable_init below. */
+static void ensure_protos(JSContext* ctx) {
+    JSValue existing = JS_GetClassProto(ctx, observable_class_id);
+    bool done = JS_IsObject(existing);
+    JS_FreeValue(ctx, existing);
+    if (done) return;
+
     JSValue subscriber_proto = JS_NewObject(ctx);
     JS_SetPropertyFunctionList(ctx, subscriber_proto, subscriber_proto_funcs,
                                sizeof(subscriber_proto_funcs) /
@@ -1024,19 +1942,45 @@ static int observable_module_init(JSContext* ctx, JSModuleDef* m) {
                                         JS_CFUNC_constructor, 0);
     JS_SetConstructor(ctx, obs_ctor, obs_proto);
 
-    JS_DefinePropertyValueStr(
-        ctx, obs_ctor, "from",
-        JS_NewCFunction(ctx, observable_from, "from", 1), JS_PROP_C_W_E);
     JS_DefinePropertyValueStr(
         ctx, obs_ctor, "withEmitters",
         JS_NewCFunction(ctx, observable_with_emitters, "withEmitters", 0), JS_PROP_C_W_E);
+    /* The prototype keeps the constructor reachable (proto.constructor). */
+    JS_FreeValue(ctx, obs_ctor);
+}
 
+static int observable_module_init(JSContext* ctx, JSModuleDef* m) {
+    ensure_protos(ctx);
+    JSValue obs_proto = JS_GetClassProto(ctx, observable_class_id);
+    JSValue obs_ctor = JS_GetPropertyStr(ctx, obs_proto, "constructor");
+    JS_FreeValue(ctx, obs_proto);
     JS_SetModuleExport(ctx, m, "Observable", obs_ctor);
+    JS_SetModuleExport(ctx, m, "from", JS_NewCFunction(ctx, observable_from, "from", 1));
+    JS_SetModuleExport(ctx, m, "of", JS_NewCFunction(ctx, observable_of, "of", 0));
     return 0;
 }
 
 }  // namespace
 
+/* mikro/observable/operators, resolved through the C-module table in
+ * modules.cpp on first import. */
+JSModuleDef* mik__observable_operators_load(JSContext* ctx) {
+    JSModuleDef* m = JS_NewCModule(ctx, "mikro/observable/operators", operators_module_init);
+    if (!m) return nullptr;
+    for (int kind = OP_MAP; kind < OP_TAKE_WHILE; kind++) {
+        JS_AddModuleExport(ctx, m, op_names[kind]);
+    }
+    JS_AddModuleExport(ctx, m, "pipe");
+    return m;
+}
+
+int mik__observable_multicast_new(JSContext* ctx, JSValue* observable, JSValue* next,
+                                  JSValue* complete) {
+    /* A C module can hand out an Observable before any JS imports mikro/observable. */
+    ensure_protos(ctx);
+    return multicast_new(ctx, observable, next, complete);
+}
+
 void mik__observable_dispatch_free(MIKRuntime* mik_rt) {
     delete mik_rt->observable_dispatch;
     mik_rt->observable_dispatch = nullptr;
@@ -1063,9 +2007,13 @@ JSModuleDef* mik__observable_init(JSContext* ctx) {
     JS_NewClass(rt, from_promise_class_id, &from_promise_class_def);
     JS_NewClassID(rt, &multicast_class_id);
     JS_NewClass(rt, multicast_class_id, &multicast_class_def);
+    JS_NewClassID(rt, &op_state_class_id);
+    JS_NewClass(rt, op_state_class_id, &op_state_class_def);
 
     JSModuleDef* m = JS_NewCModule(ctx, "native:mikro/observable", observable_module_init);
     if (!m) return nullptr;
     JS_AddModuleExport(ctx, m, "Observable");
+    JS_AddModuleExport(ctx, m, "from");
+    JS_AddModuleExport(ctx, m, "of");
     return m;
 }