robot-heads-solid 0.1.0 → 0.2.0-beta.1

package/README.md

@@ -1,113 +1,136 @@
 # robot-heads-solid
 
-Animated robot heads for Solid. Four shapes, nine states, and the same Canvas 2D rendering engine as [Fayaz Ahmed's robot-heads](https://github.com/fayazara/robot-heads).
+Animated 3D robot heads for Solid. Glossy, TV-headed bots with an LED-matrix face that shows what your agent is doing: thinking, searching, listening, speaking and more. Choose from four shapes, with a springy antenna, knob ears and a light on top that changes with the state.
 
-This is an independent Solid port of the MIT-licensed React project. The rendering, geometry, lighting, faces, and motion come from upstream. The component, playground, and build setup use Solid.
+Drawn on a 2D canvas: no WebGL or runtime dependencies.
+
+**[Playground →](https://robot-heads-solid.jhonra121.workers.dev)**
 
 ## Install
 
-~~~sh
+```sh
 bun add robot-heads-solid
-~~~
+```
 
-The stable release is `0.1.0`. Tested with Solid 1.9.17. Solid 2 prerelease compatibility has not been verified; its current release candidate does not provide the Solid 1 `solid-js/web` and `solid-js/jsx-runtime` entry points used by the tested consumer toolchain. React, Three.js, and WebGL are not required.
+Solid 1.9+ is supported by the default entry point. Solid 2 is still a prerelease and has a separate, explicitly selected entry point: `robot-heads-solid/solid2`. Do not mix the two entry points in one application. Solid 2 apps need both `solid-js` and `@solidjs/web` at matching versions. Solid 2 support is verified against `2.0.0-rc.14`; it is opt-in prerelease support, not a claim of compatibility with a stable Solid 2 release.
 
-## Releases
+## Quick start
 
-Releases publish from an annotated Git tag matching the version in the root `package.json` (for example, `vX.Y.Z-beta.N`). The tag must point to the `main` commit that introduced that package version. The release workflow runs anti-slop rule regression, lint, typecheck, build, browser E2E, and packed-consumer checks before publishing the exact verified tarball with npm provenance. Beta versions publish to the `beta` dist-tag; stable versions publish to `latest`. Versions are immutable and are never republished.
-All package releases share one concurrency group, and the workflow requires a release version to be strictly newer than the version already on its target npm dist-tag. If tags are pushed close together, an older queued release fails rather than moving the channel backward.
+```tsx
+import { RobotHead } from 'robot-heads-solid';
 
-One-time maintainer setup:
+function Agent(props: { status: 'idle' | 'thinking' | 'speaking' }) {
+  return <RobotHead state={props.status} size={160} />;
+}
+```
 
-1. In npm package settings for `robot-heads-solid`, configure **Trusted Publishers** for GitHub Actions with repository owner `jhomra21`, repository `robot-heads-solid`, workflow filename `release.yml`, and GitHub environment `npm-publish`. Do not create or store an npm token.
-2. In GitHub repository settings, create the `npm-publish` environment. Optionally require a reviewer to approve publication; do not add environment secrets.
-3. Ensure GitHub Actions is allowed to run and protect the `v*` tag namespace so only release maintainers can create release tags.
+### Solid 2 prerelease
 
-For each release, merge the versioned package change to `main`, then create and push its matching tag:
+Install matching Solid 2 prerelease packages and use the separate entry point:
 
-~~~sh
-git tag -a vX.Y.Z -m "vX.Y.Z"
-git push origin vX.Y.Z
-~~~
+```sh
+bun add solid-js@2.0.0-rc.14 @solidjs/web@2.0.0-rc.14 robot-heads-solid
+```
 
-Do not run `npm publish` locally. If npm Trusted Publishing is not configured or the workflow binding does not match, the publish job will fail without a token fallback.
+```tsx
+import { render } from '@solidjs/web';
+import { RobotHead } from 'robot-heads-solid/solid2';
 
-## Usage
+render(() => <RobotHead state="thinking" />, document.getElementById('root')!);
+```
 
-~~~tsx
-import { createSignal } from 'solid-js';
-import { RobotHead } from 'robot-heads-solid';
+The default `robot-heads-solid` entry remains the Solid 1.9 build. Configure the Solid 2 JSX runtime as `jsxImportSource: "@solidjs/web"` and use the Solid 2 Vite integration (`@solidjs/vite-plugin`); the Solid 1 `vite-plugin-solid` compiler does not target Solid 2. The library's Solid 2 entry has been checked for client rendering, server rendering, hydration and early-event replay.
 
-function Example() {
-  const [state, setState] = createSignal<'idle' | 'thinking' | 'working'>('idle');
-
-  return (
-    <>
-      <RobotHead
-        state={state()}
-        shape="rectangle"
-        size={160}
-        color="#2b49a3"
-        trimColor="#93a6c8"
-        screenColor="#e8f2ff"
-        speed={1}
-        interactive
-        floorShadow
-      />
-      <button onClick={() => setState('thinking')}>Think</button>
-    </>
-  );
-}
-~~~
+## Shapes
+
+One head, four outlines. Every shape has the same screen, ears, antenna, screws and back panel, and moves the same way.
+
+```tsx
+<RobotHead shape="rectangle" />  {/* the classic TV (default) */}
+<RobotHead shape="square" />
+<RobotHead shape="circle" />     {/* a porthole */}
+<RobotHead shape="hexagon" />    {/* a nut, flat on top */}
+```
 
-The component forwards ordinary Solid canvas attributes, event handlers, styling, accessibility attributes, and a canvas ref. State and appearance props react to Solid signals.
+The list is exported as `robotHeadShapes`.
 
-### Shapes
+## States
 
-'rectangle' (default), 'square', 'circle', 'hexagon'. Exported as `robotHeadShapes`.
+Each state has its own face on the screen, its own motion and its own antenna light. Switching states plays a short glitch and cross-fade, and the head eases into its new pose.
 
-### States
+| State | Screen | Motion |
+|---|---|---|
+| `idle` | block eyes that blink and glance | looks around, hops now and then |
+| `thinking` | heavy-lidded eyes looking up, three pulsing dots | head tilted up, switching sides; amber light pulses |
+| `searching` | darting eyes, a beam sweeping the whole screen | head sweeps side to side; cyan beacon |
+| `listening` | alert eyes over a live equaliser | head cocked, small nods; steady green light |
+| `speaking` | a mouth that moves with the words | bobs as it talks |
+| `working` | focused eyes looking down, a progress bar | busy bobbing, a hop with a spin now and then |
+| `happy` | `^ ^` eyes and a smile | bouncy hops |
+| `error` | red `X X` eyes | shakes its head; red light blinks |
+| `sleeping` | closed eyes and rising z's | head drooped, slow breathing; light off |
 
-'idle', 'thinking', 'searching', 'listening', 'speaking', 'working', 'happy', 'error', 'sleeping'. Exported as `robotHeadStates`.
+The list is exported as `robotHeadStates`.
 
-### Props
+## Props
 
-| Prop | Type | Default |
-| --- | --- | --- |
-| 'model' | 'tv' | 'tv' |
-| 'shape' | 'RobotHeadShape' | 'rectangle' |
-| 'state' | 'RobotHeadState' | 'idle' |
-| 'size' | 'number' (px) | 160 |
-| 'color' | 'string' | '#2b49a3' |
-| 'trimColor' | 'string' | '#93a6c8' |
-| 'screenColor' | 'string' | '#e8f2ff' |
-| 'speed' | 'number' | 1 |
-| 'paused' | 'boolean' | false |
-| 'interactive' | 'boolean' | true |
-| 'floorShadow' | 'boolean' | true |
-| 'seed' | 'number' (0–1) | generated per instance |
+```tsx
+<RobotHead
+  model="tv"                // only "tv" is supported
+  shape="rectangle"         // rectangle, square, circle or hexagon
+  state="idle"              // what it is doing (above)
+  size={160}                // px
+  color="#2b49a3"           // the shell
+  trimColor="#93a6c8"       // the ears and the antenna's collar
+  screenColor="#e8f2ff"     // the LEDs
+  speed={1}                 // multiplier on every animation
+  paused={false}            // hold the state's still pose
+  interactive               // follow the pointer, hop and spin on a click
+  floorShadow               // the soft shadow under the head
+  seed={0.3}                // 0–1, desyncs blinks and glances in a row of heads
+/>
+```
 
-Animations use one shared requestAnimationFrame loop and stop when the page is hidden or the canvas leaves the viewport. Disabled or reduced motion draws the resting pose. Invalid sizes and speeds fall back to defaults; positive sizes are clamped to 32–1024px and speeds to 8× to keep rendering and simulation work bounded. Interactive heads follow the pointer and respond to clicks. The canvas defaults to 'role="img"' and an accessible state label. Node SSR imports resolve to server-compiled ESM/CJS builds; the canvas is rendered as markup and drawn once mounted on the client.
+Any other canvas attribute (`class`, `className`, `style`, `onClick`, `aria-label`, ...) is passed through to the `<canvas>`, and a `ref` reaches it too. State and appearance props update when Solid signals change. Invalid sizes and speeds fall back to their defaults. Positive sizes are clamped to 32–1024px and speeds to 8×.
+
+## Behaviour
+
+- **Pointer play.** With `interactive` on (the default), the head and eyes follow a nearby pointer, and a click makes it hop with a full spin and a happy face.
+- **Reduced motion.** With `prefers-reduced-motion: reduce`, `paused`, or a speed of `0`, the still pose of the state is drawn instead of the animation.
+- **Accessible by default.** The canvas has `role="img"` and an `aria-label` naming the state ("Robot, thinking"); pass your own `aria-label` to override it.
+- **Cheap to run many.** Every head on the page shares one animation loop, which sleeps while the tab is hidden, and heads of the same shape and size share their baked textures.
+
+## How it is drawn
+
+The head is real geometry: a shell with a rolled edge, its outline a convex polygon of corner centres grown by a corner radius, so one builder makes every shape. Knob ears and the antenna collar are lathed and built once as quad meshes. Each frame, the head turns with the pose and is projected, back faces are culled, and every quad is lit by a small studio model: a key light, a fill, a sky dome, a softbox and the key's window caught as clear-coat reflections with Fresnel, a cool back light rimming the silhouette, and a filmic tone curve.
+
+The flat front and back are plates drawn in their own plane with baked relief: the lip rolling into the screen hole, the rubber gasket, the shadow the lip casts onto the glass, screws, and vents on the back. The glass sits a little behind the bezel, so it slides against it as the head turns. The LED matrix covers the whole screen, with the face centred on it. The LEDs are drawn crisp, then bloomed from a one-pixel-per-LED image scaled up smooth. The antenna is a damped spring that whips when the head hops, lands or tilts, topped with a frosted bulb lit from inside.
 
 ## Development
 
-~~~sh
+The library is in `src/`; the Solid playground is in `site/` and runs against the library source.
+
+```sh
 bun install
-bun run dev        # Solid playground
-bun run lint       # Oxlint: anti-slop rules and classic complexity (max 20)
-bun run typecheck
-bun run build      # browser and SSR ES/CJS bundles and declarations
-bun run check      # lint, library and playground checks
-bun run e2e        # playground browser regressions, including all 36 shape/state combinations
-bun run e2e:consumer # packed Solid 1 consumer: typecheck, browser and Node ESM/CJS SSR
-~~~
+bun run setup:solid2 # installs the isolated Solid 2 compiler/runtime toolchain
+bun run dev          # the playground
+bun run build        # the library, to dist/
+bun run typecheck    # installs the isolated Solid 2 toolchain if needed
+bun run build:site   # build the library and playground (including Solid 2)
+bun run deploy       # build everything and deploy the playground Worker
+```
 
-The playground lives in 'site/'. The library is in 'src/'. To build the Cloudflare Worker playground, run 'bun run deploy' after configuring your Cloudflare account.
+```
+src/              the library
+  RobotHead.tsx   the component
+  tv/             geometry, lighting, faces, motion and renderer
+site/             the playground (Vite + Cloudflare Worker)
+```
 
-Lint uses the vendored rules in 'tools/oxlint/anti-slop/' plus Oxlint's native accumulating-spread and ESLint classic cyclomatic-complexity rules. Geometric shape names are explicitly allowed by the shape-name rule because shape is a real domain concept here; unrelated `*Shape` names remain forbidden. Legitimate TypeScript type predicates may use `typeof` to distinguish Solid's callback and style unions. Browser screenshots and pixel observations are saved under 'test-results/'.
+Release and npm publishing instructions are in [docs/releases.md](docs/releases.md).
 
-For now, the playground loads Open Runde fonts from the upstream repository because the source font binaries could not be transferred through the available GitHub connection. The library itself does not require fonts or external assets.
+## License
 
-## Attribution and licensing
+[MIT](LICENSE) © [Fayaz Ahmed](https://x.com/fayazara). This is a Solid port by [jhomra21](https://github.com/jhomra21) of [Fayaz Ahmed's React library](https://github.com/fayazara/robot-heads).
 
-Original design and Canvas renderer by [Fayaz Ahmed](https://github.com/fayazara/robot-heads), copyright © 2026 Fayaz Ahmed, licensed MIT. The original MIT license is preserved in [LICENSE](./LICENSE). Open Runde by Laurids Kern, licensed SIL OFL 1.1; see 'site/public/fonts/OFL.txt'. The Solid port is also distributed under MIT.
+The playground uses Open Runde by Laurids Kern under the SIL Open Font License 1.1 (`site/public/fonts/OFL.txt`). The font is not part of the npm package.

package/dist/solid2.d.ts

@@ -0,0 +1,40 @@
+import type { JSX } from '@solidjs/web';
+
+export type RobotHeadState =
+  | 'idle'
+  | 'thinking'
+  | 'searching'
+  | 'listening'
+  | 'speaking'
+  | 'working'
+  | 'happy'
+  | 'error'
+  | 'sleeping';
+
+export declare const robotHeadStates: RobotHeadState[];
+
+export type RobotHeadModel = 'tv';
+
+export type RobotHeadShape = 'rectangle' | 'square' | 'circle' | 'hexagon';
+
+export declare const robotHeadShapes: RobotHeadShape[];
+
+export interface RobotHeadProps extends Omit<JSX.CanvasHTMLAttributes<HTMLCanvasElement>, 'color'> {
+  model?: RobotHeadModel;
+  shape?: RobotHeadShape;
+  state?: RobotHeadState;
+  size?: number;
+  color?: string;
+  trimColor?: string;
+  screenColor?: string;
+  speed?: number;
+  paused?: boolean;
+  interactive?: boolean;
+  floorShadow?: boolean;
+  /** 0–1. Offsets blinks and glances across a row of heads. */
+  seed?: number;
+  /** React-compatible className alias; Solid's class prop also works. */
+  className?: string;
+}
+
+export declare function RobotHead(props: RobotHeadProps): JSX.Element;