route-graphics 1.8.3 → 1.9.0

package/README.md

@@ -85,12 +85,122 @@ For complete usage details, go to:
 - [Events & Render Complete](http://route-graphics.routevn.com/docs/guides/events-render-complete/)
 - [Custom Plugins](http://route-graphics.routevn.com/docs/guides/custom-plugins/)
 
+## PNG Render CLI Scaffold
+
+This repo now includes a repo-local CLI scaffold that renders YAML into a PNG by:
+
+1. reading YAML in Node,
+2. launching headless Chromium through Playwright,
+3. rendering with the bundled `dist/RouteGraphics.js`, and
+4. exporting pixels with `app.extractBase64()`.
+
+It is intentionally scaffolded as a repo workflow first, not a published package entrypoint yet.
+
+Full CLI reference: [`docs/png-render-cli.md`](./docs/png-render-cli.md)
+
+```bash
+# one-time browser install if Chromium is not already available
+npx playwright install chromium
+
+# render a YAML file to PNG
+bun run render:png -- ./examples/hello.yaml -o ./out/hello.png
+```
+
+Supported top-level YAML shapes:
+
+- A single state object
+- An array of states
+- A wrapper object with `width`, `height`, `backgroundColor`, optional `assets`, and either `state` or `states`
+- Multiple YAML documents separated by `---` (treated as a state list)
+
+Minimal example:
+
+```yaml
+width: 1280
+height: 720
+backgroundColor: "#101820"
+elements:
+  - id: title
+    type: text
+    x: 80
+    y: 80
+    content: "Hello PNG"
+    textStyle:
+      fill: "#ffffff"
+      fontSize: 48
+  - id: bar
+    type: rect
+    x: 80
+    y: 160
+    width: 320
+    height: 24
+    fill: "#4fd1c5"
+```
+
+Asset handling:
+
+- Asset-bearing render-state fields such as `src`, `thumbSrc`, `barSrc`, `inactiveBarSrc`, and `soundSrc` must reference top-level `assets` aliases.
+- Direct file paths and URLs are allowed inside top-level `assets` values.
+- Direct asset references inside `elements`, `audio`, or nested interaction config are rejected.
+
+Example with asset aliases:
+
+```yaml
+width: 1280
+height: 720
+assets:
+  hero: ./assets/hero.png
+  uiFont:
+    path: ./assets/fonts/NotoSans-Regular.ttf
+    type: font/ttf
+elements:
+  - id: title
+    type: text
+    x: 60
+    y: 60
+    content: "Alias-backed render"
+    textStyle:
+      fill: "#ffffff"
+      fontSize: 42
+      fontFamily: uiFont
+  - id: avatar
+    type: sprite
+    x: 60
+    y: 140
+    width: 128
+    height: 128
+    src: hero
+```
+
+Invalid example:
+
+```yaml
+elements:
+  - id: avatar
+    type: sprite
+    x: 60
+    y: 140
+    width: 128
+    height: 128
+    src: ./assets/hero.png # rejected by the CLI
+```
+
+Useful flags:
+
+- `--state <index>` selects a state from an array or multi-document YAML file.
+- `--time <ms>` samples animations at a specific manual timeline position.
+- `--wait-for-render-complete` waits for a `renderComplete` event before capture.
+- `--browser-executable <path>` uses a system Chrome/Chromium instead of Playwright's managed browser.
+
 ## Development
 
 ```bash
 # Run tests
 bun run test
 
+# Render a YAML file into a PNG
+bun run render:png -- ./examples/hello.yaml -o ./out/hello.png
+
 # Ensure VT assets are real binaries, not Git LFS pointer files
 git lfs pull
 git lfs checkout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "route-graphics",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "A 2D graphics rendering interface that takes JSON input and renders pixels using PixiJS",
   "main": "dist/RouteGraphics.js",
   "type": "module",
@@ -30,6 +30,7 @@
     "lint:fix": "bunx prettier --write src",
     "prepare": "husky",
     "build": "bunx esbuild ./src/index.js --bundle --minify --format=esm --outfile=./dist/RouteGraphics.js && bunx esbuild ./src/index.js --bundle --sourcemap --format=esm --outfile=./vt/static/RouteGraphics.js && mkdir -p ./.rettangoli/vt/_site && cp ./vt/static/RouteGraphics.js ./.rettangoli/vt/_site/RouteGraphics.js && cp ./vt/static/RouteGraphics.js.map ./.rettangoli/vt/_site/RouteGraphics.js.map",
+    "render:png": "bun run build && node ./bin/route-graphics-render.js",
     "vt:docker:pull": "docker pull docker.io/han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.1.0",
     "vt:generate": "bun run build && docker run --rm --user $(id -u):$(id -g) -e RTGL_VT_DEBUG=true -v \"$PWD:/workspace\" docker.io/han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.1.0 rtgl vt generate --wait-event vt:ready",
     "vt:screenshot": "bun run build && docker run --rm --user $(id -u):$(id -g) -e RTGL_VT_DEBUG=true -e RTGL_VT_CONCURRENCY=${RTGL_VT_CONCURRENCY:-8} -v \"$PWD:/workspace\" docker.io/han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.1.0 rtgl vt screenshot --wait-event vt:ready --concurrency ${RTGL_VT_CONCURRENCY:-8}",