comicforge 0.0.4__tar.gz → 0.1.0__tar.gz

{comicforge-0.0.4 → comicforge-0.1.0}/.claude/skills/comicforge/SKILL.md

@@ -42,13 +42,19 @@ needs no Python (see [`reference.md`](reference.md)).
    pixel_dir:  "../pixel"
    ```
 3. Validate before rendering: `cmf validate mystrip.yaml` — checks every actor,
-   scene, pixel sprite, slot variant, pose, and bubble speaker against the
-   libraries without drawing anything, and lists *all* problems at once. Unlike
-   `render`, it flags mis-spelled keys (e.g. `fcae:`) that render silently
-   ignores. Exits non-zero when anything is wrong. Works on page and `scene` specs.
+   scene, raster `image:`, pixel sprite, slot variant, pose, and bubble speaker
+   against the libraries without drawing anything, and lists *all* problems at
+   once. Unlike `render`, it flags mis-spelled keys (e.g. `fcae:`, `imge:`) that
+   render silently ignores. Exits non-zero when anything is wrong. Works on page
+   and `scene` specs.
 4. Render:
    - comic page: `cmf render mystrip.yaml -o out.pdf`
    - single illustration: `cmf scene myscene.yaml -o out.png`
+   - one panel of a page (to iterate on a single panel without re-reading the
+     whole page): `cmf panel mystrip.yaml --row 0 --col 1 -o panel.png`
+     (0-indexed; defaults to row 0 col 0), or `--all` to write every panel into a
+     directory. This is the right way to inspect one panel — **do not** render the
+     full page and crop it with ImageMagick or other tooling.
    - one character on its own (to eyeball a pose/expression):
      `cmf character bara sit happy --library examples/pes/characters`
      — extra args are bare pose/variant names or `key=value` (`pose=walk`,
@@ -84,6 +90,7 @@ rows:                             # page is a stack of rows…
       - width: 1.0                # relative panel width (default 1)
         bg: "#fbfaf6"             # optional flat panel background
         scene: dvur               # optional scene background (see below)
+        image: "art/01.png"       # optional raster background (see below)
         actors: [ ... ]           # characters (drawn back→front in list order)
         pixel:  [ ... ]           # pixel-art sprites (drawn behind actors)
         bubbles:[ ... ]           # speech/thought/shout (drawn on top)
@@ -123,22 +130,62 @@ Confirm scenes/slots with `comicforge scenes --scenes <project>/scenes`.
 Seeds in `examples/pes/`: `dvur` (farmyard, slot `weather: clear|rain`),
 `pokoj` (room, no slots). Both live in `examples/pes/scenes/`.
 
+### image (raster panel background)
+
+When the panel art is a finished bitmap — a generated or photographed image
+rather than a `scene:` built from SVG — point the panel at it with `image:`.
+Everything else works unchanged: bubbles, actors and pixel art all compose on
+top of it.
+
+```yaml
+image: "../refs/panels/01.png"          # path, relative to the *spec file*
+image: {src: "01.png", fit: contain}    # or the long form, to pick the fit
+```
+
+- `fit: cover` (the default) scales the image to fill the panel and
+  centre-crops the overflow — a 3:2 image in a 4:3 panel crops rather than
+  distorts, exactly like a `scene:` background.
+- `fit: contain` scales it to fit *inside* the panel; the leftover strips show
+  the panel's `bg:` colour.
+- `.png`, `.jpg`/`.jpeg`, `.gif` and `.webp` are supported.
+- The image is **embedded** as a base64 data URI, so an `.svg` or `.pdf` render
+  is one self-contained file that still works when moved. That also means the
+  output carries the full byte weight of every image on the page — expect large
+  files for a page of full-res panels.
+- `image:` and `scene:` can coexist; the scene draws over the image.
+
+A standalone illustration can be image-backed too — set `type: scene` with an
+`image:` and no `scene:`, and the canvas is sized from the image's own pixel
+dimensions times `scale:` (default `1`, i.e. one output px per image px).
+
+**Where bubbles land on a raster panel.** There are no actors to anchor to, so
+`speaker:` is meaningless — use `x`/`y`/`to` fractions, or leave them out. A
+bubble with no `y` is placed below the measured bottom of the bubble before it,
+starting near the panel top, so any number of bubbles of any length stack
+without overlapping. A bubble with no `x` is horizontally centred. Every
+bubble — explicit or automatic — is then nudged so it stays inside the panel
+(one wider or taller than the panel is centred instead). A generated spec can
+therefore emit dialogue in order and omit the coordinates entirely.
+
 ## Standalone illustration (no comic grid)
 
-Render one scene filling the whole canvas with actors/bubbles on top — good for
-covers and single panels. Render with `comicforge scene file.yaml -o out.png`.
+Render one background filling the whole canvas with actors/bubbles on top —
+good for covers and single panels. Render with
+`comicforge scene file.yaml -o out.png`.
 
 Set `type: scene` so the spec declares which command renders it: `render`
 rejects a scene spec (and `scene` rejects a page spec) with a clear message
 instead of a confusing crash, and `validate` checks the type matches the
 structure. `type:` is optional — when omitted it's inferred (a top-level
-`scene` with no `rows` == a scene) — but declare it on standalone illustrations.
+background — `scene` or `image` — with no `rows` == a scene) — but declare it
+on standalone illustrations.
 
 ```yaml
 title: "Optional"
 type: scene
-scene: {name: dvur, weather: clear}
-scale: 3                    # px per scene unit (canvas = scene viewbox × scale)
+scene: {name: dvur, weather: clear}   # …or `image: cover.png` instead
+scale: 3                    # px per scene unit (canvas = scene viewbox × scale);
+                            # with `image:` it's output px per image px, default 1
 library:    "../characters"
 scenes_dir: "../scenes"
 actors:  [ ... ]            # same actor grammar; x/y/scale are canvas fractions
@@ -154,10 +201,24 @@ bubbles: [ ... ]
   speaker: tom      # OPTIONAL: auto-place above this actor + aim the tail at
                     #           their head. Prefer this over manual x/y/to.
   x: 0.5            # OPTIONAL bubble centre (panel fraction); else from speaker
-  y: 0.18           # OPTIONAL; omit and bubbles stack downward without overlap
+  y: 0.18           # OPTIONAL; omit and bubbles stack downward by measured
+                    #           height, so they never overlap. All bubbles are
+                    #           kept inside the panel.
   to: [0.4, 0.5]    # OPTIONAL tail target (panel fraction); else speaker's head
   max_chars: 22     # wrap width (optional)
-  fs: 16            # font size px (optional)
+  fs: 16            # font size px (optional; overrides bubble_style.font_size)
+  uppercase: true   # OPTIONAL: force this bubble's text to CAPS
+                    #           (overrides bubble_style.uppercase)
+```
+
+**Page-wide bubble defaults** — set `bubble_style` at the *top level* of a
+page or scene spec to style every bubble at once; per-bubble keys override:
+
+```yaml
+bubble_style:
+  uppercase: true   # render all bubble text in CAPS (classic comic lettering)
+  font_size: 16     # default font size px for all bubbles
+rows: [ ... ]
 ```
 
 `thought` draws an ellipse with a trail of dots; `shout` draws a spiky burst.

{comicforge-0.0.4 → comicforge-0.1.0}/.claude/skills/comicforge/reference.md

@@ -435,10 +435,14 @@ renders a default-faced, default-posed actor with no error. `validate` flags:
 - poses an actor asks for that the character lacks
 - slot variants that don't exist for the chosen character+pose / scene
 - actor / scene keys that aren't reserved and aren't a real slot (likely typos)
+- panel keys the renderer doesn't know — `imge:` for `image:`, say
+- raster `image:` files that are missing, unreadable, or of an unsupported type;
+  an `image:` with no `src`, an unknown image key, an unknown `fit`
 - bubble `speaker` naming no actor in the panel; unknown bubble `kind`
 - structural holes (a page with no `rows`, a row with no `panels`, a bubble with
-  no `text`); an unknown `type:`, or a `type:` that contradicts the structure
-  (a `scene` spec carrying `rows`)
+  no `text`, a `scene` spec with neither `scene:` nor `image:`); an unknown
+  `type:`, or a `type:` that contradicts the structure (a `scene` spec carrying
+  `rows`)
 
 Exits `0` when the spec is sound, `1` (with a bulleted problem list) otherwise —
 so it works in a pre-render check or CI.
@@ -589,13 +593,26 @@ Do **not** auto-vectorize the result — hand/LLM-author the SVG using it as a g
 For the full spec grammar, see [SKILL.md](SKILL.md). Key points:
 
 - **Page-level keys**: `title`, `page` (A4/A5/letter/[w,h]), `px_per_mm`,
-  `margin_mm`, `gutter_mm`, `library`, `scenes_dir`, `pixel_dir`
+  `margin_mm`, `gutter_mm`, `library`, `scenes_dir`, `pixel_dir`,
+  `bubble_style` (page-wide bubble defaults: `uppercase`, `font_size`)
 - **Rows and panels**: `rows[].height` (relative weight), `rows[].panels[].width`
-  (relative weight), panel keys: `bg`, `scene`, `actors`, `pixel`, `bubbles`
+  (relative weight), panel keys: `bg`, `scene`, `image`, `actors`, `pixel`,
+  `bubbles` — `validate` flags any other panel key as a typo
+- **Image keys**: `image: path.png` or `image: {src:, fit:}` with
+  `fit: cover` (default; scale-to-fill + centre-crop) or `contain`
+  (fit inside + letterbox). The path resolves against the spec file's dir and
+  the image is embedded as a base64 data URI, so SVG/PDF output stays
+  self-contained. A `type: scene` spec can use `image:` in place of `scene:`,
+  and takes its canvas size from the image
 - **Actor keys**: `char`, `pose` (optional; defaults to the character's default
   pose), per-slot variant keys (`face`, `arms`, etc.), `x`, `y`, `scale`, `flip`
 - **Bubble keys**: `text`, `kind` (speech/thought/shout), `speaker`, optional
-  `x`/`y`/`to`/`max_chars`/`fs`
+  `x`/`y`/`to`/`max_chars`/`fs`/`uppercase` (`fs` and `uppercase` override
+  the page-level `bubble_style`). Omit `y` and bubbles stack down by their
+  measured height without overlapping; omit `x` and they centre (or sit above
+  their `speaker`). Every bubble is kept inside the panel — so a generated spec
+  over raster panels, which has no `speaker` to anchor to, can omit coordinates
+  entirely
 - **Pixel keys**: `art` (library name) or `grid`+`palette`, plus `x`/`y`/`scale`
 
 ---

{comicforge-0.0.4 → comicforge-0.1.0}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcairo2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
 
@@ -70,7 +70,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcairo2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
 

{comicforge-0.0.4 → comicforge-0.1.0}/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v10.0.1
 
       - name: Build sdist + wheel
         run: uv build

{comicforge-0.0.4 → comicforge-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: comicforge
-Version: 0.0.4
+Version: 0.1.0
 Summary: A tiny, scriptable comic-page engine — author comics as YAML, render to SVG / PNG / PDF
 Requires-Python: >=3.13
 Requires-Dist: cairosvg>=2.7

{comicforge-0.0.4 → comicforge-0.1.0}/comicforge/bubbles.py

@@ -26,6 +26,31 @@ def _wrap(text: str, max_chars: int) -> list[str]:
     return lines or [""]
 
 
+def _box(text, max_chars, fs, pad):
+    """Wrap *text* and return (lines, line_height, body_width, body_height)."""
+    lines = _wrap(text, max_chars)
+    lh = fs * 1.25
+    longest = max((len(ln) for ln in lines), default=1)
+    w = max(longest * fs * 0.56 + 2 * pad, 60)
+    h = len(lines) * lh + 2 * pad
+    return lines, lh, w, h
+
+
+# how far each bubble kind's outline reaches beyond the text body box
+_OUTSET = {"thought": (12, 16), "shout": (16, 16)}
+
+
+def bubble_size(text, kind="speech", max_chars=22, fs=16, pad=14):
+    """Outer (width, height) a `bubble` call will occupy, tail excluded.
+
+    `thought` and `shout` draw outside the text body, so callers that stack
+    bubbles or keep them inside a panel need this, not just the body box.
+    """
+    _lines, _lh, w, h = _box(text, max_chars, fs, pad)
+    ow, oh = _OUTSET.get(kind, (0, 0))
+    return w + ow, h + oh
+
+
 def _text_block(lines, cx, top, fs, lh):
     spans = []
     for i, ln in enumerate(lines):
@@ -39,13 +64,8 @@ def _text_block(lines, cx, top, fs, lh):
     )
 
 
-def bubble(text, bx, by, tail=None, kind="speech", max_chars=22,
-           fs=16, pad=14):
-    lines = _wrap(text, max_chars)
-    lh = fs * 1.25
-    longest = max((len(ln) for ln in lines), default=1)
-    w = max(longest * fs * 0.56 + 2 * pad, 60)
-    h = len(lines) * lh + 2 * pad
+def bubble(text, bx, by, tail=None, kind="speech", max_chars=22, fs=16, pad=14):
+    lines, lh, w, h = _box(text, max_chars, fs, pad)
     x, y = bx - w / 2, by - h / 2
     txt = _text_block(lines, bx, y + pad, fs, lh)
 
@@ -53,18 +73,22 @@ def bubble(text, bx, by, tail=None, kind="speech", max_chars=22,
         body = _burst(x, y, w, h)
     elif kind == "thought":
         rx, ry = w / 2 + 6, h / 2 + 8
-        body = (f'<ellipse cx="{bx:.1f}" cy="{by:.1f}" rx="{rx:.1f}" ry="{ry:.1f}" '
-                f'fill="#ffffff" stroke="{INK}" stroke-width="3"/>')
+        body = (
+            f'<ellipse cx="{bx:.1f}" cy="{by:.1f}" rx="{rx:.1f}" ry="{ry:.1f}" '
+            f'fill="#ffffff" stroke="{INK}" stroke-width="3"/>'
+        )
     else:
-        body = (f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
-                f'rx="{min(18, h/2):.1f}" fill="#ffffff" stroke="{INK}" '
-                f'stroke-width="3"/>')
+        body = (
+            f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
+            f'rx="{min(18, h / 2):.1f}" fill="#ffffff" stroke="{INK}" '
+            f'stroke-width="3"/>'
+        )
 
     tail_svg = ""
     if tail is not None:
         tail_svg = _tail(bx, by, w, h, tail, kind)
 
-    return f'<g>{body}{tail_svg}{txt}</g>'
+    return f"<g>{body}{tail_svg}{txt}</g>"
 
 
 def _tail(bx, by, w, h, tail, kind):
@@ -85,9 +109,11 @@ def _tail(bx, by, w, h, tail, kind):
         dots = ""
         for f in (0.45, 0.74, 1.0):
             r = 6 * (1 - f) + 2.5
-            dots += (f'<circle cx="{ex + ux * reach * f:.1f}" '
-                     f'cy="{ey + uy * reach * f:.1f}" r="{r:.1f}" '
-                     f'fill="#ffffff" stroke="{INK}" stroke-width="2.5"/>')
+            dots += (
+                f'<circle cx="{ex + ux * reach * f:.1f}" '
+                f'cy="{ey + uy * reach * f:.1f}" r="{r:.1f}" '
+                f'fill="#ffffff" stroke="{INK}" stroke-width="2.5"/>'
+            )
         return dots
     # narrow tapered tail for speech/shout
     perp = math.atan2(uy, ux) + math.pi / 2
@@ -106,17 +132,23 @@ def _tail(bx, by, w, h, tail, kind):
 def _cloud(x, y, w, h):
     # rounded body + scalloped top edge via overlapping circles
     rx = min(20, h / 2)
-    body = (f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
-            f'rx="{rx:.1f}" fill="#ffffff" stroke="{INK}" stroke-width="3"/>')
+    body = (
+        f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
+        f'rx="{rx:.1f}" fill="#ffffff" stroke="{INK}" stroke-width="3"/>'
+    )
     bumps = ""
     n = max(3, int(w // 34))
     for i in range(n):
         cx = x + (i + 0.5) * w / n
-        bumps += (f'<circle cx="{cx:.1f}" cy="{y:.1f}" r="13" '
-                  f'fill="#ffffff" stroke="{INK}" stroke-width="3"/>')
+        bumps += (
+            f'<circle cx="{cx:.1f}" cy="{y:.1f}" r="13" '
+            f'fill="#ffffff" stroke="{INK}" stroke-width="3"/>'
+        )
     # mask the inner stroke segments by redrawing body fill on top edge
-    cover = (f'<rect x="{x+3:.1f}" y="{y:.1f}" width="{w-6:.1f}" height="14" '
-             f'fill="#ffffff" stroke="none"/>')
+    cover = (
+        f'<rect x="{x + 3:.1f}" y="{y:.1f}" width="{w - 6:.1f}" height="14" '
+        f'fill="#ffffff" stroke="none"/>'
+    )
     return body + bumps + cover + body.replace('fill="#ffffff"', 'fill="none"')
 
 
@@ -129,5 +161,7 @@ def _burst(x, y, w, h):
         a = math.pi * i / n
         rr = 1.0 if i % 2 == 0 else 0.78
         pts.append(f"{cx + math.cos(a) * rx * rr:.1f},{cy + math.sin(a) * ry * rr:.1f}")
-    return (f'<polygon points="{" ".join(pts)}" fill="#ffffff" '
-            f'stroke="{INK}" stroke-width="3" stroke-linejoin="round"/>')
+    return (
+        f'<polygon points="{" ".join(pts)}" fill="#ffffff" '
+        f'stroke="{INK}" stroke-width="3" stroke-linejoin="round"/>'
+    )

{comicforge-0.0.4 → comicforge-0.1.0}/comicforge/cli.py

@@ -323,9 +323,7 @@ def main(argv=None):  # noqa: PLR0912, PLR0915 — flat CLI dispatcher; clearer
             ):
                 rich_print(f"wrote {o}")
         else:
-            out = args.out or _default_out(
-                f"{args.spec.stem}-r{args.row}c{args.col}"
-            )
+            out = args.out or _default_out(f"{args.spec.stem}-r{args.row}c{args.col}")
             render_panel(
                 args.spec,
                 out,

comicforge-0.1.0/comicforge/raster.py

@@ -0,0 +1,149 @@
+"""Embed a raster image (PNG / JPEG / GIF / WebP) as a panel background.
+
+A panel's ``image:`` is the bitmap counterpart of ``scene:``: instead of an SVG
+base plus stackable overlays, one finished picture fills the panel.  It is
+scaled to *cover* the panel and centre-cropped — the same behaviour
+:func:`comicforge.scene.cover` gives a vector scene — so a 3:2 image in a 4:3
+panel crops rather than distorts.  ``fit: contain`` letterboxes it instead.
+
+The image is embedded as a base64 ``data:`` URI rather than linked, so an
+``.svg`` / ``.pdf`` render is a single self-contained file that keeps working
+when it is moved or mailed.  That does mean the output carries the full weight
+of every image it uses.
+
+Cropping is done by the panel's clip path (see ``render._render_panel``), which
+every panel and standalone scene already establishes.
+"""
+
+from __future__ import annotations
+
+import struct
+from base64 import b64encode
+from pathlib import Path
+
+MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+# fit name -> SVG preserveAspectRatio: 'slice' crops the overflow, 'meet' fits
+# the whole image inside the box and letterboxes the remainder.
+FITS = {"cover": "xMidYMid slice", "contain": "xMidYMid meet"}
+
+
+def normalize(value) -> dict:
+    """Normalise a panel's ``image:`` value to a ``{src, fit}``-shaped dict.
+
+    Accepts the short form (``image: art/01.png``) and the long form
+    (``image: {src: art/01.png, fit: contain}``).
+    """
+    if isinstance(value, str):
+        return {"src": value}
+    if isinstance(value, dict):
+        return value
+    raise ValueError(
+        f"image must be a path or a {{src, fit}} mapping, got {type(value).__name__}"
+    )
+
+
+def resolve(value, spec_dir: Path | None) -> Path:
+    """Resolve an ``image:`` value to a path, relative to the spec file's dir.
+
+    Mirrors ``render._resolve_dir``: relative paths resolve against *spec_dir*
+    when it is known (i.e. the spec came from a file), absolute ones are used
+    as-is.
+    """
+    src = normalize(value).get("src")
+    if not src:
+        raise ValueError("image entry has no 'src' (use `image: path/to/art.png`)")
+    p = Path(src)
+    if not p.is_absolute() and spec_dir is not None:
+        p = spec_dir / p
+    return p.resolve()
+
+
+def data_uri(path: Path) -> str:
+    """Read *path* and return it as a base64 ``data:`` URI."""
+    mime = MIME.get(path.suffix.lower())
+    if mime is None:
+        raise ValueError(
+            f"unsupported image type '{path.suffix}' for {path}. "
+            f"Supported: {sorted(MIME)}"
+        )
+    return f"data:{mime};base64,{b64encode(path.read_bytes()).decode('ascii')}"
+
+
+def size(path: Path) -> tuple[int, int]:
+    """Read *path*'s pixel dimensions straight out of its header.
+
+    Only the header is parsed — no image library, so ComicForge stays a
+    three-dependency package.  A standalone ``type: scene`` spec backed by an
+    ``image:`` needs this to size its canvas; a panel does not (the panel box
+    already has a size, and ``preserveAspectRatio`` does the fitting).
+    """
+    head = path.read_bytes()[:64]
+    try:
+        if head.startswith(b"\x89PNG\r\n\x1a\n"):
+            return struct.unpack(">II", head[16:24])  # IHDR width, height
+        if head.startswith(b"GIF8"):
+            return struct.unpack("<HH", head[6:10])
+        if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+            return _webp_size(head)
+        if head.startswith(b"\xff\xd8"):
+            return _jpeg_size(path)
+    except (struct.error, IndexError, ValueError) as e:
+        raise ValueError(f"cannot read image dimensions from {path}: {e}") from e
+    raise ValueError(f"cannot read image dimensions from {path}: unrecognised header")
+
+
+def _webp_size(head: bytes) -> tuple[int, int]:
+    fmt = head[12:16]
+    if fmt == b"VP8X":
+        w = int.from_bytes(head[24:27], "little") + 1
+        h = int.from_bytes(head[27:30], "little") + 1
+        return w, h
+    if fmt == b"VP8L":
+        bits = int.from_bytes(head[21:25], "little")
+        return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
+    if fmt == b"VP8 ":
+        w, h = struct.unpack("<HH", head[26:30])
+        return w & 0x3FFF, h & 0x3FFF
+    raise ValueError(f"unknown WebP variant {fmt!r}")
+
+
+# JPEG start-of-frame markers carry the dimensions; DHP/DAC/RSTn do not.
+_SOF = {*range(0xC0, 0xD0)} - {0xC4, 0xC8, 0xCC}
+
+
+def _jpeg_size(path: Path) -> tuple[int, int]:
+    """Walk the JPEG segment chain to the first start-of-frame marker."""
+    with path.open("rb") as fh:
+        fh.read(2)  # SOI
+        while True:
+            byte = fh.read(1)
+            while byte == b"\xff":  # markers may be padded with 0xff
+                byte = fh.read(1)
+            if not byte:
+                raise ValueError("no start-of-frame marker")
+            marker = byte[0]
+            (length,) = struct.unpack(">H", fh.read(2))
+            if marker in _SOF:
+                _precision, h, w = struct.unpack(">BHH", fh.read(5))
+                return w, h
+            fh.seek(length - 2, 1)
+
+
+def place(value, spec_dir: Path | None, px, py, pw, ph) -> str:
+    """Place an ``image:`` value so it covers the (px, py, pw, ph) box, centred."""
+    fit = normalize(value).get("fit", "cover")
+    par = FITS.get(fit)
+    if par is None:
+        raise ValueError(f"unknown image fit '{fit}'. Use one of {sorted(FITS)}")
+    uri = data_uri(resolve(value, spec_dir))
+    return (
+        f'<image x="{px:.1f}" y="{py:.1f}" width="{pw:.1f}" height="{ph:.1f}" '
+        f'preserveAspectRatio="{par}" href="{uri}"/>'
+    )