@dstackai/sqircle 0.1.0 → 0.1.2

package/docs/design/README.md

@@ -6,13 +6,14 @@ Read these files when changing how a squircle looks. They are visual contracts s
 | --- | --- |
 | [geometry.md](./geometry.md) | Superellipse sampling, projection, side-wall visibility, layer offsets, regeneration checklist |
 | [rendering.md](./rendering.md) | Gradients, edge sharpness, draw order, dashed inlay, text path and paint rules |
-| [colors.md](./colors.md) | Palette stops, text contrast colors, edge colors, hover palette rules |
+| [colors.md](./colors.md) | Alpha palettes, text contrast colors, edge colors, hover palette rules |
 | [single-squircle-states.md](./single-squircle-states.md) | Reusable one-squircle state recipes for solid, transparent, wireframe, text, dash, and text + dash |
 
 ## Design Source Of Truth
 
 - Geometry is generated from math, not hand-edited point lists.
 - Filled faces use user-space gradients plus tiny in-family edge strokes.
+- Solid faces can use `off`, `fluid`, or `frosted` top-surface effects without moving geometry.
 - Wireframe faces use gradient strokes with matching top and bottom curves.
 - React top-plane text is one live SVG text element in every mode. Static fixtures keep a single compound `GPU` path for their fixed example.
 - Solid/transparent annotations use contrast colors; wireframe annotations use wire gradients.

package/docs/design/colors.md

@@ -4,15 +4,11 @@ This file is the palette contract for variants, gradients, text labels, and edge
 
 ## Sources Of Truth
 
-Colors are defined in shared CSS and in each self-contained HTML page that embeds SVG definitions. Keep them synchronized:
+Colors are defined in `src/squircle/palettes.ts` and consumed by `SquircleScene`. The root HTML files are Vite shells and do not own gradient stops. Keep these synchronized:
 
-1. SVG gradients in `index.html`, `demo.html`, and `constructor.html`:
-   - `top-13..top-20`
-   - `gpu-surface-13..gpu-surface-20` in static fixtures, mirrored as `text-surface-*` in React output
-   - `side-13..side-20`
-2. CSS variables in `public/static/styles.css`:
-   - Selected-variant selectors for `.hero-card` and `.single-drawer`
-   - `.v13..v20` classes for variant cards
+1. `SQUIRCLE_PALETTES`: alpha palettes `13..20`.
+2. Renderer docs in `README.md` and `docs/react/README.md`.
+3. This design file.
 
 Do not add or rename a variant in only one place.
 
@@ -45,7 +41,7 @@ The text surface gradient repeats the matching `top-*` stops with label-local co
 
 ## CSS Variable Contract
 
-Every selected-variant selector must target both `.hero-card` and `.single-drawer`:
+Legacy static snapshots used CSS variables such as `--top-fill` and `--side-fill`. New React work should not edit those snapshots as source of truth. If a legacy static snapshot must be refreshed, keep every selected-variant selector targeting both `.hero-card` and `.single-drawer`:
 
 ```css
 #variant-15:checked ~ .hero-card,
@@ -76,41 +72,41 @@ Variant classes may also define fallback ghost colors, but those must remain vis
 
 ## Hover Palettes
 
-`constructor.html` and `demo.html` can use any palette id as a layer's `hoverPalette`. The base variant keeps `.v${palette}` or inherits the selected page variant, and the hover variant receives `.v${hoverPalette}`. This means hover color changes use the same documented gradients, label contrast, and wireframe stroke colors as normal rendering.
+React examples and generated code can use any palette id as a layer's hover `paletteId`. The base variant keeps its normal palette, and the hover variant receives its own `paletteId`. This means hover color changes use the same documented gradients, label contrast, and wireframe stroke colors as normal rendering.
 
-Do not implement hover color with filters, opacity hacks, or untracked ad hoc colors. Hover color is a normal palette swap. `hoverPalette` may be the same id as the base `palette`; that is useful when hover should change only material while preserving color. If both hover state and hover palette match the base state and palette, the result is a deliberate no-op and should still be exported exactly, but it should not render or crossfade a hover variant.
+Do not implement hover color with filters, opacity hacks, or untracked ad hoc colors. Hover color is a normal palette swap. Hover `paletteId` may be the same id as the base `paletteId`; that is useful when hover should change only material while preserving color. If the resolved hover variant matches the base variant, `SquircleScene` should not render or crossfade a hover copy.
 
 ## Annotation Auto And Overrides
 
-Static pages and constructor layers with `gpuColor: "contrast"` and `dashColor: "contrast"` use the palette's automatic annotation colors. React configs use `textColor: "contrast"` for the same concept. Solid and transparent top-plane annotations use `--label-fill`. This applies to both the filled text path and the solid dashed `#top-inlay`, so default text + dash states keep one automatic contrast color.
+React layers with `textColor: "contrast"` and `dashColor: "contrast"` use the palette's automatic annotation colors. Solid and transparent top-plane annotations use the palette `labelFill`. This applies to both filled text and solid dashed inlays, so default text + dash states keep one automatic contrast color.
 
 - Darker top gradients may use a near-white label. Current example: `15 Alpha` uses `#f7fbff`.
 - Lighter top gradients should use dark in-family annotation colors.
 - Do not add a second outline copy for automatic contrast.
 
-Wireframe text labels ignore `--label-fill` and use gradient wire paint:
+Wireframe text labels ignore fixed label paint and use gradient wire paint:
 
 ```css
 fill: none !important;
-stroke: var(--top-fill);
+stroke: url("#...text-wire...");
 stroke-width: var(--label-wire-width);
 ```
 
-`#top-inlay-wire` also uses `stroke: var(--top-fill)`.
+Wireframe inlays use the top-face gradient.
 
-In React, `textStyle: "wireframe"` outlines the same live SVG text element used by filled mode. On solid/transparent material, outline paint comes from `textColor`; `contrast` resolves to `--label-fill`, matching filled text and solid dash. On wireframe material, outline paint comes from label-local `textWire` gradients; do not sample the full-face `--top-fill` ramp there, and do not replace the text with single-stroke lettering. The static constructor keeps `gpuStyle`, `gpuColor`, and `#gpu-wire-*` names only for its GPU example schema.
+In React, `textStyle: "wireframe"` outlines the same live SVG text element used by filled mode. On solid/transparent material, outline paint comes from `textColor`; `contrast` resolves to `labelFill`, matching filled text and solid dash. On wireframe material, outline paint comes from label-local `textWire` gradients; do not sample the full-face top ramp there, and do not replace the text with single-stroke lettering.
 
-`constructor.html` adds explicit annotation overrides:
+`SquircleVariantConfig` supports explicit annotation overrides:
 
 | Field | Values | Paint |
 | --- | --- | --- |
-| `gpuColor` | `contrast`, `white`, `black` | Filled or outlined GPU paint for solid/transparent material; `contrast` appears as `Auto` in the UI |
-| `gpuStyle` | `solid`, `wireframe` | Filled or outlined GPU label |
+| `textColor` | `contrast`, `white`, `black` | Filled or outlined text paint for solid/transparent material; `contrast` appears as `Auto` in the UI |
+| `textStyle` | `solid`, `wireframe` | Filled or outlined text label |
 | `dashColor` | `contrast`, `white`, `black` | Dash stroke for solid/transparent material; `contrast` appears as `Auto` in the UI |
 
-Use `Auto` when the annotation should follow the palette. The exported value is `contrast`. Use `white` or `black` only when the user deliberately wants fixed annotation paint. React generated code emits `textColor`; the static constructor stores `gpuColor`. On wireframe material, dash always uses `--top-fill`; text uses the text surface gradient at full opacity when `textStyle` is `solid` and the text wire gradient when `textStyle` is `wireframe`. Dash symbol selection is not configurable in the constructor; it follows the squircle material.
+Use `Auto` when the annotation should follow the palette. The exported value is `contrast`. Use `white` or `black` only when the user deliberately wants fixed annotation paint. On wireframe material, dash always uses the top gradient; text uses the text surface gradient at full opacity when `textStyle` is `solid` and the text wire gradient when `textStyle` is `wireframe`.
 
-Legacy configs with `gpuStyle: "transparent"` normalize to `solid`; there is no third text paint control.
+Deprecated `gpuColor` and `gpuStyle` aliases are accepted only for older snippets. Legacy configs with `gpuStyle: "transparent"` normalize to `solid`; there is no third text paint control.
 
 ## Edge Colors
 
@@ -136,15 +132,9 @@ This is intentional: light does not interact with a wireframe surface, so top an
 
 ## Adding A Variant
 
-When adding a new variant:
-
-1. Add `top-*`, `gpu-surface-*`, and `side-*` gradients in `index.html`.
-2. Mirror those gradients in `demo.html` and `constructor.html` if those pages need the new palette.
-3. Add a hidden variant radio.
-4. Add a selected-variant CSS selector targeting `.hero-card` and `.single-drawer`.
-5. Add a `.v*` class with matching variables.
-6. Add the palette to the constructor `PALETTES` array.
-7. Add a variant card in the drawer.
-8. Add the title span in the hero copy.
-9. Update this palette table.
-10. Render hero, variant drawer, single-state drawer, demo presets, and constructor controls to confirm synchronized colors.
+When adding a new palette:
+
+1. Add it to `SQUIRCLE_PALETTES`.
+2. Include top, side, text-wire, label fill, top edge, side edge, and swatch values.
+3. Update the palette table above.
+4. Render the examples and constructor controls.

package/docs/design/geometry.md

@@ -89,25 +89,26 @@ Rotate the sampled array if needed so the selected front-facing indices are emit
 
 The complementary back-bottom edge is emitted as `ghost-hidden` and is only shown in wireframe mode.
 
-## Generated SVG Blocks
+## Generated React Geometry
 
-The generator emits:
+`src/squircle/geometry.ts` returns the geometry consumed by `SquircleScene`:
 
-- `#prism-ghost` with `ghost-hidden`, `ghost-side`, and `ghost-top`
-- `#prism-active` with `active-side` and `active-top`
-- `#top-inlay` and `#top-inlay-wire`
-- `#label-gpu`, documented separately in [rendering.md](./rendering.md)
+- `topPoints`: lit top-face polygon.
+- `wallPoints`: one continuous front side-wall polygon.
+- `hiddenPoints`: back/bottom edge used only in wireframe mode.
+- `inlayPoints`: top-plane dashed squircle polygon.
+- `labelTransform`: `matrix(cosA, sinA, -cosA, sinA, cx, cy - h)` for live SVG text.
+- `topBounds` and `sideBounds`: gradient coordinate boxes.
 
 ## Regeneration Checklist
 
-When changing geometry, regenerate the polygon coordinates from the formulas above and keep these in sync:
+When changing geometry, update the generator and keep these in sync:
 
-- The generated comment in `index.html`
-- All SVG `viewBox` values
-- `.hero-squircle`, `.mini-squircle`, and `.single-squircle` aspect ratios in `public/static/styles.css`
-- Both generated inlay copies (`#top-inlay` and `#top-inlay-wire`)
-- Every `.plane-label` transform if `cosA`, `sinA`, `cx`, or `cy - h` changes
-- Gradient bboxes documented in [rendering.md](./rendering.md)
+- `DEFAULT_GEOMETRY` in `src/squircle/geometry.ts`.
+- `SquircleScene` gradient definitions in `src/squircle/SquircleScene.tsx`.
+- Example dimensions in `src/pages`.
+- Docs in [rendering.md](./rendering.md) and [single-squircle-states.md](./single-squircle-states.md).
+- Legacy snapshots only if you intentionally refresh `legacy-static/`.
 
 For small visual changes:
 

package/docs/design/rendering.md

@@ -18,6 +18,60 @@ React uses `text-surface-*` gradients to remap the top face stops into the label
 
 Wireframe mode uses the top gradient as the stroke gradient so upper and lower curves match. This intentionally avoids fake lighting on wireframes.
 
+## Solid Surface Effects
+
+`SquircleVariantConfig.effect` changes only the top-face rendering for `material: "solid"`. It is ignored by `transparent` and `wireframe`.
+
+| Effect | Rendering |
+| --- | --- |
+| `off` | A static top polygon filled by the resolved top gradient. This is the default. |
+| `fluid` | A full-resolution top-face `clipPath` containing an isometrically projected base color field plus blurred moving color blobs. A second lighter blurred layer uses screen blending. No displacement map is used. |
+| `frosted` | The same projected moving-blob field, muted by a deep base, then finished in screen space with a pale veil and a brighter neutral rim. |
+
+The moving effects are interval-driven inside `SquircleScene`; they do not query the global DOM and they do not use `requestAnimationFrame`. Motion is enabled only when a visible base or hover variant resolves to a solid `fluid` or `frosted` state.
+
+Effect color layers are authored in the flat top-face local coordinate system, not in screen coordinates. Local `(0, 0)` is the center of the raw superellipse, and local `a` is `geometry.config.halfSize`. The whole color field is then wrapped in the same isometric matrix used by labels:
+
+```text
+matrix(cosA, sinA, -cosA, sinA, cx, cy - h)
+```
+
+This means circles are intentionally authored as local circles, then become foreshortened ellipses on the tilted top plane. The top clip path stays in screen space around the generated `topPoints` polygon. For `frosted`, the white veil and bright rim also stay in screen space; only the blob/color field is projected.
+
+The SVG structure for effect faces must keep this order:
+
+```svg
+<g clip-path="url(#top-clip)">
+  <g transform="matrix(cosA,sinA,-cosA,sinA,cx,cy-h)">
+    <rect ... />
+    <g filter="url(#local-blur)">
+      <circle ... />
+    </g>
+  </g>
+  <!-- frost-only veil stays here in screen space -->
+</g>
+<!-- rim and outline stay here in screen space -->
+```
+
+Effect scale is always derived from `W = 2 * a`, the local top-plane width, not from screen pixels or the projected bbox:
+
+- Main blob radius is about `0.45 * W`.
+- Blur is about `0.13 * W`, keeping `blur / radius` near `0.27`.
+- Drift amplitude is about `0.20..0.25 * W`.
+- Blob centers are allowed to sit outside `+-a` so every frame heavily overlaps and overfills the clipped face.
+- The base rectangle covers `+-1.3a`, so the face never shows gaps between blobs.
+
+The blur filters use `filterUnits="userSpaceOnUse"` and `primitiveUnits="userSpaceOnUse"` with a local filter region centered around `(0, 0)`. If `halfSize` changes, blob radii, blur, positions, base rect, and motion amplitudes must all scale from `a` or `W` together. Scaling only some of them makes the blobs collapse into visible circles.
+
+Effect invariants:
+
+- The clip path uses the same generated `topPoints` polygon as the normal top face.
+- Fluid/frosted color blobs must never be placed directly in screen coordinates.
+- Fluid/frosted must not use `feDisplacementMap`; it turns the smooth surface field into raster clouds.
+- Annotations render after the effect, so text and dash stay readable and stay glued to the top plane.
+- Side wall geometry, layer offsets, hover transitions, and annotation transforms do not change when the effect changes.
+- Effect colors are derived from the selected alpha palette's top and side stops, except neutral white veil/rim overlays used only for glassy sharpness.
+
 ## Sharpness Edge
 
 Every filled face has a tiny in-family edge stroke:
@@ -42,16 +96,15 @@ The top face is drawn after the side wall, so it hides the back half of the extr
 
 The middle-layer dashed squircle is generated from the same superellipse at `0.6 * a` and projected at `z = h`, so it lies on the top plane. The static copies are:
 
-- `#top-inlay` for solid/transparent rendering
-- `#top-inlay-wire` for wireframe rendering
+`SquircleScene` renders the dashed inlay as the same top-plane polygon in every material. Paint changes by material:
 
-By default, solid and transparent inlays use `stroke: var(--label-fill)`, the same contrast token as the filled text label. Wireframe inlays use `stroke: var(--top-fill)`, the same gradient token as the wireframe text outline.
+By default, solid and transparent inlays use the palette label color, the same contrast token as filled text. Wireframe inlays use the top-face gradient, matching the prism wires.
 
-`constructor.html` can override dash color per layer. `dashColor: "contrast"` keeps the default token for the material's dash symbol, while `dashColor: "white"` and `dashColor: "black"` intentionally use fixed stroke colors. Dash symbol choice follows material: solid and transparent states use `#top-inlay`; wireframe states use `#top-inlay-wire`.
+`dashColor: "contrast"` keeps the material default. `dashColor: "white"` and `dashColor: "black"` intentionally use fixed stroke colors on solid/transparent material. Wireframe material ignores fixed dash color and uses the wire gradient.
 
 ## Label Source
 
-React renders top-plane text as one live SVG `<text>` element, so component configs can pass arbitrary strings such as `text: "GPU"`, `text: "CUDA"`, or `text: "AI"`. The static fixtures still store the current `GPU` demo glyph as `#label-gpu` in `<defs>` because those pages are fixed examples.
+React renders top-plane text as one live SVG `<text>` element, so component configs can pass arbitrary strings such as `text: "GPU"`, `text: "CUDA"`, or `text: "AI"`. `GPU` is only the example string used by the local demos.
 
 Current label parameters:
 
@@ -62,7 +115,7 @@ Current label parameters:
 - Centered bbox: `x = -63.0293..63.0293`, `y = -22.9473..22.9473`
 - Label wire stroke: `1.1`
 
-For static fixture glyphs, generate the path with `opentype.js@2.0.0`:
+The old static snapshots used an outlined glyph path generated with `opentype.js@2.0.0`. Do not use that path technique in new component work; keep live text so arbitrary strings render correctly.
 
 ```js
 const font = opentype.parse(fs.readFileSync("/System/Library/Fonts/Supplemental/Arial.ttf").buffer);
@@ -72,11 +125,11 @@ const tx = -((box.x1 + box.x2) / 2);
 const ty = -((box.y1 + box.y2) / 2);
 ```
 
-Apply `tx` and `ty` to every path command coordinate before writing the static `d` attribute. Keep `fill-rule="evenodd"` and `clip-rule="evenodd"` on the path so counters, such as the hole inside `P`, remain true holes.
+If a legacy snapshot ever needs refreshing, apply `tx` and `ty` to every path command coordinate before writing the static `d` attribute, and keep `fill-rule="evenodd"` plus `clip-rule="evenodd"` so counters remain true holes.
 
 ## Label Transform And Paint
 
-Every visible static label is a single `<use>` of `#label-gpu`, and every React label is a single `<text>` element. Both are transformed onto the top plane with:
+Every React label is a single `<text>` element transformed onto the top plane with:
 
 ```text
 matrix(cosA, sinA, -cosA, sinA, cx, cy - h)
@@ -90,27 +143,27 @@ matrix(0.94, 0.342, -0.94, 0.342, 400, 145.6)
 
 The transform never changes between solid and wireframe modes; only paint changes. React and constructor defaults intentionally mirror the original generated GPU path: `textSize: 62`, `textFontFamily: "Arial, Helvetica, sans-serif"`, and `textFontWeight: 400`.
 
-Solid label style:
+Solid text style:
 
-- `.plane-label` uses `fill: var(--label-fill)` and `stroke: none` when `textColor` is `contrast`.
-- `#top-inlay` uses `stroke: var(--label-fill)` so dashed inlays match the filled label color.
+- The label uses palette label paint when `textColor` is `contrast`.
+- Solid/transparent dash uses the same palette label paint by default.
 - `15 Alpha` uses `#f7fbff` because its top gradient is dark.
 - Lighter variants use dark in-family label fills.
 
-Wireframe label style:
+Wireframe text style:
 
 - `textStyle: "wireframe"` uses the same live text element as filled mode.
-- It sets `fill:none !important` and uses `stroke: var(--gpu-wire-stroke)`.
-- On solid/transparent material, `--gpu-wire-stroke` comes from `textColor`; `contrast` resolves to `--label-fill`, matching filled text and solid dash.
-- On wireframe material, `--gpu-wire-stroke` resolves to the label-local `--gpu-wire-fill` gradient.
-- `#top-inlay-wire` also uses `stroke: var(--top-fill)` so dashed inlays match the wireframe label and prism wires.
+- It sets `fill: none` and uses a stroke.
+- On solid/transparent material, outline paint comes from `textColor`; `contrast` resolves to the palette label paint, matching filled text and solid dash.
+- On wireframe material, outline paint resolves to the label-local `textWire` gradient.
+- Wireframe dash uses the top-face gradient so dashed inlays match prism wires.
 - It must remain an outline around the font figures, not a single-stroke lettering replacement.
 - Keep the outline stroke thin relative to text size. The default `labelWire` is `1.1` at `textSize: 62`, safely below the ratio where counters start merging.
 
-Do not sample the full-face `--top-fill` ramp directly for the text outline on wireframe material; it is too large for the label geometry and makes the color read wrong. Use one text element for all text styles. Use `textColor` for solid/transparent outline paint and the label-local wire gradient for wireframe-material outline paint.
+Do not sample the full-face top ramp directly for the text outline on wireframe material; it is too large for the label geometry and makes the color read wrong. Use one text element for all text styles. Use `textColor` for solid/transparent outline paint and the label-local wire gradient for wireframe-material outline paint.
 
-Constructor `gpuColor: "white"` and `gpuColor: "black"` remain in the static GPU example schema and map to React `textColor` in generated code. They override label paint only on solid/transparent material. On wireframe material, React `textStyle: "solid"` renders a fully opaque filled label using the text surface gradient, and `textStyle: "wireframe"` renders an outlined label using the text wire gradient.
+Deprecated `gpuColor` aliases are accepted only for old snippets and map to React `textColor`. They override label paint only on solid/transparent material. On wireframe material, `textStyle: "solid"` renders a fully opaque filled label using the text surface gradient, and `textStyle: "wireframe"` renders an outlined label using the text wire gradient.
 
-Do not introduce `textStyle: "transparent"` as a third paint control. Legacy static configs with `gpuStyle: "transparent"` should normalize to `solid`.
+Do not introduce `textStyle: "transparent"` as a third paint control. Legacy configs with `gpuStyle: "transparent"` should normalize to `solid`.
 
 Do not build filled letters from `<rect>`, `<line>`, or separate stem/bowl paths. Do not add a second label copy and do not replace the text with monoline lettering for outline mode.

package/docs/design/single-squircle-states.md

@@ -1,121 +1,59 @@
 # Single-Squircle State Constructors
 
-This file documents the `Single Squircle States` drawer as reusable constructors. Use these recipes when another agent wants to compose a single squircle outside the full three-layer composition.
-
-## Shared Setup
-
-Each single-state card uses:
-
-```html
-<svg class="single-squircle" viewBox="-6 -6 812 314" aria-label="...">
-  ...
-</svg>
+This file describes reusable one-layer constructors for `SquircleScene`. Use these recipes when another agent wants one squircle outside a full multi-layer composition.
+
+## Base Layer Shape
+
+```ts
+import type { SquircleLayerConfig } from "@dstackai/sqircle";
+
+const layer: SquircleLayerConfig = {
+  id: "single",
+  base: {
+    material: "solid",
+    paletteId: "15",
+    text: "GPU",
+    textStyle: "solid",
+    dash: true
+  }
+};
 ```
 
-The viewBox frames exactly one prism plus a small margin for hairline strokes. Single-state cards inherit the currently selected variant colors from `.single-drawer`, which receives the same CSS variables as `.hero-card`:
-
-- `--top-fill`
-- `--side-fill`
-- `--label-fill`
-- `--top-edge`
-- `--side-edge`
-- `--label-wire-width`
-- `--face-edge-width`
-- `--face-edge-opacity`
-
-The global transparent/wireframe switch does not affect this drawer. The drawer always shows all constructor states at once.
-
-## Building Blocks
-
-| Part | SVG use | CSS class | Purpose |
-| --- | --- | --- | --- |
-| Solid prism | `<use href="#prism-active" />` | `.single-active` | Filled, selected-looking prism with top and side gradients |
-| Transparent prism | `<use href="#prism-ghost" />` | `.single-ghost` inside `.single-transparent` | Translucent filled prism |
-| Wireframe prism | `<use href="#prism-ghost" />` | `.single-ghost` inside `.single-wire` | Gradient outline with transparent faces |
-| Solid/transparent dash | `<use href="#top-inlay" />` | `.single-inlay` | Dashed top-plane squircle using `--label-fill` |
-| Wireframe dash | `<use href="#top-inlay-wire" />` | `.single-wire-inlay.wire-inlay` | Gradient dashed top-plane squircle |
-| Text label | `<use href="#label-gpu" />` | `.single-label.plane-label` | Compound path label on the top plane; the current static glyph spells `GPU` |
-
-The label always uses this transform:
-
-```html
-transform="matrix(0.94,0.342,-0.94,0.342,400,145.6)"
-```
+`GPU` is only example text. Any string is valid, including `"{}"` or `"CUDA"`.
 
 ## Constructor Matrix
 
-| State | Card class | SVG children in order | Paint behavior |
-| --- | --- | --- | --- |
-| `Solid` | `.single-card` | `.single-active` | Filled prism using selected variant top/side gradients |
-| `Solid Text` | `.single-card` | `.single-active`, `.single-label.plane-label` | Solid prism plus filled contrast label |
-| `Solid Dash` | `.single-card` | `.single-active`, `.single-inlay` | Solid prism plus contrast dashed inlay |
-| `Solid Text + Dash` | `.single-card` | `.single-active`, `.single-inlay`, `.single-label.plane-label` | Solid prism plus dashed inlay and filled label |
-| `Transparent` | `.single-card.single-transparent` | `.single-ghost` | Translucent prism at `0.38` opacity |
-| `Transparent Text` | `.single-card.single-transparent` | `.single-ghost`, `.single-label.plane-label` | Translucent prism plus filled label at `0.62` opacity |
-| `Transparent Dash` | `.single-card.single-transparent` | `.single-ghost`, `.single-inlay` | Translucent prism plus contrast dashed inlay |
-| `Transparent Text + Dash` | `.single-card.single-transparent` | `.single-ghost`, `.single-inlay`, `.single-label.plane-label` | Translucent prism plus dashed inlay and filled label |
-| `Wireframe` | `.single-card.single-wire` | `.single-ghost` | Transparent faces, gradient wire strokes |
-| `Wireframe Text` | `.single-card.single-wire` | `.single-ghost`, `.single-label.plane-label` | Wireframe prism plus outlined gradient label |
-| `Wireframe Dash` | `.single-card.single-wire` | `.single-ghost`, `.single-wire-inlay.wire-inlay` | Wireframe prism plus gradient dashed inlay |
-| `Wireframe Text + Dash` | `.single-card.single-wire` | `.single-ghost`, `.single-wire-inlay.wire-inlay`, `.single-label.plane-label` | Wireframe prism plus gradient dashed inlay and gradient label |
-
-## Copy-Paste Recipes
-
-Solid with text:
-
-```html
-<svg class="single-squircle" viewBox="-6 -6 812 314" aria-label="Solid single squircle with text">
-  <use class="single-active" href="#prism-active" />
-  <use class="single-label plane-label" href="#label-gpu" transform="matrix(0.94,0.342,-0.94,0.342,400,145.6)" />
-</svg>
-```
-
-Transparent with text and dash:
-
-```html
-<svg class="single-squircle" viewBox="-6 -6 812 314" aria-label="Transparent single squircle with text and dashed inlay">
-  <use class="single-ghost" href="#prism-ghost" />
-  <use class="single-inlay" href="#top-inlay" />
-  <use class="single-label plane-label" href="#label-gpu" transform="matrix(0.94,0.342,-0.94,0.342,400,145.6)" />
-</svg>
-```
-
-Wireframe with text and dash:
-
-```html
-<svg class="single-squircle" viewBox="-6 -6 812 314" aria-label="Wireframe single squircle with text and dashed inlay">
-  <use class="single-ghost" href="#prism-ghost" />
-  <use class="single-wire-inlay wire-inlay" href="#top-inlay-wire" />
-  <use class="single-label plane-label" href="#label-gpu" transform="matrix(0.94,0.342,-0.94,0.342,400,145.6)" />
-</svg>
-```
-
-The text + dash states are reusable variants that combine the top-plane text path with a dashed inlay.
-
-In the static single-state drawer, solid and transparent text + dash states use `--label-fill` for both the filled text path and dashed inlay. Wireframe text + dash states use `--top-fill` for both the outlined text path and dashed inlay. `constructor.html` can override GPU color, GPU style, and dash color per layer because it is the GPU example; React generated code maps those controls to `textColor`, `textStyle`, and `dashColor`.
+| State | Config |
+| --- | --- |
+| Solid | `{ material: "solid" }` |
+| Solid Text | `{ material: "solid", text: "GPU", textStyle: "solid" }` |
+| Solid Text Outline | `{ material: "solid", text: "GPU", textStyle: "wireframe" }` |
+| Solid Dash | `{ material: "solid", dash: true }` |
+| Solid Text + Dash | `{ material: "solid", text: "GPU", textStyle: "solid", dash: true }` |
+| Transparent | `{ material: "transparent" }` |
+| Transparent Text | `{ material: "transparent", text: "GPU", textStyle: "solid" }` |
+| Transparent Text Outline + Dash | `{ material: "transparent", text: "GPU", textStyle: "wireframe", dash: true }` |
+| Wireframe | `{ material: "wireframe" }` |
+| Wireframe Text Filled | `{ material: "wireframe", text: "GPU", textStyle: "solid" }` |
+| Wireframe Text Outline | `{ material: "wireframe", text: "GPU", textStyle: "wireframe" }` |
+| Wireframe Text Outline + Dash | `{ material: "wireframe", text: "GPU", textStyle: "wireframe", dash: true }` |
+
+The local `index.html` example renders these through `createSingleStatePresets()` in `src/pages/exampleData.ts`.
+
+## Paint Rules
+
+- Solid and transparent text + dash states use palette contrast paint by default.
+- Solid/transparent `textColor` and `dashColor` may be `contrast`, `white`, or `black`.
+- Wireframe dash always uses the wire gradient.
+- Wireframe `textStyle: "wireframe"` uses the label-local text wire gradient.
+- Wireframe `textStyle: "solid"` uses the text surface gradient at full opacity.
 
 ## Ordering Rules
 
-- Draw the prism first.
-- Draw the inlay after the prism.
-- Draw the label last.
-- Use `#top-inlay` for solid/transparent states.
-- Use `#top-inlay-wire` for wireframe states.
-- Do not use two label copies. The same `.plane-label` object changes paint through CSS.
+`SquircleScene` draws a variant in this order:
 
-## Color Inheritance
-
-The drawer must be a sibling after the hidden variant radios. The selected variant selectors target both `.hero-card` and `.single-drawer`, e.g.:
-
-```css
-#variant-15:checked ~ .hero-card,
-#variant-15:checked ~ .single-drawer {
-  --top-fill: url("#top-15");
-  --side-fill: url("#side-15");
-  --label-fill: #f7fbff;
-  --top-edge: #7c5fd0;
-  --side-edge: #2d1466;
-}
-```
+1. Prism side/top or wireframe prism.
+2. Dashed inlay, when enabled.
+3. Live SVG text, when enabled.
 
-See [colors.md](./colors.md) for the full palette contract.
+Do not create two text copies for filled and outline states. The same live `<text>` object changes only paint.

package/docs/examples/README.md

@@ -0,0 +1,33 @@
+# React Example Pages
+
+The root HTML files are Vite shells. They should stay small and only mount React entrypoints from `src/pages`.
+
+| HTML | React entrypoint | Purpose |
+| --- | --- | --- |
+| `index.html` | `src/pages/IndexPage.tsx` | Hero scene plus selectable single-squircle state drawer |
+| `demo.html` | `src/pages/DemoPage.tsx` | Selectable generated gallery of 3-layer compositions |
+| `constructor.html` | `src/pages/ConstructorPage.tsx` | Full constructor UI using `SquircleEditor` |
+| `react.html` | `src/pages/ConstructorPage.tsx` | Compatibility alias for the constructor |
+
+## Source Files
+
+- `src/pages/exampleData.ts`: shared preset and seed-layer constructors.
+- `src/pages/PageShell.tsx`: shared page chrome and theme switch.
+- `src/pages/pages.css`: example-page layout styles.
+
+The examples must consume `SquircleScene`, `SquircleEditor`, palettes, and helpers from `src/squircle`. Do not paste generated SVG polygons or duplicate renderer logic in page files.
+
+## Behavior
+
+- `index.html` renders a main three-layer scene and a collapsed/openable drawer of single-squircle states. Palette buttons recolor the examples through React state.
+- `demo.html` renders 96 generated composition presets, including alpha palettes and solid `off`/`fluid`/`frosted` surfaces. Clicking a card changes the main hero composition. Each layer hover is a state/color swap only.
+- `constructor.html` renders `SquircleEditor` with three default plain wireframe layers. The inspector exposes palette and effect controls. The Code panel exports React code using `@dstackai/sqircle` as the import path.
+- `react.html` intentionally mirrors `constructor.html` for older links.
+
+## Rules
+
+- Keep root HTML files as shells with one `#root` and one module script.
+- Keep examples transparent-background friendly.
+- Keep hover effects as opacity crossfades between base and hover variants. Do not add movement, shadows, scale, filters, or gap changes.
+- Keep all squircle geometry, palette, stroke, annotation, and theme behavior in the reusable component layer.
+- If a legacy static behavior is still valuable, migrate it into `src/pages` or `src/squircle`; do not edit ignored snapshots as source.