deckicorn 0.2.0__py3-none-any.whl

deckicorn-0.2.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: deckicorn
+Version: 0.2.0
+Summary: Spec-driven presentation runtime
+Project-URL: Documentation, https://deckicorn.org
+Project-URL: Repository, https://gitlab.com/libesys/deckicorn/deckicorn-cli
+Project-URL: Changelog, https://deckicorn.org/blog
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.4; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Provides-Extra: runtime
+Requires-Dist: arcade<4,>=3.0; extra == "runtime"
+Provides-Extra: packaging
+Requires-Dist: pyinstaller>=6.0; extra == "packaging"
+
+# Deckicorn
+
+Spec-driven presentation runtime: compile Markdown decks + layout YAML into a canonical presentation spec, then render with a 2D (Arcade) runtime.
+
+## Documentation
+
+- **Public site:** [deckicorn.org](https://deckicorn.org) (Docusaurus + Sphinx API reference)
+- ADR overview: [`docs/README-deckicorn-adr.md`](docs/README-deckicorn-adr.md)
+- Presentation spec: [`docs/SPEC-presentation-spec.md`](docs/SPEC-presentation-spec.md)
+- Deckicorn MD dialect: [`docs/SPEC-deckicorn-md-dialect.md`](docs/SPEC-deckicorn-md-dialect.md)
+- Deck project manifest: [`docs/SPEC-deckicorn-project-manifest.md`](docs/SPEC-deckicorn-project-manifest.md)
+- Implementation plan: [`plan/deckicorn-implementation-plan.md`](plan/deckicorn-implementation-plan.md)
+- AI workflow rules: [`tools/ai-rules/`](tools/ai-rules/)
+
+## Git workflow
+
+Day-to-day work happens on **`develop`**; **`master`** is ff-merged when Development CI is green (A2C `development-workflow.md`).
+
+```bash
+git checkout develop
+```
+
+## Quick start
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+pre-commit install --hook-type commit-msg
+```
+
+From a deck project directory (see `examples/deckicorn-hello/deckicorn.yaml`):
+
+```bash
+cd examples/deckicorn-hello
+deckicorn build
+deckicorn preview          # requires pip install -e ".[runtime]"
+deckicorn preview --show-bounds
+deckicorn package --clean  # requires pip install -e ".[runtime,packaging]"
+```
+
+Ad hoc paths (without `deckicorn.yaml`):
+
+```bash
+deckicorn build examples/deckicorn-hello/deck.md \
+  --layout examples/deckicorn-hello/layout-default.yaml \
+  --out examples/deckicorn-hello/build/deck-spec.yaml
+deckicorn run examples/deckicorn-hello/build/deck-spec.yaml
+```
+
+## Changelog and pre-commit
+
+This repository follows A2C changelog policy (`tools/ai-rules/rules/11-changelog-policy.md`):
+
+- Maintain `CHANGELOG.md` in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+- Curate `## [Unreleased]` as release-relevant work lands.
+- Stage `CHANGELOG.md` with any commit that changes other files (`check-changelog` hook).
+
+Version source: root `VERSION` (kept in sync with `pyproject.toml` and `deckicorn_spec.__version__` at release time).
+
+Release workflow: [docs/release-pipeline.md](docs/release-pipeline.md).
+
+## Project layout
+
+| Path | Purpose |
+|------|---------|
+| `docs/` | ADRs and specs (canonical) |
+| `inputs/` | Read-only intake copies of source docs |
+| `deckicorn-spec` (`src/deckicorn_spec`) | Presentation spec models and validation |
+| `deckicorn-md` (`src/deckicorn_md`) | Deckicorn MD parser and compiler |
+| `deckicorn-runtime` (`src/deckicorn_runtime`) | Presentation runtime |
+| `examples/` | Documented deck projects (`deckicorn-hello/`, …) |
+| `tests/fixtures/decks/` | Broken manifest fixtures for CI and unit tests |

deckicorn-0.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+deckicorn_cli/main.py,sha256=Ww19G53xeiupDYXmJecAMb3z-RJJWBKFZf-mZo2mT3Q,5294
+deckicorn_md/__init__.py,sha256=HgbQlIweC0Z8ntFD8VPKQhGhalLpc9SMs3glkgBB9C4,350
+deckicorn_md/compiler.py,sha256=9RtrrEhI1Nr1EcuxQUp-vykTwHTFCaq7_G4fNANXvEo,8851
+deckicorn_md/parser.py,sha256=71mDbyvkYJ8l3vBdZwVuYM25gW6aGpt9yDTz_b9Fjvk,4941
+deckicorn_project/__init__.py,sha256=2kID3nocuDEbjjv6aVU17OxnPzxfgTperJpssqtW_Po,282
+deckicorn_project/manifest.py,sha256=Nd3mHNDDsDUl4dsTb4K_mUoqQuL6MKT92gCf7OpSh6M,5220
+deckicorn_project/packaging.py,sha256=3J2rC7ReyBG1zaspzAlAheyVNQiJ4aWa-ngzP17oS6U,5643
+deckicorn_project/pyinstaller/hooks/hook-arcade.py,sha256=31WfAMKo1ttR9ihxR9rBbzmk-mtXEoe6gqI6ZKydIIA,1629
+deckicorn_runtime/__init__.py,sha256=ASB4zVOpKzA30fiVOx6JYRsUWSa6kaE6T3nnsZB0NWM,359
+deckicorn_runtime/arcade_app.py,sha256=1lMzt-6gbiDDLm-5dnt7CbxMvh4ixHYjS4dH2s1RMro,8451
+deckicorn_runtime/bounds_overlay.py,sha256=-g1zBhQipaJO7LnxrlP2l2ieY0OYTPbS287jwslK4NE,3020
+deckicorn_runtime/console.py,sha256=ttSzzf4PE6Rta_csDRSoQIckIMpa57PV0bEe1ApIYHM,1705
+deckicorn_runtime/coords.py,sha256=W0bx5TUapfu47Sdoka73A7PsYkctkf4JabtvUFql8g4,2365
+deckicorn_runtime/navigation.py,sha256=-_gcjuDMI0R0U3Q2VdDsCDv3K1hPt8SD9dYlCBeD4T8,2443
+deckicorn_runtime/preview_options.py,sha256=KtbSwTJJjiNJT7YvJdzxrs_lf8ReiIeHvafq4PlxTcI,4747
+deckicorn_runtime/resources.py,sha256=LF6pc_UlhKaBQcb19QE2kDLk-h3dnRh61-Oxt3dFayk,790
+deckicorn_spec/__init__.py,sha256=ihOkfrYgsNVlI5XS18Wbaf74tPA9lLwp6E3RfOGFtt0,558
+deckicorn_spec/io.py,sha256=Q6eUl4ynHYmv-KQ9Us0dGMXe_PnBGr6Cbs_5j6jfBX8,1421
+deckicorn_spec/models.py,sha256=N7QPQ13YwJS93dBu2argryGGMwNlXeL8yvm3pmwbpnw,4507
+deckicorn_spec/validate.py,sha256=kGR4J5nmHEcR8FbchSIMU9rEnwFhU0MVgWINL8md4iE,4156
+deckicorn-0.2.0.dist-info/METADATA,sha256=C59GBx2diwRjkillTabyBmM7gQWCprJ4UL8RtKCCS5Q,3689
+deckicorn-0.2.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+deckicorn-0.2.0.dist-info/entry_points.txt,sha256=oOh-1CGVwkb3De8yuRanveJZ3tOzQnBo8OIy9fybu3M,54
+deckicorn-0.2.0.dist-info/top_level.txt,sha256=jONsaW23CidLtM0_3tm4ab6HUjAObzxLK96BqlZ7x68,78
+deckicorn-0.2.0.dist-info/RECORD,,

deckicorn-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deckicorn-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+deckicorn = deckicorn_cli.main:main

deckicorn-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+deckicorn_cli
+deckicorn_md
+deckicorn_project
+deckicorn_runtime
+deckicorn_spec

deckicorn_cli/main.py

@@ -0,0 +1,155 @@
+"""Deckicorn toolchain CLI (ADR-019)."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from deckicorn_md.compiler import compile_files
+from deckicorn_project.manifest import (
+    MANIFEST_NAME,
+    ensure_paths_exist,
+    load_project,
+    resolve_project_root,
+)
+from deckicorn_project.packaging import package_presentation
+from deckicorn_runtime.console import run_presentation_file as run_console_presentation_file
+from deckicorn_runtime.preview_options import add_preview_arguments
+from deckicorn_spec.io import save_presentation_file
+
+
+def _add_project_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--project",
+        type=Path,
+        default=None,
+        help="Deck project root containing deckicorn.yaml (default: current directory)",
+    )
+
+
+def _load_resolved(args: argparse.Namespace):
+    root = resolve_project_root(args.project)
+    return load_project(root)
+
+
+def _manifest_available(project: Path | None = None) -> bool:
+    root = (project or Path.cwd()).resolve()
+    return (root / MANIFEST_NAME).is_file()
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    if args.md is not None:
+        if not args.layout or not args.out:
+            raise SystemExit("build requires --layout and --out when not using a deck project")
+        md_path = Path(args.md)
+        layout_path = Path(args.layout)
+        out_path = Path(args.out)
+    else:
+        project = _load_resolved(args)
+        ensure_paths_exist(project)
+        md_path = project.content
+        layout_path = project.layout
+        out_path = project.build_spec
+
+    presentation = compile_files(md_path, layout_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    save_presentation_file(presentation, out_path)
+    print(f"Wrote {out_path}")
+    return 0
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    if args.spec is not None:
+        spec_path = Path(args.spec)
+    else:
+        project = _load_resolved(args)
+        ensure_paths_exist(project, need_spec=True)
+        spec_path = project.build_spec
+
+    run_console_presentation_file(str(spec_path))
+    return 0
+
+
+def _cmd_preview(args: argparse.Namespace) -> int:
+    from deckicorn_runtime.arcade_app import run_arcade_presentation
+    from deckicorn_runtime.preview_options import preview_options_from_args, profile_bounds_defaults
+
+    bounds_style = profile_bounds_defaults("minimal")
+    if args.spec is not None:
+        spec_path = Path(args.spec)
+        asset_root = spec_path.parent
+    else:
+        project = _load_resolved(args)
+        ensure_paths_exist(project, need_spec=True)
+        spec_path = project.build_spec
+        asset_root = project.root
+        bounds_style = project.preview_bounds
+
+    options = preview_options_from_args(args, bounds=bounds_style)
+    run_arcade_presentation(
+        spec_path,
+        asset_root=asset_root,
+        width=options.width,
+        height=options.height,
+        show_element_bounds=options.show_bounds,
+        bounds_style=options.bounds,
+    )
+    return 0
+
+
+def _cmd_package(args: argparse.Namespace) -> int:
+    project = _load_resolved(args)
+    binary = package_presentation(project, clean=args.clean)
+    print(f"Built {binary}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="deckicorn", description="Deckicorn toolchain CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    build = sub.add_parser("build", help="Compile MD + layout into presentation spec YAML")
+    build.add_argument("md", nargs="?", help="Deckicorn MD deck file")
+    build.add_argument("--layout", help="Layout overlay YAML")
+    build.add_argument("--out", help="Output presentation spec YAML")
+    _add_project_arg(build)
+    build.set_defaults(func=_cmd_build)
+
+    run = sub.add_parser("run", help="Run a presentation spec (console mode)")
+    run.add_argument("spec", nargs="?", help="Presentation spec YAML")
+    _add_project_arg(run)
+    run.set_defaults(func=_cmd_run)
+
+    preview = sub.add_parser("preview", help="Preview a presentation spec in an Arcade window")
+    preview.add_argument("spec", nargs="?", help="Presentation spec YAML")
+    add_preview_arguments(preview)
+    _add_project_arg(preview)
+    preview.set_defaults(func=_cmd_preview)
+
+    package = sub.add_parser("package", help="Package a deck project into a standalone executable")
+    package.add_argument("--clean", action="store_true", help="Remove prior build artifacts first")
+    _add_project_arg(package)
+    package.set_defaults(func=_cmd_package)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "build" and args.md is None and not _manifest_available(args.project):
+        parser.error(
+            "build requires a deck MD path, or run from a directory containing deckicorn.yaml "
+            "(or pass --project)",
+        )
+    if (
+        args.command in {"run", "preview"}
+        and getattr(args, "spec", None) is None
+        and not _manifest_available(args.project)
+    ):
+        parser.error(
+            f"{args.command} requires a spec path, or run from a directory containing "
+            "deckicorn.yaml (or pass --project)",
+        )
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

deckicorn_md/__init__.py

@@ -0,0 +1,12 @@
+"""Deckicorn MD parser and compiler (ADR-013)."""
+
+from deckicorn_md.compiler import compile_files, compile_presentation
+from deckicorn_md.parser import ContentDeck, parse_deckicorn_md, parse_deckicorn_md_file
+
+__all__ = [
+    "ContentDeck",
+    "compile_files",
+    "compile_presentation",
+    "parse_deckicorn_md",
+    "parse_deckicorn_md_file",
+]

deckicorn_md/compiler.py

@@ -0,0 +1,286 @@
+"""Compile content AST + layout overlay into presentation spec (ADR-013, ADR-016)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from deckicorn_md.parser import ContentDeck, ContentSlide, parse_deckicorn_md
+from deckicorn_spec.models import (
+    Action,
+    Assets,
+    Element,
+    Interaction,
+    Layout,
+    LayoutRegion,
+    Meta,
+    Presentation,
+    Size3,
+    Slide,
+    SlideBackground,
+    Style,
+    Theme,
+    Trigger,
+    Vec3,
+)
+from deckicorn_spec.validate import validate_presentation
+
+
+def _load_layout_overlay(path: str | Path) -> dict[str, Any]:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+
+
+def _normalize_region(
+    position: dict[str, float],
+    size: dict[str, float],
+    width: float,
+    height: float,
+) -> tuple[Vec3, Size3]:
+    """Convert pixel top-left coords to normalized bottom-left (ADR-018)."""
+    x = float(position.get("x", 0))
+    y = float(position.get("y", 0))
+    w = float(size.get("w", 0))
+    h = float(size.get("h", 0))
+    return (
+        Vec3(x=x / width, y=(height - y - h) / height, z=float(position.get("z", 0))),
+        Size3(w=w / width, h=h / height),
+    )
+
+
+def _overlay_layouts(overlay: dict[str, Any]) -> list[Layout]:
+    coords = overlay.get("coords", {})
+    width = float(coords.get("width", 1920))
+    height = float(coords.get("height", 1080))
+    layouts: list[Layout] = []
+    for item in overlay.get("layouts", []):
+        regions: dict[str, LayoutRegion] = {}
+        for name, region in item.get("regions", {}).items():
+            pos, size = _normalize_region(region["position"], region["size"], width, height)
+            regions[name] = LayoutRegion(
+                position=pos,
+                size=size,
+                style=region.get("style"),
+            )
+        background = None
+        if "background" in item:
+            bg = item["background"]
+            background = SlideBackground(
+                color=bg.get("color"),
+                image=bg.get("image"),
+                image_mode=bg.get("image_mode"),
+            )
+        layouts.append(
+            Layout(
+                id=item["id"],
+                name=item.get("name"),
+                description=item.get("description"),
+                background=background,
+                regions=regions,
+            )
+        )
+    return layouts
+
+
+def _overlay_styles(overlay: dict[str, Any]) -> dict[str, Style]:
+    raw = overlay.get("styles", {})
+    return {name: Style.model_validate(values) for name, values in raw.items()}
+
+
+def _overlay_assets(overlay: dict[str, Any]) -> Assets:
+    raw = overlay.get("assets", {})
+    return Assets.model_validate(raw)
+
+
+def _overlay_theme(overlay: dict[str, Any]) -> Theme | None:
+    theme_data = overlay.get("theme")
+    if not theme_data:
+        return None
+    mapped = dict(theme_data)
+    font = mapped.pop("font", None)
+    if font:
+        mapped.setdefault("font_family", font.get("body"))
+        mapped.setdefault("heading_font_family", font.get("heading"))
+    return Theme.model_validate(mapped)
+
+
+def _text_element(
+    element_id: str,
+    region: LayoutRegion,
+    text: str,
+    style: str | None,
+) -> Element:
+    return Element(
+        id=element_id,
+        type="text",
+        position=region.position,
+        size=region.size,
+        style=style or region.style,
+        props={"text": text, "wrap": True},
+    )
+
+
+def _body_text(slide: ContentSlide) -> str:
+    return "\n".join(line for line in slide.body_lines if line is not None).strip()
+
+
+def _compile_title_slide(
+    slide: ContentSlide,
+    deck: ContentDeck,
+    layout: Layout,
+    defaults: dict[str, Any],
+) -> Slide:
+    bindings = defaults.get("bindings", {})
+    elements: list[Element] = []
+
+    title_region = layout.regions.get(bindings.get("deck_title", "title"))
+    if title_region and slide.title:
+        elements.append(_text_element("title", title_region, slide.title, title_region.style))
+
+    subtitle_region = layout.regions.get(bindings.get("deck_subtitle", "subtitle"))
+    subtitle_text = slide.subtitle or deck.meta.title
+    if subtitle_region and subtitle_text:
+        elements.append(
+            _text_element("subtitle", subtitle_region, subtitle_text, subtitle_region.style)
+        )
+
+    meta_region = layout.regions.get(bindings.get("deck_meta", "meta"))
+    if meta_region and slide.meta_lines:
+        elements.append(
+            _text_element(
+                "meta",
+                meta_region,
+                "\n".join(slide.meta_lines),
+                meta_region.style,
+            )
+        )
+
+    background = layout.background
+    return Slide(
+        id=slide.meta.id or "title",
+        title=slide.title,
+        layout=layout.id,
+        background=background,
+        elements=elements,
+        interactions=[_default_prev_interaction(), _default_next_interaction()],
+    )
+
+
+def _compile_content_slide(
+    slide: ContentSlide,
+    layout: Layout,
+    defaults: dict[str, Any],
+    page_number: int,
+    deck_title: str,
+) -> Slide:
+    bindings = defaults.get("bindings", {})
+    elements: list[Element] = []
+
+    header_region = layout.regions.get(bindings.get("slide_title", "header"))
+    if header_region and slide.title:
+        elements.append(_text_element("header", header_region, slide.title, header_region.style))
+
+    body_region = layout.regions.get(bindings.get("slide_body", "body"))
+    body = _body_text(slide)
+    if body_region and body:
+        elements.append(_text_element("body", body_region, body, body_region.style))
+
+    footer_region = layout.regions.get(bindings.get("slide_footer", "footer"))
+    footer_text = f"{deck_title} - Page {page_number}"
+    if footer_region:
+        elements.append(_text_element("footer", footer_region, footer_text, footer_region.style))
+
+    return Slide(
+        id=slide.meta.id or f"slide-{page_number}",
+        title=slide.title,
+        layout=layout.id,
+        background=layout.background,
+        elements=elements,
+        interactions=[_default_prev_interaction(), _default_next_interaction()],
+    )
+
+
+def _default_prev_interaction() -> Interaction:
+    return Interaction(
+        id="prev_on_left",
+        trigger=Trigger(type="key", key="LEFT"),
+        action=Action(type="goto_slide", target="prev"),
+    )
+
+
+def _default_next_interaction() -> Interaction:
+    return Interaction(
+        id="next_on_right",
+        trigger=Trigger(type="key", key="RIGHT"),
+        action=Action(type="goto_slide", target="next"),
+    )
+
+
+def _resolve_layout(
+    layout_id: str | None,
+    layouts_by_id: dict[str, Layout],
+    overlay_defaults: dict[str, Any],
+) -> tuple[Layout, dict[str, Any]]:
+    if layout_id == "title_slide" or layout_id == overlay_defaults.get("title_slide", {}).get(
+        "layout"
+    ):
+        key = "title_slide"
+    else:
+        key = "content_slide"
+    defaults = overlay_defaults.get(key, {})
+    resolved_id = layout_id or defaults.get("layout", "content")
+    layout = layouts_by_id.get(resolved_id)
+    if layout is None:
+        raise ValueError(f"Unknown layout id: {resolved_id}")
+    return layout, defaults
+
+
+def compile_presentation(
+    deck: ContentDeck,
+    layout_overlay: dict[str, Any],
+) -> Presentation:
+    """Apply layout overlay to content AST and produce a presentation spec."""
+    layouts = _overlay_layouts(layout_overlay)
+    layouts_by_id = {layout.id: layout for layout in layouts}
+    overlay_defaults = layout_overlay.get("defaults", {})
+
+    slides: list[Slide] = []
+    content_page = 0
+    for slide in deck.slides:
+        layout_id = slide.meta.layout
+        layout, defaults = _resolve_layout(layout_id, layouts_by_id, overlay_defaults)
+        if layout.id == overlay_defaults.get("title_slide", {}).get("layout", "title_slide"):
+            slides.append(_compile_title_slide(slide, deck, layout, defaults))
+        else:
+            content_page += 1
+            slides.append(
+                _compile_content_slide(
+                    slide,
+                    layout,
+                    defaults,
+                    content_page,
+                    deck.meta.title or deck.meta.id,
+                )
+            )
+
+    presentation = Presentation(
+        version="0.1.0",
+        meta=Meta(
+            id=deck.meta.id,
+            title=deck.meta.title,
+        ),
+        theme=_overlay_theme(layout_overlay),
+        layouts=layouts,
+        styles=_overlay_styles(layout_overlay),
+        assets=_overlay_assets(layout_overlay),
+        slides=slides,
+    )
+    validate_presentation(presentation)
+    return presentation
+
+
+def compile_files(md_path: str | Path, layout_path: str | Path) -> Presentation:
+    deck = parse_deckicorn_md(Path(md_path).read_text(encoding="utf-8"))
+    overlay = _load_layout_overlay(layout_path)
+    return compile_presentation(deck, overlay)