pymppwriter 0.3.0__py3-none-any.whl

pymppwriter/__init__.py

@@ -0,0 +1,12 @@
+from .writer import (MppWriter, Project, Task, Relation, Resource, Assignment,
+                     Calendar, CalendarException, ScheduleWarning, validate)
+from .reader import read_project, MppReadError
+
+try:                                    # the installed distribution's version
+    from importlib.metadata import PackageNotFoundError, version as _version
+    __version__ = _version("pymppwriter")
+except (ImportError, PackageNotFoundError):     # running from a source tree
+    __version__ = "0.0.0.dev0"
+__all__ = ["MppWriter", "Project", "Task", "Relation", "Resource", "Assignment",
+           "Calendar", "CalendarException", "ScheduleWarning", "validate",
+           "read_project", "MppReadError", "__version__"]

pymppwriter/blocks.py

@@ -0,0 +1,363 @@
+"""Decoders/encoders for the block structures inside an MPP14 file.
+
+Layouts derived from the public behaviour of the LGPL MPXJ reader and from
+diffing files saved by Microsoft Project.
+"""
+from __future__ import annotations
+import struct
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Tuple
+
+MAGIC = 0xFADFADBA
+EPOCH = datetime(1983, 12, 31)
+
+PROPS_TASK_FIELD_MAP = 131092
+PROPS_RESOURCE_FIELD_MAP = 131093
+PROPS_RELATION_FIELD_MAP = 131094
+PROPS_ASSIGNMENT_FIELD_MAP = 131095
+PROPS_PROJECT_START_DATE = 37748738
+PROPS_PROJECT_FINISH_DATE = 37748739      # 0x2400003
+PROPS_TITLE = 37748744
+PROPS_DEFAULT_CALENDAR_NAME = 37748750    # UTF-16 name + 4 NUL bytes
+PROPS_CURRENCY_SYMBOL = 37748752          # 0x2400010
+PROPS_STATUS_DATE = 37748805              # 0x2400045; 0xFFFFFFFF = NA
+PROPS_CURRENCY_CODE = 37753787            # 0x24013BB, e.g. "USD"
+PROPS_LEGACY_NEXT_UIDS = 37748910         # 0x24000AE: 2010-era only; stale values make
+                                          # Project renumber task uids, M365 drops it on save
+PROPS_EDITED_BASE_CALENDARS = 8388609     # 0x800001: base calendars with custom data
+# 0x10001..: Var2Data byte length per storage — Project truncates its var-data
+# read at the declared length, so a stale value hides var entries
+PROPS_VAR2DATA_SIZE = {"TBkndTask": 65537, "TBkndRsc": 65538, "TBkndCal": 65539,
+                       "TBkndAssn": 65540}
+# record-count dwords: Project sizes its tables from these on load and drops
+# records beyond the count (verified against four Project-written files)
+PROPS_TASK_RECORD_COUNT = 16777217        # 0x1000001, includes stubs + uid-0 summary
+PROPS_RESOURCE_RECORD_COUNT = 16777218    # 0x1000002
+PROPS_ASSN_RECORD_COUNT = 16777220        # 0x1000004
+PROPS_REL_RECORD_COUNT = 16777221         # 0x1000005
+
+
+# ---------------------------------------------------------------- Props ----
+PROPS_TYPES: Dict[int, int] = {}   # key -> type code (third dword of each entry; 0/2/4/9 observed)
+
+
+def parse_props(data: bytes) -> Tuple[bytes, Dict[int, bytes], List[int]]:
+    """Return (16-byte header, {key: value}, key order). Entry type codes are kept in PROPS_TYPES."""
+    header = data[:16]
+    count = struct.unpack_from("<H", header, 12)[0]
+    pos, out, order = 16, {}, []
+    for _ in range(count):
+        if len(data) - pos < 12:
+            break
+        size, key, ptype = struct.unpack_from("<III", data, pos)
+        pos += 12
+        val = data[pos:pos + size]
+        pos += size + (size & 1)  # 2-byte alignment
+        out[key] = val
+        PROPS_TYPES[key] = ptype
+        order.append(key)
+    return header, out, order
+
+
+def build_props(header: bytes, values: Dict[int, bytes], order: List[int]) -> bytes:
+    hdr = bytearray(header)
+    struct.pack_into("<H", hdr, 12, len(order))
+    body = bytearray()
+    for key in order:
+        val = values[key]
+        body += struct.pack("<III", len(val), key, PROPS_TYPES.get(key, 0)) + val
+        if len(val) & 1:
+            body += b"\0"
+    total = len(hdr) + len(body)
+    struct.pack_into("<II", hdr, 0, total - 4, total - 4)   # header dwords 0,1 = stream size - 4
+    return bytes(hdr) + bytes(body)
+
+
+# ------------------------------------------------------------- FieldMap ----
+@dataclass
+class FieldItem:
+    type_value: int        # MS Project field ID (TaskField/ResourceField numeric)
+    block: int             # 0 = FixedData, 1 = Fixed2Data
+    offset: int            # byte offset within the fixed record (65535 = not fixed)
+    var_key: int           # key in Var2Data when stored as variable data
+    category: int
+    mask: int
+    raw: bytes
+
+    @property
+    def in_fixed(self) -> bool:
+        return self.category not in (0x0B, 0x64) and self.offset != 65535
+
+    @property
+    def in_meta(self) -> bool:
+        return self.category in (0x0B, 0x64)
+
+
+def parse_field_map(data: bytes) -> List[FieldItem]:
+    items, last, block = [], 0, 0
+    for i in range(0, len(data) - 27, 28):
+        mask = struct.unpack_from("<I", data, i)[0]
+        offset = struct.unpack_from("<H", data, i + 4)[0]
+        var_key = data[i + 6]
+        type_value = struct.unpack_from("<I", data, i + 12)[0]
+        category = struct.unpack_from("<H", data, i + 20)[0]
+        if category not in (0x0B, 0x64) and offset != 65535:
+            if offset < last:
+                block += 1
+            last = offset
+        items.append(FieldItem(type_value, block, offset, var_key, category, mask, data[i:i + 28]))
+    return items
+
+
+# -------------------------------------------------------- Fixed blocks -----
+def parse_fixed_meta(data: bytes, item_size: int) -> Tuple[bytes, int, List[bytes]]:
+    magic, unk, count, unk2 = struct.unpack_from("<IIII", data, 0)
+    assert magic == MAGIC, hex(magic)
+    n = (len(data) - 16) // item_size
+    items = [data[16 + i * item_size:16 + (i + 1) * item_size] for i in range(n)]
+    return data[:16], count, items
+
+
+def parse_fixed_meta_auto(data: bytes, default_size: int) -> Tuple[bytes, int, List[bytes]]:
+    """parse_fixed_meta with the item size derived from the header count, so
+    files of any Project vintage parse (M365 uses 96/51/10-byte Fixed2Meta
+    items where 2010-era files use 92/50/9). Falls back to default_size when
+    the stream length is not an exact multiple (trailing slack)."""
+    count = struct.unpack_from("<I", data, 8)[0]
+    size = default_size
+    if count and (len(data) - 16) % count == 0:
+        size = (len(data) - 16) // count
+    return parse_fixed_meta(data, size)
+
+
+def build_fixed_meta(header: bytes, items: List[bytes], data_len: Optional[int] = None) -> bytes:
+    hdr = bytearray(header)
+    struct.pack_into("<I", hdr, 8, len(items))
+    if data_len is not None:
+        struct.pack_into("<I", hdr, 12, data_len)   # header dword 3 = FixedData byte length
+    return bytes(hdr) + b"".join(items)
+
+
+def split_fixed_data(data: bytes, meta_items: List[bytes]) -> List[bytes]:
+    out = []
+    for i, m in enumerate(meta_items):
+        off = struct.unpack_from("<I", m, 4)[0]
+        if i + 1 < len(meta_items):
+            nxt = struct.unpack_from("<I", meta_items[i + 1], 4)[0]
+        else:
+            nxt = len(data)
+        out.append(data[off:nxt])
+    return out
+
+
+# ------------------------------------------------------- meta bitmaps ------
+# A FixedMeta / Fixed2Meta item is: uint32 flags, uint32 offset-in-FixedData,
+# then a bitmap with one bit per TASK_FIELD_MAP entry (little-endian bit order).
+# FixedMeta carries entries 0..(item_size-8)*8-1; Fixed2Meta continues from there.
+# Boolean fields (category 0x0B/0x64) store their value in their entry's bit;
+# for other fields the bit marks the field as populated.
+
+def meta_bit(meta: bytes, meta2: bytes, entry_index: int) -> Optional[int]:
+    nbits0 = (len(meta) - 8) * 8
+    buf, i = (meta, entry_index) if entry_index < nbits0 else (meta2, entry_index - nbits0)
+    byte = 8 + i // 8
+    if byte >= len(buf):
+        return None
+    return (buf[byte] >> (i % 8)) & 1
+
+
+def set_meta_bit(meta: bytearray, meta2: bytearray, entry_index: int, value: bool) -> None:
+    nbits0 = (len(meta) - 8) * 8
+    buf, i = (meta, entry_index) if entry_index < nbits0 else (meta2, entry_index - nbits0)
+    byte = 8 + i // 8
+    if byte >= len(buf):
+        return
+    if value:
+        buf[byte] |= 1 << (i % 8)
+    else:
+        buf[byte] &= ~(1 << (i % 8)) & 0xFF
+
+
+# ---------------------------------------------------------- Var blocks -----
+def parse_var_meta(data: bytes) -> Tuple[bytes, Dict[int, Dict[int, int]], List[Tuple[int, int, int, int]]]:
+    """VarMeta12: 24-byte header then 12-byte entries (uid, offset, type, unk)."""
+    magic, unk, count, unk2, unk3, data_size = struct.unpack_from("<IIIIII", data, 0)
+    table: Dict[int, Dict[int, int]] = {}
+    entries = []
+    pos = 24
+    for _ in range(count):
+        if len(data) - pos < 12:
+            break
+        uid, off, typ, unk4 = struct.unpack_from("<IIHH", data, pos)
+        pos += 12
+        table.setdefault(uid, {})[typ] = off
+        entries.append((uid, off, typ, unk4))
+    return data[:24], table, entries
+
+
+def read_var(data: bytes, off: int) -> bytes:
+    size = struct.unpack_from("<I", data, off)[0]
+    return data[off + 4:off + 4 + size]
+
+
+TASK_FIELD_HI, RESOURCE_FIELD_HI, ASSIGNMENT_FIELD_HI = 0x0B40, 0x0C40, 0x0F40
+
+
+def build_var_blocks(header: bytes, values: List[Tuple[int, int, bytes]], field_hi: int = TASK_FIELD_HI) -> Tuple[bytes, bytes]:
+    """values: [(uid, type, payload)] -> (VarMeta, Var2Data).
+
+    Each entry is (uid, offset, fieldId low16, fieldId high16); the high word is the
+    native field-class prefix (0x0B40 tasks, 0x0C40 resources, 0x0F40 assignments).
+    Entries must be ordered by (uid, fieldId)."""
+    meta = bytearray(header)
+    var = bytearray()
+    entries = bytearray()
+    for uid, typ, payload in sorted(values, key=lambda v: (v[0], v[1])):
+        entries += struct.pack("<IIHH", uid, len(var), typ, field_hi)
+        var += struct.pack("<I", len(payload)) + payload
+    struct.pack_into("<I", meta, 8, len(values))
+    struct.pack_into("<I", meta, 20, len(var))
+    return bytes(meta) + bytes(entries), bytes(var)
+
+
+# ------------------------------------- OLE property sets (MS-OLEPS) --------
+VT_LPSTR = 30
+
+
+def update_property_set_strings(data: bytes, updates: Dict[int, str], section: int = 0,
+                                codepage: str = "cp1252") -> bytes:
+    """Replace or add VT_LPSTR properties in one section of an OLE property set
+    stream (SummaryInformation / DocumentSummaryInformation), keeping every
+    other property byte-for-byte."""
+    nsec = struct.unpack_from("<I", data, 24)[0]
+    header = data[:28]
+    secs = []
+    for s in range(nsec):
+        fmtid = data[28 + s * 20:44 + s * 20]
+        off = struct.unpack_from("<I", data, 44 + s * 20)[0]
+        size, cnt = struct.unpack_from("<II", data, off)
+        entries = [struct.unpack_from("<II", data, off + 8 + i * 8) for i in range(cnt)]
+        bounds = sorted(e[1] for e in entries) + [size]
+        raw, order = {}, []
+        for pid, poff in entries:
+            nxt = min(b for b in bounds if b > poff)
+            raw[pid] = data[off + poff:off + nxt]
+            order.append(pid)
+        secs.append([fmtid, order, raw])
+    fmtid, order, raw = secs[section]
+    for pid, val in updates.items():
+        b = val.encode(codepage, "replace") + b"\0"
+        v = struct.pack("<II", VT_LPSTR, len(b)) + b
+        raw[pid] = v + b"\0" * ((-len(v)) % 4)
+        if pid not in order:
+            order.append(pid)
+    out_secs = []
+    for fm, ord_, rw in secs:
+        base = 8 + len(ord_) * 8
+        body, entries = bytearray(), []
+        for pid in ord_:
+            v = rw[pid] + b"\0" * ((-len(rw[pid])) % 4)
+            entries.append((pid, base + len(body)))
+            body += v
+        sec = struct.pack("<II", base + len(body), len(ord_))
+        for pid, poff in entries:
+            sec += struct.pack("<II", pid, poff)
+        out_secs.append((fm, sec + bytes(body)))
+    dir_, pos = bytearray(), 28 + len(out_secs) * 20
+    for fm, sec in out_secs:
+        dir_ += fm + struct.pack("<I", pos)
+        pos += len(sec)
+    return bytes(header) + bytes(dir_) + b"".join(sec for _, sec in out_secs)
+
+
+# ------------------------------------------------------ calendar data ------
+CAL_DAY_NONWORKING, CAL_DAY_DEFAULT, CAL_DAY_WORKING = 0, 1, 2
+
+
+def build_calendar_data(days, exceptions=()) -> bytes:
+    """Calendar definition blob (var-data key 8 on a TBkndCal record), in the
+    dialect Microsoft Project M365 writes (an earlier form using day type 2
+    for working days is readable by MPXJ but ignored by Project).
+
+    days: 7 (day_type, ranges) tuples, SUNDAY first; ranges are
+    (start_minute, end_minute) pairs from midnight, at most 5 per day and only
+    meaningful for CAL_DAY_WORKING.
+    exceptions: (from_date, to_date, name) tuples of non-working days, sorted.
+
+    Each 60-byte day block: uint16 day type on the wire (1 = default,
+    0 = explicit; working vs non-working is the range count), uint16 range
+    count, uint32 total working tenths-of-a-minute at +4, range start times as
+    uint16 tenths at +8 (stride 2), range durations as uint32 tenths at +20
+    (stride 4) and duplicated at +40. Exceptions: uint32 count, then per
+    exception a 92-byte record (uint16 from-day, uint16 to-day, uint16 day
+    count, recurrence dwords 1, 0, 1, 0x4000 at +72, uint32 name byte length
+    at +88) followed by the UTF-16 name, zero-padded to a 4-byte boundary plus
+    4 more zero bytes (both as observed in Project-written files).
+    """
+    if len(days) != 7:
+        raise ValueError("days must have exactly 7 entries, Sunday first")
+    out = bytearray()
+    for dtype, ranges in days:
+        b = bytearray(60)
+        struct.pack_into("<H", b, 0, 1 if dtype == CAL_DAY_DEFAULT else 0)
+        if dtype == CAL_DAY_WORKING:
+            ranges = list(ranges)[:5]
+            struct.pack_into("<H", b, 2, len(ranges))
+            struct.pack_into("<I", b, 4, sum(end - start for start, end in ranges) * 10)
+            cumulative = 0
+            for i, (start, end) in enumerate(ranges):
+                struct.pack_into("<H", b, 8 + 2 * i, start * 10)
+                struct.pack_into("<I", b, 20 + 4 * i, (end - start) * 10)
+                cumulative += (end - start) * 10
+                struct.pack_into("<I", b, 40 + 4 * i, cumulative)
+        out += b
+    if exceptions:
+        out += struct.pack("<I", len(exceptions))
+        for i, (from_date, to_date, name) in enumerate(exceptions):
+            rec = bytearray(92)
+            d1 = (from_date - EPOCH.date()).days
+            d2 = (to_date - EPOCH.date()).days
+            struct.pack_into("<HH", rec, 0, d1, d2)
+            struct.pack_into("<H", rec, 4, d2 - d1 + 1)
+            struct.pack_into("<I", rec, 72, 1)
+            struct.pack_into("<I", rec, 80, 1)
+            struct.pack_into("<I", rec, 84, 0x4000)
+            nb = (name + "\0").encode("utf-16-le")
+            struct.pack_into("<I", rec, 88, len(nb))
+            # next record 4-byte aligned; 4 extra zero bytes close the blob
+            out += rec + nb + b"\0" * ((-len(nb)) % 4)
+            if i == len(exceptions) - 1:
+                out += b"\0\0\0\0"
+    return bytes(out)
+
+
+# ------------------------------------------------------- primitives --------
+def decode_timestamp(b: bytes, off: int) -> Optional[datetime]:
+    time, days = struct.unpack_from("<HH", b, off)
+    if days <= 1 or days == 65535:
+        return None
+    if time == 65535:
+        time = 0
+    return EPOCH + timedelta(days=days, seconds=time * 6)
+
+
+def encode_timestamp(dt: Optional[datetime]) -> bytes:
+    if dt is None:
+        return b"\xff\xff\xff\xff"
+    delta = dt - EPOCH
+    days = delta.days
+    tenths = delta.seconds // 6
+    return struct.pack("<HH", tenths, days)
+
+
+def encode_unicode(s: str) -> bytes:
+    return s.encode("utf-16-le") + b"\0\0"
+
+
+def decode_unicode(b: bytes) -> str:
+    return b.decode("utf-16-le", errors="replace").split("\0", 1)[0]
+
+
+# duration units (MS Project codes) -> tenths-of-a-minute divisor
+DURATION_UNITS = {3: ("m", 10), 5: ("h", 600), 7: ("d", 4800), 9: ("w", 24000), 11: ("mo", 96000)}

pymppwriter/cfb.py

@@ -0,0 +1,248 @@
+"""Minimal writer for Microsoft Compound File Binary (OLE2) containers.
+
+Implements enough of [MS-CFB] v3 (512-byte sectors, 64-byte mini sectors,
+4096-byte mini-stream cutoff) to produce files that Apache POI / olefile /
+MS Project can read. Written from the public [MS-CFB] specification.
+"""
+from __future__ import annotations
+import struct
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Union
+
+FREESECT = 0xFFFFFFFF
+ENDOFCHAIN = 0xFFFFFFFE
+FATSECT = 0xFFFFFFFD
+DIFSECT = 0xFFFFFFFC
+NOSTREAM = 0xFFFFFFFF
+
+SECTOR = 512
+MINI_SECTOR = 64
+MINI_CUTOFF = 4096
+FAT_PER_SECTOR = SECTOR // 4
+
+TYPE_STORAGE, TYPE_STREAM, TYPE_ROOT = 1, 2, 5
+
+
+@dataclass
+class Storage:
+    children: Dict[str, Union["Storage", bytes]] = field(default_factory=dict)
+
+    def add_stream(self, name: str, data: bytes) -> None:
+        self.children[name] = bytes(data)
+
+    def add_storage(self, name: str) -> "Storage":
+        s = self.children.get(name)
+        if not isinstance(s, Storage):
+            s = Storage()
+            self.children[name] = s
+        return s
+
+    def set_path(self, path: str, data: bytes) -> None:
+        parts = path.split("/")
+        s = self
+        for p in parts[:-1]:
+            s = s.add_storage(p)
+        s.add_stream(parts[-1], data)
+
+    def storage_path(self, path: str) -> "Storage":
+        s = self
+        for p in path.split("/"):
+            s = s.add_storage(p)
+        return s
+
+
+class _Entry:
+    __slots__ = ("name", "etype", "data", "child", "left", "right", "start", "size", "index", "clsid")
+
+    def __init__(self, name: str, etype: int, data: Optional[bytes] = None):
+        self.name = name
+        self.etype = etype
+        self.data = data
+        self.child = NOSTREAM
+        self.left = NOSTREAM
+        self.right = NOSTREAM
+        self.start = ENDOFCHAIN
+        self.size = 0
+        self.index = -1
+        self.clsid = b"\0" * 16
+
+
+def _name_key(name: str):
+    # [MS-CFB] 2.6.4: compare by UTF-16 length first, then upper-cased code units.
+    u = name.encode("utf-16-le")
+    return (len(u), name.upper().encode("utf-16-le"))
+
+
+def _build_tree(entries: List[_Entry]) -> int:
+    """Return index of root of a balanced binary tree over sorted entries."""
+    if not entries:
+        return NOSTREAM
+    mid = len(entries) // 2
+    node = entries[mid]
+    node.left = _build_tree(entries[:mid])
+    node.right = _build_tree(entries[mid + 1:])
+    return node.index
+
+
+def _pad(data: bytes, unit: int) -> bytes:
+    rem = len(data) % unit
+    return data if rem == 0 else data + b"\0" * (unit - rem)
+
+
+def write_cfb(root: Storage, root_clsid: bytes = b"\0" * 16) -> bytes:
+    # ---- flatten directory -------------------------------------------------
+    entries: List[_Entry] = []
+    root_entry = _Entry("Root Entry", TYPE_ROOT)
+    root_entry.clsid = root_clsid
+    entries.append(root_entry)
+
+    def flatten(storage: Storage, parent: _Entry) -> None:
+        kids: List[_Entry] = []
+        for name, val in storage.children.items():
+            if isinstance(val, Storage):
+                e = _Entry(name, TYPE_STORAGE)
+            else:
+                e = _Entry(name, TYPE_STREAM, val)
+            entries.append(e)
+            kids.append(e)
+        for e in kids:
+            e.index = entries.index(e)
+        kids.sort(key=lambda e: _name_key(e.name))
+        parent.child = _build_tree(kids)
+        for e in kids:
+            if e.etype == TYPE_STORAGE:
+                flatten(storage.children[e.name], e)
+
+    root_entry.index = 0
+    flatten(root, root_entry)
+    for i, e in enumerate(entries):
+        e.index = i
+
+    # ---- mini stream -------------------------------------------------------
+    mini_stream = bytearray()
+    minifat: List[int] = []
+    for e in entries:
+        if e.etype == TYPE_STREAM and 0 < len(e.data) < MINI_CUTOFF:
+            e.size = len(e.data)
+            e.start = len(minifat)
+            padded = _pad(e.data, MINI_SECTOR)
+            n = len(padded) // MINI_SECTOR
+            mini_stream += padded
+            minifat.extend(range(len(minifat) + 1, len(minifat) + n))
+            minifat.append(ENDOFCHAIN)
+    root_entry.size = len(mini_stream)
+
+    # ---- regular sectors ---------------------------------------------------
+    sectors: List[bytes] = []          # sector payloads (512 bytes each)
+    fat: List[int] = []                # FAT entry per sector
+
+    def add_chain(data: bytes) -> int:
+        padded = _pad(data, SECTOR)
+        n = len(padded) // SECTOR
+        if n == 0:
+            return ENDOFCHAIN
+        first = len(sectors)
+        for i in range(n):
+            sectors.append(padded[i * SECTOR:(i + 1) * SECTOR])
+            fat.append(first + i + 1 if i < n - 1 else ENDOFCHAIN)
+        return first
+
+    # large streams
+    for e in entries:
+        if e.etype == TYPE_STREAM and len(e.data) >= MINI_CUTOFF:
+            e.size = len(e.data)
+            e.start = add_chain(e.data)
+
+    # mini stream itself lives in regular sectors, pointed to by root entry
+    root_entry.start = add_chain(bytes(mini_stream)) if mini_stream else ENDOFCHAIN
+
+    # minifat
+    minifat_start, minifat_count = ENDOFCHAIN, 0
+    if minifat:
+        raw = b"".join(struct.pack("<I", v) for v in minifat)
+        raw = _pad(raw, SECTOR)
+        # pad unused minifat slots with FREESECT
+        raw = raw[: len(minifat) * 4] + b"\xff" * (len(raw) - len(minifat) * 4)
+        minifat_start = add_chain(raw)
+        minifat_count = len(raw) // SECTOR
+
+    # directory
+    dir_raw = bytearray()
+    for e in entries:
+        dir_raw += _dir_entry(e)
+    dir_raw = _pad(bytes(dir_raw), SECTOR)
+    # fill trailing unused entries with valid empty entries
+    n_slots = len(dir_raw) // 128
+    for i in range(len(entries), n_slots):
+        dir_raw = dir_raw[: i * 128] + _dir_entry(None) + dir_raw[(i + 1) * 128:]
+    dir_start = add_chain(bytes(dir_raw))
+
+    # FAT sectors (iterate: FAT sectors — and any DIFAT sectors listing them
+    # beyond the header's 109 slots — need FAT entries too)
+    DIFAT_PER_SECTOR = FAT_PER_SECTOR - 1      # last dword chains to the next DIFAT sector
+    n_data = len(sectors)
+    n_fat = n_difat = 0
+    while True:
+        needed_fat = -(-(n_data + n_fat + n_difat) // FAT_PER_SECTOR)
+        needed_difat = -(-max(0, needed_fat - 109) // DIFAT_PER_SECTOR)
+        if (needed_fat, needed_difat) == (n_fat, n_difat):
+            break
+        n_fat, n_difat = needed_fat, needed_difat
+
+    fat_full = fat + [FATSECT] * n_fat + [DIFSECT] * n_difat
+    fat_full += [FREESECT] * (n_fat * FAT_PER_SECTOR - len(fat_full))
+    fat_raw = b"".join(struct.pack("<I", v) for v in fat_full)
+    fat_sector_ids = list(range(n_data, n_data + n_fat))
+    difat_sector_ids = list(range(n_data + n_fat, n_data + n_fat + n_difat))
+    for i in range(n_fat):
+        sectors.append(fat_raw[i * SECTOR:(i + 1) * SECTOR])
+    for i in range(n_difat):
+        chunk = fat_sector_ids[109 + i * DIFAT_PER_SECTOR: 109 + (i + 1) * DIFAT_PER_SECTOR]
+        chunk += [FREESECT] * (DIFAT_PER_SECTOR - len(chunk))
+        nxt = difat_sector_ids[i + 1] if i + 1 < n_difat else ENDOFCHAIN
+        sectors.append(b"".join(struct.pack("<I", v) for v in chunk) + struct.pack("<I", nxt))
+
+    # ---- header ------------------------------------------------------------
+    hdr = bytearray(SECTOR)
+    struct.pack_into("<8s16sHHHHH6sIIIIIIIII", hdr, 0,
+                     b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1", b"\0" * 16,
+                     0x003E, 0x0003, 0xFFFE, 9, 6, b"\0" * 6,
+                     0,               # number of directory sectors (v3: 0)
+                     n_fat,
+                     dir_start,
+                     0,               # transaction signature
+                     MINI_CUTOFF,
+                     minifat_start, minifat_count,
+                     difat_sector_ids[0] if n_difat else ENDOFCHAIN, n_difat)
+    difat = fat_sector_ids[:109] + [FREESECT] * max(0, 109 - len(fat_sector_ids))
+    struct.pack_into("<109I", hdr, 76, *difat)
+
+    return bytes(hdr) + b"".join(sectors)
+
+
+def _dir_entry(e: Optional[_Entry]) -> bytes:
+    if e is None:
+        return struct.pack("<64sHBBIII16sIQQIQ", b"\0" * 64, 0, 0, 0,
+                           NOSTREAM, NOSTREAM, NOSTREAM, b"\0" * 16, 0, 0, 0, 0, 0)
+    name = e.name.encode("utf-16-le") + b"\0\0"
+    if len(name) > 64:
+        raise ValueError(f"name too long: {e.name!r}")
+    return struct.pack("<64sHBBIII16sIQQIQ",
+                       name.ljust(64, b"\0"), len(name), e.etype, 1,  # colour: black
+                       e.left, e.right, e.child, e.clsid, 0, 0, 0,
+                       e.start if e.start != ENDOFCHAIN else (0 if e.etype != TYPE_STREAM else ENDOFCHAIN),
+                       e.size)
+
+
+def load_cfb(path: str) -> Storage:
+    """Read an existing compound file into a Storage tree (via olefile)."""
+    import olefile
+    ole = olefile.OleFileIO(path)
+    root = Storage()
+    for parts in ole.listdir(streams=True, storages=True):
+        p = "/".join(parts)
+        if ole.get_type(p) == olefile.STGTY_STORAGE:
+            root.storage_path(p)
+        else:
+            root.set_path(p, ole.openstream(p).read())
+    return root