/**
 * hasselink/tiling/tiling.ts
 * ------------------------------------------------------
 * Multi-scale 2D tiling spec for the number tesseract.
 *
 * This describes how:
 *   - 5D logical cells (Coord5D / GenesisCell / Hasseract cells)
 *   - map onto a 2D square texture
 *   - across multiple resolution levels (fat pixels vs tiny pixels)
 *
 * Two separate ideas live here and must NOT be conflated:
 *
 * 1) Physical substrate packing (implementation convenience)
 *    - We often pack pixels into square blocks (1×1, 2×2, 4×4, 8×8, ...)
 *      because GPUs/images are naturally square-grid.
 *    - These "Levels" describe that packing only.
 *
 * 2) Logical refinement arity (normative Hasselink recursion)
 *    - Refinement follows the prime/Mersenne ladder (7, 31, 127, ...),
 *      consistent with `program/nat-ladder.ts`.
 *    - This is how we recurse cells "inside cells" in the crystal.
 *
 * The key rule:
 * - Level ≠ logical fanout.
 * - Level is a way to *draw/store*; prime-ladder arity is a way to *name/refine*.
 *
 * Each logical “value cell” is represented by:
 *   - a fat block (payload) at some Level,
 *   - with smaller pixels in/around it (delta, seam, echo, code).
 *
 * This file only defines SHAPES and ROLES.
 * spec/impl will implement the actual mapping.
 */

import { Coord5D } from "../genesis/genesis.ts";
import { GenesisCell } from "../genesis/ball.ts";
import type { Assert } from "../tuple.ts";

/* ----------------------------------------------------- */
/* 1. Levels and block sizes                             */
/* ----------------------------------------------------- */

/**
 * Level = multi-resolution tier for the 2D substrate.
 *
 * Level 0: smallest pixels (raw substrate)
 * Level 1: 2×2 blocks
 * Level 2: 4×4 blocks
 * Level 3: 8×8 blocks
 *
 * You can extend this as needed for storage/visualization.
 */
export type Level = 0 | 1 | 2 | 3;

/**
 * BlockSize<L>:
 *   the edge length (in Level-0 pixels) of one block at Level L.
 *
 * L=0 → 1
 * L=1 → 2
 * L=2 → 4
 * L=3 → 8
 */
export type BlockSize<L extends Level> =
  L extends 0 ? 1 :
  L extends 1 ? 2 :
  L extends 2 ? 4 :
  L extends 3 ? 8 :
  never;

// compile-time sanity checks
type _Proof_BlockSize_L0 = Assert<BlockSize<0> extends 1 ? true : false>;
type _Proof_BlockSize_L1 = Assert<BlockSize<1> extends 2 ? true : false>;
type _Proof_BlockSize_L2 = Assert<BlockSize<2> extends 4 ? true : false>;
type _Proof_BlockSize_L3 = Assert<BlockSize<3> extends 8 ? true : false>;

/* ----------------------------------------------------- */
/* 2. Block and pixel coordinates                        */
/* ----------------------------------------------------- */

/**
 * BlockCoord<L>:
 *   the integer coordinate of a Level-L block in the global texture.
 *
 * The actual global texture dimensions are implementation-defined.
 */
export interface BlockCoord<L extends Level = Level> {
  level: L;
  bx: number; // block index in X
  by: number; // block index in Y
}

/**
 * PixelIndex<L>:
 *   the local index of a pixel INSIDE a Level-L block.
 *
 * Valid ranges:
 *   ix,iy ∈ [0 .. BlockSize<L>-1]
 *
 * We do not enforce the numeric range at type-level; impl must honor it.
 */
export interface PixelIndex<L extends Level = Level> {
  ix: number;
  iy: number;
}

/**
 * TiledPixel:
 *   a fully qualified pixel coordinate in the 2D substrate:
 *     - which Level,
 *     - which block at that level,
 *     - which pixel inside that block.
 */
export interface TiledPixel<L extends Level = Level> {
  block: BlockCoord<L>;
  index: PixelIndex<L>;
}

/* ----------------------------------------------------- */
/* 3. Pixel roles and channels                           */
/* ----------------------------------------------------- */

/**
 * PixelRole:
 *   how this pixel is interpreted within a block.
 *
 * The intent:
 *   - "Payload" : bulk value bits (fat pixels)
 *   - "Delta"   : "what changed" since prev state
 *   - "Corner"  : corner link / neighbor presence
 *   - "Rib"     : edge / seam metadata (truncated-octahedron ribs)
 *   - "Echo"    : long-term memory (past states / ripple info)
 */
export type PixelRole =
  | "Payload"
  | "Delta"
  | "Corner"
  | "Rib"
  | "Echo";

/**
 * PixelChannel:
 *   logical channel dimension this pixel belongs to.
 *
 *   - "Prev"    : previous frame / t-1 view
 *   - "Next"    : next frame / t+1 view
 *   - "Data"    : data interpretation (EvenData)
 *   - "Code"    : code interpretation (OddCode)
 *   - "Meta"    : metadata not toggled by data/code parity
 */
export type PixelChannel =
  | "Prev"
  | "Next"
  | "Data"
  | "Code"
  | "Meta";

/**
 * TypedTiledPixel:
 *   a fully annotated pixel:
 *     - where it lives in the 2D substrate,
 *     - what role it plays,
 *     - on which logical channel.
 */
export interface TypedTiledPixel<L extends Level = Level> extends TiledPixel<L> {
  role: PixelRole;
  channel: PixelChannel;
}

/* ----------------------------------------------------- */
/* 4. Logical → Tiling mapping shapes                    */
/* ----------------------------------------------------- */

/**
 * LogicalID:
 *   A logical "owner" of pixels.
 *
 * Most commonly:
 *   - a Coord5D cell (full 5D address),
 *   - or a GenesisCell (role + ring + coord),
 *   - or a future HASSERact cell structure.
 */
export type LogicalID = Coord5D | GenesisCell;

/**
 * BlockRole:
 *   coarse-grained role of an entire Level-L block.
 *
 * Example:
 *   - a Level-2 block might be the "bulk payload" of a single value cell,
 *   - while Level-1 blocks around it carry ribs and corners.
 */
export type BlockRole =
  | "PayloadBlock"   // bulk value of a logical cell
  | "LinkBlock"      // mostly LINK / seam / neighbor info
  | "EchoBlock"      // long-term memory / shadows
  | "ReservedBlock"; // reserved for future / special use

/**
 * BlockAssignment:
 *   assigns a block to:
 *     - a logical owner (cell),
 *     - a coarse-grained role,
 *     - and a Level.
 */
export interface BlockAssignment<L extends Level = Level> {
  owner: LogicalID;
  level: L;
  block: BlockCoord<L>;
  role: BlockRole;
}

/**
 * PixelAssignment:
 *   a finer-grained assignment of a pixel inside a block.
 *
 * This decomposes a BlockAssignment down to individual pixels.
 */
export interface PixelAssignment<L extends Level = Level> extends BlockAssignment<L> {
  pixel: TypedTiledPixel<L>;
}

/* ----------------------------------------------------- */
/* 5. Tiling strategy interface                          */
/* ----------------------------------------------------- */

/**
 * TilingStrategy:
 *   describes how logical cells are laid out on the 2D substrate
 *   across multiple Levels.
 *
 * This is a SPEC-ONLY interface.
 * Implementations live in spec/impl/TilingImpl.ts (or similar).
 *
 * Typical strategy:
 *   - each logical Coord5D maps to one primary PayloadBlock at some Level,
 *   - plus a small "halo" of LinkBlocks at same or lower Levels,
 *   - echoes/Deltas stored at lower Levels in shared blocks.
 */
export interface TilingStrategy {
  /**
   * Given a logical cell, return the blocks it occupies at various Levels.
   *
   * Example:
   *   - Level 2 block = bulk payload for that cell
   *   - Level 1 blocks around it = seam ribs / corners
   */
  blocksForLogical(logical: LogicalID): readonly BlockAssignment[];

  /**
   * Given a block assignment, return all pixel-level assignments
   * for that block.
   *
   * Here is where the strategy can enforce:
   *   - the "fat payload pixel(s)" for the cell,
   *   - which corners are "neighbor presence" bits,
   *   - which pixels encode Delta,
   *   - where Echo bits live.
   */
  pixelsForBlock(block: BlockAssignment): readonly PixelAssignment[];
}

/* ----------------------------------------------------- */
/* 6. High-level semantic intentions                     */
/* ----------------------------------------------------- */

/**
 * Intended semantics (non-binding, descriptive):
 *
 * 1. Multi-scale representation:
 *    - Level 3 blocks hold "big" payload pixels
 *    - Level 2 / 1 / 0 hold finer detail:
 *        * Delta vs previous frame
 *        * Link / seam bits (neighbors)
 *        * Echo bits (past history)
 *
 * 2. Fat vs small pixels:
 *    - "Payload" pixels are visually large, representing whole cells.
 *    - "Corner" / "Rib" pixels sit on edges/corners inside the block
 *      and are used to infer truncated-octahedron adjacency from
 *      an underlying square grid.
 *
 * 3. Only-changes-painted rule:
 *    - impl may choose a convention where:
 *        * changed bits are explicitly updated,
 *        * unchanged bits are color-inverted (XOR),
 *      so that long-term parity encodes how many steps have passed.
 *
 * 4. Echo / long-term memory:
 *    - deeper Levels (smaller pixels) can encode echoes of older
 *      states, so that:
 *        * even with just two frames (prev/next),
 *        * multiple steps of history remain locally visible,
 *      by reading nested patterns and their parities.
 *
 * 5. Moebius parity:
 *    - PixelChannel "Data" vs "Code" can be interpreted differently
 *      depending on global time parity:
 *        * even t: Payload = data, Echo/Delta = code hints
 *        * odd t: Payload = code, Echo/Delta = data hints
 *
 * This Tiling spec is the "visual substrate" for the Hasselink /
 * HASSERact universe: a way to imagine and later implement
 * the 5D number tesseract on a 2D GPU texture or image.
 */