@dstackai/sqircle 0.1.1 → 0.1.2

package/README.md

@@ -64,7 +64,13 @@ const layers: SquircleLayerConfig[] = [
   {
     id: "top",
     offset: { y: 0 },
-    base: { material: "solid", paletteId: "15", text: "GPU", dash: true },
+    base: {
+      material: "solid",
+      paletteId: "15",
+      effect: "fluid",
+      text: "GPU",
+      dash: true
+    },
     hover: { material: "wireframe", paletteId: "20" }
   }
 ];
@@ -116,6 +122,7 @@ Each layer has a required `base` variant and an optional `hover` variant. Hover
 | --- | --- | --- | --- |
 | `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. |
@@ -181,6 +188,16 @@ Each layer has a required `base` variant and an optional `hover` variant. Hover
 | `sideEdge` | Side-wall hairline stroke color. |
 | `swatch` | Two-color UI swatch. |
 
+`effect: "off"` uses the normal static top gradient. `fluid` and `frosted` clip animated blurred color fields to the top face, with the color field authored in local squircle-plane coordinates and projected through 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.
+
+## Surface Effects
+
+Solid squircles can opt into animated top-surface effects with `effect: "fluid"` or `effect: "frosted"`. Both effects keep the prism geometry fixed: only the top face paint changes.
+
+The color field is built in the flat squircle plane, blurred in that local coordinate system, and then projected onto the top face. The generated top polygon remains the screen-space clip path, while the frosted veil and rim stay screen-space overlays. This keeps the gradients reading as surface paint instead of flat circles floating above the prism.
+
+Use [Rendering Contract](docs/design/rendering.md) for the exact ratios and SVG nesting rules before changing these effects.
+
 ## HTML Pages
 
 The root HTML files are intentionally thin shells. They mount React entrypoints from `src/pages`, and those pages render examples built on the package components.
@@ -229,4 +246,6 @@ Start at [Documentation Index](docs/README.md). The docs are split by purpose:
 - 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 animated top effects clipped to the generated full-resolution top polygon; annotations still draw above the effect.
+- Keep fluid/frosted color fields in local top-plane coordinates before projection; do not place their blobs directly in screen space.
 - Keep the body background transparent.

package/dist/index.d.ts

@@ -2,7 +2,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 { DEFAULT_PALETTE_ID, SQUIRCLE_PALETTE_IDS, SQUIRCLE_PALETTES, getSquirclePalette, isSquirclePaletteId } 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";
+export type { SquircleGradientStop, SquirclePalette, SquirclePaletteId } from "./palettes";
+export type { SquircleAnnotationColor, SquircleEffect, SquircleGeometryConfig, SquircleLayerConfig, SquircleMaterial, SquircleOpacityConfig, SquircleSceneProps, SquircleStrokeConfig, SquircleTextStyle, SquircleTheme, SquircleVariantConfig } from "./types";

package/dist/palettes.d.ts

@@ -179,3 +179,4 @@ 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;
+export declare function isSquirclePaletteId(paletteId: string | undefined): paletteId is SquirclePaletteId;