@syrin/iris 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iris contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/syrin-labs/iris@main/assets/readme/lockup-on-dark.png" />
+  <img alt="Syrin Iris — eyes for your coding agent" src="https://cdn.jsdelivr.net/gh/syrin-labs/iris@main/assets/readme/lockup-on-light.png" width="300" />
+</picture>
+
+### Your AI writes the code. Iris tells it whether the code actually works — with evidence, not screenshots.
+
+<a href="https://github.com/syrin-labs/iris"><img src="https://cdn.jsdelivr.net/gh/syrin-labs/iris@main/assets/readme/hero.gif" alt="Iris catches a 401 your agent said was 'done' — pass:false with evidence, then a one-line fix to pass:true" width="760" /></a>
+
+[![npm](https://img.shields.io/npm/v/@syrin/iris?color=8b7bff&labelColor=15131f&logo=npm)](https://www.npmjs.com/package/@syrin/iris)
+[![downloads](https://img.shields.io/npm/dm/@syrin/iris?color=5fd9f5&labelColor=15131f)](https://www.npmjs.com/package/@syrin/iris)
+[![license](https://img.shields.io/badge/license-MIT-46d6a0?labelColor=15131f)](https://github.com/syrin-labs/iris/blob/main/LICENSE)
+
+**TypeScript · Model Context Protocol · React-first · dev-only · localhost-only · MIT**
+
+[Docs & full README](https://github.com/syrin-labs/iris) · [Getting Started](https://github.com/syrin-labs/iris/blob/main/docs/getting-started.md) · [Why it's ~73× cheaper](https://github.com/syrin-labs/iris/blob/main/docs/token-efficiency.md)
+
+</div>
+
+---
+
+## The problem: your agent has hands, but no eyes
+
+You ask your AI agent to build a feature. It edits the files, says _"done ✅"_ — and then **you** open the
+browser, click around, and find out it isn't. Every. Single. Time. The agent can't really check its own
+work, so you become its QA department. Screenshots are bad eyes: ~1,500+ tokens through a vision model,
+slow, non-deterministic, and **blind to everything non-visual** — the failed request, the console error,
+the route that didn't change, the webhook that never came.
+
+## The idea: your app already knows what happened — let the agent ask
+
+Iris exposes your running app to your agent over **MCP** as a tight loop — **look → act → observe →
+assert** — and one call checks many things at once and comes back with proof:
+
+```jsonc
+// The agent clicked "Pay". Did the right things actually happen? One call, ~33 tokens, no screenshot:
+iris_assert({
+  predicate: { allOf: [
+    { kind: "net",     method: "POST", urlContains: "/api/order", status: 200 },
+    { kind: "element", query: { role: "dialog", name: "Order confirmed" }, state: "visible" },
+    { kind: "signal",  name: "order:saved" },          // the charge actually committed
+    { kind: "console", level: "error", absent: true }  // ...and nothing errored
+  ]}
+})
+// → { pass: false, evidence: { net: { status: 500, url: "/api/order" } },
+//     failureReason: "POST /api/order returned 500, expected 200",
+//     source: { file: "src/checkout/PayButton.tsx", line: 42 } }   ❌ caught before you ever saw it
+```
+
+Deterministic (structured events, not pixels), cheap (any model, no vision), and it points at the **file:line** to fix.
+
+## Quickstart
+
+**One install** — SDK, React adapter, source-mapping plugins, spec runner, and the MCP server all ship in
+a single package:
+
+```bash
+npm i -D @syrin/iris
+```
+
+**1. Point your agent at the MCP server** (Claude Code `.mcp.json`, Cursor, Windsurf, …):
+
+```jsonc
+{ "mcpServers": { "iris": { "command": "npx", "args": ["@syrin/iris"] } } }
+```
+
+**2. Embed the SDK in your app (dev only):**
+
+```ts
+import { iris } from '@syrin/iris';
+if (import.meta.env.DEV) iris.connect({ session: 'my-app' });
+```
+
+Run your app and ask your agent: _"add a logout button and verify it works with Iris."_
+→ [Full Getting Started walkthrough](https://github.com/syrin-labs/iris/blob/main/docs/getting-started.md).
+
+## What it can verify
+
+API calls (`net`) · DOM changes · SPA navigation · console & errors (incl. "**no** errors") · animations ·
+app **signals** (webhooks, store commits, async jobs you surface via `iris.signal()`) · **regressions**
+(baseline now, diff later) · **source mapping** (DOM → React component → file:line). Plus an autonomous
+crawler. ~44 MCP tools in total.
+
+## ~73× fewer tokens than feeding the agent the whole page
+
+|                                                        | Tokens per step |
+| ------------------------------------------------------ | --------------: |
+| Full accessibility-tree snapshot (e.g. Playwright MCP) |          ~7,300 |
+| **Iris verify loop** (query + observe + assert)        |        **~100** |
+
+The honest version: force Iris to dump the whole tree too and the gap is only ~1.8×. The 73× comes from
+**not needing the whole tree** — that's architectural.
+[Full methodology + caveats →](https://github.com/syrin-labs/iris/blob/main/docs/token-efficiency.md)
+
+## How is this different?
+
+Everyone now gives agents _eyes_; **Iris gives agents a _verdict_.** Playwright/Cypress are scripted CI
+tests you write and maintain. Playwright MCP / Chrome DevTools MCP let an agent _drive_ a separate browser
+(token-heavy snapshots, no first-class assert/regression/source-map). Iris runs _inside_ your real running
+app (your session/auth), returns a verdict-with-evidence in ~100 tokens, sees what screenshots can't,
+catches silent regressions, and points at the file to fix. **They compose: drive with Playwright MCP,
+verify with Iris.**
+
+---
+
+dev-only and localhost-only by default · no telemetry · tree-shaken out of production · MIT
+
+**[→ Full documentation on GitHub](https://github.com/syrin-labs/iris)**

package/dist/babel.d.ts

@@ -0,0 +1,14 @@
+import { types, PluginObj, PluginPass } from '@babel/core';
+
+declare const SOURCE_ATTR = "data-iris-source";
+interface PluginApi {
+    types: typeof types;
+}
+/**
+ * Stamps `data-iris-source="relativeFile:line:col"` on every JSX host element (lowercase
+ * tag). @syrin/iris-react reads it to map a DOM node back to its source — needed on React 19,
+ * which removed `_debugSource`. Intended for dev builds only.
+ */
+declare function irisSourcePlugin({ types: t }: PluginApi): PluginObj<PluginPass>;
+
+export { SOURCE_ATTR, irisSourcePlugin as default };

package/dist/babel.js

@@ -0,0 +1,32 @@
+// ../babel-plugin/dist/index.js
+import { relative } from "path";
+var SOURCE_ATTR = "data-iris-source";
+function irisSourcePlugin({ types: t }) {
+  return {
+    name: "iris-source",
+    visitor: {
+      JSXOpeningElement(path, state) {
+        const node = path.node;
+        if (node.name.type !== "JSXIdentifier")
+          return;
+        const first = node.name.name[0];
+        if (first === void 0 || first !== first.toLowerCase())
+          return;
+        const alreadyStamped = node.attributes.some((attr) => attr.type === "JSXAttribute" && attr.name.type === "JSXIdentifier" && attr.name.name === SOURCE_ATTR);
+        if (alreadyStamped)
+          return;
+        const loc = node.loc;
+        if (loc === null || loc === void 0)
+          return;
+        const filename = state.filename ?? "unknown";
+        const rel = relative(process.cwd(), filename);
+        const value = `${rel}:${String(loc.start.line)}:${String(loc.start.column)}`;
+        node.attributes.push(t.jsxAttribute(t.jsxIdentifier(SOURCE_ATTR), t.stringLiteral(value)));
+      }
+    }
+  };
+}
+export {
+  SOURCE_ATTR,
+  irisSourcePlugin as default
+};

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import './spec.js';
+import './registry.js';
+import './runner.js';
+import './summary.js';
+import './junit.js';
+import './boot.js';
+import './skip.js';
+import './test-context.js';
+import './clock.js';
+import './resolve.js';
+import './input-mode.js';
+import './constants.js';
+import './types.js';
+import './flow-spec.js';
+import './success-assert.js';
+import './register.js';