@sanmid/flux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Sanmid Anavkar
+
+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,88 @@
+# Flux
+
+Visual editor overlay for React: inspect the DOM, tweak styles with a live preview, undo/redo, and copy a structured prompt for your AI workflow. **Flux branding only** — no third-party product names in the UI or copy output.
+
+## Install
+
+```bash
+pnpm add @sanmid/flux lucide-react clsx tailwind-merge framer-motion
+# or: npm / yarn with the same peer dependencies
+```
+
+Peers: `react`, `react-dom` (18+), `lucide-react`, `clsx`, `tailwind-merge`, `framer-motion`.
+
+## 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
+
+Include the built bundle in `content` so utilities used inside Flux are generated:
+
+```js
+// tailwind.config.ts
+export default {
+  content: [
+    "./app/**/*.{ts,tsx}",
+    "./components/**/*.{ts,tsx}",
+    "./node_modules/@sanmid/flux/dist/index.js",
+  ],
+};
+```
+
+## Next.js
+
+```js
+const nextConfig = {
+  transpilePackages: ["@sanmid/flux"],
+};
+```
+
+## 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.
+
+## 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.

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## Reporting issues
+
+Please report security vulnerabilities through **GitHub Security Advisories** for this repository (preferred) or by opening a private discussion with maintainers if that option is unavailable.
+
+Do not file public issues for undisclosed vulnerabilities.
+
+## Threat model (npm package)
+
+Flux is a **client-side React library** that runs in the browser alongside your app.
+
+| Area | Behavior |
+|------|----------|
+| **Network** | The published package does **not** ship telemetry or call remote APIs for core editing. Your app’s own network traffic is unchanged by Flux alone. |
+| **Clipboard** | Copy uses the browser **Clipboard API** / `execCommand('copy')` **after a user gesture** (e.g. clicking Copy). Prompt text reflects DOM and styles under the user’s control. |
+| **Storage** | Preview state may be persisted to **`localStorage`** (namespaced keys) so edits survive reloads during development. Treat stored data as **sensitive as your page content**; clear site data if needed. |
+| **DOM** | The editor injects UI (overlay, panel, drag layers) and may set temporary inline styles during drag/reposition. It applies preview CSS via a stylesheet; review `PreviewEngine` if you extend integration. |
+| **Dependencies** | Runtime deps are limited (see `package.json`). Run `pnpm audit` / `npm audit` in your app and keep peers updated. |
+
+## Production use
+
+`DesignEditor` is intended for **development** by default (`NODE_ENV === "development"`). Use `force` only when you understand the risk of exposing a design surface in production.
+
+## Supply chain
+
+- Publish from **clean CI** with **npm provenance** if you maintain the package (`npm publish --provenance` on supported registries).
+- Pin lockfiles in apps that consume Flux.

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type DesignEditorProps = {
+    /**
+     * When true, the editor mounts in production builds.
+     * Default is **development only** (`process.env.NODE_ENV === "development"`).
+     */
+    force?: boolean;
+    /**
+     * Classic margin / border / padding overlay bands on the selected node.
+     * Default **false** — only the mint selection ring is shown unless you opt in.
+     */
+    showBoxModel?: boolean;
+    /**
+     * When the overlay is active, block default actions on interactive page nodes (buttons, links, inputs, …)
+     * via capture-phase listeners. Opt-in for host apps (e.g. playgrounds); default **false**.
+     */
+    blockPageInteractions?: boolean;
+};
+/**
+ * Visual design editor overlay. **Does not render in production** unless `force` is set.
+ */
+declare function DesignEditor({ force, showBoxModel, blockPageInteractions, }: DesignEditorProps): react_jsx_runtime.JSX.Element | null;
+
+/** Persisted for copy prompt after a successful DOM reorder. */
+type FluxStructuralReorder = {
+    type: "reorder";
+    containerSelector: string;
+    containerComponents: string[];
+    originalOrder: string[];
+    newOrder: string[];
+    childrenType: "array" | "static";
+    containerSourceFile: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    } | null;
+    childSources?: {
+        label: string;
+        sourceFile: {
+            fileName: string;
+            lineNumber: number;
+            columnNumber?: number;
+        };
+    }[];
+    timestamp: number;
+};
+
+/**
+ * Live preview engine using Constructable Stylesheets when supported,
+ * otherwise a single <style> tag in document.head.
+ *
+ * Applies CSS changes without mutating the host element's inline styles.
+ */
+interface AppliedRule {
+    selector: string;
+    property: string;
+    value: string;
+}
+declare class PreviewEngine {
+    private sheet;
+    private fallbackStyle;
+    private rules;
+    private attached;
+    constructor();
+    attach(): void;
+    detach(): void;
+    applyChange(selector: string, property: string, value: string): void;
+    removeChange(selector: string, property: string): void;
+    removeAllChanges(selector: string): void;
+    clearAll(): void;
+    getChanges(): readonly AppliedRule[];
+    /** Last preview value applied for this selector + property (e.g. `100%` when Fill), or undefined. */
+    getPreviewValue(selector: string, property: string): string | undefined;
+    destroy(): void;
+    private flush;
+}
+/**
+ * Generate a unique CSS selector for an element using @medv/finder.
+ * Falls back to a manual path if finder throws (e.g., SVG elements).
+ */
+declare function getUniqueSelector(el: Element): string;
+/**
+ * `parent > :nth-child(n)` so preview rules (e.g. `order`) target the exact direct child.
+ * Finder-only selectors often collide for sibling elements; this stays stable for flex/grid children.
+ */
+declare function getDirectChildSelector(parent: Element, child: Element): string;
+/**
+ * Selector used for {@link PreviewEngine} rules. Verifies each candidate with
+ * `document.querySelector(sel) === el` so previews (e.g. background) hit the
+ * intended node; @medv/finder can occasionally produce a selector that matches
+ * a different element. Last resort: a temporary `data-flux-preview-target` id
+ * on the element — call {@link removePreviewTargetAttribute} when deselecting.
+ */
+declare function getReliableSelectorForPreview(el: Element): {
+    selector: string;
+    usedAttrFallback: boolean;
+};
+declare function removePreviewTargetAttribute(el: Element | null | undefined): void;
+
+interface StyleSnapshot {
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string;
+    lineHeight: string;
+    letterSpacing: string;
+    color: string;
+    textAlign: string;
+    width: string;
+    height: string;
+    padding: string;
+    margin: string;
+    paddingTop: string;
+    paddingRight: string;
+    paddingBottom: string;
+    paddingLeft: string;
+    marginTop: string;
+    marginRight: string;
+    marginBottom: string;
+    marginLeft: string;
+    /** CSS `position` (static, relative, absolute, fixed, sticky). */
+    position: string;
+    /** Inset offsets for positioned layout (`top` / `right` / `bottom` / `left`). */
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+    /** CSS `align-self` — item alignment in flex/grid. */
+    alignSelf: string;
+    /** CSS `justify-self` — grid item alignment on row axis. */
+    justifySelf: string;
+    overflow: string;
+    display: string;
+    flexDirection: string;
+    justifyContent: string;
+    alignItems: string;
+    gap: string;
+    rowGap: string;
+    columnGap: string;
+    gridTemplateColumns: string;
+    gridTemplateRows: string;
+    backgroundColor: string;
+    /** Computed `background-image` (gradients count as fill for `hasFill`-style checks). */
+    backgroundImage: string;
+    borderTopWidth: string;
+    borderRightWidth: string;
+    borderBottomWidth: string;
+    borderLeftWidth: string;
+    borderTopLeftRadius: string;
+    borderTopRightRadius: string;
+    borderBottomRightRadius: string;
+    borderBottomLeftRadius: string;
+    borderTopColor: string;
+    borderRightColor: string;
+    borderBottomColor: string;
+    borderLeftColor: string;
+    borderTopStyle: string;
+    borderRightStyle: string;
+    borderBottomStyle: string;
+    borderLeftStyle: string;
+    borderColor: string;
+    borderRadius: string;
+    borderStyle: string;
+    boxShadow: string;
+    opacity: string;
+}
+type DesignEditorElement = Element & {
+    style: CSSStyleDeclaration;
+};
+declare function isStyleableElement(target: EventTarget | null): target is DesignEditorElement;
+declare function getComputedSnapshot(el: Element): StyleSnapshot;
+declare function getElementPath(el: Element): string;
+declare function getElementSelector(el: Element): string;
+
+/**
+ * Border-box dimensions in viewport CSS pixels, rounded for the overlay label.
+ */
+declare function formatSelectionDimensions(width: number, height: number): string;
+
+/**
+ * React fiber traversal for extracting component hierarchy and source file locations.
+ * Works with React 18+ dev builds that attach `__reactFiber$` to DOM nodes.
+ */
+interface ReactComponentInfo {
+    components: string[];
+    sourceFile: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    } | null;
+}
+declare function getExactSourceLocation(el: Element): string | null;
+declare function getReactComponentStack(el: Element): string | null;
+declare function getReactComponentInfo(el: Element): ReactComponentInfo;
+
+/**
+ * Lazy token scanner — walks document.styleSheets to discover CSS custom properties
+ * and utility class tokens. Scans on-demand per category, cached until stylesheet count changes.
+ */
+type TokenCategory = "colors" | "spacing" | "typography" | "borders" | "effects" | "layout";
+type CssFramework = "tailwind" | "css-modules" | "custom" | "unknown";
+interface DesignToken {
+    className: string;
+    property: string;
+    value: string;
+    category: TokenCategory;
+}
+interface CssVariable {
+    name: string;
+    value: string;
+    category: TokenCategory;
+}
+interface TokenScanResult {
+    tokens: DesignToken[];
+    variables: CssVariable[];
+    framework: CssFramework;
+}
+declare function scanTokens(): TokenScanResult;
+/** One-line summary for AI prompts (design-token preamble). */
+declare function summarizeTokenSystem(): string | null;
+declare function detectFramework(): CssFramework;
+declare function getTokensForProperty(cssProperty: string): DesignToken[];
+declare function getVariablesForProperty(cssProperty: string): CssVariable[];
+/**
+ * Variables that appear in real CSS rules for this property first, then category fallback.
+ */
+declare function getVariablesForPropertySmart(cssPropertyKebab: string): CssVariable[];
+
+/**
+ * Maps CSS property names (kebab-case) to custom property names that appear
+ * in stylesheet values via var(--name), so pickers can prefer vars actually
+ * used for that property in the host app.
+ */
+declare function invalidateVariableUsageCache(): void;
+/** Custom property names (--foo) that appear in rules for this CSS property. */
+declare function getVariablesUsedForCssProperty(kebabProperty: string): string[];
+
+/** Collect `font-family` values from parsed stylesheets (best-effort; skips cross-origin). */
+declare function scanStylesheetFontFamilies(): string[];
+
+export { type CssFramework, type CssVariable, DesignEditor, type DesignEditorElement, type DesignEditorProps, type DesignToken, type FluxStructuralReorder, PreviewEngine, type ReactComponentInfo, type StyleSnapshot, type TokenCategory, type TokenScanResult, detectFramework, formatSelectionDimensions, getComputedSnapshot, getDirectChildSelector, getElementPath, getElementSelector, getExactSourceLocation, getReactComponentInfo, getReactComponentStack, getReliableSelectorForPreview, getTokensForProperty, getUniqueSelector, getVariablesForProperty, getVariablesForPropertySmart, getVariablesUsedForCssProperty, invalidateVariableUsageCache, isStyleableElement, removePreviewTargetAttribute, scanStylesheetFontFamilies, scanTokens, summarizeTokenSystem };