diff --git a/client/global_client.html b/client/global_client.html
index 8118d42..96204eb 100644
--- a/client/global_client.html
+++ b/client/global_client.html
@@ -162,6 +162,7 @@
   <div id="debugSprites"></div>
 </div>
 <script src="snappyjs.min.js"></script>
+<script src="spritecodec.js"></script>
 <script>
 const canvas=document.getElementById("c"),ctx=canvas.getContext("2d");
 function viewWidth(){
@@ -1002,6 +1003,38 @@
       });
       scheduleDebugSprites();
       scheduleDebugUpdateClear();
+    }else if(type===0x08){
+      // Define Encoded Sprite: same fields as 0x01 plus an encoding
+      // byte before the payload length. Decoded by spritecodec.js.
+      const packetStart=offset-1;
+      const encoded=window.SpriteCodec.readEncodedSprite(bytes,offset,textDecoder);
+      if(!encoded)throw new Error("Truncated encoded sprite");
+      const decoded=window.SpriteCodec.decodeSprite(
+        encoded.encoding,
+        encoded.payload,
+        encoded.width,
+        encoded.height,
+        sourceId=>sprites.get(sourceId)
+      );
+      if(decoded.pixels.length!==encoded.width*encoded.height*4){
+        throw new Error("Bad sprite pixel length");
+      }
+      offset=encoded.offset;
+      const previous=sprites.get(encoded.id);
+      const packetBytes=offset-packetStart;
+      sprites.set(encoded.id,{
+        width:encoded.width,
+        height:encoded.height,
+        pixels:decoded.pixels,
+        indices:decoded.indices,
+        palette:decoded.palette,
+        label:encoded.label,
+        updates:(previous?previous.updates:0)+1,
+        bytesDown:(previous?previous.bytesDown:0)+packetBytes,
+        updatedUntil:performance.now()+DebugUpdateFlashMs
+      });
+      scheduleDebugSprites();
+      scheduleDebugUpdateClear();
     }else if(type===0x02){
       const id=readU16(bytes,offset);
       const x=readI16(bytes,offset+2);
diff --git a/client/global_client.nim b/client/global_client.nim
index e9769fa..f443dc7 100644
--- a/client/global_client.nim
+++ b/client/global_client.nim
@@ -13,6 +13,10 @@ type
     width, height: int
     label: string
     pixels: seq[uint8]
+    indices: seq[uint8]
+      ## Index plane kept for indexed sprites so a later palette swap
+      ## can reuse it; empty for RGBA sprites.
+    palette: seq[uint8]
 
   GlobalObject = object
     id, x, y, z, layer, spriteId: int
@@ -707,6 +711,60 @@ proc parseMessage*(app: GlobalApp, data: string) =
       offset += labelLength
       sprite.label = label
       app.sprites[id] = sprite
+    of 0x08:
+      require(11)
+      var def = SpritePacketSpriteDef(
+        id: data.readU16(offset),
+        width: data.readU16(offset + 2),
+        height: data.readU16(offset + 4),
+        encoding: data.readU8(offset + 6)
+      )
+      let payloadSize = data.readU32(offset + 7)
+      offset += 11
+      if def.width <= 0 or def.height <= 0:
+        app.closeNetwork()
+        return
+      require(payloadSize)
+      def.compressedPixels = newSeq[uint8](payloadSize)
+      for i in 0 ..< payloadSize:
+        def.compressedPixels[i] = data[offset + i].uint8
+      offset += payloadSize
+      require(2)
+      let labelLength = data.readU16(offset)
+      offset += 2
+      require(labelLength)
+      def.label = newString(labelLength)
+      for i in 0 ..< labelLength:
+        def.label[i] = data[offset + i]
+      offset += labelLength
+      var source: DecodedSprite
+      let sourceId = def.paletteSwapSourceId()
+      if sourceId >= 0 and app.sprites.hasKey(sourceId):
+        source = DecodedSprite(
+          width: app.sprites[sourceId].width,
+          height: app.sprites[sourceId].height,
+          indices: app.sprites[sourceId].indices,
+          palette: app.sprites[sourceId].palette
+        )
+      var decoded: DecodedSprite
+      try:
+        decoded = def.decodeSprite(source)
+      except SpriteProtocolError:
+        app.closeNetwork()
+        return
+      # Renderers need pixels; a pixel-free definition is a protocol
+      # error here, matching the legacy Define Sprite branch.
+      if decoded.pixels.len != def.width * def.height * 4:
+        app.closeNetwork()
+        return
+      app.sprites[def.id] = GlobalSprite(
+        width: def.width,
+        height: def.height,
+        label: def.label,
+        pixels: decoded.pixels,
+        indices: decoded.indices,
+        palette: decoded.palette
+      )
     of 0x02:
       require(11)
       let item = GlobalObject(
diff --git a/client/player_client.html b/client/player_client.html
index c28c9a3..a2dd968 100644
--- a/client/player_client.html
+++ b/client/player_client.html
@@ -17,6 +17,7 @@
 <input id="i" maxlength="48" autocomplete="off" autocapitalize="off" spellcheck="false">
 <div id="s">connecting...</div>
 <script src="snappyjs.min.js"></script>
+<script src="spritecodec.js"></script>
 <script>
 const c=document.getElementById("c"),i=document.getElementById("i"),s=document.getElementById("s"),x=c.getContext("2d");
 const p=[0,0,0,255,194,195,199,255,255,241,232,255,255,0,77,255,255,119,168,255,95,87,79,255,171,82,54,255,255,163,0,255,255,236,39,255,126,37,83,255,0,135,81,255,0,228,54,255,29,43,83,255,131,118,156,255,41,173,255,255,255,204,170,255];
@@ -156,6 +157,13 @@
       const snappy=trySnappySprite(bytes,offset,bytes.length-offset,width,height);
       if(snappy){sprites.set(id,{width,height,pixels:snappy.pixels,label:snappy.label});offset=snappy.offset}
       else{sprites.set(id,{width,height,pixels:rawSprite(bytes,offset,width,height),label:""});offset+=width*height}
+    }else if(type===0x08){
+      const encoded=window.SpriteCodec.readEncodedSprite(bytes,offset,textDecoder);
+      if(!encoded)throw new Error("Truncated encoded sprite");
+      const decoded=window.SpriteCodec.decodeSprite(encoded.encoding,encoded.payload,encoded.width,encoded.height,sourceId=>sprites.get(sourceId));
+      if(decoded.pixels.length!==encoded.width*encoded.height*4)throw new Error("Bad sprite pixel length");
+      sprites.set(encoded.id,{width:encoded.width,height:encoded.height,pixels:decoded.pixels,indices:decoded.indices,palette:decoded.palette,label:encoded.label});
+      offset=encoded.offset
     }else if(type===0x02){
       const id=readU16(bytes,offset),ox=readI16(bytes,offset+2),oy=readI16(bytes,offset+4),z=readI16(bytes,offset+6),layer=bytes[offset+8],spriteId=readU16(bytes,offset+9);
       objects.set(id,{id,x:ox,y:oy,z,layer,spriteId});offset+=11
diff --git a/client/spritecodec.js b/client/spritecodec.js
new file mode 100644
index 0000000..4ed56d0
--- /dev/null
+++ b/client/spritecodec.js
@@ -0,0 +1,258 @@
+// Sprite v1 Define Encoded Sprite (0x08) decoder for browser clients.
+//
+// Exposes SpriteCodec.decodeSprite(encoding, payload, width, height,
+// lookup), which returns {pixels, indices, palette}: straight RGBA
+// pixels (Uint8Array of width*height*4), plus the index plane and RGBA
+// palette for indexed and palette-swap sprites so a later palette swap
+// can reuse them. `lookup(spriteId)` must return the previously decoded
+// sprite object ({indices, width, height}) for palette swaps.
+//
+// Encodings:
+//   0x00 rgba-snappy   Snappy stream of raw RGBA (needs window.SnappyJS)
+//   0x01 rgba-deflate  zlib stream of raw RGBA
+//   0x02 indexed       u8 count-1, count*4 palette bytes, zlib(index bytes)
+//   0x03 palette-swap  u16 source sprite id, u8 count-1, count*4 palette
+//
+// SpriteCodec.inflate is a small RFC 1950/1951 decoder (stored, fixed,
+// and dynamic Huffman blocks) written against a known output length,
+// so browser clients decode synchronously inside the packet parser.
+(function(root){
+"use strict";
+
+const LENGTH_BASE=[3,4,5,6,7,8,9,10,11,13,15,17,19,23,27,31,35,43,51,59,67,83,99,115,131,163,195,227,258];
+const LENGTH_EXTRA=[0,0,0,0,0,0,0,0,1,1,1,1,2,2,2,2,3,3,3,3,4,4,4,4,5,5,5,5,0];
+const DIST_BASE=[1,2,3,4,5,7,9,13,17,25,33,49,65,97,129,193,257,385,513,769,1025,1537,2049,3073,4097,6145,8193,12289,16385,24577];
+const DIST_EXTRA=[0,0,0,0,1,1,2,2,3,3,4,4,5,5,6,6,7,7,8,8,9,9,10,10,11,11,12,12,13,13];
+const CODE_LENGTH_ORDER=[16,17,18,0,8,7,9,6,10,5,11,4,12,3,13,2,14,1,15];
+
+function buildHuffman(lengths,count){
+  // Canonical Huffman table in the style of zlib's puff.c: counts per
+  // code length and symbols ordered by (length, value).
+  const lengthCount=new Uint16Array(16);
+  for(let i=0;i<count;i++)lengthCount[lengths[i]]++;
+  lengthCount[0]=0;
+  const offsets=new Uint16Array(16);
+  for(let len=1;len<16;len++)offsets[len]=offsets[len-1]+lengthCount[len-1];
+  const symbols=new Uint16Array(count);
+  for(let i=0;i<count;i++){
+    if(lengths[i])symbols[offsets[lengths[i]]++]=i;
+  }
+  return {lengthCount,symbols};
+}
+
+let fixedLiteral=null,fixedDistance=null;
+function fixedTables(){
+  if(fixedLiteral)return;
+  const lengths=new Uint8Array(288);
+  let i=0;
+  for(;i<144;i++)lengths[i]=8;
+  for(;i<256;i++)lengths[i]=9;
+  for(;i<280;i++)lengths[i]=7;
+  for(;i<288;i++)lengths[i]=8;
+  fixedLiteral=buildHuffman(lengths,288);
+  const distances=new Uint8Array(30).fill(5);
+  fixedDistance=buildHuffman(distances,30);
+}
+
+function inflate(input,expectedLength){
+  // Decodes a zlib (RFC 1950) or raw deflate (RFC 1951) stream into a
+  // Uint8Array of exactly expectedLength bytes.
+  const src=input instanceof Uint8Array?input:new Uint8Array(input);
+  let pos=0;
+  if(src.length>=2&&(src[0]&0x0f)===8&&(((src[0]<<8)|src[1])%31)===0){
+    if(src[1]&0x20)throw new Error("zlib preset dictionary not supported");
+    pos=2;
+  }
+  const out=new Uint8Array(expectedLength);
+  let outPos=0;
+  let bitBuffer=0,bitCount=0;
+
+  function bits(need){
+    let value=bitBuffer;
+    while(bitCount<need){
+      if(pos>=src.length)throw new Error("deflate stream truncated");
+      value|=src[pos++]<<bitCount;
+      bitCount+=8;
+    }
+    bitBuffer=value>>>need;
+    bitCount-=need;
+    return value&((1<<need)-1);
+  }
+
+  function decodeSymbol(table){
+    let code=0,first=0,index=0;
+    for(let len=1;len<16;len++){
+      code|=bits(1);
+      const count=table.lengthCount[len];
+      if(code-count<first)return table.symbols[index+(code-first)];
+      index+=count;
+      first+=count;
+      first<<=1;
+      code<<=1;
+    }
+    throw new Error("bad huffman code");
+  }
+
+  function inflateBlock(literal,distance){
+    for(;;){
+      let symbol=decodeSymbol(literal);
+      if(symbol<256){
+        if(outPos>=expectedLength)throw new Error("deflate output too long");
+        out[outPos++]=symbol;
+      }else if(symbol===256){
+        return;
+      }else{
+        symbol-=257;
+        if(symbol>=29)throw new Error("bad length code");
+        const length=LENGTH_BASE[symbol]+bits(LENGTH_EXTRA[symbol]);
+        const distSymbol=decodeSymbol(distance);
+        if(distSymbol>=30)throw new Error("bad distance code");
+        const dist=DIST_BASE[distSymbol]+bits(DIST_EXTRA[distSymbol]);
+        if(dist>outPos)throw new Error("deflate distance too far back");
+        if(outPos+length>expectedLength)throw new Error("deflate output too long");
+        let from=outPos-dist;
+        for(let i=0;i<length;i++)out[outPos++]=out[from++];
+      }
+    }
+  }
+
+  let last=0;
+  do{
+    last=bits(1);
+    const type=bits(2);
+    if(type===0){
+      bitBuffer=0;bitCount=0;
+      if(pos+4>src.length)throw new Error("deflate stream truncated");
+      const len=src[pos]|(src[pos+1]<<8);
+      const nlen=src[pos+2]|(src[pos+3]<<8);
+      pos+=4;
+      if((len^0xffff)!==nlen)throw new Error("bad stored block length");
+      if(pos+len>src.length)throw new Error("deflate stream truncated");
+      if(outPos+len>expectedLength)throw new Error("deflate output too long");
+      out.set(src.subarray(pos,pos+len),outPos);
+      pos+=len;
+      outPos+=len;
+    }else if(type===1){
+      fixedTables();
+      inflateBlock(fixedLiteral,fixedDistance);
+    }else if(type===2){
+      const literalCount=bits(5)+257;
+      const distanceCount=bits(5)+1;
+      const codeLengthCount=bits(4)+4;
+      if(literalCount>286||distanceCount>30)throw new Error("bad dynamic block header");
+      const codeLengths=new Uint8Array(19);
+      for(let i=0;i<codeLengthCount;i++)codeLengths[CODE_LENGTH_ORDER[i]]=bits(3);
+      const codeTable=buildHuffman(codeLengths,19);
+      const lengths=new Uint8Array(literalCount+distanceCount);
+      let i=0;
+      while(i<literalCount+distanceCount){
+        const symbol=decodeSymbol(codeTable);
+        if(symbol<16){
+          lengths[i++]=symbol;
+        }else{
+          let repeat=0,value=0;
+          if(symbol===16){
+            if(i===0)throw new Error("bad code length repeat");
+            value=lengths[i-1];
+            repeat=3+bits(2);
+          }else if(symbol===17){
+            repeat=3+bits(3);
+          }else{
+            repeat=11+bits(7);
+          }
+          if(i+repeat>literalCount+distanceCount)throw new Error("bad code lengths");
+          while(repeat--)lengths[i++]=value;
+        }
+      }
+      if(lengths[256]===0)throw new Error("dynamic block has no end code");
+      const literal=buildHuffman(lengths.subarray(0,literalCount),literalCount);
+      const distance=buildHuffman(lengths.subarray(literalCount),distanceCount);
+      inflateBlock(literal,distance);
+    }else{
+      throw new Error("bad deflate block type");
+    }
+  }while(!last);
+  if(outPos!==expectedLength)throw new Error("deflate output too short");
+  return out;
+}
+
+function expandIndices(indices,palette,count){
+  const paletteCount=palette.length>>2;
+  const pixels=new Uint8Array(count*4);
+  for(let i=0;i<count;i++){
+    const index=indices[i];
+    if(index>=paletteCount)throw new Error("sprite palette index out of range");
+    const slot=index*4,out=i*4;
+    pixels[out]=palette[slot];
+    pixels[out+1]=palette[slot+1];
+    pixels[out+2]=palette[slot+2];
+    pixels[out+3]=palette[slot+3];
+  }
+  return pixels;
+}
+
+function decodeSprite(encoding,payload,width,height,lookup){
+  const count=width*height;
+  const expected=count*4;
+  if(payload.length===0){
+    return {pixels:new Uint8Array(0),indices:null,palette:null};
+  }
+  if(encoding===0x00){
+    if(!root.SnappyJS)throw new Error("SnappyJS is not loaded");
+    const raw=root.SnappyJS.uncompress(payload,expected);
+    const pixels=raw instanceof Uint8Array?raw:new Uint8Array(raw);
+    if(pixels.length!==expected)throw new Error("Bad sprite pixel length");
+    return {pixels,indices:null,palette:null};
+  }
+  if(encoding===0x01){
+    return {pixels:inflate(payload,expected),indices:null,palette:null};
+  }
+  if(encoding===0x02){
+    const paletteCount=payload[0]+1;
+    const paletteEnd=1+paletteCount*4;
+    if(payload.length<paletteEnd)throw new Error("truncated sprite palette");
+    const palette=payload.slice(1,paletteEnd);
+    const indices=inflate(payload.subarray(paletteEnd),count);
+    return {pixels:expandIndices(indices,palette,count),indices,palette};
+  }
+  if(encoding===0x03){
+    if(payload.length<3)throw new Error("truncated palette swap");
+    const sourceId=payload[0]|(payload[1]<<8);
+    const paletteCount=payload[2]+1;
+    const paletteEnd=3+paletteCount*4;
+    if(payload.length<paletteEnd)throw new Error("truncated sprite palette");
+    const palette=payload.slice(3,paletteEnd);
+    const source=lookup?lookup(sourceId):null;
+    if(!source||!source.indices||source.indices.length!==count){
+      throw new Error("palette swap source "+sourceId+" is not an indexed sprite of the same size");
+    }
+    return {pixels:expandIndices(source.indices,palette,count),indices:source.indices,palette};
+  }
+  throw new Error("unknown sprite encoding "+encoding);
+}
+
+// Parses the fields after the message type byte of one Define Encoded
+// Sprite message. Returns {id, width, height, encoding, payload,
+// label, offset} with `offset` past the label, or null when the packet
+// is truncated.
+function readEncodedSprite(bytes,offset,textDecoder){
+  if(offset+11>bytes.length)return null;
+  const id=bytes[offset]|(bytes[offset+1]<<8);
+  const width=bytes[offset+2]|(bytes[offset+3]<<8);
+  const height=bytes[offset+4]|(bytes[offset+5]<<8);
+  const encoding=bytes[offset+6];
+  const payloadLength=(bytes[offset+7]|(bytes[offset+8]<<8)|(bytes[offset+9]<<16)|(bytes[offset+10]*0x1000000))>>>0;
+  offset+=11;
+  if(offset+payloadLength+2>bytes.length)return null;
+  const payload=bytes.subarray(offset,offset+payloadLength);
+  offset+=payloadLength;
+  const labelLength=bytes[offset]|(bytes[offset+1]<<8);
+  offset+=2;
+  if(offset+labelLength>bytes.length)return null;
+  const label=textDecoder?textDecoder.decode(bytes.slice(offset,offset+labelLength)):"";
+  offset+=labelLength;
+  return {id,width,height,encoding,payload,label,offset};
+}
+
+root.SpriteCodec={inflate,expandIndices,decodeSprite,readEncodedSprite};
+})(typeof window!=="undefined"?window:globalThis);
diff --git a/docs/compressed_sprites_proposal.md b/docs/compressed_sprites_proposal.md
new file mode 100644
index 0000000..93ab842
--- /dev/null
+++ b/docs/compressed_sprites_proposal.md
@@ -0,0 +1,204 @@
+# Proposal: Define Encoded Sprite (0x08) for Sprite v1
+
+To: Andre (treeform)
+From: Alessandro Solbiati, with the prototype on branch `compressed-sprites`
+of `SolbiatiAlessandro/bitworld`
+
+## The problem, with numbers
+
+Define Sprite (0x01) carries every sprite as raw RGBA, 4 bytes per pixel,
+compressed with Snappy. Snappy is fast, but on flat pixel art it does not
+remove much: it finds repeated 4-byte colors, not the structure of the image.
+
+Heartleaf's director view sends 313 sprites in its init packet. The source art
+for the whole game is about 600 KB of aseprite files (`map.aseprite` is
+289 KB). The init packet was 7,487,421 bytes. The top of the table, measured
+with `tools/init_packet_report.nim` in the heartleaf repo:
+
+| id | label | size | wire bytes | raw RGBA | colors |
+| ---: | --- | --- | ---: | ---: | ---: |
+| 30 | forest underlay | 1708x1901 | 1,698,908 | 12,987,632 | 1629 |
+| 1 | heartleaf bottom | 748x941 | 685,138 | 2,815,472 | 16 |
+| 10..14 | heartleaf bottom tint 0..4 | 748x941 | 5 x ~680,000 | 2,815,472 each | 16 |
+| 2 | heartleaf overhang | 748x941 | 164,407 | 2,815,472 | 17 |
+| 15..19 | heartleaf overhang tint 0..4 | 748x941 | 5 x ~164,000 | 2,815,472 each | 17 |
+| 4, 20..24 | home bottom and 5 tints | 251x247 | 6 x ~53,000 | 247,988 each | 16 |
+| 8700 | chat banner | 318x60 | 29,353 | 76,320 | 1806 |
+| 31..35 | forest dusk veil 0..4 | 512x256 | 5 x 24,650 | 524,288 each | 1 |
+
+Three things stand out. First, a 16-color map costs 685 KB because Snappy sees
+RGBA, not indices. Second, the game pre-composites five dusk tints of each
+map, and each tint is a full copy, although a tint of 16 colors is just 16
+different palette entries over the same index plane. All twenty tinted copies
+(main bottom, main overhang, home bottom, home overhang, five stages each) are
+per-color remaps of their four base sprites, and they cannot be replaced by a
+flat overlay: the early stages rotate hue (grass stays green while paths warm),
+so only the darkest stage approximates a veil. Third, Snappy has a floor on
+constant-color sprites: a solid 748x941 overlay costs 132,208 bytes, and each
+512x256 dusk veil above costs 24,650, so shaped or solid overlay sprites are
+not cheap under the current codec either. The same solid 748x941 sprite is 725
+bytes indexed and 2,772 bytes as deflated RGBA.
+
+## The change
+
+One new server-to-client message. The fields are Define Sprite's fields plus
+one encoding byte in front of the payload length:
+
+| Field | Type |
+| --- | --- |
+| Message type | `u8` = `0x08` |
+| Sprite id | `u16` |
+| Width | `u16` |
+| Height | `u16` |
+| Encoding | `u8` |
+| Payload length | `u32` |
+| Payload | `u8[]` |
+| Label length | `u16` |
+| Label | `u8[]` |
+
+Encodings:
+
+| Value | Payload |
+| ---: | --- |
+| `0x00` rgba-snappy | Snappy stream of raw RGBA. Identical to the 0x01 payload. |
+| `0x01` rgba-deflate | zlib stream of raw RGBA. |
+| `0x02` indexed | `u8` palette count minus one, `count * 4` RGBA palette bytes, then a zlib stream of one index byte per pixel. At most 256 colors. |
+| `0x03` palette-swap | `u16` source sprite id, `u8` palette count minus one, `count * 4` RGBA palette bytes. The client reuses the index plane of the indexed sprite it already holds under the source id. |
+
+A payload length of 0 is a pixel-free definition, same as 0x01. Every other
+payload must decode to exactly `width * height * 4` bytes of straight RGBA.
+The full text is in `docs/sprite_v1.md` on the branch.
+
+0x07 was skipped because stag_hunt already sends 0x07 as a private identity
+packet and both browser clients skip its two bytes. The spec now says so.
+
+## Why this encoding and not PNG
+
+I measured PNG (pixie's encoder, RGBA, no palette), zlib over raw RGBA,
+palette plus run-length, and palette plus zlib on all 313 sprites:
+
+| Encoding | Total bytes for the 313 sprites |
+| --- | ---: |
+| Snappy over RGBA (today) | 7,487,381 |
+| PNG, RGBA color type | 3,765,210 |
+| zlib over RGBA | 2,866,942 |
+| palette + PackBits, PNG for >256 colors | 3,731,903 |
+| palette + zlib, PNG for >256 colors | 2,195,573 |
+| palette + zlib, zlib RGBA for >256 colors, palette swap for tints | 1,083,130 |
+
+Indexed PNG (color type 3) would give the same bytes as "palette + zlib" and is
+a standard container, but it costs the same decoder work in JavaScript (an
+inflater plus PNG chunk and filter parsing on top), it cannot express the
+palette swap, and the browser's native PNG decode is asynchronous and does not
+return exact bytes for translucent pixels (canvas premultiplies alpha). The
+custom payloads are two short reads on top of inflate, decode synchronously
+inside the existing packet parser, and are pixel-exact in every client.
+
+Snappy stays available as encoding 0x00 so a server can send the old payload
+through the new message if it wants one code path.
+
+## Results on the Heartleaf director view
+
+Same 313 sprites, same pixels in every client:
+
+| | Bytes |
+| --- | ---: |
+| Init packet, Define Sprite | 7,487,421 |
+| Init packet, Define Encoded Sprite | 1,083,170 |
+
+Per sprite, the big ones:
+
+| id | label | encoding | before | after |
+| ---: | --- | --- | ---: | ---: |
+| 30 | forest underlay | rgba-deflate | 1,698,908 | 766,928 |
+| 1 | heartleaf bottom | indexed | 685,138 | 189,608 |
+| 10..14 | heartleaf bottom tint 0..4 | palette-swap | 5 x ~680,000 | 5 x 81 |
+| 2 | heartleaf overhang | indexed | 164,407 | 13,918 |
+| 15..19 | heartleaf overhang tint 0..4 | palette-swap | 5 x ~164,000 | 5 x 85 |
+| 4 | heartleaf home bottom | indexed | 53,032 | 14,448 |
+| 20..24 | home bottom tint 0..4 | palette-swap | 5 x ~53,000 | 5 x 81 |
+| 8700 | chat banner | rgba-deflate | 29,353 | 17,435 |
+| 31..35 | forest dusk veil 0..4 | indexed | 5 x 24,650 | 5 x 41 |
+
+The twenty tints together went from about 4.5 MB to 1,660 bytes, with the
+base sprites carrying the index planes once. The palette swap is exact: the
+test suite decodes the encoded packet next to the legacy one and compares
+every sprite byte for byte. Opening the director page in a browser against
+this packet renders the map, forest, and clock through `spritecodec.js` with
+no console errors.
+
+The forest underlay is now 71% of the packet. It is generated at half
+resolution and upscaled 2x on the server, has 1629 colors, and does not index.
+Quantizing it to 4 bits per channel (123 colors) would bring it to 306 KB; that
+is a Heartleaf art decision, not a protocol one. A protocol-level fix would be
+an object or sprite scale factor so the server can send it at half size; that
+is a separate proposal.
+
+## Compatibility
+
+- Define Sprite (0x01) is unchanged and still tested. A server that never sends
+  0x08 is unaffected.
+- A client that predates this change closes the connection on 0x08, which is
+  the existing rule for unknown message types. A server should only send 0x08
+  to clients it ships itself (the embedded browser clients, the native and
+  wasm global client) or to clients that are known to be updated. Heartleaf
+  serves its own copy of the bitworld browser client, so it upgrades both
+  sides in one deploy.
+- `parseSpritePacket` returns 0x08 messages as `spkSprite`, with `encoding`
+  and the payload in `compressedPixels`. A legacy 0x01 message parses with
+  `encoding = SpriteEncodingRgbaSnappy`, so code that switches on encoding
+  handles both.
+- Sprites Off clients get pixel-free definitions through either message.
+- No change to the client-to-server direction, replays, or certification.
+
+## What is on the branch
+
+- `src/bitworld/spriteprotocol.nim`: constants, `encoding` on
+  `SpritePacketSpriteDef`, `DecodedSprite`, `indexPixels`, the four payload
+  encoders, `addEncodedSpritePayload`, `addEncodedSprite` (auto-picks indexed
+  or rgba-deflate), `addPaletteSwapSprite` (falls back to a normal sprite when
+  the recoloring is not consistent), `paletteSwapSourceId`, `decodeSprite`,
+  parser and `spriteMessageBytes` cases for 0x08. zippy is already a
+  dependency (pixie needs it); the module now imports it directly.
+- `client/spritecodec.js`: an RFC 1950/1951 inflater (stored, fixed, and
+  dynamic blocks, decoded against the known output length) plus
+  `decodeSprite` and `readEncodedSprite`. About 250 lines, no dependencies.
+- `client/global_client.html`, `client/player_client.html`: load
+  `spritecodec.js` next to `snappyjs.min.js` and parse `0x08` next to `0x01`.
+  Sprites keep `indices` and `palette` so a palette swap can find them.
+- `client/global_client.nim`: the native and wasm renderer decodes 0x08 with
+  `decodeSprite` and keeps the index plane on `GlobalSprite`.
+- `src/bitworld/client.nim`: `/spritecodec.js`, `/client/spritecodec.js`, and
+  `/clients/spritecodec.js` routes, embedded like the Snappy script.
+- `docs/sprite_v1.md`: the message, encodings, error cases, and the 0x07 note.
+- Tests: `tests/test_spriteencoding.nim` (round trips for every encoding,
+  chained swaps, swap fallback, sizes, malformed payloads),
+  `tests/test_spritecodec_js.nim` with `tests/spritecodec_check.js` (node
+  decodes 11 sprites the Nim encoder wrote, including a legacy 0x01 message,
+  and compares every byte; skipped when node is not installed),
+  `tests/test_client.nim` (routes and parser cases).
+
+## Server-side use
+
+```nim
+packet.addEncodedSprite(id, w, h, pixels, label)          # indexed or deflate
+packet.addPaletteSwapSprite(tintId, id, w, h, pixels, tinted, label)
+```
+
+Heartleaf's branch `compressed-sprites` on `SolbiatiAlessandro/coworld-heartleaf`
+switches its `addRgbaSprite` to `addEncodedSprite` and its map tints to
+`addPaletteSwapSprite`, and adds a test that the encoded init packet decodes
+pixel-identical to the legacy one. Dynamic sprites (name tags, speech bubbles,
+cards) go through the same call and shrink too.
+
+## Open points for you
+
+1. Message value: 0x08 with 0x07 documented as taken by stag_hunt, or reclaim
+   0x07 and move stag_hunt's identity packet.
+2. Whether `SpriteEncodingRgbaSnappy` (0x00) is worth keeping in the new
+   message or whether 0x08 should carry only the new payloads.
+3. The inflater is hand-written in `spritecodec.js`. `DecompressionStream`
+   exists in current browsers but is asynchronous, which would move sprite
+   definitions out of the synchronous parse loop; I kept it synchronous.
+4. Whether to add a scale factor to sprites or objects, which is what the
+   forest underlay needs next.
diff --git a/docs/sprite_v1.md b/docs/sprite_v1.md
index 7056bfe..b17738d 100644
--- a/docs/sprite_v1.md
+++ b/docs/sprite_v1.md
@@ -63,6 +63,54 @@ other client a sprite must carry its full pixel payload.
 
 A sprite with width `0` or height `0` is invalid.
 
+### Define Encoded Sprite
+
+Defines or replaces a sprite with a compressed pixel payload. This message has
+the same meaning as Define Sprite; only the pixel payload changes. Servers that
+send it must know the client supports it, because receivers close the
+connection on unknown message types.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| Message type | `u8` | `0x08` |
+| Sprite id | `u16` | Id of the sprite to define |
+| Width | `u16` | Sprite width in pixels |
+| Height | `u16` | Sprite height in pixels |
+| Encoding | `u8` | Pixel payload encoding, see below |
+| Payload length | `u32` | Number of payload bytes |
+| Payload | `u8[]` | Encoded pixels |
+| Label length | `u16` | Number of UTF-8 label bytes |
+| Label | `u8[]` | Optional human-readable sprite label |
+
+A payload length of `0` is a pixel-free definition with the same rules as for
+Define Sprite. Every other payload must decode to exactly `Width * Height * 4`
+bytes of straight RGBA, the same pixel format Define Sprite uses.
+
+Encoding values:
+
+| Value | Name | Payload |
+| ---: | --- | --- |
+| `0x00` | RGBA Snappy | Snappy stream of raw RGBA pixels. Identical to the Define Sprite payload. |
+| `0x01` | RGBA deflate | zlib stream (RFC 1950) of raw RGBA pixels. |
+| `0x02` | Indexed | Palette count minus one as `u8`, then `count * 4` RGBA palette bytes, then a zlib stream of `Width * Height` palette index bytes, one per pixel in scanline order. |
+| `0x03` | Palette swap | Source sprite id as `u16`, palette count minus one as `u8`, then `count * 4` RGBA palette bytes. |
+
+An indexed sprite has `1 .. 256` colors. A palette index that is greater than
+or equal to the palette count is invalid.
+
+A palette swap reuses the index plane of a sprite the client already holds and
+gives it a new palette. The source sprite must have been defined earlier on
+the same connection with the indexed encoding, or as a palette swap of one,
+and must have the same width and height. The client keeps the index plane of
+every indexed sprite for this purpose; the new sprite keeps that index plane
+too, so a palette swap can itself be the source of a later palette swap.
+Palette entries beyond those the index plane uses are allowed and unused.
+
+Servers should prefer the indexed encoding for sprites with at most 256 colors,
+the palette swap for recolored copies of an indexed sprite (day tints, team
+colors), and RGBA deflate for everything else. RGBA Snappy exists so a server
+can carry the legacy payload through the new message.
+
 ### Define Object
 
 Defines or replaces an object instance.
@@ -330,6 +378,7 @@ supports this message must accept it at any point in the connection.
 | `0x04` | Server to client | Clear objects |
 | `0x05` | Server to client | Set viewport |
 | `0x06` | Server to client | Define layer |
+| `0x08` | Server to client | Define encoded sprite |
 | `0x81` | Client to server | Input text |
 | `0x82` | Client to server | Mouse position |
 | `0x83` | Client to server | Mouse button |
@@ -338,7 +387,9 @@ supports this message must accept it at any point in the connection.
 | `0x86` | Client to server | Debug sprites |
 | `0x87` | Client to server | Sprites off |
 
-Message values `0x00`, `0x07 .. 0x7f`, and `0x88 .. 0xff` are reserved.
+Message values `0x00`, `0x07`, `0x09 .. 0x7f`, and `0x88 .. 0xff` are
+reserved. Value `0x07` is used by one game (stag_hunt) for a private identity
+packet; the shared clients skip its two payload bytes.
 
 ## Rendering Model
 
@@ -380,6 +431,9 @@ A receiver should close the connection on malformed messages, including:
 - Sprite decompressed pixel payloads that do not match `Width * Height * 4`.
   A pixel-free definition with compressed length `0` carries no payload to
   check.
+- Encoded sprite payloads with an unknown encoding, a zlib stream that fails
+  to decode, a palette index outside the palette, or a palette swap whose
+  source sprite is unknown, not indexed, or a different size.
 - Pixel-free sprite definitions sent to a client that did not request
   Sprites Off.
 - Sprite labels whose byte count does not match `Label length`.
diff --git a/src/bitworld/client.nim b/src/bitworld/client.nim
index edcc316..e34ce0d 100644
--- a/src/bitworld/client.nim
+++ b/src/bitworld/client.nim
@@ -18,9 +18,11 @@ const
   RewardClientHtmlRoute* = "/client/rewards.html"
   SnappyClientRoute* = "/snappyjs.min.js"
   QrcodeClientRoute* = "/qrcode.min.js"
+  SpriteCodecClientRoute* = "/spritecodec.js"
   ReplayClientRoute* = "/client/replay"
   SnappyClientPath* = "/client/snappyjs.min.js"
   QrcodeClientPath* = "/client/qrcode.min.js"
+  SpriteCodecClientPath* = "/client/spritecodec.js"
   CoworldPlayerClientRoute* = "/clients/player"
   CoworldGlobalClientRoute* = "/clients/global"
   CoworldReplayClientRoute* = "/clients/replay"
@@ -28,18 +30,21 @@ const
   CoworldRewardClientRoute* = "/clients/rewards"
   CoworldSnappyClientRoute* = "/clients/snappyjs.min.js"
   CoworldQrcodeClientRoute* = "/clients/qrcode.min.js"
+  CoworldSpriteCodecClientRoute* = "/clients/spritecodec.js"
   PlayerClientHtml* = "player_client.html"
   GlobalClientHtml* = "global_client.html"
   AdminClientHtml* = "admin_client.html"
   RewardClientHtml* = "reward_client.html"
   SnappyClientJs* = "snappyjs.min.js"
   QrcodeClientJs* = "qrcode.min.js"
+  SpriteCodecClientJs* = "spritecodec.js"
   EmbeddedPlayerClientHtml* = staticRead("../../client/player_client.html")
   EmbeddedGlobalClientHtml* = staticRead("../../client/global_client.html")
   EmbeddedAdminClientHtml* = staticRead("../../client/admin_client.html")
   EmbeddedRewardClientHtml* = staticRead("../../client/reward_client.html")
   EmbeddedSnappyClientJs* = staticRead("../../client/snappyjs.min.js")
   EmbeddedQrcodeClientJs* = staticRead("../../client/qrcode.min.js")
+  EmbeddedSpriteCodecClientJs* = staticRead("../../client/spritecodec.js")
 
 proc repoDir*(): string =
   ## Returns the Bit World repository directory.
@@ -86,6 +91,8 @@ proc clientRoute*(route: string, playerRoute = PlayerClientRoute): string =
     SnappyClientRoute
   of QrcodeClientPath, CoworldQrcodeClientRoute:
     QrcodeClientRoute
+  of SpriteCodecClientPath, CoworldSpriteCodecClientRoute:
+    SpriteCodecClientRoute
   else:
     route
 
@@ -114,6 +121,8 @@ proc clientStaticPath*(route: string, playerRoute = PlayerClientRoute): string =
     clientDir() / SnappyClientJs
   of QrcodeClientRoute:
     clientDir() / QrcodeClientJs
+  of SpriteCodecClientRoute:
+    clientDir() / SpriteCodecClientJs
   else:
     clientHtmlPath(route, playerRoute)
 
@@ -123,7 +132,7 @@ proc clientStaticContentType*(
 ): string =
   ## Returns the content type for a served static client file.
   case clientRoute(route, playerRoute)
-  of SnappyClientRoute, QrcodeClientRoute:
+  of SnappyClientRoute, QrcodeClientRoute, SpriteCodecClientRoute:
     "application/javascript; charset=utf-8"
   else:
     "text/html; charset=utf-8"
@@ -146,6 +155,8 @@ proc clientStaticBody*(
     EmbeddedSnappyClientJs
   of QrcodeClientRoute:
     EmbeddedQrcodeClientJs
+  of SpriteCodecClientRoute:
+    EmbeddedSpriteCodecClientJs
   else:
     ""
 
diff --git a/src/bitworld/spriteprotocol.nim b/src/bitworld/spriteprotocol.nim
index 65fbc89..176f7fa 100644
--- a/src/bitworld/spriteprotocol.nim
+++ b/src/bitworld/spriteprotocol.nim
@@ -1,6 +1,8 @@
 import
+  std/tables,
   pixie,
   supersnappy,
+  zippy,
   flatty/binny
 
 const
@@ -30,6 +32,25 @@ const
   SpriteMessageClearObjects* = 0x04'u8
   SpriteMessageViewport* = 0x05'u8
   SpriteMessageLayer* = 0x06'u8
+  SpriteMessageEncodedSprite* = 0x08'u8
+    ## Define Encoded Sprite: like Define Sprite, plus one encoding byte
+    ## that says how the pixel payload is packed. 0x07 is skipped
+    ## because the stag_hunt game already uses it for identity packets.
+  SpriteEncodingRgbaSnappy* = 0x00'u8
+    ## Snappy stream of raw RGBA. The legacy Define Sprite payload.
+  SpriteEncodingRgbaDeflate* = 0x01'u8
+    ## Zlib stream of raw RGBA.
+  SpriteEncodingIndexed* = 0x02'u8
+    ## u8 palette count minus one, RGBA palette entries, then a zlib
+    ## stream of one palette index byte per pixel.
+  SpriteEncodingPaletteSwap* = 0x03'u8
+    ## u16 source sprite id, u8 palette count minus one, RGBA palette
+    ## entries. Reuses the index plane of an indexed sprite the client
+    ## already holds; only the palette is new.
+  SpriteEncodingAuto* = 0xff'u8
+    ## Encoder-only: indexed when the sprite has at most 256 colors,
+    ## otherwise RGBA deflate. Never written to the wire.
+  SpriteMaxPaletteColors* = 256
   SpriteClientChat* = 0x81'u8
   SpriteClientMouseMove* = 0x82'u8
   SpriteClientMouseButton* = 0x83'u8
@@ -68,9 +89,23 @@ type
 
   SpritePacketSpriteDef* = object
     id*, width*, height*: int
+    encoding*: uint8
+      ## One of the SpriteEncoding values. A legacy Define Sprite
+      ## message parses as SpriteEncodingRgbaSnappy.
     compressedPixels*: seq[uint8]
+      ## The encoded pixel payload as it appeared on the wire. Empty for
+      ## a pixel-free definition.
     label*: string
 
+  DecodedSprite* = object
+    ## One sprite definition decoded to straight RGBA. Indexed and
+    ## palette-swap sprites also keep their index plane and palette so
+    ## a later palette swap can reuse them.
+    width*, height*: int
+    pixels*: seq[uint8]
+    indices*: seq[uint8]
+    palette*: seq[uint8]
+
   SpritePacketObject* = object
     id*, x*, y*, z*, layer*, spriteId*: int
 
@@ -325,6 +360,276 @@ proc addSprite*(
   for ch in label:
     packet.addU8(uint8(ord(ch)))
 
+proc packedColor(pixels: openArray[uint8], offset: int): uint32 =
+  ## Packs one RGBA pixel into a table key.
+  uint32(pixels[offset]) or
+    (uint32(pixels[offset + 1]) shl 8) or
+    (uint32(pixels[offset + 2]) shl 16) or
+    (uint32(pixels[offset + 3]) shl 24)
+
+proc indexPixels*(
+  pixels: openArray[uint8],
+  palette: var seq[uint8],
+  indices: var seq[uint8]
+): bool =
+  ## Splits straight RGBA pixels into a palette and an index plane. The
+  ## palette lists colors in first-seen scanline order, so two sprites
+  ## with the same layout share the same index plane. Returns false
+  ## when the sprite has more than 256 colors.
+  palette.setLen(0)
+  indices.setLen(pixels.len div 4)
+  var lookup = initTable[uint32, uint8]()
+  var offset = 0
+  for i in 0 ..< indices.len:
+    let key = pixels.packedColor(offset)
+    var index: uint8
+    if lookup.hasKey(key):
+      index = lookup[key]
+    else:
+      if lookup.len >= SpriteMaxPaletteColors:
+        return false
+      index = uint8(lookup.len)
+      lookup[key] = index
+      for channel in 0 .. 3:
+        palette.add(pixels[offset + channel])
+    indices[i] = index
+    offset += 4
+  true
+
+proc encodeIndexedPayload*(pixels: openArray[uint8]): seq[uint8] =
+  ## Builds an indexed sprite payload, or an empty seq when the sprite
+  ## has more than 256 colors.
+  var palette, indices: seq[uint8]
+  if pixels.len == 0 or not pixels.indexPixels(palette, indices):
+    return
+  result.add(uint8(palette.len div 4 - 1))
+  result.add(palette)
+  result.add(zippy.compress(indices, dataFormat = dfZlib))
+
+proc encodeRgbaDeflatePayload*(pixels: openArray[uint8]): seq[uint8] =
+  ## Builds a zlib stream of raw RGBA pixels.
+  var raw = newSeq[uint8](pixels.len)
+  for i in 0 ..< pixels.len:
+    raw[i] = pixels[i]
+  zippy.compress(raw, dataFormat = dfZlib)
+
+proc encodeRgbaSnappyPayload*(pixels: openArray[uint8]): seq[uint8] =
+  ## Builds a Snappy stream of raw RGBA pixels, the legacy payload.
+  var raw = newSeq[uint8](pixels.len)
+  for i in 0 ..< pixels.len:
+    raw[i] = pixels[i]
+  supersnappy.compress(raw)
+
+proc encodePaletteSwapPayload*(
+  sourceSpriteId: int,
+  sourcePixels, pixels: openArray[uint8]
+): seq[uint8] =
+  ## Builds a palette-swap payload when `pixels` recolors `sourcePixels`
+  ## one color at a time: every pixel that has color A in the source has
+  ## the same color B here. Returns an empty seq when the sizes differ,
+  ## the source has more than 256 colors, or the recoloring is not
+  ## consistent. The source must have been sent as an indexed sprite.
+  if sourcePixels.len == 0 or sourcePixels.len != pixels.len:
+    return
+  var sourcePalette, sourceIndices: seq[uint8]
+  if not sourcePixels.indexPixels(sourcePalette, sourceIndices):
+    return
+  let count = sourcePalette.len div 4
+  var
+    palette = newSeq[uint8](count * 4)
+    seen = newSeq[bool](count)
+  for i, index in sourceIndices:
+    let
+      slot = int(index) * 4
+      offset = i * 4
+    if seen[index]:
+      for channel in 0 .. 3:
+        if palette[slot + channel] != pixels[offset + channel]:
+          return @[]
+    else:
+      seen[index] = true
+      for channel in 0 .. 3:
+        palette[slot + channel] = pixels[offset + channel]
+  result.addU16(sourceSpriteId)
+  result.add(uint8(count - 1))
+  result.add(palette)
+
+proc addEncodedSpritePayload*(
+  packet: var seq[uint8],
+  spriteId, width, height: int,
+  encoding: uint8,
+  payload: openArray[uint8],
+  label = ""
+) =
+  ## Appends one Define Encoded Sprite message with a prebuilt payload.
+  ## An empty payload is a pixel-free definition.
+  packet.addU8(SpriteMessageEncodedSprite)
+  packet.addU16(spriteId)
+  packet.addU16(width)
+  packet.addU16(height)
+  packet.addU8(encoding)
+  packet.addU32(payload.len)
+  for byte in payload:
+    packet.addU8(byte)
+  packet.addU16(label.len)
+  for ch in label:
+    packet.addU8(uint8(ord(ch)))
+
+proc addEncodedSprite*(
+  packet: var seq[uint8],
+  spriteId, width, height: int,
+  pixels: openArray[uint8],
+  label = "",
+  encoding = SpriteEncodingAuto
+): uint8 {.discardable.} =
+  ## Appends one Define Encoded Sprite message for straight RGBA pixels
+  ## and returns the encoding used. Auto picks indexed for sprites with
+  ## at most 256 colors and RGBA deflate for everything else.
+  var payload: seq[uint8]
+  result = encoding
+  case encoding
+  of SpriteEncodingAuto:
+    payload = pixels.encodeIndexedPayload()
+    result = SpriteEncodingIndexed
+    if payload.len == 0:
+      payload = pixels.encodeRgbaDeflatePayload()
+      result = SpriteEncodingRgbaDeflate
+  of SpriteEncodingIndexed:
+    payload = pixels.encodeIndexedPayload()
+    if payload.len == 0:
+      raise newException(
+        SpriteProtocolError,
+        "indexed sprite needs 1 .. 256 colors"
+      )
+  of SpriteEncodingRgbaDeflate:
+    payload = pixels.encodeRgbaDeflatePayload()
+  of SpriteEncodingRgbaSnappy:
+    payload = pixels.encodeRgbaSnappyPayload()
+  else:
+    raise newException(
+      SpriteProtocolError,
+      "unknown sprite encoding " & $encoding
+    )
+  packet.addEncodedSpritePayload(spriteId, width, height, result, payload, label)
+
+proc addPaletteSwapSprite*(
+  packet: var seq[uint8],
+  spriteId, sourceSpriteId, width, height: int,
+  sourcePixels, pixels: openArray[uint8],
+  label = ""
+): bool {.discardable.} =
+  ## Appends sprite `spriteId` as a palette swap of the indexed sprite
+  ## `sourceSpriteId` when `pixels` is a per-color recoloring of
+  ## `sourcePixels`, and as an ordinary auto-encoded sprite otherwise.
+  ## Returns true when the swap was used. The source sprite must already
+  ## have been defined with the indexed encoding in the same packet
+  ## stream, or the client has no index plane to reuse.
+  let payload = encodePaletteSwapPayload(sourceSpriteId, sourcePixels, pixels)
+  if payload.len == 0:
+    packet.addEncodedSprite(spriteId, width, height, pixels, label)
+    return false
+  packet.addEncodedSpritePayload(
+    spriteId, width, height, SpriteEncodingPaletteSwap, payload, label
+  )
+  true
+
+proc paletteSwapSourceId*(def: SpritePacketSpriteDef): int =
+  ## Returns the source sprite id a palette-swap definition reuses, or
+  ## -1 for every other definition.
+  if def.encoding != SpriteEncodingPaletteSwap or
+      def.compressedPixels.len < 3:
+    return -1
+  def.compressedPixels.readU16(0)
+
+proc expandIndices(
+  indices, palette: openArray[uint8],
+  width, height: int
+): seq[uint8] =
+  ## Expands one index plane through a palette into straight RGBA.
+  if indices.len != width * height:
+    raise newException(
+      SpriteProtocolError,
+      "sprite index plane does not match width * height"
+    )
+  let count = palette.len div 4
+  result = newSeq[uint8](indices.len * 4)
+  for i, index in indices:
+    if int(index) >= count:
+      raise newException(SpriteProtocolError, "sprite palette index out of range")
+    let
+      slot = int(index) * 4
+      offset = i * 4
+    result[offset] = palette[slot]
+    result[offset + 1] = palette[slot + 1]
+    result[offset + 2] = palette[slot + 2]
+    result[offset + 3] = palette[slot + 3]
+
+proc decodeSprite*(
+  def: SpritePacketSpriteDef,
+  source = DecodedSprite()
+): DecodedSprite =
+  ## Decodes one sprite definition to straight RGBA. `source` is the
+  ## already decoded sprite named by paletteSwapSourceId for a
+  ## palette-swap definition and is ignored by the other encodings. A
+  ## pixel-free definition decodes with empty pixels. Raises
+  ## SpriteProtocolError for payloads that do not decode to exactly
+  ## width * height * 4 bytes.
+  result.width = def.width
+  result.height = def.height
+  let payload = def.compressedPixels
+  if payload.len == 0:
+    return
+  case def.encoding
+  of SpriteEncodingRgbaSnappy:
+    try:
+      result.pixels = supersnappy.uncompress(payload)
+    except SnappyError as e:
+      raise newException(SpriteProtocolError, "bad snappy sprite: " & e.msg)
+  of SpriteEncodingRgbaDeflate:
+    try:
+      result.pixels = zippy.uncompress(payload, dfZlib)
+    except ZippyError as e:
+      raise newException(SpriteProtocolError, "bad deflate sprite: " & e.msg)
+  of SpriteEncodingIndexed:
+    let count = int(payload[0]) + 1
+    if payload.len < 1 + count * 4:
+      raise newException(SpriteProtocolError, "truncated sprite palette")
+    result.palette = payload[1 ..< 1 + count * 4]
+    try:
+      result.indices = zippy.uncompress(payload[1 + count * 4 .. ^1], dfZlib)
+    except ZippyError as e:
+      raise newException(SpriteProtocolError, "bad indexed sprite: " & e.msg)
+    result.pixels = expandIndices(
+      result.indices, result.palette, def.width, def.height
+    )
+  of SpriteEncodingPaletteSwap:
+    if payload.len < 3:
+      raise newException(SpriteProtocolError, "truncated palette swap")
+    let count = int(payload[2]) + 1
+    if payload.len < 3 + count * 4:
+      raise newException(SpriteProtocolError, "truncated sprite palette")
+    if source.indices.len != def.width * def.height:
+      raise newException(
+        SpriteProtocolError,
+        "palette swap source " & $def.paletteSwapSourceId() &
+          " is not an indexed sprite of the same size"
+      )
+    result.palette = payload[3 ..< 3 + count * 4]
+    result.indices = source.indices
+    result.pixels = expandIndices(
+      result.indices, result.palette, def.width, def.height
+    )
+  else:
+    raise newException(
+      SpriteProtocolError,
+      "unknown sprite encoding " & $def.encoding
+    )
+  if result.pixels.len != def.width * def.height * 4:
+    raise newException(
+      SpriteProtocolError,
+      "sprite pixels do not match width * height * 4"
+    )
+
 proc addObject*(
   packet: var seq[uint8],
   objectId, x, y, z, layer, spriteId: int
@@ -375,6 +680,31 @@ proc parseSpritePacket*(packet: openArray[uint8]): seq[SpritePacketMessage] =
       message.sprite.label = bytes.readStr(offset, labelLen)
       offset += labelLen
       result.add(message)
+    of SpriteMessageEncodedSprite:
+      bytes.checkRead(offset, 11)
+      var message = SpritePacketMessage(kind: spkSprite)
+      message.sprite.id = bytes.readU16(offset)
+      message.sprite.width = bytes.readU16(offset + 2)
+      message.sprite.height = bytes.readU16(offset + 4)
+      message.sprite.encoding = bytes.readU8(offset + 6)
+      let payloadLen = bytes.readU32(offset + 7)
+      offset += 11
+      if message.sprite.encoding > SpriteEncodingPaletteSwap:
+        raise newException(
+          SpriteProtocolError,
+          "unknown sprite encoding " & $message.sprite.encoding
+        )
+      bytes.checkRead(offset, payloadLen)
+      message.sprite.compressedPixels = newSeq[uint8](payloadLen)
+      for i in 0 ..< payloadLen:
+        message.sprite.compressedPixels[i] = bytes[offset + i].uint8
+      offset += payloadLen
+      let labelLen = bytes.readU16(offset)
+      offset += 2
+      bytes.checkRead(offset, labelLen)
+      message.sprite.label = bytes.readStr(offset, labelLen)
+      offset += labelLen
+      result.add(message)
     of SpriteMessageObject:
       bytes.checkRead(offset, 11)
       var message = SpritePacketMessage(kind: spkObject)
@@ -457,6 +787,16 @@ proc spriteMessageBytes*(packet: openArray[uint8], offset: int): int =
       return packet.len - offset
     let labelLen = packet.readU16(labelOffset)
     min(packet.len - offset, 13 + compressedLen + labelLen)
+  of SpriteMessageEncodedSprite:
+    if offset + 12 > packet.len:
+      return packet.len - offset
+    let
+      payloadLen = packet.readU32(offset + 8)
+      labelOffset = offset + 12 + payloadLen
+    if labelOffset + 2 > packet.len:
+      return packet.len - offset
+    let labelLen = packet.readU16(labelOffset)
+    min(packet.len - offset, 14 + payloadLen + labelLen)
   of SpriteMessageObject:
     min(packet.len - offset, 12)
   of SpriteMessageDeleteObject:
diff --git a/tests/spritecodec_check.js b/tests/spritecodec_check.js
new file mode 100644
index 0000000..86a05b5
--- /dev/null
+++ b/tests/spritecodec_check.js
@@ -0,0 +1,91 @@
+// Decodes a sprite packet with the browser codec (client/spritecodec.js
+// plus client/snappyjs.min.js) under node and compares every sprite
+// against the RGBA bytes the Nim encoder started from.
+//
+//   node tests/spritecodec_check.js packet.bin expected.bin
+//
+// expected.bin holds, per sprite in packet order: u16 sprite id,
+// u32 pixel byte count, then that many RGBA bytes.
+"use strict";
+const fs=require("fs");
+const path=require("path");
+const clientDir=path.join(__dirname,"..","client");
+// snappyjs.min.js registers itself on `window`; give node one.
+if(typeof globalThis.window==="undefined")globalThis.window=globalThis;
+require(path.join(clientDir,"snappyjs.min.js"));
+require(path.join(clientDir,"spritecodec.js"));
+const SpriteCodec=globalThis.SpriteCodec;
+if(!globalThis.SnappyJS)throw new Error("snappyjs did not register on the global object");
+
+const packet=new Uint8Array(fs.readFileSync(process.argv[2]));
+const expected=new Uint8Array(fs.readFileSync(process.argv[3]));
+const textDecoder=new TextDecoder("utf-8");
+
+function readU16(bytes,offset){return bytes[offset]|(bytes[offset+1]<<8)}
+function readU32(bytes,offset){return (bytes[offset]|(bytes[offset+1]<<8)|(bytes[offset+2]<<16)|(bytes[offset+3]*0x1000000))>>>0}
+
+const sprites=new Map();
+const order=[];
+let offset=0;
+while(offset<packet.length){
+  const type=packet[offset++];
+  if(type===0x01){
+    const id=readU16(packet,offset);
+    const width=readU16(packet,offset+2);
+    const height=readU16(packet,offset+4);
+    const length=readU32(packet,offset+6);
+    offset+=10;
+    const payload=packet.subarray(offset,offset+length);
+    offset+=length;
+    const labelLength=readU16(packet,offset);
+    offset+=2+labelLength;
+    const decoded=SpriteCodec.decodeSprite(0x00,payload,width,height,null);
+    sprites.set(id,{width,height,pixels:decoded.pixels,indices:null,palette:null});
+    order.push(id);
+  }else if(type===0x08){
+    const encoded=SpriteCodec.readEncodedSprite(packet,offset,textDecoder);
+    if(!encoded)throw new Error("truncated encoded sprite at "+offset);
+    const decoded=SpriteCodec.decodeSprite(
+      encoded.encoding,encoded.payload,encoded.width,encoded.height,
+      sourceId=>sprites.get(sourceId)
+    );
+    sprites.set(encoded.id,{
+      width:encoded.width,height:encoded.height,
+      pixels:decoded.pixels,indices:decoded.indices,palette:decoded.palette,
+      label:encoded.label,encoding:encoded.encoding
+    });
+    order.push(encoded.id);
+    offset=encoded.offset;
+  }else{
+    throw new Error("unexpected message type "+type+" at "+(offset-1));
+  }
+}
+
+let cursor=0,checked=0,failed=0;
+for(const id of order){
+  const expectedId=readU16(expected,cursor);
+  const length=readU32(expected,cursor+2);
+  cursor+=6;
+  const want=expected.subarray(cursor,cursor+length);
+  cursor+=length;
+  const sprite=sprites.get(id);
+  let ok=expectedId===id&&sprite&&sprite.pixels.length===length;
+  if(ok){
+    for(let i=0;i<length;i++){
+      if(sprite.pixels[i]!==want[i]){ok=false;break}
+    }
+  }
+  checked++;
+  if(!ok){
+    failed++;
+    console.log("sprite "+id+" MISMATCH ("+(sprite?sprite.width+"x"+sprite.height+" encoding "+sprite.encoding:"missing")+")");
+  }else{
+    console.log("sprite "+id+" ok "+sprite.width+"x"+sprite.height+" encoding "+sprite.encoding+" "+(sprite.label||""));
+  }
+}
+if(cursor!==expected.length){
+  console.log("expected data has trailing bytes");
+  failed++;
+}
+console.log(checked+" sprites checked, "+failed+" failed");
+process.exit(failed===0?0:1);
diff --git a/tests/test_client.nim b/tests/test_client.nim
index e2fbc65..74a50d7 100644
--- a/tests/test_client.nim
+++ b/tests/test_client.nim
@@ -15,6 +15,8 @@ proc testCanonicalCoworldClientRoutes() =
   doAssert coworldClientStaticRoute(CoworldRewardClientRoute) == RewardClientRoute
   doAssert coworldClientStaticRoute(CoworldSnappyClientRoute) == SnappyClientRoute
   doAssert coworldClientStaticRoute(CoworldQrcodeClientRoute) == QrcodeClientRoute
+  doAssert coworldClientStaticRoute(CoworldSpriteCodecClientRoute) == SpriteCodecClientRoute
+  doAssert coworldClientStaticRoute(SpriteCodecClientPath) == SpriteCodecClientRoute
   doAssert coworldClientStaticRoute(ReplayClientRoute) == GlobalClientRoute
   doAssert coworldClientStaticRoute("/client/replay.html") == "/client/replay.html"
   doAssert clientStaticPath("/client/replay.html") == ""
@@ -30,9 +32,11 @@ proc testClientStaticPaths() =
   assertEndsWith(clientStaticPath(CoworldRewardClientRoute), "client" / RewardClientHtml)
   assertEndsWith(clientStaticPath(CoworldSnappyClientRoute), "client" / SnappyClientJs)
   assertEndsWith(clientStaticPath(CoworldQrcodeClientRoute), "client" / QrcodeClientJs)
+  assertEndsWith(clientStaticPath(CoworldSpriteCodecClientRoute), "client" / SpriteCodecClientJs)
   doAssert clientStaticContentType(CoworldReplayClientRoute) == "text/html; charset=utf-8"
   doAssert clientStaticContentType(CoworldSnappyClientRoute) == "application/javascript; charset=utf-8"
   doAssert clientStaticContentType(CoworldQrcodeClientRoute) == "application/javascript; charset=utf-8"
+  doAssert clientStaticContentType(CoworldSpriteCodecClientRoute) == "application/javascript; charset=utf-8"
 
 proc testReplayClientPreservesUri() =
   ## Tests that the shared replay client forwards Coworld replay URIs.
@@ -77,10 +81,25 @@ proc testPlayerClientSpeaksSpriteProtocol() =
   doAssert "Math.max(.000001,Math.min" in html
   doAssert "function layerScreenPos" in html
   doAssert "layerDrawRank" in html
-  for messageType in ["0x01", "0x02", "0x03", "0x04", "0x05", "0x06", "0x07"]:
+  for messageType in ["0x01", "0x02", "0x03", "0x04", "0x05", "0x06", "0x07", "0x08"]:
     doAssert ("type===" & messageType) in html,
       "missing sprite protocol parser case " & messageType
 
+proc testClientsDecodeEncodedSprites() =
+  ## Tests that both browser clients load the shared sprite codec and
+  ## parse Define Encoded Sprite messages with it.
+  echo "Testing client encoded sprite support"
+  for route in [CoworldReplayClientRoute, CoworldPlayerClientRoute]:
+    let html = readClientHtml(route)
+    doAssert "<script src=\"spritecodec.js\"></script>" in html
+    doAssert "type===0x08" in html
+    doAssert "SpriteCodec.readEncodedSprite(bytes,offset,textDecoder)" in html
+    doAssert "SpriteCodec.decodeSprite(" in html
+  let codec = clientStaticBody(SpriteCodecClientRoute)
+  doAssert "root.SpriteCodec={inflate,expandIndices,decodeSprite,readEncodedSprite}" in codec
+  doAssert clientStaticBody(CoworldSpriteCodecClientRoute) == codec
+  doAssert clientStaticBody(SpriteCodecClientPath) == codec
+
 proc testGlobalClientFitsIframeView() =
   ## Tests that the hosted viewer sizes UI to the canvas, not the page.
   echo "Testing global client iframe view size"
@@ -111,6 +130,7 @@ testReplayClientPreservesUri()
 testGlobalClientFullScreenLayers()
 testGlobalClientWheelZoomTargetsMap()
 testPlayerClientSpeaksSpriteProtocol()
+testClientsDecodeEncodedSprites()
 testGlobalClientFitsIframeView()
 testEmbeddedClientBodies()
 echo "All tests passed"
diff --git a/tests/test_spritecodec_js.nim b/tests/test_spritecodec_js.nim
new file mode 100644
index 0000000..bdc7d7f
--- /dev/null
+++ b/tests/test_spritecodec_js.nim
@@ -0,0 +1,114 @@
+## Cross-checks the browser decoder (client/spritecodec.js) against the
+## Nim encoder: builds a packet that exercises every encoding, writes
+## the source RGBA next to it, and has node decode the packet with the
+## same JavaScript the HTML clients load. Skips when node is missing.
+
+import
+  std/[os, osproc, random, strutils],
+  bitworld/spriteprotocol
+
+proc pixels(width, height, colors: int, seed: int): seq[uint8] =
+  ## Deterministic sprite with the given number of RGBA values.
+  var rng = initRand(seed)
+  result = newSeq[uint8](width * height * 4)
+  for i in 0 ..< width * height:
+    let
+      color = rng.rand(colors - 1)
+      offset = i * 4
+    result[offset] = uint8(color * 7 mod 256)
+    result[offset + 1] = uint8(color * 13 mod 256)
+    result[offset + 2] = uint8(color * 29 mod 256)
+    result[offset + 3] = uint8(if color == 0: 0 elif color mod 3 == 0: 128 else: 255)
+
+proc bands(width, height, colors: int): seq[uint8] =
+  ## Long horizontal runs of few colors: highly compressible, so the
+  ## deflate stream has long matches.
+  result = newSeq[uint8](width * height * 4)
+  for y in 0 ..< height:
+    for x in 0 ..< width:
+      let
+        color = (x div 16 + y div 8) mod colors
+        offset = (y * width + x) * 4
+      result[offset] = uint8(color * 40)
+      result[offset + 1] = uint8(255 - color * 30)
+      result[offset + 2] = uint8(color * 90)
+      result[offset + 3] = 255
+
+proc noise(width, height: int, seed: int): seq[uint8] =
+  ## Incompressible RGBA, which makes deflate fall back to stored blocks.
+  var rng = initRand(seed)
+  result = newSeq[uint8](width * height * 4)
+  for i in 0 ..< result.len:
+    result[i] = uint8(rng.rand(255))
+
+proc recolor(source: seq[uint8]): seq[uint8] =
+  result = source
+  for i in 0 ..< source.len div 4:
+    let offset = i * 4
+    result[offset] = source[offset] xor 0xa5
+    result[offset + 1] = source[offset + 1] div 3
+    result[offset + 2] = 255'u8 - source[offset + 2]
+
+proc main() =
+  echo "Testing browser sprite codec against the Nim encoder"
+  let node = findExe("node")
+  if node.len == 0:
+    echo "node not found, skipping browser codec check"
+    return
+
+  var packet, expected: seq[uint8]
+  proc expect(id: int, rgba: seq[uint8]) =
+    expected.addU16(id)
+    expected.addU32(rgba.len)
+    expected.add(rgba)
+
+  let
+    small = pixels(37, 23, 16, 1)
+    full = pixels(40, 30, 256, 2)
+    flat = bands(300, 200, 6)
+    random = noise(64, 48, 3)
+    tinted = recolor(small)
+    tintedFlat = recolor(flat)
+    tiny = pixels(1, 1, 2, 4)
+
+  packet.addEncodedSprite(1, 37, 23, small, "indexed")
+  expect(1, small)
+  packet.addEncodedSprite(2, 40, 30, full, "full palette")
+  expect(2, full)
+  packet.addEncodedSprite(3, 300, 200, flat, "bands")
+  expect(3, flat)
+  packet.addEncodedSprite(4, 64, 48, random, "noise deflate")
+  expect(4, random)
+  packet.addEncodedSprite(5, 64, 48, random, "noise snappy", SpriteEncodingRgbaSnappy)
+  expect(5, random)
+  packet.addEncodedSprite(6, 300, 200, flat, "bands deflate", SpriteEncodingRgbaDeflate)
+  expect(6, flat)
+  doAssert packet.addPaletteSwapSprite(7, 1, 37, 23, small, tinted, "tint")
+  expect(7, tinted)
+  doAssert packet.addPaletteSwapSprite(8, 3, 300, 200, flat, tintedFlat, "bands tint")
+  expect(8, tintedFlat)
+  doAssert packet.addPaletteSwapSprite(9, 8, 300, 200, tintedFlat, flat, "bands back")
+  expect(9, flat)
+  packet.addSprite(10, 37, 23, small, "legacy")
+  expect(10, small)
+  packet.addEncodedSprite(11, 1, 1, tiny, "tiny")
+  expect(11, tiny)
+
+  let dir = getTempDir() / "bitworld_spritecodec_check"
+  createDir(dir)
+  let
+    packetPath = dir / "packet.bin"
+    expectedPath = dir / "expected.bin"
+  writeFile(packetPath, cast[string](packet))
+  writeFile(expectedPath, cast[string](expected))
+
+  let script = currentSourcePath().parentDir() / "spritecodec_check.js"
+  let (output, code) = execCmdEx(
+    quoteShellCommand([node, script, packetPath, expectedPath])
+  )
+  echo output.strip()
+  doAssert code == 0, "browser codec check failed"
+  doAssert "11 sprites checked, 0 failed" in output
+  echo "All tests passed"
+
+main()
diff --git a/tests/test_spriteencoding.nim b/tests/test_spriteencoding.nim
new file mode 100644
index 0000000..c1b1bed
--- /dev/null
+++ b/tests/test_spriteencoding.nim
@@ -0,0 +1,242 @@
+## Round-trip tests for Define Encoded Sprite (0x08): every encoding
+## must decode to the exact RGBA bytes that went in, the legacy Define
+## Sprite message must keep working next to it, and malformed encoded
+## messages must raise.
+
+import
+  std/[random, tables],
+  bitworld/spriteprotocol,
+  supersnappy
+
+proc expectSpriteError(body: proc()) =
+  ## Asserts that a body raises SpriteProtocolError.
+  var raised = false
+  try:
+    body()
+  except SpriteProtocolError:
+    raised = true
+  doAssert raised, "expected a sprite protocol error"
+
+proc checkerPixels(width, height, colors: int, seed = 1): seq[uint8] =
+  ## Builds a deterministic sprite with the given number of distinct
+  ## RGBA values, including transparent and translucent pixels.
+  var rng = initRand(seed)
+  result = newSeq[uint8](width * height * 4)
+  for i in 0 ..< width * height:
+    let
+      color = rng.rand(colors - 1)
+      offset = i * 4
+    result[offset] = uint8(color * 7 mod 256)
+    result[offset + 1] = uint8(color * 13 mod 256)
+    result[offset + 2] = uint8(color * 29 mod 256)
+    result[offset + 3] = uint8(if color == 0: 0 elif color mod 3 == 0: 128 else: 255)
+
+proc allColorsPixels(): seq[uint8] =
+  ## A 16x16 sprite that uses exactly 256 distinct RGBA values.
+  result = newSeq[uint8](256 * 4)
+  for i in 0 ..< 256:
+    result[i * 4] = uint8(i)
+    result[i * 4 + 1] = uint8(255 - i)
+    result[i * 4 + 2] = uint8(i * 3 mod 256)
+    result[i * 4 + 3] = uint8(if i == 0: 0 else: 255)
+
+proc noisePixels(width, height: int, seed = 2): seq[uint8] =
+  ## Builds an incompressible RGBA sprite with far more than 256 colors.
+  var rng = initRand(seed)
+  result = newSeq[uint8](width * height * 4)
+  for i in 0 ..< result.len:
+    result[i] = uint8(rng.rand(255))
+
+proc recolor(pixels: seq[uint8]): seq[uint8] =
+  ## Recolors pixels one color at a time, the way a tint does.
+  result = pixels
+  for i in 0 ..< pixels.len div 4:
+    let offset = i * 4
+    result[offset] = 255'u8 - pixels[offset]
+    result[offset + 1] = pixels[offset + 1] div 2
+    result[offset + 2] = pixels[offset + 2] xor 0x55
+
+proc decodeAll(packet: seq[uint8]): OrderedTable[int, DecodedSprite] =
+  ## Decodes every sprite definition in a packet in order, resolving
+  ## palette swaps against earlier definitions.
+  result = initOrderedTable[int, DecodedSprite]()
+  for message in packet.parseSpritePacket():
+    if message.kind != spkSprite:
+      continue
+    var source: DecodedSprite
+    let sourceId = message.sprite.paletteSwapSourceId()
+    if sourceId >= 0 and result.hasKey(sourceId):
+      source = result[sourceId]
+    result[message.sprite.id] = message.sprite.decodeSprite(source)
+
+proc testEncodings() =
+  echo "Testing encoded sprite round trips"
+  let
+    indexed = checkerPixels(37, 23, 16)
+    full = allColorsPixels()
+    noise = noisePixels(64, 48)
+    tinted = recolor(indexed)
+  var packet: seq[uint8]
+  doAssert packet.addEncodedSprite(1, 37, 23, indexed, "indexed") ==
+    SpriteEncodingIndexed
+  doAssert packet.addEncodedSprite(2, 16, 16, full, "full palette") ==
+    SpriteEncodingIndexed
+  doAssert packet.addEncodedSprite(3, 64, 48, noise, "noise") ==
+    SpriteEncodingRgbaDeflate
+  doAssert packet.addEncodedSprite(
+    4, 64, 48, noise, "noise snappy", SpriteEncodingRgbaSnappy
+  ) == SpriteEncodingRgbaSnappy
+  doAssert packet.addEncodedSprite(
+    5, 37, 23, indexed, "indexed deflate", SpriteEncodingRgbaDeflate
+  ) == SpriteEncodingRgbaDeflate
+  doAssert packet.addPaletteSwapSprite(6, 1, 37, 23, indexed, tinted, "tint")
+  packet.addSprite(7, 37, 23, indexed, "legacy")
+  packet.addEncodedSpritePayload(8, 37, 23, SpriteEncodingIndexed, [], "ghost")
+
+  let decoded = packet.decodeAll()
+  doAssert decoded.len == 8
+  doAssert decoded[1].pixels == indexed
+  doAssert decoded[1].indices.len == 37 * 23
+  doAssert decoded[1].palette.len == 16 * 4
+  doAssert decoded[2].pixels == full
+  doAssert decoded[2].palette.len == 256 * 4
+  doAssert decoded[3].pixels == noise
+  doAssert decoded[3].indices.len == 0
+  doAssert decoded[4].pixels == noise
+  doAssert decoded[5].pixels == indexed
+  doAssert decoded[6].pixels == tinted
+  doAssert decoded[6].indices == decoded[1].indices
+  doAssert decoded[7].pixels == indexed
+  doAssert decoded[8].pixels.len == 0
+  doAssert decoded[8].width == 37
+
+  # A palette swap of a palette swap keeps working.
+  var chained: seq[uint8]
+  chained.addEncodedSprite(1, 37, 23, indexed)
+  doAssert chained.addPaletteSwapSprite(2, 1, 37, 23, indexed, tinted)
+  doAssert chained.addPaletteSwapSprite(3, 2, 37, 23, tinted, indexed)
+  let chainDecoded = chained.decodeAll()
+  doAssert chainDecoded[3].pixels == indexed
+
+  # The messages parse with the encoding and payload preserved.
+  let messages = packet.parseSpritePacket()
+  doAssert messages[0].sprite.encoding == SpriteEncodingIndexed
+  doAssert messages[2].sprite.encoding == SpriteEncodingRgbaDeflate
+  doAssert messages[3].sprite.encoding == SpriteEncodingRgbaSnappy
+  doAssert uncompress(messages[3].sprite.compressedPixels) == noise
+  doAssert messages[5].sprite.encoding == SpriteEncodingPaletteSwap
+  doAssert messages[5].sprite.paletteSwapSourceId() == 1
+  doAssert messages[6].sprite.encoding == SpriteEncodingRgbaSnappy
+  doAssert messages[6].sprite.paletteSwapSourceId() == -1
+  doAssert messages[7].sprite.label == "ghost"
+  doAssert packet.spritePacketSpriteIds() == @[1, 2, 3, 4, 5, 6, 7, 8]
+
+  # Sizes: indexed beats snappy RGBA by a wide margin on flat art, and a
+  # palette swap is header plus palette.
+  var flat = newSeq[uint8](64 * 64 * 4)
+  for i in 0 ..< 64 * 64:
+    let color = (i mod 64 div 8 + i div 64 div 16) mod 6
+    flat[i * 4] = uint8(color * 40)
+    flat[i * 4 + 1] = uint8(200 - color * 30)
+    flat[i * 4 + 2] = uint8(color * 90 mod 256)
+    flat[i * 4 + 3] = 255
+  var legacy, encoded, swap: seq[uint8]
+  legacy.addSprite(1, 64, 64, flat)
+  encoded.addEncodedSprite(1, 64, 64, flat)
+  swap.addPaletteSwapSprite(2, 1, 64, 64, flat, recolor(flat))
+  doAssert encoded.len * 4 < legacy.len
+  doAssert swap.len == 14 + 2 + 1 + 6 * 4
+
+proc testPaletteSwapFallback() =
+  echo "Testing palette swap fallback"
+  let
+    base = checkerPixels(20, 20, 8)
+    noise = noisePixels(20, 20) # 400 pixels, more than 256 colors
+  var inconsistent = base
+  # One pixel changes color while the other pixels of that source color
+  # keep theirs, so the recoloring is not a palette swap.
+  inconsistent[0] = 1
+  inconsistent[1] = 2
+  inconsistent[2] = 3
+  inconsistent[3] = 4
+  var packet: seq[uint8]
+  packet.addEncodedSprite(1, 20, 20, base)
+  doAssert not packet.addPaletteSwapSprite(2, 1, 20, 20, base, inconsistent)
+  doAssert not packet.addPaletteSwapSprite(3, 1, 20, 20, noise, base)
+  let decoded = packet.decodeAll()
+  doAssert decoded[2].pixels == inconsistent
+  doAssert decoded[2].indices.len == 400
+  doAssert decoded[3].pixels == base
+  doAssert encodePaletteSwapPayload(1, base, base).len == 3 + 8 * 4
+  doAssert encodePaletteSwapPayload(1, noise, noise).len == 0
+  doAssert encodePaletteSwapPayload(1, base, base[0 ..< 8]).len == 0
+  doAssert encodePaletteSwapPayload(1, base, inconsistent).len == 0
+
+proc testEncodedMessageBytes() =
+  echo "Testing encoded sprite message byte sizes"
+  var packet: seq[uint8]
+  packet.addEncodedSprite(3, 4, 4, checkerPixels(4, 4, 3), "abc")
+  packet.addPaletteSwapSprite(4, 3, 4, 4, checkerPixels(4, 4, 3),
+    recolor(checkerPixels(4, 4, 3)), "")
+  packet.addObject(1, 0, 0, 0, 0, 3)
+  var offset = 0
+  let first = packet.spriteMessageBytes(0)
+  doAssert packet[0] == SpriteMessageEncodedSprite
+  doAssert first > 14 + 3
+  offset += first
+  doAssert packet[offset] == SpriteMessageEncodedSprite
+  doAssert packet.spriteMessageBytes(offset) == 14 + 3 + 3 * 4
+  offset += packet.spriteMessageBytes(offset)
+  doAssert packet.spriteMessageBytes(offset) == 12
+  offset += 12
+  doAssert offset == packet.len
+  doAssert @[SpriteMessageEncodedSprite, 1'u8, 2].spriteMessageBytes(0) == 3
+
+proc testMalformedEncodedMessages() =
+  echo "Testing malformed encoded sprites"
+  proc header(encoding: uint8, payloadLen: int): seq[uint8] =
+    result.addU8(SpriteMessageEncodedSprite)
+    result.addU16(1)
+    result.addU16(2)
+    result.addU16(2)
+    result.addU8(encoding)
+    result.addU32(payloadLen)
+
+  expectSpriteError(proc() = discard parseSpritePacket(@[SpriteMessageEncodedSprite, 1'u8]))
+  expectSpriteError(proc() = discard parseSpritePacket(header(0x04, 0) & @[0'u8, 0]))
+  expectSpriteError(proc() = discard parseSpritePacket(header(SpriteEncodingIndexed, 5) & @[1'u8]))
+  expectSpriteError(proc() = discard parseSpritePacket(header(SpriteEncodingIndexed, 0)))
+
+  # Decoding failures: bad deflate stream, index out of range, palette
+  # swap without a source, pixel count mismatch.
+  var badDeflate = header(SpriteEncodingRgbaDeflate, 3) & @[1'u8, 2, 3, 0, 0]
+  expectSpriteError(proc() = discard badDeflate.parseSpritePacket()[0].sprite.decodeSprite())
+
+  var payload: seq[uint8]
+  payload.add(0'u8) # one palette entry
+  payload.add([9'u8, 9, 9, 255])
+  payload.add(encodeRgbaDeflatePayload([0'u8, 1, 0, 0])) # index 1 is out of range
+  var outOfRange = header(SpriteEncodingIndexed, payload.len) & payload & @[0'u8, 0]
+  expectSpriteError(proc() = discard outOfRange.parseSpritePacket()[0].sprite.decodeSprite())
+
+  var swap: seq[uint8]
+  swap.addU16(7)
+  swap.add(0'u8)
+  swap.add([1'u8, 2, 3, 4])
+  var noSource = header(SpriteEncodingPaletteSwap, swap.len) & swap & @[0'u8, 0]
+  expectSpriteError(proc() = discard noSource.parseSpritePacket()[0].sprite.decodeSprite())
+
+  var wrongSize: seq[uint8]
+  wrongSize.addEncodedSprite(1, 2, 2, checkerPixels(3, 3, 2))
+  expectSpriteError(proc() = discard wrongSize.parseSpritePacket()[0].sprite.decodeSprite())
+
+  expectSpriteError(proc() =
+    var packet: seq[uint8]
+    packet.addEncodedSprite(1, 64, 48, noisePixels(64, 48), "", SpriteEncodingIndexed)
+  )
+
+testEncodings()
+testPaletteSwapFallback()
+testEncodedMessageBytes()
+testMalformedEncodedMessages()
+echo "All tests passed"