Update app.py

app.py

@@ -1,831 +1,136 @@
-# ============================================================
-# FLC v1.3 — Standalone Fibonacci Lattice Compression
-#   + Real .flc file format (v2 header)
-#   + Hologram preview PNG
-#   + "Holographic Unzip" progressive GIF (REAL partial reconstructions)
-#   + max_bands horizon control
-#   + Fibonacci spiral unfold layout (right panel)
-#   + NEW: Event-horizon ring overlay (left panel)
-#   + NEW: Fibonacci tile outlines (right panel)
-#
-# Notebook usage:
-#   enc = flc_encode_file("in.bin","out.flc","preview.png", unzip_gif="unzip.gif",
-#                         block_len=1024, n_bands=10, base_step=0.004)
-#   dec = flc_decode_file("out.flc","recovered.bin", unzip_gif="decode_unzip.gif", max_bands=None)
-#
-# Partial/horizon:
-#   decp = flc_decode_file("out.flc","partial.bin", unzip_gif="partial_unzip.gif", max_bands=4)
-#
-# Depends: numpy, pillow
-# ============================================================
-
-import os, struct, math, argparse
+import streamlit as st
+import os
+import tempfile
 import numpy as np
-from PIL import Image, ImageDraw
-
-PHI = (1.0 + 5.0**0.5) / 2.0
-MAGIC = b"FLC1\x00\x00\x00\x00"  # 8 bytes
-VER_V2 = 2  # float64 params
-
-# --------------------------
-# Fibonacci utilities
-# --------------------------
-def fibonacci_sequence(n):
-    fibs = [1, 2]
-    while len(fibs) < n:
-        fibs.append(fibs[-1] + fibs[-2])
-    return np.array(fibs[:n], dtype=np.int64)
-
-def fibonacci_sequence_std(n):
-    fibs = [1, 1]
-    while len(fibs) < n:
-        fibs.append(fibs[-1] + fibs[-2])
-    return np.array(fibs[:n], dtype=np.int64)
-
-def fibonacci_frequency_boundaries(n_coeffs: int, n_bands: int):
-    """
-    Strict: returns exactly n_bands+1 boundaries => exactly n_bands intervals.
-    Deterministic repair enforces strict monotone boundaries.
-    """
-    if n_bands < 2:
-        return [0, n_coeffs]
-
-    fibs = fibonacci_sequence(n_bands).astype(np.float64)
-    w = fibs / (fibs.sum() + 1e-12)
-    cum = np.cumsum(w)
-
-    b = [0]
-    for i in range(n_bands - 1):
-        bi = int(round(n_coeffs * cum[i]))
-        b.append(bi)
-    b.append(n_coeffs)
-
-    b = [max(0, min(n_coeffs, int(x))) for x in b]
-    b[0] = 0
-    b[-1] = n_coeffs
-
-    # strictify forward
-    for i in range(1, len(b) - 1):
-        if b[i] <= b[i-1]:
-            b[i] = b[i-1] + 1
-    # strictify backward
-    for i in range(len(b) - 2, 0, -1):
-        if b[i] >= b[i+1]:
-            b[i] = b[i+1] - 1
-
-    # remove invalid interior points
-    b = [0] + [x for x in b[1:-1] if 0 < x < n_coeffs] + [n_coeffs]
-
-    # repack if we lost points (n_coeffs small or rounding)
-    while len(b) < n_bands + 1:
-        gaps = [(b[i+1] - b[i], i) for i in range(len(b) - 1)]
-        gaps.sort(reverse=True)
-        _, gi = gaps[0]
-        mid = (b[gi] + b[gi+1]) // 2
-        if mid == b[gi] or mid == b[gi+1]:
-            break
-        b.insert(gi+1, mid)
-
-    # trim if we have too many
-    while len(b) > n_bands + 1:
-        gaps = [(b[i+1] - b[i], i) for i in range(len(b) - 1)]
-        gaps.sort()  # smallest first
-        _, gi = gaps[0]
-        if 0 < gi+1 < len(b)-1:
-            b.pop(gi+1)
-        else:
-            break
-
-    return b
-
-# --------------------------
-# Orthonormal DCT-II / IDCT (no scipy)
-# --------------------------
-def dct_ortho_1d(x: np.ndarray) -> np.ndarray:
-    x = np.asarray(x, dtype=np.float64)
-    N = x.shape[0]
-    v = np.concatenate([x, x[::-1]])
-    V = np.fft.fft(v)
-    k = np.arange(N)
-    X = np.real(V[:N] * np.exp(-1j * np.pi * k / (2 * N)))
-    X *= 2.0
-    X[0] *= (1.0 / math.sqrt(4 * N))
-    X[1:] *= (1.0 / math.sqrt(2 * N))
-    return X
-
-def idct_ortho_1d(X: np.ndarray) -> np.ndarray:
-    X = np.asarray(X, dtype=np.float64)
-    N = X.shape[0]
-    x = X.copy()
-
-    x0 = x[0] * math.sqrt(4 * N)
-    xr = x[1:] * math.sqrt(2 * N)
-    c = np.empty(N, dtype=np.complex128)
-    c[0] = x0 / 2.0
-    c[1:] = xr / 2.0
-
-    k = np.arange(N)
-    c = c * np.exp(1j * np.pi * k / (2 * N))
-
-    V = np.zeros(2 * N, dtype=np.complex128)
-    V[:N] = c
-    V[N+1:] = np.conj(c[1:][::-1])
-    v = np.fft.ifft(V).real
-    return v[:N]
-
-def dct_blocks_ortho(x_blocks: np.ndarray) -> np.ndarray:
-    B, L = x_blocks.shape
-    out = np.empty((B, L), dtype=np.float64)
-    for i in range(B):
-        out[i] = dct_ortho_1d(x_blocks[i])
-    return out
-
-def idct_blocks_ortho(X_blocks: np.ndarray) -> np.ndarray:
-    B, L = X_blocks.shape
-    out = np.empty((B, L), dtype=np.float64)
-    for i in range(B):
-        out[i] = idct_ortho_1d(X_blocks[i])
-    return out
-
-# --------------------------
-# Bit IO
-# --------------------------
-class BitWriter:
-    def __init__(self):
-        self.buf = bytearray()
-        self.acc = 0
-        self.nbits = 0
-
-    def write_bit(self, b: int):
-        self.acc = (self.acc << 1) | (b & 1)
-        self.nbits += 1
-        if self.nbits == 8:
-            self.buf.append(self.acc & 0xFF)
-            self.acc = 0
-            self.nbits = 0
-
-    def finish(self) -> bytes:
-        if self.nbits:
-            self.acc <<= (8 - self.nbits)
-            self.buf.append(self.acc & 0xFF)
-            self.acc = 0
-            self.nbits = 0
-        return bytes(self.buf)
-
-class BitReader:
-    def __init__(self, data: bytes):
-        self.data = data
-        self.i = 0
-        self.acc = 0
-        self.nbits = 0
-
-    def read_bit(self) -> int:
-        if self.nbits == 0:
-            if self.i >= len(self.data):
-                raise EOFError("BitReader EOF")
-            self.acc = self.data[self.i]
-            self.i += 1
-            self.nbits = 8
-        b = (self.acc >> (self.nbits - 1)) & 1
-        self.nbits -= 1
-        return b
-
-# --------------------------
-# Fibonacci coding
-# --------------------------
-def _fib_numbers_upto(n: int):
-    fibs = [1, 2]
-    while fibs[-1] <= n:
-        fibs.append(fibs[-1] + fibs[-2])
-    return fibs
-
-def fib_encode_nonneg(bw: BitWriter, n: int):
-    m = int(n) + 1
-    fibs = _fib_numbers_upto(m)
-    bits = [0] * (len(fibs) - 1)
-    rem = m
-    for i in reversed(range(len(bits))):
-        f = fibs[i]
-        if f <= rem:
-            bits[i] = 1
-            rem -= f
-    hi = max((i for i, b in enumerate(bits) if b), default=0)
-    for i in range(hi + 1):
-        bw.write_bit(bits[i])
-    bw.write_bit(1)
-
-def fib_decode_nonneg(br: BitReader) -> int:
-    fibs = [1, 2]
-    bits = []
-    prev = 0
-    while True:
-        b = br.read_bit()
-        bits.append(b)
-        if prev == 1 and b == 1:
-            break
-        prev = b
-        if len(bits) > len(fibs):
-            fibs.append(fibs[-1] + fibs[-2])
-    payload = bits[:-1]
-    while len(fibs) < len(payload):
-        fibs.append(fibs[-1] + fibs[-2])
-    m = 0
-    for i, bi in enumerate(payload):
-        if bi:
-            m += fibs[i]
-    return m - 1
-
-def zigzag_encode_i64(x: int) -> int:
-    x = int(x)
-    return (x << 1) ^ (x >> 63)
-
-def zigzag_decode_i64(u: int) -> int:
-    u = int(u)
-    return (u >> 1) ^ (-(u & 1))
-
-def rle_fib_encode_ints(ints: np.ndarray) -> bytes:
-    bw = BitWriter()
-    ints = ints.astype(np.int64, copy=False)
-    zrun = 0
-    for v in ints:
-        if v == 0:
-            zrun += 1
-            continue
-        if zrun:
-            bw.write_bit(0)
-            fib_encode_nonneg(bw, zrun)
-            zrun = 0
-        bw.write_bit(1)
-        fib_encode_nonneg(bw, zigzag_encode_i64(int(v)))
-    if zrun:
-        bw.write_bit(0)
-        fib_encode_nonneg(bw, zrun)
-    return bw.finish()
-
-def rle_fib_decode_ints(payload: bytes, n_out: int) -> np.ndarray:
-    br = BitReader(payload)
-    out = np.zeros(n_out, dtype=np.int64)
-    i = 0
-    while i < n_out:
-        tag = br.read_bit()
-        if tag == 0:
-            k = fib_decode_nonneg(br)
-            i = min(n_out, i + k)
-        else:
-            u = fib_decode_nonneg(br)
-            out[i] = zigzag_decode_i64(u)
-            i += 1
-    return out
-
-def delta1d(x: np.ndarray) -> np.ndarray:
-    x = x.astype(np.int64, copy=False)
-    out = np.empty_like(x, dtype=np.int64)
-    prev = 0
-    for i, v in enumerate(x):
-        out[i] = int(v) - prev
-        prev = int(v)
-    return out
-
-def inv_delta1d(d: np.ndarray) -> np.ndarray:
-    d = d.astype(np.int64, copy=False)
-    out = np.empty_like(d, dtype=np.int64)
-    acc = 0
-    for i, v in enumerate(d):
-        acc += int(v)
-        out[i] = acc
-    return out
-
-# --------------------------
-# φ-scaled band quantization
-# --------------------------
-def band_quantize_dct(coeffs: np.ndarray, boundaries, base_step: float, phi: float = PHI):
-    B, L = coeffs.shape
-    q = np.zeros((B, L), dtype=np.int32)
-    for bi in range(len(boundaries) - 1):
-        a, b = boundaries[bi], boundaries[bi + 1]
-        if a >= b:
-            continue
-        step = base_step * (phi ** bi)
-        q[:, a:b] = np.round(coeffs[:, a:b] / step).astype(np.int32)
-    return q
-
-def band_dequantize_dct(q: np.ndarray, boundaries, base_step: float, phi: float = PHI):
-    B, L = q.shape
-    coeffs = np.zeros((B, L), dtype=np.float64)
-    for bi in range(len(boundaries) - 1):
-        a, b = boundaries[bi], boundaries[bi + 1]
-        if a >= b:
-            continue
-        step = base_step * (phi ** bi)
-        coeffs[:, a:b] = q[:, a:b].astype(np.float64) * step
-    return coeffs
-
-# --------------------------
-# Hologram (left panel) + horizon ring overlay
-# --------------------------
-def choose_fib_grid(n_symbols: int) -> int:
-    N = int(math.ceil(math.sqrt(n_symbols)))
-    fibs = [1, 2]
-    while fibs[-1] < N:
-        fibs.append(fibs[-1] + fibs[-2])
-    return fibs[-1]
-
-def ints_to_constellation(zints: np.ndarray):
-    zints = zints.astype(np.int64)
-    v = np.tanh(zints / 32.0).astype(np.float64)
-    k = np.arange(v.size, dtype=np.float64)
-    golden = 2 * math.pi / (PHI**2)
-    theta = golden * k + 2.0 * math.pi * (v * 0.25)
-    r = 1.0 + 0.35 * np.abs(v)
-    return (r * np.cos(theta) + 1j * r * np.sin(theta)).astype(np.complex64)
-
-def hologram_spectrum_image(zints: np.ndarray, max_symbols: int = 262144):
-    if zints.size > max_symbols:
-        zints = zints[:max_symbols]
-    syms = ints_to_constellation(zints)
-    N = choose_fib_grid(syms.size)
-    total = N * N
-    if syms.size < total:
-        syms = np.pad(syms, (0, total - syms.size), constant_values=(1+0j)).astype(np.complex64)
-    U = syms.reshape(N, N)
-    F = np.fft.fftshift(np.fft.fft2(U))
-    mag = np.log1p(np.abs(F)).astype(np.float32)
-    mag -= mag.min()
-    mag /= (mag.max() + 1e-12)
-    return (mag * 255).astype(np.uint8)
-
-def make_hologram_preview(zints: np.ndarray, out_png: str, max_symbols: int = 262144):
-    img = hologram_spectrum_image(zints, max_symbols=max_symbols)
-    Image.fromarray(img).save(out_png)
-
-def overlay_event_horizon_ring(imL: Image.Image, t: int, T: int):
-    """
-    Draw a glowing event-horizon ring (as 3 concentric ellipses) on the hologram.
-    Radius expands with progress t/T.
-    """
-    W, H = imL.size
-    cx, cy = W // 2, H // 2
-    # start small, expand
-    r0 = int(0.08 * min(W, H))
-    r1 = int((0.45 * min(W, H)) * (t / max(1, T)) + r0)
-
-    rgb = imL.convert("RGB")
-    d = ImageDraw.Draw(rgb)
-
-    # glow: 3 rings
-    for k, alpha in [(0, 255), (3, 170), (6, 90)]:
-        rr = r1 + k
-        bbox = (cx - rr, cy - rr, cx + rr, cy + rr)
-        # gold-ish ring
-        col = (255, 215, 0) if alpha == 255 else (220, 180, 0)
-        d.ellipse(bbox, outline=col, width=2)
-
-    # center dot (singularity hint)
-    d.ellipse((cx-2, cy-2, cx+2, cy+2), fill=(255, 215, 0))
-    return rgb
-
-# --------------------------
-# Fibonacci spiral unfold (right panel) + tile outlines
-# --------------------------
-def fibonacci_spiral_tiles_for_area(n_pixels: int, max_tiles: int = 30):
-    fibs = fibonacci_sequence_std(max_tiles)  # 1,1,2,3,5...
-    sizes = []
-    area = 0
-    for s in fibs:
-        sizes.append(int(s))
-        area += int(s) * int(s)
-        if area >= n_pixels:
-            break
-    return sizes
-
-def fibonacci_spiral_tile_positions(sizes):
-    tiles = []
-    s0 = sizes[0]
-    minx, miny, maxx, maxy = 0, 0, s0, s0
-    tiles.append((0, 0, s0))
-
-    for i in range(1, len(sizes)):
-        s = sizes[i]
-        d = (i - 1) % 4  # right, up, left, down
-        if d == 0:      # right
-            x, y = maxx, miny
-        elif d == 1:    # up
-            x, y = maxx - s, maxy
-        elif d == 2:    # left
-            x, y = minx - s, maxy - s
-        else:           # down
-            x, y = minx, miny - s
-
-        tiles.append((x, y, s))
-        minx = min(minx, x)
-        miny = min(miny, y)
-        maxx = max(maxx, x + s)
-        maxy = max(maxy, y + s)
-
-    bbox = (minx, miny, maxx, maxy)
-    return tiles, bbox
-
-def bytes_to_fib_spiral_image(data: bytes, max_pixels: int = 262144, want_tiles=False):
-    arr = np.frombuffer(data, dtype=np.uint8)
-    if arr.size > max_pixels:
-        arr = arr[:max_pixels]
-    n = int(arr.size)
-    if n == 0:
-        if want_tiles:
-            return np.zeros((1, 1), dtype=np.uint8), [(0,0,1)], (0,0,1,1)
-        return np.zeros((1, 1), dtype=np.uint8)
-
-    sizes = fibonacci_spiral_tiles_for_area(n_pixels=n, max_tiles=32)
-    tiles, (minx, miny, maxx, maxy) = fibonacci_spiral_tile_positions(sizes)
-
-    W = int(maxx - minx)
-    H = int(maxy - miny)
-    img = np.zeros((H, W), dtype=np.uint8)
-    idx = 0
-
-    for (x, y, s) in tiles:
-        if idx >= n:
-            break
-        x0 = int(x - minx)
-        y0_up = int(y - miny)
-        y0 = int((H - (y0_up + s)))
-
-        take = min(s * s, n - idx)
-        block = arr[idx:idx + take]
-        if take < s * s:
-            block = np.pad(block, (0, s * s - take), constant_values=0)
-        block2d = block.reshape(s, s)
-        img[y0:y0+s, x0:x0+s] = block2d
-        idx += take
-
-    if want_tiles:
-        return img, tiles, (minx, miny, maxx, maxy)
-    return img
-
-def overlay_tile_outlines(imL: Image.Image, tiles, bbox_info, outline=(120,120,120)):
-    """
-    Draw square outlines for the Fibonacci tiling on the right panel.
-    `tiles` are in y-up coords with original bbox min offsets.
-    """
-    rgb = imL.convert("RGB")
-    d = ImageDraw.Draw(rgb)
-    # rebuild H,W from image
-    W, H = rgb.size
-
-    # bbox is y-up coords: minx,miny,maxx,maxy
-    minx, miny, maxx, maxy = bbox_info
-    # For each tile, map y-up to y-down in image coords
-    for (x, y, s) in tiles:
-        x0 = int(x - minx)
-        y0_up = int(y - miny)
-        y0 = int((H - (y0_up + s)))
-        d.rectangle((x0, y0, x0 + s - 1, y0 + s - 1), outline=outline, width=1)
-    return rgb
-
-# --------------------------
-# GIF assembly
-# --------------------------
-def save_gif(frames, out_gif: str, duration=90):
-    if not frames:
-        return
-    frames[0].save(out_gif, save_all=True, append_images=frames[1:], duration=duration, loop=0, optimize=True)
-
-def make_unzip_gif_from_Q(Q_full: np.ndarray,
-                          boundaries,
-                          base_step: float,
-                          mu: float,
-                          n_bytes: int,
-                          out_gif: str,
-                          max_bands: int = None,
-                          gif_scale: int = 2,
-                          max_symbols: int = 262144,
-                          max_pixels: int = 262144,
-                          draw_outlines: bool = True,
-                          draw_horizon: bool = True):
-    n_total_bands = len(boundaries) - 1
-    T = n_total_bands if max_bands is None else max(0, min(int(max_bands), n_total_bands))
-    if T == 0:
-        T = 1
-
-    frames = []
-    band_slices = [(boundaries[i], boundaries[i+1]) for i in range(n_total_bands)]
-
-    for t in range(1, T + 1):
-        Q_part = np.zeros_like(Q_full)
-        for bi in range(t):
-            a, b = band_slices[bi]
-            if a < b:
-                Q_part[:, a:b] = Q_full[:, a:b]
-
-        # partial recon bytes
-        C_part = band_dequantize_dct(Q_part, boundaries, base_step=base_step, phi=PHI)
-        X_part = idct_blocks_ortho(C_part)
-        x = X_part.reshape(-1)[:n_bytes]
-        x = (x * 127.5) + float(mu)
-        x = np.clip(np.round(x), 0, 255).astype(np.uint8).tobytes()
-
-        # left hologram
-        qflat = Q_part.reshape(-1).astype(np.int64)
-        holo_u8 = hologram_spectrum_image(qflat, max_symbols=max_symbols)
-        A = Image.fromarray(holo_u8).convert("L")
-        if gif_scale != 1:
-            A = A.resize((A.size[0]*gif_scale, A.size[1]*gif_scale), Image.NEAREST)
-
-        # horizon ring overlay
-        if draw_horizon:
-            A_rgb = overlay_event_horizon_ring(A, t=t, T=T)
-        else:
-            A_rgb = A.convert("RGB")
-
-        # right spiral image
-        field_u8, tiles, bbox_info = bytes_to_fib_spiral_image(x, max_pixels=max_pixels, want_tiles=True)
-        Bimg = Image.fromarray(field_u8).convert("L")
-        if gif_scale != 1:
-            Bimg = Bimg.resize((Bimg.size[0]*gif_scale, Bimg.size[1]*gif_scale), Image.NEAREST)
-
-        if draw_outlines:
-            # scale tile coordinates too (by rendering outlines after scaling)
-            # easiest: draw outlines on scaled image using scaled bbox & tiles
-            # so adjust bbox and tiles by gif_scale
-            minx, miny, maxx, maxy = bbox_info
-            tiles_s = [(x*gif_scale, y*gif_scale, s*gif_scale) for (x,y,s) in tiles]
-            bbox_s = (minx*gif_scale, miny*gif_scale, maxx*gif_scale, maxy*gif_scale)
-            B_rgb = overlay_tile_outlines(Bimg, tiles_s, bbox_s, outline=(120,120,120))
-        else:
-            B_rgb = Bimg.convert("RGB")
-
-        # match heights by padding
-        H = max(A_rgb.size[1], B_rgb.size[1])
-        def pad_to_h_rgb(im, H):
-            if im.size[1] == H:
-                return im
-            canvas = Image.new("RGB", (im.size[0], H), (0,0,0))
-            canvas.paste(im, (0, (H - im.size[1])//2))
-            return canvas
-        A_rgb = pad_to_h_rgb(A_rgb, H)
-        B_rgb = pad_to_h_rgb(B_rgb, H)
-
-        W = A_rgb.size[0]
-        canvas = Image.new("RGB", (W*2, H + 44), (0, 0, 0))
-        canvas.paste(A_rgb, (0, 44))
-        canvas.paste(B_rgb, (W, 44))
-
-        draw = ImageDraw.Draw(canvas)
-        draw.text((12, 10), f"FLC HOLOGRAPHIC UNZIP  |  bands {t}/{T}  (horizon={T})", fill=(255, 215, 0))
-        draw.text((12, 26), "LEFT: hologram + event horizon  |  RIGHT: Fibonacci spiral + tile outlines", fill=(180, 180, 180))
-        frames.append(canvas)
-
-    save_gif(frames, out_gif, duration=90)
-
-# ============================================================
-# Encoder / Decoder
-# ============================================================
-def flc_encode_file(in_path: str,
-                    out_flc: str,
-                    preview_png: str = None,
-                    unzip_gif: str = None,
-                    block_len: int = 1024,
-                    n_bands: int = 10,
-                    base_step: float = 0.004,
-                    use_mean_center: bool = True,
-                    gif_scale: int = 2,
-                    gif_horizon: int = None,
-                    draw_horizon: bool = True,
-                    draw_outlines: bool = True):
-    raw = open(in_path, "rb").read()
-    n_bytes = len(raw)
-
-    x = np.frombuffer(raw, dtype=np.uint8).astype(np.float64)
-    mu = float(np.mean(x)) if use_mean_center else 127.5
-    x = (x - mu) / 127.5
-
-    pad = (-x.size) % block_len
-    if pad:
-        x = np.pad(x, (0, pad), constant_values=0.0)
-    n_blocks = x.size // block_len
-    X = x.reshape(n_blocks, block_len)
-
-    C = dct_blocks_ortho(X)
-    boundaries = fibonacci_frequency_boundaries(block_len, n_bands)
-    Q = band_quantize_dct(C, boundaries, base_step=base_step, phi=PHI)
-
-    q_flat = Q.reshape(-1).astype(np.int64)
-    d = delta1d(q_flat)
-    payload = rle_fib_encode_ints(d)
-
-    header = struct.pack(
-        "<8sH Q I I H d d H",
-        MAGIC, VER_V2,
-        int(n_bytes),
-        int(block_len),
-        int(n_blocks),
-        int(n_bands),
-        float(base_step),
-        float(mu),
-        int(len(boundaries)),
-    )
-    bnds = struct.pack("<" + "I"*len(boundaries), *[int(b) for b in boundaries])
-    paylen = struct.pack("<I", int(len(payload)))
-
-    with open(out_flc, "wb") as f:
-        f.write(header)
-        f.write(bnds)
-        f.write(paylen)
-        f.write(payload)
-
-    if preview_png is not None:
-        make_hologram_preview(q_flat, preview_png)
-
-    if unzip_gif is not None:
-        make_unzip_gif_from_Q(
-            Q_full=Q,
-            boundaries=boundaries,
-            base_step=float(base_step),
-            mu=float(mu),
-            n_bytes=int(n_bytes),
-            out_gif=unzip_gif,
-            max_bands=gif_horizon,
-            gif_scale=gif_scale,
-            draw_horizon=draw_horizon,
-            draw_outlines=draw_outlines,
-        )
-
-    return {
-        "n_bytes": int(n_bytes),
-        "block_len": int(block_len),
-        "n_blocks": int(n_blocks),
-        "n_bands": int(n_bands),
-        "base_step": float(base_step),
-        "mu": float(mu),
-        "payload_len": int(len(payload)),
-        "out_flc": out_flc,
-        "preview_png": preview_png,
-        "unzip_gif": unzip_gif,
-        "ratio": (os.path.getsize(out_flc) / max(1, n_bytes)),
-    }
-
-def flc_decode_file(in_flc: str,
-                    out_path: str,
-                    unzip_gif: str = None,
-                    max_bands: int = None,
-                    gif_scale: int = 2,
-                    draw_horizon: bool = True,
-                    draw_outlines: bool = True):
-    blob = open(in_flc, "rb").read()
-    off = 0
-
-    (magic, ver, n_bytes, block_len, n_blocks, n_bands, base_step, mu, bnd_len) = struct.unpack_from(
-        "<8sH Q I I H d d H", blob, off
-    )
-    off += struct.calcsize("<8sH Q I I H d d H")
-    if magic != MAGIC:
-        raise ValueError("Bad magic (not FLC1)")
-    if ver != VER_V2:
-        raise ValueError(f"Unsupported version {ver}")
-
-    boundaries = list(struct.unpack_from("<" + "I"*bnd_len, blob, off))
-    off += 4 * bnd_len
-
-    (payload_len,) = struct.unpack_from("<I", blob, off)
-    off += 4
-    payload = blob[off:off+payload_len]
-    off += payload_len
-
-    n_coeffs = int(n_blocks) * int(block_len)
-    d = rle_fib_decode_ints(payload, n_coeffs)
-    q_flat = inv_delta1d(d).astype(np.int64)
-    Q_full = q_flat.reshape(int(n_blocks), int(block_len)).astype(np.int32)
-
-    # horizon
-    n_total_bands = len(boundaries) - 1
-    bands_to_apply = n_total_bands if max_bands is None else max(0, min(int(max_bands), n_total_bands))
-
-    if bands_to_apply < n_total_bands:
-        Q_use = np.zeros_like(Q_full)
-        for bi in range(bands_to_apply):
-            a, b = boundaries[bi], boundaries[bi+1]
-            if a < b:
-                Q_use[:, a:b] = Q_full[:, a:b]
-    else:
-        Q_use = Q_full
-
-    C = band_dequantize_dct(Q_use, boundaries, base_step=float(base_step), phi=PHI)
-    X = idct_blocks_ortho(C)
-
-    x = X.reshape(-1)[:int(n_bytes)]
-    x = (x * 127.5) + float(mu)
-    x = np.clip(np.round(x), 0, 255).astype(np.uint8)
-
-    with open(out_path, "wb") as f:
-        f.write(x.tobytes())
-
-    if unzip_gif is not None:
-        make_unzip_gif_from_Q(
-            Q_full=Q_full,
-            boundaries=boundaries,
-            base_step=float(base_step),
-            mu=float(mu),
-            n_bytes=int(n_bytes),
-            out_gif=unzip_gif,
-            max_bands=(bands_to_apply if bands_to_apply > 0 else 1),
-            gif_scale=gif_scale,
-            draw_horizon=draw_horizon,
-            draw_outlines=draw_outlines,
-        )
-
-    return {
-        "n_bytes": int(n_bytes),
-        "block_len": int(block_len),
-        "n_blocks": int(n_blocks),
-        "n_bands": int(n_bands),
-        "base_step": float(base_step),
-        "mu": float(mu),
-        "payload_len": int(payload_len),
-        "out_path": out_path,
-        "unzip_gif": unzip_gif,
-        "bands_applied": int(bands_to_apply),
+from PIL import Image
+from flc_core import flc_encode_file, flc_decode_file, cosine_similarity_bytes
+
+st.set_page_config(page_title="FLC v1.3 | How it Works", layout="wide")
+
+# Styling for a "Scientific Laboratory" look
+st.markdown("""
+    <style>
+    .reportview-container { background: #0e1117; }
+    .main { color: #e0e0e0; }
+    h1, h2, h3 { color: #f1c40f !important; }
+    .stAlert { background-color: #1a1c24; border: 1px solid #f1c40f; }
+    </style>
+    """, unsafe_allow_html=True)
+
+st.title("🌀 Fibonacci Lattice Compression (FLC)")
+st.markdown("""
+    **FLC v1.3** is a bio-inspired data compression architecture. Unlike standard ZIP or JPEG formats, 
+    FLC uses the **Golden Ratio ($\Phi$)** to decide which parts of your data are "essential" and which are "noise."
+""")
+
+# --- PILLAR 1: THE EXPLAINER ---
+with st.expander("📖 Step-by-Step: How does the 'Secret Sauce' work?"):
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        st.markdown("### 1. Spectral Projection")
+        st.write("""
+            We treat your data like a sound wave. Using a **DCT (Discrete Cosine Transform)**, 
+            we project the bits into frequency space. 
+            * **Low Frequencies:** The "skeleton" of your data.
+            * **High Frequencies:** The "dust" and fine details.
+        """)
+
+    with col2:
+        st.markdown("### 2. The Golden Filter")
+        st.write("""
+            Instead of treating all frequencies equally, FLC uses **Fibonacci Bands**. 
+            We compress the 'dust' using steps based on the **Golden Ratio ($\Phi \approx 1.618$)**. 
+            As the frequency increases, the compression gets exponentially more aggressive.
+        """)
+
+    with col3:
+        with st.container():
+            st.markdown("### 3. Fibonacci Coding")
+            st.write("""
+                Standard computers use 8-bit bytes. FLC uses **Fibonacci Binary**. 
+                It's a "universal code" that uses the sum of Fibonacci numbers to represent values, 
+                making the compressed stream incredibly resilient and dense.
+            """)
+
+st.divider()
+
+# --- PILLAR 2: THE INTERACTIVE DEMO ---
+st.header("🧪 Test the Horizon")
+with st.sidebar:
+    st.header("🎛️ Architecture Params")
+    st.info("Adjusting these changes how the 'Secret Sauce' math is applied.")
+    
+    quality_map = {
+        "High Compression (Lossy)": {"bands": 6, "step": 0.08, "desc": "Aggressive $\Phi$-scaling."},
+        "Balanced": {"bands": 12, "step": 0.005, "desc": "The Golden Mean of fidelity."},
+        "Near-Lossless": {"bands": 24, "step": 0.0001, "desc": "Full spectral recovery."}
     }
-
-# --------------------------
-# Quality metric
-# --------------------------
-def cosine_similarity_bytes(a: bytes, b: bytes) -> float:
-    x = np.frombuffer(a, dtype=np.uint8).astype(np.float64)
-    y = np.frombuffer(b, dtype=np.uint8).astype(np.float64)
-    n = min(x.size, y.size)
-    x = x[:n]; y = y[:n]
-    x -= x.mean(); y -= y.mean()
-    nx = np.linalg.norm(x) + 1e-12
-    ny = np.linalg.norm(y) + 1e-12
-    return float(np.dot(x, y) / (nx * ny))
-
-# --------------------------
-# CLI wrapper (call explicitly)
-# --------------------------
-def flc_cli(argv=None):
-    ap = argparse.ArgumentParser(description="FLC v1.3: Fibonacci-banded DCT + φ quant + Fibonacci coding + horizon ring + tile outlines")
-    ap.add_argument("inp", type=str)
-    ap.add_argument("out_flc", type=str)
-    ap.add_argument("preview_png", type=str)
-    ap.add_argument("unzip_gif", type=str)
-    ap.add_argument("out_recovered", type=str)
-    ap.add_argument("--block", type=int, default=1024)
-    ap.add_argument("--bands", type=int, default=10)
-    ap.add_argument("--step", type=float, default=0.004)
-    ap.add_argument("--no_center", action="store_true")
-    ap.add_argument("--horizon", type=int, default=None)
-    ap.add_argument("--gif_scale", type=int, default=2)
-    ap.add_argument("--no_ring", action="store_true")
-    ap.add_argument("--no_outlines", action="store_true")
-    args = ap.parse_args(argv)
-
-    enc = flc_encode_file(
-        args.inp, args.out_flc, args.preview_png, unzip_gif=args.unzip_gif,
-        block_len=args.block, n_bands=args.bands, base_step=args.step,
-        use_mean_center=(not args.no_center),
-        gif_scale=args.gif_scale,
-        gif_horizon=None,
-        draw_horizon=(not args.no_ring),
-        draw_outlines=(not args.no_outlines),
-    )
-    print("ENC:", enc)
-
-    dec = flc_decode_file(
-        args.out_flc, args.out_recovered,
-        unzip_gif="decode_" + os.path.basename(args.unzip_gif),
-        max_bands=args.horizon,
-        gif_scale=args.gif_scale,
-        draw_horizon=(not args.no_ring),
-        draw_outlines=(not args.no_outlines),
-    )
-    print("DEC:", dec)
-
-    a = open(args.inp, "rb").read()
-    b = open(args.out_recovered, "rb").read()
-    cs = cosine_similarity_bytes(a, b)
-    print("Cosine similarity (bytes):", cs, " => ", cs*100, "%")
-    print("ORIG:", os.path.getsize(args.inp), "FLC:", os.path.getsize(args.out_flc),
-          "RATIO:", os.path.getsize(args.out_flc)/max(1, os.path.getsize(args.inp)))
-
-# ============================================================
-# Notebook demo (run manually)
-# ============================================================
-with open("test_input.bin","wb") as f:
-    f.write(b"Black hole horizon unzip meets Fibonacci spiral. " * 220)
-enc = flc_encode_file("test_input.bin","test_output.flc","test_preview.png",
-                      unzip_gif="test_unzip.gif",
-                      block_len=1024, n_bands=10, base_step=0.004,
-                       gif_scale=2, draw_horizon=True, draw_outlines=True)
-print("ENC:", enc)
-dec = flc_decode_file("test_output.flc","test_recovered.bin",
-                      unzip_gif="test_decode_unzip.gif",
-                      max_bands=None, gif_scale=2,
-                      draw_horizon=True, draw_outlines=True)
-print("DEC:", dec)
-a = open("test_input.bin","rb").read()
-b = open("test_recovered.bin","rb").read()
-print("Cosine similarity:", cosine_similarity_bytes(a,b))
-decp = flc_decode_file("test_output.flc","test_partial.bin",
-                       unzip_gif="test_partial_unzip.gif",
-                       max_bands=4, gif_scale=2,
-                       draw_horizon
+    
+    tier = st.radio("Fidelity Tier", list(quality_map.keys()), index=1)
+    st.caption(quality_map[tier]["desc"])
+    
+    st.subheader("Visual Overlays")
+    show_spiral = st.checkbox("Fibonacci Spiral Outlines", value=True)
+    show_ring = st.checkbox("Event Horizon Ring", value=True)
+
+uploaded_file = st.file_uploader("Upload a file (Image, Text, or Binary)", type=["bin", "png", "jpg", "txt"])
+
+if uploaded_file is not None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        in_path = os.path.join(tmpdir, "input.bin")
+        out_flc = os.path.join(tmpdir, "output.flc")
+        out_gif = os.path.join(tmpdir, "unzip.gif")
+        recovered_path = os.path.join(tmpdir, "recovered.bin")
+        
+        with open(in_path, "wb") as f:
+            f.write(uploaded_file.getbuffer())
+            
+        if st.button("RUN HOLOGRAPHIC RECONSTRUCTION"):
+            with st.status("Initializing Fibonacci Manifolds...", expanded=True) as status:
+                st.write("Transforming data to Frequency Space...")
+                enc = flc_encode_file(
+                    in_path, out_flc, unzip_gif=out_gif,
+                    n_bands=quality_map[tier]["bands"], 
+                    base_step=quality_map[tier]["step"]
+                )
+                
+                st.write("Applying $\Phi$-scaled quantization...")
+                dec = flc_decode_file(out_flc, recovered_path)
+                
+                st.write("Generating Holographic Unzip visualization...")
+                status.update(label="Reconstruction Complete!", state="complete", expanded=False)
+
+            # Results Section
+            st.subheader("📊 Compression Performance")
+            c1, c2, c3, c4 = st.columns(4)
+            c1.metric("Original Size", f"{enc['n_bytes']} B")
+            c2.metric("Compressed Size", f"{enc['payload_len']} B")
+            c3.metric("Ratio", f"{enc['ratio']:.2%}")
+            
+            # Calculate Similarity
+            orig_data = open(in_path, "rb").read()
+            reco_data = open(recovered_path, "rb").read()
+            fidelity = cosine_similarity_bytes(orig_data, reco_data)
+            c4.metric("Data Fidelity", f"{fidelity*100:.2f}%")
+
+            st.divider()
+
+            # Visualization
+            st.header("🎞️ The Unzip Sequence")
+            st.markdown("""
+                This animation shows the **Progressive Reconstruction**. 
+                The 'Hologram' on the left shows the frequency data being added band-by-band. 
+                The 'Spiral' on the right shows the bits filling the Fibonacci tiles in real-time.
+            """)
+            
+            if os.path.exists(out_gif):
+                st.image(out_gif, use_container_width=True)
+            
+            st.info("💡 Notice how the general shape appears first, and the fine details (noise) appear last. This is the hallmark of Spectral Compression.")
+
+            with open(out_flc, "rb") as f:
+                st.download_button("📥 Download Encoded .FLC File", f, file_name="demo.flc")
+
+else:
+    st.warning("Please upload a file to visualize the Fibonacci transformation.")