npm package: @sanmid/flux
Description: A design editor for your localhost — tweak UI in place and copy changes for any AI agent. React only.
Author: Sanmid Anavkar
Latest version: 0.1.9

# Flux

**A design editor for your localhost.** Point to an element on the UI, tweak visual properties and copy the changes. The copied changes can be sent to any AI agent with the source to make the changes come alive.

**React only for now** — Flux ships as a React component; Vue, Svelte, and plain HTML apps are not supported yet.

---

## Install

```bash
npm install @sanmid/flux -D
```

Or: `pnpm add -D @sanmid/flux` · `yarn add -D @sanmid/flux`

Icons, `clsx`, and `tailwind-merge` are **dependencies of Flux** — you do not install them separately. You only need **`react` and `react-dom` (18+)** in your app (Flux lists them as peer dependencies so one React instance is shared with your UI).

---

## Local development (localhost)

Mount `DesignEditor` in your app root (providers layout) so it appears over your pages in dev:

```tsx
"use client";
import { DesignEditor } from "@sanmid/flux";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      {process.env.NODE_ENV === "development" && <DesignEditor />}
    </>
  );
}
```

Open your app at `http://localhost:3000` (or your dev URL). Toggle the editor with the floating control or **⌘.** / **Ctrl+.**

- **`force`** — render in production builds (use only if you accept exposing the overlay to end users).
- **`blockPageInteractions`** — optional; blocks clicks on buttons/links on the host page while editing (useful in demos).
- **Inline text** — double-click the current selection to edit copy in place (plain text nodes, text-like inputs). Blur commits, **Escape** cancels. Stored with other preview data in `localStorage`. In React apps, a host re-render can still overwrite DOM text until you wire edits into your source of truth.

## Tailwind

Flux **injects its own utility CSS** for light-DOM UI (floating toggle, panel chrome, etc.), so you **do not** need to add Flux to your Tailwind `content` for normal use.

If you fork Flux or build from source and change its class names, add your paths (or the published bundle) to `content` so your build picks up those utilities.

## Next.js

**No extra Next config** — the published build ships **ESM and CJS** (`package.json` `exports`) and a **`"use client"`** banner so the App Router can consume `@sanmid/flux` like any other dependency. Mount `DesignEditor` from a client component (as in [Local development](#local-development-localhost)) and you are done.

If you ever hit a resolution error on an older Next.js release, try adding `transpilePackages: ["@sanmid/flux"]` to `next.config` as a fallback.

## Security

See [SECURITY.md](./SECURITY.md) for data handling (clipboard, `localStorage`, DOM), reporting vulnerabilities, and production considerations.

## Publishing to npm (maintainers)

1. **Version** — bump `"version"` in `package.json` (semver).
2. **Build** — `pnpm install && pnpm run build` (runs automatically via `prepublishOnly`).
3. **Login** — `npm login` (or your registry).
4. **Publish** — `npm publish --access public` (required for **scoped** public packages like `@sanmid/flux`).

Optional: enable **provenance** on supported registries for supply-chain transparency.

## Repository layout

| Path | Role |
| --- | --- |
| **`src/`** | Library source (TypeScript / React). |
| **`dist/`** | Build output (not committed). Produced by `pnpm run build`. |
| **`package.json` → `files`** | **Only** `dist`, `README.md`, `LICENSE`, and `SECURITY.md` are published to npm — that is what consumers install. |
| **`playground/`** | Optional Vite app for local testing; **not** on npm, but usually **kept in git** so maintainers can run `pnpm run dev:playground` without a separate repo. |
| **`scripts/`** | Tailwind → CSS strings, `tsup`, `prepend-use-client`. |

## Playground

This repo includes a **private** Vite app under `playground/` for local demos. It is **not** part of the published npm artifact. See [CONTRIBUTING.md](./CONTRIBUTING.md).

```bash
pnpm run dev:playground
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT — see [LICENSE](./LICENSE). Other packages on npm may use different licenses (for example Polyform Shield); that is independent of Flux’s license.