snagset 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eurico Sá Fernandes
+
+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,143 @@
+# `snagset`
+
+Click-to-comment review for a live website. Your client clicks the thing that's
+wrong and types; you get the pin, the screenshot, the console and the route.
+
+One import, or one script tag. Both do exactly the same thing.
+
+```bash
+npm install snagset
+```
+
+## Vanilla
+
+```js
+import snagset from "snagset";
+
+snagset.init({ host: "https://review.example.com", site: "prj_…" });
+```
+
+That is the whole API. `snagset.destroy()` takes it back off; `snagset.tag({…})`
+gives you the tag as data if you would rather render it yourself.
+
+## React
+
+```jsx
+import Snagset from "snagset/react";
+
+<Snagset host="https://review.example.com" site="prj_…" />
+```
+
+## Vue
+
+```vue
+<script setup>
+import Snagset from "snagset/vue";
+</script>
+
+<template>
+  <Snagset host="https://review.example.com" site="prj_…" />
+</template>
+```
+
+## Next.js
+
+```tsx
+// app/layout.tsx
+import { Snagset } from "snagset/next";
+
+<body>
+  {children}
+  <Snagset host="https://review.example.com" site="prj_…" />
+</body>
+```
+
+No `"use client"` — it renders the script tag on the server, so it costs zero
+client JavaScript. Leave the props off and it reads `NEXT_PUBLIC_SNAGSET_HOST`
+and `NEXT_PUBLIC_SNAGSET_SITE`, so each environment configures itself from
+`.env`. Works in the Pages Router too.
+
+## Vite — and Nuxt, SvelteKit, SolidStart, anything on Vite
+
+```ts
+// vite.config.ts
+import { snagset } from "snagset/vite";
+
+export default defineConfig({
+  plugins: [snagset({ host: "https://review.example.com", site: "prj_…" })],
+});
+```
+
+One line in a file the project already has; the tag is injected before
+`</body>`. In Nuxt, put it under `vite: { plugins: […] }` in `nuxt.config`.
+Want it only in dev? Use Vite's own idiom:
+`mode === "development" ? snagset({…}) : undefined`. Shipping the tag to
+production is safe either way — who sees the toolbar is a dashboard setting,
+checked by the tag on load, not something baked into your build.
+
+## Astro, Rails — anything that renders a layout
+
+```astro
+---
+import { snagsetTag } from "snagset/astro";
+const tag = snagsetTag({ host: "https://review.example.com", site: "prj_…" });
+---
+<script src={tag.src} {...tag.attrs} defer is:inline></script>
+```
+
+`is:inline` matters — without it Astro bundles the script and rewrites the
+`src`, and the widget finds its chunks relative to its own `src`.
+
+## Or no npm at all
+
+```html
+<script src="https://review.example.com/snag.js" data-snag-site="prj_…" defer></script>
+```
+
+That is what this package writes for you. There is no feature behind the npm
+install — if a script tag suits your stack better, use it. It works on
+WordPress, Webflow, Shopify and Rails, where a React-only tool cannot go.
+
+## Options
+
+Every `data-snag-*` attribute, as a camelCase key. `host` and `site` are the
+only required ones.
+
+| Option | What it does |
+|---|---|
+| `host` | Your Snagset instance |
+| `site` | The project uid, from the dashboard |
+| `env` | Which environment this build is — `staging`, `production` |
+| `theme` | `light`, `dark`, or leave it to follow the page |
+| `lang` | UI language |
+| `position` | Where the toolbar sits |
+| `hotkey` | Default is `alt+c` |
+| `branch`, `build` | Stamped onto every comment, for "which deploy was this?" |
+
+## What this package is
+
+**A loader.** It writes the script tag and nothing else — the widget itself is
+served by your Snagset instance, at your instance's version.
+
+That is deliberate. The widget is a lazy chunk graph: about 10 kB loads on
+every page and the remaining ~245 kB arrives only if somebody opens the toolbar.
+Bundling it here would put all of it into your bundle, and pin a widget version
+in your `package.json` that can drift from the server it talks to.
+
+It also means the bytes come from your own origin, so your CSP is one
+`script-src 'self'` entry and there is no third party to justify to anyone.
+
+## Requirements
+
+A Snagset instance. It self-hosts on Node and Postgres —
+[snagset/snagset](https://github.com/snagset/snagset), or
+`npx create-snagset` to scaffold one.
+
+---
+
+**Early release.** This is a `0.0.x` line: the tag it writes is stable and
+tested, but expect the odd rough edge, and pin the version if you need
+stability. Issues and notes are welcome at
+[snagset/snagset](https://github.com/snagset/snagset).
+
+MIT.

package/dist/astro.d.ts

@@ -0,0 +1,48 @@
+import { tagFor, type InitOptions } from "./index.ts";
+/**
+ * `snagset/astro` — D63.
+ *
+ * Astro is the case where the OTHER answer is better, and this file says so
+ * rather than pretending otherwise.
+ *
+ * Astro renders on the server and ships zero JavaScript by default. A component
+ * that exists only to run a `init()` effect in the browser would need a client
+ * directive (`client:load`), which means shipping a hydration runtime to boot a
+ * script tag — paying for a framework to do something HTML does natively.
+ *
+ * So this subpath gives you the tag as data, to render in your layout:
+ *
+ * ```astro
+ * ---
+ * import { snagsetTag } from "snagset/astro";
+ * const tag = snagsetTag({ host: "https://review.example.com", site: "prj_…" });
+ * ---
+ * <script src={tag.src} {...tag.attrs} defer is:inline></script>
+ * ```
+ *
+ * `is:inline` matters: without it Astro takes ownership of the script, bundles
+ * it, and rewrites the `src` — which breaks `resolveAssetBase`, because the
+ * widget finds its sibling chunks relative to its own `<script src>`.
+ *
+ * The same function is what a plain Nuxt/SvelteKit/Rails layout wants, and
+ * `useHead`/`svelte:head` consume it directly.
+ */
+export declare function snagsetTag(options: InitOptions): {
+    src: string;
+    attrs: Record<string, string>;
+    /** The whole thing as a string, for a template that wants one. */
+    html: string;
+};
+export { tagFor };
+/**
+ * Default-exported too, so a consumer who prefers defaults has one — but the
+ * NAMED import is what the docs show.
+ *
+ * `import snagset from "snagset/astro"` would give you a callable `snagset(…)`
+ * beside the core's `snagset.init(…)`, which is two different shapes under one
+ * name. `snagsetTag` says what it returns.
+ *
+ * The same function is on the core as `snagset.tag(…)` — it touches no DOM, so
+ * it is safe to call while rendering on a server.
+ */
+export default snagsetTag;

package/dist/astro.js

@@ -0,0 +1,50 @@
+import { tagFor } from "./index.js";
+/**
+ * `snagset/astro` — D63.
+ *
+ * Astro is the case where the OTHER answer is better, and this file says so
+ * rather than pretending otherwise.
+ *
+ * Astro renders on the server and ships zero JavaScript by default. A component
+ * that exists only to run a `init()` effect in the browser would need a client
+ * directive (`client:load`), which means shipping a hydration runtime to boot a
+ * script tag — paying for a framework to do something HTML does natively.
+ *
+ * So this subpath gives you the tag as data, to render in your layout:
+ *
+ * ```astro
+ * ---
+ * import { snagsetTag } from "snagset/astro";
+ * const tag = snagsetTag({ host: "https://review.example.com", site: "prj_…" });
+ * ---
+ * <script src={tag.src} {...tag.attrs} defer is:inline></script>
+ * ```
+ *
+ * `is:inline` matters: without it Astro takes ownership of the script, bundles
+ * it, and rewrites the `src` — which breaks `resolveAssetBase`, because the
+ * widget finds its sibling chunks relative to its own `<script src>`.
+ *
+ * The same function is what a plain Nuxt/SvelteKit/Rails layout wants, and
+ * `useHead`/`svelte:head` consume it directly.
+ */
+export function snagsetTag(options) {
+    const { src, attrs } = tagFor(options);
+    const rendered = Object.entries(attrs)
+        .map(([k, v]) => (v === "" ? ` ${k}` : ` ${k}="${v.replace(/"/g, "&quot;")}"`))
+        .join("");
+    return { src, attrs, html: `<script src="${src}"${rendered} defer></script>` };
+}
+export { tagFor };
+/**
+ * Default-exported too, so a consumer who prefers defaults has one — but the
+ * NAMED import is what the docs show.
+ *
+ * `import snagset from "snagset/astro"` would give you a callable `snagset(…)`
+ * beside the core's `snagset.init(…)`, which is two different shapes under one
+ * name. `snagsetTag` says what it returns.
+ *
+ * The same function is on the core as `snagset.tag(…)` — it touches no DOM, so
+ * it is safe to call while rendering on a server.
+ */
+export default snagsetTag;
+//# sourceMappingURL=astro.js.map

package/dist/astro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"astro.js","sourceRoot":"","sources":["../src/astro.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,UAAU,CAAC,OAAoB;IAM7C,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;SAC9E,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,QAAQ,kBAAkB,EAAE,CAAC;AACjF,CAAC;AAED,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB;;;;;;;;;;GAUG;AACH,eAAe,UAAU,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { type ScriptAttr } from "./vendor/types/names";
+/**
+ * `snagset` — the npm way in. D63, and D37's structure with D63's name.
+ *
+ * ── THIS PACKAGE DOES NOT CONTAIN THE WIDGET, AND THAT IS THE DESIGN ──
+ *
+ * It writes the script tag for you. Nothing more. The question that deserves an
+ * answer before anyone reads further is *why not just bundle it*, and the
+ * answer is measured rather than argued:
+ *
+ * | file | bytes |
+ * |---|---|
+ * | `snag.js` — the eager stub | **10 230** |
+ * | the other nine chunks, lazy | 245 945 |
+ *
+ * The widget is a lazy chunk graph. Ten kilobytes load on every page; the
+ * screenshot code, the panels, the fuzzy anchorer and the rest arrive only if
+ * somebody actually opens the toolbar. Bundling that into `snagset` would put a
+ * quarter of a megabyte into the host application's own bundle — or force them
+ * to teach their bundler about our code-splitting — and foundations §6's eager
+ * envelope, the budget the whole architecture is built around, would be a
+ * number about a file nobody loads.
+ *
+ * Three more things fall out of the shim that a bundle would break:
+ *
+ *  · **No version skew.** The chunks are fetched from the server at the
+ *    server's version. A bundled widget pinned in someone's `package.json` at
+ *    an older version would request chunk names that build no longer has.
+ *  · **Same-origin stays same-origin** (D38, A7). The bytes come from the
+ *    instance the widget already talks to, so a client's CSP is one
+ *    `script-src 'self'` entry and there is no third party to justify.
+ *  · **The script tag is still sacred** (D19, LOCK L5) — literally, not by
+ *    analogy. This package emits exactly the tag the docs tell you to paste,
+ *    so a bug here cannot produce behaviour the tag cannot.
+ *
+ * ── AND NO CUSTOM ELEMENT ──
+ *
+ * D37 sketched registering one so that "Vue, Svelte and Astro need no adapter
+ * at all". That was reasoning about a *bundled* widget, where a framework needs
+ * something to render. With a shim there is nothing to render — `init()` is
+ * already framework-agnostic, and the framework subpaths are lifecycle glue
+ * over this file rather than wrappers around an element. The custom element
+ * would be bytes added to the eager stub to solve a problem this shape does not
+ * have.
+ */
+/**
+ * Everything the script tag accepts, as an object.
+ *
+ * Keys are the attribute names minus their `data-snag-` prefix, which is the
+ * mapping `scriptAttr()` already owns — so this type cannot drift from the
+ * attribute registry, and a new attribute is accepted here the day it is
+ * registered rather than the day somebody remembers this file.
+ */
+export type SnagsetConfig = Partial<Record<ScriptAttr, string | number | boolean>>;
+export interface InitOptions extends SnagsetConfig {
+    /**
+     * The instance. `https://review.example.com`.
+     *
+     * Required, and the ONE thing with no sensible default: the widget has to
+     * know which server to talk to, and guessing `location.origin` would be
+     * wrong on every site that is not itself the instance — which is all of them.
+     */
+    host: string;
+    /** The project uid — `prj_…`, from the dashboard's Sites screen. */
+    site: string;
+    /** Where to put the tag. Defaults to `document.head`. */
+    target?: Element;
+}
+/** The tag this package writes, exposed for tests and for docs to render. */
+export declare function tagFor(options: InitOptions): {
+    src: string;
+    attrs: Record<string, string>;
+};
+/**
+ * Start Snagset on this page.
+ *
+ * ```js
+ * import snagset from "snagset";
+ *
+ * snagset.init({ host: "https://review.example.com", site: "prj_…" });
+ * ```
+ *
+ * ── WHY `init` AND NOT `mount` ──
+ *
+ * Because the product already had a name for this and it was not mine to
+ * choose. [02 §5](../../../specs/02-widget-runtime.md) defines
+ * **`Snagset.init(config)`** as the public JS API — *"may be called repeatedly
+ * before activation; each call merges"* — and `window.Snagset.init` /
+ * `window.Snagset.destroy` are on the live object right now.
+ *
+ * The first version of this package called it `mount`/`unmount`, which is React
+ * vocabulary imported into a package whose underlying object has said `init`
+ * since 02 draft 1. A developer reading `snagset.mount()` in their app and
+ * `Snagset.init()` in the console would reasonably conclude they were two
+ * different things. Raised by Eurico — *"init seems better than mount"* — and
+ * he is right for a better reason than either of us gave at the time.
+ *
+ * ── REPEATED CALLS MERGE, LIKE THE SPEC SAYS ──
+ *
+ * A second `init()` does not add a second tag (that would boot a second
+ * widget). It forwards the new config to `Snagset.init()`, which deep-merges
+ * it — so this behaves the way §5 documents rather than being a same-named
+ * function with different rules. When the widget has not finished loading the
+ * config is QUEUED and flushed on the script's `load` event, because a caller
+ * has no way to know whether an async script has arrived yet and "your second
+ * call was silently dropped depending on timing" is not a contract.
+ *
+ * Returns a function that removes the tag.
+ */
+declare function init(options: InitOptions): () => void;
+/**
+ * Take Snagset off the page — [02 §5](../../../specs/02-widget-runtime.md)'s
+ * `Snagset.destroy()`.
+ *
+ * Delegates to the widget's OWN teardown rather than removing the script
+ * element, because removing a script element does nothing at all: the code has
+ * already run, the listeners are already bound, and the toolbar is already in
+ * the DOM. That is the difference between a teardown that works and one that
+ * appears to.
+ */
+declare function destroy(): void;
+/**
+ * Is the tag on this page?
+ *
+ * `isInstalled`, not `isActive`: 02 §5's `state` is `inert | dormant | active`
+ * and "active" already means *the toolbar is open*, which is a different
+ * question with a different answer. Read `window.Snagset.state` for that one.
+ */
+declare function isInstalled(): boolean;
+/**
+ * The default export — the package's own name, carrying 02 §5's verbs.
+ *
+ * An OBJECT with `init`, not a callable. The first version made `snagset({…})`
+ * itself the call, on the argument that one verb should be the noun; with the
+ * verb named `init` that argument evaporates, and `snagset({…})` alongside
+ * `snagset.init({…})` would be two ways to do one thing in a brand-new API.
+ * This is the shape every SDK a developer has installed before this one has —
+ * `posthog.init`, `Sentry.init`, `mixpanel.init` — and now also the shape the
+ * widget's own global has, which matters more.
+ */
+export declare const snagset: {
+    init: typeof init;
+    destroy: typeof destroy;
+    isInstalled: typeof isInstalled;
+    tag: typeof tagFor;
+};
+export { init, destroy, isInstalled };
+export default snagset;

package/dist/index.js

@@ -0,0 +1,152 @@
+import { GLOBALS, scriptAttr } from "./vendor/types/names.js";
+const INSTALLED = "__snagset_npm_installed__";
+/** The tag this package writes, exposed for tests and for docs to render. */
+export function tagFor(options) {
+    const host = String(options.host).replace(/\/+$/, "");
+    const attrs = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (key === "target" || key === "host" || value === undefined || value === null)
+            continue;
+        // `false` is dropped rather than written as the string "false". Every one
+        // of these attributes is read by `loader.ts` as a STRING, and the presence
+        // of `data-snag-disabled="false"` reads as "disabled" to anything doing a
+        // has-attribute check — which is the shape of kill switch §6 uses.
+        if (value === false)
+            continue;
+        attrs[scriptAttr(key)] = value === true ? "" : String(value);
+    }
+    // `host` is both the config and the source, exactly as a hand-pasted tag has
+    // it: the tag's own `src` is what `resolveAssetBase` falls back to, so the
+    // chunks resolve with no extra configuration.
+    attrs[scriptAttr("host")] = host;
+    return { src: `${host}/snag.js`, attrs };
+}
+/**
+ * Start Snagset on this page.
+ *
+ * ```js
+ * import snagset from "snagset";
+ *
+ * snagset.init({ host: "https://review.example.com", site: "prj_…" });
+ * ```
+ *
+ * ── WHY `init` AND NOT `mount` ──
+ *
+ * Because the product already had a name for this and it was not mine to
+ * choose. [02 §5](../../../specs/02-widget-runtime.md) defines
+ * **`Snagset.init(config)`** as the public JS API — *"may be called repeatedly
+ * before activation; each call merges"* — and `window.Snagset.init` /
+ * `window.Snagset.destroy` are on the live object right now.
+ *
+ * The first version of this package called it `mount`/`unmount`, which is React
+ * vocabulary imported into a package whose underlying object has said `init`
+ * since 02 draft 1. A developer reading `snagset.mount()` in their app and
+ * `Snagset.init()` in the console would reasonably conclude they were two
+ * different things. Raised by Eurico — *"init seems better than mount"* — and
+ * he is right for a better reason than either of us gave at the time.
+ *
+ * ── REPEATED CALLS MERGE, LIKE THE SPEC SAYS ──
+ *
+ * A second `init()` does not add a second tag (that would boot a second
+ * widget). It forwards the new config to `Snagset.init()`, which deep-merges
+ * it — so this behaves the way §5 documents rather than being a same-named
+ * function with different rules. When the widget has not finished loading the
+ * config is QUEUED and flushed on the script's `load` event, because a caller
+ * has no way to know whether an async script has arrived yet and "your second
+ * call was silently dropped depending on timing" is not a contract.
+ *
+ * Returns a function that removes the tag.
+ */
+function init(options) {
+    // SSR guard first. This package is imported at module scope in a Next.js or
+    // Nuxt component, so it IS evaluated on the server, and touching `document`
+    // there throws before anything can explain itself.
+    if (typeof document === "undefined")
+        return () => { };
+    const w = window;
+    if (w[INSTALLED]) {
+        merge(options);
+        return () => { };
+    }
+    if (!options.host)
+        throw new Error("snagset: `host` is required — the URL of your Snagset instance.");
+    if (!options.site)
+        throw new Error("snagset: `site` is required — the project uid, which looks like prj_….");
+    const { src, attrs } = tagFor(options);
+    const el = document.createElement("script");
+    el.src = src;
+    el.defer = true;
+    for (const [name, value] of Object.entries(attrs))
+        el.setAttribute(name, value);
+    el.addEventListener("load", flush, { once: true });
+    w[INSTALLED] = true;
+    (options.target ?? document.head).appendChild(el);
+    return () => {
+        el.remove();
+        w[INSTALLED] = false;
+        queued.length = 0;
+    };
+}
+/** Config handed to `init()` after the first call, before the widget exists. */
+const queued = [];
+function widget() {
+    if (typeof window === "undefined")
+        return undefined;
+    return window[GLOBALS.api];
+}
+function merge(options) {
+    const api = widget();
+    // `target` is OURS — where to put the tag — and means nothing to the widget.
+    const { target: _drop, ...config } = options;
+    if (api?.init)
+        api.init(config);
+    else
+        queued.push(options);
+}
+function flush() {
+    const pending = queued.splice(0);
+    for (const options of pending)
+        merge(options);
+}
+/**
+ * Take Snagset off the page — [02 §5](../../../specs/02-widget-runtime.md)'s
+ * `Snagset.destroy()`.
+ *
+ * Delegates to the widget's OWN teardown rather than removing the script
+ * element, because removing a script element does nothing at all: the code has
+ * already run, the listeners are already bound, and the toolbar is already in
+ * the DOM. That is the difference between a teardown that works and one that
+ * appears to.
+ */
+function destroy() {
+    if (typeof window === "undefined")
+        return;
+    widget()?.destroy?.();
+    window[INSTALLED] = false;
+    queued.length = 0;
+}
+/**
+ * Is the tag on this page?
+ *
+ * `isInstalled`, not `isActive`: 02 §5's `state` is `inert | dormant | active`
+ * and "active" already means *the toolbar is open*, which is a different
+ * question with a different answer. Read `window.Snagset.state` for that one.
+ */
+function isInstalled() {
+    return typeof window !== "undefined" && !!window[INSTALLED];
+}
+/**
+ * The default export — the package's own name, carrying 02 §5's verbs.
+ *
+ * An OBJECT with `init`, not a callable. The first version made `snagset({…})`
+ * itself the call, on the argument that one verb should be the noun; with the
+ * verb named `init` that argument evaporates, and `snagset({…})` alongside
+ * `snagset.init({…})` would be two ways to do one thing in a brand-new API.
+ * This is the shape every SDK a developer has installed before this one has —
+ * `posthog.init`, `Sentry.init`, `mixpanel.init` — and now also the shape the
+ * widget's own global has, which matters more.
+ */
+export const snagset = { init, destroy, isInstalled, tag: tagFor };
+export { init, destroy, isInstalled };
+export default snagset;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/next.d.ts

@@ -0,0 +1,51 @@
+import { createElement } from "react";
+import { type InitOptions } from "./index.ts";
+/**
+ * `snagset/next` — D67.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { Snagset } from "snagset/next";
+ *
+ * <body>
+ *   {children}
+ *   <Snagset host="https://review.example.com" site="prj_…" />
+ * </body>
+ * ```
+ *
+ * ── A SERVER COMPONENT, NOT A CLIENT EFFECT ──
+ *
+ * `snagset/react` runs `init()` in a `useEffect`, because a generic React tree
+ * offers nothing better. Next offers something better: this component has no
+ * hooks and no `"use client"`, so in the App Router it renders on the server
+ * and the script tag arrives IN the HTML — zero client JavaScript, zero
+ * hydration, byte-for-byte the tag the docs tell you to paste. It degrades
+ * cleanly too: in the Pages Router (or any client tree) it renders the same
+ * element and React mounts it, which boots the script just the same.
+ *
+ * ── WHY THERE IS NO `withSnagset(nextConfig)` WRAPPER ──
+ *
+ * Vercel's own toolbar ships one because their setup needs `next.config`
+ * rewrites to proxy toolbar traffic through the deployment. Ours needs no
+ * proxy: the widget is served by the studio's instance and talks back to that
+ * same origin (D38). A config wrapper would exist to look like theirs, not to
+ * do anything — the component is the whole install.
+ *
+ * ── PROPS, OR `NEXT_PUBLIC_SNAGSET_*` ──
+ *
+ * A bare `<Snagset />` reads `NEXT_PUBLIC_SNAGSET_HOST` and
+ * `NEXT_PUBLIC_SNAGSET_SITE`, so per-environment values live where a Next
+ * project already keeps them (`.env.local`, the host's env UI) instead of in
+ * the layout. The names carry Next's own public prefix — deliberately NOT bare
+ * `SNAGSET_*`, which is the server's reserved namespace (08 §4): an instance
+ * colocated with the app must never find widget config in variables it treats
+ * as its own and refuses to boot on.
+ *
+ * Missing config renders NOTHING rather than throwing: this sits in the root
+ * layout, and a review widget that can take down every page of the site over
+ * an unset env var would violate the product's oldest rule. The dev-only
+ * console line is the diagnostic.
+ */
+export type SnagsetProps = Partial<InitOptions>;
+export declare function Snagset(props?: SnagsetProps): ReturnType<typeof createElement> | null;
+export default Snagset;

package/dist/next.js

@@ -0,0 +1,17 @@
+import { createElement } from "react";
+import { tagFor } from "./index.js";
+export function Snagset(props = {}) {
+    const hasEnv = typeof process !== "undefined" && !!process.env;
+    const host = props.host ?? (hasEnv ? process.env.NEXT_PUBLIC_SNAGSET_HOST : undefined);
+    const site = props.site ?? (hasEnv ? process.env.NEXT_PUBLIC_SNAGSET_SITE : undefined);
+    if (!host || !site) {
+        if (hasEnv && process.env.NODE_ENV !== "production") {
+            console.warn("snagset/next: rendering nothing — set `host` and `site` props, or NEXT_PUBLIC_SNAGSET_HOST and NEXT_PUBLIC_SNAGSET_SITE.");
+        }
+        return null;
+    }
+    const { src, attrs } = tagFor({ ...props, host, site });
+    return createElement("script", { src, defer: true, ...attrs });
+}
+export default Snagset;
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,MAAM,EAAoB,MAAM,YAAY,CAAC;AAkEtD,MAAM,UAAU,OAAO,CAAC,QAAsB,EAAE;IAC9C,MAAM,MAAM,GAAG,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IAC/D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAQ,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACxF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAQ,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACxF,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,IAAI,MAAM,IAAI,OAAQ,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YACrD,OAAO,CAAC,IAAI,CACV,0HAA0H,CAC3H,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,OAAO,aAAa,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,eAAe,OAAO,CAAC"}