agentation-team

A self-contained React feedback toolbar for agentation-rs. Drop one component into your app — designers / PMs click any element on the page, leave a comment, and it becomes a ticket the team (and AI agents) can act on. No third-party toolbar dependency.

• Backend (API): https://agentation-rs.vercel.app (baked in)
• Admin console: https://agentation-admin.vercel.app

Install

npm i agentation-team

Peer deps: react and react-dom (>=18). That's it.

Use

import { AgentationTeam } from "agentation-team";

export default function App() {
  return (
    <>
      <YourApp />
      {/* on everywhere EXCEPT real production — see "Gating" below */}
      {process.env.APP_ENV !== "production" && <AgentationTeam />}
    </>
  );
}

No server / projectId needed — the backend URL is baked in and projectId / env / brand are derived from the hostname.

Gating: do NOT use NODE_ENV

You almost certainly want the toolbar on in deployed non-production environments (staging / release / preview) but off in real production. The trap: bundlers derive NODE_ENV — and Vite's import.meta.env.PROD / import.meta.env.MODE — from the build mode, which is production for every vite build / next build / webpack --mode production, including your staging and release builds. So this only ever renders on your local dev server:

// ❌ true only on the local dev server — never in a deployed staging/release build
{process.env.NODE_ENV !== "production" && <AgentationTeam />}

Gate instead on a variable that reflects the deploy target and is injected into the client bundle. Most apps already have one (APP_ENV, DEPLOY_ENV, REACT_APP_ENV, …):

{process.env.APP_ENV !== "production" && <AgentationTeam />}

Two things to verify:

1. The variable is exposed to client code. It must be in your bundler's define / env allow-list (e.g. Vite only injects what your config maps; CRA only injects REACT_APP_*). If it isn't injected, the check can't tell environments apart and silently does the wrong thing.
2. It is set per environment at build time to the right value (staging, release-x, production, …).

No such variable? Gate on the hostname instead:

{location.hostname !== "app.example.com" && <AgentationTeam />}

Features

A half-hidden handle sits on the right edge. Click to open the panel.

• New feedback — start a capture, hover-highlight any element, click to attach a comment. We record the CSS selector path, nearby text, and the source location (from the React fiber _debugSource, when the build keeps JSX __source — see below). The composer lets you set a priority (blocking / important / suggestion).
• Environment-shared list — feedback is scoped to the environment (project + env + brand), so everyone working on the same env sees each other's feedback, newest first, each tagged with its author and priority. Polls every ~5s.
• Chat threads — per item: the original comment plus replies, with names; reply inline (⌘/Ctrl+Enter). Status actions (acknowledge / resolve / dismiss) and soft-delete for your own items.
• On-page markers (on by default, toggle in the panel) — numbered pins over the elements that have feedback; click a pin to open its thread.
• Environment mapping (local dev only) — a second handle lets a developer running locally point the toolbar at another environment's feedback (e.g. production / staging) and triage it (read / reply / change status) without leaving localhost.
• Notifications — replies / status changes to your own items light a badge on the handle when collapsed.
• Soft delete — deleting your feedback marks it withdrawn; the platform keeps it, flagged.

View, reply, change status, and jump to source in the admin console.

Props (all optional)

| Prop | Default | Notes | |---|---|---| | server | hosted backend URL | Override the API base. | | projectId | derived from hostname | Explicit project override. | | authorName | prompted once | Pass your logged-in user to skip the prompt. | | storageKey | "agentation:author" | localStorage key for the author name. | | label | "反馈" (Chinese for "Feedback") | Text on the right-edge handle; override to localize. |

projectId / env / brand

Derived from window.location.hostname (mirrors the backend derive module):

| hostname | projectId | env | brand | |---|---|---|---| | admin.aftership.io | admin | io | aftership | | release-pear-admin.aftership.io | admin | release-pear | aftership | | staging-admin.aftership.com | admin | staging | aftership | | admin.automizely.com | admin | production | automizely | | localhost | localhost | local | local |

Feedback is grouped by (brand, project, env), so the same build across release / staging / production / brands stays cleanly separated.

Source-location deep links (opt-in build config)

The "jump to source" feature reads each element's source position at runtime from the React fiber (_debugSource, falling back to props.__source). This is not source maps — enabling .map output does nothing for this feature, and you do not need source maps for it.

What populates _debugSource / __source is the JSX source transform (@babel/plugin-transform-react-jsx-source). Most toolchains run it only in development and strip it from production-mode builds. So:

• Local dev — works out of the box (the transform is on).
• Built non-prod envs (release / staging / preview) — the toolbar still runs, but unless you keep the source transform in that build, the source line is empty. Everything else (comment, selector path, nearby text, thread, status, markers) works regardless.

If you want source links in a built env, keep the transform on for that build only (don't ship it to real production — it embeds file paths in the bundle).

Vite (@vitejs/plugin-react)

@vitejs/plugin-react injects the source transform automatically on the dev server but drops it in vite build. Re-add it for the non-prod builds where the toolbar runs:

npm i -D @babel/plugin-transform-react-jsx-source

// vite.config.js
import react from "@vitejs/plugin-react";

// build (not serve) + any env that isn't real production
const keepSource =
  process.argv.includes("build") && process.env.APP_ENV !== "production";

export default {
  plugins: [
    react(
      keepSource
        ? { babel: { plugins: ["@babel/plugin-transform-react-jsx-source"] } }
        : undefined
    ),
    // ...your other plugins
  ],
};

(In production builds __source lands on props.__source, which the toolbar reads as a fallback — so the deep link still resolves.)

CRA / raw Babel

Ensure @babel/plugin-transform-react-jsx-source (or @babel/preset-react with development: true) runs for the envs where the toolbar is enabled.

React version

Reading fiber._debugSource relies on React 18's dev fiber metadata. On React 19 (where _debugSource was removed) only the props.__source fallback applies — so the source transform above is what makes it work there.