gradient-lab 1.0.0

package/AGENTS.md

@@ -0,0 +1,135 @@
+# AGENTS.md — Guide for AI agents working on Gradient Lab
+
+## Quick orientation
+
+This is a zero-build, zero-dependency web app. Everything is native ES modules served by a small Node.js static file server. No bundler, no transpiler, no npm packages at runtime.
+
+## Module layout
+
+| File | Purpose |
+|------|---------|
+| `reactive-framework.js` | Generic reactive primitives — `Scope`, `Signal`, `Concern`, `ReactiveHTMLElement`. **No app-specific code here.** |
+| `utils.js` | Pure functions — color math, CSS string generation, data helpers. No DOM, no side effects. |
+| `components/gradient-element.js` | App-specific base class that adds `.app`, `.state`, `.commit()`, `.watchState()` on top of `ReactiveHTMLElement`. |
+| `components/gradient-lab-app.js` | Root component. Owns the single `Signal<AppState>`. All mutations go through `commit(draft => ...)`. |
+| `components/*.js` | One file per custom element. Each file registers its element at the bottom with `customElements.define(...)`. |
+| `app.js` | Entry point — imports every component file to trigger registration. No other logic here. |
+| `app.css` | All application CSS. No CSS-in-JS. |
+| `index.html` | Static HTML tree of web components + importmap + CDN links for Bootstrap. |
+
+## Importmap (bare specifier aliases)
+
+Defined in `index.html`:
+
+```json
+{
+  "imports": {
+    "reactive-framework": "./reactive-framework.js",
+    "utils": "./utils.js",
+    "gradient-element": "./components/gradient-element.js"
+  }
+}
+```
+
+Use bare specifiers in component imports:
+```js
+import { ReactiveHTMLElement } from "reactive-framework";  // correct
+import { escapeHtml } from "utils";                         // correct
+import { GradientElement } from "gradient-element";         // correct
+```
+
+Do **not** use relative paths for these three — it defeats the importmap's purpose.
+
+## How to add a new web component
+
+1. Create `components/my-element.js`:
+
+```js
+import { GradientElement } from "gradient-element";
+import { escapeHtml } from "utils";  // import only what you need
+
+class MyElement extends GradientElement {
+  mount() {
+    this.innerHTML = `<div>Hello</div>`;
+    this.watchState(state => this.render(state));
+  }
+
+  render(state) {
+    // update DOM from state — keep it declarative
+  }
+}
+
+customElements.define("my-element", MyElement);
+export { MyElement };
+```
+
+2. Add the import to `app.js`:
+```js
+import "./components/my-element.js";
+```
+
+3. Add to `index.html` body where it belongs in the component tree.
+
+4. Add `my-element { display: block; margin-bottom: 1rem; }` to `app.css` if it needs block layout.
+
+## How to add a new utility function
+
+Add it to `utils.js` as a named export. No side effects, no DOM access, no imports from framework files.
+
+## How to modify application state shape
+
+1. Add the new field with its default value in `GradientLabApp` constructor (`components/gradient-lab-app.js`).
+2. If the field needs deep-copying on commit, update the `commit()` method's draft construction.
+3. Update `copyLine` or `copyLibraryItem` in `utils.js` if the new field lives inside a line or library item.
+
+## State mutation rules
+
+- **Never mutate `this.state` directly.** Always use `this.commit(draft => { draft.field = value; })`.
+- `commit()` deep-copies `lines` and `library` before passing the draft, so mutations are safe.
+- `commit()` sets the signal, which triggers all `watchState` subscribers synchronously.
+
+## Reactive framework rules
+
+### Scope / lifecycle
+- `Scope.collect(fn)` registers a cleanup function.
+- `ReactiveHTMLElement` creates a `Concern` (a `Scope` subclass) in the constructor.
+- `mount()` is called once when the element first connects to the DOM.
+- `disconnectedCallback()` disposes the concern — all subscriptions, listeners, timers.
+- Always register listeners via `this.concern.on(...)` or `this.on(...)`, **not** `addEventListener` directly, so they are disposed automatically.
+
+### Signal
+- `signal.value = x` triggers subscribers only if `x !== signal.value` (by `Object.is`).
+- Use `signal.mutate(fn)` when you need to notify subscribers after mutating the same object reference.
+- Use `signal.set(x, { force: true })` to force notification even when value is equal.
+
+### Concern bindings
+- `bindValue(source, input)` — two-way binding for text inputs.
+- `bindChecked(source, checkbox)` — two-way binding for checkboxes.
+- `bindText(source, node)` — one-way text content binding.
+- `bindStyle(source, el, property, fn?)` — one-way style property binding.
+- `render(source, host, fn)` — re-renders host innerHTML/children when signal changes.
+
+## Rendering approach
+
+Components use **full innerHTML re-render** on state change (no virtual DOM diffing). This is intentional and simple. If a component owns interactive elements that must survive re-renders (e.g., a focused input), use targeted DOM updates instead of wholesale innerHTML replacement.
+
+## CSS conventions
+
+- All custom properties are defined under `:root` in `app.css` with `--lux-*` prefix.
+- Use Bootstrap utility classes for layout and spacing.
+- App-specific structural classes live in `app.css`. Do not add `<style>` blocks to component JS files.
+- The `--lux-gold` (`#ffc774`) color is used for selection, active states, and primary actions.
+- The `--lux-cyan` (`#69d8ff`) color is used for informational labels.
+
+## Server
+
+`server.js` serves all files from the project root. It handles MIME types and blocks path traversal. No changes needed unless you add a new file extension.
+
+## Do not
+
+- Add a build step, bundler, or transpiler.
+- Add npm runtime dependencies.
+- Use Shadow DOM (all components use light DOM for Bootstrap compatibility).
+- Put application logic in `reactive-framework.js` — it must stay generic.
+- Put DOM code in `utils.js` — it must stay pure.
+- Call `addEventListener` directly in component code — always go through `this.concern.on` or `this.on`.

package/README.md

@@ -0,0 +1,103 @@
+# Gradient Lab
+
+An image-sampled CSS gradient studio. Drop a photo, draw sampling lines across it, refine the color stops, and export Bootstrap-ready CSS gradient classes.
+
+## Running
+
+```bash
+npm start
+```
+
+The dev server opens the app at `http://localhost:48187` (or next available port). Files are served from the project root — no build step required.
+
+## File structure
+
+```
+gradient-lab/
+├── index.html              # App shell — importmap + component tree
+├── app.js                  # Entry point — imports all components
+├── app.css                 # Application stylesheet
+├── reactive-framework.js   # Generic reactive primitives (no dependencies)
+├── utils.js                # Pure utility functions (color math, CSS generation)
+├── server.js               # Zero-dependency static file server
+└── components/
+    ├── gradient-element.js       # GradientElement base class
+    ├── gradient-lab-app.js       # Root component — owns all application state
+    ├── app-shell.js              # Layout wrapper
+    ├── app-hero.js               # Header section
+    ├── gradient-workbench.js     # Two-column layout for sampler + editor
+    ├── lux-card.js               # Styled card with title/icon/subtitle slots
+    ├── sampler-toolbar.js        # File upload, sample count, angle controls
+    ├── image-sampling-stage.js   # Canvas + SVG overlay, drag-to-sample
+    ├── sampled-gradient-list.js  # List of sampled gradient lines
+    ├── gradient-editor.js        # Stop bar, color pickers, CSS preview
+    ├── library-controls.js       # Prefix / domain inputs, copy-all button
+    ├── gradient-library.js       # Grid of saved gradients
+    ├── library-code.js           # Collapsible full CSS output
+    └── toast-zone.js             # Fixed toast notifications
+```
+
+## Module graph
+
+```
+reactive-framework.js   (no imports)
+utils.js                (no imports)
+  └── components/gradient-element.js  ← reactive-framework
+        └── components/*.js           ← gradient-element + utils
+              └── app.js              ← all components
+```
+
+The importmap in `index.html` resolves bare specifiers:
+
+| Specifier          | File                              |
+|--------------------|-----------------------------------|
+| `reactive-framework` | `./reactive-framework.js`       |
+| `utils`            | `./utils.js`                      |
+| `gradient-element` | `./components/gradient-element.js`|
+
+## Reactive framework overview
+
+### `Scope`
+Tracks disposables (functions, objects with `.dispose()`, `Symbol.dispose`). Disposes them in reverse order on `.dispose()`. Supports `timeout`, `interval`, `frame`, and child scopes.
+
+### `Signal<T>`
+A reactive value cell. Notifies subscribers only when the value changes (`Object.is` equality by default). Supports `.subscribe(fn)`, `.map(fn)`, `.once(fn)`, `.mutate(fn)`.
+
+### `Concern extends Scope`
+Combines a `Signal` registry with binding helpers. Key methods:
+- `signal(name, value?)` — get or create a named signal
+- `effect(sources, fn)` — run `fn` whenever any source changes
+- `computed(name, sources, fn)` — derived signal
+- `on(target, event, handler)` — event listener tracked for disposal
+- `bindText / bindHTML / bindValue / bindChecked / bindStyle / bindClass / bindAttribute` — one-way or two-way DOM bindings
+- `render(source, host, fn)` — render signal value into a DOM host
+
+### `ReactiveHTMLElement extends HTMLElement`
+Base class for all web components. Mounts once on first `connectedCallback`, disposes on `disconnectedCallback`. Exposes `signal`, `subscribe`, `effect`, `computed`, `on`, `delegate`, `emit`, `$`, `$$`, `html`, `appendTemplate`.
+
+### `GradientElement extends ReactiveHTMLElement`
+Thin base for app-specific components. Adds `.app`, `.state`, `.commit(mutator)`, and `.watchState(fn)`.
+
+## Application state
+
+All state lives in a single `Signal<AppState>` on `<gradient-lab-app>`. Components read it via `this.state` and write via `this.commit(draft => { ... })`, which deep-copies lines and library before mutating.
+
+```js
+{
+  image: HTMLImageElement | null,
+  imageName: string,
+  sampleCount: number,       // 2–16
+  direction: string,         // e.g. "90deg"
+  domain: string,            // for permalink generation
+  prefix: string,            // CSS class prefix, e.g. "gr-"
+  selectedLineId: string | null,
+  selectedEndpoint: "start" | "end" | null,
+  selectedStopId: string | null,
+  lines: GradientLine[],
+  library: LibraryItem[],
+}
+```
+
+## No build step
+
+Everything runs as native ES modules. No bundler, no transpiler, no npm dependencies at runtime. Bootstrap and Bootstrap Icons are loaded from CDN.

package/app.css

@@ -0,0 +1,342 @@
+:root {
+  --lux-bg-0: #05070b;
+  --lux-bg-1: #08111f;
+  --lux-bg-2: #0d1a2d;
+  --lux-card: rgba(13, 23, 39, .82);
+  --lux-border: rgba(178, 208, 255, .16);
+  --lux-text: #edf4ff;
+  --lux-muted: #93a7c4;
+  --lux-gold: #ffc774;
+  --lux-cyan: #69d8ff;
+  --lux-shadow: 0 24px 80px rgba(0, 0, 0, .48);
+  --bs-body-bg: var(--lux-bg-0);
+  --bs-body-color: var(--lux-text);
+  --bs-border-color: var(--lux-border);
+  --bs-secondary-color: var(--lux-muted);
+  --bs-tertiary-bg: rgba(255, 255, 255, .04);
+}
+
+body {
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 8% 0%, rgba(87, 159, 255, .18), transparent 31rem),
+    radial-gradient(circle at 92% 12%, rgba(255, 133, 78, .13), transparent 30rem),
+    radial-gradient(circle at 50% 100%, rgba(72, 255, 201, .10), transparent 28rem),
+    linear-gradient(135deg, var(--lux-bg-0), var(--lux-bg-1) 42%, #030508);
+  color: var(--lux-text);
+}
+
+gradient-lab-app,
+app-shell,
+app-hero,
+gradient-workbench,
+lux-card,
+sampler-toolbar,
+image-sampling-stage,
+sampled-gradient-list,
+gradient-editor,
+library-controls,
+gradient-library,
+library-code,
+toast-zone {
+  display: block;
+  margin-bottom: 1rem;
+}
+
+.app-shell {
+  max-width: 1440px;
+}
+
+.hero-card {
+  border: 1px solid var(--lux-border);
+  border-radius: 2rem;
+  background:
+    linear-gradient(135deg, rgba(255, 255, 255, .09), rgba(255, 255, 255, .03)),
+    linear-gradient(120deg, rgba(255, 199, 116, .11), rgba(105, 216, 255, .05));
+  box-shadow: var(--lux-shadow);
+  overflow: hidden;
+  position: relative;
+}
+
+.lux-card {
+  border: 1px solid var(--lux-border);
+  border-radius: 1.5rem;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, .07), rgba(255, 255, 255, .025)),
+    var(--lux-card);
+  box-shadow: 0 18px 58px rgba(0, 0, 0, .32);
+  backdrop-filter: blur(18px);
+  overflow: hidden;
+}
+
+.lux-card .card-header {
+  border-color: var(--lux-border);
+  background: rgba(255, 255, 255, .035);
+}
+
+.text-lux-muted { color: var(--lux-muted); }
+.text-lux-gold { color: var(--lux-gold); }
+.text-lux-cyan { color: var(--lux-cyan); }
+
+.soft-pill {
+  border: 1px solid var(--lux-border);
+  background: rgba(255, 255, 255, .06);
+  border-radius: 999px;
+  padding: .35rem .75rem;
+  color: var(--lux-muted);
+  font-size: .85rem;
+}
+
+.stage-frame {
+  position: relative;
+  min-height: 430px;
+  border-radius: 1.35rem;
+  border: 1px solid rgba(255, 255, 255, .14);
+  background:
+    linear-gradient(135deg, rgba(255,255,255,.05), rgba(255,255,255,.015)),
+    repeating-conic-gradient(from 45deg, rgba(255,255,255,.025) 0% 25%, transparent 0% 50%) 50% / 34px 34px,
+    #07101d;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  box-shadow: inset 0 1px 0 rgba(255,255,255,.08), inset 0 -30px 90px rgba(0,0,0,.32);
+  touch-action: none;
+}
+
+.canvas-wrap {
+  position: relative;
+  display: block;
+  max-width: 100%;
+  max-height: 620px;
+  border-radius: 1rem;
+  overflow: hidden;
+  box-shadow: 0 18px 58px rgba(0,0,0,.45);
+}
+
+.image-canvas,
+.overlay-svg {
+  display: block;
+  max-width: 100%;
+  user-select: none;
+  touch-action: none;
+}
+
+.overlay-svg {
+  position: absolute;
+  inset: 0;
+  cursor: crosshair;
+}
+
+.drop-hint {
+  position: absolute;
+  inset: 1rem;
+  display: grid;
+  place-items: center;
+  text-align: center;
+  border: 1px dashed rgba(255,255,255,.22);
+  border-radius: 1.15rem;
+  background: rgba(0,0,0,.18);
+  z-index: 3;
+}
+
+.drop-hint.hidden { display: none; }
+
+.drop-hint .display-icon {
+  width: 4.5rem;
+  height: 4.5rem;
+  display: grid;
+  place-items: center;
+  margin-inline: auto;
+  border-radius: 1.35rem;
+  color: #07101d;
+  background: linear-gradient(135deg, var(--lux-gold), var(--lux-cyan));
+  box-shadow: 0 20px 50px rgba(105, 216, 255, .16);
+  font-size: 2rem;
+}
+
+.form-range::-webkit-slider-thumb { background: var(--lux-gold); }
+.form-range::-moz-range-thumb { background: var(--lux-gold); }
+
+.gradient-display {
+  min-height: 150px;
+  border-radius: 1.25rem;
+  border: 0;
+  box-shadow:
+    inset 0 0 0 1px rgba(0,0,0,.28),
+    inset 0 1px 0 rgba(255,255,255,.10),
+    0 22px 60px rgba(0,0,0,.28);
+  overflow: hidden;
+  position: relative;
+}
+
+.gradient-display::after,
+.gradient-chip .preview::after,
+.library-well::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  pointer-events: none;
+  background: linear-gradient(180deg, rgba(255,255,255,.18), transparent 34%, rgba(0,0,0,.12));
+  opacity: .82;
+}
+
+.gradient-track {
+  position: relative;
+  height: 54px;
+  border-radius: 999px;
+  border: 1px solid rgba(255,255,255,.17);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,.14), inset 0 -16px 32px rgba(0,0,0,.24);
+  cursor: copy;
+}
+
+.editor-stop {
+  position: absolute;
+  top: 50%;
+  width: 19px;
+  height: 34px;
+  border: 2px solid rgba(255,255,255,.86);
+  border-radius: 999px 999px 7px 7px;
+  transform: translate(-50%, -50%);
+  box-shadow: 0 10px 24px rgba(0,0,0,.4);
+  cursor: ew-resize;
+}
+
+.editor-stop.selected {
+  outline: 3px solid var(--lux-gold);
+  outline-offset: 3px;
+}
+
+.stop-row {
+  border: 1px solid rgba(255,255,255,.10);
+  border-radius: 1rem;
+  background: rgba(255,255,255,.035);
+  padding: .65rem;
+}
+
+.stop-row.selected {
+  border-color: rgba(255, 199, 116, .5);
+  box-shadow: 0 0 0 3px rgba(255, 199, 116, .10);
+}
+
+.gradient-stack {
+  display: grid;
+  gap: .75rem;
+}
+
+.gradient-chip {
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,.11);
+  border-radius: 1.1rem;
+  background: rgba(255,255,255,.035);
+  overflow: hidden;
+  transition: box-shadow .16s ease, transform .16s ease, background .16s ease;
+}
+
+.gradient-chip:hover,
+.gradient-chip.selected {
+  box-shadow: inset 0 0 0 1px rgba(255, 199, 116, .52);
+  background: rgba(255, 255, 255, .055);
+}
+
+.gradient-chip.selected { transform: translateY(-1px); }
+
+.gradient-chip .preview {
+  position: relative;
+  min-height: 52px;
+  border-radius: .85rem;
+  overflow: hidden;
+  isolation: isolate;
+  box-shadow:
+    inset 0 0 0 1px rgba(255,255,255,.16),
+    inset 0 1px 0 rgba(255,255,255,.18),
+    inset 0 -18px 32px rgba(0,0,0,.16);
+  background-clip: padding-box;
+}
+
+.library-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 1rem;
+}
+
+.library-item {
+  border: 1px solid rgba(255,255,255,.11);
+  border-radius: 1.2rem;
+  background: rgba(255,255,255,.035);
+  padding: .8rem;
+}
+
+.library-well {
+  position: relative;
+  min-height: 90px;
+  border: 0;
+  border-radius: 1rem;
+  overflow: hidden;
+  box-shadow:
+    inset 0 0 0 1px rgba(0,0,0,.30),
+    inset 0 1px 0 rgba(255,255,255,.08);
+}
+
+textarea.codebox {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  min-height: 154px;
+  color: #d8e8ff;
+  background: rgba(2, 8, 16, .82);
+  border-color: rgba(255,255,255,.12);
+}
+
+.btn-lux {
+  --bs-btn-color: #08101d;
+  --bs-btn-bg: var(--lux-gold);
+  --bs-btn-border-color: var(--lux-gold);
+  --bs-btn-hover-color: #07101d;
+  --bs-btn-hover-bg: #ffd798;
+  --bs-btn-hover-border-color: #ffd798;
+  --bs-btn-active-bg: #dca95f;
+  --bs-btn-active-border-color: #dca95f;
+  box-shadow: 0 12px 28px rgba(255, 199, 116, .16);
+}
+
+.btn-soft {
+  --bs-btn-color: #dceaff;
+  --bs-btn-bg: rgba(255,255,255,.065);
+  --bs-btn-border-color: rgba(255,255,255,.14);
+  --bs-btn-hover-color: #fff;
+  --bs-btn-hover-bg: rgba(255,255,255,.105);
+  --bs-btn-hover-border-color: rgba(255,255,255,.24);
+}
+
+.empty-state {
+  border: 1px dashed rgba(255,255,255,.18);
+  border-radius: 1rem;
+  padding: 1rem;
+  color: var(--lux-muted);
+  background: rgba(255,255,255,.025);
+}
+
+.toast-lite {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  z-index: 1080;
+  border: 1px solid rgba(255,255,255,.16);
+  border-radius: 1rem;
+  background: rgba(7, 13, 24, .92);
+  color: #fff;
+  box-shadow: 0 18px 50px rgba(0,0,0,.35);
+  padding: .8rem 1rem;
+  opacity: 0;
+  transform: translateY(12px);
+  pointer-events: none;
+  transition: opacity .18s ease, transform .18s ease;
+}
+
+.toast-lite.show {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+@media (max-width: 768px) {
+  .stage-frame { min-height: 320px; }
+  .gradient-display { min-height: 110px; }
+}

package/app.js

@@ -0,0 +1,13 @@
+import "./components/gradient-lab-app.js";
+import "./components/app-shell.js";
+import "./components/app-hero.js";
+import "./components/gradient-workbench.js";
+import "./components/lux-card.js";
+import "./components/sampler-toolbar.js";
+import "./components/image-sampling-stage.js";
+import "./components/sampled-gradient-list.js";
+import "./components/gradient-editor.js";
+import "./components/library-controls.js";
+import "./components/gradient-library.js";
+import "./components/library-code.js";
+import "./components/toast-zone.js";

package/components/app-hero.js

@@ -0,0 +1,32 @@
+import { GradientElement } from "gradient-element";
+
+class AppHero extends GradientElement {
+  mount() {
+    this.innerHTML = `
+      <section class="hero-card p-4 p-xl-5 mb-4">
+        <div class="row align-items-end g-4">
+          <div class="col-lg-8">
+            <div class="soft-pill d-inline-flex align-items-center gap-2 mb-3">
+              <i class="bi bi-eyedropper"></i>
+              Image-sampled CSS gradient studio
+            </div>
+            <h1 class="display-5 fw-semibold mb-3">Sample gradients the way nature composes color.</h1>
+            <p class="lead text-lux-muted mb-0">
+              Drop a close-up photo, draw slash-lines through the interesting color movement, then refine the sampled stops into reusable Bootstrap-ready CSS classes.
+            </p>
+          </div>
+          <div class="col-lg-4">
+            <div class="d-flex flex-wrap justify-content-lg-end gap-2">
+              <span class="soft-pill"><i class="bi bi-bezier2 me-1"></i> draggable paths</span>
+              <span class="soft-pill"><i class="bi bi-palette2 me-1"></i> 2–16 stops</span>
+              <span class="soft-pill"><i class="bi bi-code-slash me-1"></i> copy CSS</span>
+            </div>
+          </div>
+        </div>
+      </section>
+    `;
+  }
+}
+
+customElements.define("app-hero", AppHero);
+export { AppHero };

package/components/app-shell.js

@@ -0,0 +1,12 @@
+import { GradientElement } from "gradient-element";
+
+class AppShell extends GradientElement {
+  mount() {
+    const children = [...this.childNodes];
+    this.innerHTML = `<main class="app-shell container py-4 py-xl-5"></main>`;
+    this.querySelector("main").append(...children);
+  }
+}
+
+customElements.define("app-shell", AppShell);
+export { AppShell };