/**
 * Type declarations for `WorldCodec.js`.
 *
 * The app itself needs none of this — it type-checks the JSDoc in place via `// @ts-check`. This file
 * exists for the **Devvit app**, whose TypeScript build imports the codec across the package
 * boundary (server-side validation of the pasted world code) and, unlike the root, does not enable
 * `allowJs`. Keep it in step with the JSDoc next door; `tests/worldCodec.test.js` pins the behavior.
 */

export type GeneratorDescriptor = {
  /** The initial-state generator mode: `'density'` (random fill) or `'clusters'` (clumps). */
  mode: string
  /** Generator parameters (e.g. `{density}` or the cluster params). */
  params: object
}

export type DecodedWorld = {
  /** Grid rows. */
  rows: number
  /** Grid columns (as captured — the codec does not re-derive them from `rows`). */
  cols: number
  /** 32-char uppercase hex. */
  rulesetHex: string
  /** `rows * cols` entries, one byte per cell (0 or 1) — the exact tick-0 state. Null iff `generator` is set. */
  cells: Uint8Array | null
  /** A recipe to reseed the state on every start. Null iff `cells` is set. */
  generator: GeneratorDescriptor | null
  /** Ticks per second. */
  speed: number
  /**
   * Brush / neighborhood radius (0–40). Always set; legacy v1 codes decode as
   * {@link DEFAULT_BRUSH_SIZE} (2).
   */
  brushSize: number
  /** Color settings to feed `generateColorLUT`. Null iff `lut` is set. */
  colorSettings: object | null
  /** A ready 128×2 RGBA LUT (1024 bytes). Null iff `colorSettings` is set. */
  lut: Uint8Array | null
}

export type WorldCodeInput = {
  rows: number
  cols: number
  rulesetHex: string
  /** The exact tick-0 grid. Required unless `generator` is given. */
  cells?: Uint8Array | number[]
  /** A `{mode, params}` generator that replaces `cells` — the embed reseeds from it on every start. */
  generator?: GeneratorDescriptor
  /** Preferred palette form: compact, and the decoder rebuilds the identical LUT. */
  colorSettings?: object
  /** Fallback palette form: a baked 128×2 **RGBA** LUT (1024 bytes). */
  lut?: Uint8Array
  speed?: number
  /** Brush / neighborhood radius (0–40). Defaults to 2. */
  brushSize?: number
}

export const DEFAULT_BRUSH_SIZE: 2

/** Encode a world into a `HXW1.` code, or null if the inputs don't describe a world. */
export function encodeWorldCode(world: WorldCodeInput): Promise<string | null>

/** Decode a `HXW1.` code. Never throws; resolves to null for anything malformed. */
export function decodeWorldCode(code: string): Promise<DecodedWorld | null>

/** Cheap synchronous shape check: does this string even claim to be a world code? */
export function isWorldCode(code: string): boolean

/**
 * Whether a world-code palette is safe to autoplay (no birth/death strobing).
 * Conservative when unknown (baked LUT, gradient, missing settings).
 */
export function isFlickerProofPalette(
  colorSettings: object | null | undefined,
  lut?: Uint8Array | null,
): boolean

/**
 * Explorer deep-link with ShareCodec `r` (and optional `g` rows). `edit: true` adds `edit=1`,
 * which opens the ruleset editor on boot in the mode that fits the rule.
 */
export function explorerUrlForRuleset(
  rulesetHex: string,
  opts?: {rows?: number; origin?: string; edit?: boolean},
): string

export const PALETTE_SETTINGS: 0
export const PALETTE_LUT: 1

export const CELLS_PACKED: 0
export const CELLS_GENERATOR: 1