# Tweens CSS engine setup

The CSS-only source release is **0.2.0, not yet published**. Published npm package
tweens-cli@0.1.1 and MCP Registry server io.github.sohei1l/tweens@0.1.1 predate CSS.
Use an authorized checkout or verified maintainer-supplied 0.2.0 tarball for this
workflow. The CLI is MIT licensed; that does not relicense the editor repository.

## Source setup

Use a supported Node.js 22 LTS release or newer. From the repository root:

```bash
npm ci
npm run build --workspace tweens-cli
npx playwright install chromium
mkdir -p work/animation
node packages/cli/dist/cli.mjs --version
node packages/cli/dist/cli.mjs tools
node packages/cli/dist/cli.mjs call get_css_capabilities '{}' --workspace work/animation
```

Alternatively install a verified package with
`npm install -g /absolute/path/to/package.tgz`. The executable is tweens.
Chromium is an explicit compilation/text/PNG prerequisite; file authoring does
not need it. TWEENS_CHROME can select a compatible installed Chrome.

## Connect an MCP client

Choose an existing dedicated workspace. Configure a stdio process (formats vary):

```json
{
  "mcpServers": {
    "tweens": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/checkout/packages/cli/dist/cli.mjs",
        "mcp", "--workspace", "/absolute/path/to/animation-workspace"
      ]
    }
  }
}
```

For an installed tarball use the absolute tweens executable as command and start
args at mcp. Restart the client, then read tools/list and get_css_capabilities.
No account, API key, public server URL or origin-trial token is needed.
A discovery page does not install anything or grant permission.

## Try it

> Use Tweens to build a short geometric CSS logo reveal in a new project.
> Duplicate states to preserve identities. Inspect start, midpoint and end PNGs,
> repair overlap or clipping, and deliver both the editable project and an offline
> HTML animation. Do not overwrite existing work or upload anything.

The 25-tool local MCP catalog supports shapes/text, transforms, simple styling,
group/ungroup, nested components, state duplication, duration/delay/easing,
atomic batches, validation, PNG preview and CSS/HTML export.
Read exact schemas; use the latest returned IDs/revisions. Serialize operations.
Use the app for advanced asset/path/mask authoring. create_inner_state returns a
child composition ID: pass it to get_editor_state and subsequent commands to
author inside it. apply_commands inherits one outer compositionId. Validation,
preview and export accept that same scope; omitted scope uses the saved root.
Nested edits/exports never change the root. Browser tools remain visible-scope only.

The HTML player has icon-only play/pause, a scrubber and time. The sidebar adds
expandable highlighted HTML with Copy. Looping is an authoring/export option.
Motion uses 60 Hz CSS samples and bounded SVG variants with exact root boundaries.
System fonts may vary. Unsupported media/effects are rejected, not silently
removed. GIF/MP4 are not offered by the new source release.

## Boundaries

- Simple filenames inside the workspace; no traversal, symlink projects,
  arbitrary code, shell, remote URLs or publication tools. Outputs must be new.
- Projects ≤20 MiB, 1000 nodes, 16 compositions, 100 states per composition,
  4096px dimensions and 120 seconds. Additional complexity limits apply.
- HTML ≤32 MiB at document dimensions; PNG ≤1280px/64 MiB. Isolated Chromium
  rendering stops after two minutes and blocks external requests.
- Revisions/atomic batches prevent stale/partial edits. Cancellation racing a
  completed write does not undo it: re-read. Keep backups; file history is not persistent.
- State deletion is separately confirmed. Start keeps its frame but empties its
  contents. No project-file deletion tool exists.
- Validation is technical, not visual approval. Inspect the HTML for motion and
  the .tweens file for human editing. Browser autosave is not disk synchronization.

## WebMCP is a separate route

Browser WebMCP operates on the open editor only when native browser and agent
support exist. It shares commands with local MCP but is not a public HTTP endpoint.
The localhost QA bridge is not proof of native availability. Publishing 0.2.0 to
npm and the Registry remains a separate release step.