walkthru 0.0.2__py3-none-any.whl

walkthru/__init__.py

@@ -0,0 +1,114 @@
+"""walkthru — editable, re-renderable demo/tour artifacts from a command sequence.
+
+walkthru owns the *representation* (the Demo Document) and a tiny pure playback/capture
+engine, ``play(demoDoc, executor, observers)``. It never renders the final video — it hands a
+validated artifact to a renderer (the ``reelee`` ecosystem, Remotion, moviepy/ffmpeg). Owning
+representation, not pixels, is the load-bearing boundary of the design.
+
+Two modes share one data model and one engine: *generative* (an author supplies the document;
+walkthru plays it while recording) and *capture* (a human drives; walkthru records the video
+and the underlying command stream into the same document).
+
+See ``PLAN.md``, ``DECISIONS.md``, and the repository's enhancement issues for the design and
+its running development journal. This package currently holds the Python side (schema SSOT +
+core + render hand-off); the live capture/play engine ships separately as ``acture-walkthru``.
+
+Quickstart::
+
+    import asyncio
+    from walkthru import DemoDocument, Section, CommandStep, Command, Timing, play
+
+    doc = DemoDocument(
+        id="demo",
+        sections=[Section(id="s1", steps=[
+            CommandStep(id="step-1", command=Command(id="app.open"), timing=Timing(duration_ms=500)),
+        ])],
+    )
+
+    async def executor(command):
+        print("run", command.id)
+        return {"ok": True}
+
+    asyncio.run(play(doc, executor))
+"""
+
+from walkthru.core import (  # noqa: F401
+    Anchor,
+    AssetRef,
+    Beat,
+    CalloutCue,
+    Command,
+    CommandInvocation,
+    CommandStep,
+    Cue,
+    CursorCue,
+    DemoDocument,
+    Event,
+    HighlightCue,
+    HotspotCue,
+    Locator,
+    Meta,
+    NarrationSegment,
+    Observer,
+    Outcome,
+    Rect,
+    ResolvedCamera,
+    ResolvedCue,
+    ResolvedNarration,
+    ResolvedStep,
+    Section,
+    SpotlightCue,
+    Step,
+    Target,
+    Timeline,
+    Timing,
+    Tracks,
+    demo_document_json_schema,
+    iter_events,
+    iter_resolved_steps,
+    play,
+    record,
+    resolve_timeline,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "__version__",
+    "play",
+    "record",
+    "iter_events",
+    "resolve_timeline",
+    "iter_resolved_steps",
+    "Timeline",
+    "ResolvedStep",
+    "ResolvedCue",
+    "ResolvedNarration",
+    "ResolvedCamera",
+    "demo_document_json_schema",
+    "DemoDocument",
+    "Meta",
+    "Section",
+    "Step",
+    "CommandStep",
+    "Beat",
+    "Command",
+    "Timing",
+    "Anchor",
+    "Target",
+    "Locator",
+    "Rect",
+    "Tracks",
+    "Cue",
+    "HighlightCue",
+    "SpotlightCue",
+    "HotspotCue",
+    "CalloutCue",
+    "CursorCue",
+    "NarrationSegment",
+    "AssetRef",
+    "Event",
+    "Observer",
+    "Outcome",
+    "CommandInvocation",
+]

walkthru/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""Optional, isolated port implementations — the firewall's outer ring.
+
+Each adapter implements one or more :mod:`walkthru.ports` against a concrete tool (Playwright,
+OBS/ffmpeg, WhisperX, Piper, driver.js, ...). Adapters depend on ports, **never the reverse**, and
+the core never imports anything from here. Each adapter's heavy dependency is an *optional* extra,
+so installing walkthru's core pulls in no vendor SDK.
+
+No adapters are implemented yet — the web-first generative path (Playwright player/recorder/
+locator + driver.js cues) is MVP Stage 3. See ``PLAN.md`` §3.4 and issue #5.
+"""

walkthru/adapters/export/__init__.py

@@ -0,0 +1,16 @@
+"""Dependency-free export targets — the renderer hand-off and caption sidecars.
+
+These adapters turn a validated Demo Document into the artifacts a renderer or player consumes.
+They depend only on the core (schema + :mod:`timeline <walkthru.core.timeline>`), never the reverse,
+and pull in no vendor dependency — so they sit behind the ports firewall yet need no optional extra.
+
+* :class:`JsonArtifactTarget` / :func:`to_json` — the frozen JSON projection of the Demo Document,
+  the brief's *primary* renderer contract (the renderer owns pixels; we own representation).
+* :func:`narration_to_webvtt` — WebVTT captions derived from the narration track, "nearly free"
+  from the resolved timeline.
+"""
+
+from walkthru.adapters.export.json_target import JsonArtifactTarget, to_json
+from walkthru.adapters.export.webvtt import narration_to_webvtt
+
+__all__ = ["JsonArtifactTarget", "to_json", "narration_to_webvtt"]

walkthru/adapters/export/json_target.py

@@ -0,0 +1,40 @@
+"""The frozen JSON projection — walkthru's primary renderer hand-off.
+
+The boundary the whole design rests on: walkthru owns the *representation* (the Demo Document) and
+hands a renderer a validated JSON artifact; the renderer owns the pixels and may ignore anything it
+does not understand. :class:`JsonArtifactTarget` is the reference :class:`~walkthru.ports.RenderTarget`
+that emits exactly that artifact.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from walkthru.core.schema import AssetRef, DemoDocument
+
+
+def to_json(document: DemoDocument, *, indent: int | None = 2) -> str:
+    """The frozen JSON projection (camelCase keys), validated by construction.
+
+    Because ``document`` is a validated :class:`~walkthru.core.schema.DemoDocument`, the emitted
+    JSON conforms to the published schema; the TS side / a renderer can consume it directly.
+    """
+    return document.model_dump_json(by_alias=True, indent=indent)
+
+
+class JsonArtifactTarget:
+    """A :class:`~walkthru.ports.RenderTarget` that writes the Demo Document's JSON projection.
+
+    Args:
+        out_dir: directory to write ``<document.id>.json`` into (created on demand).
+    """
+
+    def __init__(self, out_dir: Union[str, Path] = "."):
+        self._out_dir = Path(out_dir)
+
+    async def export(self, artifact: DemoDocument) -> AssetRef:
+        path = self._out_dir / f"{artifact.id}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(to_json(artifact) + "\n", encoding="utf-8")
+        return AssetRef(uri=str(path), mime="application/json")

walkthru/adapters/export/webvtt.py

@@ -0,0 +1,38 @@
+"""WebVTT captions derived from the narration track.
+
+Narration is timed, editable text anchored to steps; once the timeline is composed to absolute
+time, captions fall out almost for free (Report 01 §D.2). This exporter is the web-native default;
+SRT is deliberately not implemented until a real need appears (YAGNI).
+"""
+
+from __future__ import annotations
+
+from walkthru.core.schema import DemoDocument
+from walkthru.core.timeline import resolve_timeline
+
+
+def _timestamp(ms: int) -> str:
+    """Format milliseconds as a WebVTT timestamp ``HH:MM:SS.mmm``."""
+    hours, rem = divmod(ms, 3_600_000)
+    minutes, rem = divmod(rem, 60_000)
+    seconds, millis = divmod(rem, 1000)
+    return f"{hours:02d}:{minutes:02d}:{seconds:02d}.{millis:03d}"
+
+
+def narration_to_webvtt(document: DemoDocument) -> str:
+    """Render the narration track as a WebVTT caption document.
+
+    Cue start/end come from the resolved (absolute) timeline; cues are emitted in time order.
+    Returns a complete ``.vtt`` document (trailing newline included).
+    """
+    timeline = resolve_timeline(document)
+    segments = sorted(timeline.narration, key=lambda r: (r.start_ms, r.end_ms))
+
+    lines = ["WEBVTT", ""]
+    for index, segment in enumerate(segments, start=1):
+        lines.append(str(index))
+        lines.append(f"{_timestamp(segment.start_ms)} --> {_timestamp(segment.end_ms)}")
+        lines.append(segment.text)
+        lines.append("")
+
+    return "\n".join(lines) + "\n"

walkthru/core/__init__.py

@@ -0,0 +1,116 @@
+"""walkthru's pure core: the Demo Document schema, the lifecycle events, and the engine.
+
+Nothing in this package imports from :mod:`walkthru.adapters` or :mod:`walkthru.ecosystem`, and it
+has no vendor dependencies — only Pydantic (for the schema SSOT). Import the engine and schema from
+here or from the top-level :mod:`walkthru` package.
+"""
+
+from walkthru.core.engine import iter_events, play, record
+from walkthru.core.timeline import (
+    ResolvedCamera,
+    ResolvedCue,
+    ResolvedNarration,
+    ResolvedStep,
+    Timeline,
+    iter_resolved_steps,
+    resolve_timeline,
+)
+from walkthru.core.events import (
+    AfterCommand,
+    BeatEvent,
+    BeforeCommand,
+    CommandError,
+    CommandInvocation,
+    CueBegin,
+    CueEnd,
+    DemoEnd,
+    DemoStart,
+    Event,
+    Narration,
+    Observer,
+    Outcome,
+    SectionEnter,
+    SectionExit,
+    StepEnter,
+    StepExit,
+)
+from walkthru.core.schema import (
+    Anchor,
+    AssetRef,
+    Beat,
+    CalloutCue,
+    Command,
+    CommandStep,
+    Cue,
+    CursorCue,
+    DemoDocument,
+    HighlightCue,
+    HotspotCue,
+    Locator,
+    Meta,
+    NarrationSegment,
+    Rect,
+    Section,
+    SpotlightCue,
+    Step,
+    Target,
+    Timing,
+    Tracks,
+    demo_document_json_schema,
+)
+
+__all__ = [
+    # engine
+    "play",
+    "record",
+    "iter_events",
+    # timeline
+    "resolve_timeline",
+    "iter_resolved_steps",
+    "Timeline",
+    "ResolvedStep",
+    "ResolvedCue",
+    "ResolvedNarration",
+    "ResolvedCamera",
+    # schema
+    "DemoDocument",
+    "Meta",
+    "Section",
+    "Step",
+    "CommandStep",
+    "Beat",
+    "Command",
+    "Timing",
+    "Anchor",
+    "Target",
+    "Locator",
+    "Rect",
+    "Tracks",
+    "Cue",
+    "HighlightCue",
+    "SpotlightCue",
+    "HotspotCue",
+    "CalloutCue",
+    "CursorCue",
+    "NarrationSegment",
+    "AssetRef",
+    "demo_document_json_schema",
+    # events
+    "Event",
+    "Observer",
+    "Outcome",
+    "CommandInvocation",
+    "DemoStart",
+    "DemoEnd",
+    "SectionEnter",
+    "SectionExit",
+    "StepEnter",
+    "StepExit",
+    "BeforeCommand",
+    "AfterCommand",
+    "CommandError",
+    "CueBegin",
+    "CueEnd",
+    "Narration",
+    "BeatEvent",
+]

walkthru/core/engine.py

@@ -0,0 +1,196 @@
+"""The pure engine: walk a Demo Document, emit the lifecycle event stream.
+
+One small core, one lifecycle protocol, two modes with the *driver inverted* (Report 02 §B.2):
+
+* :func:`play` — **generative**: the executor drives. Walk the document, call ``executor`` for
+  each command, and emit the lifecycle :mod:`events <walkthru.core.events>`. Observers record,
+  draw, narrate.
+* :func:`record` — **capture**: the human drives. Consume a stream of already-executed commands
+  and assemble the *same* :class:`~walkthru.core.schema.DemoDocument`, emitting the *same*
+  lifecycle so every observer behaves identically.
+
+The engine performs exactly one injected effect — calling ``executor`` — and never records,
+renders, or speaks. All other effects are injected observers/ports. ``executor`` and observers may
+be sync or async; the engine awaits whatever is awaitable.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterable
+from typing import Any, Union
+
+from walkthru.core.events import (
+    AfterCommand,
+    BeatEvent,
+    BeforeCommand,
+    CommandError,
+    CommandInvocation,
+    CueBegin,
+    CueEnd,
+    DemoEnd,
+    DemoStart,
+    Event,
+    Narration,
+    Observer,
+    Outcome,
+    SectionEnter,
+    SectionExit,
+    StepEnter,
+    StepExit,
+)
+from walkthru.core.schema import (
+    Command,
+    CommandStep,
+    Cue,
+    DemoDocument,
+    NarrationSegment,
+    Section,
+    Step,
+    Timing,
+)
+
+#: The executor is any callable taking a :class:`~walkthru.core.schema.Command`; sync or async.
+Executor = Callable[[Command], Union[Awaitable[Any], Any]]
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Await ``value`` if it is awaitable, else return it as-is."""
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+def _cues_for(document: DemoDocument, step_id: str) -> Iterable[Cue]:
+    """The cues anchored to ``step_id`` (anchor is the SSOT for cue-to-step association)."""
+    for cue in document.tracks.cues:
+        if cue.anchor.step_id == step_id:
+            yield cue
+
+
+def _narration_for(document: DemoDocument, step_id: str) -> Iterable[NarrationSegment]:
+    """The narration segments anchored to ``step_id``."""
+    for segment in document.tracks.narration:
+        if segment.anchor.step_id == step_id:
+            yield segment
+
+
+async def iter_events(
+    document: DemoDocument, executor: Executor
+) -> AsyncIterator[Event]:
+    """Walk ``document`` and yield the lifecycle event stream (generative mode).
+
+    This is the canonical realization of the lifecycle protocol. The only injected effect is
+    ``executor``, awaited between :class:`~walkthru.core.events.BeforeCommand` and
+    :class:`~walkthru.core.events.AfterCommand`. A command that raises yields a
+    :class:`~walkthru.core.events.CommandError` and the walk continues (the renderer/observer
+    decides what a failed step means).
+    """
+    yield DemoStart(document)
+    errors: list[CommandError] = []
+    steps_run = 0
+
+    for section in document.sections:
+        yield SectionEnter(section)
+        for step in section.steps:
+            yield StepEnter(step)
+
+            for segment in _narration_for(document, step.id):
+                yield Narration(segment)
+
+            if isinstance(step, CommandStep):
+                yield BeforeCommand(step.command, step)
+                try:
+                    result = await _maybe_await(executor(step.command))
+                except Exception as error:  # noqa: BLE001 — surfaced as a CommandError event
+                    err = CommandError(step.command, error, step)
+                    errors.append(err)
+                    yield err
+                else:
+                    yield AfterCommand(step.command, result, step)
+                steps_run += 1
+            else:
+                yield BeatEvent(step)
+
+            for cue in _cues_for(document, step.id):
+                yield CueBegin(cue)
+                yield CueEnd(cue)
+
+            yield StepExit(step)
+        yield SectionExit(section)
+
+    yield DemoEnd(Outcome(ok=not errors, steps_run=steps_run, errors=tuple(errors)))
+
+
+async def _emit(event: Event, observers: Iterable[Observer]) -> None:
+    """Fan one event out to every observer, awaiting async observers."""
+    for observer in observers:
+        await _maybe_await(observer(event))
+
+
+async def play(
+    document: DemoDocument,
+    executor: Executor,
+    *,
+    observers: Iterable[Observer] = (),
+) -> Outcome:
+    """Play ``document`` generatively, driving ``executor`` and notifying ``observers``.
+
+    Returns the run :class:`~walkthru.core.events.Outcome`. This is a thin driver over
+    :func:`iter_events`: it forwards each event to every observer and captures the final outcome.
+    """
+    observers = tuple(observers)
+    outcome = Outcome(ok=True, steps_run=0)
+    async for event in iter_events(document, executor):
+        if isinstance(event, DemoEnd):
+            outcome = event.outcome
+        await _emit(event, observers)
+    return outcome
+
+
+async def _aiter(items: Union[Iterable[Any], AsyncIterator[Any]]) -> AsyncIterator[Any]:
+    """Normalize a sync or async iterable to an async iterator."""
+    if hasattr(items, "__aiter__"):
+        async for item in items:  # type: ignore[union-attr]
+            yield item
+    else:
+        for item in items:  # type: ignore[union-attr]
+            yield item
+
+
+async def record(
+    invocations: Union[Iterable[CommandInvocation], AsyncIterator[CommandInvocation]],
+    *,
+    observers: Iterable[Observer] = (),
+    document_id: str = "capture",
+    section_id: str = "captured",
+    section_title: str | None = None,
+    default_duration_ms: int = 1000,
+) -> DemoDocument:
+    """Capture mode: assemble a Demo Document from a stream of executed commands.
+
+    Each :class:`~walkthru.core.events.CommandInvocation` becomes a
+    :class:`~walkthru.core.schema.CommandStep`, and the same lifecycle events are emitted so
+    observers (a logger, a video recorder, a transcriber) behave exactly as in generative mode.
+    The returned document plays back through :func:`play` to reproduce the captured commands — the
+    two modes are inverses over one data model.
+    """
+    observers = tuple(observers)
+    steps: list[Step] = []
+
+    async for invocation in _aiter(invocations):
+        step = CommandStep(
+            id=f"step-{len(steps) + 1}",
+            command=invocation.command,
+            timing=Timing(duration_ms=invocation.duration_ms or default_duration_ms),
+        )
+        steps.append(step)
+        await _emit(StepEnter(step), observers)
+        await _emit(BeforeCommand(step.command, step), observers)
+        await _emit(AfterCommand(step.command, invocation.result, step), observers)
+        await _emit(StepExit(step), observers)
+
+    return DemoDocument(
+        id=document_id,
+        sections=[Section(id=section_id, title=section_title, steps=steps)],
+    )

walkthru/core/events.py

@@ -0,0 +1,154 @@
+"""The lifecycle protocol, as a typed event stream.
+
+The brief describes the engine's lifecycle as a set of named observer hooks (``onStepEnter``,
+``beforeCommand``, ...). walkthru realizes that protocol as a stream of **typed events** consumed
+by observer **callables** — the functional equivalent (each event type corresponds 1:1 to a hook
+name), chosen for composability and to match Thor's functional conventions. See ``DECISIONS.md``
+§D9.
+
+An :data:`Observer` is any callable taking one :data:`Event`; it may be sync or async. The engine
+(:mod:`walkthru.core.engine`) emits events; observers are pure subscribers — a recorder, an
+overlay renderer, a narrator, a pacer, and a logger are all just observers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+from walkthru.core.schema import (
+    Beat,
+    Command,
+    CommandStep,
+    Cue,
+    DemoDocument,
+    NarrationSegment,
+    Section,
+    Step,
+)
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """The result of a play/record run."""
+
+    ok: bool
+    steps_run: int
+    errors: tuple["CommandError", ...] = field(default_factory=tuple)
+
+
+# --- lifecycle events (one type per hook in the protocol) ---
+
+
+@dataclass(frozen=True)
+class DemoStart:
+    """Emitted once, before any section."""
+
+    document: DemoDocument
+
+
+@dataclass(frozen=True)
+class DemoEnd:
+    """Emitted once, after the last section; carries the run :class:`Outcome`."""
+
+    outcome: Outcome
+
+
+@dataclass(frozen=True)
+class SectionEnter:
+    section: Section
+
+
+@dataclass(frozen=True)
+class SectionExit:
+    section: Section
+
+
+@dataclass(frozen=True)
+class StepEnter:
+    step: Step
+
+
+@dataclass(frozen=True)
+class StepExit:
+    step: Step
+
+
+@dataclass(frozen=True)
+class BeforeCommand:
+    """Emitted just before the executor runs the command."""
+
+    command: Command
+    step: CommandStep
+
+
+@dataclass(frozen=True)
+class AfterCommand:
+    """Emitted after the executor returns successfully."""
+
+    command: Command
+    result: Any
+    step: CommandStep
+
+
+@dataclass(frozen=True)
+class CommandError:
+    """Emitted when the executor raises; the run continues unless an observer stops it."""
+
+    command: Command
+    error: BaseException
+    step: CommandStep
+
+
+@dataclass(frozen=True)
+class CueBegin:
+    cue: Cue
+
+
+@dataclass(frozen=True)
+class CueEnd:
+    cue: Cue
+
+
+@dataclass(frozen=True)
+class Narration:
+    segment: NarrationSegment
+
+
+@dataclass(frozen=True)
+class BeatEvent:
+    beat: Beat
+
+
+Event = Union[
+    DemoStart,
+    DemoEnd,
+    SectionEnter,
+    SectionExit,
+    StepEnter,
+    StepExit,
+    BeforeCommand,
+    AfterCommand,
+    CommandError,
+    CueBegin,
+    CueEnd,
+    Narration,
+    BeatEvent,
+]
+
+#: An observer is any callable that consumes an event; it may return ``None`` or an awaitable.
+Observer = Callable[[Event], Union[Awaitable[None], None]]
+
+
+@dataclass(frozen=True)
+class CommandInvocation:
+    """A command that has already executed — the unit of the capture-mode input stream.
+
+    In capture mode the human drives the app, each dispatch is observed *after the fact*, and the
+    engine records it. ``result``/``durationMs`` are what the live dispatch returned.
+    """
+
+    command: Command
+    result: Any = None
+    duration_ms: int | None = None