@dstackai/sqircle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# Squircle
+
+Squircle is a React/TypeScript component for rendering precise isometric squircle-prism SVG compositions. The reusable implementation lives in `src/squircle`; the HTML files are visual fixtures, demos, and constructor prototypes that preserve earlier design decisions.
+
+Use this repo when you need:
+
+- `SquircleScene`: a configurable SVG renderer for 0-N squircle layers.
+- `SquircleEditor`: a small constructor UI for editing layers and copying React code.
+- A documented visual system for squircle geometry, gradients, wireframes, top-plane text, and dashed inlays.
+- Static HTML reference pages for regression checks and agent handoff.
+
+## Quick Start
+
+```sh
+npm install
+npm run dev
+```
+
+Open `react.html` from the Vite dev server to use the React constructor demo.
+
+For production checks:
+
+```sh
+npm run typecheck
+npm run build
+git diff --check -- .
+```
+
+## React Usage
+
+```tsx
+import { SquircleScene, type SquircleLayerConfig } from "./squircle";
+
+const layers: SquircleLayerConfig[] = [
+  {
+    id: "bottom",
+    offset: { y: 176 },
+    base: { material: "wireframe", paletteId: "15" }
+  },
+  {
+    id: "top",
+    offset: { y: 0 },
+    base: { material: "solid", paletteId: "15", text: "GPU", dash: true },
+    hover: { material: "wireframe", paletteId: "20" }
+  }
+];
+
+export function ExampleSquircle() {
+  return <SquircleScene theme="light" layers={layers} />;
+}
+```
+
+For the full API, layer model, palette fields, editor props, and generated-code export, read [React Component Guide](docs/react/README.md).
+
+## Documentation Map
+
+Start at [Documentation Index](docs/README.md). The docs are split by purpose:
+
+- [React Component Guide](docs/react/README.md): how to use and configure `SquircleScene`, `SquircleEditor`, and code export.
+- [Design Documentation](docs/design/README.md): geometry, rendering, color, annotation, wireframe, and single-squircle visual rules.
+- [Static Prototype Documentation](docs/static/README.md): `index.html`, `demo.html`, and `constructor.html` contracts.
+- [Verification Checklist](docs/verification.md): static checks, render checks, and expected behavior.
+
+## Repository Shape
+
+| Path | Role |
+| --- | --- |
+| `src/squircle` | Main React/TypeScript component implementation |
+| `react.html` | Vite entry for the React constructor demo |
+| `index.html` | Static CSS-only hero and variant fixture |
+| `demo.html` | Static preset gallery fixture |
+| `constructor.html` | Legacy dynamic constructor prototype that exports React code |
+| `public/static/styles.css` | Shared static-page fixture styles, served at `/static/styles.css` |
+| `static/styles.css` | Symlink for opening static HTML files directly with `file://` |
+| `docs/` | Agent-facing component, design, static-page, and verification docs |
+
+## Current Visual Defaults
+
+- Superellipse: `n = 12`, `N = 160`, `a = 225.49`
+- Prism height: `h = 10`
+- Projection: `20deg`
+- ViewBox: `0 0 800 480`
+- Default palette: `15 Alpha`
+- Default three-layer offsets: bottom `y = 176`, middle `y = 88`, top `y = 0`
+
+## Hard Rules
+
+- New reusable work should go through `src/squircle`.
+- Component styles belong beside their components in `src/squircle`; static fixture styles live under `public/static/`, with `static/styles.css` kept as a direct-file symlink.
+- Do not hand-edit generated prism, inlay, or hidden-edge coordinates; regenerate from [Geometry Contract](docs/design/geometry.md).
+- Keep hover swaps opacity-only: no transform, scale, filter, halo, or layer-gap changes.
+- Render top-plane text as one SVG text element on the projected top plane. Do not duplicate it for filled and wireframe states.
+- Keep variant colors synchronized with [Color System](docs/design/colors.md).
+- Keep the body background transparent.

package/dist/SquircleEditor.d.ts

@@ -0,0 +1,24 @@
+import type { SquircleLayerConfig, SquircleTheme } from "./types";
+import "./SquircleEditor.css";
+export interface SquircleEditorProps {
+    value?: SquircleLayerConfig[];
+    initialLayers?: SquircleLayerConfig[];
+    onChange?: (layers: SquircleLayerConfig[]) => void;
+    title?: string;
+    description?: string;
+    /** @deprecated The editor now exports React code instead of schema-tagged JSON. */
+    schema?: string;
+    className?: string;
+    layerGap?: number;
+    showCode?: boolean;
+    /** @deprecated Use showCode. */
+    showConfig?: boolean;
+    codeComponentName?: string;
+    codeImportPath?: string;
+    theme?: SquircleTheme;
+    defaultTheme?: SquircleTheme;
+    onThemeChange?: (theme: SquircleTheme) => void;
+    showThemeSwitch?: boolean;
+}
+export declare function createDefaultSquircleEditorLayers(paletteId?: string): SquircleLayerConfig[];
+export declare function SquircleEditor({ value, initialLayers, onChange, title, description, className, layerGap, showCode, showConfig, codeComponentName, codeImportPath, theme, defaultTheme, onThemeChange, showThemeSwitch }: SquircleEditorProps): import("react").JSX.Element;

package/dist/SquircleScene.d.ts

@@ -0,0 +1,3 @@
+import type { SquircleSceneProps } from "./types";
+import "./SquircleScene.css";
+export declare function SquircleScene({ layers, geometry, selectedLayerId, theme, idPrefix, className, ariaLabel, fitToLayers, transitionMs, onLayerSelect }: SquircleSceneProps): import("react").JSX.Element;

package/dist/codeExport.d.ts

@@ -0,0 +1,10 @@
+import type { SquircleLayerConfig, SquircleTheme } from "./types";
+export interface SquircleReactCodeOptions {
+    layers: SquircleLayerConfig[];
+    theme: SquircleTheme;
+    componentName?: string;
+    importPath?: string;
+    ariaLabel?: string;
+}
+export declare function createSquircleReactCode({ layers, theme, componentName, importPath, ariaLabel }: SquircleReactCodeOptions): string;
+export declare function toComponentName(input: string): string;

package/dist/geometry.d.ts

@@ -0,0 +1,42 @@
+import type { SquircleGeometryConfig, SquircleLayerConfig, SquirclePoint } from "./types";
+export declare const DEFAULT_GEOMETRY: {
+    readonly width: 800;
+    readonly viewBoxHeight: 480;
+    readonly exponent: 12;
+    readonly samples: 160;
+    readonly prismHeight: 10;
+    readonly angleDegrees: 20;
+    readonly inlayScale: 0.6;
+};
+interface Bounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface SquircleGeometry {
+    config: Required<Omit<SquircleGeometryConfig, "halfSize" | "center">> & {
+        halfSize: number;
+        center: SquirclePoint;
+    };
+    cosA: number;
+    sinA: number;
+    topPoints: SquirclePoint[];
+    bottomPoints: SquirclePoint[];
+    wallPoints: SquirclePoint[];
+    hiddenPoints: SquirclePoint[];
+    inlayPoints: SquirclePoint[];
+    labelTransform: string;
+    topBounds: Bounds;
+    sideBounds: Bounds;
+    viewBox: string;
+}
+export declare function createSquircleGeometry(input?: SquircleGeometryConfig): SquircleGeometry;
+export declare function pointsToString(points: SquirclePoint[]): string;
+export declare function createSquircleLayers(count: number, options?: {
+    gap?: number;
+    paletteId?: string;
+    material?: "solid" | "transparent" | "wireframe";
+}): SquircleLayerConfig[];
+export declare function reflowLayerOffsets(layers: SquircleLayerConfig[], gap?: number): SquircleLayerConfig[];
+export {};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { SquircleScene } from "./SquircleScene";
+export { SquircleEditor, createDefaultSquircleEditorLayers } from "./SquircleEditor";
+export { createSquircleReactCode, toComponentName } from "./codeExport";
+export { DEFAULT_GEOMETRY, createSquircleGeometry, createSquircleLayers, reflowLayerOffsets } from "./geometry";
+export { DEFAULT_PALETTE_ID, SQUIRCLE_PALETTE_IDS, SQUIRCLE_PALETTES, getSquirclePalette } from "./palettes";
+export type { SquircleReactCodeOptions } from "./codeExport";
+export type { SquircleEditorProps } from "./SquircleEditor";
+export type { SquircleAnnotationColor, SquircleGeometryConfig, SquircleLayerConfig, SquircleMaterial, SquircleOpacityConfig, SquircleSceneProps, SquircleStrokeConfig, SquircleTextStyle, SquircleTheme, SquircleVariantConfig } from "./types";

package/dist/palettes.d.ts

@@ -0,0 +1,181 @@
+export interface SquircleGradientStop {
+    offset: number;
+    color: string;
+}
+export interface SquirclePalette {
+    id: string;
+    label: string;
+    top: SquircleGradientStop[];
+    side: SquircleGradientStop[];
+    textWire: SquircleGradientStop[];
+    labelFill: string;
+    topEdge: string;
+    sideEdge: string;
+    swatch: [string, string];
+}
+export declare const SQUIRCLE_PALETTES: {
+    "13": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "14": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "15": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "16": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "17": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "18": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "19": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+    "20": {
+        id: string;
+        label: string;
+        top: {
+            offset: number;
+            color: string;
+        }[];
+        side: {
+            offset: number;
+            color: string;
+        }[];
+        textWire: {
+            offset: number;
+            color: string;
+        }[];
+        labelFill: string;
+        topEdge: string;
+        sideEdge: string;
+        swatch: [string, string];
+    };
+};
+export type SquirclePaletteId = keyof typeof SQUIRCLE_PALETTES;
+export declare const SQUIRCLE_PALETTE_IDS: SquirclePaletteId[];
+export declare const DEFAULT_PALETTE_ID: SquirclePaletteId;
+export declare function getSquirclePalette(paletteId: string | undefined): SquirclePalette;