core: preserve terminal color intent

Flattening indexed and default colors into RGBA snapshots makes
palette-relative roles lose meaning before the renderer sees them.
Carry a color tag alongside RGBA through the TS, FFI, buffer, and
native renderer, and publish the active terminal palette with
epoch invalidation so the renderer can emit 39/49, keep
38;5 slots stable, and remap RGB fallback after palette changes
instead of reusing stale indices

Co-authored-by:  Trim Bresilla <trim.bresilla@gmail.com>

Author: simonklee

packages/core/src/buffer.ts

@@ -54,6 +54,10 @@ export class OptimizedBuffer {
     bg: Float32Array
     attributes: Uint32Array
   } | null = null
+  private _rawColorTags: {
+    fg: Uint16Array
+    bg: Uint16Array
+  } | null = null
   private _destroyed: boolean = false
 
   get ptr(): Pointer {
@@ -67,29 +71,47 @@ export class OptimizedBuffer {
     if (this._destroyed) throw new Error(`Buffer ${this.id} is destroyed`)
   }
 
+  private ensureRawBufferViews(): void {
+    if (this._rawBuffers !== null && this._rawColorTags !== null) {
+      return
+    }
+
+    const size = this._width * this._height
+    const charPtr = this.lib.bufferGetCharPtr(this.bufferPtr)
+    const fgPtr = this.lib.bufferGetFgPtr(this.bufferPtr)
+    const bgPtr = this.lib.bufferGetBgPtr(this.bufferPtr)
+    const fgTagPtr = this.lib.bufferGetFgTagPtr(this.bufferPtr)
+    const bgTagPtr = this.lib.bufferGetBgTagPtr(this.bufferPtr)
+    const attributesPtr = this.lib.bufferGetAttributesPtr(this.bufferPtr)
+
+    this._rawBuffers = {
+      char: new Uint32Array(toArrayBuffer(charPtr, 0, size * 4)),
+      fg: new Float32Array(toArrayBuffer(fgPtr, 0, size * 4 * 4)),
+      bg: new Float32Array(toArrayBuffer(bgPtr, 0, size * 4 * 4)),
+      attributes: new Uint32Array(toArrayBuffer(attributesPtr, 0, size * 4)),
+    }
+
+    this._rawColorTags = {
+      fg: new Uint16Array(toArrayBuffer(fgTagPtr, 0, size * 2)),
+      bg: new Uint16Array(toArrayBuffer(bgTagPtr, 0, size * 2)),
+    }
+  }
+
   get buffers(): {
     char: Uint32Array
     fg: Float32Array
     bg: Float32Array
     attributes: Uint32Array
   } {
     this.guard()
-    if (this._rawBuffers === null) {
-      const size = this._width * this._height
-      const charPtr = this.lib.bufferGetCharPtr(this.bufferPtr)
-      const fgPtr = this.lib.bufferGetFgPtr(this.bufferPtr)
-      const bgPtr = this.lib.bufferGetBgPtr(this.bufferPtr)
-      const attributesPtr = this.lib.bufferGetAttributesPtr(this.bufferPtr)
-
-      this._rawBuffers = {
-        char: new Uint32Array(toArrayBuffer(charPtr, 0, size * 4)),
-        fg: new Float32Array(toArrayBuffer(fgPtr, 0, size * 4 * 4)),
-        bg: new Float32Array(toArrayBuffer(bgPtr, 0, size * 4 * 4)),
-        attributes: new Uint32Array(toArrayBuffer(attributesPtr, 0, size * 4)),
-      }
-    }
+    this.ensureRawBufferViews()
+    return this._rawBuffers!
+  }
 
-    return this._rawBuffers
+  private get rawColorTags(): { fg: Uint16Array; bg: Uint16Array } {
+    this.guard()
+    this.ensureRawBufferViews()
+    return this._rawColorTags!
   }
 
   constructor(
@@ -155,6 +177,7 @@ export class OptimizedBuffer {
   public getSpanLines(): CapturedLine[] {
     this.guard()
     const { char, fg, bg, attributes } = this.buffers
+    const { fg: fgTag, bg: bgTag } = this.rawColorTags
     const lines: CapturedLine[] = []
 
     const CHAR_FLAG_CONTINUATION = 0xc0000000 | 0
@@ -173,8 +196,8 @@ export class OptimizedBuffer {
       for (let x = 0; x < this._width; x++) {
         const i = y * this._width + x
         const cp = char[i]
-        const cellFg = RGBA.fromValues(fg[i * 4], fg[i * 4 + 1], fg[i * 4 + 2], fg[i * 4 + 3])
-        const cellBg = RGBA.fromValues(bg[i * 4], bg[i * 4 + 1], bg[i * 4 + 2], bg[i * 4 + 3])
+        const cellFg = RGBA.fromValues(fg[i * 4], fg[i * 4 + 1], fg[i * 4 + 2], fg[i * 4 + 3], fgTag[i])
+        const cellBg = RGBA.fromValues(bg[i * 4], bg[i * 4 + 1], bg[i * 4 + 2], bg[i * 4 + 3], bgTag[i])
         const cellAttrs = attributes[i] & 0xff
 
         // Continuation cells are placeholders for wide characters (emojis, CJK)
@@ -422,6 +445,7 @@ export class OptimizedBuffer {
     this._width = width
     this._height = height
     this._rawBuffers = null
+    this._rawColorTags = null
 
     this.lib.bufferResize(this.bufferPtr, width, height)
   }

packages/core/src/lib/RGBA.test.ts

@@ -1,36 +1,62 @@
 import { test, expect, describe } from "bun:test"
-import { RGBA, hexToRgb, rgbToHex, hsvToRgb, parseColor } from "./RGBA.js"
+import {
+  COLOR_TAG_DEFAULT,
+  COLOR_TAG_RGB,
+  RGBA,
+  decodeColorTag,
+  hexToRgb,
+  hsvToRgb,
+  normalizeColorValue,
+  parseColor,
+  rgbToHex,
+} from "./RGBA.js"
 
 describe("RGBA class", () => {
   describe("constructor", () => {
-    test("creates RGBA with Float32Array buffer", () => {
-      const buffer = new Float32Array([0.5, 0.6, 0.7, 0.8])
+    test("uses the provided 5-float buffer", () => {
+      const buffer = new Float32Array([0.5, 0.6, 0.7, 0.8, COLOR_TAG_RGB])
       const rgba = new RGBA(buffer)
       expect(rgba.buffer).toBe(buffer)
+      expect(rgba.tag).toBe(COLOR_TAG_RGB)
     })
 
-    test("buffer is mutable reference", () => {
+    test("upgrades legacy 4-float buffers to explicit RGB tag", () => {
       const buffer = new Float32Array([0.5, 0.6, 0.7, 0.8])
       const rgba = new RGBA(buffer)
+
+      expect(rgba.buffer).not.toBe(buffer)
+      expect(rgba.buffer).toHaveLength(5)
+      expect(rgba.r).toBeCloseTo(0.5, 5)
+      expect(rgba.g).toBeCloseTo(0.6, 5)
+      expect(rgba.b).toBeCloseTo(0.7, 5)
+      expect(rgba.a).toBeCloseTo(0.8, 5)
+      expect(rgba.tag).toBe(COLOR_TAG_RGB)
+    })
+
+    test("buffer is mutable reference when already 5-float", () => {
+      const buffer = new Float32Array([0.5, 0.6, 0.7, 0.8, COLOR_TAG_RGB])
+      const rgba = new RGBA(buffer)
       buffer[0] = 0.9
       expect(rgba.r).toBeCloseTo(0.9, 5)
     })
   })
 
   describe("fromArray", () => {
-    test("creates RGBA from Float32Array", () => {
+    test("creates RGBA from legacy 4-float arrays", () => {
       const array = new Float32Array([0.1, 0.2, 0.3, 0.4])
       const rgba = RGBA.fromArray(array)
       expect(rgba.r).toBeCloseTo(0.1, 5)
       expect(rgba.g).toBeCloseTo(0.2, 5)
       expect(rgba.b).toBeCloseTo(0.3, 5)
       expect(rgba.a).toBeCloseTo(0.4, 5)
+      expect(rgba.tag).toBe(COLOR_TAG_RGB)
     })
 
-    test("uses same buffer reference", () => {
-      const array = new Float32Array([0.1, 0.2, 0.3, 0.4])
+    test("uses same buffer reference when already 5-float", () => {
+      const array = new Float32Array([0.1, 0.2, 0.3, 0.4, COLOR_TAG_DEFAULT])
       const rgba = RGBA.fromArray(array)
       expect(rgba.buffer).toBe(array)
+      expect(rgba.tag).toBe(COLOR_TAG_DEFAULT)
     })
   })
 
@@ -120,6 +146,69 @@ describe("RGBA class", () => {
     })
   })
 
+  describe("clone", () => {
+    test("creates a detached copy", () => {
+      const original = RGBA.fromValues(0.1, 0.2, 0.3, 0.4)
+      const cloned = RGBA.clone(original)
+      expect(cloned).not.toBe(original)
+      expect(cloned.buffer).not.toBe(original.buffer)
+      expect(cloned.toInts()).toEqual(original.toInts())
+      cloned.r = 0.9
+      expect(original.r).toBeCloseTo(0.1, 5)
+    })
+  })
+
+  describe("intent helpers", () => {
+    test("fromIndex uses ANSI256 fallback snapshots", () => {
+      expect(RGBA.fromIndex(9).toInts()).toEqual([255, 0, 0, 255])
+      expect(RGBA.fromIndex(21).toInts()).toEqual([0, 0, 255, 255])
+      expect(RGBA.fromIndex(232).toInts()).toEqual([8, 8, 8, 255])
+      expect(RGBA.fromIndex(255).toInts()).toEqual([238, 238, 238, 255])
+    })
+
+    test("stores explicit tags in the fifth float", () => {
+      const rgb = RGBA.fromHex("#112233")
+      const indexed = RGBA.fromIndex(6)
+      const defaultFg = RGBA.defaultForeground()
+
+      expect(rgb.buffer).toHaveLength(5)
+      expect(rgb.buffer[4]).toBe(COLOR_TAG_RGB)
+      expect(indexed.buffer[4]).toBe(6)
+      expect(defaultFg.buffer[4]).toBe(COLOR_TAG_DEFAULT)
+    })
+
+    test("does not mutate caller-owned snapshots when constructing tagged colors", () => {
+      const indexedSnapshot = RGBA.fromHex("#112233")
+      const defaultSnapshot = RGBA.fromHex("#abcdef")
+
+      const indexed = RGBA.fromIndex(6, indexedSnapshot)
+      const defaultFg = RGBA.defaultForeground(defaultSnapshot)
+
+      expect(indexed).not.toBe(indexedSnapshot)
+      expect(defaultFg).not.toBe(defaultSnapshot)
+      expect(RGBA.getIntentTag(indexedSnapshot)).toBe(COLOR_TAG_RGB)
+      expect(RGBA.getIntentTag(defaultSnapshot)).toBe(COLOR_TAG_RGB)
+      expect(RGBA.getIntentTag(indexed)).toBe(6)
+      expect(RGBA.getIntentTag(defaultFg)).toBe(COLOR_TAG_DEFAULT)
+      expect(indexed.toInts()).toEqual(indexedSnapshot.toInts())
+      expect(defaultFg.toInts()).toEqual(defaultSnapshot.toInts())
+    })
+
+    test("normalizeColorValue and decodeColorTag preserve color intent", () => {
+      expect(normalizeColorValue(null)).toBeNull()
+      expect(
+        [RGBA.fromHex("#123456"), RGBA.fromIndex(12), RGBA.defaultBackground()].map((color) => [
+          normalizeColorValue(color)?.tag,
+          decodeColorTag(color.tag),
+        ]),
+      ).toEqual([
+        [COLOR_TAG_RGB, { kind: "rgb" }],
+        [12, { kind: "indexed", index: 12 }],
+        [COLOR_TAG_DEFAULT, { kind: "default" }],
+      ])
+    })
+  })
+
   describe("fromHex", () => {
     test("creates RGBA from hex string", () => {
       const rgba = RGBA.fromHex("#FF8040")
@@ -274,6 +363,14 @@ describe("RGBA class", () => {
     })
   })
 
+  describe("equals", () => {
+    test("compares both rgba values and tags", () => {
+      const rgb = RGBA.fromHex("#112233")
+      expect(rgb.equals(RGBA.fromIndex(6, rgb))).toBe(false)
+      expect(RGBA.defaultForeground("#aabbcc").equals(RGBA.defaultForeground("#aabbcc"))).toBe(true)
+    })
+  })
+
   describe("toString", () => {
     test("formats as rgba string with 2 decimal places", () => {
       const rgba = RGBA.fromValues(0.5, 0.6, 0.7, 0.8)