"""seams.py — documented efferent seams for IMAGE and VIDEO surfaces.

These are NOT implemented (per the build rails: architect, do not overbuild).
They are registered as first-class seams so the interface PROVES it accepts
future non-text projectors without any upstream change. Each documents exactly
what its decoder would read from the geometry-carrying IR, making the multimodal
generalization concrete rather than hand-wavy.

The symmetry that guarantees these are possible, not moonshots: they are the
efferent twins of multimodal INGEST. If meaning can HOLD an image (ingest as
first-class geometry), meaning can PROJECT one back. Video = image x sound x
TIME, and the engram already stores time (chronoception). So video falls out of
an image projector + the music projector + the stored temporal ordering.
"""
from __future__ import annotations

import os
import sys

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from document_ir import DocumentIR  # noqa: E402
from projectors.base import register  # noqa: E402


class _Seam:
    """A registered-but-unimplemented projector. Names its decoder contract."""

    def project(self, doc: DocumentIR) -> bytes:  # pragma: no cover - seam
        raise NotImplementedError(
            f"{self.surface!r} projector is a documented seam, not yet built. "
            f"Decoder contract: {self.decoder_contract}")


class ImageProjector(_Seam):
    surface = "image"
    media_type = "image/png"
    ext = "png"
    modality = "image"
    decoder_contract = (
        "reads block.provenance as a spatial layout — nodes become regions, edges "
        "become adjacencies; salience/importance drive size/contrast; polarity "
        "drives figure/ground. The efferent twin of image ingest (a geometry->raster "
        "decoder, learned or engineered), exactly mirroring the embedder that turned "
        "the image INTO geometry.")


class VideoProjector(_Seam):
    surface = "video"
    media_type = "video/mp4"
    ext = "mp4"
    modality = "video"
    decoder_contract = (
        "image x sound x TIME. Composes the image projector (per-keyframe geometry "
        "layout) with the midi/music projector (score) along the geometry's stored "
        "temporal ordering (chronoception). Needs no new principle once image + music "
        "exist — only a muxer.")


register(ImageProjector())
register(VideoProjector())