# bfce

> A circle, and two circles inside it that follow the pointer. An animated face
> for web UIs — 30 expressions, 9 one-shot reactions, spring-driven. The head is
> a sphere, so the eyes travel a curved path and foreshorten toward the rim.
> 3.7 kB gzipped, no dependencies, MIT.

From npm:

    npm i @bwnd/bfce

    import { createFace } from '@bwnd/bfce'        // no React needed
    import { Face } from '@bwnd/bfce/react'        // optional peer dep

Or with no install and no build step at all:

    import { createFace } from 'https://bfce.bwnd.app/face.js'
    createFace(document.querySelector('#bot'), { expression: 'curious' })

Either way styles inject themselves — there is no stylesheet to link. The host
element needs an explicit width and height, or nothing renders.

## Render API — a face without running anything

If you want a picture of a face rather than a live one, ask for it. No key, no
signup:

    curl -X POST https://bfce.bwnd.app/api/render \
      -H 'content-type: application/json' \
      -d '{"expression":"joy","ink":"#b6ff3d","format":"jpg"}'

Returns JSON: a `url` to a 1080×1080 file, and `snippet` — the embed code for
that same face, live. `format` is one of:

- `jpg` — a still card, captioned bfce.bwnd.app. Good for an avatar or a post.
- `mp4` — a 1–6 second clip (`seconds`), H.264. Uploads straight to TikTok,
  Instagram or X. By default the face pops in, sweeps its gaze, blinks, winks and
  bounces; pass a `script` to choreograph it instead — a list of cues like
  `{"at": 1.2, "expression": "surprised", "react": "pop"}`, each with `at` plus
  any of `expression`, `react` and `look`. Moods cross-fade, so space them ~0.5s.
- `snippet` — the embed code only. Nothing is rendered, so it returns instantly.

Colours are `#rrggbb`: `skin` is the head *and* the backdrop behind it, `ink` the
eyes and mouth, `ring` the hairline. `mouth` and `pupils` are booleans. An
unknown expression is rejected with the list of valid ones, so you can retry.

It is the real library that answers — the endpoint drives it in a headless
browser, so what you get back is what a person gets from the playground.

One gotcha: the edge in front of this domain 403s the `Python-urllib` default
User-Agent, on these docs as well as the API. Send any other agent string (or use
requests) and it is fine. Retrying will not help.

## MCP

Inside bwnd, the same four actions are MCP tools on this incubator's own server
(`incu-sbx:8000/mcp` on the mesh — not exposed publicly; use the HTTP API above
from outside): `list_face_moods`, `render_face`, `record_face`, `face_embed_code`.

## Docs

- [SKILL.md](https://bfce.bwnd.app/SKILL.md): full agent-facing usage — API, options, expressions, reactions, theming, and the mistakes worth avoiding
- [expressions.json](https://bfce.bwnd.app/expressions.json): machine-readable manifest — every expression and reaction with its parameters, generated from source on each build
- [Library bundle](https://bfce.bwnd.app/face.js): ESM, styles injected at runtime
- [Stylesheet](https://bfce.bwnd.app/face.css): only needed if importing the raw source instead of the bundle

## Source

- [GitHub](https://github.com/bwndapp/bfce): source, README, runnable demo
- [CDN mirror](https://cdn.jsdelivr.net/gh/bwndapp/bfce@main/dist/face.js): jsDelivr, pinnable by tag