nanoframes 0.1.0__tar.gz

nanoframes-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# LoopX / local goal state (private evidence — never commit)
+.loopx/
+.codex/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+
+# render outputs
+out/
+build/
+*.mp4
+.nanoframes-cache/
+
+# macOS
+.DS_Store
+**/.DS_Store

nanoframes-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 nanoframes contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

nanoframes-0.1.0/Makefile

@@ -0,0 +1,37 @@
+SHELL := /bin/bash
+PY ?= python3
+
+.PHONY: install test pytest lint build sdist upload clean
+
+install:
+	$(PY) -m pip install -e .[dev]
+
+test:
+	$(PY) -m pytest -q
+
+pytest:
+	$(PY) -m pytest -q
+
+lint:
+	ruff check nanoframes tests
+
+# Local build: sdist + wheel into dist/ (hatchling; wheel embeds docs/skills/font).
+build:
+	$(PY) -m pip install --upgrade build
+	$(PY) -m build .
+
+# PyPI artifact: a fresh sdist only (mirrors ../redisk; pip builds the wheel
+# from it on install). Dry-run check:  twine check dist/*.tar.gz
+sdist:
+	rm -rf dist
+	python3 -m pipx run build --sdist
+
+# Publish the sdist to PyPI (needs twine + ~/.pypirc credentials).
+# Test index first:  twine upload dist/nanoframes-*.tar.gz -r testpypi
+upload: sdist
+	twine upload dist/nanoframes-*.tar.gz -r pypi
+
+clean:
+	rm -rf build dist *.egg-info nanoframes.egg-info
+	find . -name __pycache__ -type d -prune -exec rm -rf {} +
+	rm -rf out

nanoframes-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: nanoframes
+Version: 0.1.0
+Summary: SVG-first, browserless, deterministic frame rendering built on ThorVG. Offline hyperframes-style animated compositions for fast AI-agent iteration.
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: thorvg-python
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nanoframes
+
+**SVG-first, browserless, deterministic frame rendering on ThorVG.**
+
+nanoframes is an offline counterpart to [hyperframes](https://github.com/heygen-com/hyperframes): the same
+idea — *write a frame, render a video, built for agents* — but without a browser. Compositions are
+authored as **SVG** documents plus a small declarative animation timeline, and every frame is
+rasterized deterministically by **ThorVG** (`thorvg-python`) to PNG, then muxed to MP4 with FFmpeg.
+
+Because nothing depends on a browser, an AI agent can render a frame or a whole clip locally in
+milliseconds and iterate fast: `check` → `preview` → `render`.
+
+## Status
+
+**v1 complete.** Full offline pipeline works end-to-end: `init` → `check` →
+`render`/`preview` → `video`. SVG compositions + declarative keyframe timeline are
+rendered deterministically by ThorVG; MP4 export via ffmpeg; visual snapshots guard
+regressions. Text auto-layout (measured chips, wrap, curve, fit) + a bundled
+**monospace CJK** font (`Sarasa Mono SC`, ligatures stripped) for solid Chinese.
+
+## Layout
+
+```
+docs/             architecture + composition contract
+examples/         `.nf.svg` compositions
+skills/nanoframes/ SKILL.md — the agent production loop
+nanoframes/       package (model, parser, timeline, bake, render, lint, cli, video)
+tests/            unit + render + snapshot + CLI tests
+```
+
+## Docs
+
+- [Architecture](docs/architecture.md) — why SVG + ThorVG, the pipeline, scope decisions.
+- [Composition](docs/composition.md) — the `.nf.svg` contract (timing attributes + animation timeline).
+- [Text capabilities](docs/text-capabilities.md) — measured chips/wrap/curve/fit, bundled CJK font, `text_handler` escape hatch.
+
+`docs/` and `skills/` also ship inside the pip wheel (`nanoframes/docs`,
+`nanoframes/skills`); running `nanoframes` with no arguments prints where the
+docs and the agent skill live — repo checkout or installed package alike.

nanoframes-0.1.0/README.md

@@ -0,0 +1,39 @@
+# nanoframes
+
+**SVG-first, browserless, deterministic frame rendering on ThorVG.**
+
+nanoframes is an offline counterpart to [hyperframes](https://github.com/heygen-com/hyperframes): the same
+idea — *write a frame, render a video, built for agents* — but without a browser. Compositions are
+authored as **SVG** documents plus a small declarative animation timeline, and every frame is
+rasterized deterministically by **ThorVG** (`thorvg-python`) to PNG, then muxed to MP4 with FFmpeg.
+
+Because nothing depends on a browser, an AI agent can render a frame or a whole clip locally in
+milliseconds and iterate fast: `check` → `preview` → `render`.
+
+## Status
+
+**v1 complete.** Full offline pipeline works end-to-end: `init` → `check` →
+`render`/`preview` → `video`. SVG compositions + declarative keyframe timeline are
+rendered deterministically by ThorVG; MP4 export via ffmpeg; visual snapshots guard
+regressions. Text auto-layout (measured chips, wrap, curve, fit) + a bundled
+**monospace CJK** font (`Sarasa Mono SC`, ligatures stripped) for solid Chinese.
+
+## Layout
+
+```
+docs/             architecture + composition contract
+examples/         `.nf.svg` compositions
+skills/nanoframes/ SKILL.md — the agent production loop
+nanoframes/       package (model, parser, timeline, bake, render, lint, cli, video)
+tests/            unit + render + snapshot + CLI tests
+```
+
+## Docs
+
+- [Architecture](docs/architecture.md) — why SVG + ThorVG, the pipeline, scope decisions.
+- [Composition](docs/composition.md) — the `.nf.svg` contract (timing attributes + animation timeline).
+- [Text capabilities](docs/text-capabilities.md) — measured chips/wrap/curve/fit, bundled CJK font, `text_handler` escape hatch.
+
+`docs/` and `skills/` also ship inside the pip wheel (`nanoframes/docs`,
+`nanoframes/skills`); running `nanoframes` with no arguments prints where the
+docs and the agent skill live — repo checkout or installed package alike.

nanoframes-0.1.0/docs/architecture.md

@@ -0,0 +1,121 @@
+# nanoframes Architecture
+
+## North star
+
+**Write a frame as SVG. Render frames, and a video, without a browser.** Built so an AI coding
+agent can iterate fast and deterministically on every local change: `check` → `preview` →
+`render` in milliseconds, no browser, no network.
+
+## Why SVG + ThorVG (instead of HTML + Chromium)
+
+Hyperframes uses HTML/CSS + a browser engine + GSAP, and captures frames through Chromium to a
+seekable MP4. That is powerful but heavy and non-deterministic in some dimensions:
+
+- The browser is a huge, opaque surface; agents can't inspect it locally without it.
+- HTML/CSS layout is complex; matching pixel output requires capture round-trips.
+
+nanoframes chooses the minimal deterministic subset that still covers typical motion-graphic
+output:
+
+- **Authoring surface = SVG**, which is (a) a first-class native output of language models, (b)
+  declarative, (c) directly rasterizable.
+- **Rendering engine = ThorVG** (`thorvg-python`), an embedded SVG rasterizer (conforms to
+  *SVG Tiny 1.2* — see `../thorvg.wiki/SVG-Support.md`). No browser, no DOM, pure software raster
+  → Pillow → PNG/MP4. Deterministic and trivially iterable.
+- The `frames-pack` toolchain already demonstrated offline ThorVG→PNG rendering; we reuse that
+  pattern (thorvg-python + Pillow), and we reuse hyperframes' *timing/intent* ideas (clip
+  in/out, tracks, seek) but <b>flatten animation to a declarative timeline</b> instead of GSAP.
+
+## Pipeline
+
+```
+composition.nf.svg  (SVG scene + embedded <script> JSON animation timeline)
+        │  parse (stdlib xml) → nanoframes.Composition
+        v
+ seek(t): evaluate animation timeline → per-frame property values
+        │
+        v
+ bake(t): merge visibility + animated props into a frame-specific SVG
+        │
+        v
+ thorvg render → Pillow PNG   (single frame, or batch)
+        │
+        v
+ ffmpeg → deterministic MP4   (P1)
+```
+
+Every stage is pure and deterministic given `(composition, t, fps)`. No web surface anywhere.
+
+## Composition model
+
+A composition is one `.nf.svg` file (valid SVG) carrying:
+
+- root `<svg>` canvas metadata: `data-width`, `data-height`, `data-fps`, `data-duration`
+  (`data-composition-id` optional).
+- per-element presence: `data-start` + `data-duration` (absolute seconds, clip in/out) and
+  optional `data-fade` (fade-in/out seconds). Elements outside their window are not rasterized.
+- an embedded `<script type="application/nanoframes+json">` holding the **animation timeline**:
+  ordered animations, each targeting elements by CSS selector (`#id`, `.class`) with keyframe
+  lists over time.
+
+Detailed contract: `docs/composition.md`.
+
+## Animation timeline (declarative, seekable)
+
+Hyperframes uses GSAP timelines loaded into the browser. We replace JS with a deterministic
+keyframe JSON timeline evaluated by `seek(t)`:
+
+- supported animated properties: `opacity`, `transform` (`translate`, `scale`, `rotate`),
+  `fill`, `stroke` (interpolated color).
+- keyframes are `{ "t": <sec>, <props>: value }`; between keyframes we interpolate linearly,
+  optionally eased (`linear`, `ease-in`, `ease-out`, `ease-in-out`).
+- clip + fade is folded into effective opacity so visibility, fade and animation compose into a
+  single `opacity` / `transform` baked value per frame.
+
+This is deliberately *small*. Full GSAP/CSS expressiveness is out of scope; the payoff is fast,
+deterministic, inspectable motion.
+
+## Rendering (thorvg-python)
+
+- `bake(t)` writes a temp standalone SVG (strips the `<script>`, applies the computed attrs).
+- a renderer creates `thorvg_python.Engine` + `SwCanvas`, sets the target size, loads the SVG as
+  a `Picture`, `add → update → draw → sync`, and reads a Pillow image via `get_pillow()`.
+- Energy is per-frame and isolated, so batch rendering stays deterministic and trivially
+  parallelizable later.
+
+## Scope decisions (what we drop from hyperframes)
+
+| Hyperframes scope              | nanoframes |
+|--------------------------------|------------|
+| HTML/CSS + browser capture     | SVG + ThorVG software raster |
+| GSAP / Lottie / Three.js / anime | declarative keyframe timeline (v1) |
+| inline `<video>` playback      | static `<image>` only (v1); no video-in-scene |
+| full audio mixing (buses, ducking) | optional FFmpeg audio mux passthrough (deferred P2) |
+| hosted / Lambda / GCP rendering | local offline render only |
+| Figma import, Remotion port     | out of scope |
+| 20 authoring workflows          | a few core example templates |
+| frame.md / design.md system     | composition doc + lint (v1) |
+| binary TreePack compressed pack | deferred optional binary cache (P2) |
+
+**Kept:** deterministic seekable frames, clip timing, `check`/`preview`/`render` agent loop,
+MP4 export, and an agent-facing skill.
+
+## Non-goals
+
+- No browser, no network, no live media.
+- No JS runtime / no GSAP semantics.
+- No production audio mastering; no cloud rendering.
+
+## Milestones
+
+- **v1 (done, 2026-09)** composition model + parser, timeline evaluator, ThorVG
+  frame renderer, CLI (`init`/`check`/`render`/`preview`/`video`/`measure`/
+  `fonts`/`walkthrough`), MP4 export + audio mux, fast re-render cache,
+  renderer-exact text story (chips/wrap/curve/fit), bundled mono CJK font,
+  `text_handler` escape hatch, example compositions + visual snapshot suite,
+  agent skill (`skills/nanoframes/SKILL.md`).
+- **Deferred** optional binary tree-pack cache; CLI bridge for `text_handler`
+  (it is a library-API feature by design); in-scene video.
+
+`docs/` and `skills/` ship inside the pip wheel as `nanoframes/docs` and
+`nanoframes/skills`; `nanoframes` (no args) prints their installed locations.

nanoframes-0.1.0/docs/composition.md

@@ -0,0 +1,154 @@
+# nanoframes composition contract
+
+A composition is a single **`.nf.svg`** file: valid SVG + an embedded animation
+timeline. Rendering is deterministic: the same `(composition, t, fps)` always
+yields the same frame.
+
+## Canvas (root `<svg>`)
+
+| attribute | default | meaning |
+|---|---|---|
+| `data-width` / `data-height` | — (required) | output canvas, pixels |
+| `data-fps` | `30` | frames per second |
+| `data-duration` | `1.0` | total duration, seconds |
+| `data-composition-id` | — | name used for frame/video output |
+
+`width`/`height` are accepted as fallbacks for `data-width`/`data-height`.
+
+## Element presence (clip in/out)
+
+| attribute | default | meaning |
+|---|---|---|
+| `data-start` | `0` | absolute start time, seconds |
+| `data-duration` | = composition duration | how long the clip is visible |
+| `data-fade` | `0` | fade-in seconds at clip start (fade-out mirrors at clip end) |
+
+Outside its `[start, start+duration]` window an element is `display:none` (not
+rasterized). Fade and clip fold into the effective opacity.
+
+## Animation timeline
+
+Embedded as `<script type="application/nanoframes+json"><![CDATA[ … ]]></script>`.
+The JSON has one `animations` array; each animation has a CSS `target` (selector
+`#id`, `.class`, or tag) and ordered `keyframes`. Per keyframe: `t` (seconds),
+any animated properties, and an optional `ease` (`linear` | `ease-in` |
+`ease-out` | `ease-in-out`, default `linear`).
+
+```json
+{
+  "animations": [
+    {
+      "target": "#title",
+      "keyframes": [
+        { "t": 0.0, "opacity": 0.0, "transform": { "translate": [0, 30] } },
+        { "t": 0.7, "opacity": 1.0, "transform": { "translate": [0, 0] }, "ease": "ease-out" }
+      ]
+    }
+  ]
+}
+```
+
+Between keyframes, numeric properties interpolate **linearly** (after easing);
+colors interpolate RGB; anything non-interpolable holds the earlier keyframe.
+
+### Supported properties
+
+| property | value | interpolation |
+|---|---|---|
+| `opacity` | float `0..1` | linear/eased |
+| `transform` | `{"translate":[x,y], "scale":[sx,sy], "rotate":deg}` | elementwise |
+| `fill` / `stroke` | `#RRGGBB` (or `#RRGGBBAA`) | RGB lerp |
+
+Bake emits `transform="translate(x,y) rotate(d) scale(sx,sy)"` (translate ·
+rotate · scale order).
+
+## Media
+
+- **Raster images**: `<image href="assets/foo.png" />` (relative paths are
+  dereferenced against the composition directory).
+- **Fonts**: text renders with a system font loaded automatically (Arial /
+  DejaVuSans fallback). Declare `font-family`, `font-size`, `font-weight` as in SVG.
+
+## Supported SVG surface
+
+ThorVG rasterizes the **SVG Tiny 1.2** subset — see
+`../thorvg.wiki/SVG-Support.md`. Shapes (`rect`, `circle`, `ellipse`, `path`,
+`polygon`, `polyline`, `line`), `<image>`, gradients, `<text>`/`<tspan>`,
+`<g>`, `clipPath`/`mask`, and transforms are supported. Layout/CSS keep their
+SVG meaning but only within that subset.
+
+### Known ThorVG behaviors
+
+- **Keep transformed elements on-canvas.** An element whose transformed extent
+  leaves the canvas (especially rotated, partially off-screen) is clipped
+  coarsely: ThorVG paints **black** over the off-screen extent. Animate within
+  the frame (fade/scale/grow in place, translate inside bounds) rather than
+  sliding in from outside the canvas.
+- **Text needs a loaded font.** ThorVG only rasterizes `<text>` after a font is
+  registered (`Text.font_load`, done automatically per engine). Renders are
+  therefore limited to fonts present on the host unless you supply one.
+
+## Text auto-layout (`data-*` on `<text>`)
+
+Measured by the same ThorVG SVG loader that rasterizes the frame, so background
+chips / wrapped lines / curved text always line up with the rendered glyphs.
+
+| attr | meaning | default |
+|---|---|---|
+| `data-bg="COLOR"` | auto-sized rounded background chip behind the text | — |
+| `data-bg-rx` | chip corner radius | `10` |
+| `data-bg-pad-x` / `data-bg-pad-y` | ink-to-chip padding | `12` / `8` |
+| `data-wrap="WIDTH"` | wrap text into stacked `<text>` lines fitting `WIDTH` px | — |
+| `data-fit="WIDTH"` | auto-shrink font-size (floor `data-fit-min`) so the text fits | `data-fit-min=9` |
+| `data-curve-d="PATH"` | place each char along a sampled SVG path `d` | — |
+| `data-curve-circle="cx,cy,r[,startDeg]"` | place each char along a circle | — |
+
+When auto-layout is used without a `Measurer` (e.g. a bare `bake_svg` call) it
+is a no-op, so plain compositions bake exactly as before. See
+`docs/text-capabilities.md` for the full audit and caveats.
+
+## External raster text (`text_handler`)
+
+Text that ThorVG fonts cannot cover — LaTeX math, an exotic brand face, emoji —
+is rendered *outside* the framework by a library callback. Pass
+`text_handler=callable` to `bake_svg` / `render_frame`; every
+`<text data-raster="kind">` is offered to it as a `TextRequest` (content, kind,
+style, fill, raw attrs). The handler returns **PNG bytes** and the node is
+replaced by an `<image>` at an anchor-driven bbox, or `None` to keep the normal
+ThorVG font path (auto-layout `data-*` still applies in that case).
+
+| attr | meaning | default |
+|---|---|---|
+| `data-raster="KIND"` | opt in to the handler; `KIND` is passed through for dispatch | — |
+| `data-anchor` | which bbox corner/edge sits at `(x, y)`: `top-*` / `middle-*` / `bottom-*` × `-left` / `-center` / `-right` | `center` |
+| `data-width` / `data-height` | target box px; PNG is uniformly contained (no distortion) | natural size |
+| `data-yaw` | degrees clockwise, rotating the image around the anchor point | `0` |
+
+Contract: `x`/`y` mean the anchor point (not an SVG baseline) while rasterized;
+bytes must decode as PNG (anything else raises at bake time); a handler should
+be a deterministic pure function of the request and is invoked once per node
+per bake — `render_frame` bypasses `FrameCache` whenever a handler is supplied
+(its key knows nothing about the handler); CLI rendering has no handler and
+falls back to fonts. See `nanoframes/rastertext.py` and
+`tests/test_rastertext.py` for the reference contract.
+
+## Fonts
+
+A bundled **monospace CJK** face ships with nanoframes
+(`fonts/SarasaMonoSC-Regular-noliga.ttf`, Sarasa Mono SC, ligature feature
+stripped). Use `font-family="Sarasa Mono SC"` for deterministic-width Chinese
+labels (each Han char = `font-size` px wide). Query it with
+`nanoframes fonts list`; add other faces with `nanoframes fonts add <path>`.
+
+## CLI examples
+
+```bash
+nanoframes init my-video            # scaffold a .nf.svg
+nanoframes check my-video.nf.svg    # lint (exit 1 on errors)
+nanoframes measure my-video.nf.svg  # report renderer-exact text widths
+nanoframes render my-video.nf.svg --t 2.0          # single frame PNG
+nanoframes preview my-video.nf.svg --t 2.0         # render + open
+nanoframes render my-video.nf.svg -o frames        # full batch
+nanoframes video my-video.nf.svg -o out.mp4        # MP4 via ffmpeg
+nanoframes video my-video.nf.svg -o out.mp4 --audio track.mp3   # + audio mux
+```

nanoframes-0.1.0/docs/text-capabilities.md

@@ -0,0 +1,112 @@
+# Text capabilities: audit, findings, and the nanoframes answer
+
+This doc is the result of a full audit of our text story against the reference
+projects — **hyperframes** and (its ancestor) **remotion** — plus the actual
+ThorVG runtime we render with. It answers three questions with evidence and
+specifies the features we added (and how to extend further).
+
+## The three questions
+
+### 1. Can we measure a text bounding box exactly? — Yes, and it must be renderer-exact
+
+Two ways, and one of them is misleading:
+
+| approach | exact? | notes |
+|---|---|---|
+| **rasterize + read ink** (what we use) | ✅ exact by construction | Reuses the *same* SVG loader, so the measured box always matches the final render. Size = tiny isolated `<text>` raster; cached by `(text, family, weight, size)`. |
+| ThorVG `Text.get_aabb` / `get_metrics` | ❌ no | Two gotchas found empirically: (a) `set_size` is in **points** (px = size × `96/72`, so you must pass `px × 0.75`); (b) in this `thorvg-python 1.1.1` build a hand-built `Text` **reports metrics but does not rasterize**, and per-glyph widths are unreliable — a lone `i` measured `0.86 px`. The *newer* source `../thorvg-python` adds `get_glyph_metrics` + `line_count`; upgrading would give fast per-glyph advances. |
+
+Because the background-misalignment bug you hit is exactly the "my vet habit maths the text differently than my renderer" failure, the invariant we chose is: **measure by rendering.** Same fonts, same loader, same result. Add a `Measurer` and auto-size from ink — it cannot drift.
+
+### 2. Multiline text? — Not natively, so we build it
+
+Empirically, in the installed ThorVG SVG loader neither route works:
+
+- `<tspan>` with `x`/`y`/`dy` **renders all spans on the same baseline** (confirmed: two tspans at `y=100`/`dy=40` both ink a single 20 px-tall line).
+- a literal `&#10;` newline is **collapsed into horizontal advance** (two "lines" render side by side, one line tall).
+
+So multiline must be baked by us. We measure each candidate line and emit **separate `<text>` per line** (each line is its own paint, which ThorVG positions reliably). Interface: `data-wrap="<maxWidth>"`.
+
+### 3. Text along a shape / curve? — No `<textPath>`, so we sample the curve ourselves
+
+ThorVG's SVG loader has **no `<textPath>`** (confirmed: it loads with error code 0 but rasterizes nothing — an 8 px sliver). We implement the standard offline approach remotion exposes in `@remotion/paths` (`getPointAtLength` / `getTangentAtLength`): flatten the path, build an arc-length table, place each character at `point(s)` rotated to `tangent(s)`. Uses per-character ink advances for spacing. Mirrors remotion's `warp-path`/`paths` suite but as pure Python.
+
+## Features we added (v1 of the text story)
+
+All three are bake-time passes over the already-animated tree, driven by a
+renderer-exact `Measurer` (`nanoframes/measure.py`, `curve.py`, `textflow.py`):
+
+- **Measured background chip** — `<text data-bg="#3b5998" data-bg-pad-x="10" data-bg-pad-y="6" data-bg-rx="12">行人入侵</text>`: bake injects a rounded `<rect>` sized to the ink + padding. Padding/radius optional.
+- **Auto-wrap paragraph** — `<text data-wrap="300">…</text>` (optionally with `data-bg` for a block chip): bake splits into stacked lines that fit the width.
+- **Along-curve text** — `<text data-curve-d="M 90 300 C 200 190 420 190 560 300">DRIVE SAFE</text>` or `<text data-curve-circle="cx,cy,r[,startDeg]">…</text>`: bake emits rotated per-character `<text>` elements.
+- **`nanoframes measure <comp>`** — prints each text's renderer-exact width, so an author can sanity-check widths before trusting a layout.
+
+Consistency invariant: measurement uses the same font list, loader, and raster as the final frame. If auto-layout runs without a `Measurer` it is a no-op, so plain compositions bake exactly as before (all existing tests pass).
+
+## External text: the `text_handler` escape hatch (v1)
+
+Every finding above is about text **ThorVG draws with a loaded font**. When the
+text itself cannot live there — LaTeX math, a brand face that crashes this
+loader, emoji — the framework steps aside instead of growing a font engine:
+
+`<text data-raster="kind">` is offered to a library-supplied `text_handler`
+(`bake_svg` / `render_frame` parameter). The handler receives a `TextRequest`
+(content, kind, style, the live animated fill, raw attrs) and returns **PNG
+bytes**; bake replaces the node with an `<image>` at an anchor-driven bbox
+(`data-anchor` = one of 9 corner/edge/center anchors, default `center`;
+`data-width` / `data-height` contain the PNG without distortion; `data-yaw`
+rotates it around the anchor point). `None` keeps the normal ThorVG font
+path — chips, wrap, curve and fit all still apply there.
+
+Consistency note: this is the deliberate exception to "measure by rendering".
+A handled text's ink box is exact **by construction**: the PNG is literally
+what the frame draws, and its size comes from the bytes (Pillow), never from
+ThorVG metrics or fallback-font widths — so nothing can drift. The handler
+must be a deterministic pure function of the request (there is no framework
+memo; slow backends cache internally), and `render_frame` bypasses
+`FrameCache` while a handler is attached, since the cache key knows nothing
+about it. CLI rendering has no Python callback, so `data-raster` files fall
+back to fonts there — this is a library-API feature.
+
+Reference: `docs/composition.md` → External raster text,
+`nanoframes/rastertext.py`, `tests/test_rastertext.py` (a hello → 你好 dummy
+handler end-to-end), and the walkthrough showcase built from
+`examples/raster-title.nf.svg`.
+
+## What else is absorbable from hyperframes / remotion (ranked)
+
+| idea | source | nanoframes status |
+|---|---|---|
+| TeX / any custom typesetting — LaTeX math, exotic faces (manim compiles TeX to glyph-path SVG so its renderer never loads fonts) | manim | ✅ v1 as the `text_handler` hook above — outside ThorVG fonts entirely (library API; a CLI bridge is deferred). |
+| measure + auto-fit font size (`fitTextFontSize` shrink-down until it fits one line) | hyperframes `core/text`, remotion layout-utils | ⚠️ trivial to add on top of `Measurer` (binary/step search). |
+| word-level wrapping / caption timing | remotion `@remotion/captions`, layout-utils; hyperframes caption blocks | wrap ✅ done; caption-timing needs duration→width math, straightforward. |
+| shrinkwrap "rounded text box" | remotion `@remotion/rounded-text-box` | ✅ done as `data-bg`. |
+| per-char / per-word highlight, kinetic captions (weight-shift, gradient-fill, clip-wipe…) | hyperframes `docs/catalog/components/caption-*` | examples to port later; core is just `tspan`-replacements + fills we already bake. |
+| global transforms (e.g. `getBoundingRect` helpers, `@remotion/paths` point/tangent) | remotion paths | curve ✅; expose `getLength/point/tangent` as re-usable module (done in `curve.py`). |
+| variable-font axis animation | hyperframes `registry/components/variable-font-flex` | ⚠️ needs font with variation axes + a shaper; stretch. |
+| Google-fonts auto-download | hyperframes/remotion `fonts` | ⚠️ offline equivalent = a `fonts/` dir + exact-family registration; see font note below. |
+
+## Findings / caveats to keep in mind
+
+- **Font coverage decides width.** A CJK string measured under a font lacking the glyphs still "measures" (via fallback), so a chip sized for it matches the *fallback* glyphs — not a real Chinese face. Use a face that actually has the glyphs.
+- **ThorVG's loader font-family resolution is unreliable in this build.** A loaded font is not always used (`Arial Unicode MS` loads but never matches, so Chinese falls back to a dim built-in face). Empirically only some faces render solidly, and some *crash the process at teardown* when loaded (`AppleGothic` → segfault exit 139). `.ttc` collections can't be loaded at all.
+- **We therefore do NOT auto-register arbitrary discovered fonts in the renderer.** Instead: `nanoframes fonts list` shows CJK faces + exact family names; `nanoframes fonts add <path>` copies a font into `~/.local/share/nanoframes/fonts`. The **bundled** face below is registered explicitly (verified safe).
+- **Bundled CJK font: Sarasa Mono SC.** `nanoframes/fonts/SarasaMonoSC-Regular-noliga.ttf` (SIL OFL) is a **monospace** CJK face (Western = Iosevka-style, Han = Source Han Sans) — every Han char is exactly `font-size` px wide, and its `calt`/`dlig` ligature features are stripped. It is loaded **first** in the candidates list, so it is ThorVG's default: CJK text (and any font-family that doesn't resolve) renders through Sarasa, solid and monospaced. Explicit `font-family="Arial"` still resolves to Arial. Verified: load-safe, resolves, solid CJK, clean exit (unlike `AppleGothic`, which crashes this ThorVG build).
+- **等宽 for authoring.** Use `font-family="Sarasa Mono SC"` for deterministic-width Chinese labels (and `nanoframes measure` reports its exact widths).
+- **`set_size` points-vs-px trap.** If you use the raw `Text` metric API directly, px = size × `96/72`. We avoid it for exact work.
+- **Upgrade path.** The newer `thorvg-python` (see `../thorvg-python`) reworks text/font support and exposes `get_glyph_metrics` + `line_count`; upgrading is the enabling change for a truly bundled/等宽 CJK font.
+
+## Contract (extended)
+
+New optional `data-*` on `<text>`:
+
+| attr | meaning | default |
+|---|---|---|
+| `data-bg` | fill color of an auto-sized rounded background chip | — |
+| `data-bg-rx` | chip corner radius | 10 |
+| `data-bg-pad-x` / `data-bg-pad-y` | ink→chip padding | 12 / 8 |
+| `data-wrap` | max line width (px); wraps text into stacked `<text>` lines | — |
+| `data-curve-d` | SVG path `d` to lay characters along | — |
+| `data-curve-circle` | `cx,cy,r[,startDeg]` circular layout | — |
+
+Rendering a frame/video with these is unchanged: `nanoframes render|preview|video`.

nanoframes-0.1.0/examples/master-demo.nf.svg

@@ -0,0 +1,87 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+     data-width="960" data-height="540" data-fps="30" data-duration="6.0"
+     data-composition-id="master-demo">
+  <defs>
+    <linearGradient id="sky" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0a1128"/>
+      <stop offset="1" stop-color="#203a6b"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#5ef17c"/>
+      <stop offset="1" stop-color="#38bdf8"/>
+    </linearGradient>
+  </defs>
+
+  <rect id="bg" width="960" height="540" fill="url(#sky)"/>
+
+  <!-- floating image: translate + scale pulse -->
+  <image id="orb" class="float" href="assets/dot.png"
+         x="700" y="120" width="120" height="120"
+         data-start="0.2" data-duration="5.2"/>
+  <image id="orb2" class="float" href="assets/dot.png"
+         x="100" y="320" width="72" height="72" transform="scale(0.6)"
+         data-start="0.6" data-duration="4.8"/>
+
+  <!-- rotating gradient panel (translate + rotate) -->
+  <rect id="panel" x="0" y="0" width="200" height="120" rx="22" fill="url(#accent)"
+        opacity="0.9" data-start="0.0" data-duration="6.0"/>
+
+  <!-- title: fade + slide -->
+  <text id="title" x="60" y="120" font-family="Sarasa Mono SC" font-weight="700"
+        font-size="72" fill="#f4f7ff" data-start="0.0" data-duration="6.0">
+    nanoframes
+  </text>
+
+  <!-- subtitle with fade, gradient underline that grows -->
+  <rect id="rule" x="62" y="150" width="6" height="90" rx="3" fill="url(#accent)"
+        data-start="0.6" data-duration="5.0"/>
+  <text id="sub" x="90" y="205" font-family="Sarasa Mono SC" font-size="30"
+        fill="#b6c2d8" data-start="0.9" data-duration="4.8">
+    SVG renders MP4. No browser. Fast for agents.
+  </text>
+
+  <script type="application/nanoframes+json"><![CDATA[
+  {
+    "animations": [
+      {
+        "target": "#panel",
+        "keyframes": [
+          {"t": 0.0,  "opacity": 0.0, "transform": {"translate": [-260, 260], "rotate": 0}},
+          {"t": 1.0,  "opacity": 0.9, "transform": {"translate": [60, 380], "rotate": -14}, "ease": "ease-in-out"},
+          {"t": 4.0,  "opacity": 0.9, "transform": {"translate": [700, 320], "rotate": 12}, "ease": "ease-in-out"},
+          {"t": 5.5,  "opacity": 0.4, "transform": {"translate": [760, 420], "rotate": 0}}
+        ]
+      },
+      {
+        "target": "#title",
+        "keyframes": [
+          {"t": 0.0, "opacity": 0.0, "transform": {"translate": [0, 30]}},
+          {"t": 0.7, "opacity": 1.0, "transform": {"translate": [0, 0]}, "ease": "ease-out"}
+        ]
+      },
+      {
+        "target": ".float",
+        "keyframes": [
+          {"t": 0.2, "opacity": 0.0, "transform": {"translate": [0, 40], "scale": [0.5, 0.5]}},
+          {"t": 1.2, "opacity": 1.0, "transform": {"translate": [0, 0], "scale": [1.0, 1.0]}, "ease": "ease-out"},
+          {"t": 4.5, "opacity": 1.0, "transform": {"translate": [0, -30], "scale": [1.1, 1.1]}, "ease": "ease-in-out"}
+        ]
+      },
+      {
+        "target": "#rule",
+        "keyframes": [
+          {"t": 0.6, "opacity": 0.0, "transform": {"scale": [1.0, 0.05]}},
+          {"t": 1.2, "opacity": 1.0, "transform": {"scale": [1.0, 1.0]}, "ease": "ease-in-out"}
+        ]
+      },
+      {
+        "target": "#sub",
+        "keyframes": [
+          {"t": 0.9, "opacity": 0.0},
+          {"t": 1.4, "opacity": 1.0}
+        ]
+      }
+    ]
+  }
+  ]]></script>
+</svg>