@dstackai/sqircle 0.1.0 → 0.1.2

package/docs/react/README.md

@@ -1,17 +1,16 @@
 # React Component Guide
 
-The maintainable implementation lives in `src/squircle`. Static HTML pages remain useful visual fixtures, but new constructor work should prefer the React component.
+The maintainable renderer implementation lives in `src/squircle`. The root HTML files mount React examples from `src/pages`; reusable scene work should prefer `SquircleScene` rather than static SVG markup.
 
 ## Files
 
 - `src/squircle/SquircleScene.tsx`: renders the SVG scene.
-- `src/squircle/SquircleEditor.tsx`: reusable editor UI that owns layer editing, preview, React code output, and optional controlled state.
-- `src/squircle/codeExport.ts`: serializes the current editor state into a copyable `SquircleScene` React component snippet.
 - `src/squircle/geometry.ts`: generates superellipse prism, hidden edge, inlay, label transform, and gradient bounds from constants.
 - `src/squircle/palettes.ts`: exports palette constants.
 - `src/squircle/types.ts`: public config and prop types.
-- Top-plane text is rendered by `SquircleScene` as live SVG text projected with the same isometric matrix as the top face. The constructor demo uses `GPU` as example text, but component configs can pass any string.
-- `src/App.tsx`: tiny app entry that renders `SquircleEditor`.
+- `src/pages`: repo-local examples that consume `SquircleScene`.
+- Top-plane text is rendered by `SquircleScene` as live SVG text projected with the same isometric matrix as the top face. The demos use `GPU` as example text, but component configs can pass any string.
+- `src/squircle/SquircleEditor.tsx` and `src/squircle/codeExport.ts`: optional constructor UI and code exporter, documented separately in [editor.md](./editor.md).
 
 ## Renderer Component
 
@@ -23,7 +22,7 @@ The maintainable implementation lives in `src/squircle`. Static HTML pages remai
       id: "bottom",
       offset: { y: 176 },
       base: { material: "wireframe", paletteId: "15" },
-      hover: { material: "solid", paletteId: "20" },
+      hover: { material: "solid", paletteId: "20", effect: "fluid" },
       stroke: { wire: 1.6, face: 0.35, labelWire: 1.1 }
     }
   ]}
@@ -35,72 +34,115 @@ The maintainable implementation lives in `src/squircle`. Static HTML pages remai
 
 ## Editor Component
 
-Use `SquircleEditor` when you want the complete constructor UI:
+The optional constructor UI is documented separately in [Editor Guide](./editor.md). Keep this guide focused on the main renderer and reusable scene data model.
 
-```tsx
-<SquircleEditor
-  initialLayers={createSquircleLayers(5)}
-  onChange={(layers) => console.log(layers)}
-/>
-```
+## Complete Options Reference
 
-The editor uses `SquircleScene` for the center preview. It can be uncontrolled with `initialLayers`, or controlled with `value` plus `onChange`. It supports 0-N layers, add/delete/clear, layer visibility, preview click selection, base/hover variant editing, stroke controls, and a copyable Code panel through `showCode`.
+This section is the renderer source of truth for public options. Keep it synchronized with `src/squircle/types.ts`.
 
-`showConfig` remains as a deprecated compatibility alias for `showCode`; new callers should use `showCode`. The Code panel shows actual TSX: it imports `SquircleScene`, defines a typed `SquircleLayerConfig[]`, includes the active `theme`, and renders a ready-to-use component. The icon button copies that React code to the clipboard.
+### `SquircleScene`
 
-Both public components accept `theme="light" | "dark"`. `SquircleScene` keeps the SVG transparent and palette-driven, but adds `.sq-theme-light` / `.sq-theme-dark` classes plus `data-theme` for host styling. `SquircleEditor` applies the theme to the whole constructor shell and passes it into the preview scene.
+| Prop | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `layers` | `SquircleLayerConfig[]` | required | Draw-order layer array. First item is lowest/backmost; last item is topmost/frontmost. |
+| `geometry` | `SquircleGeometryConfig` | `DEFAULT_GEOMETRY` | Scene geometry, projection, prism height, and dashed inlay scale. |
+| `selectedLayerId` | `string \| null` | `null` | Marks a layer as selected for class/state styling. Does not move or restack layers. |
+| `theme` | `light`, `dark` | `light` | Adds theme classes/data attributes for host styling while keeping the SVG background transparent. |
+| `idPrefix` | `string` | generated React id | Prefix for SVG gradient ids. Use when deterministic ids are required. |
+| `className` | `string` | none | Extra class on the root SVG. |
+| `ariaLabel` | `string` | `Squircle scene` | Accessible label for the SVG. |
+| `fitToLayers` | `boolean` | `true` | Expands the viewBox height to include visible layer offsets. |
+| `transitionMs` | `number` | `220` | Hover crossfade duration in milliseconds. |
+| `onLayerSelect` | `(layerId: string) => void` | none | Called when a rendered layer is clicked. |
 
-The editor can own theme state or be controlled:
-
-```tsx
-<SquircleEditor
-  defaultTheme="dark"
-  showThemeSwitch
-/>
-
-<SquircleEditor
-  theme={theme}
-  onThemeChange={setTheme}
-/>
-```
+### `SquircleLayerConfig`
 
-The constructor page shows a Light/Dark segmented control in the top bar by default. Hide it with `showThemeSwitch={false}` when the host app owns theme elsewhere.
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | required | Stable layer id. |
+| `visible` | `boolean` | `true` | Hidden layers are skipped without changing other offsets. |
+| `offset` | `{ x?: number; y?: number }` | `{ x: 0, y: 0 }` | SVG translation for this layer. |
+| `base` | `SquircleVariantConfig` | required | Normal layer state. |
+| `hover` | `SquircleVariantConfig` | none | Hover state merged over `base`. If absent or identical, no hover copy is rendered. |
+| `stroke` | `Partial<SquircleStrokeConfig>` | default strokes | Layer-wide stroke overrides. |
+| `opacity` | `Partial<SquircleOpacityConfig>` | default opacity | Layer-wide opacity overrides. |
+| `className` | `string` | none | Extra class on the layer group. |
 
-The generated React code includes the active `theme` next to `layers` so a handoff can recreate the same constructor appearance.
+### `SquircleVariantConfig`
 
-Use the exporter directly when you need the same code string outside the full editor:
-
-```ts
-import { createSquircleReactCode } from "./squircle";
+Each layer has a required `base` variant and an optional `hover` variant. Hover is still a state swap: the component renders a `.sq-hover` group only when the resolved hover variant differs from base. If hover is absent or identical, the layer has no `.sq-has-hover`, no hover copy, and no crossfade blink.
 
-const code = createSquircleReactCode({
-  theme: "light",
-  layers,
-  componentName: "CustomSquircle"
-});
-```
+| Field | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `material` | `solid`, `transparent`, `wireframe` | `wireframe` | Prism rendering mode. |
+| `paletteId` | `13` through `20` | `15` | Palette from `SQUIRCLE_PALETTES`. |
+| `effect` | `off`, `fluid`, `frosted` | `off` | Solid-material top-face effect. Ignored by transparent and wireframe materials. |
+| `text` | `string`, `boolean` | none | Render top-plane text. Pass a string such as `"GPU"` or `"{}"`; `true` is a compatibility shorthand for `"GPU"`. |
+| `dash` | `boolean` | `false` | Render the dashed inlay. |
+| `textStyle` | `solid`, `wireframe` | `solid` | Filled or outlined text. |
+| `textColor` | `auto`, `white`, `black`, `contrast` | `contrast` | Text paint for solid/transparent material. `auto` and `contrast` currently resolve the same way. |
+| `textSize` | `number` | `62` | Text font size. |
+| `textFontFamily` | `string` | `Arial, Helvetica, sans-serif` | SVG text font family. |
+| `textFontWeight` | `string`, `number` | `400` | SVG text font weight. |
+| `dashColor` | `auto`, `white`, `black`, `contrast` | `contrast` | Dash paint for solid/transparent material. |
+| `stroke` | `Partial<SquircleStrokeConfig>` | default strokes | Per-variant stroke overrides. |
+| `opacity` | `Partial<SquircleOpacityConfig>` | default opacity | Per-variant opacity overrides. |
+
+`auto` is the preferred value for palette-managed annotation paint. `contrast` remains a backwards-compatible alias and renders the same way. `gpu`, `gpuStyle`, and `gpuColor` are deprecated aliases accepted only for older snippets; new configs and generated code should use `text`, `textStyle`, and `textColor`.
+
+### `SquircleGeometryConfig`
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `width` | `number` | `800` | SVG viewBox width and geometry fitting target. |
+| `viewBoxHeight` | `number` | `480` | Base SVG viewBox height before optional layer fitting. |
+| `exponent` | `number` | `12` | Superellipse exponent. Lower is rounder, higher is squarer. |
+| `samples` | `number` | `160` | Number of sampled superellipse points. |
+| `halfSize` | `number` | computed from `width` | Raw superellipse half-size before projection. |
+| `prismHeight` | `number` | `10` | Extrusion height in SVG units. |
+| `angleDegrees` | `number` | `20` | Isometric projection elevation angle. |
+| `inlayScale` | `number` | `0.6` | Dashed inlay scale relative to the outer squircle. |
+| `center` | `{ x: number; y: number }` | computed | Projection center. Override only when manually composing a custom viewBox. |
+
+### `SquircleStrokeConfig`
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `face` | `0.35` | Hairline stroke for filled top and side faces. |
+| `faceOpacity` | `0.72` | Opacity for filled-face strokes. |
+| `wire` | `1.6` | Visible wireframe outline width. |
+| `wireOpacity` | `0.88` | Visible wireframe outline opacity. |
+| `hidden` | `1.2` | Hidden/back wireframe guide width. |
+| `hiddenOpacity` | `0.28` | Hidden/back wireframe guide opacity. |
+| `dash` | `2.2` | Dashed inlay width for solid/transparent material. |
+| `wireDash` | `1.6` | Dashed inlay width for wireframe material. |
+| `labelWire` | `1.1` | Outlined text stroke width. |
+
+### `SquircleOpacityConfig`
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `transparentFace` | `0.38` | Face opacity for `material: "transparent"`. |
+| `transparentAnnotation` | `0.62` | Text/dash opacity on transparent material. |
+| `solidAnnotation` | `0.88` | Text/dash opacity on solid or wireframe material. |
 
-## Layer Variant Fields
+### Palettes
 
-Each layer has a required `base` variant and an optional `hover` variant. Hover is still a state swap: the component renders a `.sq-hover` group only when the resolved hover variant differs from base. If hover is absent or identical, the layer has no `.sq-has-hover`, no hover copy, and no crossfade blink.
+`paletteId` accepts any id from `SQUIRCLE_PALETTE_IDS`: `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`. The palette object fields are:
 
-Variant fields:
+| Field | Meaning |
+| --- | --- |
+| `id` | Stable palette id. |
+| `label` | Human-readable palette name. |
+| `top` | Top-face gradient stops. |
+| `side` | Side-wall gradient stops. |
+| `textWire` | Gradient stops used for outlined text. |
+| `labelFill` | Automatic filled text/dash color. |
+| `topEdge` | Top-face hairline stroke color. |
+| `sideEdge` | Side-wall hairline stroke color. |
+| `swatch` | Two-color UI swatch. |
 
-| Field | Values | Meaning |
-| --- | --- | --- |
-| `material` | `solid`, `transparent`, `wireframe` | Prism rendering mode |
-| `paletteId` | `13` through `20` | Palette from `SQUIRCLE_PALETTES` |
-| `text` | string, boolean | Render top-plane text. Pass a string such as `"GPU"` or `"CUDA"`; `true` is a compatibility shorthand for `"GPU"` |
-| `dash` | boolean | Render the dashed inlay |
-| `textStyle` | `solid`, `wireframe` | Filled or outlined text |
-| `textColor` | `contrast`, `auto`, `white`, `black` | Text paint for solid/transparent material |
-| `textSize` | number | Text font size, default `62` |
-| `textFontFamily` | string | SVG text font family, default `Arial, Helvetica, sans-serif` |
-| `textFontWeight` | string, number | SVG text font weight, default `400` |
-| `dashColor` | `contrast`, `auto`, `white`, `black` | Dash paint for solid/transparent material |
-| `stroke` | partial `SquircleStrokeConfig` | Per-variant stroke overrides |
-
-`auto` is accepted as a friendly alias for `contrast`. `gpu`, `gpuStyle`, and `gpuColor` are deprecated aliases accepted only for older snippets; new configs and generated code should use `text`, `textStyle`, and `textColor`.
+`effect: "off"` uses the normal static top gradient. `fluid` and `frosted` clip animated blurred color fields to the top face, but the fields are authored in the flat squircle plane and projected with the same isometric matrix as text. `frosted` adds a screen-space pale veil and brighter rim. Effect colors are derived from the selected alpha palette.
 
 ## Stroke Parameters
 
@@ -133,7 +175,7 @@ Set `layer.stroke` for layer-wide defaults. Set `base.stroke` or `hover.stroke`
 - `topEdge` and `sideEdge`: hairline edge strokes
 - `swatch`: UI preview colors
 
-Do not invent colors inside a layer config. Add new palettes to `palettes.ts` and update [colors.md](../design/colors.md).
+Do not invent colors inside a layer config. Add new palettes to `palettes.ts` and update [colors.md](../design/colors.md). Effect colors are derived from palette stops except for neutral white highlight/rim overlays documented in [rendering.md](../design/rendering.md).
 
 ## Geometry
 
@@ -149,7 +191,7 @@ The component generates polygons at render time. Do not paste generated point li
 
 ## 0-N Layer Helpers
 
-Use `createSquircleLayers(count)` for quick default layers and `reflowLayerOffsets(layers, gap)` when adding/removing layers in an editor. These helpers preserve the convention that the top layer has `offset.y = 0` and lower layers move downward by `gap`.
+Use `createSquircleLayers(count)` for quick default layers and `reflowLayerOffsets(layers, gap)` when adding/removing layers in a host UI. These helpers preserve the convention that the top layer has `offset.y = 0` and lower layers move downward by `gap`.
 
 ## Verification
 
@@ -160,9 +202,11 @@ npm run typecheck
 npm run build
 ```
 
-Then open `/react.html` from the Vite dev server and verify:
+Then open `/index.html` and `/demo.html` from the Vite dev server and verify:
 
 - empty layer arrays render an empty SVG without crashing.
 - adding layers keeps array order as draw order.
 - no-op hover layers do not blink.
 - wireframe text outline uses the text-local gradient, not a single-stroke replacement.
+- solid palettes can switch between `off`, `fluid`, and `frosted` without moving geometry or annotations.
+- `fluid` and `frosted` read as smooth projected surface fields, not as visible screen-space circles.

package/docs/react/editor.md

@@ -0,0 +1,162 @@
+# Editor Guide
+
+`SquircleEditor` is the optional constructor UI for building `SquircleScene` layer configs and copying ready-to-use React code. Keep renderer details in [README.md](./README.md); this file owns editor behavior, editor props, and code export.
+
+## Files
+
+- `src/squircle/SquircleEditor.tsx`: reusable constructor UI.
+- `src/squircle/SquircleEditor.css`: editor shell, layer list, inspector, preview, and responsive styles.
+- `src/squircle/codeExport.ts`: serializes editor state into a copyable `SquircleScene` component snippet.
+- `src/pages/ConstructorPage.tsx`: local example page that mounts `SquircleEditor`.
+
+## Usage
+
+```tsx
+import { SquircleEditor } from "@dstackai/sqircle";
+import "@dstackai/sqircle/style.css";
+
+export function Constructor() {
+  return (
+    <SquircleEditor
+      title="Squircle Constructor"
+      codeImportPath="@dstackai/sqircle"
+      showCode
+    />
+  );
+}
+```
+
+Use controlled state when the host app owns layer, geometry, or theme data:
+
+```tsx
+<SquircleEditor
+  value={layers}
+  onChange={setLayers}
+  geometry={geometry}
+  onGeometryChange={setGeometry}
+  theme={theme}
+  onThemeChange={setTheme}
+/>
+```
+
+## UX Model
+
+The editor is organized as three zones:
+
+- `Layers`: cards with material, palette, text/dash/hover tags, and an eye icon for visibility. Add and clear actions live beside the layer count.
+- `Preview`: the live `SquircleScene` stage. Clicking a squircle selects that layer. When `showCode` is enabled, the Code drawer can be opened without permanently shrinking the stage; the copy icon is available from the preview toolbar and the drawer header.
+- `Inspector`: selected-layer editing. `Base` and `Hover` are explicit state tabs, and both states use the same variant controls.
+
+On desktop, the editor workspace has a fixed app-like height and the side panels scroll internally. This keeps the preview stage stable when toggling controls such as Text or Dash; annotations must never appear to move layer positions.
+
+The controls are intentionally visual: material and text-paint choices use segmented buttons, text/dash/hover use action chips, palette choices use swatches, and editable annotation colors use `Auto / White / Black` segmented controls. Avoid generic dropdowns or checkboxes unless the option set becomes too large to scan.
+
+Hover editing is a pure variant swap. Enabling hover creates a hover variant by copying the base state and flipping the material (`wireframe` <-> `solid`) as a starting point. No hover control should add transforms, filters, shadows, spacing changes, or layer-gap changes.
+
+## Editor Options
+
+| Prop | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `value` | `SquircleLayerConfig[]` | uncontrolled | Controlled layer state. Pair with `onChange`. |
+| `initialLayers` | `SquircleLayerConfig[]` | three wireframe layers | Initial uncontrolled layer state. |
+| `onChange` | `(layers) => void` | none | Receives layer updates. |
+| `geometry` | `SquircleGeometryConfig` | uncontrolled | Controlled geometry state. Pair with `onGeometryChange`. |
+| `initialGeometry` | `SquircleGeometryConfig` | editor defaults | Initial uncontrolled geometry state. |
+| `onGeometryChange` | `(geometry) => void` | none | Receives geometry updates. |
+| `title` | `string` | `Squircle` | Editor heading and generated component-name fallback. |
+| `description` | `string` | constructor description | Editor subtitle. |
+| `schema` | `string` | none | Deprecated compatibility prop; unused by the React-code exporter. |
+| `className` | `string` | none | Extra class on the editor root. |
+| `layerGap` | `number` | `88` | Gap used when adding/removing layers with `reflowLayerOffsets()`. |
+| `showCode` | `boolean` | `showConfig` | Shows the React Code drawer. |
+| `showConfig` | `boolean` | `true` | Deprecated alias for `showCode`. |
+| `codeComponentName` | `string` | `title` | Generated React component name. |
+| `codeImportPath` | `string` | `./squircle` | Import path used by the generated code. |
+| `theme` | `light`, `dark` | uncontrolled | Controlled editor and preview theme. Pair with `onThemeChange`. |
+| `defaultTheme` | `light`, `dark` | `light` | Initial uncontrolled editor theme. |
+| `onThemeChange` | `(theme) => void` | none | Receives theme updates. |
+| `showThemeSwitch` | `boolean` | `true` | Shows the Light/Dark switcher. |
+
+## Editor Coverage
+
+The editor exposes the common constructor surface:
+
+- layer add/delete/visibility and preview selection
+- theme
+- scene radius, height, and dash size
+- base material, palette, effect, text, text paint, text color, text size, font weight, dash, and dash color
+- hover material, palette, effect, text, text paint, text color, text size, font weight, dash, and dash color
+- collapsed stroke width controls for face, wire, dash, and text outline
+- generated React code
+
+Layer labels are generic (`Layer 1`, `Layer 2`, ...), because the editor supports 0-N layers. The array order remains draw order: lower-numbered layers are lower/backmost, and higher-numbered layers sit above them after `reflowLayerOffsets()`.
+
+Supported renderer API fields that remain intentionally code-only in the editor:
+
+- advanced text typography: `textFontFamily`
+- advanced opacity: `transparentFace`, `transparentAnnotation`, `solidAnnotation`
+- deeper stroke tuning: `faceOpacity`, `wireOpacity`, `hidden`, `hiddenOpacity`, `wireDash`
+- advanced geometry beyond Radius/Height/Dash size: `angleDegrees`, `center`, `width`, `viewBoxHeight`, `samples`, `halfSize`
+- manual layer offsets and scene fitting
+
+The `Effect` segmented control appears only when the edited state has `material: "solid"`. It writes `effect: "off" | "fluid" | "frosted"`. The renderer ignores this field for `transparent` and `wireframe`, so hiding the control for those materials avoids implying that it changes glass or wire states.
+
+## Annotation Rules
+
+Annotation color controls are contextual. Text color appears after enabling text; dash color appears after enabling dash. Wireframe material owns annotation paint through gradients, so the editor shows the forced gradient token instead of pretending `Auto / White / Black` would apply.
+
+`Auto` is the default annotation color. Enabling text or dash writes `auto` explicitly unless the layer already has a color choice. Text size and font weight appear with the text controls because they are per-variant typography settings.
+
+Radius, Height, and Dash size are scene-level controls in the left panel. Radius maps to `geometry.exponent`, Height maps to `geometry.prismHeight`, and Dash size maps to `geometry.inlayScale`.
+
+## Code Export
+
+`showConfig` remains as a deprecated compatibility alias for `showCode`; new callers should use `showCode`. The Code drawer shows actual TSX: it imports `SquircleScene`, defines a typed `SquircleLayerConfig[]`, includes the active `theme`, and renders a ready-to-use component. The icon button copies that React code to the clipboard.
+
+When `codeImportPath="@dstackai/sqircle"`, generated code also imports `@dstackai/sqircle/style.css`. Set `styleImportPath={false}` through `createSquircleReactCode()` if a host app already bundles the component CSS another way.
+
+Use the exporter directly when you need the same code string outside the full editor:
+
+```ts
+import { createSquircleReactCode } from "@dstackai/sqircle";
+
+const code = createSquircleReactCode({
+  theme: "light",
+  layers,
+  geometry,
+  componentName: "CustomSquircle",
+  importPath: "@dstackai/sqircle"
+});
+```
+
+### `createSquircleReactCode()`
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `layers` | `SquircleLayerConfig[]` | required | Layers to serialize into TSX. |
+| `theme` | `SquircleTheme` | required | Theme to serialize into TSX. |
+| `geometry` | `SquircleGeometryConfig` | none | Optional geometry object to serialize. |
+| `componentName` | `string` | `CustomSquircle` | Generated component name. Sanitized with `toComponentName()`. |
+| `importPath` | `string` | `./squircle` | Import path for `SquircleScene` and types. |
+| `styleImportPath` | `string \| false` | auto for `@dstackai/sqircle` | CSS import path. Set `false` to omit CSS import. |
+| `ariaLabel` | `string` | `${componentName} composition` | Serialized `ariaLabel` for `SquircleScene`. |
+
+## Verification
+
+Run:
+
+```sh
+npm run typecheck
+npm run build
+npm run build:demo
+```
+
+Then open `/constructor.html` from the Vite dev server and verify:
+
+- three default wireframe layers render.
+- click selection works in the layer list and preview.
+- visibility, add, delete, theme switching, and shape controls update the preview.
+- base and hover state tabs expose the same variant controls.
+- palette and effect changes update the preview and copied code.
+- no-op hover layers do not blink.
+- copied React code imports the expected package path and includes active layers, theme, and geometry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dstackai/sqircle",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React components for precise isometric squircle-prism SVG compositions.",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,8 @@
     "dist",
     "README.md",
     "docs/react",
-    "docs/design"
+    "docs/design",
+    "docs/examples"
   ],
   "exports": {
     ".": {