northcel 0.1.0__tar.gz

northcel-0.1.0/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 North Noir (https://northnoir.com). All rights reserved.
+
+Proprietary License (matches packages/northnoir-cli).
+
+Permission is granted to install and use the `northcel` package, CLI (`northcel` / `ncel`),
+specification, examples, and editor grammar to author, validate, format, and render
+`.ncel` AI-drawn images and videos locally or with North Noir services.
+
+Redistribution of modified commercial forks of the North Noir platform or misrepresentation
+of the official NorthCel specification without written permission from North Noir is prohibited.

northcel-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: northcel
+Version: 0.1.0
+Summary: NorthCel (.ncel) — the AI-drawn video programming language combining MoonBit typed ASTs, Bend parallel swarms, and GLSL 4x4 subpixel rendering.
+Author: North Noir
+License: Proprietary
+Project-URL: Homepage, https://northnoir.com/northcel
+Project-URL: Documentation, https://northnoir.com/northcel
+Project-URL: Repository, https://github.com/syver777/NorthNoir/tree/main/packages/northcel
+Keywords: northcel,ncel,ai-drawn-video,animation,hand-drawn,dsl,northnoir
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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 :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: Pillow>=10.0
+Dynamic: license-file
+
+# `northcel` — The AI-Drawn Video Programming Language (`.ncel`)
+
+**NorthCel** (`.ncel`) is North Noir's domain-specific programming language for AI-drawn images and frame-by-frame animation.
+
+It combines the best properties of three complementary execution models into a single compact, deterministic format:
+
+1. **MoonBit-style typed, declarative scene structure** — algebraic scene layers (`paper`, `def`/`use`, `layer`/`wash`, `stroke`, `ribbon`, `bend_swarm`), compact relative contour encodings (`0.25px` quarter-pixel deltas and `1px` Base-63 deltas), and strict `line:column` diagnostics that an AI coding agent can read and fix.
+2. **Bend-style deterministic parallel evaluation** — repetitive organic marks (water droplets, beard bristles, wet hair strands, rain streaks, and line boil) are modeled as stateless agents whose output is a pure function of `(seed, frame_index, agent_id)`, independent of evaluation order.
+3. **GLSL-style per-pixel supersampled rendering** — every frame is a pure function of `(time, seed, coordinates)` evaluated with even-odd winding parity on an `N×N` subpixel grid (default `4×4`, i.e., `0.25px` resolution) and box-integrated to 8-bit RGB/greyscale.
+
+The reference implementation in this package (`northcel`) is a **pure-Python + NumPy renderer** requiring no GPU or external language compilers at user install time. MoonBit, Bend, and OpenGL/EGL GLSL remain optional documented backends.
+
+## Install
+
+```sh
+pipx install northcel
+# or
+pip install northcel
+```
+
+Both `northcel` and the short alias `ncel` are installed on your `PATH`.
+
+## CLI Commands
+
+```sh
+northcel check scene.ncel [--json]          # Parse and validate with line:column diagnostics
+northcel fmt scene.ncel [-w] [--check]      # Canonical formatter
+northcel info scene.ncel                    # JSON summary of layers, rings, vertices, and bytes
+northcel render scene.ncel -o frame0.png    # Render a single frame (--frame N, --seed S)
+northcel film film.ncel -o frames/ --mp4 out.mp4  # Render frame sequence + optional MP4 via ffmpeg
+```
+
+## Example (`lantern_film.ncel`)
+
+```ncel
+northcel "0.1.0-draft"
+
+film LanternFilm(width: 512, height: 512, fps: 12, frames: 6, precision: 0.25px, seed: 108) {
+  paper { color: #101824, antialias_grid: 4, grain: 0.012 }
+
+  def SeaWave(dx: 0, dy: 0) {
+    stroke crest(color: #6CCFF6, taper: (4.5, 1.5), boil: 0.75px) {
+      (40 + dx, 410 + dy), (180 + dx, 398 + dy), (330 + dx, 412 + dy), (470 + dx, 402 + dy)
+    }
+  }
+
+  layer sea_base(color: #1B3B5A, rings: 1) { "0,1520 2048,0 0,528 -2048,0" }
+  layer lantern_halo(color: #F4A261, rings: 1, boil: 0.6px, translate: (sin(t * 6.28318) * 14, 0)) {
+    "920,640 208,0 40,120 -40,120 -208,0 -40,-120"
+  }
+  ribbon post_ink(color: #F8F9FA, boil: 0.4px) {
+    (256, 480, 12), (256 + sin(t * 6.28318) * 6, 320, 9), (256 + sin(t * 6.28318) * 14, 190, 6)
+  }
+  bend_swarm rain_streaks(agents: 4, color: #E0FBFC, boil: 0.35px, translate: (lerp(-18, 18, t), lerp(0, 48, t))) {
+    "320,240 24,72 -8,4 -24,-72|840,300 24,72 -8,4 -24,-72|1420,220 24,72 -8,4 -24,-72|1760,340 24,72 -8,4 -24,-72"
+  }
+
+  use SeaWave(dx: sin(t * 6.28318) * 10, dy: 0)
+  use SeaWave(dx: cos(t * 6.28318) * -12, dy: 42)
+}
+```
+
+## Documentation
+
+Full language specification (`0.1.0-draft`), AI-agent guide, benchmarks, and tutorials live at:
+- Website: https://northnoir.com/northcel
+- Repository docs: `docs/northcel/`

northcel-0.1.0/README.md

@@ -0,0 +1,67 @@
+# `northcel` — The AI-Drawn Video Programming Language (`.ncel`)
+
+**NorthCel** (`.ncel`) is North Noir's domain-specific programming language for AI-drawn images and frame-by-frame animation.
+
+It combines the best properties of three complementary execution models into a single compact, deterministic format:
+
+1. **MoonBit-style typed, declarative scene structure** — algebraic scene layers (`paper`, `def`/`use`, `layer`/`wash`, `stroke`, `ribbon`, `bend_swarm`), compact relative contour encodings (`0.25px` quarter-pixel deltas and `1px` Base-63 deltas), and strict `line:column` diagnostics that an AI coding agent can read and fix.
+2. **Bend-style deterministic parallel evaluation** — repetitive organic marks (water droplets, beard bristles, wet hair strands, rain streaks, and line boil) are modeled as stateless agents whose output is a pure function of `(seed, frame_index, agent_id)`, independent of evaluation order.
+3. **GLSL-style per-pixel supersampled rendering** — every frame is a pure function of `(time, seed, coordinates)` evaluated with even-odd winding parity on an `N×N` subpixel grid (default `4×4`, i.e., `0.25px` resolution) and box-integrated to 8-bit RGB/greyscale.
+
+The reference implementation in this package (`northcel`) is a **pure-Python + NumPy renderer** requiring no GPU or external language compilers at user install time. MoonBit, Bend, and OpenGL/EGL GLSL remain optional documented backends.
+
+## Install
+
+```sh
+pipx install northcel
+# or
+pip install northcel
+```
+
+Both `northcel` and the short alias `ncel` are installed on your `PATH`.
+
+## CLI Commands
+
+```sh
+northcel check scene.ncel [--json]          # Parse and validate with line:column diagnostics
+northcel fmt scene.ncel [-w] [--check]      # Canonical formatter
+northcel info scene.ncel                    # JSON summary of layers, rings, vertices, and bytes
+northcel render scene.ncel -o frame0.png    # Render a single frame (--frame N, --seed S)
+northcel film film.ncel -o frames/ --mp4 out.mp4  # Render frame sequence + optional MP4 via ffmpeg
+```
+
+## Example (`lantern_film.ncel`)
+
+```ncel
+northcel "0.1.0-draft"
+
+film LanternFilm(width: 512, height: 512, fps: 12, frames: 6, precision: 0.25px, seed: 108) {
+  paper { color: #101824, antialias_grid: 4, grain: 0.012 }
+
+  def SeaWave(dx: 0, dy: 0) {
+    stroke crest(color: #6CCFF6, taper: (4.5, 1.5), boil: 0.75px) {
+      (40 + dx, 410 + dy), (180 + dx, 398 + dy), (330 + dx, 412 + dy), (470 + dx, 402 + dy)
+    }
+  }
+
+  layer sea_base(color: #1B3B5A, rings: 1) { "0,1520 2048,0 0,528 -2048,0" }
+  layer lantern_halo(color: #F4A261, rings: 1, boil: 0.6px, translate: (sin(t * 6.28318) * 14, 0)) {
+    "920,640 208,0 40,120 -40,120 -208,0 -40,-120"
+  }
+  ribbon post_ink(color: #F8F9FA, boil: 0.4px) {
+    (256, 480, 12), (256 + sin(t * 6.28318) * 6, 320, 9), (256 + sin(t * 6.28318) * 14, 190, 6)
+  }
+  bend_swarm rain_streaks(agents: 4, color: #E0FBFC, boil: 0.35px, translate: (lerp(-18, 18, t), lerp(0, 48, t))) {
+    "320,240 24,72 -8,4 -24,-72|840,300 24,72 -8,4 -24,-72|1420,220 24,72 -8,4 -24,-72|1760,340 24,72 -8,4 -24,-72"
+  }
+
+  use SeaWave(dx: sin(t * 6.28318) * 10, dy: 0)
+  use SeaWave(dx: cos(t * 6.28318) * -12, dy: 42)
+}
+```
+
+## Documentation
+
+Full language specification (`0.1.0-draft`), AI-agent guide, benchmarks, and tutorials live at:
+- Website: https://northnoir.com/northcel
+- Repository docs: `docs/northcel/`

northcel-0.1.0/northcel/__init__.py

@@ -0,0 +1,79 @@
+"""NorthCel (.ncel) — the AI-drawn video programming language."""
+
+from .config import (
+    CLI_COMMAND,
+    CLI_SHORT_ALIAS,
+    DOCS_URL,
+    FILE_EXTENSION,
+    LANGUAGE_NAME,
+    NPM_PACKAGE,
+    PACKAGE_VERSION,
+    PYPI_PACKAGE,
+    SPEC_VERSION,
+)
+from .ast_nodes import (
+    BoilSpec,
+    ColorValue,
+    DefBlock,
+    DocumentNode,
+    FilmNode,
+    LayerNode,
+    PaperSpec,
+    RibbonNode,
+    SceneNode,
+    StrokeNode,
+    SwarmNode,
+    UseNode,
+)
+from .parser import NorthCelSyntaxError, parse_ncel
+from .validator import ValidationDiagnostic, validate_document
+from .formatter import format_document
+from .rings import (
+    decode_ring_b63_1px,
+    decode_ring_q25,
+    decode_rings_payload,
+    encode_ring_b63_1px,
+    encode_ring_q25,
+    encode_rings_payload,
+)
+from .renderer import render_document_frame, render_film_frames
+
+__version__ = PACKAGE_VERSION
+
+__all__ = [
+    "LANGUAGE_NAME",
+    "FILE_EXTENSION",
+    "CLI_COMMAND",
+    "CLI_SHORT_ALIAS",
+    "PYPI_PACKAGE",
+    "NPM_PACKAGE",
+    "PACKAGE_VERSION",
+    "SPEC_VERSION",
+    "DOCS_URL",
+    "__version__",
+    "BoilSpec",
+    "ColorValue",
+    "DefBlock",
+    "DocumentNode",
+    "FilmNode",
+    "LayerNode",
+    "PaperSpec",
+    "RibbonNode",
+    "SceneNode",
+    "StrokeNode",
+    "SwarmNode",
+    "UseNode",
+    "NorthCelSyntaxError",
+    "parse_ncel",
+    "ValidationDiagnostic",
+    "validate_document",
+    "format_document",
+    "decode_ring_b63_1px",
+    "decode_ring_q25",
+    "decode_rings_payload",
+    "encode_ring_b63_1px",
+    "encode_ring_q25",
+    "encode_rings_payload",
+    "render_document_frame",
+    "render_film_frames",
+]

northcel-0.1.0/northcel/ast_nodes.py

@@ -0,0 +1,159 @@
+"""Typed AST nodes for NorthCel (.ncel) v0.1."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class ColorValue:
+    """Represents either a greyscale tone (0..255) or an RGB color (r, g, b)."""
+
+    r: int
+    g: int
+    b: int
+    is_grey: bool = True
+
+    @classmethod
+    def from_tone(cls, tone: int) -> "ColorValue":
+        v = int(tone)
+        return cls(r=v, g=v, b=v, is_grey=True)
+
+    @classmethod
+    def from_rgb(cls, r: int, g: int, b: int) -> "ColorValue":
+        return cls(r=int(r), g=int(g), b=int(b), is_grey=(r == g == b))
+
+    @classmethod
+    def from_hex(cls, hex_str: str) -> "ColorValue":
+        h = hex_str.lstrip("#")
+        if len(h) == 3:
+            h = "".join(c * 2 for c in h)
+        r = int(h[0:2], 16)
+        g = int(h[2:4], 16)
+        b = int(h[4:6], 16)
+        return cls(r=r, g=g, b=b, is_grey=(r == g == b))
+
+    def to_hex(self) -> str:
+        return f"#{self.r:02X}{self.g:02X}{self.b:02X}"
+
+    def as_rgb_tuple(self) -> tuple[int, int, int]:
+        return (self.r, self.g, self.b)
+
+
+@dataclass(frozen=True)
+class BoilSpec:
+    amplitude_px: float = 0.0
+    frequency: float = 1.0
+    seed_offset: int = 0
+
+
+@dataclass(frozen=True)
+class PaperSpec:
+    color: ColorValue = field(default_factory=lambda: ColorValue.from_tone(239))
+    antialias_grid: int = 4
+    grain: float = 0.0
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class LayerNode:
+    name: str
+    color: ColorValue
+    rings_count: int | None
+    payload: str
+    boil: BoilSpec | None = None
+    translate_expr: tuple[Any, Any] = (0.0, 0.0)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class SwarmNode:
+    name: str
+    agents: int
+    color: ColorValue
+    payload: str
+    boil: BoilSpec | None = None
+    translate_expr: tuple[Any, Any] = (0.0, 0.0)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class StrokeNode:
+    name: str
+    color: ColorValue
+    width_start: float
+    width_end: float
+    points: list[tuple[Any, Any]]
+    boil: BoilSpec | None = None
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class RibbonNode:
+    name: str
+    color: ColorValue
+    points: list[tuple[Any, Any, float]]
+    boil: BoilSpec | None = None
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class DefBlock:
+    name: str
+    params: dict[str, float]
+    items: list[LayerNode | SwarmNode | StrokeNode | RibbonNode]
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class UseNode:
+    def_name: str
+    args: dict[str, Any]
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+SceneItem = LayerNode | SwarmNode | StrokeNode | RibbonNode | UseNode
+
+
+@dataclass(frozen=True)
+class SceneNode:
+    name: str
+    width: int = 1024
+    height: int = 1024
+    fps: int = 6
+    precision: str = "0.25px"
+    seed: int = 42
+    paper: PaperSpec = field(default_factory=PaperSpec)
+    defs: dict[str, DefBlock] = field(default_factory=dict)
+    items: list[SceneItem] = field(default_factory=list)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class FilmNode:
+    name: str
+    width: int = 1024
+    height: int = 1024
+    fps: int = 6
+    frames: int = 2
+    precision: str = "0.25px"
+    seed: int = 42
+    paper: PaperSpec = field(default_factory=PaperSpec)
+    defs: dict[str, DefBlock] = field(default_factory=dict)
+    items: list[SceneItem] = field(default_factory=list)
+    frame_overrides: dict[int, SceneNode] = field(default_factory=dict)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class DocumentNode:
+    spec_version: str
+    root: SceneNode | FilmNode
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))

northcel-0.1.0/northcel/cli.py

@@ -0,0 +1,290 @@
+"""CLI entrypoint for `northcel` and `ncel`: check, fmt, info, render, film."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+import time
+from typing import Sequence
+
+from PIL import Image
+
+from .ast_nodes import FilmNode, LayerNode, RibbonNode, SceneNode, StrokeNode, SwarmNode
+from .config import CLI_COMMAND, FILE_EXTENSION, LANGUAGE_NAME, PACKAGE_VERSION, SPEC_VERSION
+from .formatter import format_document
+from .parser import NorthCelSyntaxError, parse_ncel
+from .renderer import render_document_frame, render_film_frames
+from .rings import decode_rings_payload
+from .validator import validate_document
+
+
+def _load_and_validate(path: Path):
+    if not path.is_file():
+        return None, None, [f"1:1: error: File not found: {path}"]
+    src = path.read_text(encoding="utf-8")
+    try:
+        doc = parse_ncel(src)
+    except NorthCelSyntaxError as exc:
+        return src, None, [f"{exc.line}:{exc.column}: error: {exc.message}"]
+    diags = validate_document(doc)
+    return src, doc, diags
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    _, doc, diags = _load_and_validate(path)
+    if doc is None:
+        errors = diags
+        warnings = []
+    else:
+        errors = [d.format() for d in diags if d.level == "error"]
+        warnings = [d.format() for d in diags if d.level == "warning"]
+
+    ok = len(errors) == 0
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": ok,
+                    "file": str(path),
+                    "spec_version": doc.spec_version if doc else None,
+                    "errors": errors,
+                    "warnings": warnings,
+                },
+                indent=2,
+            )
+        )
+    else:
+        for w in warnings:
+            print(f"{path}:{w}", file=sys.stderr)
+        for e in errors:
+            print(f"{path}:{e}", file=sys.stderr)
+        if ok:
+            print(f"{path}: OK ({LANGUAGE_NAME} {doc.spec_version if doc else SPEC_VERSION})")
+    return 0 if ok else 1
+
+
+def cmd_fmt(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    src, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        for e in errors:
+            print(f"{path}:{e.format()}", file=sys.stderr)
+        return 1
+
+    formatted = format_document(doc, include_version_header=True)
+    if args.check:
+        if src != formatted:
+            print(f"{path}: needs formatting", file=sys.stderr)
+            return 1
+        print(f"{path}: formatted")
+        return 0
+    if args.write:
+        path.write_text(formatted, encoding="utf-8")
+        print(f"{path}: formatted in-place")
+        return 0
+    sys.stdout.write(formatted)
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    src, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    root = doc.root
+    total_rings = 0
+    total_vertices = 0
+    layers_summary = []
+
+    def inspect_items(items, precision: str):
+        nonlocal total_rings, total_vertices
+        for it in items:
+            if isinstance(it, (LayerNode, SwarmNode)):
+                rings = decode_rings_payload(it.payload, precision=precision)
+                v_cnt = sum(len(r) for r in rings)
+                total_rings += len(rings)
+                total_vertices += v_cnt
+                layers_summary.append(
+                    {
+                        "kind": "layer" if isinstance(it, LayerNode) else "bend_swarm",
+                        "name": it.name,
+                        "color": it.color.to_hex(),
+                        "rings": len(rings),
+                        "vertices": v_cnt,
+                    }
+                )
+            elif isinstance(it, StrokeNode):
+                total_rings += 1
+                total_vertices += len(it.points) * 2
+                layers_summary.append(
+                    {
+                        "kind": "stroke",
+                        "name": it.name,
+                        "color": it.color.to_hex(),
+                        "points": len(it.points),
+                    }
+                )
+            elif isinstance(it, RibbonNode):
+                total_rings += 1
+                total_vertices += len(it.points) * 2
+                layers_summary.append(
+                    {
+                        "kind": "ribbon",
+                        "name": it.name,
+                        "color": it.color.to_hex(),
+                        "points": len(it.points),
+                    }
+                )
+
+    inspect_items(root.items, root.precision)
+    if isinstance(root, FilmNode):
+        for f_scene in root.frame_overrides.values():
+            inspect_items(f_scene.items, f_scene.precision)
+
+    info = {
+        "file": str(path),
+        "bytes": len(src.encode("utf-8")) if src else 0,
+        "spec_version": doc.spec_version,
+        "kind": "film" if isinstance(root, FilmNode) else "scene",
+        "name": root.name,
+        "width": root.width,
+        "height": root.height,
+        "fps": root.fps,
+        "frames": root.frames if isinstance(root, FilmNode) else 1,
+        "precision": root.precision,
+        "seed": root.seed,
+        "defs": list(root.defs.keys()),
+        "total_rings": total_rings,
+        "total_vertices": total_vertices,
+        "layers": layers_summary,
+    }
+    print(json.dumps(info, indent=2))
+    return 0
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    _, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        for e in errors:
+            print(f"{path}:{e.format()}", file=sys.stderr)
+        return 1
+
+    t0 = time.monotonic()
+    rgb = render_document_frame(doc, frame_index=args.frame, seed_override=args.seed)
+    out_p = Path(args.out) if args.out else path.with_suffix(".png")
+    out_p.parent.mkdir(parents=True, exist_ok=True)
+    Image.fromarray(rgb, mode="RGB").save(out_p)
+    elapsed = time.monotonic() - t0
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    "input": str(path),
+                    "output": str(out_p),
+                    "frame": args.frame,
+                    "width": int(rgb.shape[1]),
+                    "height": int(rgb.shape[0]),
+                    "seconds": round(elapsed, 4),
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(f"Rendered {out_p} ({rgb.shape[1]}x{rgb.shape[0]}, frame {args.frame}) in {elapsed:.3f}s")
+    return 0
+
+
+def cmd_film(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    _, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        for e in errors:
+            print(f"{path}:{e.format()}", file=sys.stderr)
+        return 1
+
+    indices: list[int] | None = None
+    if args.frames:
+        if ".." in args.frames:
+            a_s, b_s = args.frames.split("..", 1)
+            indices = list(range(int(a_s), int(b_s) + 1))
+        else:
+            indices = [int(x.strip()) for x in args.frames.split(",") if x.strip()]
+
+    t0 = time.monotonic()
+    res = render_film_frames(doc, out_dir=args.out_dir, frame_indices=indices, mp4_path=args.mp4)
+    res["seconds"] = round(time.monotonic() - t0, 4)
+    print(json.dumps(res, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog=CLI_COMMAND,
+        description=f"{LANGUAGE_NAME} ({FILE_EXTENSION}) — AI-drawn video language compiler, formatter, validator, and reference renderer.",
+    )
+    p.add_argument("--version", action="version", version=f"{CLI_COMMAND} {PACKAGE_VERSION} (spec {SPEC_VERSION})")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="Parse and validate a .ncel file with line:column diagnostics.")
+    p_check.add_argument("file", help="Path to .ncel file")
+    p_check.add_argument("--json", action="store_true", help="Output structured JSON diagnostics")
+    p_check.set_defaults(func=cmd_check)
+
+    p_fmt = sub.add_parser("fmt", help="Format a .ncel file into canonical form.")
+    p_fmt.add_argument("file", help="Path to .ncel file")
+    p_fmt.add_argument("-w", "--write", action="store_true", help="Write formatted output in-place")
+    p_fmt.add_argument("--check", action="store_true", help="Exit non-zero if file is not canonically formatted")
+    p_fmt.set_defaults(func=cmd_fmt)
+
+    p_info = sub.add_parser("info", help="Inspect scene/film metadata, layers, rings, and vertex counts.")
+    p_info.add_argument("file", help="Path to .ncel file")
+    p_info.set_defaults(func=cmd_info)
+
+    p_render = sub.add_parser("render", help="Render a single frame of a .ncel scene or film to PNG.")
+    p_render.add_argument("file", help="Path to .ncel file")
+    p_render.add_argument("-o", "--out", help="Output PNG path (default: <file>.png)")
+    p_render.add_argument("-f", "--frame", type=int, default=0, help="Frame index to render (default: 0)")
+    p_render.add_argument("--seed", type=int, default=None, help="Optional seed override")
+    p_render.add_argument("--json", action="store_true", help="Output JSON summary")
+    p_render.set_defaults(func=cmd_render)
+
+    p_film = sub.add_parser("film", help="Render a sequence of frames from a .ncel film to PNGs and optional MP4.")
+    p_film.add_argument("file", help="Path to .ncel file")
+    p_film.add_argument("-o", "--out-dir", required=True, help="Directory for rendered f0000.png frames")
+    p_film.add_argument("--frames", help="Optional frame range '0..5' or comma list '0,1,2'")
+    p_film.add_argument("--mp4", help="Optional output MP4 file path (muxed with ffmpeg if available)")
+    p_film.set_defaults(func=cmd_film)
+
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())