bluedither 1.0.0

package/theme/generators/react.md

@@ -0,0 +1,88 @@
+# React Generation
+
+When the target project uses **React** (detected via `react` in package.json dependencies), follow these patterns.
+
+## Detection
+
+React is detected when `package.json` contains `react` in `dependencies` or `devDependencies`. Also check for:
+- `react-dom` (standard React)
+- `next` (Next.js — use `"use client"` directive)
+- TypeScript: present if `typescript` is in devDependencies or `tsconfig.json` exists
+
+## Component Structure
+
+Generate separate component files matching `structure.json` nodes:
+
+### `BlueDitherTheme.jsx` (or `.tsx`)
+Root component wrapping the full layout. Imports and composes child components.
+
+```jsx
+import { BlueDitherHeader } from './BlueDitherHeader';
+import { BlueDitherHero } from './BlueDitherHero';
+import './bluedither.css';
+
+export function BlueDitherTheme() {
+  return (
+    <div className="bd-root">
+      <BlueDitherHero />
+      <BlueDitherHeader />
+    </div>
+  );
+}
+```
+
+### `BlueDitherHeader.jsx`
+Navbar component with logo, nav items, and CTA.
+
+- Nav items come from `content.navItems` token array
+- Use `<nav>` with `<a>` elements for nav items
+- CTA is an `<a>` or `<button>` element
+
+### `BlueDitherHero.jsx`
+Hero section with shader and text content.
+
+- **Shader initialization**: Use `useEffect` + `useRef` for the shader parent div:
+```jsx
+import { useEffect, useRef } from 'react';
+
+const shaderRef = useRef(null);
+
+useEffect(() => {
+  // Dynamic import to avoid SSR issues
+  import('./paper-shaders-bundle.js').then(({ ShaderMount, ditheringFragmentShader, getShaderColorFromString }) => {
+    const mount = new ShaderMount(shaderRef.current, ditheringFragmentShader, uniforms, opts, speed, 0, 2);
+    return () => mount.dispose();
+  });
+}, []);
+```
+
+### `bluedither.css`
+All CSS custom properties and `.bd-*` class rules, identical to the vanilla `<style>` block but as an external file.
+
+## TypeScript
+
+If TypeScript is detected, use `.tsx` extensions and add minimal type annotations:
+- Props interfaces where components accept props
+- `useRef<HTMLDivElement>(null)` for refs
+
+## Next.js
+
+If Next.js is detected:
+- Add `"use client"` at the top of components that use `useEffect` or `useRef`
+- The CSS file can be imported directly in the component
+
+## File Output
+
+| File | Contents |
+|------|----------|
+| `BlueDitherTheme.jsx/tsx` | Root layout component |
+| `BlueDitherHeader.jsx/tsx` | Navbar component |
+| `BlueDitherHero.jsx/tsx` | Hero + shader component |
+| `bluedither.css` | CSS custom properties + rules |
+| `paper-shaders-bundle.js` | Shader library (copied) |
+
+## Content Handling
+
+- Inject content tokens directly as JSX text
+- Headline newlines: use `{headline.split('\\n').map((line, i) => <Fragment key={i}>{i > 0 && <br />}{line}</Fragment>)}`
+- Nav items: `{navItems.map(item => <a key={item} className="bd-nav-item" href="#">{item}</a>)}`

package/theme/generators/svelte.md

@@ -0,0 +1,103 @@
+# Svelte Generation
+
+When the target project uses **Svelte** (detected via `svelte` in package.json dependencies), follow these patterns.
+
+## Detection
+
+Svelte is detected when `package.json` contains `svelte` in `dependencies` or `devDependencies`. Also check for:
+- `@sveltejs/kit` (SvelteKit)
+- TypeScript: present if `typescript` is in devDependencies or `svelte.config.js` references TypeScript
+
+## Component Structure
+
+Generate Svelte components (`.svelte` files):
+
+### `BlueDitherTheme.svelte`
+Root component:
+```svelte
+<script>
+  import BlueDitherHeader from './BlueDitherHeader.svelte';
+  import BlueDitherHero from './BlueDitherHero.svelte';
+</script>
+
+<div class="bd-root">
+  <BlueDitherHero />
+  <BlueDitherHeader />
+</div>
+
+<style src="./bluedither.css"></style>
+```
+
+### `BlueDitherHeader.svelte`
+Navbar with content tokens inlined:
+```svelte
+<script>
+  const navItems = ['HOME', 'FEATURES', 'FAQ', 'CONTACT'];
+</script>
+
+<header class="bd-header">
+  <div class="bd-header-inner">
+    <div class="bd-logo">COMPANYLOGO</div>
+    <nav class="bd-nav">
+      {#each navItems as item}
+        <a class="bd-nav-item" href="#">{item}</a>
+      {/each}
+    </nav>
+    <a class="bd-cta" href="#">
+      <span class="bd-cta-text">SIGN UP</span>
+    </a>
+  </div>
+</header>
+```
+
+### `BlueDitherHero.svelte`
+Hero section with shader initialization using `onMount`:
+```svelte
+<script>
+  import { onMount, onDestroy } from 'svelte';
+
+  let shaderParent;
+  let shaderMount = null;
+
+  onMount(async () => {
+    const { ShaderMount, ditheringFragmentShader, getShaderColorFromString } = await import('./paper-shaders-bundle.js');
+    shaderMount = new ShaderMount(shaderParent, ditheringFragmentShader, uniforms, opts, speed, 0, 2);
+  });
+
+  onDestroy(() => {
+    shaderMount?.dispose();
+  });
+</script>
+
+<div class="bd-hero">
+  <div class="bd-hero-inner">
+    <div bind:this={shaderParent} class="bd-shader-layer"></div>
+    <div class="bd-hero-content">
+      <div class="bd-headline">AN ABSOLUTELY<br>FANTASTIC HEADLINE.</div>
+      <div class="bd-subheadline">Sub-headline text here.</div>
+    </div>
+  </div>
+</div>
+```
+
+## Svelte 5 Runes
+
+If Svelte 5 is detected (check `svelte` version in package.json):
+- Use `$state()` instead of `let` for reactive variables
+- Use `$effect()` instead of `onMount` for side effects with cleanup
+
+## SvelteKit
+
+If SvelteKit is detected:
+- Place components in `src/lib/` directory
+- Import shader bundle using `$lib/` alias
+
+## File Output
+
+| File | Contents |
+|------|----------|
+| `BlueDitherTheme.svelte` | Root layout component |
+| `BlueDitherHeader.svelte` | Navbar component |
+| `BlueDitherHero.svelte` | Hero + shader component |
+| `bluedither.css` | CSS custom properties + rules |
+| `paper-shaders-bundle.js` | Shader library (copied) |

package/theme/generators/vanilla.md

@@ -0,0 +1,54 @@
+# Vanilla HTML Generation
+
+When the target project is **plain HTML/CSS/JS** (no framework detected), follow these patterns.
+
+## Output Structure
+
+Generate a single `index.html` file containing:
+1. Inline `<style>` with CSS custom properties from tokens + all `.bd-*` class rules
+2. Semantic HTML matching `structure.json` exactly
+3. `<script type="module">` at the end of `<body>` that:
+   - Imports `bluedither-shader.js` (or the bundled version)
+   - Initializes `ShaderMount` on `#bd-shader-parent`
+
+## CSS Custom Properties
+
+Compute `clamp()` values from all `referencePx` and spacing tokens using:
+```
+clamp(max*0.55 rem, px/designWidth*100 vw, px/16 rem)
+```
+
+Emit all properties under `:root` using the `--bd-*` namespace. See `template/index.html` for the exact variable names.
+
+## Google Fonts
+
+Include `<link>` tags for `typography.primaryFont` and `typography.secondaryFont` via Google Fonts CDN:
+```html
+<link href="https://fonts.googleapis.com/css2?family=FONT_NAME:wght@400;700&display=swap" rel="stylesheet">
+```
+URL-encode the font family name.
+
+## Shader Module
+
+Copy `theme/shaders/bluedither-shader.js` and `theme/shaders/paper-shaders-bundle.js` to the target project.
+
+Import and initialize inline:
+```js
+import { ShaderMount, ditheringFragmentShader, getShaderColorFromString } from './paper-shaders-bundle.js';
+```
+
+Map shader tokens to uniforms as shown in `template/index.html`'s existing `<script type="module">` block.
+
+## File Output
+
+| File | Contents |
+|------|----------|
+| `index.html` | Complete rendered page |
+| `bluedither-shader.js` | Shader module (copied) |
+| `paper-shaders-bundle.js` | Shader library bundle (copied) |
+
+## Content Handling
+
+- Replace `{{content.*}}` placeholders with token values
+- `{{content.headline}}` newlines become `<br>` tags
+- `{{#each content.navItems}}` expands to repeated `<a>` elements

package/theme/generators/vue.md

@@ -0,0 +1,104 @@
+# Vue Generation
+
+When the target project uses **Vue** (detected via `vue` in package.json dependencies), follow these patterns.
+
+## Detection
+
+Vue is detected when `package.json` contains `vue` in `dependencies` or `devDependencies`. Also check for:
+- `nuxt` (Nuxt.js)
+- TypeScript: present if `typescript` is in devDependencies or `tsconfig.json` exists
+
+## Component Structure
+
+Generate Vue Single File Components (SFCs) using `<script setup>` syntax (Vue 3):
+
+### `BlueDitherTheme.vue`
+Root component:
+```vue
+<script setup>
+import BlueDitherHeader from './BlueDitherHeader.vue';
+import BlueDitherHero from './BlueDitherHero.vue';
+</script>
+
+<template>
+  <div class="bd-root">
+    <BlueDitherHero />
+    <BlueDitherHeader />
+  </div>
+</template>
+
+<style src="./bluedither.css"></style>
+```
+
+### `BlueDitherHeader.vue`
+Navbar with logo, nav items, CTA:
+```vue
+<script setup>
+const navItems = ['HOME', 'FEATURES', 'FAQ', 'CONTACT'];
+const ctaText = 'SIGN UP';
+const companyName = 'COMPANYLOGO';
+</script>
+
+<template>
+  <header class="bd-header">
+    <div class="bd-header-inner">
+      <div class="bd-logo">{{ companyName }}</div>
+      <nav class="bd-nav">
+        <a v-for="item in navItems" :key="item" class="bd-nav-item" href="#">{{ item }}</a>
+      </nav>
+      <a class="bd-cta" href="#">
+        <span class="bd-cta-text">{{ ctaText }}</span>
+      </a>
+    </div>
+  </header>
+</template>
+```
+
+### `BlueDitherHero.vue`
+Hero section with shader initialization using `onMounted`:
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+
+const shaderParent = ref(null);
+let shaderMount = null;
+
+onMounted(async () => {
+  const { ShaderMount, ditheringFragmentShader, getShaderColorFromString } = await import('./paper-shaders-bundle.js');
+  shaderMount = new ShaderMount(shaderParent.value, ditheringFragmentShader, uniforms, opts, speed, 0, 2);
+});
+
+onUnmounted(() => {
+  shaderMount?.dispose();
+});
+</script>
+
+<template>
+  <div class="bd-hero">
+    <div class="bd-hero-inner">
+      <div ref="shaderParent" class="bd-shader-layer"></div>
+      <div class="bd-hero-content">
+        <div class="bd-headline">...</div>
+        <div class="bd-subheadline">...</div>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## TypeScript
+
+If TypeScript is detected, add `lang="ts"` to `<script setup lang="ts">`. Type the template ref:
+```ts
+const shaderParent = ref<HTMLDivElement | null>(null);
+```
+
+## File Output
+
+| File | Contents |
+|------|----------|
+| `BlueDitherTheme.vue` | Root layout SFC |
+| `BlueDitherHeader.vue` | Navbar SFC |
+| `BlueDitherHero.vue` | Hero + shader SFC |
+| `bluedither.css` | CSS custom properties + rules |
+| `paper-shaders-bundle.js` | Shader library (copied) |

package/theme/rules.md

@@ -0,0 +1,71 @@
+# BlueDither Design Language Rules
+
+These rules govern how tokens should be applied when an AI agent generates or extends BlueDither-themed components. They encode the design intent behind the token values.
+
+## Color Relationships
+
+- **Background** (`colors.background`) is always the darkest value — near-black with a color tint (e.g., deep navy `#040037`).
+- **Primary** (`colors.primary`) is a saturated accent used for the navbar background and shader foreground. It should be a bold, high-chroma color.
+- **Text** (`colors.text`) is always light (white or near-white) for contrast against the dark background.
+- **CTA** uses inverted contrast: light background (`colors.ctaBackground`) with dark text (`colors.ctaText`). The CTA must visually pop against both the navbar and the hero.
+- **Shader colors**: `shaderFront` typically matches `colors.primary`. `shaderBack` is usually transparent (`#00000000`) so the page background shows through the dither pattern.
+- When adjusting colors, maintain a minimum contrast ratio of 4.5:1 for body text and 3:1 for large text (headline).
+
+## Type Scale
+
+- **Two font families only**: a display/primary font (bold, impactful — e.g., Bebas Neue) and a secondary/mono font (readable, technical — e.g., Space Mono).
+- **Primary font** is used for: logo, nav items, headline, CTA text. Always set to `primaryFontWeight` (typically 700).
+- **Secondary font** is used for: sub-headline only. Always set to `secondaryFontWeight` (typically 400).
+- **Size hierarchy** (from largest to smallest): headline → logo ≈ nav ≈ CTA → sub-headline. The headline should be dramatically larger (5-7x) than the sub-headline.
+- All typography `referencePx` values are relative to `layout.designWidth`. At render time they become `clamp()` values for fluid responsiveness.
+- The formula: `clamp(max*0.55 rem, px/designWidth*100 vw, px/16 rem)` — scales down to 55% on small screens.
+
+## Spacing System
+
+- All spacing values are in reference px at `designWidth`, converted to `clamp()` the same way as typography.
+- **Header padding** is tight — just enough to frame the logo/nav/CTA row.
+- **Hero padding** is generous at the bottom and sides, minimal at the top — content anchors to the bottom-left.
+- **Nav gap** should be wide enough for clear separation but not so wide the items lose visual grouping.
+- **CTA padding** is compact (button should feel tight/punchy, not bloated).
+- **Border radius** is intentionally small (4px default). The design language is angular, not rounded.
+
+## Font Usage
+
+- All text in the navbar uses the primary font.
+- Only the sub-headline uses the secondary font.
+- Text transform (`uppercase`) is applied via CSS, not by modifying content strings. The `textTransform` token on sub-headline controls this.
+- When generating content, write it in the natural case for the slot — CSS handles visual casing.
+
+## Opacity Conventions
+
+- `opacity.navLinks` dims the navigation row slightly (default 0.87) to create depth hierarchy. The logo and CTA remain at full opacity.
+- Opacity should stay above 0.7 for accessibility. Values below 0.5 make text unreadable.
+
+## Shader Integration
+
+- The shader layer is always **full-bleed** behind hero content, positioned absolute.
+- Shader `rotation` rotates the entire shader layer via CSS `rotate()`.
+- The shader is a WebGL `<canvas>` managed by `ShaderMount` from `@paper-design/shaders`.
+- Available shapes: simplex, warp, dots, wave, ripple, swirl, sphere. Default is `warp`.
+- Available dither types: random, 2x2, 4x4, 8x8. Default is `2x2`.
+- `speed` controls animation rate (0 = frozen, 0.18 = subtle motion, >1 = energetic).
+- `scale` controls the zoom of the noise pattern. `size` controls dither pixel size.
+
+## Layout Constraints
+
+- The layout is **exactly two visual sections**: a header (navbar) and a hero. Nothing else.
+- The header sits on top with `z-index: 10`, the hero is positioned absolute behind it.
+- Hero content aligns to the **bottom-left** (`justify-content: end; align-items: start`).
+- The root container is `min-height: 100vh` with `overflow: clip`.
+- The design is **not scrollable** — it's a single-viewport statement piece.
+
+## Extending the Theme
+
+When the AI generates new components outside the locked template:
+1. Use only CSS custom properties from the `--bd-*` namespace.
+2. Follow the same two-font-family rule — never introduce a third font.
+3. Maintain the dark-background + light-text paradigm.
+4. Use `colors.primary` as the accent for interactive elements.
+5. Use `colors.ctaBackground`/`colors.ctaText` for any additional buttons.
+6. New spacing should derive from existing tokens (multiples or fractions of `heroPaddingX`).
+7. Keep the angular, minimal aesthetic — no rounded corners > 8px, no shadows, no gradients (the shader IS the visual interest).

package/theme/shaders/bluedither-shader.js

@@ -0,0 +1,92 @@
+/**
+ * BlueDither Shader Module
+ *
+ * Uses the actual @paper-design/shaders library (ShaderMount + ditheringFragmentShader)
+ * for pixel-accurate rendering matching the Paper design tool.
+ */
+
+import {
+  ShaderMount,
+  ditheringFragmentShader,
+  DitheringShapes,
+  DitheringTypes,
+  getShaderColorFromString
+} from './paper-shaders-bundle.js';
+
+/**
+ * Mount the dithering shader into a parent element.
+ * ShaderMount creates its own canvas inside the parent.
+ *
+ * @param {HTMLElement} parentEl - Container element (shader fills it)
+ * @param {object} params - Token-driven params
+ * @returns {{ updateParams, destroy }}
+ */
+export function createDitheringRenderer(parentEl, params) {
+  const shapeValue = DitheringShapes[params.shape] ?? DitheringShapes.warp;
+  const typeValue = DitheringTypes[params.type] ?? DitheringTypes['2x2'];
+
+  const uniforms = {
+    u_colorFront: getShaderColorFromString(params.colorFront),
+    u_colorBack: getShaderColorFromString(params.colorBack),
+    u_shape: shapeValue,
+    u_type: typeValue,
+    u_pxSize: params.size,
+    u_scale: params.scale,
+    u_rotation: parseFloat(params.rotation) || 180,
+    u_originX: 0.5,
+    u_originY: 0.5,
+    u_worldWidth: 0,
+    u_worldHeight: 0,
+    u_fit: 0,
+    u_offsetX: 0,
+    u_offsetY: 0,
+  };
+
+  const mount = new ShaderMount(
+    parentEl,
+    ditheringFragmentShader,
+    uniforms,
+    { alpha: true, premultipliedAlpha: false },
+    params.speed,  // speed
+    0,             // frame
+    2,             // minPixelRatio
+  );
+
+  return {
+    updateParams(newParams) {
+      const updatedUniforms = {};
+
+      if (newParams.colorFront !== undefined) {
+        updatedUniforms.u_colorFront = getShaderColorFromString(newParams.colorFront);
+      }
+      if (newParams.colorBack !== undefined) {
+        updatedUniforms.u_colorBack = getShaderColorFromString(newParams.colorBack);
+      }
+      if (newParams.shape !== undefined) {
+        updatedUniforms.u_shape = DitheringShapes[newParams.shape] ?? shapeValue;
+      }
+      if (newParams.type !== undefined) {
+        updatedUniforms.u_type = DitheringTypes[newParams.type] ?? typeValue;
+      }
+      if (newParams.size !== undefined) {
+        updatedUniforms.u_pxSize = newParams.size;
+      }
+      if (newParams.scale !== undefined) {
+        updatedUniforms.u_scale = newParams.scale;
+      }
+      if (newParams.rotation !== undefined) {
+        updatedUniforms.u_rotation = parseFloat(newParams.rotation) || 180;
+      }
+      if (newParams.speed !== undefined) {
+        mount.setSpeed(newParams.speed);
+      }
+
+      if (Object.keys(updatedUniforms).length > 0) {
+        mount.setUniforms(updatedUniforms);
+      }
+    },
+    destroy() {
+      mount.dispose();
+    }
+  };
+}