Source code for tangl.story.episode.action

from __future__ import annotations

from typing import Any

from pydantic import field_serializer

from tangl.journal.intent import Accepts, Blocker, UIHints
from tangl.vm import ResolutionPhase, TraversableEdge




class Action(TraversableEdge):
    """Action()

    Traversable choice edge connecting story blocks.

    Why
    ----
    ``Action`` carries both user-facing choice text and authored successor
    semantics, allowing the compiler and materializer to preserve the narrative
    meaning of redirects, continuations, and interactive choices.
    """

    text: str = ""
    successor_ref: str | None = None
    activation: str | None = None
    payload: Any = None
    accepts: Accepts | None = None
    blockers: list[Blocker] | None = None
    ui_hints: UIHints | None = None
    journal_text: str | None = None

    @field_serializer("accepts")
    def _serialize_accepts(self, accepts: Accepts | None) -> dict[str, Any] | None:
        if accepts is None:
            return None
        return accepts.model_dump(mode="python", by_alias=True, exclude_none=True)

    @classmethod
    def trigger_phase_from_activation(cls, activation: str | None) -> ResolutionPhase | None:
        """Map authored activation shorthands to vm resolution phases."""
        if activation == "first":
            return ResolutionPhase.PREREQS
        if activation == "last":
            return ResolutionPhase.POSTREQS
        return None