luvatrix 0.2.0__tar.gz → 0.2.2__tar.gz

{luvatrix-0.2.0/luvatrix.egg-info → luvatrix-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luvatrix
-Version: 0.2.0
+Version: 0.2.2
 Summary: Luvatrix runtime and plotting toolkit
 Author: Luvatrix contributors
 License-Expression: LicenseRef-Proprietary
@@ -215,3 +215,45 @@ Android Keystore. iOS bridges should use `ASWebAuthenticationSession` and
 Keychain. `InMemoryTokenStore` remains available for tests, but production apps
 should not use it for long-lived refresh tokens. Mobile apps must not embed a
 Google client secret.
+
+## Prepared Text Wrapping
+
+Luvatrix includes an optional, dependency-free prepared wrapping style inspired
+by the MIT-licensed [Pretext](https://github.com/chenglou/pretext) architecture.
+Text is segmented and measured once; changing only the available width reuses
+those native measurements.
+
+Scene/UI text uses `TextWrapping` on `TextComponent`:
+
+```python
+from luvatrix.app import TextWrapping
+from luvatrix_ui.text import TextComponent
+
+body = TextComponent(
+    component_id="body",
+    text="A paragraph which should wrap across multiple lines.",
+    max_width_px=320,
+    wrapping=TextWrapping(white_space="normal"),
+)
+```
+
+Matrix text uses the same layout engine and its matrix-font measurements:
+
+```python
+from luvatrix.app import draw_text_to_matrix
+
+draw_text_to_matrix(
+    matrix,
+    "A paragraph rendered into an RGBA matrix.",
+    x=12,
+    y=12,
+    font_size_px=12,
+    max_width_px=240,
+    wrapping="pretext",
+    line_height_multiplier=1.2,
+)
+```
+
+`white_space="pre-wrap"` preserves repeated spaces and hard line breaks.
+Ordinary wrapping collapses whitespace and uses grapheme-safe emergency breaks
+for content wider than a complete line.

{luvatrix-0.2.0 → luvatrix-0.2.2}/README.md

@@ -177,3 +177,45 @@ Android Keystore. iOS bridges should use `ASWebAuthenticationSession` and
 Keychain. `InMemoryTokenStore` remains available for tests, but production apps
 should not use it for long-lived refresh tokens. Mobile apps must not embed a
 Google client secret.
+
+## Prepared Text Wrapping
+
+Luvatrix includes an optional, dependency-free prepared wrapping style inspired
+by the MIT-licensed [Pretext](https://github.com/chenglou/pretext) architecture.
+Text is segmented and measured once; changing only the available width reuses
+those native measurements.
+
+Scene/UI text uses `TextWrapping` on `TextComponent`:
+
+```python
+from luvatrix.app import TextWrapping
+from luvatrix_ui.text import TextComponent
+
+body = TextComponent(
+    component_id="body",
+    text="A paragraph which should wrap across multiple lines.",
+    max_width_px=320,
+    wrapping=TextWrapping(white_space="normal"),
+)
+```
+
+Matrix text uses the same layout engine and its matrix-font measurements:
+
+```python
+from luvatrix.app import draw_text_to_matrix
+
+draw_text_to_matrix(
+    matrix,
+    "A paragraph rendered into an RGBA matrix.",
+    x=12,
+    y=12,
+    font_size_px=12,
+    max_width_px=240,
+    wrapping="pretext",
+    line_height_multiplier=1.2,
+)
+```
+
+`white_space="pre-wrap"` preserves repeated spaces and hard line breaks.
+Ordinary wrapping collapses whitespace and uses grapheme-safe emergency breaks
+for content wider than a complete line.

{luvatrix-0.2.0 → luvatrix-0.2.2}/luvatrix/app.py

@@ -22,9 +22,11 @@ from luvatrix_core.core.app_runtime import (
     ResolvedAppVariant,
 )
 from luvatrix_core.core.hdi_thread import HDIEvent, HDIThread
+from luvatrix_core.core.interaction_work import InteractionAwareWorkScheduler
 from luvatrix_core.core.sensor_manager import SensorManagerThread, SensorSample
 from luvatrix_core.core.window_matrix import FullRewrite, WriteBatch, WindowMatrix
 from luvatrix_core import accel
+from luvatrix_ui.text.wrapping import TextWrapping, layout_text, prepare_text
 
 PLATFORM_MACOS = "macos"
 PLATFORM_IOS = "ios"
@@ -298,6 +300,11 @@ class SwipeMomentumController:
     def dragging(self) -> bool:
         return self._dragging
 
+    @property
+    def active(self) -> bool:
+        """Whether a drag or post-release momentum is active."""
+        return self._dragging or self._velocity != 0.0
+
     def reset(self) -> None:
         self._touch_id = None
         self._last_position = None
@@ -1262,11 +1269,15 @@ def draw_text_to_matrix(
     font_size_px: float = 14.0,
     color: tuple[int, int, int, int] | str = (255, 255, 255, 255),
     antialias: bool = True,
+    max_width_px: float | None = None,
+    wrapping: str | TextWrapping | None = None,
+    line_height_multiplier: float = 1.2,
 ):
     """Rasterize Luvatrix's default matrix text glyphs into an RGBA matrix.
 
     Set ``antialias=False`` for crisp, thresholded glyph pixels on compact
-    matrix surfaces such as calendar event tiles.
+    matrix surfaces such as calendar event tiles. Set ``wrapping="pretext"``
+    with ``max_width_px`` for prepared multiline wrapping.
     """
     height = int(matrix.shape[0])
     width = int(matrix.shape[1])
@@ -1275,30 +1286,58 @@ def draw_text_to_matrix(
 
     font = _default_matrix_font()
     scale = max(1, int(round(float(font_size_px) / float(font.height))))
-    cursor = int(x)
-    top = int(y)
+    line_height = max(1.0, float(font_size_px) * float(line_height_multiplier))
+    if line_height_multiplier <= 0:
+        raise ValueError("line_height_multiplier must be > 0")
+    if wrapping is not None and max_width_px is None:
+        raise ValueError("max_width_px is required when matrix text wrapping is enabled")
+    if isinstance(wrapping, str):
+        if wrapping != "pretext":
+            raise ValueError("wrapping must be None, 'pretext', or TextWrapping")
+        wrapping = TextWrapping()
+    if wrapping is not None and not isinstance(wrapping, TextWrapping):
+        raise TypeError("wrapping must be None, 'pretext', or TextWrapping")
+
+    lines = (str(text),)
+    if wrapping is not None:
+        advance = font.advance * scale
+        prepared = prepare_text(
+            str(text),
+            measure=lambda value: float(len(value) * advance),
+            wrapping=wrapping,
+        )
+        wrapped = layout_text(
+            prepared,
+            max_width_px=float(max_width_px),
+            line_height_px=line_height,
+        )
+        lines = tuple(line.text for line in wrapped.lines)
+
     rgba = _rgba(color)
     space = font.glyphs[" "]
-    for raw_ch in str(text):
-        glyph = font.glyphs.get(raw_ch, font.glyphs.get(raw_ch.upper(), space))
-        for gy, row in enumerate(glyph):
-            for gx, coverage in enumerate(row):
-                if not antialias:
-                    coverage = 255 if coverage >= 128 else 0
-                if coverage <= 0:
-                    continue
-                _paint_matrix_rect(
-                    matrix,
-                    cursor + gx * scale,
-                    top + gy * scale,
-                    cursor + (gx + 1) * scale,
-                    top + (gy + 1) * scale,
-                    rgba,
-                    coverage=coverage,
-                    width=width,
-                    height=height,
-                )
-        cursor += font.advance * scale
+    for line_index, line in enumerate(lines):
+        cursor = int(x)
+        top = int(float(y) + line_index * line_height)
+        for raw_ch in line:
+            glyph = font.glyphs.get(raw_ch, font.glyphs.get(raw_ch.upper(), space))
+            for gy, row in enumerate(glyph):
+                for gx, coverage in enumerate(row):
+                    if not antialias:
+                        coverage = 255 if coverage >= 128 else 0
+                    if coverage <= 0:
+                        continue
+                    _paint_matrix_rect(
+                        matrix,
+                        cursor + gx * scale,
+                        top + gy * scale,
+                        cursor + (gx + 1) * scale,
+                        top + (gy + 1) * scale,
+                        rgba,
+                        coverage=coverage,
+                        width=width,
+                        height=height,
+                    )
+            cursor += font.advance * scale
     return matrix
 
 
@@ -1823,6 +1862,7 @@ __all__ = [
     "Display",
     "InputManager",
     "InputState",
+    "InteractionAwareWorkScheduler",
     "MatrixFrame",
     "MissingOptionalDependencyError",
     "ResolvedAppVariant",
@@ -1833,6 +1873,7 @@ __all__ = [
     "Sensors",
     "SwipeMomentumController",
     "SwipeMomentumUpdate",
+    "TextWrapping",
     "UIFrame",
     "apply_hdi_events",
     "check_app_install",

{luvatrix-0.2.0 → luvatrix-0.2.2/luvatrix.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luvatrix
-Version: 0.2.0
+Version: 0.2.2
 Summary: Luvatrix runtime and plotting toolkit
 Author: Luvatrix contributors
 License-Expression: LicenseRef-Proprietary
@@ -215,3 +215,45 @@ Android Keystore. iOS bridges should use `ASWebAuthenticationSession` and
 Keychain. `InMemoryTokenStore` remains available for tests, but production apps
 should not use it for long-lived refresh tokens. Mobile apps must not embed a
 Google client secret.
+
+## Prepared Text Wrapping
+
+Luvatrix includes an optional, dependency-free prepared wrapping style inspired
+by the MIT-licensed [Pretext](https://github.com/chenglou/pretext) architecture.
+Text is segmented and measured once; changing only the available width reuses
+those native measurements.
+
+Scene/UI text uses `TextWrapping` on `TextComponent`:
+
+```python
+from luvatrix.app import TextWrapping
+from luvatrix_ui.text import TextComponent
+
+body = TextComponent(
+    component_id="body",
+    text="A paragraph which should wrap across multiple lines.",
+    max_width_px=320,
+    wrapping=TextWrapping(white_space="normal"),
+)
+```
+
+Matrix text uses the same layout engine and its matrix-font measurements:
+
+```python
+from luvatrix.app import draw_text_to_matrix
+
+draw_text_to_matrix(
+    matrix,
+    "A paragraph rendered into an RGBA matrix.",
+    x=12,
+    y=12,
+    font_size_px=12,
+    max_width_px=240,
+    wrapping="pretext",
+    line_height_multiplier=1.2,
+)
+```
+
+`white_space="pre-wrap"` preserves repeated spaces and hard line breaks.
+Ordinary wrapping collapses whitespace and uses grapheme-safe emergency breaks
+for content wider than a complete line.

{luvatrix-0.2.0 → luvatrix-0.2.2}/luvatrix.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ luvatrix_core/core/engine.py
 luvatrix_core/core/events.py
 luvatrix_core/core/frame_rate_controller.py
 luvatrix_core/core/hdi_thread.py
+luvatrix_core/core/interaction_work.py
 luvatrix_core/core/process_runtime.py
 luvatrix_core/core/process_sdk.py
 luvatrix_core/core/protocol_governance.py
@@ -185,4 +186,5 @@ luvatrix_ui/table/__init__.py
 luvatrix_ui/table/component.py
 luvatrix_ui/text/__init__.py
 luvatrix_ui/text/component.py
-luvatrix_ui/text/renderer.py
+luvatrix_ui/text/renderer.py
+luvatrix_ui/text/wrapping.py

{luvatrix-0.2.0 → luvatrix-0.2.2}/luvatrix_core/__init__.py

@@ -1,4 +1,4 @@
 """Luvatrix runtime."""
 
 __all__ = ["__version__"]
-__version__ = "0.2.0"
+__version__ = "0.2.2"

luvatrix-0.2.2/luvatrix_core/core/interaction_work.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Hashable
+from dataclasses import dataclass
+import threading
+import time
+from typing import Any
+
+
+@dataclass(frozen=True)
+class _WorkItem:
+    key: Hashable
+    prepare: Callable[[], Any]
+    on_complete: Callable[[Any], None] | None
+
+
+class InteractionAwareWorkScheduler:
+    """Run keyed preparation work only while user interaction is idle.
+
+    Work and callbacks execute sequentially on one daemon thread. Running work
+    is not preempted when interaction begins; the idle gate prevents queued
+    work from starting until ``interaction_active`` returns false.
+
+    Pair with ``SwipeMomentumController`` using
+    ``interaction_active=lambda: swipe.active`` and call
+    :meth:`notify_interaction_state_changed` after controller updates to wake
+    queued work immediately when momentum stops.
+    """
+
+    def __init__(
+        self,
+        *,
+        interaction_active: Callable[[], bool],
+        request_render: Callable[[], None] | None = None,
+        on_error: Callable[[Hashable, Exception], None] | None = None,
+        idle_poll_interval: float = 1.0 / 120.0,
+        thread_name: str = "luvatrix-interaction-work",
+    ) -> None:
+        self.interaction_active = interaction_active
+        self.request_render = request_render
+        self.on_error = on_error
+        self.idle_poll_interval = max(0.001, float(idle_poll_interval))
+        self.thread_name = str(thread_name)
+        self._condition = threading.Condition()
+        self._pending: deque[_WorkItem] = deque()
+        self._keys: set[Hashable] = set()
+        self._thread: threading.Thread | None = None
+        self._closed = False
+
+    @property
+    def pending_count(self) -> int:
+        with self._condition:
+            return len(self._keys)
+
+    def submit(
+        self,
+        key: Hashable,
+        prepare: Callable[[], Any],
+        *,
+        on_complete: Callable[[Any], None] | None = None,
+    ) -> bool:
+        """Queue work unless the key is already queued or running."""
+        with self._condition:
+            if self._closed:
+                raise RuntimeError("interaction-aware work scheduler is closed")
+            if key in self._keys:
+                return False
+            self._keys.add(key)
+            self._pending.append(_WorkItem(key, prepare, on_complete))
+            if self._thread is None:
+                self._thread = threading.Thread(
+                    target=self._run,
+                    name=self.thread_name,
+                    daemon=True,
+                )
+                self._thread.start()
+            self._condition.notify_all()
+            return True
+
+    def notify_interaction_state_changed(self) -> None:
+        """Wake idle-gated work after a controller state update."""
+        with self._condition:
+            self._condition.notify_all()
+
+    def wait_idle(self, timeout: float | None = None) -> bool:
+        """Wait until queued/running work and its callbacks have completed."""
+        deadline = None if timeout is None else time.monotonic() + max(0.0, float(timeout))
+        with self._condition:
+            while self._keys:
+                if deadline is None:
+                    self._condition.wait()
+                    continue
+                remaining = deadline - time.monotonic()
+                if remaining <= 0.0:
+                    return False
+                self._condition.wait(remaining)
+            return True
+
+    def close(self, *, wait: bool = False) -> None:
+        """Cancel queued work and optionally wait for running work to finish."""
+        with self._condition:
+            self._closed = True
+            while self._pending:
+                self._keys.discard(self._pending.popleft().key)
+            thread = self._thread
+            self._condition.notify_all()
+        if wait and thread is not None and thread is not threading.current_thread():
+            thread.join()
+
+    def _run(self) -> None:
+        while True:
+            with self._condition:
+                while not self._closed and not self._pending:
+                    self._condition.wait()
+                if self._closed:
+                    return
+                pending_key = self._pending[0].key
+
+            try:
+                interaction_active = bool(self.interaction_active())
+            except Exception as exc:
+                self._report_error(pending_key, exc)
+                interaction_active = False
+
+            with self._condition:
+                if self._closed:
+                    return
+                if not self._pending:
+                    continue
+                if interaction_active:
+                    self._condition.wait(self.idle_poll_interval)
+                    continue
+                item = self._pending.popleft()
+
+            try:
+                value = item.prepare()
+            except Exception as exc:
+                self._report_error(item.key, exc)
+            else:
+                if item.on_complete is not None:
+                    try:
+                        item.on_complete(value)
+                    except Exception as exc:
+                        self._report_error(item.key, exc)
+            try:
+                if self.request_render is not None:
+                    self.request_render()
+            except Exception as exc:
+                self._report_error(item.key, exc)
+            finally:
+                with self._condition:
+                    self._keys.discard(item.key)
+                    self._condition.notify_all()
+
+    def _report_error(self, key: Hashable, error: Exception) -> None:
+        if self.on_error is None:
+            return
+        try:
+            self.on_error(key, error)
+        except Exception:
+            return

{luvatrix-0.2.0 → luvatrix-0.2.2}/luvatrix_core/platform/android/runner.py

@@ -332,14 +332,17 @@ def sync_android_python_assets(app_dir: Path, *, project_dir: Path) -> None:
 
 def _android_python_packages_for_app(app_dir: Path, *, exclude_dirs: Iterable[Path] = ()) -> tuple[str, ...]:
     packages = ["luvatrix", "luvatrix_core"]
-    imports = _top_level_imports_for_app(app_dir, exclude_dirs=exclude_dirs)
+    imported_modules = _imported_modules_for_app(app_dir, exclude_dirs=exclude_dirs)
+    imports = {module.split(".", 1)[0] for module in imported_modules}
+    for module in imported_modules:
+        imports.update(_first_party_module_import_roots(module))
     for optional_pkg in ("luvatrix_ui", "luvatrix_plot"):
         if optional_pkg in imports:
             packages.append(optional_pkg)
     return tuple(packages)
 
 
-def _top_level_imports_for_app(app_dir: Path, *, exclude_dirs: Iterable[Path] = ()) -> set[str]:
+def _imported_modules_for_app(app_dir: Path, *, exclude_dirs: Iterable[Path] = ()) -> set[str]:
     imports: set[str] = set()
     excluded = tuple(path.resolve() for path in exclude_dirs)
     for path in app_dir.rglob("*.py"):
@@ -355,12 +358,37 @@ def _top_level_imports_for_app(app_dir: Path, *, exclude_dirs: Iterable[Path] =
         for node in ast.walk(tree):
             if isinstance(node, ast.Import):
                 for alias in node.names:
-                    imports.add(alias.name.split(".", 1)[0])
+                    imports.add(alias.name)
             elif isinstance(node, ast.ImportFrom) and node.module:
-                imports.add(node.module.split(".", 1)[0])
+                imports.add(node.module)
     return imports
 
 
+def _first_party_module_import_roots(module_name: str) -> set[str]:
+    package_name, _, relative_module = module_name.partition(".")
+    if package_name not in {"luvatrix", "luvatrix_core"}:
+        return set()
+    package_dir = _python_package_dir(package_name)
+    if relative_module:
+        module_path = package_dir.joinpath(*relative_module.split("."))
+        source_path = module_path.with_suffix(".py")
+        if not source_path.is_file():
+            source_path = module_path / "__init__.py"
+    else:
+        source_path = package_dir / "__init__.py"
+    try:
+        tree = ast.parse(source_path.read_text(encoding="utf-8"), filename=str(source_path))
+    except (OSError, SyntaxError):
+        return set()
+    roots: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            roots.update(alias.name.split(".", 1)[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            roots.add(node.module.split(".", 1)[0])
+    return roots
+
+
 def _make_android_app_ignore(project_dir: Path):
     pattern_ignore = shutil.ignore_patterns("__pycache__", "*.pyc", ".pytest_cache", ".luvatrix")
     project = project_dir.resolve()

{luvatrix-0.2.0 → luvatrix-0.2.2}/luvatrix_ui/text/__init__.py

@@ -11,6 +11,7 @@ from .renderer import (
     TextRenderer,
     TextSizeSpec,
 )
+from .wrapping import PreparedText, TextLayout, TextWrapping, WrappedLine, layout_text, prepare_text
 
 __all__ = [
     "FontSpec",
@@ -22,4 +23,10 @@ __all__ = [
     "TextRenderCommand",
     "TextRenderer",
     "TextSizeSpec",
+    "TextWrapping",
+    "PreparedText",
+    "TextLayout",
+    "WrappedLine",
+    "prepare_text",
+    "layout_text",
 ]

{luvatrix-0.2.0 → luvatrix-0.2.2}/luvatrix_ui/text/component.py

@@ -14,6 +14,7 @@ from .renderer import (
     TextRenderer,
     TextSizeSpec,
 )
+from .wrapping import PreparedText, TextWrapping, layout_text, prepare_text
 
 
 @dataclass
@@ -31,7 +32,10 @@ class TextComponent(ComponentBase):
     size: TextSizeSpec = field(default_factory=TextSizeSpec)
     appearance: TextAppearance = field(default_factory=TextAppearance)
     max_width_px: float | None = None
+    wrapping: TextWrapping | None = None
     _visual_bounds_cache: BoundingBox | None = field(default=None, init=False, repr=False)
+    _prepared_text_cache: PreparedText | None = field(default=None, init=False, repr=False)
+    _prepared_text_key: tuple[object, ...] | None = field(default=None, init=False, repr=False)
 
     def _resolved_frame(self) -> str:
         return self.position.frame or self.default_frame
@@ -89,11 +93,79 @@ class TextComponent(ComponentBase):
         *,
         transformer: CoordinateTransformer | None = None,
     ) -> TextRenderBatch:
+        if self.wrapping is not None and self.max_width_px is not None:
+            batch = self._wrapped_render_batch(renderer, display, transformer=transformer)
+            renderer.draw_text_batch(batch)
+            return batch
         command, _ = self.layout(renderer, display, transformer=transformer)
         batch = TextRenderBatch(commands=(command,))
         renderer.draw_text_batch(batch)
         return batch
 
+    def _wrapped_render_batch(
+        self,
+        renderer: TextRenderer,
+        display: DisplayableArea,
+        *,
+        transformer: CoordinateTransformer | None = None,
+    ) -> TextRenderBatch:
+        font_size_px = self.size.resolve_px(display)
+        key = (
+            id(renderer),
+            self.text,
+            self.font,
+            font_size_px,
+            self.appearance,
+            self.wrapping,
+        )
+        if self._prepared_text_cache is None or self._prepared_text_key != key:
+            def measure(value: str) -> float:
+                return renderer.measure_text(
+                    TextMeasureRequest(
+                        text=value,
+                        font=self.font,
+                        font_size_px=font_size_px,
+                        appearance=self.appearance,
+                    )
+                ).width_px
+
+            self._prepared_text_cache = prepare_text(
+                self.text,
+                measure=measure,
+                wrapping=self.wrapping,
+            )
+            self._prepared_text_key = key
+        line_height = font_size_px * self.appearance.line_height_multiplier
+        wrapped = layout_text(
+            self._prepared_text_cache,
+            max_width_px=self.max_width_px,
+            line_height_px=line_height,
+        )
+        x, y = self._resolved_xy(transformer)
+        frame = self._resolved_frame()
+        commands = tuple(
+            TextRenderCommand(
+                component_id=f"{self.component_id}:line:{index}",
+                text=line.text,
+                x=x,
+                y=y + index * line_height,
+                frame=frame,
+                font=self.font,
+                font_size_px=font_size_px,
+                appearance=self.appearance,
+                max_width_px=None,
+            )
+            for index, line in enumerate(wrapped.lines)
+        )
+        self._visual_bounds_cache = BoundingBox(
+            x=x,
+            y=y,
+            width=wrapped.width_px,
+            height=wrapped.height_px,
+            frame=frame,
+        )
+        return TextRenderBatch(commands=commands)
+
     def visual_bounds(self) -> BoundingBox:
         if self._visual_bounds_cache is None:
             return BoundingBox(