@newtonedev/editor 0.1.12 → 0.2.0

package/src/components/sections/FontsSection.tsx

@@ -1,9 +1,7 @@
-import { Slider } from "@newtonedev/components";
-import { useTokens } from "@newtonedev/components";
+import { Slider, Wrapper, Text } from "@newtonedev/components";
 import type { FontConfig } from "@newtonedev/components";
-import { srgbToHex } from "newtone";
-import type { ConfiguratorState, FontScope, FontSlotConfig } from "@newtonedev/configurator";
-import type { ConfiguratorAction } from "@newtonedev/configurator";
+import type { ConfiguratorState, FontScope, FontSlotConfig } from "../../configurator/types";
+import type { ConfiguratorAction } from "../../configurator/state/actions";
 import type { GoogleFontEntry } from "@newtonedev/fonts";
 import { FontPicker } from "../FontPicker";
 
@@ -45,10 +43,6 @@ const FONT_SCOPES: readonly { scope: FontScope; label: string; slot: "default" |
 ];
 
 export function FontsSection({ state, dispatch, fontCatalog }: FontsSectionProps) {
-  const tokens = useTokens();
-
-  const labelColor = srgbToHex(tokens.textSecondary.srgb);
-
   const handleFontChange = (scope: FontScope, font: FontConfig) => {
     // Preserve existing weight slots when switching font family
     const weights = state.typography?.fonts[scope]?.weights ?? { regular: 400, medium: 500, bold: 700 };
@@ -56,20 +50,13 @@ export function FontsSection({ state, dispatch, fontCatalog }: FontsSectionProps
     dispatch({ type: "SET_FONT", scope, font: slotConfig });
   };
 
-  const sectionLabelStyle = {
-    fontSize: 11,
-    fontWeight: 600 as const,
-    color: labelColor,
-    textTransform: "uppercase" as const,
-    letterSpacing: 0.5,
-    marginBottom: 8,
-  };
-
   return (
-    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
-      <div>
-        <div style={sectionLabelStyle}>Fonts</div>
-        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+    <Wrapper direction="vertical" gap="16">
+      <Wrapper direction="vertical">
+        <Text role="caption" color="tertiary" style={{ textTransform: "uppercase", letterSpacing: 0.5, marginBottom: 8 }}>
+          Fonts
+        </Text>
+        <Wrapper direction="vertical" gap="12">
           {FONT_SCOPES.map(({ scope, label, slot }) => (
             <FontPicker
               key={scope}
@@ -80,10 +67,12 @@ export function FontsSection({ state, dispatch, fontCatalog }: FontsSectionProps
               fontCatalog={fontCatalog}
             />
           ))}
-        </div>
-      </div>
-      <div>
-        <div style={sectionLabelStyle}>Type Scale</div>
+        </Wrapper>
+      </Wrapper>
+      <Wrapper direction="vertical">
+        <Text role="caption" color="tertiary" style={{ textTransform: "uppercase", letterSpacing: 0.5, marginBottom: 8 }}>
+          Type Scale
+        </Text>
         <Slider
           value={Math.round((state.typography?.typeScaleOffset ?? 0.5) * 100)}
           onValueChange={(v) =>
@@ -94,7 +83,7 @@ export function FontsSection({ state, dispatch, fontCatalog }: FontsSectionProps
           label="Scale"
           showValue
         />
-      </div>
-    </div>
+      </Wrapper>
+    </Wrapper>
   );
 }

package/src/components/sections/IconsSection.tsx

@@ -1,6 +1,6 @@
 import { Select } from "@newtonedev/components";
-import type { ConfiguratorState } from "@newtonedev/configurator";
-import type { ConfiguratorAction } from "@newtonedev/configurator";
+import type { ConfiguratorState } from "../../configurator/types";
+import type { ConfiguratorAction } from "../../configurator/state/actions";
 
 const ICON_VARIANT_OPTIONS = [
   { label: "Outlined", value: "outlined" },

package/src/components/sections/OthersSection.tsx

@@ -1,7 +1,6 @@
 import { Slider, Select, useTokens } from "@newtonedev/components";
-import { srgbToHex } from "newtone";
-import type { ConfiguratorState, SpacingPreset } from "@newtonedev/configurator";
-import type { ConfiguratorAction } from "@newtonedev/configurator";
+import type { ConfiguratorState, SpacingPreset } from "../../configurator/types";
+import type { ConfiguratorAction } from "../../configurator/state/actions";
 
 interface OthersSectionProps {
   readonly state: ConfiguratorState;
@@ -29,7 +28,7 @@ export function OthersSection({ state, dispatch }: OthersSectionProps) {
           style={{
             fontSize: 11,
             fontWeight: 600,
-            color: srgbToHex(tokens.textSecondary.srgb),
+            color: tokens.colors.primary.main.fontTertiary,
             textTransform: "uppercase",
             letterSpacing: 0.5,
             marginBottom: 8,
@@ -52,7 +51,7 @@ export function OthersSection({ state, dispatch }: OthersSectionProps) {
           style={{
             fontSize: 11,
             fontWeight: 600,
-            color: srgbToHex(tokens.textSecondary.srgb),
+            color: tokens.colors.primary.main.fontTertiary,
             textTransform: "uppercase",
             letterSpacing: 0.5,
             marginBottom: 8,

package/src/components/sections/ScalePlots.tsx

@@ -0,0 +1,221 @@
+import { maxChroma, resolveGradedHue, buildOneSidedGrade, resolveLightest, resolveDarkest } from "@newtonedev/colors";
+import type { Grading } from "@newtonedev/colors";
+import type { ColorResult } from "newtone";
+import type { ConfiguratorState } from "../../configurator/types";
+
+const SVG_W = 200;
+const SVG_H = 140;
+const PAD = { top: 8, right: 8, bottom: 20, left: 28 };
+
+interface ScalePlotsProps {
+  readonly state: ConfiguratorState;
+  readonly scale: readonly ColorResult[];
+  readonly activePaletteIndex: number;
+  readonly useP3: boolean;
+}
+
+/** CSS oklch color for a given OKLCH hue — used for plot line/segment colors. */
+function hueColor(h: number): string {
+  return `oklch(65% 0.2 ${h.toFixed(1)}deg)`;
+}
+
+export function ScalePlots({ state, scale, activePaletteIndex, useP3 }: ScalePlotsProps) {
+  if (!scale || scale.length < 2) return null;
+
+  const palette = state.palettes[activePaletteIndex];
+  const pw = SVG_W - PAD.left - PAD.right;
+  const ph = SVG_H - PAD.top - PAD.bottom;
+
+  const lightestL = resolveLightest(state.dynamicRange.lightest);
+  const darkestL = resolveDarkest(state.dynamicRange.darkest);
+  const lRange = lightestL - darkestL || 1;
+
+  function toX(L: number): number {
+    return PAD.left + ((lightestL - L) / lRange) * pw;
+  }
+
+  // ── Hue Plot ──
+
+  const baseY = PAD.top + ph - (palette.hue / 360) * ph;
+
+  const hueSegments = scale.slice(1).map((step, i) => {
+    const prev = scale[i];
+    const midH = (prev.oklch.h + step.oklch.h) / 2;
+    return (
+      <line
+        key={i}
+        x1={toX(prev.oklch.L).toFixed(1)}
+        y1={(PAD.top + ph - (prev.oklch.h / 360) * ph).toFixed(1)}
+        x2={toX(step.oklch.L).toFixed(1)}
+        y2={(PAD.top + ph - (step.oklch.h / 360) * ph).toFixed(1)}
+        stroke={hueColor(midH)}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    );
+  });
+
+  const g = state.globalHueGrading;
+  const gradeRefLines: React.ReactNode[] = [];
+  if (g.lightIntensity > 0) {
+    const h = g.lightHue;
+    const y = (PAD.top + ph - (h / 360) * ph).toFixed(1);
+    gradeRefLines.push(
+      <line key="gl" x1={PAD.left} y1={y} x2={PAD.left + pw} y2={y}
+        stroke={hueColor(h)} strokeWidth="0.75" strokeDasharray="3 2" opacity="0.7" />
+    );
+  }
+  if (g.darkIntensity > 0) {
+    const h = g.darkHue;
+    const y = (PAD.top + ph - (h / 360) * ph).toFixed(1);
+    gradeRefLines.push(
+      <line key="gd" x1={PAD.left} y1={y} x2={PAD.left + pw} y2={y}
+        stroke={hueColor(h)} strokeWidth="0.75" strokeDasharray="3 2" opacity="0.7" />
+    );
+  }
+  const lg = palette.localHueGrade;
+  if (lg && lg.intensity > 0) {
+    const h = lg.hue;
+    const y = (PAD.top + ph - (h / 360) * ph).toFixed(1);
+    gradeRefLines.push(
+      <line key="ll" x1={PAD.left} y1={y} x2={PAD.left + pw} y2={y}
+        stroke={hueColor(h)} strokeWidth="0.75" strokeDasharray="2 3" opacity="0.6" />
+    );
+  }
+
+  // ── Chroma Plot ──
+
+  // Build grading objects for boundary hue resolution
+  const globalGrade: Grading | undefined =
+    (g.lightIntensity > 0 || g.darkIntensity > 0)
+      ? {
+          ...(g.lightIntensity > 0 ? { light: { hue: g.lightHue, amount: g.lightIntensity } } : {}),
+          ...(g.darkIntensity > 0 ? { dark: { hue: g.darkHue, amount: g.darkIntensity } } : {}),
+        }
+      : undefined;
+
+  const localGrade = lg && lg.intensity > 0
+    ? buildOneSidedGrade(lg.hue, lg.intensity, lg.side === "light")
+    : undefined;
+
+  // Dense-sample both gamut boundaries (60 points)
+  const BOUNDARY_SAMPLES = 60;
+  let maxC = 0;
+  const srgbBoundary: { x: number; y: number }[] = [];
+  const p3Boundary: { x: number; y: number }[] = [];
+  for (let i = 0; i <= BOUNDARY_SAMPLES; i++) {
+    const t = i / BOUNDARY_SAMPLES;
+    const L = lightestL - t * lRange;
+    const h = resolveGradedHue(palette.hue, t, globalGrade, localGrade);
+    const sC = maxChroma(L, h, "srgb");
+    const pC = maxChroma(L, h, "display-p3");
+    if (pC > maxC) maxC = pC;
+    const x = toX(L);
+    srgbBoundary.push({ x, y: sC });
+    p3Boundary.push({ x, y: pC });
+  }
+  if (maxC < 0.01) maxC = 0.01;
+
+  function toBoundaryPath(pts: { x: number; y: number }[]): string {
+    return pts.map((pt, i) => {
+      const y = (PAD.top + ph - (pt.y / maxC) * ph).toFixed(1);
+      return `${i === 0 ? "M" : "L"}${pt.x.toFixed(1)},${y}`;
+    }).join(" ");
+  }
+
+  const srgbPath = toBoundaryPath(srgbBoundary);
+  const p3Path = toBoundaryPath(p3Boundary);
+
+  const chromaSegments = scale.slice(1).map((step, i) => {
+    const prev = scale[i];
+    const midH = (prev.oklch.h + step.oklch.h) / 2;
+    return (
+      <line
+        key={i}
+        x1={toX(prev.oklch.L).toFixed(1)}
+        y1={(PAD.top + ph - (prev.oklch.C / maxC) * ph).toFixed(1)}
+        x2={toX(step.oklch.L).toFixed(1)}
+        y2={(PAD.top + ph - (step.oklch.C / maxC) * ph).toFixed(1)}
+        stroke={hueColor(midH)}
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    );
+  });
+
+  const labelStyle: React.CSSProperties = {
+    fontSize: 11,
+    fontWeight: 600,
+    color: "currentColor",
+    opacity: 0.5,
+    letterSpacing: 0.3,
+    textTransform: "uppercase" as const,
+    marginBottom: 4,
+  };
+
+  const axisStyle = { stroke: "currentColor", strokeWidth: 0.75, opacity: 0.25 };
+  const textStyle: React.SVGProps<SVGTextElement> = {
+    fontSize: 8,
+    fill: "currentColor",
+    opacity: 0.5,
+  };
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+      {/* Hue plot */}
+      <div>
+        <div style={labelStyle}>Hue</div>
+        <svg
+          viewBox={`0 0 ${SVG_W} ${SVG_H}`}
+          style={{ width: "100%", display: "block" }}
+          preserveAspectRatio="xMidYMid meet"
+        >
+          {/* Axes */}
+          <line x1={PAD.left} y1={PAD.top} x2={PAD.left} y2={PAD.top + ph} {...axisStyle} />
+          <line x1={PAD.left} y1={PAD.top + ph} x2={PAD.left + pw} y2={PAD.top + ph} {...axisStyle} />
+          {/* Base hue reference */}
+          <line
+            x1={PAD.left} y1={baseY.toFixed(1)}
+            x2={PAD.left + pw} y2={baseY.toFixed(1)}
+            stroke={hueColor(palette.hue)} strokeWidth="0.75" opacity="0.5"
+          />
+          {gradeRefLines}
+          {hueSegments}
+          {/* Labels */}
+          <text {...textStyle} x={PAD.left + pw / 2} y={SVG_H - 2} textAnchor="middle">L</text>
+          <text {...textStyle} x={3} y={PAD.top + ph / 2} textAnchor="middle"
+            transform={`rotate(-90, 3, ${PAD.top + ph / 2})`}>H</text>
+          <text {...textStyle} x={PAD.left - 3} y={PAD.top + 3} textAnchor="end">360°</text>
+          <text {...textStyle} x={PAD.left - 3} y={PAD.top + ph + 3} textAnchor="end">0°</text>
+        </svg>
+      </div>
+
+      {/* Chroma plot */}
+      <div>
+        <div style={labelStyle}>Chroma</div>
+        <svg
+          viewBox={`0 0 ${SVG_W} ${SVG_H}`}
+          style={{ width: "100%", display: "block" }}
+          preserveAspectRatio="xMidYMid meet"
+        >
+          {/* Axes */}
+          <line x1={PAD.left} y1={PAD.top} x2={PAD.left} y2={PAD.top + ph} {...axisStyle} />
+          <line x1={PAD.left} y1={PAD.top + ph} x2={PAD.left + pw} y2={PAD.top + ph} {...axisStyle} />
+          {/* P3 gamut boundary */}
+          <path d={p3Path} fill="none" stroke="currentColor" strokeWidth="0.75"
+            opacity={useP3 ? 0.2 : 0.1} strokeDasharray={useP3 ? undefined : "3 2"} />
+          {/* sRGB gamut boundary */}
+          <path d={srgbPath} fill="none" stroke="currentColor" strokeWidth="0.75"
+            opacity={useP3 ? 0.1 : 0.2} strokeDasharray={useP3 ? "3 2" : undefined} />
+          {chromaSegments}
+          {/* Labels */}
+          <text {...textStyle} x={PAD.left + pw / 2} y={SVG_H - 2} textAnchor="middle">L</text>
+          <text {...textStyle} x={3} y={PAD.top + ph / 2} textAnchor="middle"
+            transform={`rotate(-90, 3, ${PAD.top + ph / 2})`}>C</text>
+          <text {...textStyle} x={PAD.left - 3} y={PAD.top + 3} textAnchor="end">{maxC.toFixed(2)}</text>
+          <text {...textStyle} x={PAD.left - 3} y={PAD.top + ph + 3} textAnchor="end">0</text>
+        </svg>
+      </div>
+    </div>
+  );
+}

package/src/components/sections/index.ts

@@ -1,4 +1,5 @@
 export { ColorsSection } from "./ColorsSection";
+export { ScalePlots } from "./ScalePlots";
 export { DynamicRangeSection } from "./DynamicRangeSection";
 export { IconsSection } from "./IconsSection";
 export { FontsSection } from "./FontsSection";

package/src/configurator/bridge/toCSS.ts

@@ -0,0 +1,44 @@
+import type { ConfiguratorState } from '../types';
+import type { ColorMode } from '@newtonedev/components';
+import { computeTokens } from '@newtonedev/components';
+import { toThemeConfig } from './toThemeConfig';
+
+/**
+ * Generate CSS custom properties for both light and dark modes.
+ * Computes tokens for the primary theme at grounded elevation in sRGB gamut.
+ */
+export function toCSS(state: ConfiguratorState): string {
+  const config = toThemeConfig(state);
+  const modes: readonly ColorMode[] = ['light', 'dark'];
+
+  let css = '';
+  for (const mode of modes) {
+    const tokens = computeTokens(
+      config.colorSystem,
+      mode,
+      'srgb',
+      'grounded',
+      config.spacing,
+      config.radius,
+      config.typography,
+      config.icons,
+    );
+
+    const c = tokens.colors;
+    const selector = mode === 'light' ? ':root' : '[data-theme="dark"]';
+    css += `${selector} {\n`;
+    css += `  --newtone-background: ${c.primary.main.background};\n`;
+    css += `  --newtone-text-primary: ${c.primary.main.fontPrimary};\n`;
+    css += `  --newtone-text-secondary: ${c.primary.main.fontTertiary};\n`;
+    css += `  --newtone-border: ${c.primary.main.fontDisabled};\n`;
+    css += `  --newtone-accent: ${c.secondary.emphasis.fontPrimary};\n`;
+    css += `  --newtone-accent-hover: ${c.secondary.emphasis.fontSecondary};\n`;
+    css += `  --newtone-accent-active: ${c.secondary.emphasis.fontTertiary};\n`;
+    css += `  --newtone-success: ${c.success.emphasis.fontPrimary};\n`;
+    css += `  --newtone-warning: ${c.warning.emphasis.fontPrimary};\n`;
+    css += `  --newtone-error: ${c.error.emphasis.fontPrimary};\n`;
+    css += `}\n\n`;
+  }
+
+  return css;
+}

package/src/configurator/bridge/toJSON.ts

@@ -0,0 +1,24 @@
+import type { ConfiguratorState } from '../types';
+import type { NewtoneThemeConfig } from '@newtonedev/components';
+import { toThemeConfig } from './toThemeConfig';
+
+/** Serializable configurator export format */
+export interface ConfiguratorExport {
+  readonly version: '1.0';
+  readonly configuratorState: ConfiguratorState;
+  readonly themeConfig: NewtoneThemeConfig;
+}
+
+/**
+ * Export the configurator state as a JSON string.
+ * Includes both the human-readable state (for round-tripping)
+ * and the engine-ready theme config.
+ */
+export function toJSON(state: ConfiguratorState): string {
+  const output: ConfiguratorExport = {
+    version: '1.0',
+    configuratorState: state,
+    themeConfig: toThemeConfig(state),
+  };
+  return JSON.stringify(output, null, 2);
+}

package/src/configurator/bridge/toThemeConfig.ts

@@ -0,0 +1,114 @@
+import type { ConfiguratorState, SpacingPreset } from '../types';
+import type { NewtoneThemeConfig } from '@newtonedev/components';
+import { DEFAULT_FONT_SIZES, DEFAULT_LINE_HEIGHTS, DEFAULT_ROLE_SCALES, DEFAULT_FONT_SLOTS, ROLE_DEFAULT_WEIGHTS, migrateToFontSlot, computeBreakpointRoleScales, applyTypeScaleOffset } from '@newtonedev/fonts';
+import type { DynamicRange } from 'newtone';
+import type { Grading } from '@newtonedev/colors';
+
+const SPACING_PRESET_TO_BASE: Record<SpacingPreset, number> = {
+  xs: 6,
+  sm: 7,
+  md: 8,
+  lg: 9,
+  xl: 10,
+};
+
+function roundnessToMultiplier(intensity: number): number {
+  return intensity * 2.0;
+}
+
+const DEFAULT_ICONS = {
+  variant: 'rounded' as const,
+  weight: 400 as const,
+  autoGrade: true,
+};
+
+function buildGlobalGrading(g: ConfiguratorState['globalHueGrading']): Grading | undefined {
+  if (g.lightIntensity === 0 && g.darkIntensity === 0) return undefined;
+  return {
+    light: { hue: g.lightHue, amount: g.lightIntensity },
+    dark: { hue: g.darkHue, amount: g.darkIntensity },
+  };
+}
+
+/**
+ * Convert configurator state to a NewtoneThemeConfig (engine-ready format).
+ * Hues are already in OKLCH space — passed through directly.
+ */
+export function toThemeConfig(state: ConfiguratorState): NewtoneThemeConfig {
+  const grading = buildGlobalGrading(state.globalHueGrading);
+
+  const palettes = state.palettes.map(p => {
+    const shift = p.localHueGrade && p.localHueGrade.intensity > 0
+      ? {
+          hue: p.localHueGrade.hue,
+          amount: p.localHueGrade.intensity,
+          ...(p.localHueGrade.side === 'light' ? { light: true as const } : {}),
+        }
+      : undefined;
+
+    return {
+      hue: p.hue,
+      chroma: {
+        amount: p.chromaRatio,
+        ...(p.chromaPeak !== 0.5 ? { balance: p.chromaPeak } : {}),
+      },
+      ...(shift ? { shift } : {}),
+      ...(p.keyColorStep !== undefined ? { keyStep: p.keyColorStep } : {}),
+      ...(p.keyColorStepDark !== undefined ? { keyStepDark: p.keyColorStepDark } : {}),
+    };
+  });
+
+  const dynamicRange: DynamicRange = {
+    lightest: state.dynamicRange.lightest,
+    darkest: state.dynamicRange.darkest,
+  };
+
+  const spacingBase = SPACING_PRESET_TO_BASE[state.spacing?.preset ?? 'md'];
+  const radiusMultiplier = roundnessToMultiplier(state.roundness?.intensity ?? 0.5);
+
+  return {
+    colorSystem: { dynamicRange, grading, palettes },
+    spacing: {
+      '00': Math.round(spacingBase * 0),
+      '02': Math.round(spacingBase * 0.25),
+      '04': Math.round(spacingBase * 0.5),
+      '06': Math.round(spacingBase * 0.75),
+      '08': Math.round(spacingBase * 1),
+      '10': Math.round(spacingBase * 1.25),
+      '12': Math.round(spacingBase * 1.5),
+      '16': Math.round(spacingBase * 2),
+      '20': Math.round(spacingBase * 2.5),
+      '24': Math.round(spacingBase * 3),
+      '32': Math.round(spacingBase * 4),
+      '40': Math.round(spacingBase * 5),
+      '48': Math.round(spacingBase * 6),
+    },
+    radius: {
+      none: 0,
+      sm: Math.round(4 * radiusMultiplier),
+      md: Math.round(6 * radiusMultiplier),
+      lg: Math.round(8 * radiusMultiplier),
+      xl: Math.round(12 * radiusMultiplier),
+      pill: 999,
+    },
+    typography: (() => {
+      const roles = state.typography?.typeScaleOffset != null
+        ? applyTypeScaleOffset(DEFAULT_ROLE_SCALES, state.typography.typeScaleOffset)
+        : DEFAULT_ROLE_SCALES;
+      return {
+        fonts: {
+          main: migrateToFontSlot(state.typography?.fonts.main ?? (state.typography?.fonts as any)?.default, DEFAULT_FONT_SLOTS.main),
+          display: migrateToFontSlot(state.typography?.fonts.display, DEFAULT_FONT_SLOTS.display),
+          mono: migrateToFontSlot(state.typography?.fonts.mono, DEFAULT_FONT_SLOTS.mono),
+          currency: migrateToFontSlot(state.typography?.fonts.currency, DEFAULT_FONT_SLOTS.currency),
+        },
+        fontSizes: DEFAULT_FONT_SIZES,
+        lineHeights: DEFAULT_LINE_HEIGHTS,
+        roles,
+        breakpointRoles: computeBreakpointRoleScales(roles),
+        roleWeights: { ...ROLE_DEFAULT_WEIGHTS, ...state.typography?.roleWeights },
+      };
+    })(),
+    icons: state.icons ?? DEFAULT_ICONS,
+  };
+}

package/src/configurator/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * Hue ranges for semantic palettes (OKLCH hues).
+ * Indices 0 (Primary), 1 (Secondary), and 2 (Tertiary) are unconstrained.
+ *
+ * Gaps between ranges prevent adjacent semantics from overlapping:
+ * - ~34–45: gap between Error (reds) and Warning (yellows)
+ * - ~103–130: gap between Warning and Success (greens)
+ */
+export const SEMANTIC_HUE_RANGES: Readonly<Record<number, { readonly min: number; readonly max: number }>> = {
+  3: { min: 129.86, max: 160.14 },   // Success (greens)
+  4: { min: 44.85, max: 102.80 },    // Warning (yellow/orange)
+  5: { min: 20.91, max: 34.48 },     // Error (reds)
+};

package/src/configurator/hex-conversion.ts

@@ -0,0 +1,67 @@
+import {
+  hexToSrgb,
+  srgbToOklch,
+  findMaxChromaInGamut,
+  resolveLightest,
+  resolveDarkest,
+} from 'newtone';
+import type { DynamicRange } from 'newtone';
+
+/** Result of decomposing a hex color into palette parameters */
+export interface HexPaletteParams {
+  /** OKLCH hue [0, 360) */
+  readonly hue: number;
+  /** Chroma as fraction of max in-gamut chroma [0, 1] */
+  readonly chromaRatio: number;
+  /** Step index in the 26-step scale [0, 25] (0 = lightest, 25 = darkest) */
+  readonly stepIndex: number;
+}
+
+// Achromatic threshold — below this chroma, the color has no meaningful hue
+const ACHROMATIC_THRESHOLD = 0.005;
+
+/**
+ * Map an OKLCH lightness value back to an engineNv [0, 1] within the dynamic range.
+ * engineNv: 0=darkest, 1=lightest.
+ */
+function lightnessToNormalizedValue(dynamicRange: DynamicRange, L: number): number {
+  const lightestL = resolveLightest(dynamicRange.lightest);
+  const darkestL = resolveDarkest(dynamicRange.darkest);
+  if (lightestL <= darkestL) return 0.5;
+  return Math.max(0, Math.min(1, (L - darkestL) / (lightestL - darkestL)));
+}
+
+/**
+ * Decompose a hex color string into palette parameters (hue, chromaRatio, normalizedValue).
+ *
+ * Returns null if the hex string is invalid.
+ * Hue is returned in OKLCH space [0, 360).
+ *
+ * @param hex - Hex color string (e.g., "#FF0000", "#f00", "FF0000")
+ * @param dynamicRange - Current dynamic range for normalizedValue mapping
+ */
+export function hexToPaletteParams(
+  hex: string,
+  dynamicRange: DynamicRange,
+): HexPaletteParams | null {
+  const cleaned = hex.startsWith('#') ? hex.slice(1) : hex;
+  if (!/^[0-9a-fA-F]{3}$/.test(cleaned) && !/^[0-9a-fA-F]{6}$/.test(cleaned)) {
+    return null;
+  }
+
+  const srgb = hexToSrgb(hex);
+  const oklch = srgbToOklch(srgb);
+  const normalizedValue = lightnessToNormalizedValue(dynamicRange, oklch.L);
+  // NV: 0=darkest, 1=lightest → step: 0=lightest, 25=darkest
+  const stepIndex = Math.round((1 - normalizedValue) * 25);
+
+  if (oklch.C < ACHROMATIC_THRESHOLD) {
+    return { hue: 0, chromaRatio: 0, stepIndex };
+  }
+
+  const hue = ((oklch.h % 360) + 360) % 360;
+  const maxChroma = findMaxChromaInGamut(oklch.L, oklch.h);
+  const chromaRatio = maxChroma > 0 ? Math.min(1, oklch.C / maxChroma) : 0;
+
+  return { hue, chromaRatio, stepIndex };
+}

package/src/configurator/hooks/useConfigurator.ts

@@ -0,0 +1,33 @@
+import { useReducer, useCallback, useMemo } from 'react';
+import type { ConfiguratorState } from '../types';
+import type { ConfiguratorAction } from '../state/actions';
+import type { NewtoneThemeConfig } from '@newtonedev/components';
+import { configuratorReducer, migrateConfiguratorState } from '../state/reducer';
+import { DEFAULT_CONFIGURATOR_STATE } from '../state/defaults';
+import { toThemeConfig } from '../bridge/toThemeConfig';
+
+export interface UseConfiguratorResult {
+  readonly state: ConfiguratorState;
+  readonly dispatch: (action: ConfiguratorAction) => void;
+  readonly themeConfig: NewtoneThemeConfig;
+  readonly reset: () => void;
+}
+
+export function useConfigurator(
+  initialState?: Partial<ConfiguratorState>,
+): UseConfiguratorResult {
+  // Merge with defaults, then run full migration (palette format + count)
+  const merged = initialState
+    ? { ...DEFAULT_CONFIGURATOR_STATE, ...initialState }
+    : DEFAULT_CONFIGURATOR_STATE;
+
+  const mergedInitial = migrateConfiguratorState(merged);
+
+  const [state, dispatch] = useReducer(configuratorReducer, mergedInitial);
+
+  const themeConfig = useMemo(() => toThemeConfig(state), [state]);
+
+  const reset = useCallback(() => dispatch({ type: 'RESET' }), []);
+
+  return { state, dispatch, themeConfig, reset };
+}