ncel 0.2.1__tar.gz

ncel-0.2.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: ncel
+Version: 0.2.1
+Summary: NorthCel (.ncel) one-command CLI: runs the native MoonBit + Bend/HVM2 + GLSL runtime when the platform supports it, and says so plainly when it does not.
+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/packaging
+Keywords: ncel,northcel,ai-drawn-video,animation,hand-drawn,moonbit,bend,glsl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+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
+Requires-Dist: northcel==0.2.1
+Requires-Dist: ncel-native==0.2.1; sys_platform == "linux" and platform_machine == "x86_64"
+
+# ncel — NorthCel, drawn frame by frame by a native runtime
+
+`ncel` is the one-command NorthCel (`.ncel`) CLI. It runs the **native runtime**:
+
+* **MoonBit** parses the typed scene/film AST, decodes every contour chain, expands
+  `def`/`use`, applies frame deltas and the deterministic boil hash;
+* **Bend 0.2.38 / HVM 2.0.22** evaluates every `bend_swarm` agent;
+* **GLSL 4.30**, compiled by the **Mesa/EGL** driver (llvmpipe, no GPU), rasterises
+  the normative `aa×aa` even-odd integration.
+
+The Python reference implementation (`northcel`) ships alongside as the
+conformance oracle and as a **clearly labelled** fallback where the native runtime
+cannot run. Nothing is ever silently substituted.
+
+## Install
+
+```
+pip install ncel            # Linux x86_64
+ncel doctor                 # stages, exact versions, platform verdict
+ncel verify                 # real renders + determinism, from bundled fixtures
+```
+
+Supported today: **Linux x86_64**, glibc >= 2.39, Mesa `libegl1` + `libgl1` +
+`mesa-libgallium` (Ubuntu 24.04+, Debian 13, Fedora 40+, RHEL 10).
+
+Not supported yet, and it says so: macOS (Apple's OpenGL caps at 4.1; the 4.30
+shader cannot compile — macOS needs Vulkan/MoltenVK or a tested GL 4.1 path),
+Windows, and non-x86_64 Linux. On those platforms `pip install ncel` still
+installs the CLI, `ncel doctor` prints the exact reason, and `render`/`film`/`check`
+use the Python reference renderer, marked `python-reference` — never "native".
+
+`pip install ncel` brings `ncel-native` (the ~3 MB runtime bundle, no download at
+first run) and `northcel` (the reference parser/validator/formatter).
+
+## Use
+
+```
+ncel render scene.ncel -o frame.png --frame 0 --json
+ncel film   film.ncel -o out/ --frames 0..5 --mp4 out.mp4 --json
+ncel check  scene.ncel --json
+ncel info   scene.ncel --json
+ncel fmt    scene.ncel --check
+ncel guide                          # offline authoring guide
+ncel doctor --json                  # machine-readable stage report
+ncel toolchain status|install       # MoonBit compiler, only needed to rebuild
+```
+
+`--json` receipts come from the native runtime and include `language`,
+`northcel_version`, `spec_version`, size/fps/frames, source bytes, per-frame
+`sha256`, stage timings, geometry, swarm counts and `"stage": "MoonBit+Bend+GLSL"`.
+
+## What `doctor` proves
+
+```
+ncel 0.2.1  (NorthCel spec 0.2.0-draft)
+platform      linux-x86_64 glibc 2.39
+supported     yes
+native        0.2.0  (bundle checksums 13 verified, stage MoonBit+Bend+GLSL)
+  MoonBit       stage present: yes  binary ncel-ast  compiled with MoonBit 0.1.20261102 (ea07287 2026-11-02)
+  Bend          bend-lang 0.2.38  …/bin/bend
+  HVM2          hvm 2.0.22  …/bin/hvm
+  GL runtime    4.5 (Core Profile) Mesa 25.2.8  llvmpipe (LLVM 20.1.2, 256 bits)  GLSL 4.50
+  GLSL          draw430 14829a3cbb6c… compiles  draw410 fe4d0c4fe4e0… compiles
+  ffmpeg        present (optional, --mp4)
+  reference     northcel 0.2.1 — fallback only — non-native reference renderer
+```
+
+## What `verify` proves
+
+* a starter scene renders to a 320×180 PNG;
+* the shower `f0001` frame reproduces the pinned conformance hash
+  (`be0eb036…`), which the Python reference reproduces pixel-for-pixel;
+* a 6-frame film renders 6 distinct frames;
+* both renders repeat with identical sha256 (determinism).
+
+## Toolchain notes
+
+A runtime needs no downloads: the MoonBit-compiled stage, Bend and HVM2 are inside
+`ncel-native`, with every file sha256-pinned in `bundle-manifest.json` and checked
+against `native/ncel/toolchain.lock`. The **MoonBit compiler** (101 MB) is only
+needed to rebuild the native tree from source — `ncel toolchain install` fetches
+and verifies it into `~/.local/share/ncel/toolchain`.
+
+GLSL is not installed; it is compiled by the GL driver. That is why the installer
+provisions the **Mesa/EGL runtime** and why `doctor` compiles and links both
+shaders as proof.
+
+## Uninstall
+
+```
+pip uninstall ncel ncel-native northcel
+rm -rf ~/.local/share/ncel        # only if you ran `ncel toolchain install`
+```
+
+## Licence
+
+Proprietary — North Noir. See `LICENSE` in the NorthCel distribution.

ncel-0.2.1/README.md

@@ -0,0 +1,97 @@
+# ncel — NorthCel, drawn frame by frame by a native runtime
+
+`ncel` is the one-command NorthCel (`.ncel`) CLI. It runs the **native runtime**:
+
+* **MoonBit** parses the typed scene/film AST, decodes every contour chain, expands
+  `def`/`use`, applies frame deltas and the deterministic boil hash;
+* **Bend 0.2.38 / HVM 2.0.22** evaluates every `bend_swarm` agent;
+* **GLSL 4.30**, compiled by the **Mesa/EGL** driver (llvmpipe, no GPU), rasterises
+  the normative `aa×aa` even-odd integration.
+
+The Python reference implementation (`northcel`) ships alongside as the
+conformance oracle and as a **clearly labelled** fallback where the native runtime
+cannot run. Nothing is ever silently substituted.
+
+## Install
+
+```
+pip install ncel            # Linux x86_64
+ncel doctor                 # stages, exact versions, platform verdict
+ncel verify                 # real renders + determinism, from bundled fixtures
+```
+
+Supported today: **Linux x86_64**, glibc >= 2.39, Mesa `libegl1` + `libgl1` +
+`mesa-libgallium` (Ubuntu 24.04+, Debian 13, Fedora 40+, RHEL 10).
+
+Not supported yet, and it says so: macOS (Apple's OpenGL caps at 4.1; the 4.30
+shader cannot compile — macOS needs Vulkan/MoltenVK or a tested GL 4.1 path),
+Windows, and non-x86_64 Linux. On those platforms `pip install ncel` still
+installs the CLI, `ncel doctor` prints the exact reason, and `render`/`film`/`check`
+use the Python reference renderer, marked `python-reference` — never "native".
+
+`pip install ncel` brings `ncel-native` (the ~3 MB runtime bundle, no download at
+first run) and `northcel` (the reference parser/validator/formatter).
+
+## Use
+
+```
+ncel render scene.ncel -o frame.png --frame 0 --json
+ncel film   film.ncel -o out/ --frames 0..5 --mp4 out.mp4 --json
+ncel check  scene.ncel --json
+ncel info   scene.ncel --json
+ncel fmt    scene.ncel --check
+ncel guide                          # offline authoring guide
+ncel doctor --json                  # machine-readable stage report
+ncel toolchain status|install       # MoonBit compiler, only needed to rebuild
+```
+
+`--json` receipts come from the native runtime and include `language`,
+`northcel_version`, `spec_version`, size/fps/frames, source bytes, per-frame
+`sha256`, stage timings, geometry, swarm counts and `"stage": "MoonBit+Bend+GLSL"`.
+
+## What `doctor` proves
+
+```
+ncel 0.2.1  (NorthCel spec 0.2.0-draft)
+platform      linux-x86_64 glibc 2.39
+supported     yes
+native        0.2.0  (bundle checksums 13 verified, stage MoonBit+Bend+GLSL)
+  MoonBit       stage present: yes  binary ncel-ast  compiled with MoonBit 0.1.20261102 (ea07287 2026-11-02)
+  Bend          bend-lang 0.2.38  …/bin/bend
+  HVM2          hvm 2.0.22  …/bin/hvm
+  GL runtime    4.5 (Core Profile) Mesa 25.2.8  llvmpipe (LLVM 20.1.2, 256 bits)  GLSL 4.50
+  GLSL          draw430 14829a3cbb6c… compiles  draw410 fe4d0c4fe4e0… compiles
+  ffmpeg        present (optional, --mp4)
+  reference     northcel 0.2.1 — fallback only — non-native reference renderer
+```
+
+## What `verify` proves
+
+* a starter scene renders to a 320×180 PNG;
+* the shower `f0001` frame reproduces the pinned conformance hash
+  (`be0eb036…`), which the Python reference reproduces pixel-for-pixel;
+* a 6-frame film renders 6 distinct frames;
+* both renders repeat with identical sha256 (determinism).
+
+## Toolchain notes
+
+A runtime needs no downloads: the MoonBit-compiled stage, Bend and HVM2 are inside
+`ncel-native`, with every file sha256-pinned in `bundle-manifest.json` and checked
+against `native/ncel/toolchain.lock`. The **MoonBit compiler** (101 MB) is only
+needed to rebuild the native tree from source — `ncel toolchain install` fetches
+and verifies it into `~/.local/share/ncel/toolchain`.
+
+GLSL is not installed; it is compiled by the GL driver. That is why the installer
+provisions the **Mesa/EGL runtime** and why `doctor` compiles and links both
+shaders as proof.
+
+## Uninstall
+
+```
+pip uninstall ncel ncel-native northcel
+rm -rf ~/.local/share/ncel        # only if you ran `ncel toolchain install`
+```
+
+## Licence
+
+Proprietary — North Noir. See `LICENSE` in the NorthCel distribution.

ncel-0.2.1/ncel/__init__.py

@@ -0,0 +1,18 @@
+"""`ncel` — the one-command NorthCel CLI.
+
+The native runtime (MoonBit typed AST + Bend/HVM2 swarms + GLSL via Mesa/EGL) is
+the implementation this CLI calls whenever it is available. The Python reference
+renderer (`northcel`) is used only when the native stages genuinely cannot run on
+the current platform, and then the tool says so and labels the result.
+"""
+
+__version__ = "0.2.1"
+
+#: Version of the bundled native runtime build (native/ncel, commit 3ad5f7e).
+NATIVE_RUNTIME_VERSION = "0.2.0"
+
+#: NorthCel language specification implemented by both implementations.
+SPEC_VERSION = "0.2.0-draft"
+
+#: Exit code used when the native runtime is unavailable on this platform.
+EXIT_NO_NATIVE = 3

ncel-0.2.1/ncel/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m ncel` — same entry point as the `ncel` script."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ncel-0.2.1/ncel/bundle.py

@@ -0,0 +1,84 @@
+"""Locate and verify the bundled native runtime (`ncel-native` wheel)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+
+def bundle_dir() -> Path | None:
+    """Directory of the installed native bundle, or None when it is not installed."""
+    try:
+        import ncel_native_bundle  # noqa: PLC0415 - optional platform dependency
+    except Exception:
+        return None
+    path = Path(ncel_native_bundle.__file__).resolve().parent
+    return path if (path / "bundle-manifest.json").is_file() else path
+
+
+def manifest_path() -> Path | None:
+    root = bundle_dir()
+    if not root:
+        return None
+    manifest = root / "bundle-manifest.json"
+    return manifest if manifest.is_file() else None
+
+
+def load_manifest() -> dict | None:
+    path = manifest_path()
+    if not path:
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def binary() -> Path | None:
+    root = bundle_dir()
+    if not root:
+        return None
+    exe = root / "bin" / "ncel-native"
+    return exe if exe.is_file() else None
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def verify_checksums(manifest: dict | None = None) -> dict:
+    """Hash every file named in the bundle manifest.
+
+    Returns {"checked": n, "failed": [{"path", "expected", "actual"}], "missing": [...]}.
+    """
+    root = bundle_dir()
+    manifest = manifest if manifest is not None else load_manifest()
+    if not root or not manifest:
+        return {"checked": 0, "failed": [], "missing": [], "available": False}
+
+    checked = 0
+    failed: list[dict] = []
+    missing: list[str] = []
+    for entry in manifest.get("files", []):
+        rel = entry.get("path", "")
+        target = root / rel
+        if not target.is_file():
+            missing.append(rel)
+            continue
+        actual = sha256_file(target)
+        checked += 1
+        if actual != entry.get("sha256"):
+            failed.append(
+                {"path": rel, "expected": entry.get("sha256"), "actual": actual}
+            )
+    return {
+        "checked": checked,
+        "failed": failed,
+        "missing": missing,
+        "available": True,
+    }

ncel-0.2.1/ncel/cli.py

@@ -0,0 +1,189 @@
+"""`ncel` command-line entry point.
+
+Dispatch rule (this is the whole product promise): if the native runtime can run
+here, run it. If it cannot, say why, use the Python reference and label the result.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from . import EXIT_NO_NATIVE, NATIVE_RUNTIME_VERSION, SPEC_VERSION, __version__, fallback, native
+from . import doctor as doctor_mod
+from . import toolchain as toolchain_mod
+from . import verify as verify_mod
+
+USAGE = """ncel — NorthCel (.ncel) command line
+
+usage: ncel <command> [options]
+
+  doctor  [--json]                     stage availability, exact versions, platform verdict
+  verify  [--json] [--keep DIR]        render the bundled fixtures with the native runtime
+  check   FILE [--json]                parse + validate (native when available)
+  info    FILE [--json]                scene/film metadata, layers, rings, vertices
+  render  FILE [-o OUT.png] [--frame N] [--seed N] [--json]
+  film    FILE -o OUTDIR [--frames 0..5] [--mp4 OUT.mp4] [--json]
+  fmt     FILE [-w|--write] [--check]  canonical formatting (Python reference)
+  guide                                offline authoring guide
+  toolchain <status|install> [--json] [--dry-run]
+  version, --version                   versions (launcher, native runtime, spec)
+
+Global: --no-native  force the labelled Python reference path (never called "native")
+Platform: Linux x86_64, glibc >= 2.39, Mesa EGL/llvmpipe. macOS/Windows are not
+supported in this release; `ncel doctor` explains exactly what is missing.
+"""
+
+
+def _version_line() -> str:
+    native_version = NATIVE_RUNTIME_VERSION
+    usable, _ = native.available()
+    if usable:
+        doc = native.doctor_json() or {}
+        if doc.get("version"):
+            native_version = doc["version"]
+    state = "native" if usable else "python-reference only"
+    return f"ncel {__version__} (native runtime {native_version}, spec {SPEC_VERSION}, {state})"
+
+
+def _pop_flag(args: list[str], *names: str) -> bool:
+    hit = False
+    for name in names:
+        while name in args:
+            args.remove(name)
+            hit = True
+    return hit
+
+
+def _pop_option(args: list[str], *names: str) -> str | None:
+    for name in names:
+        for index, token in enumerate(args):
+            if token == name and index + 1 < len(args):
+                value = args[index + 1]
+                del args[index : index + 2]
+                return value
+            if token.startswith(name + "="):
+                value = token.split("=", 1)[1]
+                del args[index]
+                return value
+    return None
+
+
+def _native_or_reason(args: list[str], command: str) -> tuple[bool, str | None]:
+    if _pop_flag(args, "--no-native", "--python"):
+        return False, "explicitly requested with --no-native"
+    return native.available() if command != "" else (False, None)
+
+
+def _passthrough(command: str, args: list[str], strip_native_only: bool = True) -> int:
+    usable, reason = _native_or_reason(args, command)
+    if strip_native_only:
+        _pop_flag(args, "--require-full")
+    if not usable:
+        fallback.notify(reason)
+        return fallback.delegate([command, *args])
+    return native.run([command, *args]).returncode
+
+
+def _cmd_render(args: list[str]) -> int:
+    usable, reason = _native_or_reason(args, "render")
+    if usable:
+        return native.run(["render", *args]).returncode
+    fallback.notify(reason)
+    as_json = _pop_flag(args, "--json")
+    out = _pop_option(args, "-o", "--out")
+    frame_raw = _pop_option(args, "-f", "--frame") or "0"
+    seed_raw = _pop_option(args, "--seed")
+    files = [a for a in args if not a.startswith("-")]
+    if not files:
+        print("usage: ncel render FILE [-o OUT.png] [--frame N] [--seed N]", file=sys.stderr)
+        return 2
+    try:
+        frame = int(frame_raw)
+        seed = int(seed_raw) if seed_raw is not None else None
+    except ValueError:
+        print("ncel: --frame/--seed must be integers", file=sys.stderr)
+        return 2
+    return fallback.render(files[0], out, frame, seed, as_json)
+
+
+def _cmd_film(args: list[str]) -> int:
+    usable, reason = _native_or_reason(args, "film")
+    if usable:
+        return native.run(["film", *args]).returncode
+    fallback.notify(reason)
+    as_json = _pop_flag(args, "--json")
+    out_dir = _pop_option(args, "-o", "--out-dir")
+    frames = _pop_option(args, "--frames")
+    mp4 = _pop_option(args, "--mp4")
+    files = [a for a in args if not a.startswith("-")]
+    if not files or not out_dir:
+        print("usage: ncel film FILE -o OUTDIR [--frames 0..5] [--mp4 OUT.mp4]", file=sys.stderr)
+        return 2
+    return fallback.film(files[0], out_dir, frames, mp4, as_json)
+
+
+def _cmd_guide(args: list[str]) -> int:
+    path = Path(__file__).with_name("data") / "AGENT-GUIDE.md"
+    if path.is_file():
+        sys.stdout.write(path.read_text(encoding="utf-8"))
+        return 0
+    return fallback.delegate(["guide", *args])
+
+
+def _cmd_toolchain(args: list[str]) -> int:
+    as_json = _pop_flag(args, "--json")
+    dry_run = _pop_flag(args, "--dry-run")
+    action = next((a for a in args if not a.startswith("-")), "status")
+    return toolchain_mod.cmd_toolchain(action, as_json, dry_run)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help", "help"}:
+        print(USAGE, end="")
+        return 0
+
+    command, rest = args[0], args[1:]
+
+    if command in {"--version", "version", "-V"}:
+        print(_version_line())
+        return 0
+
+    if command == "doctor":
+        return doctor_mod.cmd_doctor(_pop_flag(rest, "--json"))
+
+    if command == "verify":
+        as_json = _pop_flag(rest, "--json")
+        keep = _pop_option(rest, "--keep")
+        return verify_mod.cmd_verify(as_json, keep)
+
+    if command == "check":
+        return _passthrough("check", rest)
+    if command == "info":
+        return _passthrough("info", rest)
+
+    if command == "fmt":
+        # The native runtime has no formatter; formatting is the Python reference.
+        return fallback.delegate(["fmt", *rest])
+
+    if command == "guide":
+        return _cmd_guide(rest)
+
+    if command == "render":
+        return _cmd_render(rest)
+    if command == "film":
+        return _cmd_film(rest)
+
+    if command == "toolchain":
+        return _cmd_toolchain(rest)
+
+    if command in {"--json-doctor"}:
+        return doctor_mod.cmd_doctor(True)
+
+    print(f"ncel: unknown command {command!r}\n", file=sys.stderr)
+    print(USAGE, end="", file=sys.stderr)
+    return 2
+
+
+__all__ = ["main", "EXIT_NO_NATIVE"]

ncel-0.2.1/ncel/data/AGENT-GUIDE.md

@@ -0,0 +1,92 @@
+# NorthCel quick agent guide — tools 0.2.1, spec 0.2.0-draft
+
+Discover this guide offline with `npx northcel guide`. The npm package is a
+zero-dependency **partial JS pre-check and Python CLI bridge**, not a renderer.
+
+## Start here (a complete 3-second film)
+
+```ncel
+northcel "0.2.0-draft"
+film Kite(width: 320, height: 180, fps: 12, frames: 36, precision: 0.25px, seed: 42) {
+  palette { ink: #202830, red: #D65C52 }
+  paper { color: #FFF8EC, antialias_grid: 4 }
+  cel kite(color: $red, outline: ($ink, 2px), boil: 0.3px,
+           translate: (lerp(0, 100, t), sin(t * 6.28318) * 10)) {
+    "240,120 100,80 -100,140 -100,-140"
+  }
+  stroke string(color: $ink, taper: (1.5, 0.5)) {
+    (60 + 100 * t, 85 + sin(t * 6.28318) * 10), (110, 160)
+  }
+}
+```
+
+Coordinates are pixels, origin top left. Quoted rings are **relative integer
+quarter-pixel pairs**, NOT absolute pixel vertices: multiply vertices by 4,
+write the first vertex then deltas; at least three vertices per ring. `|`
+separates rings (even-odd holes). `precision: 1px` and `0.25px-b63` instead use
+`x0,y0:ABCD...` Base-63 pairs; prefer plain quarter-pixel deltas for hand authoring.
+Never put expressions inside a quoted ring: move it with `translate: (x, y)`.
+
+## Five language features to combine
+
+1. **Reusable shapes:** `def Mark(dx: 0, dy: 0) { stroke line(width: 2) { (0, 0), (8, 4) } }`
+   then `use Mark(dx: 20, dy: 30)`. Only primitives inside `def`, not nested `use`.
+   `dx/dy` auto-translate expanded geometry; don't also add them to coordinates.
+   Same-named cels in repeated uses replace one another; use distinct named defs
+   for independent cel instances (stroke/ribbon uses append).
+2. **Film/time:** `frames` belongs in the film **header**, never `film X { frames: 36 }`.
+   Duration = frames / fps. `t = f / max(1, frames - 1)`; `f` is zero-based.
+   Expressions: numbers, parameters, `t`, `f`, `seed`, `+ - * /`, `sin(x)`,
+   `cos(x)`, `lerp(a, b, t)`, `step(edge, x)`. Use spaces around minus.
+   `frame 12 { ... }` affects exactly frame 12, not all subsequent frames.
+3. **Deterministic line boil:** `boil: 0.3px` or `boil: (0.3, 1)`; keep it subtle.
+   No randomness, wall clock or cross-frame state.
+4. **Colour/cels:** `palette { ink: #202830 }` before `$ink` references; hex, `rgb(r,g,b)`
+   or `tone: 0..255`. `cel name(color: $ink, outline: (#000, 2px)) { "..." }`
+   couples fill and outline. `layer`/`wash` fills; `bend_swarm`/`swarm` adds detail rings.
+5. **Tapered ink:** `stroke name(color: $ink, taper: (3, 1)) { (10, 10), (40, 20) }`;
+   `ribbon name(color: $ink) { (10, 10, 3), (40, 20, 1) }` uses per-point widths.
+   At least two points. Give every primitive a distinct name in each block.
+
+## Honest validation and look-and-fix loop
+
+1. Run `npx northcel check film.ncel --json`. Without Python it reports
+   `partial: true`, `validator: "js"`, a reason and next command. `ok: true` and
+   exit 0 mean **only that the JS pre-check found no error**, not full validity.
+   Text says **PARTIAL**, never OK. Syntax/header/ring/palette checks help, but
+   numeric ranges, expression evaluation, def resolution and render quality remain unchecked.
+2. Run `npx northcel check film.ncel --require-full --json` before claiming full
+   validation. Exit 2 = no full validator (clean partial); exit 1 = detected error;
+   exit 0 = Python full check succeeded. Install `pipx install northcel` (or
+   `pip install northcel` in a venv), expose its Python CLI on PATH, then repeat.
+   The npm bridge finds importable Python modules or pipx-style Python entrypoints.
+   Never suppress exit 2 or call a partial check fully validated.
+3. Python: `northcel render film.ncel -o frame0.png --frame 0`, inspect the PNG;
+   `northcel film film.ncel -o frames/ --mp4 preview.mp4`, inspect first/middle/last
+   and transition frames. ffmpeg is required for MP4; verify the MP4 exists.
+   Render samples in reverse order and compare native RGB hashes for determinism.
+4. Fix the named block that is wrong, preserve good parts, render again; up to
+   three look-and-fix rounds. `northcel fmt -w film.ncel` canonicalizes it.
+   Full validation is not a visual-quality or runtime-expression guarantee.
+
+Alternatively install `pip install "northnoir[ncel]"` and use
+`northnoir init ink --language ncel --duration 3 --fps 24`,
+`northnoir check ink/scene.ncel`, `northnoir render ink/scene.ncel -o ink/video.mp4`.
+This is an explicit optional local path; JavaScript `scene.html` stays the default.
+NorthCel films are silent; there is no native audio engine or hosted NorthCel API.
+
+## Common mistakes
+
+- No root, unclosed quote/brace, unknown statement: fix the reported line:column.
+- `frames:` in the body: move it to `film Name(..., frames: N) { ... }`.
+- Missing primitive attributes: `cel`, `layer`, `swarm`, `stroke` need `(...)`,
+  even `()`. `ribbon`, `def` and `use` may omit it. Palette takes `{ key: value }`
+  or `(key: value)`, not a name. `use Name(...)` has **no body**.
+- Invalid/odd Base-63 tail: use only `0-9A-Za-z_`, two characters per delta.
+  Quarter-pixel payloads need whole integer pairs, not decimals or suffixes.
+- Undefined `$colour`: declare it earlier, including before `def` bodies.
+- Duplicate names: intentional layer/cel replacement is legal (JS warns, not errors).
+  Frame overrides replace named layers/cels; same-named strokes/ribbons append,
+  leaving stale ink. For moving ink use cels or time expressions instead.
+- Undefined def, bad sizes/fps, expression variable errors: JS may miss these;
+  use Python full check **and real renders**. No JS success authorizes shipping.

ncel-0.2.1/ncel/data/lantern_film.ncel

@@ -0,0 +1,14 @@
+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)
+}