margin-ts 0.6.1 → 0.6.2

package/dist/adapters/nextjs.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Next.js API route adapter for margin.
+ *
+ * One-liner health tracking for any API route:
+ *
+ *   // pages/api/users.ts (Pages Router)
+ *   import { withMargin } from 'margin-ts/adapters/nextjs';
+ *   export default withMargin(handler);
+ *
+ *   // app/api/users/route.ts (App Router)
+ *   import { withMarginApp } from 'margin-ts/adapters/nextjs';
+ *   export const GET = withMarginApp(handler);
+ *
+ *   // Health endpoint
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ *
+ * Tracks latency, error rate, and request count per route.
+ * Zero dependencies beyond margin-ts core.
+ */
+import { Thresholds } from '../index.js';
+export interface NextjsThresholds {
+    p50Latency: Thresholds;
+    p99Latency: Thresholds;
+    errorRate: Thresholds;
+}
+export declare const DEFAULT_NEXTJS_THRESHOLDS: NextjsThresholds;
+export interface WithMarginOptions {
+    route?: string;
+    thresholds?: NextjsThresholds;
+}
+/**
+ * Wrap a Pages Router API handler with margin health tracking.
+ *
+ *   export default withMargin(handler);
+ *   export default withMargin(handler, { route: '/api/users' });
+ */
+export declare function withMargin(handler: (req: any, res: any) => any, options?: WithMarginOptions): (req: any, res: any) => any;
+/**
+ * Wrap an App Router handler with margin health tracking.
+ *
+ *   export const GET = withMarginApp(handler);
+ *   export const POST = withMarginApp(handler, { route: '/api/users' });
+ */
+export declare function withMarginApp(handler: (req: any) => any, options?: WithMarginOptions): (req: any) => any;
+/**
+ * Pages Router: health endpoint handler.
+ *
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ */
+export declare function marginHealthHandler(thresholds?: NextjsThresholds): (req: any, res: any) => void;
+/**
+ * App Router: health endpoint handler.
+ *
+ *   // app/api/margin/health/route.ts
+ *   import { marginHealthAppHandler } from 'margin-ts/adapters/nextjs';
+ *   export const GET = marginHealthAppHandler();
+ */
+export declare function marginHealthAppHandler(thresholds?: NextjsThresholds): (req: any) => any;
+/** Clear all tracked routes (for testing). */
+export declare function resetRoutes(): void;
+//# sourceMappingURL=nextjs.d.ts.map

package/dist/adapters/nextjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../src/adapters/nextjs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,UAAU,EAOX,MAAM,aAAa,CAAC;AAwCrB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AA8CF,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,GAAG,EACpC,OAAO,GAAE,iBAAsB,GAC9B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,GAAG,CAiB7B;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,CAiBnB;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAkC/F;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,CAqCvF;AAED,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/adapters/nextjs.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Next.js API route adapter for margin.
+ *
+ * One-liner health tracking for any API route:
+ *
+ *   // pages/api/users.ts (Pages Router)
+ *   import { withMargin } from 'margin-ts/adapters/nextjs';
+ *   export default withMargin(handler);
+ *
+ *   // app/api/users/route.ts (App Router)
+ *   import { withMarginApp } from 'margin-ts/adapters/nextjs';
+ *   export const GET = withMarginApp(handler);
+ *
+ *   // Health endpoint
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ *
+ * Tracks latency, error rate, and request count per route.
+ * Zero dependencies beyond margin-ts core.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NEXTJS_THRESHOLDS = void 0;
+exports.withMargin = withMargin;
+exports.withMarginApp = withMarginApp;
+exports.marginHealthHandler = marginHealthHandler;
+exports.marginHealthAppHandler = marginHealthAppHandler;
+exports.resetRoutes = resetRoutes;
+const index_js_1 = require("../index.js");
+const _routes = new Map();
+const _MAX_WINDOW = 200;
+function getOrCreateRoute(route) {
+    if (!_routes.has(route)) {
+        _routes.set(route, {
+            totalRequests: 0,
+            totalErrors: 0,
+            latencies: [],
+            maxWindow: _MAX_WINDOW,
+        });
+    }
+    return _routes.get(route);
+}
+function record(route, latencyMs, isError) {
+    const stats = getOrCreateRoute(route);
+    stats.totalRequests++;
+    if (isError)
+        stats.totalErrors++;
+    stats.latencies.push(latencyMs);
+    if (stats.latencies.length > stats.maxWindow)
+        stats.latencies.shift();
+}
+exports.DEFAULT_NEXTJS_THRESHOLDS = {
+    p50Latency: (0, index_js_1.createThresholds)(100, 500, false),
+    p99Latency: (0, index_js_1.createThresholds)(500, 2000, false),
+    errorRate: (0, index_js_1.createThresholds)(0.01, 0.10, false),
+};
+// -----------------------------------------------------------------------
+// Classification
+// -----------------------------------------------------------------------
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil(sorted.length * p) - 1;
+    return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];
+}
+function classifyRoute(route, stats, thresholds) {
+    if (stats.latencies.length < 3)
+        return null;
+    const sorted = [...stats.latencies].sort((a, b) => a - b);
+    const p50 = percentile(sorted, 0.5);
+    const p99 = percentile(sorted, 0.99);
+    const errorRate = stats.totalRequests > 0 ? stats.totalErrors / stats.totalRequests : 0;
+    const now = new Date();
+    const observations = [
+        {
+            name: `${route}:p50`, health: (0, index_js_1.classify)(p50, index_js_1.Confidence.HIGH, thresholds.p50Latency),
+            value: p50, baseline: thresholds.p50Latency.intact, confidence: index_js_1.Confidence.HIGH,
+            higherIsBetter: false, provenance: [], measuredAt: now,
+        },
+        {
+            name: `${route}:p99`, health: (0, index_js_1.classify)(p99, index_js_1.Confidence.HIGH, thresholds.p99Latency),
+            value: p99, baseline: thresholds.p99Latency.intact, confidence: index_js_1.Confidence.HIGH,
+            higherIsBetter: false, provenance: [], measuredAt: now,
+        },
+        {
+            name: `${route}:errors`, health: (0, index_js_1.classify)(errorRate, index_js_1.Confidence.HIGH, thresholds.errorRate),
+            value: errorRate, baseline: 0.001, confidence: index_js_1.Confidence.HIGH,
+            higherIsBetter: false, provenance: [], measuredAt: now,
+        },
+    ];
+    return (0, index_js_1.createExpression)(observations, [], route);
+}
+/**
+ * Wrap a Pages Router API handler with margin health tracking.
+ *
+ *   export default withMargin(handler);
+ *   export default withMargin(handler, { route: '/api/users' });
+ */
+function withMargin(handler, options = {}) {
+    return async (req, res) => {
+        const route = options.route || req.url || '/api/unknown';
+        const start = Date.now();
+        try {
+            const result = await handler(req, res);
+            const latency = Date.now() - start;
+            const status = res.statusCode || 200;
+            record(route, latency, status >= 500);
+            return result;
+        }
+        catch (err) {
+            const latency = Date.now() - start;
+            record(route, latency, true);
+            throw err;
+        }
+    };
+}
+// -----------------------------------------------------------------------
+// App Router wrapper
+// -----------------------------------------------------------------------
+/**
+ * Wrap an App Router handler with margin health tracking.
+ *
+ *   export const GET = withMarginApp(handler);
+ *   export const POST = withMarginApp(handler, { route: '/api/users' });
+ */
+function withMarginApp(handler, options = {}) {
+    return async (req) => {
+        const route = options.route || new URL(req.url || '/', 'http://localhost').pathname;
+        const start = Date.now();
+        try {
+            const response = await handler(req);
+            const latency = Date.now() - start;
+            const status = response?.status || 200;
+            record(route, latency, status >= 500);
+            return response;
+        }
+        catch (err) {
+            const latency = Date.now() - start;
+            record(route, latency, true);
+            throw err;
+        }
+    };
+}
+// -----------------------------------------------------------------------
+// Health endpoint
+// -----------------------------------------------------------------------
+/**
+ * Pages Router: health endpoint handler.
+ *
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ */
+function marginHealthHandler(thresholds) {
+    const t = thresholds || exports.DEFAULT_NEXTJS_THRESHOLDS;
+    return (_req, res) => {
+        const routeHealth = {};
+        let worstOverall = index_js_1.Health.INTACT;
+        const SEVERITY = {
+            [index_js_1.Health.INTACT]: 0, [index_js_1.Health.RECOVERING]: 1, [index_js_1.Health.DEGRADED]: 2,
+            [index_js_1.Health.ABLATED]: 3, [index_js_1.Health.OOD]: 4,
+        };
+        for (const [route, stats] of _routes) {
+            const expr = classifyRoute(route, stats, t);
+            if (expr) {
+                routeHealth[route] = {
+                    expression: (0, index_js_1.expressionToString)(expr),
+                    ...(0, index_js_1.expressionToDict)(expr),
+                    requests: stats.totalRequests,
+                    errors: stats.totalErrors,
+                };
+                for (const obs of expr.observations) {
+                    if (SEVERITY[obs.health] > SEVERITY[worstOverall]) {
+                        worstOverall = obs.health;
+                    }
+                }
+            }
+        }
+        res.status(200).json({
+            status: worstOverall,
+            routes: routeHealth,
+            totalRoutes: _routes.size,
+        });
+    };
+}
+/**
+ * App Router: health endpoint handler.
+ *
+ *   // app/api/margin/health/route.ts
+ *   import { marginHealthAppHandler } from 'margin-ts/adapters/nextjs';
+ *   export const GET = marginHealthAppHandler();
+ */
+function marginHealthAppHandler(thresholds) {
+    const t = thresholds || exports.DEFAULT_NEXTJS_THRESHOLDS;
+    return (_req) => {
+        const routeHealth = {};
+        let worstOverall = index_js_1.Health.INTACT;
+        const SEVERITY = {
+            [index_js_1.Health.INTACT]: 0, [index_js_1.Health.RECOVERING]: 1, [index_js_1.Health.DEGRADED]: 2,
+            [index_js_1.Health.ABLATED]: 3, [index_js_1.Health.OOD]: 4,
+        };
+        for (const [route, stats] of _routes) {
+            const expr = classifyRoute(route, stats, t);
+            if (expr) {
+                routeHealth[route] = {
+                    expression: (0, index_js_1.expressionToString)(expr),
+                    ...(0, index_js_1.expressionToDict)(expr),
+                    requests: stats.totalRequests,
+                    errors: stats.totalErrors,
+                };
+                for (const obs of expr.observations) {
+                    if (SEVERITY[obs.health] > SEVERITY[worstOverall]) {
+                        worstOverall = obs.health;
+                    }
+                }
+            }
+        }
+        return new Response(JSON.stringify({
+            status: worstOverall,
+            routes: routeHealth,
+            totalRoutes: _routes.size,
+        }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        });
+    };
+}
+/** Clear all tracked routes (for testing). */
+function resetRoutes() {
+    _routes.clear();
+}
+//# sourceMappingURL=nextjs.js.map

package/dist/adapters/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../../src/adapters/nextjs.ts"],"names":[],"mappings":"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"}

package/dist/adapters/stream.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Streaming health updates via Server-Sent Events (SSE).
+ *
+ * Push health/drift/anomaly updates to browser dashboards in real-time.
+ *
+ * Express:
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Next.js Pages Router:
+ *   export default marginSSEHandler(monitor);
+ *
+ * Browser client:
+ *   const source = new EventSource('/margin/stream');
+ *   source.onmessage = (e) => {
+ *     const health = JSON.parse(e.data);
+ *     updateDashboard(health);
+ *   };
+ *
+ * Zero dependencies. Works with any framework that supports
+ * writable response streams (Express, Fastify, Next.js, raw Node http).
+ */
+import { Expression, Parser, DriftClassification, AnomalyClassification } from '../index.js';
+export declare class StreamingMonitor {
+    private parser;
+    private windows;
+    private _expression;
+    private _step;
+    private maxWindow;
+    private minAnomalyRef;
+    constructor(parser: Parser, options?: {
+        window?: number;
+        minAnomalyRef?: number;
+    });
+    get expression(): Expression | null;
+    get step(): number;
+    update(values: Record<string, number>, now?: Date): Expression;
+    drift(component: string): DriftClassification | null;
+    anomaly(component: string): AnomalyClassification | null;
+    status(): Record<string, unknown>;
+    reset(): void;
+}
+/**
+ * Broadcast a status update to all connected SSE clients.
+ * Call this after each monitor.update().
+ */
+export declare function broadcast(monitor: StreamingMonitor): void;
+/**
+ * Express/Fastify route handler for SSE streaming.
+ *
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Each connected browser receives real-time health updates.
+ * Call broadcast(monitor) after each monitor.update() to push.
+ */
+export declare function marginSSE(monitor: StreamingMonitor): (req: any, res: any) => void;
+/**
+ * Next.js Pages Router SSE handler.
+ *
+ *   // pages/api/margin/stream.ts
+ *   export default marginSSEHandler(monitor);
+ */
+export declare function marginSSEHandler(monitor: StreamingMonitor): (req: any, res: any) => void;
+/**
+ * Create a polling endpoint (for environments that don't support SSE).
+ * Returns the current status as JSON on each request.
+ *
+ *   app.get('/margin/poll', marginPoll(monitor));
+ */
+export declare function marginPoll(monitor: StreamingMonitor): (req: any, res: any) => void;
+/** Number of connected SSE clients. */
+export declare function connectedClients(): number;
+/** Disconnect all SSE clients (for testing). */
+export declare function resetClients(): void;
+//# sourceMappingURL=stream.d.ts.map

package/dist/adapters/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/adapters/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAIL,UAAU,EACV,MAAM,EAKN,mBAAmB,EAInB,qBAAqB,EAEtB,MAAM,aAAa,CAAC;AAYrB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO;IAMrF,IAAI,UAAU,IAAI,UAAU,GAAG,IAAI,CAA6B;IAChE,IAAI,IAAI,IAAI,MAAM,CAAuB;IAEzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,UAAU;IAwB9D,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAMpD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI;IAQxD,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAoBjC,KAAK,IAAI,IAAI;CAKd;AAeD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAWzD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAoBjF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAExF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAIlF;AAED,uCAAuC;AACvC,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,gDAAgD;AAChD,wBAAgB,YAAY,IAAI,IAAI,CAMnC"}

package/dist/adapters/stream.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Streaming health updates via Server-Sent Events (SSE).
+ *
+ * Push health/drift/anomaly updates to browser dashboards in real-time.
+ *
+ * Express:
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Next.js Pages Router:
+ *   export default marginSSEHandler(monitor);
+ *
+ * Browser client:
+ *   const source = new EventSource('/margin/stream');
+ *   source.onmessage = (e) => {
+ *     const health = JSON.parse(e.data);
+ *     updateDashboard(health);
+ *   };
+ *
+ * Zero dependencies. Works with any framework that supports
+ * writable response streams (Express, Fastify, Next.js, raw Node http).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingMonitor = void 0;
+exports.broadcast = broadcast;
+exports.marginSSE = marginSSE;
+exports.marginSSEHandler = marginSSEHandler;
+exports.marginPoll = marginPoll;
+exports.connectedClients = connectedClients;
+exports.resetClients = resetClients;
+const index_js_1 = require("../index.js");
+class StreamingMonitor {
+    parser;
+    windows = new Map();
+    _expression = null;
+    _step = 0;
+    maxWindow;
+    minAnomalyRef;
+    constructor(parser, options = {}) {
+        this.parser = parser;
+        this.maxWindow = options.window ?? 100;
+        this.minAnomalyRef = options.minAnomalyRef ?? 10;
+    }
+    get expression() { return this._expression; }
+    get step() { return this._step; }
+    update(values, now) {
+        now = now ?? new Date();
+        this._expression = this.parser.parse(values, { step: this._step });
+        this._step++;
+        // Update per-component windows
+        for (const obs of this._expression.observations) {
+            if (!this.windows.has(obs.name)) {
+                this.windows.set(obs.name, { values: [], observations: [], maxWindow: this.maxWindow });
+            }
+            const w = this.windows.get(obs.name);
+            w.values.push(obs.value);
+            // Stamp the observation with time for drift
+            const stamped = { ...obs, measuredAt: now };
+            w.observations.push(stamped);
+            if (w.values.length > this.maxWindow) {
+                w.values.shift();
+                w.observations.shift();
+            }
+        }
+        return this._expression;
+    }
+    drift(component) {
+        const w = this.windows.get(component);
+        if (!w || w.observations.length < 3)
+            return null;
+        return (0, index_js_1.classifyDrift)(w.observations);
+    }
+    anomaly(component) {
+        const w = this.windows.get(component);
+        if (!w || w.values.length < this.minAnomalyRef + 1)
+            return null;
+        const ref = w.values.slice(0, -1);
+        const current = w.values[w.values.length - 1];
+        return (0, index_js_1.classifyAnomaly)(current, ref, { component });
+    }
+    status() {
+        const drift = {};
+        const anomaly = {};
+        for (const [name] of this.windows) {
+            const dc = this.drift(name);
+            if (dc)
+                drift[name] = { state: dc.state, direction: dc.direction, rate: dc.rate };
+            const ac = this.anomaly(name);
+            if (ac)
+                anomaly[name] = { state: ac.state, zScore: ac.zScore };
+        }
+        return {
+            step: this._step,
+            expression: this._expression ? (0, index_js_1.expressionToString)(this._expression) : null,
+            health: this._expression ? (0, index_js_1.expressionToDict)(this._expression) : null,
+            drift,
+            anomaly,
+        };
+    }
+    reset() {
+        this.windows.clear();
+        this._expression = null;
+        this._step = 0;
+    }
+}
+exports.StreamingMonitor = StreamingMonitor;
+let _clients = [];
+let _clientIdCounter = 0;
+/**
+ * Broadcast a status update to all connected SSE clients.
+ * Call this after each monitor.update().
+ */
+function broadcast(monitor) {
+    const data = JSON.stringify(monitor.status());
+    const message = `data: ${data}\n\n`;
+    _clients = _clients.filter(client => {
+        try {
+            client.res.write(message);
+            return true;
+        }
+        catch {
+            return false; // client disconnected
+        }
+    });
+}
+/**
+ * Express/Fastify route handler for SSE streaming.
+ *
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Each connected browser receives real-time health updates.
+ * Call broadcast(monitor) after each monitor.update() to push.
+ */
+function marginSSE(monitor) {
+    return (req, res) => {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'Access-Control-Allow-Origin': '*',
+        });
+        // Send current state immediately
+        const initial = JSON.stringify(monitor.status());
+        res.write(`data: ${initial}\n\n`);
+        const client = { id: String(++_clientIdCounter), res };
+        _clients.push(client);
+        req.on('close', () => {
+            _clients = _clients.filter(c => c.id !== client.id);
+        });
+    };
+}
+/**
+ * Next.js Pages Router SSE handler.
+ *
+ *   // pages/api/margin/stream.ts
+ *   export default marginSSEHandler(monitor);
+ */
+function marginSSEHandler(monitor) {
+    return marginSSE(monitor);
+}
+/**
+ * Create a polling endpoint (for environments that don't support SSE).
+ * Returns the current status as JSON on each request.
+ *
+ *   app.get('/margin/poll', marginPoll(monitor));
+ */
+function marginPoll(monitor) {
+    return (_req, res) => {
+        res.json(monitor.status());
+    };
+}
+/** Number of connected SSE clients. */
+function connectedClients() {
+    return _clients.length;
+}
+/** Disconnect all SSE clients (for testing). */
+function resetClients() {
+    for (const client of _clients) {
+        try {
+            client.res.end();
+        }
+        catch { }
+    }
+    _clients = [];
+    _clientIdCounter = 0;
+}
+//# sourceMappingURL=stream.js.map

package/dist/adapters/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/adapters/stream.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export { DriftState, DriftDirection, DriftClassification, classifyDrift, } from
 export { AnomalyState, ANOMALY_SEVERITY, AnomalyClassification, classifyAnomaly, } from './anomaly.js';
 export { marginMiddleware, marginHealthRoute, DEFAULT_THRESHOLDS as EXPRESS_THRESHOLDS, type MarginMiddlewareOptions, type MarginState, type EndpointThresholds, } from './adapters/express.js';
 export { classifySuite, suiteHealthString, DEFAULT_SUITE_THRESHOLDS, type SuiteResults, type SuiteThresholds, } from './adapters/vitest.js';
+export { withMargin, withMarginApp, marginHealthHandler, marginHealthAppHandler, resetRoutes, DEFAULT_NEXTJS_THRESHOLDS, type WithMarginOptions, type NextjsThresholds, } from './adapters/nextjs.js';
+export { StreamingMonitor, broadcast, marginSSE, marginSSEHandler, marginPoll, connectedClients, resetClients, } from './adapters/stream.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEzG,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAC9C,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAC9B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EACvC,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAC3E,kBAAkB,EAClB,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,EAC1E,MAAM,GACP,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAC/C,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EACrD,eAAe,GAChB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,gBAAgB,EAAE,iBAAiB,EACnC,kBAAkB,IAAI,kBAAkB,EACxC,KAAK,uBAAuB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,GACxE,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,aAAa,EAAE,iBAAiB,EAChC,wBAAwB,EACxB,KAAK,YAAY,EAAE,KAAK,eAAe,GACxC,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEzG,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAC9C,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAC9B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EACvC,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAC3E,kBAAkB,EAClB,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,EAC1E,MAAM,GACP,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAC/C,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EACrD,eAAe,GAChB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,gBAAgB,EAAE,iBAAiB,EACnC,kBAAkB,IAAI,kBAAkB,EACxC,KAAK,uBAAuB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,GACxE,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,aAAa,EAAE,iBAAiB,EAChC,wBAAwB,EACxB,KAAK,YAAY,EAAE,KAAK,eAAe,GACxC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,UAAU,EAAE,aAAa,EACzB,mBAAmB,EAAE,sBAAsB,EAC3C,WAAW,EACX,yBAAyB,EACzB,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,GAC9C,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAClD,gBAAgB,EAAE,YAAY,GAC/B,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -8,7 +8,7 @@
  * Copyright (c) 2026 Cope Labs LLC. MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SUITE_THRESHOLDS = exports.suiteHealthString = exports.classifySuite = exports.EXPRESS_THRESHOLDS = exports.marginHealthRoute = exports.marginMiddleware = exports.classifyAnomaly = exports.ANOMALY_SEVERITY = exports.AnomalyState = exports.classifyDrift = exports.DriftDirection = exports.DriftState = exports.Parser = exports.expressionToDict = exports.expressionToString = exports.degraded = exports.healthOf = exports.createExpression = exports.correctionIsActive = exports.observationFromDict = exports.observationToDict = exports.observationToAtom = exports.observationSigma = exports.Op = exports.classify = exports.isAblated = exports.isIntact = exports.createThresholds = exports.SEVERITY = exports.Health = exports.minConfidence = exports.confidenceLt = exports.confidenceGte = exports.confidenceRank = exports.Confidence = void 0;
+exports.resetClients = exports.connectedClients = exports.marginPoll = exports.marginSSEHandler = exports.marginSSE = exports.broadcast = exports.StreamingMonitor = exports.DEFAULT_NEXTJS_THRESHOLDS = exports.resetRoutes = exports.marginHealthAppHandler = exports.marginHealthHandler = exports.withMarginApp = exports.withMargin = exports.DEFAULT_SUITE_THRESHOLDS = exports.suiteHealthString = exports.classifySuite = exports.EXPRESS_THRESHOLDS = exports.marginHealthRoute = exports.marginMiddleware = exports.classifyAnomaly = exports.ANOMALY_SEVERITY = exports.AnomalyState = exports.classifyDrift = exports.DriftDirection = exports.DriftState = exports.Parser = exports.expressionToDict = exports.expressionToString = exports.degraded = exports.healthOf = exports.createExpression = exports.correctionIsActive = exports.observationFromDict = exports.observationToDict = exports.observationToAtom = exports.observationSigma = exports.Op = exports.classify = exports.isAblated = exports.isIntact = exports.createThresholds = exports.SEVERITY = exports.Health = exports.minConfidence = exports.confidenceLt = exports.confidenceGte = exports.confidenceRank = exports.Confidence = void 0;
 var confidence_js_1 = require("./confidence.js");
 Object.defineProperty(exports, "Confidence", { enumerable: true, get: function () { return confidence_js_1.Confidence; } });
 Object.defineProperty(exports, "confidenceRank", { enumerable: true, get: function () { return confidence_js_1.confidenceRank; } });
@@ -52,4 +52,19 @@ var vitest_js_1 = require("./adapters/vitest.js");
 Object.defineProperty(exports, "classifySuite", { enumerable: true, get: function () { return vitest_js_1.classifySuite; } });
 Object.defineProperty(exports, "suiteHealthString", { enumerable: true, get: function () { return vitest_js_1.suiteHealthString; } });
 Object.defineProperty(exports, "DEFAULT_SUITE_THRESHOLDS", { enumerable: true, get: function () { return vitest_js_1.DEFAULT_SUITE_THRESHOLDS; } });
+var nextjs_js_1 = require("./adapters/nextjs.js");
+Object.defineProperty(exports, "withMargin", { enumerable: true, get: function () { return nextjs_js_1.withMargin; } });
+Object.defineProperty(exports, "withMarginApp", { enumerable: true, get: function () { return nextjs_js_1.withMarginApp; } });
+Object.defineProperty(exports, "marginHealthHandler", { enumerable: true, get: function () { return nextjs_js_1.marginHealthHandler; } });
+Object.defineProperty(exports, "marginHealthAppHandler", { enumerable: true, get: function () { return nextjs_js_1.marginHealthAppHandler; } });
+Object.defineProperty(exports, "resetRoutes", { enumerable: true, get: function () { return nextjs_js_1.resetRoutes; } });
+Object.defineProperty(exports, "DEFAULT_NEXTJS_THRESHOLDS", { enumerable: true, get: function () { return nextjs_js_1.DEFAULT_NEXTJS_THRESHOLDS; } });
+var stream_js_1 = require("./adapters/stream.js");
+Object.defineProperty(exports, "StreamingMonitor", { enumerable: true, get: function () { return stream_js_1.StreamingMonitor; } });
+Object.defineProperty(exports, "broadcast", { enumerable: true, get: function () { return stream_js_1.broadcast; } });
+Object.defineProperty(exports, "marginSSE", { enumerable: true, get: function () { return stream_js_1.marginSSE; } });
+Object.defineProperty(exports, "marginSSEHandler", { enumerable: true, get: function () { return stream_js_1.marginSSEHandler; } });
+Object.defineProperty(exports, "marginPoll", { enumerable: true, get: function () { return stream_js_1.marginPoll; } });
+Object.defineProperty(exports, "connectedClients", { enumerable: true, get: function () { return stream_js_1.connectedClients; } });
+Object.defineProperty(exports, "resetClients", { enumerable: true, get: function () { return stream_js_1.resetClients; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,iDAAyG;AAAhG,2GAAA,UAAU,OAAA;AAAE,+GAAA,cAAc,OAAA;AAAE,8GAAA,aAAa,OAAA;AAAE,6GAAA,YAAY,OAAA;AAAE,8GAAA,aAAa,OAAA;AAE/E,yCAGqB;AAFnB,mGAAA,MAAM,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAAc,6GAAA,gBAAgB,OAAA;AAC9C,qGAAA,QAAQ,OAAA;AAAE,sGAAA,SAAS,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAG/B,mDAM0B;AALxB,oGAAA,EAAE,OAAA;AACF,kHAAA,gBAAgB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,qHAAA,mBAAmB,OAAA;AAC3E,oHAAA,kBAAkB,OAAA;AAClB,kHAAA,gBAAgB,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAAE,oHAAA,kBAAkB,OAAA;AAAE,kHAAA,gBAAgB,OAAA;AAC1E,wGAAA,MAAM,OAAA;AAGR,uCAGoB;AAFlB,sGAAA,UAAU,OAAA;AAAE,0GAAA,cAAc,OAAA;AAC1B,yGAAA,aAAa,OAAA;AAGf,2CAGsB;AAFpB,0GAAA,YAAY,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAC9B,6GAAA,eAAe,OAAA;AAGjB,WAAW;AACX,oDAI+B;AAH7B,8GAAA,gBAAgB,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AACnC,gHAAA,kBAAkB,OAAsB;AAI1C,kDAI8B;AAH5B,0GAAA,aAAa,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAChC,qHAAA,wBAAwB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,iDAAyG;AAAhG,2GAAA,UAAU,OAAA;AAAE,+GAAA,cAAc,OAAA;AAAE,8GAAA,aAAa,OAAA;AAAE,6GAAA,YAAY,OAAA;AAAE,8GAAA,aAAa,OAAA;AAE/E,yCAGqB;AAFnB,mGAAA,MAAM,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAAc,6GAAA,gBAAgB,OAAA;AAC9C,qGAAA,QAAQ,OAAA;AAAE,sGAAA,SAAS,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAG/B,mDAM0B;AALxB,oGAAA,EAAE,OAAA;AACF,kHAAA,gBAAgB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,qHAAA,mBAAmB,OAAA;AAC3E,oHAAA,kBAAkB,OAAA;AAClB,kHAAA,gBAAgB,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAAE,oHAAA,kBAAkB,OAAA;AAAE,kHAAA,gBAAgB,OAAA;AAC1E,wGAAA,MAAM,OAAA;AAGR,uCAGoB;AAFlB,sGAAA,UAAU,OAAA;AAAE,0GAAA,cAAc,OAAA;AAC1B,yGAAA,aAAa,OAAA;AAGf,2CAGsB;AAFpB,0GAAA,YAAY,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAC9B,6GAAA,eAAe,OAAA;AAGjB,WAAW;AACX,oDAI+B;AAH7B,8GAAA,gBAAgB,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AACnC,gHAAA,kBAAkB,OAAsB;AAI1C,kDAI8B;AAH5B,0GAAA,aAAa,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAChC,qHAAA,wBAAwB,OAAA;AAI1B,kDAM8B;AAL5B,uGAAA,UAAU,OAAA;AAAE,0GAAA,aAAa,OAAA;AACzB,gHAAA,mBAAmB,OAAA;AAAE,mHAAA,sBAAsB,OAAA;AAC3C,wGAAA,WAAW,OAAA;AACX,sHAAA,yBAAyB,OAAA;AAI3B,kDAI8B;AAH5B,6GAAA,gBAAgB,OAAA;AAChB,sGAAA,SAAS,OAAA;AAAE,sGAAA,SAAS,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAAE,uGAAA,UAAU,OAAA;AAClD,6GAAA,gBAAgB,OAAA;AAAE,yGAAA,YAAY,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "margin-ts",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Typed health classification for systems that measure things. Zero dependencies.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/adapters/nextjs.ts

@@ -0,0 +1,290 @@
+/**
+ * Next.js API route adapter for margin.
+ *
+ * One-liner health tracking for any API route:
+ *
+ *   // pages/api/users.ts (Pages Router)
+ *   import { withMargin } from 'margin-ts/adapters/nextjs';
+ *   export default withMargin(handler);
+ *
+ *   // app/api/users/route.ts (App Router)
+ *   import { withMarginApp } from 'margin-ts/adapters/nextjs';
+ *   export const GET = withMarginApp(handler);
+ *
+ *   // Health endpoint
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ *
+ * Tracks latency, error rate, and request count per route.
+ * Zero dependencies beyond margin-ts core.
+ */
+
+import {
+  Confidence,
+  Health,
+  Thresholds,
+  createThresholds,
+  classify,
+  Observation,
+  createExpression,
+  expressionToString,
+  expressionToDict,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// Shared state — singleton across all wrapped routes
+// -----------------------------------------------------------------------
+
+interface RouteStats {
+  totalRequests: number;
+  totalErrors: number;
+  latencies: number[];
+  maxWindow: number;
+}
+
+const _routes = new Map<string, RouteStats>();
+const _MAX_WINDOW = 200;
+
+function getOrCreateRoute(route: string): RouteStats {
+  if (!_routes.has(route)) {
+    _routes.set(route, {
+      totalRequests: 0,
+      totalErrors: 0,
+      latencies: [],
+      maxWindow: _MAX_WINDOW,
+    });
+  }
+  return _routes.get(route)!;
+}
+
+function record(route: string, latencyMs: number, isError: boolean): void {
+  const stats = getOrCreateRoute(route);
+  stats.totalRequests++;
+  if (isError) stats.totalErrors++;
+  stats.latencies.push(latencyMs);
+  if (stats.latencies.length > stats.maxWindow) stats.latencies.shift();
+}
+
+// -----------------------------------------------------------------------
+// Thresholds
+// -----------------------------------------------------------------------
+
+export interface NextjsThresholds {
+  p50Latency: Thresholds;
+  p99Latency: Thresholds;
+  errorRate: Thresholds;
+}
+
+export const DEFAULT_NEXTJS_THRESHOLDS: NextjsThresholds = {
+  p50Latency: createThresholds(100, 500, false),
+  p99Latency: createThresholds(500, 2000, false),
+  errorRate: createThresholds(0.01, 0.10, false),
+};
+
+// -----------------------------------------------------------------------
+// Classification
+// -----------------------------------------------------------------------
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil(sorted.length * p) - 1;
+  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];
+}
+
+function classifyRoute(route: string, stats: RouteStats, thresholds: NextjsThresholds) {
+  if (stats.latencies.length < 3) return null;
+
+  const sorted = [...stats.latencies].sort((a, b) => a - b);
+  const p50 = percentile(sorted, 0.5);
+  const p99 = percentile(sorted, 0.99);
+  const errorRate = stats.totalRequests > 0 ? stats.totalErrors / stats.totalRequests : 0;
+  const now = new Date();
+
+  const observations: Observation[] = [
+    {
+      name: `${route}:p50`, health: classify(p50, Confidence.HIGH, thresholds.p50Latency),
+      value: p50, baseline: thresholds.p50Latency.intact, confidence: Confidence.HIGH,
+      higherIsBetter: false, provenance: [], measuredAt: now,
+    },
+    {
+      name: `${route}:p99`, health: classify(p99, Confidence.HIGH, thresholds.p99Latency),
+      value: p99, baseline: thresholds.p99Latency.intact, confidence: Confidence.HIGH,
+      higherIsBetter: false, provenance: [], measuredAt: now,
+    },
+    {
+      name: `${route}:errors`, health: classify(errorRate, Confidence.HIGH, thresholds.errorRate),
+      value: errorRate, baseline: 0.001, confidence: Confidence.HIGH,
+      higherIsBetter: false, provenance: [], measuredAt: now,
+    },
+  ];
+
+  return createExpression(observations, [], route);
+}
+
+// -----------------------------------------------------------------------
+// Pages Router wrapper
+// -----------------------------------------------------------------------
+
+export interface WithMarginOptions {
+  route?: string;
+  thresholds?: NextjsThresholds;
+}
+
+/**
+ * Wrap a Pages Router API handler with margin health tracking.
+ *
+ *   export default withMargin(handler);
+ *   export default withMargin(handler, { route: '/api/users' });
+ */
+export function withMargin(
+  handler: (req: any, res: any) => any,
+  options: WithMarginOptions = {},
+): (req: any, res: any) => any {
+  return async (req: any, res: any) => {
+    const route = options.route || req.url || '/api/unknown';
+    const start = Date.now();
+
+    try {
+      const result = await handler(req, res);
+      const latency = Date.now() - start;
+      const status = res.statusCode || 200;
+      record(route, latency, status >= 500);
+      return result;
+    } catch (err) {
+      const latency = Date.now() - start;
+      record(route, latency, true);
+      throw err;
+    }
+  };
+}
+
+// -----------------------------------------------------------------------
+// App Router wrapper
+// -----------------------------------------------------------------------
+
+/**
+ * Wrap an App Router handler with margin health tracking.
+ *
+ *   export const GET = withMarginApp(handler);
+ *   export const POST = withMarginApp(handler, { route: '/api/users' });
+ */
+export function withMarginApp(
+  handler: (req: any) => any,
+  options: WithMarginOptions = {},
+): (req: any) => any {
+  return async (req: any) => {
+    const route = options.route || new URL(req.url || '/', 'http://localhost').pathname;
+    const start = Date.now();
+
+    try {
+      const response = await handler(req);
+      const latency = Date.now() - start;
+      const status = response?.status || 200;
+      record(route, latency, status >= 500);
+      return response;
+    } catch (err) {
+      const latency = Date.now() - start;
+      record(route, latency, true);
+      throw err;
+    }
+  };
+}
+
+// -----------------------------------------------------------------------
+// Health endpoint
+// -----------------------------------------------------------------------
+
+/**
+ * Pages Router: health endpoint handler.
+ *
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ */
+export function marginHealthHandler(thresholds?: NextjsThresholds): (req: any, res: any) => void {
+  const t = thresholds || DEFAULT_NEXTJS_THRESHOLDS;
+
+  return (_req: any, res: any) => {
+    const routeHealth: Record<string, any> = {};
+    let worstOverall = Health.INTACT;
+    const SEVERITY: Record<Health, number> = {
+      [Health.INTACT]: 0, [Health.RECOVERING]: 1, [Health.DEGRADED]: 2,
+      [Health.ABLATED]: 3, [Health.OOD]: 4,
+    };
+
+    for (const [route, stats] of _routes) {
+      const expr = classifyRoute(route, stats, t);
+      if (expr) {
+        routeHealth[route] = {
+          expression: expressionToString(expr),
+          ...expressionToDict(expr),
+          requests: stats.totalRequests,
+          errors: stats.totalErrors,
+        };
+        for (const obs of expr.observations) {
+          if (SEVERITY[obs.health] > SEVERITY[worstOverall]) {
+            worstOverall = obs.health;
+          }
+        }
+      }
+    }
+
+    res.status(200).json({
+      status: worstOverall,
+      routes: routeHealth,
+      totalRoutes: _routes.size,
+    });
+  };
+}
+
+/**
+ * App Router: health endpoint handler.
+ *
+ *   // app/api/margin/health/route.ts
+ *   import { marginHealthAppHandler } from 'margin-ts/adapters/nextjs';
+ *   export const GET = marginHealthAppHandler();
+ */
+export function marginHealthAppHandler(thresholds?: NextjsThresholds): (req: any) => any {
+  const t = thresholds || DEFAULT_NEXTJS_THRESHOLDS;
+
+  return (_req: any) => {
+    const routeHealth: Record<string, any> = {};
+    let worstOverall = Health.INTACT;
+    const SEVERITY: Record<Health, number> = {
+      [Health.INTACT]: 0, [Health.RECOVERING]: 1, [Health.DEGRADED]: 2,
+      [Health.ABLATED]: 3, [Health.OOD]: 4,
+    };
+
+    for (const [route, stats] of _routes) {
+      const expr = classifyRoute(route, stats, t);
+      if (expr) {
+        routeHealth[route] = {
+          expression: expressionToString(expr),
+          ...expressionToDict(expr),
+          requests: stats.totalRequests,
+          errors: stats.totalErrors,
+        };
+        for (const obs of expr.observations) {
+          if (SEVERITY[obs.health] > SEVERITY[worstOverall]) {
+            worstOverall = obs.health;
+          }
+        }
+      }
+    }
+
+    return new Response(JSON.stringify({
+      status: worstOverall,
+      routes: routeHealth,
+      totalRoutes: _routes.size,
+    }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  };
+}
+
+/** Clear all tracked routes (for testing). */
+export function resetRoutes(): void {
+  _routes.clear();
+}

package/src/adapters/stream.ts

@@ -0,0 +1,227 @@
+/**
+ * Streaming health updates via Server-Sent Events (SSE).
+ *
+ * Push health/drift/anomaly updates to browser dashboards in real-time.
+ *
+ * Express:
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Next.js Pages Router:
+ *   export default marginSSEHandler(monitor);
+ *
+ * Browser client:
+ *   const source = new EventSource('/margin/stream');
+ *   source.onmessage = (e) => {
+ *     const health = JSON.parse(e.data);
+ *     updateDashboard(health);
+ *   };
+ *
+ * Zero dependencies. Works with any framework that supports
+ * writable response streams (Express, Fastify, Next.js, raw Node http).
+ */
+
+import {
+  Confidence,
+  Health,
+  Observation,
+  Expression,
+  Parser,
+  createExpression,
+  expressionToString,
+  expressionToDict,
+  classifyDrift,
+  DriftClassification,
+  DriftState,
+  DriftDirection,
+  classifyAnomaly,
+  AnomalyClassification,
+  AnomalyState,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// StreamingMonitor — the TS equivalent of Python's Monitor
+// -----------------------------------------------------------------------
+
+interface ComponentWindow {
+  values: number[];
+  observations: Observation[];
+  maxWindow: number;
+}
+
+export class StreamingMonitor {
+  private parser: Parser;
+  private windows: Map<string, ComponentWindow> = new Map();
+  private _expression: Expression | null = null;
+  private _step = 0;
+  private maxWindow: number;
+  private minAnomalyRef: number;
+
+  constructor(parser: Parser, options: { window?: number; minAnomalyRef?: number } = {}) {
+    this.parser = parser;
+    this.maxWindow = options.window ?? 100;
+    this.minAnomalyRef = options.minAnomalyRef ?? 10;
+  }
+
+  get expression(): Expression | null { return this._expression; }
+  get step(): number { return this._step; }
+
+  update(values: Record<string, number>, now?: Date): Expression {
+    now = now ?? new Date();
+    this._expression = this.parser.parse(values, { step: this._step });
+    this._step++;
+
+    // Update per-component windows
+    for (const obs of this._expression.observations) {
+      if (!this.windows.has(obs.name)) {
+        this.windows.set(obs.name, { values: [], observations: [], maxWindow: this.maxWindow });
+      }
+      const w = this.windows.get(obs.name)!;
+      w.values.push(obs.value);
+      // Stamp the observation with time for drift
+      const stamped = { ...obs, measuredAt: now };
+      w.observations.push(stamped);
+      if (w.values.length > this.maxWindow) {
+        w.values.shift();
+        w.observations.shift();
+      }
+    }
+
+    return this._expression;
+  }
+
+  drift(component: string): DriftClassification | null {
+    const w = this.windows.get(component);
+    if (!w || w.observations.length < 3) return null;
+    return classifyDrift(w.observations);
+  }
+
+  anomaly(component: string): AnomalyClassification | null {
+    const w = this.windows.get(component);
+    if (!w || w.values.length < this.minAnomalyRef + 1) return null;
+    const ref = w.values.slice(0, -1);
+    const current = w.values[w.values.length - 1];
+    return classifyAnomaly(current, ref, { component });
+  }
+
+  status(): Record<string, unknown> {
+    const drift: Record<string, unknown> = {};
+    const anomaly: Record<string, unknown> = {};
+
+    for (const [name] of this.windows) {
+      const dc = this.drift(name);
+      if (dc) drift[name] = { state: dc.state, direction: dc.direction, rate: dc.rate };
+      const ac = this.anomaly(name);
+      if (ac) anomaly[name] = { state: ac.state, zScore: ac.zScore };
+    }
+
+    return {
+      step: this._step,
+      expression: this._expression ? expressionToString(this._expression) : null,
+      health: this._expression ? expressionToDict(this._expression) : null,
+      drift,
+      anomaly,
+    };
+  }
+
+  reset(): void {
+    this.windows.clear();
+    this._expression = null;
+    this._step = 0;
+  }
+}
+
+// -----------------------------------------------------------------------
+// SSE helpers
+// -----------------------------------------------------------------------
+
+/** Connected SSE client. */
+interface SSEClient {
+  id: string;
+  res: any;
+}
+
+let _clients: SSEClient[] = [];
+let _clientIdCounter = 0;
+
+/**
+ * Broadcast a status update to all connected SSE clients.
+ * Call this after each monitor.update().
+ */
+export function broadcast(monitor: StreamingMonitor): void {
+  const data = JSON.stringify(monitor.status());
+  const message = `data: ${data}\n\n`;
+  _clients = _clients.filter(client => {
+    try {
+      client.res.write(message);
+      return true;
+    } catch {
+      return false; // client disconnected
+    }
+  });
+}
+
+/**
+ * Express/Fastify route handler for SSE streaming.
+ *
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Each connected browser receives real-time health updates.
+ * Call broadcast(monitor) after each monitor.update() to push.
+ */
+export function marginSSE(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return (req: any, res: any) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+
+    // Send current state immediately
+    const initial = JSON.stringify(monitor.status());
+    res.write(`data: ${initial}\n\n`);
+
+    const client: SSEClient = { id: String(++_clientIdCounter), res };
+    _clients.push(client);
+
+    req.on('close', () => {
+      _clients = _clients.filter(c => c.id !== client.id);
+    });
+  };
+}
+
+/**
+ * Next.js Pages Router SSE handler.
+ *
+ *   // pages/api/margin/stream.ts
+ *   export default marginSSEHandler(monitor);
+ */
+export function marginSSEHandler(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return marginSSE(monitor);
+}
+
+/**
+ * Create a polling endpoint (for environments that don't support SSE).
+ * Returns the current status as JSON on each request.
+ *
+ *   app.get('/margin/poll', marginPoll(monitor));
+ */
+export function marginPoll(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return (_req: any, res: any) => {
+    res.json(monitor.status());
+  };
+}
+
+/** Number of connected SSE clients. */
+export function connectedClients(): number {
+  return _clients.length;
+}
+
+/** Disconnect all SSE clients (for testing). */
+export function resetClients(): void {
+  for (const client of _clients) {
+    try { client.res.end(); } catch {}
+  }
+  _clients = [];
+  _clientIdCounter = 0;
+}

package/src/index.ts

@@ -44,3 +44,17 @@ export {
   DEFAULT_SUITE_THRESHOLDS,
   type SuiteResults, type SuiteThresholds,
 } from './adapters/vitest.js';
+
+export {
+  withMargin, withMarginApp,
+  marginHealthHandler, marginHealthAppHandler,
+  resetRoutes,
+  DEFAULT_NEXTJS_THRESHOLDS,
+  type WithMarginOptions, type NextjsThresholds,
+} from './adapters/nextjs.js';
+
+export {
+  StreamingMonitor,
+  broadcast, marginSSE, marginSSEHandler, marginPoll,
+  connectedClients, resetClients,
+} from './adapters/stream.js';