@dstackai/sqircle 0.1.0

package/docs/design/rendering.md

@@ -0,0 +1,116 @@
+# Rendering Contract
+
+This file documents gradients, edge sharpness, top-plane annotations, and the text-label technique. The current demo text spells `GPU`, but reusable React config calls the feature `text`.
+
+For exact variant stops and CSS color variables, see [colors.md](./colors.md).
+
+## Gradient Bboxes
+
+All face gradients use `gradientUnits="userSpaceOnUse"` and coordinates derived from generated points:
+
+- Top gradient bbox: `x1 = 0`, `y1 = 0`, `x2 = 800`, `y2 = 291.18`
+- Text surface gradient: `x1 = -425.63`, `y1 = -0.1`, `x2 = 425.6`, `y2 = 0.07`, with the same stops as the matching top gradient
+- Side gradient bbox: `x1 = 0`, `y1 = 0`, `x2 = 800`, `y2 = 301.18`, computed from top face plus side wall
+
+Top gradients span only the top face. Side gradients span the full top-plus-wall silhouette so the shadow ramp continues in the same projected coordinate space instead of restarting on the wall.
+
+React uses `text-surface-*` gradients to remap the top face stops into the label's local projected plane. Static fixtures still use `gpu-surface-*` ids because those pages render the GPU example glyph. These gradients are used for `textStyle: "solid"` on wireframe material, where filled text should read as top-surface paint rather than wire stroke color.
+
+Wireframe mode uses the top gradient as the stroke gradient so upper and lower curves match. This intentionally avoids fake lighting on wireframes.
+
+## Sharpness Edge
+
+Every filled face has a tiny in-family edge stroke:
+
+- `--top-edge` on the top face
+- `--side-edge` on the side wall
+- `--face-edge-width: 0.35`
+- `--face-edge-opacity: 0.72`
+
+These edge colors are set per variant and must stay in the same color family. Never use black for prism edges; it flattens the gradients.
+
+## Draw Order
+
+Each prism definition follows this order:
+
+1. Side wall polygon
+2. Top face polygon
+
+The top face is drawn after the side wall, so it hides the back half of the extrusion without masks or z-buffering.
+
+## Inlay
+
+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
+
+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.
+
+`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`.
+
+## 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.
+
+Current label parameters:
+
+- Label outline source: `/System/Library/Fonts/Supplemental/Arial.ttf`
+- Label outline size: `62px`
+- Source bbox before centering: `x = 3.2998..129.3584`, `y = -45.1377..0.7568`
+- Centering translation before projection: `x = -66.3291`, `y = 22.1904`
+- 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`:
+
+```js
+const font = opentype.parse(fs.readFileSync("/System/Library/Fonts/Supplemental/Arial.ttf").buffer);
+const path = font.getPath("GPU", 0, 0, 62, { kerning: true });
+const box = path.getBoundingBox();
+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.
+
+## 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:
+
+```text
+matrix(cosA, sinA, -cosA, sinA, cx, cy - h)
+```
+
+For the current geometry:
+
+```text
+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:
+
+- `.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.
+- `15 Alpha` uses `#f7fbff` because its top gradient is dark.
+- Lighter variants use dark in-family label fills.
+
+Wireframe label 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 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.
+
+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.
+
+Do not introduce `textStyle: "transparent"` as a third paint control. Legacy static 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

@@ -0,0 +1,121 @@
+# 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>
+```
+
+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)"
+```
+
+## 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`.
+
+## 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.
+
+## 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;
+}
+```
+
+See [colors.md](./colors.md) for the full palette contract.

package/docs/react/README.md

@@ -0,0 +1,168 @@
+# 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.
+
+## 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`.
+
+## Renderer Component
+
+```tsx
+<SquircleScene
+  theme="dark"
+  layers={[
+    {
+      id: "bottom",
+      offset: { y: 176 },
+      base: { material: "wireframe", paletteId: "15" },
+      hover: { material: "solid", paletteId: "20" },
+      stroke: { wire: 1.6, face: 0.35, labelWire: 1.1 }
+    }
+  ]}
+  onLayerSelect={(id) => setSelectedId(id)}
+/>
+```
+
+`layers` can contain 0-N items. The array order is draw order: first item is lowest/backmost, last item is topmost/frontmost. A layer with `visible: false` is skipped without changing the other layer offsets.
+
+## Editor Component
+
+Use `SquircleEditor` when you want the complete constructor UI:
+
+```tsx
+<SquircleEditor
+  initialLayers={createSquircleLayers(5)}
+  onChange={(layers) => console.log(layers)}
+/>
+```
+
+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`.
+
+`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.
+
+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.
+
+The editor can own theme state or be controlled:
+
+```tsx
+<SquircleEditor
+  defaultTheme="dark"
+  showThemeSwitch
+/>
+
+<SquircleEditor
+  theme={theme}
+  onThemeChange={setTheme}
+/>
+```
+
+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.
+
+The generated React code includes the active `theme` next to `layers` so a handoff can recreate the same constructor appearance.
+
+Use the exporter directly when you need the same code string outside the full editor:
+
+```ts
+import { createSquircleReactCode } from "./squircle";
+
+const code = createSquircleReactCode({
+  theme: "light",
+  layers,
+  componentName: "CustomSquircle"
+});
+```
+
+## Layer Variant Fields
+
+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.
+
+Variant fields:
+
+| 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`.
+
+## Stroke Parameters
+
+Stroke widths and opacities are explicit data, not hard-coded CSS side effects:
+
+```ts
+{
+  face: 0.35,
+  faceOpacity: 0.72,
+  wire: 1.6,
+  wireOpacity: 0.88,
+  hidden: 1.2,
+  hiddenOpacity: 0.28,
+  dash: 2.2,
+  wireDash: 1.6,
+  labelWire: 1.1
+}
+```
+
+Set `layer.stroke` for layer-wide defaults. Set `base.stroke` or `hover.stroke` only when a particular state needs to override that layer. Geometry does not move when strokes change.
+
+## Palettes
+
+`SQUIRCLE_PALETTES` is the source of truth for React:
+
+- `top`: top-face gradient stops
+- `side`: side-wall gradient stops
+- `textWire`: text-local wireframe gradient stops
+- `labelFill`: automatic annotation color
+- `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).
+
+## Geometry
+
+`createSquircleGeometry()` implements the math from [geometry.md](../design/geometry.md):
+
+- superellipse exponent `n = 12`
+- samples `N = 160`
+- projection angle `20deg`
+- prism height `10`
+- inlay scale `0.6`
+
+The component generates polygons at render time. Do not paste generated point lists into React source.
+
+## 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`.
+
+## Verification
+
+Run:
+
+```sh
+npm run typecheck
+npm run build
+```
+
+Then open `/react.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.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@dstackai/sqircle",
+  "version": "0.1.0",
+  "description": "React components for precise isometric squircle-prism SVG compositions.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dstackai/sqircle.git"
+  },
+  "homepage": "https://github.com/dstackai/sqircle#readme",
+  "bugs": {
+    "url": "https://github.com/dstackai/sqircle/issues"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "docs/react",
+    "docs/design"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/sqircle.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/sqircle.js",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "npm run typecheck && npm run build:lib",
+    "build:demo": "tsc --noEmit && vite build",
+    "build:lib": "vite build --config vite.lib.config.ts && npm run build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0"
+  }
+}