@insitue/swc-source-attr 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rod Leviton
+
+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,113 @@
+# `@insitue/swc-source-attr`
+
+SWC plugin that stamps every JSX element with a `data-insitu-source="file:line:col"`
+attribute so the [InSitue](https://www.insitue.com) cloud agent can resolve in-app bug
+reports to exact source coordinates and open the right pull request automatically.
+
+> **Spelling note** — the npm package is `@insitue/*` (with the 'e'); the DOM attribute
+> stays as `data-insitu-source` (no 'e'). The split is intentional: the brand evolves,
+> the wire format doesn't.
+
+## Why you need this
+
+In production builds, React strips its component-debugger metadata (`_debugSource`,
+`_debugOwner`, component names get minified). Without an explicit source attribute, the
+[InSitue capture SDK](https://www.npmjs.com/package/@insitue/sdk) can only ship a CSS
+selector + DOM snapshot — and the cloud agent has to guess which file to edit. Confidence
+drops below the resolution threshold and the report routes to `needs_human` instead of
+auto-opening a draft PR.
+
+This plugin fixes that by injecting `data-insitu-source` at compile time. Customers using
+it land in the "auto-PR" path; customers without it stay in the "needs human review" path.
+
+## Install
+
+```bash
+pnpm add -D @insitue/swc-source-attr
+# or: npm install --save-dev @insitue/swc-source-attr
+```
+
+## Wire into Next.js
+
+```js
+// next.config.mjs
+const nextConfig = {
+  experimental: {
+    swcPlugins: [
+      ['@insitue/swc-source-attr', { rootDir: process.cwd() }],
+    ],
+  },
+};
+export default nextConfig;
+```
+
+That's it. Build your app normally — every JSX element in the output now carries
+`data-insitu-source="<rel-path>:<line>:<col>"`.
+
+## Options
+
+| Option | Type | Default | What |
+|---|---|---|---|
+| `rootDir` | `string` | _none_ | Project root, used to make emitted paths relative + portable. Recommend `process.cwd()`. Without it, paths are absolute (still works but leaks your local filesystem layout into the bundle). |
+| `attrName` | `string` | `"data-insitu-source"` | Override only if the default collides with another tool. The [`@insitue/sdk`](https://www.npmjs.com/package/@insitue/sdk) picker reads the default name — if you override here, override the SDK's matching option too. |
+| `exclude` | `string[]` | `[]` | Substrings; files whose path contains any of these are skipped. Cheap substring match — no glob library on the compile hot path. E.g. `["node_modules/", "/generated/"]`. |
+
+## How it behaves
+
+- **Idempotent.** Elements that already have `data-insitu-source` are left alone — safe to
+  run alongside the [Babel-plugin fallback](https://www.npmjs.com/package/@insitue/sdk)
+  during a migration.
+- **Per-file skip via `exclude`.** Whole files matching any exclude substring are skipped
+  entirely (the plugin doesn't visit their AST at all).
+- **Paths are POSIX, relative to `rootDir`.** If your `rootDir` is `/Users/you/app` and the
+  file is `/Users/you/app/src/components/Button.tsx`, the emitted attribute is
+  `data-insitu-source="src/components/Button.tsx:42:8"`. Line is 1-based; column is the
+  0-based byte offset (matches SWC's convention).
+
+## Compatibility
+
+This plugin compiles against `swc_core` 50.x — the version Next.js 15.5.x bundles in
+`@next/swc`. SWC's plugin ABI breaks periodically (see SWC's
+[plugin-compat docs](https://swc.rs/docs/plugin/selecting-swc-core)). We pin to the latest
+stable swc_core supported by current Next, and ship patch releases when Next bumps.
+
+| `@insitue/swc-source-attr` | `swc_core` | Verified with Next.js |
+|---|---|---|
+| `0.1.x` | `50.2.3` | `15.5.x` |
+
+If you hit one of the SWC plugin-host error signatures
+(`failed to invoke plugin`, `out of bounds memory access`,
+`LayoutError called Result::unwrap()`), you're on an incompatible combination — either
+upgrade Next.js to the matching version or fall back to the
+[Babel plugin](https://www.npmjs.com/package/@insitue/sdk) (`@insitue/sdk/babel` — Babel's
+ABI is stable forever, no compat dance).
+
+## What it does, end-to-end
+
+```jsx
+// You write:
+function Button({ children }) {
+  return <button className="bg-violet-500">{children}</button>;
+}
+
+// SWC + this plugin emit (in your prod bundle):
+function Button({ children }) {
+  return (
+    <button
+      className="bg-violet-500"
+      data-insitu-source="src/components/Button.tsx:2:10"
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+When a real user clicks that button in your deployed app and reports a bug via the
+`@insitue/sdk` widget, the captured bundle carries the exact `file:line:col`. The cloud
+agent opens `src/components/Button.tsx`, jumps to line 2, edits with full context, runs
+your typecheck + build inside a sandbox, and pushes a draft PR for review.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@insitue/swc-source-attr",
+  "version": "0.1.1",
+  "description": "SWC plugin that stamps every JSX element with data-insitu-source=\"file:line:col\" so the InSitue cloud agent can resolve captures to exact source coordinates.",
+  "license": "MIT",
+  "main": "insitue_swc_source_attr.wasm",
+  "files": [
+    "insitue_swc_source_attr.wasm",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InSitue/insitue.git",
+    "directory": "packages/swc-source-attr"
+  },
+  "homepage": "https://www.insitue.com",
+  "bugs": {
+    "url": "https://github.com/InSitue/insitue/issues"
+  },
+  "keywords": [
+    "insitue",
+    "swc",
+    "swc-plugin",
+    "babel",
+    "source",
+    "jsx",
+    "instrumentation",
+    "react",
+    "nextjs"
+  ],
+  "author": "InSitue (https://www.insitue.com)",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "cargo build-wasi && cp target/wasm32-wasip1/release/insitue_swc_source_attr.wasm .",
+    "test": "cargo test"
+  }
+}