tw-framework 0.2.3__py3-none-any.whl

tw_framework/hydration.py

@@ -0,0 +1,129 @@
+"""
+Partial hydration / islands architecture for TW Framework.
+
+Interactive components are wrapped with data attributes and a small runtime
+that hydrates only those components, leaving static HTML untouched.
+"""
+
+import html
+import json
+import logging
+from typing import Dict, List, Optional
+
+from .ir import IRComponent, IRElement, IRProgram
+from .runtime_values import RuntimeEnvironment
+
+logger = logging.getLogger(__name__)
+
+
+def _is_interactive(node) -> bool:
+    """Check if a node has interactive attributes (events, router, or lazy component)."""
+    if isinstance(node, IRElement):
+        if node.events or node.router:
+            return True
+        for child in node.children:
+            if _is_interactive(child):
+                return True
+    if isinstance(node, IRComponent):
+        for prop in node.props:
+            if prop.get("name") == "lazy" and prop.get("value") in (True, "true"):
+                return True
+        for child in node.children:
+            if _is_interactive(child):
+                return True
+    return False
+
+
+def _collect_interactive_nodes(node, path: str, interactive: List[Dict]):
+    """Recursively collect interactive nodes with their paths."""
+    if isinstance(node, IRElement):
+        if node.events or node.router:
+            interactive.append({
+                "path": path,
+                "tag": node.tag,
+                "events": [{"name": e["name"], "value": e["value"]} for e in node.events],
+                "router": dict(node.router),
+            })
+        for i, child in enumerate(node.children):
+            _collect_interactive_nodes(child, f"{path}.children[{i}]", interactive)
+    if isinstance(node, IRComponent):
+        for prop in node.props:
+            if prop.get("name") == "lazy" and prop.get("value") in (True, "true"):
+                interactive.append({
+                    "path": path,
+                    "tag": f"component:{node.name}",
+                    "lazy": True,
+                })
+        for i, child in enumerate(node.children):
+            _collect_interactive_nodes(child, f"{path}.children[{i}]", interactive)
+
+
+def wrap_interactive_nodes(html: str, program: IRProgram, context: Optional[Dict] = None) -> str:
+    """Wrap interactive nodes with data-tw-hydrate attributes and inject hydration script."""
+    interactive = []
+    for i, node in enumerate(program.body):
+        _collect_interactive_nodes(node, f"body[{i}]", interactive)
+    if not interactive:
+        return html
+
+    # Inject data attributes
+    for item in interactive:
+        path = item["path"]
+        tag = item["tag"]
+        if item.get("lazy"):
+            html = html.replace(
+                f"<{tag}",
+                f'<{tag} data-tw-hydrate="lazy" data-tw-path="{html.escape(path, quote=True)}"',
+                1,
+            )
+        else:
+            html = html.replace(
+                f"<{tag}",
+                f'<{tag} data-tw-hydrate="interactive" data-tw-path="{html.escape(path, quote=True)}"',
+                1,
+            )
+
+    # Inject hydration runtime
+    runtime_js = """
+(function() {
+  var hydratable = document.querySelectorAll('[data-tw-hydrate]');
+  if (!hydratable.length) return;
+  var observer = new IntersectionObserver(function(entries) {
+    entries.forEach(function(entry) {
+      if (entry.isIntersecting) {
+        var el = entry.target;
+        var type = el.getAttribute('data-tw-hydrate');
+        if (type === 'lazy') {
+          // Lazy component: load chunk and hydrate
+          var path = el.getAttribute('data-tw-path');
+          import('/_tw/chunks/' + path + '.js').then(function(mod) {
+            if (mod.hydrate) mod.hydrate(el);
+          }).catch(function(err) {
+            console.warn('TW hydration failed for', path, err);
+          });
+        } else {
+          // Interactive element: attach events
+          var events = JSON.parse(el.getAttribute('data-tw-events') || '[]');
+          events.forEach(function(ev) {
+            el.addEventListener(ev.name, function(event) {
+              try {
+                var fn = new Function('event', ev.value);
+                fn(event);
+              } catch(e) {
+                console.warn('TW event handler error', e);
+              }
+            });
+          });
+        }
+        observer.unobserve(el);
+      }
+    });
+  }, { rootMargin: '200px' });
+  hydratable.forEach(function(el) { observer.observe(el); });
+})();
+"""
+    html = html.replace("</body>", f"<script>{runtime_js}</script></body>", 1)
+    return html
+
+
+__all__ = ["wrap_interactive_nodes", "_is_interactive"]

tw_framework/incremental_cache.py

@@ -0,0 +1,53 @@
+"""
+Incremental compiler cache for TW Framework.
+
+Caches parsed AST, compiled output, dependency graph, CSS, and assets.
+Only rebuilds changed nodes.
+"""
+
+import hashlib
+import json
+import logging
+import os
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class IncrementalCache:
+    """Persistent cache for compiler artifacts."""
+
+    def __init__(self, project_root: str):
+        self.cache_dir = os.path.join(project_root, ".tw", "cache")
+        os.makedirs(self.cache_dir, exist_ok=True)
+
+    def _key_path(self, key: str) -> str:
+        return os.path.join(self.cache_dir, f"{key}.json")
+
+    def get(self, key: str) -> Optional[Any]:
+        path = self._key_path(key)
+        if not os.path.exists(path):
+            return None
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def set(self, key: str, value: Any):
+        path = self._key_path(key)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(value, f, indent=2)
+
+    def invalidate(self, key: str):
+        path = self._key_path(key)
+        if os.path.exists(path):
+            os.remove(path)
+
+    def clear(self):
+        for fname in os.listdir(self.cache_dir):
+            if fname.endswith(".json"):
+                os.remove(os.path.join(self.cache_dir, fname))
+
+
+__all__ = ["IncrementalCache"]

tw_framework/interpreter.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from .lowering import lower_program
+from .parser import parse_file, parse_text
+from .render_html import build_runtime_context, render_program_document
+from .runtime_values import RuntimeEnvironment
+
+
+@dataclass
+class InterpreterResult:
+    html: str
+    context: Dict
+
+
+class Interpreter:
+    def run_program(self, program, context: Optional[Dict] = None, css_href: Optional[str] = None) -> InterpreterResult:
+        ir_program = lower_program(program)
+        runtime_context = build_runtime_context(program, context=context)
+        html = render_program_document(ir_program, page_program=program, context=runtime_context, css_href=css_href)
+        return InterpreterResult(html=html, context=runtime_context)
+
+    def run_text(self, text: str, *, base_dir: str = ".", file_path: str = "<memory>", context: Optional[Dict] = None, css_href: Optional[str] = None, debug: bool = False) -> InterpreterResult:
+        program = parse_text(text, base_dir=base_dir, file_path=file_path, debug=debug)
+        return self.run_program(program, context=context, css_href=css_href)
+
+    def run_file(self, path: str, context: Optional[Dict] = None, css_href: Optional[str] = None, debug: bool = False) -> InterpreterResult:
+        program = parse_file(path, debug=debug)
+        return self.run_program(program, context=context, css_href=css_href)
+
+
+def run_file(path: str, context: Optional[Dict] = None, css_href: Optional[str] = None) -> InterpreterResult:
+    return Interpreter().run_file(path, context=context, css_href=css_href)
+
+
+def build_runtime_environment(initial: Optional[Dict] = None) -> RuntimeEnvironment:
+    return RuntimeEnvironment(values=dict(initial or {}))
+
+
+__all__ = ["Interpreter", "InterpreterResult", "build_runtime_environment", "run_file"]

tw_framework/ir.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class IRNode:
+    kind: str
+
+
+@dataclass
+class IRText(IRNode):
+    value: str
+
+    def __init__(self, value: str):
+        super().__init__("text")
+        self.value = value
+
+
+@dataclass
+class IRLet(IRNode):
+    name: str
+    value: Any
+
+    def __init__(self, name: str, value: Any):
+        super().__init__("let")
+        self.name = name
+        self.value = value
+
+
+@dataclass
+class IRIf(IRNode):
+    condition: str
+    children: List[IRNode] = field(default_factory=list)
+    else_children: List[IRNode] = field(default_factory=list)
+
+    def __init__(self, condition: str, children=None, else_children=None):
+        super().__init__("if")
+        self.condition = condition
+        self.children = children or []
+        self.else_children = else_children or []
+
+
+@dataclass
+class IRFor(IRNode):
+    var_name: str
+    iterable: str
+    children: List[IRNode] = field(default_factory=list)
+
+    def __init__(self, var_name: str, iterable: str, children=None):
+        super().__init__("for")
+        self.var_name = var_name
+        self.iterable = iterable
+        self.children = children or []
+
+
+@dataclass
+class IRScript(IRNode):
+    raw_js: str
+
+    def __init__(self, raw_js: str):
+        super().__init__("script")
+        self.raw_js = raw_js
+
+
+@dataclass
+class IRElement(IRNode):
+    tag: str
+    text: Optional[str] = None
+    attrs: List[Dict[str, Any]] = field(default_factory=list)
+    styles: List[Dict[str, Any]] = field(default_factory=list)
+    events: List[Dict[str, Any]] = field(default_factory=list)
+    router: Dict[str, Any] = field(default_factory=dict)
+    children: List[IRNode] = field(default_factory=list)
+
+    def __init__(self, tag: str, text=None, attrs=None, styles=None, events=None, router=None, children=None):
+        super().__init__("element")
+        self.tag = tag
+        self.text = text
+        self.attrs = attrs or []
+        self.styles = styles or []
+        self.events = events or []
+        self.router = router or {}
+        self.children = children or []
+
+
+@dataclass
+class IRComponent(IRNode):
+    name: str
+    props: List[Dict[str, Any]] = field(default_factory=list)
+    children: List[IRNode] = field(default_factory=list)
+
+    def __init__(self, name: str, props=None, children=None):
+        super().__init__("component")
+        self.name = name
+        self.props = props or []
+        self.children = children or []
+
+
+@dataclass
+class IRProgram:
+    meta: Dict[str, Any]
+    head: Dict[str, Any]
+    lets: Dict[str, Any] = field(default_factory=dict)
+    state: Dict[str, Any] = field(default_factory=dict)
+    body: List[IRNode] = field(default_factory=list)
+
+    def to_dict(self):
+        return {
+            "meta": dict(self.meta),
+            "head": dict(self.head),
+            "lets": dict(self.lets),
+            "state": dict(self.state),
+            "body": [ir_node_to_dict(node) for node in self.body],
+        }
+
+
+def ir_node_to_dict(node: IRNode):
+    if isinstance(node, IRText):
+        return {"kind": node.kind, "value": node.value}
+    if isinstance(node, IRLet):
+        return {"kind": node.kind, "name": node.name, "value": node.value}
+    if isinstance(node, IRIf):
+        return {
+            "kind": node.kind,
+            "condition": node.condition,
+            "children": [ir_node_to_dict(child) for child in node.children],
+            "else_children": [ir_node_to_dict(child) for child in node.else_children],
+        }
+    if isinstance(node, IRFor):
+        return {
+            "kind": node.kind,
+            "var_name": node.var_name,
+            "iterable": node.iterable,
+            "children": [ir_node_to_dict(child) for child in node.children],
+        }
+    if isinstance(node, IRScript):
+        return {"kind": node.kind, "raw_js": node.raw_js}
+    if isinstance(node, IRElement):
+        return {
+            "kind": node.kind,
+            "tag": node.tag,
+            "text": node.text,
+            "attrs": list(node.attrs),
+            "styles": list(node.styles),
+            "events": list(node.events),
+            "router": dict(node.router),
+            "children": [ir_node_to_dict(child) for child in node.children],
+        }
+    if isinstance(node, IRComponent):
+        return {
+            "kind": node.kind,
+            "name": node.name,
+            "props": list(node.props),
+            "children": [ir_node_to_dict(child) for child in node.children],
+        }
+    return {"kind": getattr(node, "kind", "unknown"), "repr": repr(node)}
+
+
+__all__ = [
+    "IRComponent",
+    "IRElement",
+    "IRFor",
+    "IRIf",
+    "IRLet",
+    "IRProgram",
+    "IRScript",
+    "IRText",
+    "ir_node_to_dict",
+]

tw_framework/lexer.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class LexerToken:
+    type: str
+    value: str
+    line: int
+    col: int
+
+    def to_dict(self):
+        return {
+            "type": self.type,
+            "value": self.value,
+            "line": self.line,
+            "col": self.col,
+        }
+
+
+def _legacy():
+    from . import compiler
+
+    return compiler
+
+
+def tokenize(code: str, allow_inline_scripts: bool = True) -> List[LexerToken]:
+    compiler = _legacy()
+    tokens = compiler.tokenize(code, allow_inline_scripts=allow_inline_scripts)
+    return [
+        LexerToken(
+            type=token.type,
+            value=token.value,
+            line=token.line,
+            col=token.col,
+        )
+        for token in tokens
+    ]
+
+
+def tokenize_tw(code: str) -> List[LexerToken]:
+    return tokenize(code, allow_inline_scripts=True)
+
+
+def tokenize_file(path: str) -> List[LexerToken]:
+    compiler = _legacy()
+    return tokenize_tw(compiler.read_text_file(path))
+
+
+__all__ = ["LexerToken", "tokenize", "tokenize_file", "tokenize_tw"]

tw_framework/lowering.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from .ast_nodes import ComponentNode, ElementNode, ForNode, IfNode, LetNode, Program, ScriptNode, TextNode
+from .ir import IRComponent, IRElement, IRFor, IRIf, IRLet, IRProgram, IRScript, IRText
+
+
+def lower_node(node):
+    if isinstance(node, TextNode):
+        return IRText(node.value)
+    if isinstance(node, LetNode):
+        return IRLet(node.name, node.value)
+    if isinstance(node, IfNode):
+        return IRIf(
+            condition=node.condition,
+            children=[lower_node(child) for child in node.children],
+            else_children=[lower_node(child) for child in node.else_children],
+        )
+    if isinstance(node, ForNode):
+        return IRFor(
+            var_name=node.var_name,
+            iterable=node.iterable,
+            children=[lower_node(child) for child in node.children],
+        )
+    if isinstance(node, ScriptNode):
+        return IRScript(node.raw_js)
+    if isinstance(node, ComponentNode):
+        return IRComponent(
+            name=node.name,
+            props=[{"name": prop.name, "value": prop.value} for prop in node.props],
+            children=[lower_node(child) for child in node.children],
+        )
+    if isinstance(node, ElementNode):
+        return IRElement(
+            tag=node.tag,
+            text=node.text,
+            attrs=[{"name": attr.name, "value": attr.value} for attr in node.attrs],
+            styles=[{"name": attr.name, "value": attr.value} for attr in node.styles],
+            events=[{"name": attr.name, "value": attr.value} for attr in node.events],
+            router=dict(node.router),
+            children=[lower_node(child) for child in node.children],
+        )
+    raise TypeError(f"Unsupported AST node: {type(node)!r}")
+
+
+def lower_program(program: Program) -> IRProgram:
+    return IRProgram(
+        meta={
+            "title": program.meta.title,
+            "layout": program.meta.layout,
+            "layouts": list(program.meta.layouts),
+            "render_mode": program.meta.render_mode,
+            "revalidate": program.meta.revalidate,
+            "redirect_to": program.meta.redirect_to,
+            "rewrite_to": program.meta.rewrite_to,
+            "responsive": program.meta.responsive,
+        },
+        head={
+            "metas": list(program.head.metas),
+            "icon": program.head.icon,
+            "seo": dict(program.head.seo),
+        },
+        lets=dict(program.lets),
+        state=dict(program.state),
+        body=[lower_node(node) for node in program.body],
+    )
+
+
+__all__ = ["lower_node", "lower_program"]

tw_framework/parser.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import os
+import ast
+import warnings
+from typing import Any, List
+
+from .ast_nodes import (
+    Attribute,
+    ComponentNode,
+    ElementNode,
+    ForNode,
+    HeadModel,
+    IfNode,
+    LetNode,
+    PageMeta,
+    Program,
+    ScriptNode,
+    node_to_dict,
+)
+from .lexer import tokenize_tw
+
+
+def _legacy():
+    from . import compiler
+
+    return compiler
+
+
+def _convert_node(node: Any):
+    tag = getattr(node, "tag", "")
+    if tag == "__let__":
+        return LetNode(node.name, node.value)
+    if tag == "__if__":
+        return IfNode(
+            condition=node.condition,
+            children=[_convert_node(child) for child in getattr(node, "children", [])],
+            else_children=[_convert_node(child) for child in getattr(node, "else_children", [])],
+        )
+    if tag == "__for__":
+        return ForNode(
+            var_name=node.var_name,
+            iterable=node.list_expr,
+            children=[_convert_node(child) for child in getattr(node, "children", [])],
+        )
+    if tag == "__script__":
+        return ScriptNode(node.raw_js)
+    if tag == "__script_tag__":
+        # Declarative external script tag (Next.js-like). In the modular AST we
+        # model it as a regular <script> element with a data attribute so the
+        # structure is still meaningful for analysis/debugging.
+        return ElementNode(
+            tag="script",
+            text=None,
+            attrs=[
+                Attribute(name="src", value=getattr(node, "src", "")),
+                Attribute(name="data-tw-strategy", value=getattr(node, "strategy", "")),
+            ],
+            styles=[],
+            events=[],
+            router={},
+            children=[],
+        )
+    if tag == "__component__":
+        return ComponentNode(
+            name=node.name,
+            props=[Attribute(name=name, value=value) for name, value in getattr(node, "props", [])],
+            children=[_convert_node(child) for child in getattr(node, "children", [])],
+        )
+    return ElementNode(
+        tag=getattr(node, "tag", "div"),
+        text=getattr(node, "text", None),
+        attrs=[Attribute(name=name, value=value) for name, value in getattr(node, "attrs", [])],
+        styles=[Attribute(name=name, value=value) for name, value in getattr(node, "inline_style", [])],
+        events=[Attribute(name=name, value=value) for name, value in getattr(node, "events", [])],
+        router=dict(getattr(node, "router", {}) or {}),
+        children=[_convert_node(child) for child in getattr(node, "children", [])],
+    )
+
+
+def _normalize_scalar(value: Any):
+    compiler = _legacy()
+    if not isinstance(value, str):
+        return value
+    stripped = value.strip()
+    if len(stripped) >= 2 and stripped[0] == stripped[-1] and stripped[0] in {"'", '"'}:
+        try:
+            return ast.literal_eval(stripped)
+        except Exception as err:
+            warnings.warn(
+                f"Malformed quoted literal {stripped!r}: {err}. Falling back to raw string content.",
+                RuntimeWarning,
+            )
+            return stripped[1:-1]
+    return compiler.parse_literal_value(stripped)
+
+
+def from_legacy_page(page, source_path: str = "") -> Program:
+    program = Program(
+        meta=PageMeta(
+            title=page.title,
+            layout=page.layout,
+            layouts=list(getattr(page, "layouts", []) or []),
+            render_mode=page.render_mode,
+            revalidate=page.revalidate,
+            redirect_to=page.redirect_to,
+            rewrite_to=page.rewrite_to,
+            responsive=bool(getattr(page, "responsive", False)),
+        ),
+        head=HeadModel(
+            metas=list(getattr(page.head, "metas", []) or []),
+            icon=getattr(page.head, "icon", None),
+            seo=dict(getattr(page.head, "seo", {}) or {}),
+        ),
+        lets={key: _normalize_scalar(value) for key, value in dict(getattr(page, "let_vars", {}) or {}).items()},
+        state={key: _normalize_scalar(value) for key, value in dict(getattr(page, "state_vars", {}) or {}).items()},
+        body=[_convert_node(node) for node in getattr(page, "body", [])],
+        loaded_sheets=list(getattr(page, "loaded_sheets", []) or []),
+        loaded_json=list(getattr(page, "loaded_json", []) or []),
+        source_path=source_path or getattr(page, "_tw_source_path", ""),
+        legacy_page=page,
+    )
+    return program
+
+
+def parse_text(text: str, base_dir: str = ".", file_path: str = "<memory>", debug: bool = False) -> Program:
+    compiler = _legacy()
+    tokens = compiler.tokenize_tw(text)
+    page = compiler.build_tw_ast(tokens, base_dir, file_path, text)
+    page._tw_source_path = file_path
+    return from_legacy_page(page, source_path=file_path)
+
+
+def parse_file(path: str, debug: bool = False) -> Program:
+    compiler = _legacy()
+    source = compiler.read_text_file(path)
+    return parse_text(source, base_dir=compiler.normalize_path(os.path.dirname(path)), file_path=path, debug=debug)
+
+
+def build_tw_ast(tokens, base_dir, file_path, source):
+    compiler = _legacy()
+    return compiler.build_tw_ast(tokens, base_dir, file_path, source)
+
+
+def build_tss_ast_from_text(text: str):
+    compiler = _legacy()
+    return compiler.build_tss_ast_from_text(text)
+
+
+def program_to_dict(program: Program):
+    return program.to_dict()
+
+
+def nodes_to_dict(nodes: List[Any]):
+    return [node_to_dict(node) for node in nodes]
+
+
+__all__ = [
+    "build_tss_ast_from_text",
+    "build_tw_ast",
+    "from_legacy_page",
+    "nodes_to_dict",
+    "parse_file",
+    "parse_text",
+    "program_to_dict",
+    "tokenize_tw",
+]