pyflashkit 1.0.0__py3-none-any.whl

flashkit/swf/builder.py

@@ -0,0 +1,283 @@
+"""
+SWF container builder.
+
+Provides functions to serialize SWF tags, rebuild complete SWF files,
+create new DoABC2 tags, and build SWF files from scratch.
+
+Usage — modify an existing SWF::
+
+    from flashkit.swf.parser import parse_swf
+    from flashkit.swf.builder import rebuild_swf, make_doabc2_tag
+
+    header, tags, version, length = parse_swf(swf_bytes)
+    new_tag = make_doabc2_tag("MyCode", abc_bytes)
+    tags.insert(-1, new_tag)
+    output = rebuild_swf(header, tags, compress=True)
+
+Usage — build a SWF from scratch::
+
+    from flashkit.swf.builder import SwfBuilder
+
+    swf = SwfBuilder(version=40, width=800, height=600, fps=30)
+    swf.add_abc("MainCode", abc_bytes)
+    swf.set_document_class("com.example.Main")
+    output = swf.build(compress=True)
+
+Reference: SWF File Format Specification v19, Chapter 2.
+"""
+
+from __future__ import annotations
+
+import struct
+import zlib
+
+from .tags import SWFTag, TAG_DO_ABC, TAG_DO_ABC2, TAG_END, TAG_SYMBOL_CLASS
+
+
+def build_tag_bytes(tag: SWFTag) -> bytes:
+    """Serialize a single SWFTag to its binary representation.
+
+    Uses short headers (2 bytes) for small non-ABC tags and long headers
+    (6 bytes) for large payloads or DoABC/DoABC2 tags.
+
+    Args:
+        tag: The SWFTag to serialize.
+
+    Returns:
+        Raw bytes for this tag (header + payload).
+    """
+    payload_len = len(tag.payload)
+    if payload_len < 0x3F and tag.tag_type not in (TAG_DO_ABC, TAG_DO_ABC2):
+        # Short header — only for small non-ABC tags
+        header = struct.pack("<H", (tag.tag_type << 6) | payload_len)
+        return header + tag.payload
+    else:
+        # Long header
+        header = struct.pack("<H", (tag.tag_type << 6) | 0x3F)
+        header += struct.pack("<I", payload_len)
+        return header + tag.payload
+
+
+def rebuild_swf(
+    header_bytes: bytes,
+    tags: list[SWFTag],
+    compress: bool = True,
+) -> bytes:
+    """Rebuild a complete SWF file from header and tags.
+
+    Recomputes the file length field and optionally zlib-compresses
+    the output.
+
+    Args:
+        header_bytes: Original SWF header (from ``parse_swf()``).
+        tags: List of SWFTag objects.
+        compress: If True, output CWS (zlib-compressed). Default True.
+
+    Returns:
+        Complete SWF file bytes.
+    """
+    body = b""
+    for tag in tags:
+        body += build_tag_bytes(tag)
+
+    raw = header_bytes + body
+    # Update file length field (bytes 4-7)
+    raw = raw[:4] + struct.pack("<I", len(raw)) + raw[8:]
+
+    if compress:
+        return b"CWS" + raw[3:8] + zlib.compress(raw[8:], 9)
+    else:
+        return raw
+
+
+def make_doabc2_tag(
+    name: str,
+    abc_data: bytes,
+    lazy_init: bool = True,
+) -> SWFTag:
+    """Create a DoABC2 tag (type 82).
+
+    DoABC2 tags contain flags, a null-terminated name, and the ABC
+    bytecode data.
+
+    Args:
+        name: Name string for the ABC block.
+        abc_data: Raw ABC bytecode bytes.
+        lazy_init: If True, set the lazy initialization flag. Default True.
+
+    Returns:
+        A new SWFTag with tag_type=82.
+    """
+    flags = struct.pack("<I", 1 if lazy_init else 0)
+    name_bytes = name.encode("utf-8") + b"\x00"
+    payload = flags + name_bytes + abc_data
+    return SWFTag(tag_type=TAG_DO_ABC2, payload=payload, name=name)
+
+
+def make_symbol_class_tag(symbols: list[tuple[int, str]]) -> SWFTag:
+    """Create a SymbolClass tag (type 76).
+
+    Maps character IDs to class names. Character ID 0 with a class
+    name defines the document class.
+
+    Args:
+        symbols: List of (character_id, class_name) pairs.
+
+    Returns:
+        A new SWFTag with tag_type=76.
+    """
+    payload = struct.pack("<H", len(symbols))
+    for char_id, name in symbols:
+        payload += struct.pack("<H", char_id)
+        payload += name.encode("utf-8") + b"\x00"
+    return SWFTag(tag_type=TAG_SYMBOL_CLASS, payload=payload)
+
+
+def make_end_tag() -> SWFTag:
+    """Create an End tag (type 0)."""
+    return SWFTag(tag_type=TAG_END, payload=b"")
+
+
+class SwfBuilder:
+    """High-level builder for constructing SWF files from scratch.
+
+    Handles the header, RECT, frame rate, and tag assembly.
+    Add ABC blocks and symbol mappings, then call ``build()``.
+
+    Args:
+        version: SWF version number. Default 40.
+        width: Stage width in pixels. Default 800.
+        height: Stage height in pixels. Default 600.
+        fps: Frame rate. Default 24.
+        frame_count: Total frames. Default 1.
+    """
+
+    def __init__(
+        self,
+        version: int = 40,
+        width: int = 800,
+        height: int = 600,
+        fps: int = 24,
+        frame_count: int = 1,
+    ) -> None:
+        self.version = version
+        self.width = width
+        self.height = height
+        self.fps = fps
+        self.frame_count = frame_count
+        self._tags: list[SWFTag] = []
+        self._symbols: list[tuple[int, str]] = []
+
+    def add_tag(self, tag: SWFTag) -> None:
+        """Add a raw SWF tag.
+
+        Args:
+            tag: Any SWFTag to include before the End tag.
+        """
+        self._tags.append(tag)
+
+    def add_abc(self, name: str, abc_data: bytes,
+                lazy_init: bool = True) -> None:
+        """Add an ABC bytecode block as a DoABC2 tag.
+
+        Args:
+            name: Name for the ABC block.
+            abc_data: Serialized ABC bytes.
+            lazy_init: Whether to set the lazy init flag.
+        """
+        self._tags.append(make_doabc2_tag(name, abc_data, lazy_init))
+
+    def add_symbol(self, char_id: int, class_name: str) -> None:
+        """Map a character ID to a class name.
+
+        Args:
+            char_id: Character ID (0 for document class).
+            class_name: Fully qualified class name.
+        """
+        self._symbols.append((char_id, class_name))
+
+    def set_document_class(self, class_name: str) -> None:
+        """Set the document class (character ID 0).
+
+        Args:
+            class_name: Fully qualified class name.
+        """
+        self.add_symbol(0, class_name)
+
+    def _build_header(self) -> bytes:
+        """Build the SWF header bytes (before tags)."""
+        # Encode RECT in twips (1 pixel = 20 twips)
+        xmax = self.width * 20
+        ymax = self.height * 20
+        # Calculate nbits needed
+        max_val = max(xmax, ymax)
+        nbits = max_val.bit_length() if max_val > 0 else 1
+
+        # Pack RECT as bits: 5-bit nbits + 4 fields of nbits each
+        # Xmin=0, Xmax, Ymin=0, Ymax
+        total_bits = 5 + 4 * nbits
+        total_bytes = (total_bits + 7) // 8
+        rect = bytearray(total_bytes)
+
+        # Write bits
+        bit_pos = 0
+
+        def write_bits(value: int, count: int) -> None:
+            nonlocal bit_pos
+            for i in range(count - 1, -1, -1):
+                byte_idx = bit_pos // 8
+                bit_idx = 7 - (bit_pos % 8)
+                if value & (1 << i):
+                    rect[byte_idx] |= (1 << bit_idx)
+                bit_pos += 1
+
+        write_bits(nbits, 5)
+        write_bits(0, nbits)      # Xmin
+        write_bits(xmax, nbits)   # Xmax
+        write_bits(0, nbits)      # Ymin
+        write_bits(ymax, nbits)   # Ymax
+
+        # Frame rate (8.8 fixed point) + frame count
+        frame_rate = struct.pack("<BB", 0, self.fps)
+        frame_count = struct.pack("<H", self.frame_count)
+
+        header = bytearray()
+        header += b"FWS"
+        header += bytes([self.version])
+        header += struct.pack("<I", 0)  # file length (filled later)
+        header += rect
+        header += frame_rate
+        header += frame_count
+        return bytes(header)
+
+    def build(self, compress: bool = True) -> bytes:
+        """Build the complete SWF file.
+
+        Args:
+            compress: If True, produce CWS (zlib-compressed). Default True.
+
+        Returns:
+            Complete SWF file bytes.
+        """
+        header = self._build_header()
+
+        # Assemble tags
+        tags_bytes = bytearray()
+        for tag in self._tags:
+            tags_bytes += build_tag_bytes(tag)
+
+        # Add SymbolClass if symbols were defined
+        if self._symbols:
+            tags_bytes += build_tag_bytes(make_symbol_class_tag(self._symbols))
+
+        # End tag
+        tags_bytes += build_tag_bytes(make_end_tag())
+
+        # Combine and set file length
+        raw = bytearray(header) + tags_bytes
+        struct.pack_into("<I", raw, 4, len(raw))
+
+        if compress:
+            return b"CWS" + bytes(raw[3:8]) + zlib.compress(bytes(raw[8:]), 9)
+        else:
+            return bytes(raw)

flashkit/swf/parser.py

@@ -0,0 +1,164 @@
+"""
+SWF container parser.
+
+Parses SWF files (compressed or uncompressed) into a header and a list
+of ``SWFTag`` objects. Handles CWS (zlib-compressed) and FWS (uncompressed)
+signatures.
+
+Usage::
+
+    from flashkit.swf.parser import parse_swf
+
+    with open("application.swf", "rb") as f:
+        header, tags, version, file_length = parse_swf(f.read())
+
+    for tag in tags:
+        print(f"{tag.type_name}: {len(tag.payload)} bytes")
+
+Reference: SWF File Format Specification v19, Chapter 1-2.
+"""
+
+from __future__ import annotations
+
+import struct
+import zlib
+
+from ..errors import SWFParseError
+from .tags import SWFTag, TAG_NAMES, TAG_END, TAG_DO_ABC, TAG_DO_ABC2, TAG_SYMBOL_CLASS
+
+
+def _parse_rect_size(data: bytes, offset: int) -> int:
+    """Calculate how many bytes a RECT structure occupies.
+
+    The RECT is a bit-packed structure where the first 5 bits encode
+    the number of bits per field (Xmin, Xmax, Ymin, Ymax).
+
+    Args:
+        data: Raw SWF bytes.
+        offset: Byte offset where the RECT starts.
+
+    Returns:
+        Number of bytes the RECT occupies.
+    """
+    nbits = (data[offset] >> 3) & 0x1F
+    total_bits = 5 + 4 * nbits
+    return (total_bits + 7) // 8
+
+
+def parse_swf(data: bytes) -> tuple[bytes, list[SWFTag], int, int]:
+    """Parse a SWF file (compressed or uncompressed).
+
+    Handles both CWS (zlib-compressed) and FWS (uncompressed) formats.
+    The returned header bytes include everything up to the first tag
+    (signature, version, file length, RECT, frame rate, frame count).
+
+    Args:
+        data: Raw SWF file bytes.
+
+    Returns:
+        Tuple of (header_bytes, tags, version, file_length).
+
+    Raises:
+        SWFParseError: If the data is not a valid SWF file.
+    """
+    if not data:
+        raise SWFParseError("SWF data is empty")
+    if len(data) < 8:
+        raise SWFParseError(
+            f"SWF data too short ({len(data)} bytes, minimum 8)")
+
+    sig = data[:3]
+    if sig == b"CWS":
+        try:
+            raw = data[:8] + zlib.decompress(data[8:])
+        except zlib.error as e:
+            raise SWFParseError(
+                f"Failed to decompress CWS data: {e}") from e
+        raw = b"FWS" + raw[3:]  # fix signature to uncompressed
+    elif sig == b"FWS":
+        raw = data
+    else:
+        raise SWFParseError(f"Not a SWF file (signature: {sig!r})")
+
+    try:
+        version = raw[3]
+        file_length = struct.unpack_from("<I", raw, 4)[0]
+
+        # RECT + frame rate (2 bytes) + frame count (2 bytes)
+        rect_size = _parse_rect_size(raw, 8)
+        header_end = 8 + rect_size + 4
+        header_bytes = raw[:header_end]
+
+        # Parse tags
+        tags: list[SWFTag] = []
+        pos = header_end
+        while pos < len(raw) - 1:
+            tag_raw = struct.unpack_from("<H", raw, pos)[0]
+            tag_type = (tag_raw >> 6) & 0x3FF
+            tag_len = tag_raw & 0x3F
+            header_size = 2
+
+            if tag_len == 0x3F:
+                # Extended length: next 4 bytes are the actual length
+                tag_len = struct.unpack_from("<I", raw, pos + 2)[0]
+                header_size = 6
+
+            payload = raw[pos + header_size: pos + header_size + tag_len]
+            tag = SWFTag(tag_type=tag_type, payload=payload)
+
+            # Extract name from DoABC2 tags (4-byte flags + null-terminated name)
+            if tag_type == TAG_DO_ABC2 and len(payload) > 4:
+                null_idx = payload.index(0, 4)
+                tag.name = payload[4:null_idx].decode("utf-8", errors="replace")
+
+            tags.append(tag)
+
+            if tag_type == TAG_END:
+                break
+            pos += header_size + tag_len
+
+    except SWFParseError:
+        raise
+    except (IndexError, struct.error, ValueError, OverflowError) as e:
+        raise SWFParseError(f"Corrupted SWF data: {e}") from e
+
+    return header_bytes, tags, version, file_length
+
+
+def print_tags(tags: list[SWFTag]) -> None:
+    """Pretty-print a SWF tag list to stdout.
+
+    Shows tag index, type, name, size, and extra info for known tag types
+    (ABC version for DoABC, symbol names for SymbolClass, etc.).
+
+    Args:
+        tags: List of SWFTag objects from ``parse_swf()``.
+    """
+    for i, tag in enumerate(tags):
+        extra = ""
+        if tag.tag_type == TAG_DO_ABC2:
+            extra = f'  name="{tag.name}"'
+        elif tag.tag_type == TAG_DO_ABC:
+            if len(tag.payload) >= 4:
+                minor, major = struct.unpack_from("<HH", tag.payload, 0)
+                extra = f"  ABC v{minor}.{major}"
+        elif tag.tag_type == TAG_SYMBOL_CLASS:
+            if len(tag.payload) >= 2:
+                count = struct.unpack_from("<H", tag.payload, 0)[0]
+                extra = f"  {count} symbol(s)"
+                off = 2
+                for j in range(min(count, 5)):
+                    cid = struct.unpack_from("<H", tag.payload, off)[0]
+                    off += 2
+                    null_idx = tag.payload.index(0, off)
+                    sname = tag.payload[off:null_idx].decode(
+                        "utf-8", errors="replace")
+                    off = null_idx + 1
+                    doc = " [DOCUMENT CLASS]" if cid == 0 else ""
+                    extra += (
+                        f'\n          CharID={cid} -> "{sname}"{doc}')
+
+        size_str = f"{len(tag.payload):>10,}"
+        print(
+            f"  [{i:2d}] Tag {tag.tag_type:3d} "
+            f"({tag.type_name:<30s})  {size_str} bytes{extra}")

flashkit/swf/tags.py

@@ -0,0 +1,120 @@
+"""
+SWF tag definitions and constants.
+
+Defines the ``SWFTag`` dataclass and well-known SWF tag type IDs.
+The tag type constants eliminate magic numbers when working with
+parsed SWF tag lists.
+
+Reference: SWF File Format Specification v19, Chapter 2 (SWF structure).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# ── Tag type constants ──────────────────────────────────────────────────────
+
+TAG_END                            = 0
+TAG_SHOW_FRAME                     = 1
+TAG_SET_BACKGROUND_COLOR           = 9
+TAG_DEFINE_SHAPE                   = 2
+TAG_DEFINE_BITS                    = 6
+TAG_DEFINE_BUTTON                  = 7
+TAG_JPEG_TABLES                    = 8
+TAG_DEFINE_TEXT                    = 11
+TAG_DO_ACTION                      = 12
+TAG_DEFINE_SOUND                   = 14
+TAG_DEFINE_BITS_LOSSLESS           = 20
+TAG_DEFINE_BITS_JPEG2              = 21
+TAG_PLACE_OBJECT2                  = 26
+TAG_REMOVE_OBJECT2                 = 28
+TAG_DEFINE_SHAPE3                  = 32
+TAG_DEFINE_TEXT2                   = 33
+TAG_DEFINE_BITS_JPEG3              = 35
+TAG_DEFINE_BITS_LOSSLESS2          = 36
+TAG_DEFINE_EDIT_TEXT               = 37
+TAG_DEFINE_SPRITE                  = 39
+TAG_FRAME_LABEL                    = 43
+TAG_DEFINE_MORPH_SHAPE             = 46
+TAG_DEFINE_FONT2                   = 48
+TAG_EXPORT_ASSETS                  = 56
+TAG_IMPORT_ASSETS                  = 57
+TAG_DO_INIT_ACTION                 = 59
+TAG_DEFINE_VIDEO_STREAM            = 60
+TAG_DEFINE_FONT3                   = 75
+TAG_SCRIPT_LIMITS                  = 65
+TAG_FILE_ATTRIBUTES                = 69
+TAG_PLACE_OBJECT3                  = 70
+TAG_DO_ABC                         = 72   # Raw ABC bytecode (AVM2)
+TAG_SYMBOL_CLASS                   = 76   # Maps character IDs to class names
+TAG_DEFINE_BINARY_DATA             = 77
+TAG_DO_ABC2                        = 82   # Named ABC bytecode (flags + name + ABC)
+TAG_DEFINE_SCENE_AND_FRAME_LABEL   = 86
+TAG_DEBUG_ID                       = 255
+
+# ── Human-readable tag names ────────────────────────────────────────────────
+
+TAG_NAMES: dict[int, str] = {
+    TAG_END: "End",
+    TAG_SHOW_FRAME: "ShowFrame",
+    TAG_SET_BACKGROUND_COLOR: "SetBackgroundColor",
+    TAG_DEFINE_SHAPE: "DefineShape",
+    TAG_DEFINE_BITS: "DefineBits",
+    TAG_DEFINE_BUTTON: "DefineButton",
+    TAG_JPEG_TABLES: "JPEGTables",
+    TAG_DEFINE_TEXT: "DefineText",
+    TAG_DO_ACTION: "DoAction",
+    TAG_DEFINE_SOUND: "DefineSound",
+    TAG_DEFINE_BITS_LOSSLESS: "DefineBitsLossless",
+    TAG_DEFINE_BITS_JPEG2: "DefineBitsJPEG2",
+    TAG_PLACE_OBJECT2: "PlaceObject2",
+    TAG_REMOVE_OBJECT2: "RemoveObject2",
+    TAG_DEFINE_SHAPE3: "DefineShape3",
+    TAG_DEFINE_TEXT2: "DefineText2",
+    TAG_DEFINE_BITS_JPEG3: "DefineBitsJPEG3",
+    TAG_DEFINE_BITS_LOSSLESS2: "DefineBitsLossless2",
+    TAG_DEFINE_EDIT_TEXT: "DefineEditText",
+    TAG_DEFINE_SPRITE: "DefineSprite",
+    TAG_FRAME_LABEL: "FrameLabel",
+    TAG_DEFINE_MORPH_SHAPE: "DefineMorphShape",
+    TAG_DEFINE_FONT2: "DefineFont2",
+    TAG_EXPORT_ASSETS: "ExportAssets",
+    TAG_IMPORT_ASSETS: "ImportAssets",
+    TAG_DO_INIT_ACTION: "DoInitAction",
+    TAG_DEFINE_VIDEO_STREAM: "DefineVideoStream",
+    TAG_DEFINE_FONT3: "DefineFont3",
+    TAG_SCRIPT_LIMITS: "ScriptLimits",
+    TAG_FILE_ATTRIBUTES: "FileAttributes",
+    TAG_PLACE_OBJECT3: "PlaceObject3",
+    TAG_DO_ABC: "DoABC",
+    TAG_SYMBOL_CLASS: "SymbolClass",
+    TAG_DEFINE_BINARY_DATA: "DefineBinaryData",
+    TAG_DO_ABC2: "DoABC2",
+    TAG_DEFINE_SCENE_AND_FRAME_LABEL: "DefineSceneAndFrameLabelData",
+    TAG_DEBUG_ID: "DebugID",
+}
+
+
+# ── SWFTag dataclass ────────────────────────────────────────────────────────
+
+@dataclass
+class SWFTag:
+    """A single tag from a SWF file.
+
+    SWF files are a sequence of typed tags. Each tag has a type ID,
+    a payload, and optionally a name (for DoABC2 tags).
+
+    Attributes:
+        tag_type: Numeric tag type ID (see TAG_* constants).
+        payload: Raw tag payload bytes.
+        name: Tag name string (populated for DoABC2 tags).
+    """
+    tag_type: int
+    payload: bytes
+    name: str = ""
+
+    @property
+    def type_name(self) -> str:
+        """Human-readable tag type name."""
+        return TAG_NAMES.get(self.tag_type, f"Unknown({self.tag_type})")

flashkit/workspace/__init__.py

@@ -0,0 +1,20 @@
+"""
+Workspace and resource management.
+
+A ``Workspace`` loads one or more SWF/SWZ files, extracts their ABC
+bytecode, parses it, and builds a unified index of all classes, methods,
+and strings. It is the top-level entry point for analysis.
+
+A ``Resource`` represents a single loaded file (SWF or SWZ) with its
+parsed tags and ABC content.
+"""
+
+from .resource import Resource, load_swf, load_swz
+from .workspace import Workspace
+
+__all__ = [
+    "Workspace",
+    "Resource",
+    "load_swf",
+    "load_swz",
+]