geny-svgforge 0.1.0__tar.gz

geny_svgforge-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,49 @@
+name: publish
+
+# PyPI Trusted Publishing (OIDC). Configured publisher:
+#   project: geny-svgforge · owner: CocoRoF · repo: geny-svgforge
+#   workflow: workflow.yml · environment: pypi
+# A published GitHub Release (or manual dispatch) builds and uploads to PyPI.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Smoke-check metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

geny_svgforge-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+.uv/
+
+# caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# generated demo output
+examples/out.svg
+examples/out.png
+examples/probe.png
+
+# OS
+.DS_Store

geny_svgforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jang HaRyeom (CocoRoF)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geny_svgforge-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: geny-svgforge
+Version: 0.1.0
+Summary: AI가 좌표 대신 의미(spec)만 내면 결정론적 레이아웃으로 깨끗한 다이어그램 SVG를 만드는 라이브러리
+Project-URL: Homepage, https://github.com/CocoRoF/geny-svgforge
+Project-URL: Repository, https://github.com/CocoRoF/geny-svgforge
+Project-URL: Issues, https://github.com/CocoRoF/geny-svgforge/issues
+Author: Jang HaRyeom (CocoRoF)
+License: MIT
+License-File: LICENSE
+Keywords: ai,diagram,layout,llm,mcp,svg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: fonttools>=4.40
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: cairosvg>=2.7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: png
+Requires-Dist: cairosvg>=2.7; extra == 'png'
+Description-Content-Type: text/markdown
+
+# geny-svgforge
+
+**Give an AI a semantic spec instead of raw coordinates, and a deterministic layout engine produces a clean diagram SVG with zero overlaps or clipping.**
+
+When an LLM writes `<svg>` by hand, it can't reliably reason about text widths, box bounds, curve paths, or the viewBox — so elements overlap and captions get clipped. geny-svgforge inserts a layout layer between the AI and the SVG. The AI emits only a JSON **spec** (*"two rows of labeled tokens, posN labels, connect A's token 2 to B's token 3 with a curve, a side note, a caption"*) — no coordinates. The library measures text with real font metrics, sizes every box, routes connectors around obstacles, and fits the viewBox to the content. **Overlap and overflow become structurally impossible.**
+
+> Same lineage as edit2ppt (AI emits PPT structure, engine renders) and Contextifier (structure-preserving document parsing).
+
+---
+
+## Install
+
+```bash
+pip install geny-svgforge            # core (SVG)
+pip install 'geny-svgforge[png]'     # + PNG export (cairosvg)
+pip install 'geny-svgforge[mcp]'     # + MCP server
+```
+
+## Quickstart (Python)
+
+```python
+from geny_svgforge import render
+
+spec = {
+    "type": "token-sequence",
+    "title": "Absolute position changes, relative pattern remains",
+    "rows": [
+        {"label": "sentence A", "tokens": [
+            {"text": "나는", "pos": "pos 0"},
+            {"text": "오늘", "pos": "pos 1"},
+            {"text": "밥을", "pos": "pos 2", "id": "a2"},
+            {"text": "먹었다", "pos": "pos 3", "variant": "highlight"},
+        ]},
+        {"label": "sentence B", "tokens": [
+            {"text": "나는", "pos": "pos 0"},
+            {"text": "정말", "pos": "pos 1", "variant": "accent"},
+            {"text": "오늘", "pos": "pos 2"},
+            {"text": "밥을", "pos": "pos 3", "id": "b3"},
+            {"text": "먹었다", "pos": "pos 4", "variant": "highlight"},
+        ]},
+    ],
+    "connectors": [{"from": "a2", "to": "b3", "color": "accent"}],
+    "note": {"title": "What the model must learn",
+             "lines": ["Memorizing absolute positions is brittle to length changes.",
+                       "Relative distance and surrounding patterns are handled in attention."]},
+    "caption": "Same relative token relationship survives an absolute shift",
+}
+
+result = render(spec)        # portable SVG with the used glyphs embedded
+print(result.warnings)       # []  ← no overlap / no clipping (lint passed)
+open("out.svg", "w").write(result.svg)
+```
+
+## CLI
+
+```bash
+geny-svgforge render spec.json -o out.svg
+geny-svgforge render spec.json -o out.png      # PNG (requires [png])
+geny-svgforge validate spec.json               # validate before rendering
+geny-svgforge schema -o schema.json            # dump the JSON Schema
+```
+
+## MCP server
+
+geny-svgforge ships an [MCP](https://modelcontextprotocol.io) server over **stdio** so any MCP-compatible agent can request diagrams. After `pip install 'geny-svgforge[mcp]'` the server is launched with:
+
+```bash
+geny-svgforge-mcp                 # console script
+# or
+python -m geny_svgforge.mcp_server
+```
+
+### Tools exposed
+
+| Tool | Input | Returns |
+|---|---|---|
+| `get_diagram_schema` | – | JSON Schema describing the spec (the agent learns the format from this) |
+| `validate_diagram_spec` | `spec` | `{ ok, errors[], warnings[] }` — check before rendering |
+| `render_diagram` | `spec` | `{ svg, width, height, warnings[] }` — if `warnings` is non-empty, fix the spec and call again |
+
+### Client configuration
+
+Add the server to your MCP client config. The standard shape is an `mcpServers` map keyed by a server name.
+
+**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json`), or **Claude Code** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "geny-svgforge": {
+      "command": "geny-svgforge-mcp"
+    }
+  }
+}
+```
+
+Zero-install with [uv](https://docs.astral.sh/uv/) (no prior `pip install` needed):
+
+```json
+{
+  "mcpServers": {
+    "geny-svgforge": {
+      "command": "uvx",
+      "args": ["--from", "geny-svgforge[mcp]", "geny-svgforge-mcp"]
+    }
+  }
+}
+```
+
+Claude Code can also add it from the CLI:
+
+```bash
+claude mcp add geny-svgforge -- uvx --from 'geny-svgforge[mcp]' geny-svgforge-mcp
+```
+
+A typical agent flow: call `get_diagram_schema` once to learn the format → emit a `spec` → call `render_diagram` → if `warnings` is non-empty, repair the spec and retry.
+
+---
+
+## How it works
+
+Three layers: **Spec (JSON Schema) → Layout Engine → Renderer**.
+
+- **Real font metrics** — text width is computed in pixels by summing glyph advances via `fontTools` (no browser, no headless engine). The same font used for measurement is embedded into the SVG, so **measured layout == rendered output**.
+- **Deterministic layout** — boxes are sized to their text, connectors are routed through the inter-row band away from boxes, and the viewBox/padding is derived from the bounding box of every element — so nothing can clip.
+- **Font embedding** — only the glyphs actually used are subset and inlined as a base64 `@font-face`, so the SVG renders identically everywhere (browsers, resvg). `to_png()` renders via the installed font (`raster_safe`) because cairosvg ignores embedded `@font-face`.
+- **Lint** — a post-layout pass flags box overlaps and canvas overflow. It should always be empty; if not, the warnings are returned to the agent so it can fix the spec.
+
+## Diagram types
+
+| Type | Description |
+|---|---|
+| `token-sequence` | Rows of position-labeled token boxes, with inter-row connectors, a side note, and a caption |
+
+(`flow`, `grid`, `stack`, `callout`, … are planned — the spec is extensible via the `type` field.)
+
+## Roadmap
+
+- Automatic collision resolution (constraint / force based)
+- Visual self-repair loop: render → rasterize → multimodal critique → fix spec → re-render
+- More diagram types, themes, templates, accessibility (`<title>`/`<desc>`/aria)
+
+## License
+
+MIT. Text is measured against — and a subset is embedded from — a system font (e.g. SIL OFL Noto Sans CJK). When embedding, the embedded font's own license applies.

geny_svgforge-0.1.0/README.md

@@ -0,0 +1,145 @@
+# geny-svgforge
+
+**Give an AI a semantic spec instead of raw coordinates, and a deterministic layout engine produces a clean diagram SVG with zero overlaps or clipping.**
+
+When an LLM writes `<svg>` by hand, it can't reliably reason about text widths, box bounds, curve paths, or the viewBox — so elements overlap and captions get clipped. geny-svgforge inserts a layout layer between the AI and the SVG. The AI emits only a JSON **spec** (*"two rows of labeled tokens, posN labels, connect A's token 2 to B's token 3 with a curve, a side note, a caption"*) — no coordinates. The library measures text with real font metrics, sizes every box, routes connectors around obstacles, and fits the viewBox to the content. **Overlap and overflow become structurally impossible.**
+
+> Same lineage as edit2ppt (AI emits PPT structure, engine renders) and Contextifier (structure-preserving document parsing).
+
+---
+
+## Install
+
+```bash
+pip install geny-svgforge            # core (SVG)
+pip install 'geny-svgforge[png]'     # + PNG export (cairosvg)
+pip install 'geny-svgforge[mcp]'     # + MCP server
+```
+
+## Quickstart (Python)
+
+```python
+from geny_svgforge import render
+
+spec = {
+    "type": "token-sequence",
+    "title": "Absolute position changes, relative pattern remains",
+    "rows": [
+        {"label": "sentence A", "tokens": [
+            {"text": "나는", "pos": "pos 0"},
+            {"text": "오늘", "pos": "pos 1"},
+            {"text": "밥을", "pos": "pos 2", "id": "a2"},
+            {"text": "먹었다", "pos": "pos 3", "variant": "highlight"},
+        ]},
+        {"label": "sentence B", "tokens": [
+            {"text": "나는", "pos": "pos 0"},
+            {"text": "정말", "pos": "pos 1", "variant": "accent"},
+            {"text": "오늘", "pos": "pos 2"},
+            {"text": "밥을", "pos": "pos 3", "id": "b3"},
+            {"text": "먹었다", "pos": "pos 4", "variant": "highlight"},
+        ]},
+    ],
+    "connectors": [{"from": "a2", "to": "b3", "color": "accent"}],
+    "note": {"title": "What the model must learn",
+             "lines": ["Memorizing absolute positions is brittle to length changes.",
+                       "Relative distance and surrounding patterns are handled in attention."]},
+    "caption": "Same relative token relationship survives an absolute shift",
+}
+
+result = render(spec)        # portable SVG with the used glyphs embedded
+print(result.warnings)       # []  ← no overlap / no clipping (lint passed)
+open("out.svg", "w").write(result.svg)
+```
+
+## CLI
+
+```bash
+geny-svgforge render spec.json -o out.svg
+geny-svgforge render spec.json -o out.png      # PNG (requires [png])
+geny-svgforge validate spec.json               # validate before rendering
+geny-svgforge schema -o schema.json            # dump the JSON Schema
+```
+
+## MCP server
+
+geny-svgforge ships an [MCP](https://modelcontextprotocol.io) server over **stdio** so any MCP-compatible agent can request diagrams. After `pip install 'geny-svgforge[mcp]'` the server is launched with:
+
+```bash
+geny-svgforge-mcp                 # console script
+# or
+python -m geny_svgforge.mcp_server
+```
+
+### Tools exposed
+
+| Tool | Input | Returns |
+|---|---|---|
+| `get_diagram_schema` | – | JSON Schema describing the spec (the agent learns the format from this) |
+| `validate_diagram_spec` | `spec` | `{ ok, errors[], warnings[] }` — check before rendering |
+| `render_diagram` | `spec` | `{ svg, width, height, warnings[] }` — if `warnings` is non-empty, fix the spec and call again |
+
+### Client configuration
+
+Add the server to your MCP client config. The standard shape is an `mcpServers` map keyed by a server name.
+
+**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json`), or **Claude Code** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "geny-svgforge": {
+      "command": "geny-svgforge-mcp"
+    }
+  }
+}
+```
+
+Zero-install with [uv](https://docs.astral.sh/uv/) (no prior `pip install` needed):
+
+```json
+{
+  "mcpServers": {
+    "geny-svgforge": {
+      "command": "uvx",
+      "args": ["--from", "geny-svgforge[mcp]", "geny-svgforge-mcp"]
+    }
+  }
+}
+```
+
+Claude Code can also add it from the CLI:
+
+```bash
+claude mcp add geny-svgforge -- uvx --from 'geny-svgforge[mcp]' geny-svgforge-mcp
+```
+
+A typical agent flow: call `get_diagram_schema` once to learn the format → emit a `spec` → call `render_diagram` → if `warnings` is non-empty, repair the spec and retry.
+
+---
+
+## How it works
+
+Three layers: **Spec (JSON Schema) → Layout Engine → Renderer**.
+
+- **Real font metrics** — text width is computed in pixels by summing glyph advances via `fontTools` (no browser, no headless engine). The same font used for measurement is embedded into the SVG, so **measured layout == rendered output**.
+- **Deterministic layout** — boxes are sized to their text, connectors are routed through the inter-row band away from boxes, and the viewBox/padding is derived from the bounding box of every element — so nothing can clip.
+- **Font embedding** — only the glyphs actually used are subset and inlined as a base64 `@font-face`, so the SVG renders identically everywhere (browsers, resvg). `to_png()` renders via the installed font (`raster_safe`) because cairosvg ignores embedded `@font-face`.
+- **Lint** — a post-layout pass flags box overlaps and canvas overflow. It should always be empty; if not, the warnings are returned to the agent so it can fix the spec.
+
+## Diagram types
+
+| Type | Description |
+|---|---|
+| `token-sequence` | Rows of position-labeled token boxes, with inter-row connectors, a side note, and a caption |
+
+(`flow`, `grid`, `stack`, `callout`, … are planned — the spec is extensible via the `type` field.)
+
+## Roadmap
+
+- Automatic collision resolution (constraint / force based)
+- Visual self-repair loop: render → rasterize → multimodal critique → fix spec → re-render
+- More diagram types, themes, templates, accessibility (`<title>`/`<desc>`/aria)
+
+## License
+
+MIT. Text is measured against — and a subset is embedded from — a system font (e.g. SIL OFL Noto Sans CJK). When embedding, the embedded font's own license applies.

geny_svgforge-0.1.0/examples/render_demo.py

@@ -0,0 +1,28 @@
+"""예시 spec 을 깨끗한 SVG 로 렌더하고(PNG 도) 린트 결과를 출력."""
+import json
+import pathlib
+import sys
+
+from geny_svgforge import render
+from geny_svgforge.api import to_png
+
+HERE = pathlib.Path(__file__).parent
+spec_path = HERE / (sys.argv[1] if len(sys.argv) > 1 else "token_sequence_positions.json")
+spec = json.loads(spec_path.read_text(encoding="utf-8"))
+
+# 프로덕션 SVG (폰트 임베드 — 브라우저/resvg 에서 완전 이식)
+result = render(spec)
+out_svg = HERE / "out.svg"
+out_svg.write_text(result.svg, encoding="utf-8")
+print(f"canvas: {result.width:.0f} x {result.height:.0f}")
+print(f"lint warnings ({len(result.warnings)}):")
+for w in result.warnings:
+    print("  -", w)
+print(f"wrote {out_svg} ({len(result.svg)} bytes)")
+
+try:
+    out_png = HERE / "out.png"
+    out_png.write_bytes(to_png(spec, scale=2.0))
+    print(f"wrote {out_png}")
+except Exception as e:  # noqa: BLE001
+    print(f"(png skip: {e})")

geny_svgforge-0.1.0/examples/token_sequence_positions.json

@@ -0,0 +1,38 @@
+{
+  "type": "token-sequence",
+  "title": "Absolute position changes, relative pattern remains",
+  "subtitle": "중간에 토큰이 추가되면 뒤쪽 토큰의 절대 위치는 밀린다. 모델은 이런 이동에도 유지되는 관계를 배워야 한다.",
+  "theme": "light",
+  "rows": [
+    {
+      "label": "sentence A",
+      "tokens": [
+        { "text": "나는", "pos": "pos 0" },
+        { "text": "오늘", "pos": "pos 1" },
+        { "text": "밥을", "pos": "pos 2", "id": "a2" },
+        { "text": "먹었다", "pos": "pos 3", "id": "a3", "variant": "highlight" }
+      ]
+    },
+    {
+      "label": "sentence B",
+      "tokens": [
+        { "text": "나는", "pos": "pos 0" },
+        { "text": "정말", "pos": "pos 1", "variant": "accent" },
+        { "text": "오늘", "pos": "pos 2" },
+        { "text": "밥을", "pos": "pos 3", "id": "b3" },
+        { "text": "먹었다", "pos": "pos 4", "id": "b4", "variant": "highlight" }
+      ]
+    }
+  ],
+  "connectors": [
+    { "from": "a2", "to": "b3", "style": "arc", "color": "accent" }
+  ],
+  "note": {
+    "title": "모델이 배워야 하는 것",
+    "lines": [
+      "절대 position만 외우면 문장 길이 변화에 약하다.",
+      "상대 거리와 주변 패턴을 attention에서 같이 다룬다."
+    ]
+  },
+  "caption": "절대 위치가 바뀌어도 상대 토큰 관계가 유지되는 문장 예시"
+}

geny_svgforge-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "geny-svgforge"
+version = "0.1.0"
+description = "AI가 좌표 대신 의미(spec)만 내면 결정론적 레이아웃으로 깨끗한 다이어그램 SVG를 만드는 라이브러리"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Jang HaRyeom (CocoRoF)" }]
+keywords = ["svg", "diagram", "ai", "mcp", "layout", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+    "pydantic>=2.5",
+    "fonttools>=4.40",
+]
+
+[project.urls]
+Homepage = "https://github.com/CocoRoF/geny-svgforge"
+Repository = "https://github.com/CocoRoF/geny-svgforge"
+Issues = "https://github.com/CocoRoF/geny-svgforge/issues"
+
+[project.optional-dependencies]
+png = ["cairosvg>=2.7"]
+mcp = ["mcp>=1.2"]
+dev = ["pytest>=8", "cairosvg>=2.7"]
+
+[project.scripts]
+geny-svgforge = "geny_svgforge.cli:main"
+geny-svgforge-mcp = "geny_svgforge.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/geny_svgforge"]

geny_svgforge-0.1.0/src/geny_svgforge/__init__.py

@@ -0,0 +1,25 @@
+"""geny-svgforge — AI가 의미(spec)만 내면 결정론적 레이아웃으로 깨끗한 다이어그램 SVG를 만든다."""
+from __future__ import annotations
+
+from .api import RenderResult, render, validate_spec
+from .spec import (
+    Connector,
+    Note,
+    Row,
+    Token,
+    TokenSequenceSpec,
+    json_schema,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "render",
+    "validate_spec",
+    "RenderResult",
+    "json_schema",
+    "TokenSequenceSpec",
+    "Row",
+    "Token",
+    "Connector",
+    "Note",
+]

geny_svgforge-0.1.0/src/geny_svgforge/api.py

@@ -0,0 +1,103 @@
+"""공개 API. AI 에이전트/서버/CLI 가 쓰는 진입점."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+from .fonts import EMBED_FAMILY, FONT_FAMILY, default_fonts, subset_b64
+from .geometry import TextEl
+from .layout import build_scene
+from .lint import lint
+from .render import render_svg
+from .spec import TokenSequenceSpec
+
+
+@dataclass
+class RenderResult:
+    svg: str
+    width: float
+    height: float
+    warnings: list[str] = field(default_factory=list)
+
+
+def _coerce(spec: Union[dict, TokenSequenceSpec]) -> TokenSequenceSpec:
+    if isinstance(spec, TokenSequenceSpec):
+        return spec
+    return TokenSequenceSpec.model_validate(spec)
+
+
+def _embed_css(scene) -> tuple[str, str]:
+    """사용된 글자만 subset 해 base64 @font-face 로 임베드.
+
+    측정에 쓴 폰트를 그대로 임베드하므로 어떤 렌더러에서도 측정==렌더가 성립한다(완전 이식성).
+    반환: (font_faces_css, font_family).
+    """
+    reg, bold = default_fonts()
+    reg_chars: set[str] = set()
+    bold_chars: set[str] = set()
+    for el in scene.elements:
+        if isinstance(el, TextEl):
+            (bold_chars if el.weight == "bold" else reg_chars).update(el.text)
+    css = ""
+    if reg_chars:
+        b = subset_b64(reg.path, reg.ttc_index, reg_chars)
+        if b:
+            css += (f"@font-face{{font-family:'{EMBED_FAMILY}';font-weight:400;"
+                    f"src:url(data:font/ttf;base64,{b}) format('truetype');}}")
+    if bold_chars:
+        b = subset_b64(bold.path, bold.ttc_index, bold_chars)
+        if b:
+            css += (f"@font-face{{font-family:'{EMBED_FAMILY}';font-weight:700;"
+                    f"src:url(data:font/ttf;base64,{b}) format('truetype');}}")
+    real = default_fonts()[0].family_name
+    family = f"'{EMBED_FAMILY}', '{real}', {FONT_FAMILY}" if css else FONT_FAMILY
+    return css, family
+
+
+def render(
+    spec: Union[dict, TokenSequenceSpec],
+    embed_font: bool = True,
+    raster_safe: bool = False,
+) -> RenderResult:
+    """spec(dict or model) -> 깨끗한 SVG + 린트 경고.
+
+    잘못된 spec 은 pydantic ValidationError 를 던진다(렌더 전 차단).
+    - embed_font=True: 사용된 글자를 subset 해 @font-face 로 임베드(브라우저·resvg 에서 완전 이식).
+    - raster_safe=True: 임베드 대신 실제 설치 폰트 family 를 우선 지정(cairosvg 등 @font-face 미지원
+      래스터라이저에서 CJK 가 깨지지 않게). PNG 내보내기에 사용.
+    """
+    model = _coerce(spec)
+    scene = build_scene(model)
+    warnings = lint(scene)
+    if raster_safe:
+        real = default_fonts()[0].family_name
+        svg = render_svg(scene, font_family=f"'{real}', {FONT_FAMILY}")
+    elif embed_font:
+        css, family = _embed_css(scene)
+        svg = render_svg(scene, font_family=family, font_faces_css=css)
+    else:
+        svg = render_svg(scene)
+    return RenderResult(svg=svg, width=scene.width, height=scene.height, warnings=warnings)
+
+
+def to_png(spec: Union[dict, TokenSequenceSpec], scale: float = 2.0) -> bytes:
+    """PNG 바이트. cairosvg 필요(optional dep 'png'). @font-face 미지원 래스터라이저를 위해
+    실제 설치 폰트로 렌더한다(설치 폰트가 없으면 resvg + 임베드 SVG 사용 권장)."""
+    import cairosvg
+
+    res = render(spec, raster_safe=True)
+    return cairosvg.svg2png(
+        bytestring=res.svg.encode("utf-8"), output_width=int(res.width * scale)
+    )
+
+
+def validate_spec(spec: dict) -> dict[str, Any]:
+    """렌더 없이 spec 만 검증. {ok, errors[], warnings[]}."""
+    from pydantic import ValidationError
+
+    try:
+        model = _coerce(spec)
+    except ValidationError as e:
+        return {"ok": False, "errors": e.errors(include_url=False), "warnings": []}
+    scene = build_scene(model)
+    return {"ok": True, "errors": [], "warnings": lint(scene)}